ENH: Add the NGARCH volatility process - #966

Target 9.1: merge after v9.0.0 is tagged. Closes #636.

Adds arch.univariate.NGARCH(p=1, o=1, q=1) (o <= p): the nonlinear asymmetric GARCH of
Engle and Ng (1993), which rugarch calls NAGARCH.

sigma2_t = omega + sum_i alpha_i (e_{t-i} - theta_i sigma_{t-i})^2 + sum_j beta_j sigma2_{t-j}

Sign convention: theta > 0 is the leverage effect. It was settled from the NBER working
paper (w3681), whose estimated model reads (e - 0.2683 sqrt(h))^2, and it matches rugarch's
eta21. The class Notes explain the naming clash with Higgins and Bera (1992).

What is included:

• A compiled ngarch_recursion with a numba/Python twin and a .pyi stub.
• NGARCHUpdater, so ARCHInMean works with NGARCH, including pickling.
• arch_model(vol="ngarch", o=1). Without a shift the model is a GARCH, so
  arch_model(vol="ngarch") with o=0 (the default o of every vol) returns a GARCH
  process and issues a ValueWarning that says to use vol="garch" or set o > 0.
  NGARCH(o=0) issues the same kind of warning.
• The analytic forecasts are exact at every horizon, f_h = omega + phi f_{h-1} with
  phi = sum alpha (1 + theta^2) + sum beta, for any standardized distribution, because
  E[(z - theta)^2] = 1 + theta^2.
• Simulation and bootstrap forecasts, simulate, and the crash guards.
• Constraint: the linear sum(alpha) + sum(beta) < 1 plus non-negativity, as for APARCH.
  It does not imply the stationarity condition phi < 1, so fit issues a ValueWarning
  when the estimated persistence phi is 1 or more (controlled by show_warning). This
  uses a new private hook, VolatilityProcess._fit_warning, which returns None for the
  other processes.

Validation: rugarch 1.5-6 on R 4.6.1, fGARCH/NAGARCH.

• Variances to 4e-15 relative and log-likelihoods to 6e-14, for normal and Student-t,
  with matched initial values. rugarch's fGARCH filter adds an undocumented 1e-6 inside
  (z - eta)^2. That was confirmed on three parameter sets and is accounted for.
• 10-step forecasts to 1e-6.
• Fits on 4,000 observations: estimates within 0.008.
• For an ARCH order of 2, rugarch's fGARCH disagrees with its own sGARCH, so p >= 2 is
  validated against an independent NumPy recursion and simulation instead.

Tests:

• test_ngarch.py (175): the recursion against NumPy for 7 orders; Cython against numba
  against Python; theta = 0 equals GARCH; the updaters against the recursion.
• Analytic forecasts against simulated means within 4 standard errors (normal and
  skew-t), horizon 1 from every origin, and parameter recovery for (1,1,1), (2,1,1) and
  (2,2,1).
• The starting values have a grid persistence computed with the shift on the first o
  of the p lags.
• Both warnings: raised where expected, pointing at the caller's line, and not raised for
  a model with a shift or a stationary fit; show_warning=False silences the fit warning.
• arch_model, fix and ARCHInMean integration.
• NGARCH is added to the existing validation, crash-guard, updater, string-option,
  integer-input, forecast, append and hedgehog-plot lists.
• Every line the PR adds to volatility.py, recursions_python.py, mean.py and
  base.py is covered, with no partial branches.
• Fast suite 27,511 passed (19 skipped: numba not installed, and o < p
  parametrizations) with no warnings; the slow univariate tests, 777, passed with no
  warnings. numpydoc lint, flake8, ruff, black and isort are clean, and mypy reports no
  new errors.

For review:

• The ValueWarning for NGARCH(o=0) can be dropped if direct use of the class should
  stay silent; arch_model would still return a GARCH with a warning.
• Use the exact nonlinear constraint only if users report persistence of 1 or more.

Thanks to @itsNH98 for the request.

🤖 Generated with Claude Code