mfe-toolbox 0.1.0__tar.gz

mfe_toolbox-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,18 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install mkdocs-material mkdocstrings[python]
+      - run: mkdocs gh-deploy --force

mfe_toolbox-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install uv
+      - run: uv sync --all-groups
+      - run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

mfe_toolbox-0.1.0/.gitignore

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Cython compiled files
+*.c
+*.cpp
+*.so
+*.pyd
+*.html          # Cython annotation files (from annotate=True)
+
+# Cython build artifacts
+src/mfe/realized/_core.cpython-*.so
+src/mfe/multivariate/_core.cpython-*.so
+
+# setuptools build directories
+build/
+lib.*/
+temp.*/
+
+# pytest
+.pytest_cache/
+.cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# ruff
+.ruff_cache/
+
+# MkDocs
+site/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Profiling
+*.prof
+*.lprof
+
+# Local dev
+.env
+*.local

mfe_toolbox-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: mfe-toolbox
+Version: 0.1.0
+Summary: Python port of the MFE Toolbox — financial econometrics for HFT data
+Author: Gabin Taibi
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: arch>=6.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: scipy>=1.11
+Requires-Dist: statsmodels>=0.14
+Description-Content-Type: text/markdown
+
+# mfe — Financial Econometrics for Python
+
+Python port of Kevin Sheppard's Oxford MFE Toolbox, optimised for HFT data.
+Complements [`arch`](https://arch.readthedocs.io) — covering everything `arch` is missing.
+
+## What's inside
+
+| Module | Contents |
+|--------|----------|
+| `mfe.realized` | RV, BPV, MedRV, realized kernel, TSRV, MSRV, Hayashi-Yoshida, multivariate kernel, BNS jump test |
+| `mfe.multivariate` | DCC, CCC, BEKK, O-GARCH, GO-GARCH, RCC |
+| `mfe.univariate` | HAR-RV (standard / MODIFIED / matrix intervals / HAR-J), HEAVY |
+| `mfe.timeseries` | VAR (4 VCV options), Granger causality, IRF, Beveridge-Nelson |
+| `mfe.bootstrap` | Wild bootstrap, SPA test (Hansen 2005), StepM (Romano-Wolf 2005) |
+| `mfe.crosssection` | Fama-MacBeth, OLS/OLSNW, PCA |
+| `mfe.tests_stat` | ARCH-LM, Ljung-Box, HAC LM, Diebold-Mariano, Mincer-Zarnowitz |
+| `mfe.distributions` | Skew-t (analytic score), GED, multivariate normal log-likelihood |
+
+## Installation
+
+```bash
+pip install mfe
+```
+
+## Cython extensions (optional, recommended for production)
+
+Cython compilation gives 10–800× speedups on hot paths (realized kernel inner
+loop, Hayashi-Yoshida sweep, DCC/BEKK recursions):
+
+```bash
+pip install cython numpy setuptools
+python setup_cython.py build_ext --inplace
+```
+
+## Quick start
+
+```python
+from mfe.realized import price_filter, returns_from_prices, realized_kernel, bns_jump_test
+from mfe.realized._types import SamplingType
+
+prices_5m, times_5m = price_filter(
+    tick_prices, tick_times,
+    sampling_type=SamplingType.CALENDAR_TIME,
+    sampling_interval=300,
+)
+r = returns_from_prices(prices_5m)
+rk  = realized_kernel(r)
+jmp = bns_jump_test(r)
+
+from mfe.multivariate import DCC, RCC
+dcc = DCC().fit(returns)          # (T, K) → (T, K, K) sigma_t
+rcc = RCC().fit(returns)          # covariance targeting by construction
+
+from mfe.univariate import HEAVY
+heavy = HEAVY().fit(daily_returns, realized_variances)
+```
+
+## Development
+
+```bash
+uv sync --all-groups
+PYTHONPATH=src pytest tests/     # 246 tests
+mkdocs serve                     # documentation
+```
+
+## Relationship to MATLAB MFE Toolbox
+
+This package ports [bashtage/mfe-toolbox](https://github.com/bashtage/mfe-toolbox)
+to Python, fixing several bugs present in the MATLAB source (memory leaks, silent
+non-convergence, O(N²) algorithms replaced with O(N log N) Cython implementations).

mfe_toolbox-0.1.0/README.md

@@ -0,0 +1,70 @@
+# mfe — Financial Econometrics for Python
+
+Python port of Kevin Sheppard's Oxford MFE Toolbox, optimised for HFT data.
+Complements [`arch`](https://arch.readthedocs.io) — covering everything `arch` is missing.
+
+## What's inside
+
+| Module | Contents |
+|--------|----------|
+| `mfe.realized` | RV, BPV, MedRV, realized kernel, TSRV, MSRV, Hayashi-Yoshida, multivariate kernel, BNS jump test |
+| `mfe.multivariate` | DCC, CCC, BEKK, O-GARCH, GO-GARCH, RCC |
+| `mfe.univariate` | HAR-RV (standard / MODIFIED / matrix intervals / HAR-J), HEAVY |
+| `mfe.timeseries` | VAR (4 VCV options), Granger causality, IRF, Beveridge-Nelson |
+| `mfe.bootstrap` | Wild bootstrap, SPA test (Hansen 2005), StepM (Romano-Wolf 2005) |
+| `mfe.crosssection` | Fama-MacBeth, OLS/OLSNW, PCA |
+| `mfe.tests_stat` | ARCH-LM, Ljung-Box, HAC LM, Diebold-Mariano, Mincer-Zarnowitz |
+| `mfe.distributions` | Skew-t (analytic score), GED, multivariate normal log-likelihood |
+
+## Installation
+
+```bash
+pip install mfe
+```
+
+## Cython extensions (optional, recommended for production)
+
+Cython compilation gives 10–800× speedups on hot paths (realized kernel inner
+loop, Hayashi-Yoshida sweep, DCC/BEKK recursions):
+
+```bash
+pip install cython numpy setuptools
+python setup_cython.py build_ext --inplace
+```
+
+## Quick start
+
+```python
+from mfe.realized import price_filter, returns_from_prices, realized_kernel, bns_jump_test
+from mfe.realized._types import SamplingType
+
+prices_5m, times_5m = price_filter(
+    tick_prices, tick_times,
+    sampling_type=SamplingType.CALENDAR_TIME,
+    sampling_interval=300,
+)
+r = returns_from_prices(prices_5m)
+rk  = realized_kernel(r)
+jmp = bns_jump_test(r)
+
+from mfe.multivariate import DCC, RCC
+dcc = DCC().fit(returns)          # (T, K) → (T, K, K) sigma_t
+rcc = RCC().fit(returns)          # covariance targeting by construction
+
+from mfe.univariate import HEAVY
+heavy = HEAVY().fit(daily_returns, realized_variances)
+```
+
+## Development
+
+```bash
+uv sync --all-groups
+PYTHONPATH=src pytest tests/     # 246 tests
+mkdocs serve                     # documentation
+```
+
+## Relationship to MATLAB MFE Toolbox
+
+This package ports [bashtage/mfe-toolbox](https://github.com/bashtage/mfe-toolbox)
+to Python, fixing several bugs present in the MATLAB source (memory leaks, silent
+non-convergence, O(N²) algorithms replaced with O(N log N) Cython implementations).

mfe_toolbox-0.1.0/dev/benchmarks/bench_realized.py

@@ -0,0 +1,78 @@
+"""
+Performance benchmarks for mfe.realized on HFT-scale data.
+
+Run with:
+    cd repo_root
+    PYTHONPATH=src python dev/benchmarks/bench_realized.py
+
+Or with pytest-benchmark:
+    PYTHONPATH=src pytest dev/benchmarks/bench_realized.py --benchmark-only
+
+Target: all operations on T=1_000_000 ticks should complete in < 5s
+on a modern CPU without Cython (pure numpy). With Cython, kernel inner
+loop should be ~10x faster.
+"""
+
+import time
+
+import numpy as np
+
+from mfe.realized import (
+    realized_variance,
+    realized_bipower_variation,
+    realized_med_variance,
+    realized_kernel,
+    bns_jump_test,
+)
+from mfe.realized.covariance import realized_hayashi_yoshida
+
+
+def _make_returns(T: int, seed: int = 0) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    return rng.standard_normal(T) * 0.001
+
+
+def _make_tick_prices(T: int, seed: int = 0):
+    rng = np.random.default_rng(seed)
+    price = np.exp(np.cumsum(rng.standard_normal(T) * 0.001))
+    time_ = np.sort(rng.uniform(0, 23400, T))
+    return price, time_
+
+
+def bench(label: str, fn, *args, n_runs: int = 3):
+    times = []
+    for _ in range(n_runs):
+        t0 = time.perf_counter()
+        fn(*args)
+        times.append(time.perf_counter() - t0)
+    mean_ms = np.mean(times) * 1000
+    print(f"  {label:<40s} {mean_ms:8.1f} ms  (n={n_runs})")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("mfe.realized benchmarks")
+    print("=" * 60)
+
+    for T in [10_000, 100_000, 500_000]:
+        print(f"\nT = {T:,} returns")
+        r = _make_returns(T)
+
+        bench("realized_variance", realized_variance, r)
+        bench("realized_bipower_variation (skip=0)", realized_bipower_variation, r, 0)
+        bench("realized_bipower_variation (skip=1)", realized_bipower_variation, r, 1)
+        bench("realized_med_variance", realized_med_variance, r)
+        bench("realized_kernel (auto bandwidth)", realized_kernel, r)
+        bench("bns_jump_test", bns_jump_test, r)
+
+    print(f"\nHayashi-Yoshida bivariate (non-synchronous)")
+    for T in [1_000, 5_000, 10_000]:
+        p1, t1 = _make_tick_prices(T, seed=0)
+        p2, t2 = _make_tick_prices(T, seed=1)
+        # HY is O(N1 * N2) in worst case with the current numpy impl
+        bench(f"  HY T={T:,}", realized_hayashi_yoshida, [p1, p2], [t1, t2], n_runs=2)
+
+    print()
+    print("NOTE: Cython uses event-sweep with swap-remove open-list.")
+    print("      Complexity: O((N1+N2)*log(N1+N2)) sort + O((N1+N2)*k) sweep")
+    print("      where k = avg simultaneous open intervals (typically O(1) for HFT data).")

mfe_toolbox-0.1.0/docs/api/bootstrap.md

@@ -0,0 +1,5 @@
+# mfe.bootstrap
+
+::: mfe.bootstrap
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/crosssection.md

@@ -0,0 +1,5 @@
+# mfe.crosssection
+
+::: mfe.crosssection
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/distributions.md

@@ -0,0 +1,5 @@
+# mfe.distributions
+
+::: mfe.distributions
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/multivariate.md

@@ -0,0 +1,5 @@
+# mfe.multivariate
+
+::: mfe.multivariate
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/realized.md

@@ -0,0 +1,5 @@
+# mfe.realized
+
+::: mfe.realized
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/tests_stat.md

@@ -0,0 +1,5 @@
+# mfe.tests_stat
+
+::: mfe.tests_stat
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/timeseries.md

@@ -0,0 +1,5 @@
+# mfe.timeseries
+
+::: mfe.timeseries
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/univariate.md

@@ -0,0 +1,5 @@
+# mfe.univariate
+
+::: mfe.univariate
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/api/utils.md

@@ -0,0 +1,5 @@
+# mfe.utils
+
+::: mfe.utils
+    options:
+      show_submodules: true

mfe_toolbox-0.1.0/docs/changelog.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## 0.1.0 (2026-09)
+
+Initial release — Python port of the Oxford MFE Toolbox.
+
+### mfe.realized
+- `realized_variance`, `realized_bipower_variation` (skip-k), `realized_med_variance`, `realized_min_variance`, `realized_preaveraged_variance`, `realized_semivariance`, `realized_quantile_variance`
+- `realized_kernel` (Parzen/Bartlett/Tukey-Hanning/Cubic/Epanechnikov/FlatTop, auto-bandwidth)
+- `tsrv`, `msrv` — Two-Scale and Multi-Scale Realized Variance
+- `realized_covariance`, `realized_correlation`, `realized_hayashi_yoshida`, `realized_covariance_refresh_time`
+- `realized_multivariate_kernel` — PSD-guaranteed (K,K) multivariate realized kernel
+- `realized_range`, `realized_range_from_ticks`
+- `bns_jump_test`, `estimate_noise_variance`, `realized_quarticity`, `realized_tripower_quarticity`
+- `price_filter`, `returns_from_prices`, `refresh_time`
+- Cython extensions: `_autocovariance_sum`, `_bpv_sum`, `_medvar_triplets`, `_hy_sweep`, `_refresh_time_indices`
+
+### mfe.multivariate
+- `DCC` (Engle 2002) with cDCC and DECO variants
+- `CCC` (Bollerslev 1990)
+- `BEKK` scalar and diagonal (Engle & Kroner 1995)
+- `OGARCH` (Alexander 2001)
+- `GOGARCH` ICA and moments rotation (van der Weide 2002)
+- `RCC` symmetric and Cholesky rotation (Noureldin, Shephard & Sheppard 2014)
+- Cython extensions: `_dcc_q_recursion`, `_dcc_corr_loglik`, `_bekk_scalar_recursion`, `_bekk_diagonal_recursion`
+
+### mfe.univariate
+- `har_rv` — standard, MODIFIED spec, matrix intervals
+- `har_rv_j` — jump-augmented HAR
+- `har_forecast` — multi-step forecasting
+- `HEAVY` — joint model of returns + realized variance (Shephard & Sheppard 2010)
+
+### mfe.timeseries
+- `vectorar` — VAR(P) with 4 VCV options (homo/het × corr/uncorr)
+- `grangercause` — Granger causality LR/LM/Wald with robust VCV
+- `impulse_response` — IRF with delta-method standard errors
+- `beveridge_nelson` — AR and state-space methods, auto order selection
+
+### mfe.bootstrap
+- `wild_bootstrap_rv`, `wild_bootstrap_test` — Rademacher/Mammen/Normal multipliers
+- `spa_test` — Hansen (2005) SPA: consistent, upper (Reality Check), lower p-values
+- `step_m` — Romano & Wolf (2005) stepdown FWER control
+
+### mfe.crosssection
+- `ols`, `olsnw` — OLS with White / Newey-West SEs
+- `fama_macbeth` — Fama-MacBeth with Shanken correction
+- `rolling_betas`, `pca`
+
+### mfe.tests_stat
+- `ljung_box` — Ljung-Box Q statistic
+- `lm_test` — HAC-robust LM serial correlation test (MFE lmtest1.m)
+- `arch_lm` — Engle (1982) ARCH-LM test (LM form + F form)
+- `mincer_zarnowitz` — MZ regression forecast evaluation
+- `diebold_mariano` — DM test (MSE/MAE/QLIKE loss)
+
+### mfe.distributions
+- `skewt_logpdf`, `skewt_ppf`, `skewt_score` — Hansen (1994) Skew-t with analytic gradient
+- `ged_logpdf`, `ged_ppf`, `ged_score` — Generalized Error Distribution
+- `mvnorm_loglik`, `mvnorm_loglik_t`, `mahalanobis`, `standardize_mvn`
+
+### mfe.utils
+- `lag_matrix`, `har_lag_matrix`
+- `sandwich`, `newey_west`
+- Type aliases: `FloatArray`, `IntArray`, etc.
+
+### Bugs fixed vs. MATLAB source
+- `gogarch.m`: memory leak via closure over `volData` inside `fmincon` loop → eliminated
+- All univariate estimators: `MFEToolbox:Convergence` silently used bad params → `ConvergenceWarning`
+- `realized_kernel.m`: parameter validation mixed into hot path → separated
+- `realized_bipower_variation.m`: inconsistent `skip` default → standardised to 0
+- `dcc.m`: `Q_bar` recomputed inside likelihood → pre-computed
+- No sandwich VCV in MATLAB multivariate → standard in all `mfe` estimators
+- `realized_hayashi_yoshida.m` TODO for K>2 → implemented for general K
+- HY Cython: `sort_key = time * 4 + type` loses bits for large timestamps → `np.lexsort`

mfe_toolbox-0.1.0/docs/guide/bootstrap.md

@@ -0,0 +1,34 @@
+# Bootstrap & Multiple Testing
+
+## Wild bootstrap (realized volatility)
+
+```python
+from mfe.bootstrap import wild_bootstrap_rv, wild_bootstrap_test
+
+# 95% CI for a realized volatility statistic
+result = wild_bootstrap_rv(r, n_replications=999, multiplier="rademacher")
+print(f"Statistic: {result.statistic:.6f}")
+print(f"95% CI: [{result.ci_lower:.6f}, {result.ci_upper:.6f}]")
+```
+
+## SPA test (Superior Predictive Ability)
+
+```python
+from mfe.bootstrap import spa_test
+
+# loss_benchmark: (T,) loss for benchmark model
+# loss_models:    (T, M) losses for M alternatives  (lower = better)
+res = spa_test(loss_benchmark, loss_models, n_bootstrap=999)
+print(f"SPA p-value (consistent): {res.p_value_consistent:.3f}")
+print(f"Reality Check p-value:    {res.p_value_upper:.3f}")
+```
+
+## StepM (Romano-Wolf FWER control)
+
+```python
+from mfe.bootstrap import step_m
+
+res = step_m(loss_benchmark, loss_models, alpha=0.05, n_bootstrap=999)
+print(f"Models beating benchmark: {res.rejected}")  # indices, 0-based
+print(f"FWER-adjusted p-values:   {res.p_values_adjusted.round(3)}")
+```

mfe_toolbox-0.1.0/docs/guide/comparison.md

@@ -0,0 +1,77 @@
+# mfe vs. arch vs. statsmodels
+
+## Decision guide
+
+| Task | Use |
+|---|---|
+| GARCH / EGARCH / TARCH / APARCH estimation | [`arch`](https://arch.readthedocs.io) |
+| FIGARCH, HARCH, MIDAS-GARCH | `arch` |
+| Unit root tests (ADF, PP, KPSS, DFGLS) | `arch.unitroot` |
+| Cointegration (Johansen, Engle-Granger) | `statsmodels` |
+| ARMA/ARMAX estimation | `statsmodels` |
+| VAR with robust VCV options | **`mfe`** |
+| Granger causality with heteroskedastic VCV | **`mfe`** |
+| Impulse response functions under heteroskedasticity | **`mfe`** |
+| Realized variance / BPV / MedRV | **`mfe`** |
+| Realized kernel (noise-robust) | **`mfe`** |
+| TSRV / MSRV (two-scale noise correction) | **`mfe`** |
+| Hayashi-Yoshida non-synchronous covariance | **`mfe`** |
+| Multivariate realized kernel (PSD guaranteed) | **`mfe`** |
+| DCC-GARCH | **`mfe`** |
+| BEKK-GARCH | **`mfe`** |
+| CCC-GARCH | **`mfe`** |
+| GO-GARCH / O-GARCH | **`mfe`** |
+| RCC (Rotated Conditional Correlation) | **`mfe`** |
+| HAR-RV model | **`mfe`** |
+| HEAVY model (realized variance in mean equation) | **`mfe`** |
+| Beveridge-Nelson decomposition | **`mfe`** |
+| SPA test / StepM FWER | **`mfe`** |
+| Wild bootstrap for realized volatility | **`mfe`** |
+| Fama-MacBeth regression | **`mfe`** |
+| OLS with White / Newey-West SEs | **`mfe`** (thin wrapper) or `statsmodels` |
+| PCA with financial conventions | **`mfe`** |
+| Hansen Skew-t / GED distributions (standalone) | **`mfe`** |
+
+## Key API differences
+
+### arch (univariate, correct home for GARCH)
+
+```python
+from arch import arch_model
+am = arch_model(returns, vol="Garch", p=1, q=1)
+res = am.fit()
+```
+
+### mfe (multivariate, realized, everything arch doesn't cover)
+
+```python
+from mfe.multivariate import DCC
+from mfe.realized import realized_kernel
+
+dcc = DCC().fit(returns)          # (T, K) → (T, K, K) sigma_t
+rk = realized_kernel(r)           # noise-robust RV
+```
+
+### statsmodels (ARIMA, VAR basic, cointegration)
+
+```python
+from statsmodels.tsa.api import VAR
+mod = VAR(data)
+res = mod.fit(maxlags=2)
+# → no robust VCV, no GC test with het-robust options
+```
+
+```python
+from mfe.timeseries import vectorar, grangercause
+res = vectorar(data, lags=2, het=True)          # White-robust VCV
+gc  = grangercause(data, lags=2, method="wald") # Wald test with robust VCV
+```
+
+## What mfe does NOT replace
+
+- `arch` for any univariate GARCH estimation — we use `arch` internally for
+  the first step of DCC/RCC/CCC.
+- `statsmodels` for ARIMA, SARIMA, SARIMAX estimation.
+- `scipy.signal` for filtering.
+- `sklearn.decomposition.PCA` for general-purpose PCA (our PCA is tailored to
+  financial returns with covariance convention and factor interpretation tools).

mfe_toolbox-0.1.0/docs/guide/crosssection.md

@@ -0,0 +1,41 @@
+# Cross-Section
+
+## OLS and OLSNW
+
+```python
+from mfe.crosssection import ols, olsnw
+
+# Y = alpha + X beta + eps
+res = ols(y, X)                      # White-robust SEs
+res_nw = olsnw(y, X, nw_lags=6)     # Newey-West HAC SEs
+
+print(res.params, res.std_errors, res.r_squared)
+```
+
+## Fama-MacBeth
+
+```python
+from mfe.crosssection import fama_macbeth, rolling_betas
+
+# Pass 1: rolling betas
+betas = rolling_betas(returns, factors, window=60)   # (N, K)
+
+# Pass 2: FM
+fm = fama_macbeth(returns, betas, include_intercept=True, shanken_correction=True)
+print(fm.lambda_mean)        # (K+1,) mean risk premia
+print(fm.t_stats_shanken)    # Shanken-corrected t-stats
+print(fm.r_squared_mean)     # mean cross-sectional R²
+```
+
+## PCA
+
+```python
+from mfe.crosssection import pca
+
+res = pca(returns, n_components=3)
+print(res.explained_variance)          # proportion per component
+print(res.cumulative_variance)         # cumulative
+factors = res.factors                  # (T, 3) principal components
+loadings = res.loadings                # (K, 3) factor loadings
+recon = res.reconstruct(k_c=3)        # (T, K) reconstruction from 3 PCs
+```