arimasel 0.1.0__py3-none-any.whl

arimasel/__init__.py

@@ -0,0 +1,37 @@
+"""
+arimasel: Cartesian Product-Based (Seasonal) ARIMA Model Identification and Selection
+======================================================================================
+
+A Python port of the R package of the same name. Provides an exhaustive,
+transparent alternative to stepwise automatic ARIMA search: given
+user-supplied index sets P, D, Q (optionally combined with seasonal sets at
+a given period), every candidate (p,d,q)(P,D,Q)[m] model is fit, ranked
+simultaneously by AIC, AICc, BIC, and HQIC, and summarised with Akaike
+weights. Also provides exogenous-regressor support, ensemble forecasting,
+rolling-origin cross-validation, feature-based exploratory data analysis,
+and a feature-guided automatic search (``smart_arima``).
+
+Author: Olushina Olawale Awe <olawaleawe@gmail.com>
+"""
+
+__version__ = "0.1.0"
+
+from .cart_arima import CartArimaResult, arima_table, cart_arima
+from .cv import ArimaCVResult, arima_cv
+from .datasets import load_exchange_ng, load_gdp_ng, load_inflation_ng
+from .diagnostics import DiagnoseResult, arima_diagnose, stationarity_test, suggest_d
+from .eda import EdaResult, seasonal_strength, smart_arima, suggest_D, ts_eda, ts_features
+from .forecast import ForecastResult, arima_forecast
+from .weights import arima_weights, cp_sets, hqic
+
+__all__ = [
+    "__version__",
+    "cart_arima", "CartArimaResult", "arima_table",
+    "arima_forecast", "ForecastResult",
+    "arima_diagnose", "DiagnoseResult",
+    "stationarity_test", "suggest_d",
+    "arima_cv", "ArimaCVResult",
+    "seasonal_strength", "suggest_D", "ts_features", "ts_eda", "EdaResult", "smart_arima",
+    "hqic", "cp_sets", "arima_weights",
+    "load_gdp_ng", "load_inflation_ng", "load_exchange_ng",
+]

arimasel/_utils.py

@@ -0,0 +1,99 @@
+"""Internal helper utilities for arimasel. Not part of the public API."""
+from __future__ import annotations
+
+import warnings
+from typing import Optional, Sequence
+
+import numpy as np
+import pandas as pd
+from statsmodels.tsa.arima.model import ARIMA
+
+
+def _as_series(x) -> pd.Series:
+    """Coerce input to a plain pandas Series with a simple RangeIndex,
+    preserving values only (any datetime index is intentionally dropped
+    to keep model-fitting behaviour independent of index type -- callers
+    that want a real datetime axis can re-attach one on the way out)."""
+    if isinstance(x, pd.Series):
+        return pd.Series(np.asarray(x.values, dtype=float))
+    if isinstance(x, pd.DataFrame):
+        if x.shape[1] != 1:
+            raise ValueError("DataFrame input must have exactly one column.")
+        return pd.Series(np.asarray(x.iloc[:, 0].values, dtype=float))
+    arr = np.asarray(x, dtype=float)
+    if arr.ndim != 1:
+        raise ValueError("Input series must be one-dimensional.")
+    return pd.Series(arr)
+
+
+def _model_string(p, d, q, P=None, D=None, Q=None, period=None) -> str:
+    base = f"ARIMA({p},{d},{q})"
+    if P is not None and D is not None and Q is not None and period is not None:
+        base = f"{base}({P},{D},{Q})[{period}]"
+    return base
+
+
+def _safe_fit(x: np.ndarray, order, seasonal_order=None, exog=None, **kwargs):
+    """Fit an ARIMA/SARIMAX model, swallowing convergence warnings and
+    returning None (rather than raising) on failure -- candidate models
+    in an exhaustive search are *expected* to fail sometimes."""
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            model_kwargs = dict(order=order)
+            if seasonal_order is not None:
+                model_kwargs["seasonal_order"] = seasonal_order
+            if exog is not None:
+                model_kwargs["exog"] = exog
+            model = ARIMA(x, **model_kwargs)
+            fit = model.fit(**kwargs)
+        if not np.isfinite(fit.llf):
+            return None
+        return fit
+    except Exception:
+        return None
+
+
+def _extract_metrics(fit) -> dict:
+    return {
+        "LogLik": fit.llf,
+        "AIC": fit.aic,
+        "AICc": fit.aicc,
+        "BIC": fit.bic,
+        "HQIC": fit.hqic,
+        "n_params": int(fit.params.shape[0]),
+    }
+
+
+def _vote_table(full_table: pd.DataFrame) -> pd.DataFrame:
+    criteria = ["AIC", "AICc", "BIC", "HQIC"]
+    winners = {c: full_table.loc[full_table[c].idxmin(), "Model"] for c in criteria}
+    counts: dict[str, list[str]] = {}
+    for c, m in winners.items():
+        counts.setdefault(m, []).append(c)
+    rows = [
+        {"Model": m, "Votes": len(crits), "Criteria": "/".join(crits)}
+        for m, crits in counts.items()
+    ]
+    out = pd.DataFrame(rows).sort_values("Votes", ascending=False).reset_index(drop=True)
+    return out
+
+
+def _validate_seasonal(seasonal: Optional[dict]) -> Optional[dict]:
+    if seasonal is None:
+        return None
+    if "period" not in seasonal or seasonal["period"] is None or seasonal["period"] < 2:
+        raise ValueError("seasonal['period'] must be supplied as an integer >= 2.")
+    P = sorted(set(seasonal.get("P", range(2))))
+    D = sorted(set(seasonal.get("D", range(2))))
+    Q = sorted(set(seasonal.get("Q", range(2))))
+    if any(v < 0 for v in P + D + Q):
+        raise ValueError("Seasonal index sets P, D, Q must be >= 0.")
+    return {"P": P, "D": D, "Q": Q, "period": int(seasonal["period"])}
+
+
+def _akaike_weights(values: Sequence[float]) -> np.ndarray:
+    values = np.asarray(values, dtype=float)
+    delta = values - np.nanmin(values)
+    raw = np.exp(-delta / 2.0)
+    return raw / np.nansum(raw)

