---
title: "Getting Started with wARMASVp"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with wARMASVp}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6, fig.height = 4
)
```

The **wARMASVp** package provides closed-form estimation, simulation, hypothesis
testing, filtering, and forecasting for higher-order stochastic volatility SV(p)
models. It supports Gaussian, Student-t, and Generalized Error Distribution (GED)
innovations, with optional leverage effects.

## The SV(p) Model

The stochastic volatility model of order $p$ is:

$$y_t = \sigma_y \exp(w_t / 2)\, z_t$$
$$w_t = \phi_1 w_{t-1} + \cdots + \phi_p w_{t-p} + \sigma_v v_t$$

where $z_t$ is an i.i.d. innovation (Gaussian, Student-t, or GED) and
$v_t \sim N(0,1)$ drives the log-volatility.

## Simulation and Estimation

### Gaussian SV(1)

```{r gaussian-sv1}
library(wARMASVp)
set.seed(123)

# Simulate
sim <- sim_svp(2000, phi = 0.95, sigy = 1, sigv = 0.3)
y <- sim$y

# Estimate
fit <- svp(y, p = 1, J = 10)
summary(fit)
```

### Gaussian SV(2)

```{r gaussian-sv2}
y2 <- sim_svp(2000, phi = c(0.20, 0.63), sigy = 1, sigv = 0.5)$y
fit2 <- svp(y2, p = 2, J = 10)
summary(fit2)
```

### Student-t Innovations

```{r student-t}
yt <- sim_svp(2000, phi = 0.90, sigy = 1, sigv = 0.3,
              errorType = "Student-t", nu = 5)$y
fit_t <- svp(yt, p = 1, errorType = "Student-t")
summary(fit_t)
```

### GED Innovations

```{r ged}
yg <- sim_svp(2000, phi = 0.90, sigy = 1, sigv = 0.3,
              errorType = "GED", nu = 1.5)$y
fit_ged <- svp(yg, p = 1, errorType = "GED")
summary(fit_ged)
```

## Leverage Effects

When return and volatility shocks are correlated ($\rho \neq 0$), use the
leverage option:

```{r leverage}
sim_lev <- sim_svp(2000, phi = 0.95, sigy = 1, sigv = 0.3,
                   leverage = TRUE, rho = -0.5)
fit_lev <- svp(sim_lev$y, p = 1, leverage = TRUE)
summary(fit_lev)
```

Leverage is supported for all three distributions:

```{r leverage-t}
sim_lev_t <- sim_svp(2000, phi = 0.90, sigy = 1, sigv = 0.3,
                     errorType = "Student-t", nu = 5,
                     leverage = TRUE, rho = -0.5)
fit_lev_t <- svp(sim_lev_t$y, p = 1, errorType = "Student-t", leverage = TRUE)
summary(fit_lev_t)
```

## Hypothesis Testing

The package provides Local Monte Carlo (LMC) and Maximized Monte Carlo (MMC)
tests based on Dufour (2006).

### AR Order Testing

Test whether SV(1) is sufficient versus SV(2):

```{r test-ar}
y_test <- sim_svp(2000, phi = 0.95, sigy = 1, sigv = 0.3)$y

# H0: SV(1) vs H1: SV(2) — should not reject
test_ar <- lmc_ar(y_test, p_null = 1, p_alt = 2, N = 49)
print(test_ar)
```

### Leverage Testing

```{r test-lev}
test_lev <- lmc_lev(y_test, p = 1, N = 49, Amat = "Weighted")
print(test_lev)
```

### Distribution Testing

Test for heavy tails against a specific null value of the tail parameter:

```{r test-dist}
# Test H0: nu = 10 (mild tails) on Student-t data with true nu = 5
test_t <- lmc_t(yt, nu_null = 10, N = 49, Amat = "Weighted")
print(test_t)

# Directional test: H1: nu < 10 (heavier tails than null)
test_t_dir <- lmc_t(yt, nu_null = 10, N = 49, Amat = "Weighted", direction = "less")
print(test_t_dir)
```

## AR Order Selection via Information Criteria

In addition to the LMC/MMC pairwise AR-order test above, the package selects the
SV(p) lag order by information criteria. `svp_IC()` computes the criteria for a
single fitted model; `svp_AR_order()` sweeps over `p = 1, ..., pmax` and reports
the argmin for each criterion.

```{r ic-single}
fit_ic <- svp(y_test, p = 2, J = 10)
svp_IC(fit_ic)
```

```{r ic-sweep}
sel <- svp_AR_order(y_test, pmax = 4, J = 10)
sel$argmin
```

Four criteria are returned by default, spanning two estimation families and two
penalty philosophies: `BIC_Kalman` / `AIC_Kalman` use the QML log-likelihood from
the Gaussian mixture Kalman filter, while `BIC_HR` / `AIC_HR` use a two-stage
Hannan-Rissanen ARMA(p, p) residual variance. Additional criteria (`AICc_Kalman`,
`BIC_Whittle`, and the Yule-Walker variants) are available opt-in via the
`criteria` argument. Both functions read `errorType` and `leverage` from the
fitted model, so heavy-tailed and leverage specifications are handled
automatically. See Ahsan, Dufour, and Rodriguez-Rondon (2026) for the
theoretical motivation and consistency simulations.

## Filtering

Three methods are available via `filter_svp()`, which takes a fitted model:

- **Corrected Kalman Filter (CKF)**: Gaussian approximation, fast.
- **Gaussian Mixture Kalman Filter (GMKF)**: KSC (1998) 7-component mixture.
  Recommended — dominates CKF even under Gaussianity.
- **Bootstrap Particle Filter (BPF)**: Exact density weights. Gold-standard benchmark.

```{r filtering}
# Fit model
fit_filt <- svp(y, p = 1, J = 10)

# GMKF (recommended)
filt <- filter_svp(fit_filt, method = "mixture")
plot(filt)
```

## Forecasting

Multi-step ahead volatility forecasts using Kalman filtering. Pass a fitted
model object from `svp()`:

```{r forecast}
fit_fc <- svp(sim_lev$y, p = 1, leverage = TRUE)
fc <- forecast_svp(fit_fc, H = 20)
plot(fc)
```

Output scales can be chosen: `"log-variance"` (default), `"variance"`, or
`"volatility"`. All three are always computed and stored.

## References

- Ahsan, M. N. and Dufour, J.-M. (2021). Simple estimators and inference for
  higher-order stochastic volatility models. *Journal of Econometrics*,
  224(1), 181-197.
- Ahsan, M. N., Dufour, J.-M., and Rodriguez-Rondon, G. (2025). Estimation and
  inference for higher-order stochastic volatility models with leverage.
  *Journal of Time Series Analysis*, 46(6), 1064-1084.
- Ahsan, M. N., Dufour, J.-M., and Rodriguez-Rondon, G. (2026). Estimation and
  inference for stochastic volatility models with heavy-tailed distributions.
  Bank of Canada Staff Working Paper 2026-8.
  [doi:10.34989/swp-2026-8](https://doi.org/10.34989/swp-2026-8)
- Dufour, J.-M. (2006). Monte Carlo tests with nuisance parameters: A general
  approach to finite-sample inference and nonstandard asymptotics.
  *Journal of Econometrics*, 133(2), 443-477.