Metadata-Version: 2.4
Name: arimasel
Version: 0.1.0
Summary: Cartesian product-based (seasonal) ARIMA model identification, selection, cross-validation, and exploratory time series analysis
Author-email: Olushina Olawale Awe <olawaleawe@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/Olawaleawe/arimasel-py
Project-URL: Repository, https://github.com/Olawaleawe/arimasel-py
Project-URL: Issues, https://github.com/Olawaleawe/arimasel-py/issues
Keywords: time series,arima,sarima,forecasting,model selection,cross-validation,exploratory data analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.9
Requires-Dist: statsmodels>=0.14
Provides-Extra: plot
Requires-Dist: matplotlib>=3.6; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: matplotlib>=3.6; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# arimasel

**Cartesian product-based (seasonal) ARIMA model identification and selection for Python.**

A Python port of the R package [`arimasel`](https://github.com/Olawaleawe/arimasel). Rather
than relying on ACF/PACF plots or a stepwise search (as in `auto_arima`), `arimasel`
exhaustively evaluates every candidate `(p,d,q)(P,D,Q)[m]` model in the Cartesian product of
user-supplied index sets, ranks all converged models simultaneously by AIC, AICc, BIC, and
HQIC, and quantifies model uncertainty with Akaike weights. Built on
[statsmodels](https://www.statsmodels.org/).

## Features

- **Exhaustive, transparent search** — every candidate model in the search space is fit; no
  greedy stepwise heuristics.
- **Seasonal ARIMA** — search over `(p,d,q)` combined with seasonal `(P,D,Q)[period]`.
- **Exogenous regressors** — regression with ARIMA errors via `exog` / `exog_future`.
- **Four criteria at once** — AIC, AICc, BIC, HQIC, plus a criterion "vote table".
- **Akaike weights** — model uncertainty quantification and weighted ensemble forecasting.
- **Rolling-origin cross-validation** — genuine out-of-sample backtesting via `arima_cv`.
- **Feature-based EDA** — `ts_features` / `ts_eda` compute scale-free time series
  characteristics (trend/seasonal strength, spectral entropy, ACF(1), lumpiness, stability)
  in the spirit of Hyndman, Wang and Laptev (2015).
- **Feature-guided automatic search** — `smart_arima` narrows the search space using those
  features, transparently, before running the exhaustive search.
- **Bundled datasets** — three Nigerian macroeconomic series (`gdp_ng`, `inflation_ng`,
  `exchange_ng`) for examples and testing.

## Installation

```bash
pip install arimasel

# with plotting support
pip install arimasel[plot]
```

## Quick start

```python
import arimasel as am

x = am.load_gdp_ng()

result = am.cart_arima(x, p_set=range(3), d_set=range(2), q_set=range(3))
print(result)

forecast = am.arima_forecast(result, h=5, ensemble=True, top_k=3)
print(forecast)
forecast.plot()  # requires arimasel[plot]
```

### Seasonal search

```python
x = am.load_inflation_ng()

result = am.cart_arima(
    x, p_set=range(2), d_set=[0, 1], q_set=range(2),
    seasonal={"P": [0, 1], "D": [0, 1], "Q": [0, 1], "period": 12},
)
print(result)
```

### Exploratory data analysis and feature-guided search

```python
eda = am.ts_eda(x, period=12)
print(eda)
eda.plot()

result = am.smart_arima(x, p_set=range(3), q_set=range(3), period=12)
```

### Rolling-origin cross-validation

```python
cv = am.arima_cv(result, h=3, initial=200)
print(cv)
cv.plot(kind="rmse")
```

## API overview

| Function | Purpose |
|---|---|
| `cart_arima` | Exhaustive (seasonal) ARIMA search |
| `arima_table` | Re-rank / truncate the comparison table |
| `arima_forecast` | Point + interval forecasts, optional ensemble |
| `arima_diagnose` | Residual diagnostics (Shapiro-Wilk, Ljung-Box) |
| `stationarity_test` | ADF + KPSS with a consensus conclusion |
| `suggest_d` / `suggest_D` | Recommended non-seasonal / seasonal differencing order |
| `arima_cv` | Rolling-origin cross-validation |
| `ts_features` / `ts_eda` | Feature-based exploratory data analysis |
| `smart_arima` | Feature-guided automatic search |
| `seasonal_strength` | STL-based trend/seasonal strength |
| `hqic` / `cp_sets` / `arima_weights` | Standalone utilities |

## Companion R package

An R version of this package, also called `arimasel`, is available at
<https://github.com/Olawaleawe/arimasel>.

## License

GPL-3.0-or-later

## Author

Olushina Olawale Awe (<olawaleawe@gmail.com>) — ORCID:
[0000-0002-0442-4519](https://orcid.org/0000-0002-0442-4519)
