quantlite 0.7.0__tar.gz → 0.9.0__tar.gz

{quantlite-0.7.0/src/quantlite.egg-info → quantlite-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantlite
-Version: 0.7.0
+Version: 0.9.0
 Summary: A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite.
 Author-email: Prasant Sudhakaran <code@prasant.net>
 License: MIT License
@@ -713,6 +713,167 @@ Same Stephen Few theme, same muted palette, but with hover info, zoom, and nativ
 | `quantlite.crypto.stablecoin` | Depeg probability, peg deviation tracking, recovery time, reserve risk scoring |
 | `quantlite.crypto.exchange` | Exchange concentration (HHI), wallet risk, proof of reserves, liquidity risk, slippage |
 | `quantlite.crypto.onchain` | Wallet exposure, TVL tracking, DeFi dependency graphs, smart contract risk scoring |
+| `quantlite.factors.classical` | Fama-French three/five-factor, Carhart four-factor, factor attribution, factor summary |
+| `quantlite.factors.custom` | CustomFactor, significance testing, correlation matrix, factor portfolios, decay analysis |
+| `quantlite.factors.tail_risk` | CVaR decomposition, regime factor exposure, crowding score, tail factor beta |
+| `quantlite.simulation.evt_simulation` | EVT tail simulation, parametric tail simulation, historical bootstrap EVT, scenario fan |
+| `quantlite.simulation.copula_mc` | Gaussian copula MC, t-copula MC, stress correlation MC, joint tail probability |
+| `quantlite.simulation.regime_mc` | Regime-switching simulation, stress test scenarios, reverse stress test, simulation summary |
+
+## v0.9: Fat-Tail Monte Carlo
+
+Three simulation families that go beyond naive Monte Carlo. Standard MC assumes returns are Gaussian and independent. QuantLite's fat-tail MC uses EVT for realistic tails, copulas for joint dependence, and regime switching for structural breaks.
+
+### EVT Tail Simulation
+
+Generate scenarios with GPD-fitted tails that respect the true shape of financial returns.
+
+```python
+import numpy as np
+from quantlite.simulation import evt_tail_simulation, scenario_fan
+
+rng = np.random.default_rng(42)
+returns = np.concatenate([
+    rng.normal(0.0003, 0.01, 900),
+    rng.standard_t(3, 100) * 0.03,
+])
+
+# EVT-based scenario generation
+simulated = evt_tail_simulation(returns, n_scenarios=20000, seed=42)
+print(f"Historical 1st pctl: {np.percentile(returns, 1):.4f}")
+print(f"Simulated 1st pctl:  {np.percentile(simulated, 1):.4f}")
+
+# Fan chart across multiple horizons
+fan = scenario_fan(returns, horizons=[1, 5, 21, 63, 252])
+for h in fan["horizons"]:
+    p5, p95 = fan["fans"][h]["5"], fan["fans"][h]["95"]
+    print(f"  {h:>3}d: [{p5:+.2%}, {p95:+.2%}]")
+```
+
+![EVT Tail Simulation](docs/images/evt_tail_simulation.png)
+
+![Scenario Fan](docs/images/scenario_fan.png)
+
+### Copula Monte Carlo
+
+Multivariate simulation that preserves fat-tailed marginals and captures tail dependence.
+
+```python
+import numpy as np
+from quantlite.simulation import t_copula_mc, joint_tail_probability
+
+rng = np.random.default_rng(42)
+fund_a = np.concatenate([rng.normal(0.0005, 0.012, 900), rng.standard_t(3, 100) * 0.03])
+fund_b = np.concatenate([rng.normal(0.0003, 0.015, 900), rng.standard_t(4, 100) * 0.025])
+corr = np.array([[1.0, 0.6], [0.6, 1.0]])
+
+# t-copula captures tail dependence that Gaussian copula misses
+simulated = t_copula_mc([fund_a, fund_b], corr, df=4, n_scenarios=50000)
+
+result = joint_tail_probability(simulated, thresholds=[-0.03, -0.03])
+print(f"Joint crash probability: {result['joint_probability']:.4f}")
+print(f"Marginal probabilities:  {result['marginal_probabilities']}")
+```
+
+![Copula Comparison](docs/images/copula_comparison.png)
+
+![Stressed Correlations](docs/images/stressed_correlations.png)
+
+### Regime-Switching Simulation
+
+Paths that switch between calm, volatile, and crisis regimes via a Markov chain.
+
+```python
+import numpy as np
+from quantlite.simulation import (
+    regime_switching_simulation,
+    reverse_stress_test,
+    simulation_summary,
+)
+
+regimes = [
+    {"mu": 0.0004, "sigma": 0.008},   # Calm
+    {"mu": 0.0001, "sigma": 0.020},   # Volatile
+    {"mu": -0.002, "sigma": 0.035},   # Crisis
+]
+transition = np.array([
+    [0.95, 0.04, 0.01],
+    [0.10, 0.80, 0.10],
+    [0.05, 0.15, 0.80],
+])
+
+sim = regime_switching_simulation(regimes, transition, n_steps=252, n_scenarios=5000)
+stats = simulation_summary(sim["returns"])
+print(f"VaR 95%: {stats['var']['95%']:.2%}")
+print(f"CVaR 95%: {stats['cvar']['95%']:.2%}")
+print(f"P(loss > 20%): {stats['probability_of_ruin']['20%']:.2%}")
+```
+
+![Regime Simulation](docs/images/regime_simulation.png)
+
+![Reverse Stress Test](docs/images/reverse_stress_test.png)
+
+See [docs/simulation_evt.md](docs/simulation_evt.md), [docs/simulation_copula.md](docs/simulation_copula.md), and [docs/simulation_regime.md](docs/simulation_regime.md) for the full API reference.
+
+## v0.8: Factor Models
+
+Three modules for comprehensive factor analysis: classical academic models, custom factor tools, and tail-risk-aware factor decomposition.
+
+### Classical Factor Models
+
+Decompose returns into systematic factor exposures and genuine alpha.
+
+```python
+from quantlite.factors import fama_french_three, factor_summary
+
+# Fama-French three-factor regression
+result = fama_french_three(fund_returns, market, smb, hml)
+print(f"Alpha: {result['alpha']:.5f} (t={result['t_stats']['alpha']:.2f})")
+print(f"Market beta: {result['betas']['market']:.3f}")
+print(f"R-squared: {result['r_squared']:.3f}")
+```
+
+![Factor Betas](docs/images/factor_betas.png)
+
+### Custom Factor Tools
+
+Build, test, and analyse proprietary factors.
+
+```python
+from quantlite.factors import CustomFactor, factor_portfolio, factor_decay
+
+# Test factor decay
+decay = factor_decay(returns, momentum_signal, max_lag=20)
+print(f"Half-life: {decay['half_life']:.1f} periods")
+
+# Build long-short portfolios
+result = factor_portfolio(stock_returns, factor_values, n_quantiles=5)
+print(f"Long-short spread: {result['spread'] * 252:.2%} annualised")
+```
+
+![Factor Quintiles](docs/images/factor_quintiles.png)
+
+### Tail Risk Factor Analysis
+
+Understand how factor exposures behave in the tails and across regimes.
+
+```python
+from quantlite.factors import tail_factor_beta, factor_crowding_score
+
+# Tail betas: how exposures amplify in crises
+result = tail_factor_beta(returns, [market, value], ["Market", "Value"])
+for name in ["Market", "Value"]:
+    print(f"{name}: full={result['full_betas'][name]:.2f}, "
+          f"tail={result['tail_betas'][name]:.2f}")
+
+# Factor crowding detection
+crowd = factor_crowding_score([value_rets, momentum_rets])
+print(f"Crowding score: {crowd['current_score']:.3f}")
+```
+
+![Factor Crowding](docs/images/factor_crowding.png)
+
+See [docs/factors_classical.md](docs/factors_classical.md), [docs/factors_custom.md](docs/factors_custom.md), and [docs/factors_tail_risk.md](docs/factors_tail_risk.md) for the full API reference.
 
 ## v0.4: The Taleb Stack
 

{quantlite-0.7.0 → quantlite-0.9.0}/README.md

@@ -632,6 +632,167 @@ Same Stephen Few theme, same muted palette, but with hover info, zoom, and nativ
 | `quantlite.crypto.stablecoin` | Depeg probability, peg deviation tracking, recovery time, reserve risk scoring |
 | `quantlite.crypto.exchange` | Exchange concentration (HHI), wallet risk, proof of reserves, liquidity risk, slippage |
 | `quantlite.crypto.onchain` | Wallet exposure, TVL tracking, DeFi dependency graphs, smart contract risk scoring |
+| `quantlite.factors.classical` | Fama-French three/five-factor, Carhart four-factor, factor attribution, factor summary |
+| `quantlite.factors.custom` | CustomFactor, significance testing, correlation matrix, factor portfolios, decay analysis |
+| `quantlite.factors.tail_risk` | CVaR decomposition, regime factor exposure, crowding score, tail factor beta |
+| `quantlite.simulation.evt_simulation` | EVT tail simulation, parametric tail simulation, historical bootstrap EVT, scenario fan |
+| `quantlite.simulation.copula_mc` | Gaussian copula MC, t-copula MC, stress correlation MC, joint tail probability |
+| `quantlite.simulation.regime_mc` | Regime-switching simulation, stress test scenarios, reverse stress test, simulation summary |
+
+## v0.9: Fat-Tail Monte Carlo
+
+Three simulation families that go beyond naive Monte Carlo. Standard MC assumes returns are Gaussian and independent. QuantLite's fat-tail MC uses EVT for realistic tails, copulas for joint dependence, and regime switching for structural breaks.
+
+### EVT Tail Simulation
+
+Generate scenarios with GPD-fitted tails that respect the true shape of financial returns.
+
+```python
+import numpy as np
+from quantlite.simulation import evt_tail_simulation, scenario_fan
+
+rng = np.random.default_rng(42)
+returns = np.concatenate([
+    rng.normal(0.0003, 0.01, 900),
+    rng.standard_t(3, 100) * 0.03,
+])
+
+# EVT-based scenario generation
+simulated = evt_tail_simulation(returns, n_scenarios=20000, seed=42)
+print(f"Historical 1st pctl: {np.percentile(returns, 1):.4f}")
+print(f"Simulated 1st pctl:  {np.percentile(simulated, 1):.4f}")
+
+# Fan chart across multiple horizons
+fan = scenario_fan(returns, horizons=[1, 5, 21, 63, 252])
+for h in fan["horizons"]:
+    p5, p95 = fan["fans"][h]["5"], fan["fans"][h]["95"]
+    print(f"  {h:>3}d: [{p5:+.2%}, {p95:+.2%}]")
+```
+
+![EVT Tail Simulation](docs/images/evt_tail_simulation.png)
+
+![Scenario Fan](docs/images/scenario_fan.png)
+
+### Copula Monte Carlo
+
+Multivariate simulation that preserves fat-tailed marginals and captures tail dependence.
+
+```python
+import numpy as np
+from quantlite.simulation import t_copula_mc, joint_tail_probability
+
+rng = np.random.default_rng(42)
+fund_a = np.concatenate([rng.normal(0.0005, 0.012, 900), rng.standard_t(3, 100) * 0.03])
+fund_b = np.concatenate([rng.normal(0.0003, 0.015, 900), rng.standard_t(4, 100) * 0.025])
+corr = np.array([[1.0, 0.6], [0.6, 1.0]])
+
+# t-copula captures tail dependence that Gaussian copula misses
+simulated = t_copula_mc([fund_a, fund_b], corr, df=4, n_scenarios=50000)
+
+result = joint_tail_probability(simulated, thresholds=[-0.03, -0.03])
+print(f"Joint crash probability: {result['joint_probability']:.4f}")
+print(f"Marginal probabilities:  {result['marginal_probabilities']}")
+```
+
+![Copula Comparison](docs/images/copula_comparison.png)
+
+![Stressed Correlations](docs/images/stressed_correlations.png)
+
+### Regime-Switching Simulation
+
+Paths that switch between calm, volatile, and crisis regimes via a Markov chain.
+
+```python
+import numpy as np
+from quantlite.simulation import (
+    regime_switching_simulation,
+    reverse_stress_test,
+    simulation_summary,
+)
+
+regimes = [
+    {"mu": 0.0004, "sigma": 0.008},   # Calm
+    {"mu": 0.0001, "sigma": 0.020},   # Volatile
+    {"mu": -0.002, "sigma": 0.035},   # Crisis
+]
+transition = np.array([
+    [0.95, 0.04, 0.01],
+    [0.10, 0.80, 0.10],
+    [0.05, 0.15, 0.80],
+])
+
+sim = regime_switching_simulation(regimes, transition, n_steps=252, n_scenarios=5000)
+stats = simulation_summary(sim["returns"])
+print(f"VaR 95%: {stats['var']['95%']:.2%}")
+print(f"CVaR 95%: {stats['cvar']['95%']:.2%}")
+print(f"P(loss > 20%): {stats['probability_of_ruin']['20%']:.2%}")
+```
+
+![Regime Simulation](docs/images/regime_simulation.png)
+
+![Reverse Stress Test](docs/images/reverse_stress_test.png)
+
+See [docs/simulation_evt.md](docs/simulation_evt.md), [docs/simulation_copula.md](docs/simulation_copula.md), and [docs/simulation_regime.md](docs/simulation_regime.md) for the full API reference.
+
+## v0.8: Factor Models
+
+Three modules for comprehensive factor analysis: classical academic models, custom factor tools, and tail-risk-aware factor decomposition.
+
+### Classical Factor Models
+
+Decompose returns into systematic factor exposures and genuine alpha.
+
+```python
+from quantlite.factors import fama_french_three, factor_summary
+
+# Fama-French three-factor regression
+result = fama_french_three(fund_returns, market, smb, hml)
+print(f"Alpha: {result['alpha']:.5f} (t={result['t_stats']['alpha']:.2f})")
+print(f"Market beta: {result['betas']['market']:.3f}")
+print(f"R-squared: {result['r_squared']:.3f}")
+```
+
+![Factor Betas](docs/images/factor_betas.png)
+
+### Custom Factor Tools
+
+Build, test, and analyse proprietary factors.
+
+```python
+from quantlite.factors import CustomFactor, factor_portfolio, factor_decay
+
+# Test factor decay
+decay = factor_decay(returns, momentum_signal, max_lag=20)
+print(f"Half-life: {decay['half_life']:.1f} periods")
+
+# Build long-short portfolios
+result = factor_portfolio(stock_returns, factor_values, n_quantiles=5)
+print(f"Long-short spread: {result['spread'] * 252:.2%} annualised")
+```
+
+![Factor Quintiles](docs/images/factor_quintiles.png)
+
+### Tail Risk Factor Analysis
+
+Understand how factor exposures behave in the tails and across regimes.
+
+```python
+from quantlite.factors import tail_factor_beta, factor_crowding_score
+
+# Tail betas: how exposures amplify in crises
+result = tail_factor_beta(returns, [market, value], ["Market", "Value"])
+for name in ["Market", "Value"]:
+    print(f"{name}: full={result['full_betas'][name]:.2f}, "
+          f"tail={result['tail_betas'][name]:.2f}")
+
+# Factor crowding detection
+crowd = factor_crowding_score([value_rets, momentum_rets])
+print(f"Crowding score: {crowd['current_score']:.3f}")
+```
+
+![Factor Crowding](docs/images/factor_crowding.png)
+
+See [docs/factors_classical.md](docs/factors_classical.md), [docs/factors_custom.md](docs/factors_custom.md), and [docs/factors_tail_risk.md](docs/factors_tail_risk.md) for the full API reference.
 
 ## v0.4: The Taleb Stack
 

{quantlite-0.7.0 → quantlite-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantlite"
-version = "0.7.0"
+version = "0.9.0"
 description = "A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite."
 requires-python = ">=3.9"
 license = { file = "LICENSE" }
@@ -73,3 +73,6 @@ python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{quantlite-0.7.0 → quantlite-0.9.0}/src/quantlite/__init__.py

@@ -77,6 +77,8 @@ __all__ = [
     "diversification",
     # Crypto-native risk
     "crypto",
+    # Fat-tail Monte Carlo simulation
+    "simulation",
 ]
 
 from . import (  # noqa: E402
@@ -90,4 +92,5 @@ from . import (  # noqa: E402
     overfit,
     resample,
     scenarios,
+    simulation,
 )

quantlite-0.9.0/src/quantlite/factors/__init__.py

@@ -0,0 +1,43 @@
+"""Factor models: classical, custom, and tail risk factor analysis.
+
+Provides tools for multi-factor attribution, custom factor construction,
+factor significance testing, and tail-risk-aware factor decomposition.
+"""
+
+from quantlite.factors.classical import (
+    carhart_four,
+    factor_attribution,
+    factor_summary,
+    fama_french_five,
+    fama_french_three,
+)
+from quantlite.factors.custom import (
+    CustomFactor,
+    factor_correlation_matrix,
+    factor_decay,
+    factor_portfolio,
+    test_factor_significance,
+)
+from quantlite.factors.tail_risk import (
+    factor_crowding_score,
+    factor_cvar_decomposition,
+    regime_factor_exposure,
+    tail_factor_beta,
+)
+
+__all__ = [
+    "fama_french_three",
+    "fama_french_five",
+    "carhart_four",
+    "factor_attribution",
+    "factor_summary",
+    "CustomFactor",
+    "test_factor_significance",
+    "factor_correlation_matrix",
+    "factor_portfolio",
+    "factor_decay",
+    "factor_cvar_decomposition",
+    "regime_factor_exposure",
+    "factor_crowding_score",
+    "tail_factor_beta",
+]