arimasel/cart_arima.py

@@ -0,0 +1,290 @@
+"""Cartesian product (seasonal) ARIMA model identification and selection."""
+from __future__ import annotations
+
+import itertools
+import warnings
+from concurrent.futures import ProcessPoolExecutor
+from typing import Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+
+from ._utils import (
+    _akaike_weights,
+    _as_series,
+    _extract_metrics,
+    _model_string,
+    _safe_fit,
+    _validate_seasonal,
+    _vote_table,
+)
+
+_CRITERIA = ("AIC", "AICc", "BIC", "HQIC")
+
+
+class CartArimaResult:
+    """Result of :func:`cart_arima`.
+
+    Attributes
+    ----------
+    best_model : statsmodels ARIMAResults
+        The fitted model for the top-ranked candidate.
+    best_model_str : str
+        e.g. ``"ARIMA(1,1,1)"`` or ``"ARIMA(1,1,1)(1,0,0)[12]"``.
+    criterion : str
+        The primary ranking criterion used.
+    table : pandas.DataFrame
+        The top ``top_n`` candidate models.
+    full_table : pandas.DataFrame
+        Every converged candidate model, ranked.
+    vote_table : pandas.DataFrame
+        How many of the four criteria (AIC, AICc, BIC, HQIC) each model wins.
+    failed_models : list[str]
+        Candidate model strings that failed to converge.
+    n_total, n_converged : int
+    p_set, d_set, q_set : list[int]
+    seasonal : dict or None
+    exog : numpy.ndarray or None
+    data : pandas.Series
+        The original series used for fitting.
+    n_obs : int
+    """
+
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+        self.eda = None  # populated by smart_arima()
+
+    def __repr__(self):
+        return self.summary_str()
+
+    def summary_str(self) -> str:
+        lines = []
+        lines.append("Cartesian Product ARIMA Model Selection")
+        lines.append("=" * 41)
+        lines.append(f"Obs (n)   : {self.n_obs}")
+        if self.seasonal is not None:
+            s = self.seasonal
+            lines.append(
+                f"Seasonal  : period={s['period']}, "
+                f"P={s['P']}, D={s['D']}, Q={s['Q']}"
+            )
+        if self.exog is not None:
+            lines.append(f"exog      : {self.exog.shape[1]} external regressor column(s)")
+        lines.append(
+            f"Candidates: {self.n_total}  |  Converged: {self.n_converged}  "
+            f"|  Failed: {self.n_total - self.n_converged}"
+        )
+        lines.append(f"Criterion : {self.criterion}")
+        lines.append(f"Best model: {self.best_model_str}\n")
+        lines.append(f"Top {len(self.table)} models (ranked by {self.criterion}):")
+        cols = ["Rank", "Model", "AIC", "AICc", "BIC", "HQIC", "Delta", "Weight"]
+        lines.append(self.table[cols].to_string(index=False))
+        if self.failed_models:
+            lines.append(
+                f"\nFailed to converge ({len(self.failed_models)}): "
+                + ", ".join(self.failed_models)
+            )
+        return "\n".join(lines)
+
+    def summary(self) -> None:
+        print(self.summary_str())
+
+    @property
+    def fittedvalues(self) -> np.ndarray:
+        return np.asarray(self.best_model.fittedvalues)
+
+    @property
+    def resid(self) -> np.ndarray:
+        return np.asarray(self.best_model.resid)
+
+    def plot(self, kind: str = "criteria", criterion: Optional[str] = None,
+             top_n: int = 10, ax=None, **kwargs):
+        from .plotting import plot_cart_arima
+        return plot_cart_arima(self, kind=kind, criterion=criterion,
+                               top_n=top_n, ax=ax, **kwargs)
+
+
+def _fit_one(args):
+    (x_vals, p, d, q, P, D, Q, period, exog, fit_kwargs) = args
+    seasonal_order = (P, D, Q, period) if period is not None else None
+    model_str = _model_string(p, d, q, P, D, Q, period)
+    fit = _safe_fit(x_vals, order=(p, d, q), seasonal_order=seasonal_order,
+                    exog=exog, **fit_kwargs)
+    if fit is None:
+        return {"row": None, "fit": None, "model_str": model_str}
+    m = _extract_metrics(fit)
+    row = {
+        "Model": model_str, "p": p, "d": d, "q": q,
+        "P": P, "D": D, "Q": Q,
+        "LogLik": round(m["LogLik"], 3), "AIC": round(m["AIC"], 3),
+        "AICc": round(m["AICc"], 3), "BIC": round(m["BIC"], 3),
+        "HQIC": round(m["HQIC"], 3),
+    }
+    return {"row": row, "fit": fit, "model_str": model_str}
+
+
+def cart_arima(
+    x,
+    p_set: Sequence[int] = range(3),
+    d_set: Sequence[int] = range(2),
+    q_set: Sequence[int] = range(3),
+    seasonal: Optional[dict] = None,
+    exog: Optional[Union[np.ndarray, pd.DataFrame]] = None,
+    criterion: str = "AIC",
+    top_n: int = 10,
+    n_jobs: int = 1,
+    **fit_kwargs,
+) -> CartArimaResult:
+    """Exhaustive Cartesian-product (seasonal) ARIMA search.
+
+    Fits every candidate ``(p, d, q)`` -- optionally combined with a seasonal
+    ``(P, D, Q)[period]`` -- in the Cartesian product of the supplied index
+    sets, ranks all converged models simultaneously by AIC, AICc, BIC, and
+    HQIC, and returns the best model together with the full comparison
+    table and Akaike weights.
+
+    Parameters
+    ----------
+    x : array-like, pandas.Series, or pandas.DataFrame (one column)
+        The time series to model. Must have at least 10 observations.
+    p_set, d_set, q_set : sequence of int
+        Non-negative integer index sets for the non-seasonal AR, differencing,
+        and MA orders. Defaults: ``range(3)``, ``range(2)``, ``range(3)``.
+    seasonal : dict, optional
+        ``{"P": <seq>, "D": <seq>, "Q": <seq>, "period": <int>}``. ``P``,
+        ``D``, ``Q`` each default to ``range(2)`` if omitted; ``period`` is
+        required. When supplied, every combination of ``(p,d,q)`` and
+        ``(P,D,Q)`` at the given period is fitted.
+    exog : array-like, optional
+        External regressors (regression with ARIMA errors), same length as ``x``.
+    criterion : {"AIC", "AICc", "BIC", "HQIC"}
+        Primary ranking criterion.
+    top_n : int
+        Number of rows to keep in the abbreviated ``.table``; the full,
+        ranked table of all converged models is always in ``.full_table``.
+    n_jobs : int
+        Number of worker processes for fitting candidates in parallel.
+        ``1`` (default) fits serially in-process.
+    **fit_kwargs
+        Extra keyword arguments passed to ``ARIMAResults.fit()``, e.g.
+        ``method="statespace"``.
+
+    Returns
+    -------
+    CartArimaResult
+    """
+    if criterion not in _CRITERIA:
+        raise ValueError(f"criterion must be one of {_CRITERIA}")
+
+    x_series = _as_series(x)
+    x_vals = x_series.to_numpy(dtype=float)
+    n = len(x_vals)
+    if n < 10:
+        raise ValueError("Time series must have at least 10 observations.")
+    if n < 20:
+        warnings.warn("Time series has fewer than 20 observations; results may be unreliable.")
+    if np.isnan(x_vals).any():
+        warnings.warn("NaN values found in x. Replacing with the series mean.")
+        x_vals = np.where(np.isnan(x_vals), np.nanmean(x_vals), x_vals)
+
+    p_set = sorted(set(int(v) for v in p_set))
+    d_set = sorted(set(int(v) for v in d_set))
+    q_set = sorted(set(int(v) for v in q_set))
+    if any(v < 0 for v in p_set + d_set + q_set):
+        raise ValueError("p_set, d_set, q_set must contain only non-negative integers.")
+
+    seasonal = _validate_seasonal(seasonal)
+
+    exog_arr = None
+    if exog is not None:
+        exog_arr = np.asarray(exog, dtype=float)
+        if exog_arr.ndim == 1:
+            exog_arr = exog_arr.reshape(-1, 1)
+        if exog_arr.shape[0] != n:
+            raise ValueError("exog must have the same number of rows as len(x).")
+
+    if seasonal is None:
+        combos = [(p, d, q, None, None, None, None)
+                  for p, d, q in itertools.product(p_set, d_set, q_set)]
+    else:
+        combos = [
+            (p, d, q, P, D, Q, seasonal["period"])
+            for p, d, q, P, D, Q in itertools.product(
+                p_set, d_set, q_set, seasonal["P"], seasonal["D"], seasonal["Q"]
+            )
+        ]
+    n_total = len(combos)
+    if n_total == 0:
+        raise ValueError("No candidate models generated; check p_set/d_set/q_set.")
+
+    tasks = [(x_vals, p, d, q, P, D, Q, period, exog_arr, fit_kwargs)
+             for (p, d, q, P, D, Q, period) in combos]
+
+    if n_jobs and n_jobs > 1:
+        with ProcessPoolExecutor(max_workers=n_jobs) as ex:
+            results = list(ex.map(_fit_one, tasks))
+    else:
+        results = [_fit_one(t) for t in tasks]
+
+    rows, fits, failed = [], [], []
+    for r in results:
+        if r["row"] is None:
+            failed.append(r["model_str"])
+        else:
+            rows.append(r["row"])
+            fits.append(r["fit"])
+
+    if not rows:
+        raise RuntimeError("All candidate (S)ARIMA models failed to converge.")
+
+    full_table = pd.DataFrame(rows)
+    order_idx = np.argsort(full_table[criterion].to_numpy())
+    full_table = full_table.iloc[order_idx].reset_index(drop=True)
+    fits = [fits[i] for i in order_idx]
+
+    full_table["Rank"] = np.arange(1, len(full_table) + 1)
+    full_table["Delta"] = (full_table[criterion] - full_table[criterion].min()).round(3)
+    full_table["Weight"] = _akaike_weights(full_table[criterion].to_numpy()).round(4)
+
+    vote_table = _vote_table(full_table)
+
+    best_model = fits[0]
+    best_model_str = full_table.loc[0, "Model"]
+
+    top_n_use = min(int(top_n), len(full_table))
+    table = full_table.iloc[:top_n_use].reset_index(drop=True)
+
+    return CartArimaResult(
+        best_model=best_model,
+        best_model_str=best_model_str,
+        criterion=criterion,
+        table=table,
+        full_table=full_table,
+        vote_table=vote_table,
+        failed_models=failed,
+        n_total=n_total,
+        n_converged=len(full_table),
+        p_set=p_set, d_set=d_set, q_set=q_set,
+        seasonal=seasonal,
+        exog=exog_arr,
+        data=x_series,
+        n_obs=n,
+        _fits=fits,
+    )
+
+
+def arima_table(result: CartArimaResult, criterion: Optional[str] = None,
+                top_n: Optional[int] = None) -> pd.DataFrame:
+    """Re-rank and/or truncate the comparison table stored in a
+    :class:`CartArimaResult`, without refitting anything."""
+    ft = result.full_table.copy()
+    if criterion is not None:
+        if criterion not in _CRITERIA:
+            raise ValueError(f"criterion must be one of {_CRITERIA}")
+        ft = ft.sort_values(criterion).reset_index(drop=True)
+        ft["Rank"] = np.arange(1, len(ft) + 1)
+        ft["Delta"] = (ft[criterion] - ft[criterion].min()).round(3)
+        ft["Weight"] = _akaike_weights(ft[criterion].to_numpy()).round(4)
+    if top_n is not None:
+        ft = ft.iloc[: int(top_n)].reset_index(drop=True)
+    return ft

