multiarch 0.2.0__tar.gz

multiarch-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Legard525
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

multiarch-0.2.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: multiarch
+Version: 0.2.0
+Summary: Fast multivariate GARCH for Python: CCC, DCC, aDCC, copula-DCC and GO-GARCH, validated against rmgarch
+Author: Alex Nikolaenko
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Legard525/multiarch
+Project-URL: Issues, https://github.com/Legard525/multiarch/issues
+Keywords: garch,dcc,multivariate garch,volatility,correlation,copula,go-garch,value-at-risk,econometrics,finance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: numba>=0.58
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: arch; extra == "test"
+Dynamic: license-file
+
+# multiarch
+
+[![tests](https://github.com/Legard525/multiarch/actions/workflows/tests.yml/badge.svg)](https://github.com/Legard525/multiarch/actions/workflows/tests.yml)
+
+**Multivariate GARCH for Python.** The [`arch`](https://github.com/bashtage/arch) package
+only fits univariate models, so Python has had no maintained multivariate GARCH library.
+Courses and research therefore send Python users to R (`rmgarch`, `tsmarch`).
+multiarch fills that gap:
+
+- **Models:** CCC, DCC and asymmetric DCC, optionally as Gaussian or Student-t copulas, plus GO-GARCH.
+- **Margins:** GARCH(1,1) or GJR-GARCH(1,1) with normal or Student-t errors.
+- **Inference:** two-step standard errors that correct for the first estimation stage.
+- **Large cross-sections:** a composite-likelihood estimator for many assets.
+- **Outputs:** forecasts, simulation, portfolio VaR and ES, rolling backtests and specification tests.
+- **Validation:** it reproduces `rmgarch`'s likelihood exactly. It runs 2–9× faster than rmgarch and 7–30× faster than tsmarch.
+
+```bash
+pip install multiarch
+```
+
+Requires Python ≥ 3.10, NumPy, SciPy, pandas and numba.
+
+## Quick start
+
+```python
+import multiarch as ma
+
+res = ma.DCC(returns).fit()          # returns: (T, N) DataFrame, any units
+print(res.summary())
+
+res.conditional_correlation          # (T, N, N) R_t
+res.conditional_covariance           # (T, N, N) H_t = D_t R_t D_t
+res.correlation("JPM", "INTC")       # one rho_t path as a Series
+res.forecast(10)                     # mean, variance, correlation, covariance
+res.value_at_risk([0.5, 0.5], level=0.01, value=1e6)   # {'VaR': ..., 'ES': ...}
+```
+
+[`examples/course_workflow.py`](https://github.com/Legard525/multiarch/blob/main/examples/course_workflow.py) walks through the standard
+course sequence: EWMA → CCC → DCC → constant-correlation test → portfolio VaR → rolling VaR backtest.
+
+## What's in it
+
+| | |
+|---|---|
+| `DCC(returns, model=...)` | `"dcc"` (Engle 2002), `"adcc"` (Cappiello, Engle & Sheppard 2006), `"ccc"` (Bollerslev 1990) |
+| `vol=` | `"garch"` or `"gjr"` margins, each (1,1) |
+| `mean=` | `"constant"` or `"zero"` |
+| `dist=` | margin distribution, `"normal"` or `"t"` |
+| `corr_dist=` | correlation-stage distribution, `"normal"` or multivariate `"t"` (defaults to `dist`) |
+| `copula=` | `None`, `"normal"` or `"t"`: copula-DCC with parametric margins (as `rmgarch::cgarchfit`) |
+| `estimator=` | `"full"` likelihood or `"composite"` pairwise likelihood (Engle, Shephard & Sheppard 2008) for large N |
+| `convention=` | `"arch"` (default), `"rmgarch"` or `"tsmarch"`: start-up conventions that reproduce each package |
+| `.fit(se=...)` | `"two-step"` (Engle & Sheppard 2001 corrected), `"naive"` or `None` |
+| `.fix(params)` / `.apply(new_returns)` | evaluate fixed parameters, or filter new data with fitted ones |
+| `.forecast(h)` | closed-form variances; Engle–Sheppard correlation forecast as in rmgarch |
+| `.simulate(n, n_paths, start="end")` | Monte Carlo paths, including copula models |
+| `.value_at_risk(w, level, horizon)` | analytic (normal or multivariate t) or simulated VaR and ES |
+| `.value_at_risk_path(w, level)` | in-sample one-step VaR/ES path |
+| `GOGARCH(returns)` | GO-GARCH (van der Weide 2002) with a built-in FastICA rotation |
+| `rolling_forecast(returns, window, refit_every)` | rolling or expanding re-estimation with no look-ahead |
+| `var_backtest(r, VaR, level)` | violation ratio, Kupiec and Christoffersen tests |
+| `constant_correlation_test(returns)` | Engle & Sheppard (2001) test of CCC against DCC |
+| `hosking_test(x, lags)` | multivariate portmanteau test |
+| `ewma_covariance(returns, lam)` | RiskMetrics EWMA |
+| `simulate_dcc(...)` | simulate from given parameters |
+
+Estimation is scale-free: percent and fractional returns give the same parameters,
+with ω and μ rescaled.
+
+## Validation
+
+All numbers come from [`validation/`](https://github.com/Legard525/multiarch/tree/main/validation) and are reproducible: `Rscript rmgarch_fit.R .`
+then `python compare.py`, and `Rscript tsmarch_fit.R .` then `python compare_tsmarch.py`.
+The data are daily returns of DJI stocks from `rmgarch`'s `dji30ret` (T = 5,521).
+
+### Against rmgarch 1.3 (R 4.6)
+
+`ll(ours @ rm)` is multiarch's log-likelihood evaluated at rmgarch's own estimates.
+If both packages implement the same model, it equals rmgarch's reported value.
+
+| case | ll (rmgarch) | ll (ours @ rm) | max \|ρ_t diff\| @ rm | ll (ours, own fit) | time rmgarch → ours |
+|---|---|---|---|---|---|
+| DCC, normal, N=5 | −53514.64292 | −53514.64292 | 0 | −53513.99601 | 2.8 s → 0.32 s |
+| aDCC, normal | −53513.86843 | −53513.86843 | 0 | −53513.13231 | 3.4 s → 0.45 s |
+| DCC, Student-t | −52235.91344 | −52235.91344 | 0 | −52237.53475 | 3.7 s → 0.60 s |
+| DCC, GJR margins | −53481.97322 | −53481.97322 | 0 | −53481.59132 | 3.3 s → 0.39 s |
+| DCC, zero mean | −53534.39786 | −53534.39786 | 0 | −53533.64643 | 2.1 s → 0.26 s |
+| DCC, N=10 | −101267.48845 | −101267.48845 | 0 | −101266.80559 | 7.6 s → 1.2 s |
+| DCC, raw returns, N=2 | 28163.98498 | 28163.98498 | 0 | 28163.97845 | 0.84 s → 0.09 s |
+| t-copula DCC, t margins | −52079.16469 | −52079.16469 | 0 | −52080.47842 | 6.3 s → 3.1 s |
+| Gaussian-copula DCC, t margins | −52196.46089 | −52196.46089 | 0 | −52197.96371 | 3.6 s → 1.1 s |
+
+Timings for multiarch include the two-step standard errors.
+
+- The likelihood functions are identical, and so are the correlation paths at the same parameters.
+- The 10-step DCC covariance forecasts agree to 2e-14.
+- Estimates differ only through the optimiser, and multiarch reaches higher margin likelihoods.
+  Because estimation is two-step, a better first stage can still leave the joint
+  log-likelihood slightly lower (the t and copula rows). That is a property of the two-step
+  estimator, not a different model.
+- Standard errors for the DCC parameters *a* and *b* are within 5% of rmgarch's. For the shape ν and the aDCC asymmetry *g* they are 17–31% larger.
+  A 300-sample Monte Carlo (`mc_se.py`) shows that multiarch's two-step SEs are calibrated:
+  the median SE is 0.0059 against a sampling SD of 0.0059 for *a*, and 0.0124 against 0.0139 for *b*.
+- **GO-GARCH:** given rmgarch's ICA rotation and factor parameters, the likelihood agrees to 0.06,
+  a difference that comes from how the constant mean is estimated. multiarch's own FastICA finds a rotation
+  with a likelihood 277 points higher on this data, in 0.04 s against 0.47 s.
+
+### Against tsmarch (the package used in *Financial Risk Forecasting* notes)
+
+| case | ll (tsmarch) | ll (ours @ ts) | max \|ρ_t diff\| @ ts | time tsmarch → ours |
+|---|---|---|---|---|
+| DCC, N=2 | 28163.94124 | 28163.94306 | 4.5e-4 | 0.73 s → 0.04 s |
+| DCC, N=5 | 73611.21223 | 73611.23406 | 4.2e-4 | 2.7 s → 0.10 s |
+| aDCC, N=5 | 73612.01170 | 73612.03276 | 4.2e-4 | 3.8 s → 0.11 s |
+| DCC, multivariate t | 74873.58661 | 74873.58785 | 3.8e-4 | 3.9 s → 0.13 s |
+
+The margins match tsgarch exactly (σ_t to 1e-14). A residual gap of under 0.03 log-likelihood
+points remains in tsmarch's compiled DCC recursion; it fades to 1e-7 by the end of the sample.
+
+### Notes on rmgarch's `DCCtest`
+
+`rmgarch::DCCtest` departs from Engle & Sheppard (2001) in two ways. It calls
+`qr.solve(regressand, regressors)`, which regresses the lags on the target instead of the
+reverse, and it divides by √σ² instead of σ². `validation/compare.py` reproduces its statistic
+exactly (65.34) from its own residuals. On the same residuals, the textbook statistic
+returned by `constant_correlation_test` is 41.08.
+
+### Scaling
+
+From `validation/bench.py` (T = 2,500, no SEs):
+
+| N | full likelihood | composite likelihood |
+|---|---|---|
+| 5 | 0.05 s | 0.02 s |
+| 25 | 0.34 s | 0.09 s |
+| 50 | 0.35 s | 0.19 s |
+| 100 | n/a | 0.41 s |
+
+The full-likelihood DCC estimate of *b* is biased downward as N grows: 0.930 against a true 0.95
+at N = 50. The composite estimator does not have this bias.
+
+## Conventions
+
+The default (`"arch"`) follows the `arch` package for the margins (exponential backcast)
+and uses Q̄ = Z′Z/T with Q₁ = Q̄. `convention="rmgarch"` reproduces rmgarch's start-up:
+- σ²₁ is the sample mean of ε².
+- Q̄ = cov(Z).
+- The first Q step uses a pre-sample shock of ones in DCC and of zeros in copula-DCC.
+- Copula uniforms are clipped at 0.99999.
+
+`convention="tsmarch"` reproduces tsgarch's σ²₁ = ω + persistence · mean(ε²) and uses Q₁ = Q̄ = cov(Z).
+These choices only affect the first few dozen observations.
+
+## Limitations
+
+- Margins are GARCH(1,1) or GJR(1,1) with a constant or zero mean. There are no ARMA means or higher orders.
+- DCC is of order (1,1).
+- Estimation is two-step. The two-step SEs treat Q̄ and N̄ as known, as rmgarch does.
+- Composite-likelihood SEs are Hessian-only.
+- GO-GARCH SEs ignore estimation error in the rotation.
+- Copula models use parametric margins only. Empirical and semi-parametric margins are not implemented.
+- BEKK and DCC-MIDAS are not implemented.
+
+## References
+
+- Bollerslev (1990), *Modelling the coherence in short-run nominal exchange rates*, REStat.
+- Engle (2002), *Dynamic conditional correlation*, JBES.
+- Engle & Sheppard (2001), *Theoretical and empirical properties of dynamic conditional correlation multivariate GARCH*, NBER WP 8554.
+- Cappiello, Engle & Sheppard (2006), *Asymmetric dynamics in the correlations of global equity and bond returns*, J. Fin. Econometrics.
+- Engle, Shephard & Sheppard (2008), *Fitting vast dimensional time-varying covariance models*, working paper.
+- van der Weide (2002), *GO-GARCH: a multivariate generalized orthogonal GARCH model*, J. Applied Econometrics.
+- Patton (2006), *Modelling asymmetric exchange rate dependence*, IER.
+- Kupiec (1995); Christoffersen (1998); Hosking (1980).
+
+## License
+
+MIT

multiarch-0.2.0/README.md

@@ -0,0 +1,177 @@
+# multiarch
+
+[![tests](https://github.com/Legard525/multiarch/actions/workflows/tests.yml/badge.svg)](https://github.com/Legard525/multiarch/actions/workflows/tests.yml)
+
+**Multivariate GARCH for Python.** The [`arch`](https://github.com/bashtage/arch) package
+only fits univariate models, so Python has had no maintained multivariate GARCH library.
+Courses and research therefore send Python users to R (`rmgarch`, `tsmarch`).
+multiarch fills that gap:
+
+- **Models:** CCC, DCC and asymmetric DCC, optionally as Gaussian or Student-t copulas, plus GO-GARCH.
+- **Margins:** GARCH(1,1) or GJR-GARCH(1,1) with normal or Student-t errors.
+- **Inference:** two-step standard errors that correct for the first estimation stage.
+- **Large cross-sections:** a composite-likelihood estimator for many assets.
+- **Outputs:** forecasts, simulation, portfolio VaR and ES, rolling backtests and specification tests.
+- **Validation:** it reproduces `rmgarch`'s likelihood exactly. It runs 2–9× faster than rmgarch and 7–30× faster than tsmarch.
+
+```bash
+pip install multiarch
+```
+
+Requires Python ≥ 3.10, NumPy, SciPy, pandas and numba.
+
+## Quick start
+
+```python
+import multiarch as ma
+
+res = ma.DCC(returns).fit()          # returns: (T, N) DataFrame, any units
+print(res.summary())
+
+res.conditional_correlation          # (T, N, N) R_t
+res.conditional_covariance           # (T, N, N) H_t = D_t R_t D_t
+res.correlation("JPM", "INTC")       # one rho_t path as a Series
+res.forecast(10)                     # mean, variance, correlation, covariance
+res.value_at_risk([0.5, 0.5], level=0.01, value=1e6)   # {'VaR': ..., 'ES': ...}
+```
+
+[`examples/course_workflow.py`](https://github.com/Legard525/multiarch/blob/main/examples/course_workflow.py) walks through the standard
+course sequence: EWMA → CCC → DCC → constant-correlation test → portfolio VaR → rolling VaR backtest.
+
+## What's in it
+
+| | |
+|---|---|
+| `DCC(returns, model=...)` | `"dcc"` (Engle 2002), `"adcc"` (Cappiello, Engle & Sheppard 2006), `"ccc"` (Bollerslev 1990) |
+| `vol=` | `"garch"` or `"gjr"` margins, each (1,1) |
+| `mean=` | `"constant"` or `"zero"` |
+| `dist=` | margin distribution, `"normal"` or `"t"` |
+| `corr_dist=` | correlation-stage distribution, `"normal"` or multivariate `"t"` (defaults to `dist`) |
+| `copula=` | `None`, `"normal"` or `"t"`: copula-DCC with parametric margins (as `rmgarch::cgarchfit`) |
+| `estimator=` | `"full"` likelihood or `"composite"` pairwise likelihood (Engle, Shephard & Sheppard 2008) for large N |
+| `convention=` | `"arch"` (default), `"rmgarch"` or `"tsmarch"`: start-up conventions that reproduce each package |
+| `.fit(se=...)` | `"two-step"` (Engle & Sheppard 2001 corrected), `"naive"` or `None` |
+| `.fix(params)` / `.apply(new_returns)` | evaluate fixed parameters, or filter new data with fitted ones |
+| `.forecast(h)` | closed-form variances; Engle–Sheppard correlation forecast as in rmgarch |
+| `.simulate(n, n_paths, start="end")` | Monte Carlo paths, including copula models |
+| `.value_at_risk(w, level, horizon)` | analytic (normal or multivariate t) or simulated VaR and ES |
+| `.value_at_risk_path(w, level)` | in-sample one-step VaR/ES path |
+| `GOGARCH(returns)` | GO-GARCH (van der Weide 2002) with a built-in FastICA rotation |
+| `rolling_forecast(returns, window, refit_every)` | rolling or expanding re-estimation with no look-ahead |
+| `var_backtest(r, VaR, level)` | violation ratio, Kupiec and Christoffersen tests |
+| `constant_correlation_test(returns)` | Engle & Sheppard (2001) test of CCC against DCC |
+| `hosking_test(x, lags)` | multivariate portmanteau test |
+| `ewma_covariance(returns, lam)` | RiskMetrics EWMA |
+| `simulate_dcc(...)` | simulate from given parameters |
+
+Estimation is scale-free: percent and fractional returns give the same parameters,
+with ω and μ rescaled.
+
+## Validation
+
+All numbers come from [`validation/`](https://github.com/Legard525/multiarch/tree/main/validation) and are reproducible: `Rscript rmgarch_fit.R .`
+then `python compare.py`, and `Rscript tsmarch_fit.R .` then `python compare_tsmarch.py`.
+The data are daily returns of DJI stocks from `rmgarch`'s `dji30ret` (T = 5,521).
+
+### Against rmgarch 1.3 (R 4.6)
+
+`ll(ours @ rm)` is multiarch's log-likelihood evaluated at rmgarch's own estimates.
+If both packages implement the same model, it equals rmgarch's reported value.
+
+| case | ll (rmgarch) | ll (ours @ rm) | max \|ρ_t diff\| @ rm | ll (ours, own fit) | time rmgarch → ours |
+|---|---|---|---|---|---|
+| DCC, normal, N=5 | −53514.64292 | −53514.64292 | 0 | −53513.99601 | 2.8 s → 0.32 s |
+| aDCC, normal | −53513.86843 | −53513.86843 | 0 | −53513.13231 | 3.4 s → 0.45 s |
+| DCC, Student-t | −52235.91344 | −52235.91344 | 0 | −52237.53475 | 3.7 s → 0.60 s |
+| DCC, GJR margins | −53481.97322 | −53481.97322 | 0 | −53481.59132 | 3.3 s → 0.39 s |
+| DCC, zero mean | −53534.39786 | −53534.39786 | 0 | −53533.64643 | 2.1 s → 0.26 s |
+| DCC, N=10 | −101267.48845 | −101267.48845 | 0 | −101266.80559 | 7.6 s → 1.2 s |
+| DCC, raw returns, N=2 | 28163.98498 | 28163.98498 | 0 | 28163.97845 | 0.84 s → 0.09 s |
+| t-copula DCC, t margins | −52079.16469 | −52079.16469 | 0 | −52080.47842 | 6.3 s → 3.1 s |
+| Gaussian-copula DCC, t margins | −52196.46089 | −52196.46089 | 0 | −52197.96371 | 3.6 s → 1.1 s |
+
+Timings for multiarch include the two-step standard errors.
+
+- The likelihood functions are identical, and so are the correlation paths at the same parameters.
+- The 10-step DCC covariance forecasts agree to 2e-14.
+- Estimates differ only through the optimiser, and multiarch reaches higher margin likelihoods.
+  Because estimation is two-step, a better first stage can still leave the joint
+  log-likelihood slightly lower (the t and copula rows). That is a property of the two-step
+  estimator, not a different model.
+- Standard errors for the DCC parameters *a* and *b* are within 5% of rmgarch's. For the shape ν and the aDCC asymmetry *g* they are 17–31% larger.
+  A 300-sample Monte Carlo (`mc_se.py`) shows that multiarch's two-step SEs are calibrated:
+  the median SE is 0.0059 against a sampling SD of 0.0059 for *a*, and 0.0124 against 0.0139 for *b*.
+- **GO-GARCH:** given rmgarch's ICA rotation and factor parameters, the likelihood agrees to 0.06,
+  a difference that comes from how the constant mean is estimated. multiarch's own FastICA finds a rotation
+  with a likelihood 277 points higher on this data, in 0.04 s against 0.47 s.
+
+### Against tsmarch (the package used in *Financial Risk Forecasting* notes)
+
+| case | ll (tsmarch) | ll (ours @ ts) | max \|ρ_t diff\| @ ts | time tsmarch → ours |
+|---|---|---|---|---|
+| DCC, N=2 | 28163.94124 | 28163.94306 | 4.5e-4 | 0.73 s → 0.04 s |
+| DCC, N=5 | 73611.21223 | 73611.23406 | 4.2e-4 | 2.7 s → 0.10 s |
+| aDCC, N=5 | 73612.01170 | 73612.03276 | 4.2e-4 | 3.8 s → 0.11 s |
+| DCC, multivariate t | 74873.58661 | 74873.58785 | 3.8e-4 | 3.9 s → 0.13 s |
+
+The margins match tsgarch exactly (σ_t to 1e-14). A residual gap of under 0.03 log-likelihood
+points remains in tsmarch's compiled DCC recursion; it fades to 1e-7 by the end of the sample.
+
+### Notes on rmgarch's `DCCtest`
+
+`rmgarch::DCCtest` departs from Engle & Sheppard (2001) in two ways. It calls
+`qr.solve(regressand, regressors)`, which regresses the lags on the target instead of the
+reverse, and it divides by √σ² instead of σ². `validation/compare.py` reproduces its statistic
+exactly (65.34) from its own residuals. On the same residuals, the textbook statistic
+returned by `constant_correlation_test` is 41.08.
+
+### Scaling
+
+From `validation/bench.py` (T = 2,500, no SEs):
+
+| N | full likelihood | composite likelihood |
+|---|---|---|
+| 5 | 0.05 s | 0.02 s |
+| 25 | 0.34 s | 0.09 s |
+| 50 | 0.35 s | 0.19 s |
+| 100 | n/a | 0.41 s |
+
+The full-likelihood DCC estimate of *b* is biased downward as N grows: 0.930 against a true 0.95
+at N = 50. The composite estimator does not have this bias.
+
+## Conventions
+
+The default (`"arch"`) follows the `arch` package for the margins (exponential backcast)
+and uses Q̄ = Z′Z/T with Q₁ = Q̄. `convention="rmgarch"` reproduces rmgarch's start-up:
+- σ²₁ is the sample mean of ε².
+- Q̄ = cov(Z).
+- The first Q step uses a pre-sample shock of ones in DCC and of zeros in copula-DCC.
+- Copula uniforms are clipped at 0.99999.
+
+`convention="tsmarch"` reproduces tsgarch's σ²₁ = ω + persistence · mean(ε²) and uses Q₁ = Q̄ = cov(Z).
+These choices only affect the first few dozen observations.
+
+## Limitations
+
+- Margins are GARCH(1,1) or GJR(1,1) with a constant or zero mean. There are no ARMA means or higher orders.
+- DCC is of order (1,1).
+- Estimation is two-step. The two-step SEs treat Q̄ and N̄ as known, as rmgarch does.
+- Composite-likelihood SEs are Hessian-only.
+- GO-GARCH SEs ignore estimation error in the rotation.
+- Copula models use parametric margins only. Empirical and semi-parametric margins are not implemented.
+- BEKK and DCC-MIDAS are not implemented.
+
+## References
+
+- Bollerslev (1990), *Modelling the coherence in short-run nominal exchange rates*, REStat.
+- Engle (2002), *Dynamic conditional correlation*, JBES.
+- Engle & Sheppard (2001), *Theoretical and empirical properties of dynamic conditional correlation multivariate GARCH*, NBER WP 8554.
+- Cappiello, Engle & Sheppard (2006), *Asymmetric dynamics in the correlations of global equity and bond returns*, J. Fin. Econometrics.
+- Engle, Shephard & Sheppard (2008), *Fitting vast dimensional time-varying covariance models*, working paper.
+- van der Weide (2002), *GO-GARCH: a multivariate generalized orthogonal GARCH model*, J. Applied Econometrics.
+- Patton (2006), *Modelling asymmetric exchange rate dependence*, IER.
+- Kupiec (1995); Christoffersen (1998); Hosking (1980).
+
+## License
+
+MIT

multiarch-0.2.0/multiarch/__init__.py

@@ -0,0 +1,18 @@
+"""multiarch: fast multivariate GARCH (CCC / DCC / aDCC / copula-DCC /
+GO-GARCH) for Python."""
+
+from .dcc import DCC, DCCResult
+from .diagnostics import constant_correlation_test, hosking_test, var_backtest
+from .ewma import ewma_covariance
+from .gogarch import GOGARCH, GOGARCHResult
+from .rolling import RollingForecast, rolling_forecast
+from .simulate import simulate_dcc
+from .univariate import UnivariateSpec, fit_univariate
+
+__all__ = [
+    "DCC", "DCCResult", "GOGARCH", "GOGARCHResult", "RollingForecast",
+    "UnivariateSpec", "constant_correlation_test", "ewma_covariance",
+    "fit_univariate", "hosking_test", "rolling_forecast", "simulate_dcc",
+    "var_backtest",
+]
+__version__ = "0.2.0"

multiarch-0.2.0/multiarch/_kernels.py

@@ -0,0 +1,235 @@
+"""Numba kernels for the inner recursions. Everything here is O(T) loops that
+would be slow in pure Python; the public API lives in the other modules."""
+
+import math
+
+import numpy as np
+from numba import njit
+
+LOG_2PI = math.log(2.0 * math.pi)
+
+
+# ---------------------------------------------------------------- univariate
+
+
+@njit(cache=True)
+def garch_filter(omega, alpha, gamma, beta, resid, sigma2_0):
+    """GJR-GARCH(1,1) variance recursion (gamma=0 gives GARCH), given the
+    first conditional variance sigma2_0."""
+    n = resid.shape[0]
+    sigma2 = np.empty(n)
+    sigma2[0] = sigma2_0
+    for t in range(1, n):
+        e = resid[t - 1]
+        e2 = e * e
+        s = omega + alpha * e2 + beta * sigma2[t - 1]
+        if e < 0.0:
+            s += gamma * e2
+        sigma2[t] = s
+    return sigma2
+
+
+@njit(cache=True)
+def normal_loglik_obs(resid, sigma2):
+    return -0.5 * (LOG_2PI + np.log(sigma2) + resid * resid / sigma2)
+
+
+@njit(cache=True)
+def std_t_loglik_obs(resid, sigma2, nu):
+    """Unit-variance Student-t, as in arch's StudentsT."""
+    c = (
+        math.lgamma(0.5 * (nu + 1.0))
+        - math.lgamma(0.5 * nu)
+        - 0.5 * math.log(math.pi * (nu - 2.0))
+    )
+    return c - 0.5 * np.log(sigma2) - 0.5 * (nu + 1.0) * np.log(
+        1.0 + resid * resid / (sigma2 * (nu - 2.0))
+    )
+
+
+# ---------------------------------------------------------------- correlation
+
+
+@njit(cache=True)
+def _mv_logpdf(z_t, R, nu):
+    """Log density of z_t ~ N(0, R) (nu <= 0) or unit-variance MV-t(nu)."""
+    n = z_t.shape[0]
+    L = np.linalg.cholesky(R)
+    logdet = 0.0
+    for i in range(n):
+        logdet += 2.0 * math.log(L[i, i])
+    # forward substitution: y = L^{-1} z, quad = y'y
+    y = np.empty(n)
+    quad = 0.0
+    for i in range(n):
+        s = z_t[i]
+        for k in range(i):
+            s -= L[i, k] * y[k]
+        y[i] = s / L[i, i]
+        quad += y[i] * y[i]
+    if nu <= 0.0:
+        return -0.5 * (n * LOG_2PI + logdet + quad)
+    return (
+        math.lgamma(0.5 * (nu + n))
+        - math.lgamma(0.5 * nu)
+        - 0.5 * n * math.log(math.pi * (nu - 2.0))
+        - 0.5 * logdet
+        - 0.5 * (nu + n) * math.log(1.0 + quad / (nu - 2.0))
+    )
+
+
+@njit(cache=True)
+def _q_to_r(Q, R):
+    n = Q.shape[0]
+    for i in range(n):
+        for j in range(n):
+            R[i, j] = Q[i, j] / math.sqrt(Q[i, i] * Q[j, j])
+
+
+@njit(cache=True)
+def dcc_loglik_obs(z, Qbar, Nbar, a, b, g, nu, Q0):
+    """Per-observation log density of standardised residuals under (A)DCC.
+
+    Q_t = (1-a-b) Qbar - g Nbar + a z z' + g n n' + b Q_{t-1},  Q_0 = Qbar,
+    with n = z * 1{z<0}. g = 0 gives plain DCC; Q0 is the Q used for the
+    first observation (normally Qbar).
+    """
+    T, n = z.shape
+    out = np.empty(T)
+    C = (1.0 - a - b) * Qbar - g * Nbar
+    Q = Q0.copy()
+    R = np.empty((n, n))
+    for t in range(T):
+        if t > 0:
+            zp = z[t - 1]
+            for i in range(n):
+                ni = zp[i] if zp[i] < 0.0 else 0.0
+                for j in range(i, n):
+                    nj = zp[j] if zp[j] < 0.0 else 0.0
+                    v = C[i, j] + a * zp[i] * zp[j] + g * ni * nj + b * Q[i, j]
+                    Q[i, j] = v
+                    Q[j, i] = v
+        _q_to_r(Q, R)
+        out[t] = _mv_logpdf(z[t], R, nu)
+    return out
+
+
+@njit(cache=True)
+def dcc_filter(z, Qbar, Nbar, a, b, g, Q0):
+    """Q_t and R_t for t = 0..T (index T is the one-step-ahead forecast)."""
+    T, n = z.shape
+    Qs = np.empty((T + 1, n, n))
+    Rs = np.empty((T + 1, n, n))
+    C = (1.0 - a - b) * Qbar - g * Nbar
+    Q = Q0.copy()
+    for t in range(T + 1):
+        if t > 0:
+            zp = z[t - 1]
+            for i in range(n):
+                ni = zp[i] if zp[i] < 0.0 else 0.0
+                for j in range(i, n):
+                    nj = zp[j] if zp[j] < 0.0 else 0.0
+                    v = C[i, j] + a * zp[i] * zp[j] + g * ni * nj + b * Q[i, j]
+                    Q[i, j] = v
+                    Q[j, i] = v
+        Qs[t] = Q
+        _q_to_r(Q, Rs[t])
+    return Qs, Rs
+
+
+@njit(cache=True)
+def dcc_composite_loglik(z, Qbar, Nbar, pairs, a, b, g, nu, Q0):
+    """Composite likelihood (Engle, Shephard & Sheppard 2008): the sum of
+    bivariate DCC log-likelihoods over the given pairs. O(T * #pairs) with
+    scalar 2x2 algebra, so it scales to hundreds of assets."""
+    T = z.shape[0]
+    total = 0.0
+    if nu > 0.0:
+        c = (
+            math.lgamma(0.5 * (nu + 2.0))
+            - math.lgamma(0.5 * nu)
+            - math.log(math.pi * (nu - 2.0))
+        )
+    else:
+        c = -LOG_2PI
+    for p in range(pairs.shape[0]):
+        i = pairs[p, 0]
+        j = pairs[p, 1]
+        cii = (1.0 - a - b) * Qbar[i, i] - g * Nbar[i, i]
+        cjj = (1.0 - a - b) * Qbar[j, j] - g * Nbar[j, j]
+        cij = (1.0 - a - b) * Qbar[i, j] - g * Nbar[i, j]
+        qii = Q0[i, i]
+        qjj = Q0[j, j]
+        qij = Q0[i, j]
+        for t in range(T):
+            if t > 0:
+                zi = z[t - 1, i]
+                zj = z[t - 1, j]
+                ni = zi if zi < 0.0 else 0.0
+                nj = zj if zj < 0.0 else 0.0
+                qii = cii + a * zi * zi + g * ni * ni + b * qii
+                qjj = cjj + a * zj * zj + g * nj * nj + b * qjj
+                qij = cij + a * zi * zj + g * ni * nj + b * qij
+            rho = qij / math.sqrt(qii * qjj)
+            det = 1.0 - rho * rho
+            if det <= 0.0:
+                return -np.inf
+            x = z[t, i]
+            y = z[t, j]
+            quad = (x * x - 2.0 * rho * x * y + y * y) / det
+            if nu > 0.0:
+                total += c - 0.5 * math.log(det) - 0.5 * (nu + 2.0) * math.log(
+                    1.0 + quad / (nu - 2.0)
+                )
+            else:
+                total += c - 0.5 * math.log(det) - 0.5 * quad
+    return total
+
+
+# ---------------------------------------------------------------- simulation
+
+
+@njit(cache=True)
+def simulate_path(mu, omega, alpha, gamma, beta, Qbar, Nbar, a, b, g, shocks, burn,
+                  Q0, s2_0):
+    """Simulate returns from GJR-GARCH margins + (A)DCC correlation.
+
+    `shocks` are iid unit-variance draws (T+burn, n) with identity
+    correlation; they are rotated by chol(R_t) each step. Q0 and s2_0 are
+    the state for the first simulated period (Qbar and the unconditional
+    variances for an unconditional start, Q_{T+1} and sigma2_{T+1} to
+    simulate forward from the end of a sample).
+    """
+    Ttot, n = shocks.shape
+    eps = np.empty((Ttot, n))
+    sig2 = np.empty((Ttot, n))
+    zs = np.empty((Ttot, n))
+    C = (1.0 - a - b) * Qbar - g * Nbar
+    Q = Q0.copy()
+    R = np.empty((n, n))
+    for t in range(Ttot):
+        if t > 0:
+            zp = zs[t - 1]
+            for i in range(n):
+                ni = zp[i] if zp[i] < 0.0 else 0.0
+                for j in range(i, n):
+                    nj = zp[j] if zp[j] < 0.0 else 0.0
+                    v = C[i, j] + a * zp[i] * zp[j] + g * ni * nj + b * Q[i, j]
+                    Q[i, j] = v
+                    Q[j, i] = v
+            ep = eps[t - 1]
+            for i in range(n):
+                e2 = ep[i] * ep[i]
+                s = omega[i] + alpha[i] * e2 + beta[i] * sig2[t - 1, i]
+                if ep[i] < 0.0:
+                    s += gamma[i] * e2
+                sig2[t, i] = s
+        else:
+            sig2[0] = s2_0
+        _q_to_r(Q, R)
+        L = np.linalg.cholesky(R)
+        zt = L @ shocks[t]
+        zs[t] = zt
+        for i in range(n):
+            eps[t, i] = math.sqrt(sig2[t, i]) * zt[i]
+    return eps[burn:] + mu, sig2[burn:], zs[burn:]