---
title: "Introduction to arimasel: Cartesian Product ARIMA Model Selection"
author: "Olushina Olawale Awe (PStat, CStat, FRSS)"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to arimasel}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>",
  fig.width = 7, fig.height = 5, fig.align = "center"
)
library(arimasel)
set.seed(2026)
```

## 1. Motivation

The Box-Jenkins methodology remains the dominant framework for univariate
time series modelling. Its classical identification step relies on the
Autocorrelation Function (ACF) and Partial Autocorrelation Function (PACF)
plots. However, these plots often present conflicting or ambiguous pictures,
particularly for mixed ARIMA(p,d,q) models, making reliable identification
difficult in practice.

The `arimasel` package proposes an alternative algorithm grounded in the
mathematical theory of **Cartesian products of sets**. Rather than examining
ACF/PACF plots or using stepwise search (as in `auto.arima`), the algorithm:

1. Accepts user-defined index sets $P$, $D$, and $Q$.
2. Computes the Cartesian product $P \times D \times Q$.
3. Fits every ARIMA$(p,d,q)$ triple exhaustively.
4. Ranks all converged models by four information criteria simultaneously:
   AIC, AICc, BIC, and HQIC.
5. Quantifies model uncertainty via Akaike weights.
6. Supports best-model and ensemble forecasting.

## 2. Enumerating Candidates with `cp_sets()`

```{r cp-sets}
cp_sets(p_set = 0:2, d_set = 0:1, q_set = 0:2)
```

The function confirms $|P| \times |D| \times |Q| = 3 \times 2 \times 3 = 18$
candidate models.

## 3. Data

The package ships with three Nigerian macroeconomic time series.

```{r data-plots, fig.height=4}
data(gdp_ng)
data(exchange_ng)
data(inflation_ng)

par(mfrow = c(1, 3), mar = c(4, 4, 3, 1))
plot(gdp_ng,      main = "GDP Growth (%)",    ylab = "%")
plot(exchange_ng, main = "USD/NGN Rate",      ylab = "NGN")
plot(inflation_ng,main = "CPI Inflation (%)", ylab = "%")
par(mfrow = c(1, 1))
```

## 4. Pre-screening: Stationarity and Differencing

```{r stationarity}
stationarity_test(gdp_ng)
d_rec <- suggest_d(gdp_ng)
cat("Recommended d:", d_rec, "\n")
```

## 5. Cartesian Product ARIMA Selection

```{r cart-arima}
result <- cart_arima(gdp_ng,
                     p_set     = 0:3,
                     d_set     = 0:1,
                     q_set     = 0:3,
                     criterion = "AIC",
                     top_n     = 10L)
print(result)
```

```{r summary}
summary(result)
```

## 6. Re-ranking by Different Criteria

```{r rerank}
arima_table(result, criterion = "BIC", top_n = 5)
```

## 7. Akaike Weights

```{r weights}
ic_vals <- setNames(result$full_table$AIC,
                    result$full_table$Model)
arima_weights(ic_vals[1:6])
```

## 8. Criterion Vote Table

```{r vote}
result$vote_table
```

## 9. Visualising the Results

```{r plot-criteria, fig.height=5}
plot(result, type = "criteria", top_n = 8)
```

```{r plot-weights, fig.height=5}
plot(result, type = "weights", top_n = 8)
```

```{r plot-surface, fig.height=5}
plot(result, type = "surface", criterion = "AIC")
```

```{r plot-fitted, fig.height=5}
plot(result, type = "fitted")
```

## 10. Residual Diagnostics

```{r diagnose}
arima_diagnose(result, lags = 15)
```

## 11. Forecasting

### 11.1 Best-model forecast

```{r forecast-best, fig.height=5}
fc <- arima_forecast(result, h = 8, level = c(80, 95), plot = TRUE)
cat("Point forecasts:\n")
round(fc$mean, 2)
```

### 11.2 Ensemble forecast

```{r forecast-ensemble, fig.height=5}
fc_ens <- arima_forecast(result, h = 8, ensemble = TRUE,
                         top_k = 4L, plot = TRUE)
```

## 12. Monthly Series: Exchange Rate

```{r exchange}
res_ex <- cart_arima(exchange_ng,
                     p_set = 0:2, d_set = 1L, q_set = 0:2,
                     criterion = "BIC")
print(res_ex)
arima_forecast(res_ex, h = 12, plot = TRUE)
```

## 13. Comparing with auto.arima

```{r compare, eval=requireNamespace("forecast", quietly=TRUE)}
compare_arima(gdp_ng, p_set = 0:3, d_set = 0:1, q_set = 0:3,
              holdout = 5L)
```

## 14. Summary

The `arimasel` package provides a transparent, exhaustive, multi-criteria
approach to ARIMA model identification. Key advantages over stepwise methods:

- **Exhaustive**: every $(p,d,q)$ in the Cartesian product is evaluated.
- **Multi-criteria**: simultaneous ranking by AIC, AICc, BIC, and HQIC.
- **Uncertainty quantification**: Akaike weights and evidence ratios.
- **Ensemble forecasting**: weighted averaging across top-$k$ models.
- **Reproducible**: fully deterministic given the input sets.

## References

Awe, O. O. (2026). *arimasel: Cartesian Product-Based ARIMA Model
Identification and Selection*. R package version 0.1.0.

Akaike, H. (1974). A new look at the statistical model identification.
*IEEE Transactions on Automatic Control*, **19**(6), 716--723.

Box, G. E. P., Jenkins, G. M., Reinsel, G. C., and Ljung, G. M. (2015).
*Time Series Analysis: Forecasting and Control* (5th ed.). John Wiley & Sons.

Burnham, K. P. and Anderson, D. R. (2002). *Model Selection and Multimodel
Inference: A Practical Information-Theoretic Approach* (2nd ed.). Springer.

Hannan, E. J. and Quinn, B. G. (1979). The determination of the order of an
autoregression. *Journal of the Royal Statistical Society, Series B*,
**41**(2), 190--195.