arimasel/cv.py

@@ -0,0 +1,130 @@
+"""Rolling-origin (expanding window) cross-validation."""
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from ._utils import _safe_fit
+from .cart_arima import CartArimaResult
+
+
+class ArimaCVResult:
+    """Result of :func:`arima_cv`."""
+
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+
+    def __repr__(self):
+        lines = ["Rolling-Origin Cross-Validation", "=" * 32]
+        order_str = f"ARIMA{self.order}"
+        if self.seasonal_order is not None:
+            order_str += f"{self.seasonal_order[:3]}[{self.seasonal_order[3]}]"
+        lines.append(f"Model order : {order_str}")
+        lines.append(f"Origins     : {self.n_folds}  "
+                     f"(initial={self.initial}, step={self.step}, h={self.h})\n")
+        lines.append("Out-of-sample accuracy by horizon:")
+        lines.append(self.accuracy.to_string(index=False))
+        return "\n".join(lines)
+
+    def plot(self, kind: str = "rmse", ax=None, **kwargs):
+        from .plotting import plot_cv
+        return plot_cv(self, kind=kind, ax=ax, **kwargs)
+
+
+def arima_cv(
+    result: CartArimaResult,
+    h: int = 1,
+    initial: Optional[int] = None,
+    step: int = 1,
+) -> ArimaCVResult:
+    """Rolling-origin (expanding window) cross-validation of the model order
+    selected by :func:`cart_arima`: refit the same order at successive
+    origins, forecast ``h`` steps ahead, and record out-of-sample error.
+
+    Parameters
+    ----------
+    result : CartArimaResult
+    h : int
+        Forecast horizon evaluated at each origin.
+    initial : int, optional
+        Size of the first training window. Defaults to
+        ``max(20, floor(0.5 * n_obs))``.
+    step : int
+        Number of observations the training window expands by between origins.
+
+    Returns
+    -------
+    ArimaCVResult
+    """
+    h = int(h)
+    step = int(step)
+    if h < 1:
+        raise ValueError("h must be a positive integer.")
+    if step < 1:
+        raise ValueError("step must be a positive integer.")
+
+    x = result.data.to_numpy(dtype=float)
+    n = len(x)
+
+    fit = result.best_model
+    order = fit.model.order
+    seasonal_order = None
+    if result.seasonal is not None:
+        seasonal_order = fit.model.seasonal_order
+
+    if initial is None:
+        initial = max(20, n // 2)
+    initial = int(initial)
+    if initial >= n - h:
+        raise ValueError("initial leaves no observations for out-of-sample evaluation.")
+
+    origins = list(range(initial, n - h + 1, step))
+    if not origins:
+        raise ValueError("No valid CV origins with the given initial/h/step.")
+
+    exog = result.exog
+    rows = []
+    for orig in origins:
+        train = x[:orig]
+        actual = x[orig: orig + h]
+        exog_tr = exog[:orig] if exog is not None else None
+        exog_te = exog[orig: orig + h] if exog is not None else None
+
+        fit_o = _safe_fit(train, order=order, seasonal_order=seasonal_order, exog=exog_tr)
+        if fit_o is None:
+            fc = np.full(h, np.nan)
+        else:
+            try:
+                fc = np.asarray(fit_o.get_forecast(steps=h, exog=exog_te).predicted_mean)
+            except Exception:
+                fc = np.full(h, np.nan)
+
+        for j in range(h):
+            rows.append({"Origin": orig, "Horizon": j + 1,
+                        "Actual": actual[j], "Forecast": fc[j],
+                        "Error": actual[j] - fc[j]})
+
+    errors = pd.DataFrame(rows)
+
+    acc_rows = []
+    for horizon, grp in errors.groupby("Horizon"):
+        e = grp["Error"].to_numpy()
+        a = grp["Actual"].to_numpy()
+        finite = np.isfinite(e)
+        e, a = e[finite], a[finite]
+        acc_rows.append({
+            "Horizon": horizon,
+            "RMSE": round(float(np.sqrt(np.mean(e ** 2))), 4) if len(e) else np.nan,
+            "MAE": round(float(np.mean(np.abs(e))), 4) if len(e) else np.nan,
+            "MAPE": round(float(np.mean(np.abs(e / a))) * 100, 4) if len(e) else np.nan,
+            "N": int(len(e)),
+        })
+    accuracy = pd.DataFrame(acc_rows).sort_values("Horizon").reset_index(drop=True)
+
+    return ArimaCVResult(
+        errors=errors, accuracy=accuracy,
+        order=order, seasonal_order=seasonal_order,
+        n_folds=len(origins), h=h, initial=initial, step=step,
+    )