Add docstrings for plot_ar.py and plot_forecast_ar.py and improve naming of the plots.

Author: Lenr4

src/lennart_epp/analysis/task_forecast_ar.py

@@ -14,7 +14,7 @@
 def task_forecast_ar(
     data=BLD / "data" / "cleaned_apple_data.pkl",
     produces=BLD / "forecasts" / "multistep_forecast.pkl",
-    lags=50,
+    lags=30,
 ):
     """Generate multi-step forecasts using an AR model.
 

src/lennart_epp/final/plot_ar.py

@@ -7,12 +7,21 @@
 
 from lennart_epp.analysis.evaluate_ar_model import _predict_ar
 
-msg = "Fehler beim Erstellen des PDF-Plots"
+msg = "Pdf could not be created."
 
 
 def _predict_ar_from_coefficients(
     df: pd.DataFrame, integrated_coefficients: pd.DataFrame
 ) -> pd.Series:
+    """Generate in-sample predictions using AR model coefficients.
+
+    Args:
+        df (pd.DataFrame): The DataFrame containing the time series data.
+        integrated_coefficients (pd.DataFrame): DataFrame of integrated AR coefficients.
+
+    Returns:
+        pd.Series: A series of in-sample predictions, aligned with the original index.
+    """
     model_results = {"integrated_coefficients": integrated_coefficients}
 
     predictions = _predict_ar(df, model_results)
@@ -32,6 +41,18 @@ def plot_top_ar_models(
     *,
     export_as_pdf: bool = False,
 ):
+    """Plot and save the top AR models' approximations of the Apple stock price.
+
+    Args:
+        top_models (pd.DataFrame): DataFrame containing the top AR(p) models,
+                                   including their integrated coefficients.
+        df (pd.DataFrame): The DataFrame containing the stock price time series.
+        plot_path (str): The path to save the generated HTML plot.
+        export_as_pdf (bool, optional): If True, also exports the plots as a PDF.
+
+    Returns:
+        str: The path where the plot is saved.
+    """
     fig = go.Figure()
     fig.add_trace(
         go.Scatter(
@@ -87,8 +108,6 @@ def plot_top_ar_models(
         height=300,
     )
     combined_html = (
-        "<h1>Top 3 AR(p) Models vs. Original Data (Zoom on Last 100 Days, "
-        "Y-axis 140-200)</h1>\n"
         f"{fig.to_html(full_html=False, include_plotlyjs='cdn')}\n"
         "<h2>Residuals of AR(p) Models</h2>\n"
         f"{residual_fig.to_html(full_html=False, include_plotlyjs='cdn')}"

src/lennart_epp/final/plot_forecast_ar.py

@@ -5,7 +5,7 @@
 missing_close_msg = "Close price column is missing in the original data."
 empty_forecast_msg = "Forecast data is empty."
 invalid_index_msg = "Forecast data does not have a DatetimeIndex."
-msg_pdf = "Fehler beim Erstellen des PDF-Plots"
+msg_pdf = "Pdf_plot could not be created."
 
 
 def plot_forecast_ar(
@@ -15,6 +15,23 @@ def plot_forecast_ar(
     *,
     export_as_pdf: bool = True,
 ):
+    """Plot and save the original Apple stock price alongside the AR model forecast.
+
+    Args:
+        data_path (str): Path to the cleaned stock price data.
+        forecast_path (str): Path to the AR model forecast data.
+        output_path (str): Path to save the generated plot.
+        export_as_pdf (bool, optional): If True, also exports the plot as a PDF.
+
+    Returns:
+        str: The path where the plot is saved.
+
+    Raises:
+        KeyError: If the 'close_price' column is missing in the input data.
+        ValueError: If the forecast data is empty.
+        TypeError: If the forecast index is not a DatetimeIndex.
+        RuntimeError: If exporting to PDF fails.
+    """
     df = pd.read_pickle(data_path)
     forecast = pd.read_pickle(forecast_path)
 
@@ -53,10 +70,10 @@ def plot_forecast_ar(
     )
 
     fig.update_layout(
-        title="Apple Aktienkurs: Original vs. AR-Forecast (2023)",
+        title="Apple Stock Price: Original vs. AR-Multi-Step-Forecast",
         xaxis_title="Datum",
         yaxis_title="Kurs (USD)",
-        legend_title="Legende",
+        legend_title="Legend",
         template="plotly_white",
         autosize=True,
         yaxis={"range": [143, 180]},

src/lennart_epp/final/plot_memory.py

@@ -24,7 +24,10 @@ def plot_acf(acf_data: dict, save_path_html: str, save_path_pdf: str, n_obs: int
 
     fig.add_trace(
         go.Bar(
-            x=lags, y=acf_values, marker={"color": "rgba(0, 0, 255, 0.8)"}, name="ACF"
+            x=lags,
+            y=acf_values,
+            marker={"color": "rgba(0, 0, 255, 0.8)"},
+            name="ACF Value",
         )
     )
 
@@ -49,7 +52,7 @@ def plot_acf(acf_data: dict, save_path_html: str, save_path_pdf: str, n_obs: int
     )
 
     fig.update_layout(
-        title="Autocorrelation Function (ACF) with Confidence Bands",
+        title="ACF of differenced Close Price with Confidence Bands",
         xaxis_title="Lag",
         yaxis_title="ACF Value",
         template="plotly_white",