Added Arima ect

models/timeseries_forecasting.py

@@ -0,0 +1,626 @@
+from __future__ import annotations  
+
+
+import sys, subprocess
+def _ensure(pkg):
+    try:
+        __import__(pkg.split("==")[0].split(">=")[0])
+    except Exception:
+        subprocess.check_call([sys.executable, "-m", "pip", "install", pkg])
+for _pkg in [
+    "pandas", "numpy", "matplotlib", "scikit-learn",
+    "statsmodels", "pmdarima", "prophet"
+]:
+    _ensure(_pkg)
+
+import warnings
+warnings.filterwarnings("ignore")
+
+from typing import List, Optional, Tuple
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+# Soft deps
+try:
+    import pmdarima as pm
+    _PMDARIMA_OK = True
+except Exception:
+    _PMDARIMA_OK = False
+
+try:
+    from prophet import Prophet
+    _PROPHET_OK = True
+except Exception:
+    _PROPHET_OK = False
+
+from statsmodels.tsa.exponential_smoothing.ets import ETSModel
+from statsmodels.tsa.statespace.sarimax import SARIMAX
+from sklearn.metrics import mean_absolute_error, mean_squared_error, mean_absolute_percentage_error
+
+# ----------------------------
+# Helpers
+# ----------------------------
+def _parse_date(val: Optional[str]) -> Optional[pd.Timestamp]:
+    if val is None:
+        return None
+    if isinstance(val, str) and val.strip() == "":
+        return None
+    try:
+        return pd.to_datetime(val)
+    except Exception:
+        return None
+
+def _rmse(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    return float(np.sqrt(mean_squared_error(y_true, y_pred)))
+
+def _metrics_text(y_true: Optional[pd.Series], y_pred: Optional[pd.Series]) -> str:
+    if y_true is None or y_pred is None:
+        return ""
+    yt = pd.Series(y_true).dropna()
+    yp = pd.Series(y_pred).reindex(yt.index).dropna()
+    idx = yt.index.intersection(yp.index)
+    if len(idx) == 0:
+        return ""
+    mae = mean_absolute_error(yt.loc[idx], yp.loc[idx])
+    rmse_v = _rmse(yt.loc[idx], yp.loc[idx])
+    try:
+        mape_v = mean_absolute_percentage_error(yt.loc[idx], yp.loc[idx])
+    except Exception:
+        mape_v = np.nan
+    return f"MAE: {mae:.4f}\nRMSE: {rmse_v:.4f}\nMAPE: {mape_v:.4f}"
+
+def _render_diagnostics(series: pd.Series, resid: pd.Series) -> plt.Figure:
+    from statsmodels.graphics.tsaplots import plot_acf, plot_pacf
+    from statsmodels.stats.diagnostic import acorr_ljungbox
+
+    fig = plt.figure(figsize=(10, 8))
+    ax1 = fig.add_subplot(2, 2, 1)
+    ax1.plot(resid)
+    ax1.set_title("Residuals")
+    # MODIFIED: tilt x-axis labels on residuals plot
+    for lbl in ax1.get_xticklabels():
+        lbl.set_rotation(45)
+        lbl.set_ha("right")
+
+    ax2 = fig.add_subplot(2, 2, 2)
+    plot_acf(resid.dropna(), ax=ax2)
+
+    ax3 = fig.add_subplot(2, 2, 3)
+    plot_pacf(resid.dropna(), ax=ax3)
+
+    ax4 = fig.add_subplot(2, 2, 4)
+    lags = min(10, max(1, len(resid) // 10))
+    try:
+        lb = acorr_ljungbox(resid.dropna(), lags=[lags], return_df=True)
+        pval = float(lb["lb_pvalue"].iloc[-1])
+    except Exception:
+        pval = np.nan
+    ax4.axis("off")
+    ax4.text(0, 0.8, f"Ljung-Box p-value (~lag {lags}): {pval:.4f}")
+    fig.tight_layout()
+    return fig
+
+def perform_stationarity_tests(df_indexed: pd.DataFrame, target_col: str) -> str:
+    from statsmodels.tsa.stattools import adfuller, kpss  # local import
+    y = df_indexed[target_col].astype(float).dropna()
+    lines = [f"Observations: {len(y)}"]
+    try:
+        adf_stat, adf_p, _, _, crit, _ = adfuller(y, autolag="AIC")
+        lines.append("ADF Test")
+        lines.append(f"  Statistic: {adf_stat:.4f}, p-value: {adf_p:.4f}")
+        for k, v in crit.items():
+            lines.append(f"  Critical {k}: {v:.4f}")
+    except Exception as e:
+        lines.append(f"ADF error: {e}")
+    try:
+        kpss_stat, kpss_p, _, crit = kpss(y, regression="c", nlags="auto")
+        lines.append("KPSS Test")
+        lines.append(f"  Statistic: {kpss_stat:.4f}, p-value: {kpss_p:.4f}")
+        for k, v in crit.items():
+            lines.append(f"  Critical {k}: {v}")
+    except Exception as e:
+        lines.append(f"KPSS error: {e}")
+    return "\n".join(lines)
+
+
+def detect_outliers(df_indexed: pd.DataFrame, target_col: str, z_thresh: float = 3.0) -> str:
+    y = df_indexed[target_col].astype(float)
+    std = y.std(ddof=1)
+    std = float(std) if pd.notna(std) and std != 0 else 1.0
+    z = (y - y.mean()) / std
+    idx = y.index[(np.abs(z) > z_thresh)]
+    return f"Potential outliers beyond |z|>{z_thresh}: {len(idx)}"
+
+# ----------------------------
+# WINDOWING
+# ----------------------------
+def _build_train_and_forecast_index(
+    df_indexed: pd.DataFrame,
+    target_col: str,
+    train_start: Optional[str],
+    train_end: Optional[str],
+    horizon: int,
+    freq: str,
+) -> Tuple[pd.DataFrame, pd.DatetimeIndex, str, str, Optional[pd.Series]]:
+    hist = df_indexed[df_indexed[target_col].notna()].copy()
+    if hist.empty:
+        raise ValueError("Training window has 0 rows; check train_start/train_end.")
+
+    t_start = _parse_date(train_start) or hist.index.min()
+    t_end = _parse_date(train_end) or hist.index.max()
+
+    train_df = hist.loc[(hist.index >= t_start) & (hist.index <= t_end)].copy()
+    if train_df.empty:
+        raise ValueError("Training window has 0 rows; check train_start/train_end.")
+
+    if freq == "infer":
+        inferred = pd.infer_freq(train_df.index)
+        if inferred is None:
+            raise ValueError("Could not infer frequency from training index; please select a frequency in the UI.")
+        use_freq = inferred
+    else:
+        use_freq = freq
+
+    last_train = train_df.index.max()
+    fc_index = pd.date_range(start=last_train, periods=horizon + 1, freq=use_freq)[1:]
+
+    y_true = None
+    if set(fc_index).issubset(set(df_indexed.index)):
+        yt = df_indexed.loc[fc_index, target_col]
+        if yt.notna().any():
+            y_true = yt
+
+    train_range = f"Train range: {train_df.index.min()} → {train_df.index.max()}"
+    forecast_range = f"Forecast range: {fc_index.min()} → {fc_index.max()}"
+
+    assert train_df.index.max() < fc_index.min()
+    assert (train_df.index <= train_df.index.max()).all()
+
+    return train_df, fc_index, train_range, forecast_range, y_true
+
+# ----------------------------
+# Exogenous handling
+# ----------------------------
+def _forecast_exog(
+    train_df: pd.DataFrame,
+    forecast_index: pd.DatetimeIndex,
+    exog_cols: List[str],
+    method: str = "naive",
+    exog_m: int = 0,
+) -> pd.DataFrame:
+    if not exog_cols:
+        return pd.DataFrame(index=forecast_index)
+    fc_dict = {}
+    H = len(forecast_index)
+    for c in exog_cols:
+        y = train_df[c].astype(float)
+        if y.isna().any():
+            raise ValueError(f"Exogenous column '{c}' has NaNs in the training window.")
+        if method == "naive":
+            fc = np.repeat(y.iloc[-1], H)
+        elif method == "seasonal_naive":
+            if exog_m is None or int(exog_m) < 1:
+                raise ValueError("seasonal_naive requires exog_m >= 1.")
+            if len(y) < int(exog_m):
+                raise ValueError(f"Training window too short for exog_m={exog_m} on exogenous '{c}'.")
+            last_block = y.iloc[-int(exog_m):].values
+            reps = int(np.ceil(H / int(exog_m)))
+            fc = np.tile(last_block, reps)[:H]
+        elif method == "auto_arima":
+            if not _PMDARIMA_OK:
+                raise ValueError("pmdarima not installed; cannot auto_arima exogenous.")
+            seasonal_flag = int(exog_m) > 1
+            m_used = int(exog_m) if seasonal_flag else 1
+            model = pm.auto_arima(
+                y,
+                seasonal=seasonal_flag,
+                m=m_used,
+                error_action="ignore",
+                suppress_warnings=True,
+                stepwise=True,
+            )
+            fc = model.predict(n_periods=H)
+        else:
+            raise ValueError(f"Unknown exogenous forecast method: {method}")
+        fc_dict[c] = fc
+    return pd.DataFrame(fc_dict, index=forecast_index)
+
+def _prepare_exog_with_policy(
+    train_df: pd.DataFrame,
+    forecast_index: pd.DatetimeIndex,
+    exog_cols: Optional[List[str]],
+    df_indexed: pd.DataFrame,
+    future_exog_df: Optional[pd.DataFrame],
+    exog_policy: str = "auto_forecast",
+    exog_method: str = "naive",
+    exog_m: int = 0,
+) -> Tuple[Optional[pd.DataFrame], Optional[pd.DataFrame], str]:
+    if not exog_cols:
+        return None, None, ""
+
+    X_train = train_df[exog_cols].copy()
+    for c in exog_cols:
+        if not pd.api.types.is_numeric_dtype(X_train[c]):
+            raise ValueError(f"Exogenous column '{c}' must be numeric.")
+
+    if set(forecast_index).issubset(set(df_indexed.index)):
+        cand = df_indexed.loc[forecast_index, exog_cols]
+        if cand.notna().all().all():
+            return X_train, cand.copy(), "Exogenous: using future values from main file."
+
+    if future_exog_df is not None:
+        try:
+            cand = future_exog_df.reindex(forecast_index)[exog_cols]
+            if cand.notna().all().all():
+                return X_train, cand.copy(), "Exogenous: using provided future exog file."
+        except Exception:
+            pass
+
+    if exog_policy == "require_future":
+        need = ", ".join(exog_cols)
+        missing = ", ".join(str(ts) for ts in forecast_index[:6])
+        raise ValueError(f"Future exogenous values required for: {need}; missing at (first few): {missing}")
+    elif exog_policy == "drop_if_missing":
+        return None, None, "Exogenous: dropped (future values missing)."
+    elif exog_policy == "auto_forecast":
+        X_future = _forecast_exog(
+            train_df, forecast_index, exog_cols,
+            method=exog_method,
+            exog_m=int(exog_m or 0),
+        )
+        return X_train, X_future, f"Exogenous: auto-forecasted ({exog_method})."
+    else:
+        raise ValueError(f"Unknown exog_policy: {exog_policy}")
+
+# ----------------------------
+# Forecast runners
+# ----------------------------
+def run_auto_arima_forecast(
+    df_indexed: pd.DataFrame,
+    target_col: str,
+    horizon: int,
+    seasonal: bool,
+    m: int,
+    freq: str = "infer",
+    exog_cols: Optional[List[str]] = None,
+    future_exog_df: Optional[pd.DataFrame] = None,
+    train_start: Optional[str] = None,
+    train_end: Optional[str] = None,
+    return_diagnostics: bool = False,
+    exog_policy: str = "auto_forecast",
+    exog_method: str = "naive",
+    exog_m: int = 0,  # MODIFIED
+):
+    if not _PMDARIMA_OK:
+        return None, "Error: pmdarima is not installed; Auto-ARIMA unavailable.", None, None, None
+
+    train_df, fc_index, tr_range, fc_range, y_true = _build_train_and_forecast_index(
+        df_indexed, target_col, train_start, train_end, int(horizon), freq
+    )
+    y = train_df[target_col].astype(float)
+
+    X_train = X_future = None
+    exog_note = ""
+    if exog_cols:
+        try:
+            X_train, X_future, exog_note = _prepare_exog_with_policy(
+                train_df, fc_index, exog_cols, df_indexed, future_exog_df,
+                exog_policy, exog_method, exog_m
+            )
+        except Exception as e:
+            return None, f"Auto-ARIMA error: {e}", None, None, None
+
+    try:
+        model = pm.auto_arima(
+            y,
+            seasonal=bool(seasonal),
+            m=int(m) if seasonal else 1,
+            exogenous=X_train,
+            error_action="ignore",
+            suppress_warnings=True,
+            stepwise=True,
+        )
+        fcst, conf = model.predict(n_periods=int(horizon), exogenous=X_future, return_conf_int=True)
+        yhat = pd.Series(fcst, index=fc_index)
+        conf_df = pd.DataFrame(conf, index=fc_index, columns=["lower", "upper"])
+    except Exception as e:
+        return None, f"Auto-ARIMA error: {e}", None, None, None
+
+    fig = plt.figure(figsize=(10, 5))
+    plt.plot(y.index, y.values, label="history")
+    plt.plot(yhat.index, yhat.values, label="forecast")
+    plt.fill_between(yhat.index, conf_df["lower"], conf_df["upper"], alpha=0.2)
+    plt.legend()
+    plt.title("Auto-ARIMA Forecast")
+    plt.xticks(rotation=45, ha="right")  # MODIFIED: tilt x-axis labels on forecast plot
+    fig.tight_layout()  # MODIFIED: ensure labels fit
+
+    try:
+        fitted_in = pd.Series(model.predict_in_sample(exogenous=X_train), index=y.index)
+        resid = y - fitted_in
+    except Exception:
+        resid = pd.Series(index=y.index, dtype=float)
+
+    metrics_block = _metrics_text(y_true, yhat)
+    summary = "\n".join([s for s in [
+        f"Model: Auto-ARIMA ({'seasonal m='+str(m) if seasonal else 'non-seasonal'})",
+        exog_note,
+        tr_range, fc_range, metrics_block,
+        "Residual Diagnostics" if return_diagnostics else ""
+    ] if s]).strip()
+
+    if not return_diagnostics:
+        return fig, summary, None, yhat, conf_df
+    diag_fig = _render_diagnostics(y, resid)
+    return fig, summary, diag_fig, yhat, conf_df
+
+def run_sarimax_forecast(
+    df_indexed: pd.DataFrame,
+    target_col: str,
+    horizon: int,
+    seasonal: bool,
+    m: int,
+    freq: str = "infer",
+    exog_cols: Optional[List[str]] = None,
+    future_exog_df: Optional[pd.DataFrame] = None,
+    train_start: Optional[str] = None,
+    train_end: Optional[str] = None,
+    return_diagnostics: bool = False,
+    exog_policy: str = "auto_forecast",
+    exog_method: str = "naive",
+    exog_m: int = 0,  # MODIFIED
+):
+    if not _PMDARIMA_OK:
+        return None, "Error: pmdarima is required to select SARIMAX orders.", None, None, None
+
+    train_df, fc_index, tr_range, fc_range, y_true = _build_train_and_forecast_index(
+        df_indexed, target_col, train_start, train_end, int(horizon), freq
+    )
+    y = train_df[target_col].astype(float)
+
+    X_train = X_future = None
+    exog_note = ""
+    if exog_cols:
+        try:
+            X_train, X_future, exog_note = _prepare_exog_with_policy(
+                train_df, fc_index, exog_cols, df_indexed, future_exog_df,
+                exog_policy, exog_method, exog_m
+            )
+        except Exception as e:
+            return None, f"SARIMAX error: {e}", None, None, None
+
+    try:
+        selector = pm.auto_arima(
+            y, exogenous=X_train, seasonal=bool(seasonal), m=int(m) if seasonal else 1,
+            stepwise=True, error_action="ignore", suppress_warnings=True
+        )
+        order = selector.order
+        sorder = selector.seasonal_order if seasonal else (0, 0, 0, 0)
+
+        model = SARIMAX(
+            y, exog=X_train,
+            order=order,
+            seasonal_order=sorder if seasonal else (0, 0, 0, 0),
+            enforce_stationarity=False, enforce_invertibility=False
+        ).fit(disp=False)
+
+        pred = model.get_forecast(steps=int(horizon), exog=X_future)
+        yhat = pd.Series(pred.predicted_mean, index=fc_index)
+        conf_int = pred.conf_int(alpha=0.05)
+        conf_df = pd.DataFrame({"lower": conf_int.iloc[:, 0].values, "upper": conf_int.iloc[:, 1].values}, index=fc_index)
+    except Exception as e:
+        return None, f"SARIMAX error: {e}", None, None, None
+
+    fig = plt.figure(figsize=(10, 5))
+    plt.plot(y.index, y.values, label="history")
+    plt.plot(yhat.index, yhat.values, label="forecast")
+    plt.fill_between(yhat.index, conf_df["lower"], conf_df["upper"], alpha=0.2)
+    plt.legend()
+    plt.title(f"SARIMAX order={order} seasonal_order={sorder}")
+    plt.xticks(rotation=45, ha="right")  # MODIFIED: tilt x-axis labels on forecast plot
+    fig.tight_layout()  # MODIFIED
+
+    try:
+        resid = y - model.fittedvalues
+    except Exception:
+        resid = pd.Series(index=y.index, dtype=float)
+
+    metrics_block = _metrics_text(y_true, yhat)
+    summary = "\n".join([s for s in [
+        f"Model: SARIMAX order={order} seasonal_order={sorder}",
+        exog_note,
+        tr_range, fc_range, metrics_block,
+        "Residual Diagnostics" if return_diagnostics else ""
+    ] if s]).strip()
+
+    if not return_diagnostics:
+        return fig, summary, None, yhat, conf_df
+    diag_fig = _render_diagnostics(y, resid)
+    return fig, summary, diag_fig, yhat, conf_df
+
+def run_ets_forecast(
+    df_indexed: pd.DataFrame,
+    target_col: str,
+    horizon: int,
+    error: str,
+    trend: Optional[str],
+    seasonal: Optional[str],
+    m: int,
+    damped: bool,
+    freq: str = "infer",
+    train_start: Optional[str] = None,
+    train_end: Optional[str] = None,
+    return_diagnostics: bool = False,
+):
+    train_df, fc_index, tr_range, fc_range, y_true = _build_train_and_forecast_index(
+        df_indexed, target_col, train_start, train_end, int(horizon), freq
+    )
+    y = train_df[target_col].astype(float)
+
+    try:
+        model = ETSModel(
+            y,
+            error=error,
+            trend=trend if trend != "none" else None,
+            seasonal=seasonal if seasonal != "none" else None,
+            seasonal_periods=int(m) if seasonal != "none" else None,
+            damped_trend=bool(damped) if (trend and trend != "none") else False,
+            initialization_method="estimated",
+        ).fit()
+    except Exception as e:
+        return None, f"ETS error: {e}", None, None, None
+
+    try:
+        fc_vals = model.forecast(int(horizon))
+        yhat = pd.Series(fc_vals.values, index=fc_index)
+
+        resid = y - model.fittedvalues
+        se = float(np.nanstd(resid, ddof=1)) if len(resid.dropna()) else 0.0
+        z = 1.96
+        conf_df = pd.DataFrame({"lower": yhat - z * se, "upper": yhat + z * se}, index=fc_index)
+    except Exception as e:
+        return None, f"ETS forecast error: {e}", None, None, None
+
+    fig = plt.figure(figsize=(10, 5))
+    plt.plot(y.index, y.values, label="history")
+    plt.plot(yhat.index, yhat.values, label="forecast")
+    plt.fill_between(conf_df.index, conf_df["lower"], conf_df["upper"], alpha=0.2)
+    plt.legend()
+    plt.title("ETS Forecast")
+    plt.xticks(rotation=45, ha="right")  # MODIFIED: tilt x-axis labels on forecast plot
+    fig.tight_layout()  # MODIFIED
+
+    try:
+        resid = y - model.fittedvalues
+    except Exception:
+        resid = pd.Series(index=y.index, dtype=float)
+
+    metrics_block = _metrics_text(y_true, yhat)
+    summary = "\n".join([s for s in [
+        f"Model: ETS(error={error}, trend={trend}, seasonal={seasonal}, m={m}, damped={damped})",
+        tr_range, fc_range, metrics_block,
+        "Residual Diagnostics" if return_diagnostics else ""
+    ] if s]).strip()
+
+    if not return_diagnostics:
+        return fig, summary, None, yhat, conf_df
+    diag_fig = _render_diagnostics(y, resid)
+    return fig, summary, diag_fig, yhat, conf_df
+
+def run_prophet_forecast(
+    df_indexed: pd.DataFrame,
+    target_col: str,
+    horizon: int,
+    seasonality_mode: str,
+    yearly: bool,
+    weekly: bool,
+    daily: bool,
+    freq: str = "infer",
+    exog_cols: Optional[List[str]] = None,
+    future_exog_df: Optional[pd.DataFrame] = None,
+    train_start: Optional[str] = None,
+    train_end: Optional[str] = None,
+    return_diagnostics: bool = False,
+    exog_policy: str = "auto_forecast",
+    exog_method: str = "naive",
+    exog_m: int = 0,  # MODIFIED
+):
+    if not _PROPHET_OK:
+        return None, "Error: prophet is not installed.", None, None, None
+
+    idx_name = df_indexed.index.name or "ds"
+    train_df, fc_index, tr_range, fc_range, y_true = _build_train_and_forecast_index(
+        df_indexed, target_col, train_start, train_end, int(horizon), freq
+    )
+
+    X_train = X_future = None
+    exog_note = ""
+    exog_effective: List[str] = []
+    if exog_cols:
+        try:
+            X_train, X_future, exog_note = _prepare_exog_with_policy(
+                train_df, fc_index, exog_cols, df_indexed, future_exog_df,
+                exog_policy, exog_method, exog_m
+            )
+            if X_train is not None:
+                exog_effective = list(exog_cols)
+        except Exception as e:
+            return None, f"Prophet error: {e}", None, None, None
+
+    train = train_df.reset_index().rename(columns={idx_name: "ds"})
+    train = train[["ds", target_col]].rename(columns={target_col: "y"})
+    train["y"] = train["y"].astype(float)
+    if exog_effective:
+        train = pd.concat([train, X_train.reset_index(drop=True)], axis=1)
+
+    mobj = Prophet(seasonality_mode=seasonality_mode)
+    if yearly:
+        mobj.add_seasonality(name="yearly", period=365.25, fourier_order=10)
+    if weekly:
+        mobj.add_seasonality(name="weekly", period=7, fourier_order=6)
+    if daily:
+        mobj.add_seasonality(name="daily", period=1, fourier_order=4)
+    for c in exog_effective:
+        mobj.add_regressor(c)
+
+    try:
+        mobj.fit(train)
+        future = pd.DataFrame({"ds": fc_index})
+        if exog_effective:
+            for c in exog_effective:
+                if c not in X_future.columns:
+                    raise ValueError(f"Prophet future DataFrame missing required regressor column: {c}")
+            future = pd.concat([future, X_future.reset_index(drop=True)], axis=1)
+        fcst = mobj.predict(future)
+    except Exception as e:
+        return None, f"Prophet error: {e}", None, None, None
+
+    fig = plt.figure(figsize=(10, 5))
+    plt.plot(train["ds"], train["y"], label="history")
+    plt.plot(fcst["ds"], fcst["yhat"], label="forecast")
+    if "yhat_lower" in fcst and "yhat_upper" in fcst:
+        plt.fill_between(fcst["ds"], fcst["yhat_lower"], fcst["yhat_upper"], alpha=0.2)
+    plt.legend()
+    plt.title("Prophet Forecast")
+    plt.xticks(rotation=45, ha="right")  # MODIFIED: tilt x-axis labels on forecast plot
+    fig.tight_layout()  # MODIFIED
+
+    try:
+        in_fit = mobj.predict(train.drop(columns=["y"]))
+        resid = train["y"].values - in_fit["yhat"].values
+        resid = pd.Series(resid, index=train["ds"])
+    except Exception:
+        resid = pd.Series(dtype=float)
+
+    yhat_series = pd.Series(fcst["yhat"].values, index=pd.DatetimeIndex(fcst["ds"]))
+    metrics_block = _metrics_text(y_true, yhat_series)
+    conf_df = pd.DataFrame(
+        {"lower": fcst.get("yhat_lower", pd.Series(index=fcst.index, dtype=float)),
+         "upper": fcst.get("yhat_upper", pd.Series(index=fcst.index, dtype=float))},
+        index=pd.DatetimeIndex(fcst["ds"])
+    )
+
+    summary = "\n".join([
+        f"Model: Prophet(seasonality_mode={seasonality_mode}, yearly={yearly}, weekly={weekly}, daily={daily})",
+        exog_note,
+        tr_range, fc_range, metrics_block,
+        "Residual Diagnostics" if return_diagnostics else ""
+    ]).strip()
+
+    if not return_diagnostics:
+        return fig, summary, None, yhat_series, conf_df
+    diag_fig = _render_diagnostics(train.set_index("ds")["y"], resid)
+    return fig, summary, diag_fig, yhat_series, conf_df
+
+# ----------------------------
+# exports list
+# ----------------------------
+__all__ = [
+    "run_auto_arima_forecast",
+    "run_ets_forecast",
+    "run_prophet_forecast",
+    "run_sarimax_forecast",
+    "perform_stationarity_tests",
+    "detect_outliers",
+]