riskvalidation 0.8.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- riskvalidation/__init__.py +30 -0
- riskvalidation/aggregation/__init__.py +11 -0
- riskvalidation/aggregation/band.py +151 -0
- riskvalidation/aggregation/bounds.py +191 -0
- riskvalidation/aggregation/copulas.py +241 -0
- riskvalidation/aggregation/model_risk.py +133 -0
- riskvalidation/aggregation/simple.py +147 -0
- riskvalidation/ccr/__init__.py +13 -0
- riskvalidation/ccr/collateral.py +175 -0
- riskvalidation/ccr/cva.py +193 -0
- riskvalidation/ccr/exposure.py +192 -0
- riskvalidation/ccr/hw1f.py +426 -0
- riskvalidation/ccr/swaps.py +172 -0
- riskvalidation/core/__init__.py +1 -0
- riskvalidation/core/build.py +57 -0
- riskvalidation/core/hashing.py +48 -0
- riskvalidation/core/policy.py +130 -0
- riskvalidation/core/registry.py +65 -0
- riskvalidation/core/result.py +117 -0
- riskvalidation/core/suite.py +78 -0
- riskvalidation/engines/__init__.py +2 -0
- riskvalidation/engines/low_default.py +170 -0
- riskvalidation/engines/pd_curve.py +529 -0
- riskvalidation/engines/vasicek.py +72 -0
- riskvalidation/fairness/__init__.py +10 -0
- riskvalidation/fairness/_checks.py +115 -0
- riskvalidation/fairness/conditional.py +201 -0
- riskvalidation/fairness/inference.py +64 -0
- riskvalidation/fairness/metrics.py +261 -0
- riskvalidation/fairness/plants.py +240 -0
- riskvalidation/fairness/policy.py +97 -0
- riskvalidation/fairness/replication.py +39 -0
- riskvalidation/fairness/situation.py +307 -0
- riskvalidation/generators/__init__.py +68 -0
- riskvalidation/generators/_base.py +145 -0
- riskvalidation/generators/counts.py +232 -0
- riskvalidation/generators/drift.py +107 -0
- riskvalidation/generators/framingham.py +124 -0
- riskvalidation/generators/paths.py +349 -0
- riskvalidation/generators/ratings.py +186 -0
- riskvalidation/generators/scores.py +347 -0
- riskvalidation/harness/__init__.py +46 -0
- riskvalidation/harness/exact.py +137 -0
- riskvalidation/harness/performance.py +74 -0
- riskvalidation/harness/rates.py +103 -0
- riskvalidation/harness/run.py +197 -0
- riskvalidation/irrbb/__init__.py +9 -0
- riskvalidation/irrbb/behavioural.py +206 -0
- riskvalidation/irrbb/curves.py +286 -0
- riskvalidation/irrbb/eve_nii.py +245 -0
- riskvalidation/irrbb/shocks.py +171 -0
- riskvalidation/irrbb/simulation.py +203 -0
- riskvalidation/irrbb/slotting.py +184 -0
- riskvalidation/lgd_ead/__init__.py +8 -0
- riskvalidation/lgd_ead/_checks.py +50 -0
- riskvalidation/lgd_ead/ccf.py +228 -0
- riskvalidation/lgd_ead/downturn.py +64 -0
- riskvalidation/lgd_ead/floors.py +114 -0
- riskvalidation/lgd_ead/lgd_models.py +297 -0
- riskvalidation/lgd_ead/workout.py +162 -0
- riskvalidation/liquidity/__init__.py +9 -0
- riskvalidation/liquidity/_checks.py +78 -0
- riskvalidation/liquidity/cbc.py +158 -0
- riskvalidation/liquidity/deposits.py +151 -0
- riskvalidation/liquidity/ladder.py +119 -0
- riskvalidation/liquidity/reverse.py +141 -0
- riskvalidation/liquidity/runoff.py +220 -0
- riskvalidation/liquidity/scenarios.py +272 -0
- riskvalidation/market/__init__.py +8 -0
- riskvalidation/market/caviar.py +239 -0
- riskvalidation/market/conventions.py +83 -0
- riskvalidation/market/evt.py +111 -0
- riskvalidation/market/frtb.py +175 -0
- riskvalidation/market/garch.py +204 -0
- riskvalidation/market/gas_fz.py +219 -0
- riskvalidation/market/historical.py +96 -0
- riskvalidation/market/parametric.py +78 -0
- riskvalidation/market/scoring.py +145 -0
- riskvalidation/ml/__init__.py +11 -0
- riskvalidation/ml/_checks.py +67 -0
- riskvalidation/ml/_logistic.py +82 -0
- riskvalidation/ml/cbpe.py +91 -0
- riskvalidation/ml/challenger.py +73 -0
- riskvalidation/ml/conformal.py +116 -0
- riskvalidation/ml/dataquality.py +130 -0
- riskvalidation/ml/effects.py +67 -0
- riskvalidation/ml/explanations.py +125 -0
- riskvalidation/ml/generalisation.py +79 -0
- riskvalidation/ml/leakage.py +99 -0
- riskvalidation/ml/plants.py +425 -0
- riskvalidation/ml/policy.py +182 -0
- riskvalidation/ml/robustness.py +286 -0
- riskvalidation/ml/seeds.py +106 -0
- riskvalidation/oprisk/__init__.py +18 -0
- riskvalidation/oprisk/_checks.py +60 -0
- riskvalidation/oprisk/aggregate.py +375 -0
- riskvalidation/oprisk/distributions.py +758 -0
- riskvalidation/oprisk/scenarios.py +342 -0
- riskvalidation/oprisk/sla.py +80 -0
- riskvalidation/oprisk/sma.py +169 -0
- riskvalidation/policies/__init__.py +4 -0
- riskvalidation/policies/default.json +273 -0
- riskvalidation/portfolio/__init__.py +16 -0
- riskvalidation/portfolio/asrf_fit.py +283 -0
- riskvalidation/portfolio/copula.py +129 -0
- riskvalidation/portfolio/creditrisk_plus.py +232 -0
- riskvalidation/portfolio/euler.py +126 -0
- riskvalidation/portfolio/granularity.py +135 -0
- riskvalidation/portfolio/importance.py +277 -0
- riskvalidation/portfolio/portfolio.py +309 -0
- riskvalidation/provisions/__init__.py +8 -0
- riskvalidation/provisions/_checks.py +100 -0
- riskvalidation/provisions/ecl.py +233 -0
- riskvalidation/provisions/local_cl.py +360 -0
- riskvalidation/provisions/local_es.py +157 -0
- riskvalidation/provisions/overlays.py +102 -0
- riskvalidation/provisions/reconciliation.py +157 -0
- riskvalidation/provisions/staging.py +211 -0
- riskvalidation/provisions/term_structure.py +199 -0
- riskvalidation/regulatory/__init__.py +14 -0
- riskvalidation/regulatory/ba_cva.py +138 -0
- riskvalidation/regulatory/frtb.py +345 -0
- riskvalidation/regulatory/irb.py +314 -0
- riskvalidation/regulatory/lcr_nsfr.py +369 -0
- riskvalidation/regulatory/output_floor.py +45 -0
- riskvalidation/regulatory/sa_ccr.py +486 -0
- riskvalidation/regulatory/standardised.py +348 -0
- riskvalidation/stress/__init__.py +9 -0
- riskvalidation/stress/capital.py +476 -0
- riskvalidation/stress/paths.py +108 -0
- riskvalidation/stress/reverse.py +179 -0
- riskvalidation/stress/satellites.py +268 -0
- riskvalidation/stress/scenario_models.py +274 -0
- riskvalidation/transitions/__init__.py +0 -0
- riskvalidation/transitions/em.py +120 -0
- riskvalidation/transitions/embedding.py +221 -0
- riskvalidation/transitions/estimators.py +213 -0
- riskvalidation/transitions/intervals.py +306 -0
- riskvalidation/transitions/mobility.py +57 -0
- riskvalidation/transitions/ttc.py +171 -0
- riskvalidation/validation/__init__.py +103 -0
- riskvalidation/validation/_common.py +57 -0
- riskvalidation/validation/aggregation.py +425 -0
- riskvalidation/validation/calibration.py +757 -0
- riskvalidation/validation/ccr.py +530 -0
- riskvalidation/validation/discrimination.py +314 -0
- riskvalidation/validation/fairness.py +632 -0
- riskvalidation/validation/ifrs9.py +693 -0
- riskvalidation/validation/irrbb.py +389 -0
- riskvalidation/validation/lgd_ead.py +469 -0
- riskvalidation/validation/liquidity.py +647 -0
- riskvalidation/validation/market.py +807 -0
- riskvalidation/validation/ml.py +958 -0
- riskvalidation/validation/oprisk.py +357 -0
- riskvalidation/validation/portfolio.py +353 -0
- riskvalidation/validation/rating_system.py +245 -0
- riskvalidation/validation/stability.py +256 -0
- riskvalidation/validation/stress.py +552 -0
- riskvalidation/validation/transitions.py +386 -0
- riskvalidation-0.8.0.dist-info/METADATA +136 -0
- riskvalidation-0.8.0.dist-info/RECORD +164 -0
- riskvalidation-0.8.0.dist-info/WHEEL +5 -0
- riskvalidation-0.8.0.dist-info/licenses/LICENSE +21 -0
- riskvalidation-0.8.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""riskvalidation: validation tests, regulatory calculators and reference engines for financial risk models.
|
|
2
|
+
|
|
3
|
+
Every validation test returns one :class:`TestResult`; a versioned :class:`Policy` turns its statistic into a
|
|
4
|
+
traffic light; :func:`run_suite` runs a battery without stopping at the first failure. The core depends
|
|
5
|
+
only on NumPy and SciPy, so it also runs in the browser under Pyodide.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from riskvalidation import validation # noqa: E402,F401 (registers the test catalogue)
|
|
9
|
+
from riskvalidation.core.policy import Policy, Threshold, default_policy, load_policy
|
|
10
|
+
from riskvalidation.core.registry import TestSpec, catalogue
|
|
11
|
+
from riskvalidation.core.result import Light, TestResult
|
|
12
|
+
from riskvalidation.core.suite import SuiteRun, run_suite
|
|
13
|
+
|
|
14
|
+
__version__ = "0.8.0"
|
|
15
|
+
"""PEP 440 form of the display version in ``VERSION``."""
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"Light",
|
|
19
|
+
"Policy",
|
|
20
|
+
"SuiteRun",
|
|
21
|
+
"TestResult",
|
|
22
|
+
"TestSpec",
|
|
23
|
+
"Threshold",
|
|
24
|
+
"__version__",
|
|
25
|
+
"catalogue",
|
|
26
|
+
"default_policy",
|
|
27
|
+
"load_policy",
|
|
28
|
+
"run_suite",
|
|
29
|
+
"validation",
|
|
30
|
+
]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Risk aggregation: the ladder from the simple sum to the worst-case bounds, the dependence band, model risk and the
|
|
2
|
+
validation tests.
|
|
3
|
+
|
|
4
|
+
Modules are imported by path (for example ``from riskvalidation.aggregation import simple``); nothing is re-exported
|
|
5
|
+
here.
|
|
6
|
+
Capital is economic capital on the unexpected-loss basis, ``EC = VaR - EL``. The simple sum is the headline capital of
|
|
7
|
+
the
|
|
8
|
+
case; every other figure of the band is information, not capital. The engine computes and states no compliance claim:
|
|
9
|
+
thresholds and light parameters are supplied by the caller or are Contraste internal gates, not regulatory requirements.
|
|
10
|
+
The validation tests are in ``riskvalidation.validation.aggregation``. Contract: ``engine-aggregation-api`` 1.0.0.
|
|
11
|
+
"""
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
"""The dependence-uncertainty band every aggregate is shown with (dossier 05 G.3, l.366; the SDD): the lower bound,
|
|
2
|
+
the simple
|
|
3
|
+
sum, the variance-covariance, the Gaussian copula, one Student t copula per degrees-of-freedom value and the worst
|
|
4
|
+
case, on
|
|
5
|
+
the same marginals. The band is returned whole, never one diversified number.
|
|
6
|
+
|
|
7
|
+
Every row is economic capital on the unexpected-loss basis, `EC = VaR - EL` (dossier 04 l.652-653); the expected loss is
|
|
8
|
+
additive, so the simple sum of the marginal EC equals the comonotonic EC of the total. The simple sum is the headline
|
|
9
|
+
capital
|
|
10
|
+
(`status = "headline-capital"`); every other row is information, not capital (`"information-not-capital"`, dossier 05
|
|
11
|
+
l.519). A row above the headline is a true result (VaR is not subadditive, dossier 05 l.366): it is reported by
|
|
12
|
+
`validation.aggregation.diversification_sign`, never repaired and never refused here. The lower-bound row is signed:
|
|
13
|
+
the best
|
|
14
|
+
VaR less the sum of the expected losses may be negative and is reported as computed.
|
|
15
|
+
|
|
16
|
+
A marginal with an infinite-mean severity has no expected loss: the caller passes it as `ec = VaR` and `el = 0.0`, so
|
|
17
|
+
that
|
|
18
|
+
every row is built on the EC the document carries. The caller converts a marginal read at another level or horizon,
|
|
19
|
+
never the
|
|
20
|
+
engine. Contract: `engine-aggregation-api` 1.0.0, module aggregation.band.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import math
|
|
26
|
+
from collections.abc import Callable, Sequence
|
|
27
|
+
from dataclasses import dataclass
|
|
28
|
+
|
|
29
|
+
import numpy as np
|
|
30
|
+
|
|
31
|
+
from riskvalidation.aggregation.bounds import worst_var_bounds
|
|
32
|
+
from riskvalidation.aggregation.copulas import DEFAULT_CHUNK, copula_aggregate
|
|
33
|
+
from riskvalidation.aggregation.simple import _matrix, check_correlation, simple_sum, variance_covariance
|
|
34
|
+
from riskvalidation.portfolio.portfolio import check_level, float_vector
|
|
35
|
+
|
|
36
|
+
Ppf = Callable[[np.ndarray], np.ndarray]
|
|
37
|
+
METHODS = ("lower-bound", "simple-sum", "variance-covariance", "gaussian-copula", "t-copula", "worst-case")
|
|
38
|
+
HEADLINE = "headline-capital"
|
|
39
|
+
INFORMATION = "information-not-capital"
|
|
40
|
+
CAPITAL_BASIS = "economic-capital-var-less-el"
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@dataclass(frozen=True)
|
|
44
|
+
class BandRow:
|
|
45
|
+
"""One row of the band; maps onto the document row `outputs.aggregation.band[*]` (`method`, `nu`, `capital_clp_m`,
|
|
46
|
+
`diversification_factor`, `status`, `mc_se_clp_m`). `capital` is money (EC), `diversification_factor` is
|
|
47
|
+
capital / simple sum, `mc_se` the Monte Carlo standard error where the row is simulated."""
|
|
48
|
+
|
|
49
|
+
method: str
|
|
50
|
+
nu: float | None
|
|
51
|
+
capital: float
|
|
52
|
+
diversification_factor: float
|
|
53
|
+
status: str
|
|
54
|
+
mc_se: float | None
|
|
55
|
+
|
|
56
|
+
def __post_init__(self) -> None:
|
|
57
|
+
if self.method not in METHODS:
|
|
58
|
+
raise ValueError(f"method must be one of {METHODS}, got {self.method!r}")
|
|
59
|
+
if self.status != (HEADLINE if self.method == "simple-sum" else INFORMATION):
|
|
60
|
+
raise ValueError(f"status {self.status!r} does not follow method {self.method!r}")
|
|
61
|
+
if (self.nu is not None) != (self.method == "t-copula"):
|
|
62
|
+
raise ValueError("nu must be set exactly for the t-copula row")
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
@dataclass(frozen=True)
|
|
66
|
+
class Band:
|
|
67
|
+
"""The rows (lower bound, simple sum, variance-covariance, Gaussian, one t row per nu, worst case), the `headline`
|
|
68
|
+
(the
|
|
69
|
+
capital of the single simple-sum row), the horizon in years, the confidence level and the capital basis."""
|
|
70
|
+
|
|
71
|
+
rows: tuple[BandRow, ...]
|
|
72
|
+
headline: float
|
|
73
|
+
horizon_years: int
|
|
74
|
+
confidence_level: float
|
|
75
|
+
capital_basis: str
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _check_nu_set(nu_set: Sequence[float]) -> tuple[float, ...]:
|
|
79
|
+
nus = tuple(float(v) for v in nu_set)
|
|
80
|
+
if not nus:
|
|
81
|
+
raise ValueError("nu_set is empty")
|
|
82
|
+
if not all(math.isfinite(v) and v > 2.0 for v in nus):
|
|
83
|
+
raise ValueError(f"nu_set values must be finite and above 2, got {list(nu_set)}")
|
|
84
|
+
if any(b <= a for a, b in zip(nus, nus[1:], strict=False)):
|
|
85
|
+
raise ValueError(f"nu_set must be ascending and distinct, got {list(nu_set)}")
|
|
86
|
+
return nus
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
# A convention, not a derived constant: `marginal_ppf_sample` interpolates while `var_from_sample` takes the order
|
|
90
|
+
# statistic, so ec and ppf(level) - el agree only to sampling resolution; 1 % relative (absolute below 1).
|
|
91
|
+
EC_CONSISTENCY_TOLERANCE = 0.01
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def dependence_band(ppfs: Sequence[Ppf], ec: np.ndarray, el: np.ndarray, corr: np.ndarray, nu_set: Sequence[float],
|
|
95
|
+
level: float = 0.999, horizon_years: int = 1, n_draws: int = 1_000_000, seed: int = 0,
|
|
96
|
+
chunk_size: int = DEFAULT_CHUNK, bounds_n: int = 100_000, bounds_epsilon: float = 1e-3,
|
|
97
|
+
ec_consistency_tolerance: float = EC_CONSISTENCY_TOLERANCE) -> Band:
|
|
98
|
+
"""The band on the marginals `ppfs` (money quantile functions), their economic capital `ec` and expected loss `el`
|
|
99
|
+
(K,), the correlation `corr` of the copulas and the t degrees of freedom `nu_set` (above 2, ascending, distinct).
|
|
100
|
+
|
|
101
|
+
The rows: `simple_sum`, `variance_covariance`, `copula_aggregate` for the Gaussian copula and for each nu (the same
|
|
102
|
+
`seed` on every row), and `worst_var_bounds` (its `lower_range[0]` and `upper_range[1]` less the sum of `el`) for
|
|
103
|
+
the
|
|
104
|
+
lower and the worst case. One horizon and one confidence level apply to every row: `level` lies in (0, 1) and
|
|
105
|
+
`horizon_years` is a positive integer. Golden: ec (3, 4), el (0, 0), R = [[1, 0.5], [0.5, 1]] gives the simple-sum
|
|
106
|
+
row 7.0
|
|
107
|
+
and the variance-covariance row 6.0828, with lower <= 6.0828 <= worst."""
|
|
108
|
+
lv = check_level(level, "level")
|
|
109
|
+
if isinstance(horizon_years, bool) or not isinstance(horizon_years, (int, np.integer)) or horizon_years < 1:
|
|
110
|
+
raise ValueError(f"horizon_years must be a positive integer, got {horizon_years}")
|
|
111
|
+
nus = _check_nu_set(nu_set)
|
|
112
|
+
capital_ec = float_vector(ec, "ec")
|
|
113
|
+
if np.any(capital_ec < 0.0):
|
|
114
|
+
raise ValueError("ec must not contain a negative element")
|
|
115
|
+
losses = float_vector(el, "el")
|
|
116
|
+
if np.any(losses < 0.0):
|
|
117
|
+
raise ValueError("el must not contain a negative element")
|
|
118
|
+
r = _matrix(corr, "corr")
|
|
119
|
+
check_correlation(r)
|
|
120
|
+
k = capital_ec.size
|
|
121
|
+
if not (len(ppfs) == losses.size == r.shape[0] == k):
|
|
122
|
+
raise ValueError(f"ppfs, ec, el and corr must have the same length, got {len(ppfs)}, {k}, {losses.size} and "
|
|
123
|
+
f"{r.shape[0]}")
|
|
124
|
+
headline = simple_sum(capital_ec)
|
|
125
|
+
if not headline > 0.0:
|
|
126
|
+
raise ValueError("ec must have a positive sum: the diversification factors are undefined")
|
|
127
|
+
tol = float(ec_consistency_tolerance)
|
|
128
|
+
if not (math.isfinite(tol) and tol >= 0.0):
|
|
129
|
+
raise ValueError(f"ec_consistency_tolerance must be a nonnegative number, got {ec_consistency_tolerance}")
|
|
130
|
+
for idx, ppf in enumerate(ppfs):
|
|
131
|
+
implied = float(np.ravel(ppf(np.array([lv])))[0]) - float(losses[idx])
|
|
132
|
+
if not abs(float(capital_ec[idx]) - implied) <= tol * max(1.0, abs(float(capital_ec[idx]))):
|
|
133
|
+
raise ValueError(f"ec does not match the marginals: marginal {idx} has ec {float(capital_ec[idx])} but "
|
|
134
|
+
f"ppf(level) - el is {implied} (tolerance {tol})")
|
|
135
|
+
el_total = float(losses.sum())
|
|
136
|
+
bounds = worst_var_bounds(ppfs, lv, bounds_n, bounds_epsilon, seed=seed)
|
|
137
|
+
rows: list[tuple[str, float | None, float, float | None]] = [
|
|
138
|
+
("lower-bound", None, bounds.lower_range[0] - el_total, None),
|
|
139
|
+
("simple-sum", None, headline, None),
|
|
140
|
+
("variance-covariance", None, variance_covariance(capital_ec, r), None),
|
|
141
|
+
]
|
|
142
|
+
for family, nu in (("gaussian", None), *(("t", v) for v in nus)):
|
|
143
|
+
agg = copula_aggregate(ppfs, r, family, nu, el_total, lv, n_draws, seed, chunk_size)
|
|
144
|
+
rows.append(("gaussian-copula" if family == "gaussian" else "t-copula", nu, agg.ec, agg.var_se))
|
|
145
|
+
rows.append(("worst-case", None, bounds.upper_range[1] - el_total, None))
|
|
146
|
+
band_rows = tuple(
|
|
147
|
+
BandRow(method=method, nu=nu, capital=float(capital), diversification_factor=float(capital) / headline,
|
|
148
|
+
status=HEADLINE if method == "simple-sum" else INFORMATION, mc_se=se)
|
|
149
|
+
for method, nu, capital, se in rows)
|
|
150
|
+
return Band(rows=band_rows, headline=headline, horizon_years=int(horizon_years), confidence_level=lv,
|
|
151
|
+
capital_basis=CAPITAL_BASIS)
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
"""Rung 6 of the aggregation ladder: worst-case (and best-case) VaR bounds for given marginals and an unknown
|
|
2
|
+
dependence, by
|
|
3
|
+
the rearrangement algorithm of Embrechts, Puccetti and Ruschendorf, "Model uncertainty and VaR aggregation", Journal of
|
|
4
|
+
Banking and Finance 37(8), 2750-2764, 2013, doi:10.1016/j.jbankfin.2013.03.014 (accepted manuscript
|
|
5
|
+
https://people.math.ethz.ch/~embrecht/ftp/MUVaR.pdf, section 2.2, pp.8-11; transcribed in F5 of the U13 research
|
|
6
|
+
addendum).
|
|
7
|
+
|
|
8
|
+
VaR is not subadditive, so the comonotonic sum is not the worst case (dossier 05 l.366). For N x d matrices X the
|
|
9
|
+
operators
|
|
10
|
+
are s(X) = the smallest row sum and t(X) = the largest row sum. Upper VaR bound (the worst VaR, steps 1 to 7 of the
|
|
11
|
+
paper,
|
|
12
|
+
p.10): the matrices of (18), x_ij = F_j^-1(alpha + (1 - alpha)(i - 1) / N) and the same with i in place of i - 1, have
|
|
13
|
+
their
|
|
14
|
+
columns permuted at random, then each column in turn is rearranged oppositely ordered to the sum of the others, sweep
|
|
15
|
+
after
|
|
16
|
+
sweep, until s changes by less than epsilon; then s_N <= s-bar_N are the rearrangement range of the worst VaR (19).
|
|
17
|
+
The lower
|
|
18
|
+
bound (the best VaR, (20) and (21)) uses the matrices over [0, alpha], z_ij = F_j^-1(alpha (i - 1) / N), and the
|
|
19
|
+
largest row
|
|
20
|
+
sum t, which the loop minimises. No distribution function is inverted: the quantile functions are evaluated on the grid.
|
|
21
|
+
|
|
22
|
+
Where a marginal has unbounded support the last cell of the upper matrix x-bar is F_j^-1(1) = +infinity. The engine
|
|
23
|
+
keeps it
|
|
24
|
+
as +infinity (the paper's text read for F5 does not say how it treats that cell: UNVERIFIED): a row that holds it has an
|
|
25
|
+
infinite row sum, so it is never the smallest row and the smallest row sum stays finite. The lower matrices over [0,
|
|
26
|
+
alpha]
|
|
27
|
+
never reach probability 1 and are finite.
|
|
28
|
+
|
|
29
|
+
Remark 6 of the paper (p.11): there is no analytic proof that (19) and (21) hold for all starting configurations
|
|
30
|
+
(UNVERIFIED
|
|
31
|
+
as a theorem); the random permutation of step 3 is the paper's mitigation, and `converged = False` reports a run
|
|
32
|
+
stopped by
|
|
33
|
+
`max_sweeps`.
|
|
34
|
+
|
|
35
|
+
Randomness: `numpy.random.Generator(numpy.random.PCG64(seed))`; the result is reproducible for a seed. Inputs are never
|
|
36
|
+
mutated. Contract: `engine-aggregation-api` 1.0.0, module aggregation.bounds.
|
|
37
|
+
"""
|
|
38
|
+
|
|
39
|
+
from __future__ import annotations
|
|
40
|
+
|
|
41
|
+
import math
|
|
42
|
+
from collections.abc import Callable, Sequence
|
|
43
|
+
from dataclasses import dataclass
|
|
44
|
+
|
|
45
|
+
import numpy as np
|
|
46
|
+
|
|
47
|
+
from riskvalidation.portfolio.portfolio import check_level, positive_int
|
|
48
|
+
|
|
49
|
+
Ppf = Callable[[np.ndarray], np.ndarray]
|
|
50
|
+
OBJECTIVES = ("max-min-row-sum", "min-max-row-sum")
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def comonotonic_var(ppfs: Sequence[Ppf], q: float) -> float:
|
|
54
|
+
"""The VaR of the comonotonic total, sum_k F_k^-1(q) (money). Golden: Pareto(2) marginals F(x) = 1 - (1 + x)^-2, so
|
|
55
|
+
F^-1(q) = (1 - q)^(-1/2) - 1: d = 8 at q = 0.99 gives 72.00, at 0.995 105.14, at 0.999 244.98 (Table 4, "comonotonic
|
|
56
|
+
(exact)", PDF p.14, recomputed from the formula)."""
|
|
57
|
+
level = check_level(q)
|
|
58
|
+
if len(ppfs) == 0:
|
|
59
|
+
raise ValueError("ppfs is empty")
|
|
60
|
+
grid = np.array([level])
|
|
61
|
+
return float(sum(float(np.asarray(f(grid), dtype=float)[0]) for f in ppfs))
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def rearrangement_algorithm(matrix: np.ndarray, objective: str, epsilon: float, max_sweeps: int,
|
|
65
|
+
seed: int) -> tuple[np.ndarray, float, int, bool]:
|
|
66
|
+
"""The rearrangement algorithm (F5, p.10) on an (N, D) matrix of money: permute each column randomly under the seed,
|
|
67
|
+
then in a sweep rearrange column j to be oppositely ordered to the sum of the other columns for j = 1..D, and repeat
|
|
68
|
+
sweeps until the value changes by less than `epsilon` between two successive sweeps or `max_sweeps` is reached.
|
|
69
|
+
|
|
70
|
+
`objective` "max-min-row-sum" maximises the smallest row sum (the upper VaR bound), "min-max-row-sum" minimises the
|
|
71
|
+
largest (the lower VaR bound); both use the same oppositely-ordered step, only the value that stops the loop
|
|
72
|
+
differs.
|
|
73
|
+
Returns (the rearranged matrix, the value, the number of sweeps, converged). The output is a column-wise
|
|
74
|
+
permutation of
|
|
75
|
+
the input. A +infinity entry (the last cell of an unbounded upper matrix) is kept; NaN and -infinity are refused.
|
|
76
|
+
"""
|
|
77
|
+
m = np.array(matrix, dtype=float)
|
|
78
|
+
if m.ndim != 2:
|
|
79
|
+
raise ValueError(f"matrix must be two-dimensional, got shape {m.shape}")
|
|
80
|
+
n_rows, n_cols = m.shape
|
|
81
|
+
if n_rows < 2 or n_cols < 2:
|
|
82
|
+
raise ValueError(f"matrix needs at least 2 rows and 2 columns, got shape {m.shape}")
|
|
83
|
+
if np.any(np.isnan(m)) or np.any(np.isneginf(m)):
|
|
84
|
+
raise ValueError("matrix must not contain NaN or -infinity")
|
|
85
|
+
if objective not in OBJECTIVES:
|
|
86
|
+
raise ValueError(f"objective must be one of {OBJECTIVES}, got {objective!r}")
|
|
87
|
+
eps = float(epsilon)
|
|
88
|
+
if not (math.isfinite(eps) and eps > 0.0):
|
|
89
|
+
raise ValueError(f"epsilon must be positive, got {epsilon}")
|
|
90
|
+
sweeps_max = positive_int(max_sweeps, "max_sweeps")
|
|
91
|
+
rng = np.random.Generator(np.random.PCG64(int(seed)))
|
|
92
|
+
for j in range(n_cols):
|
|
93
|
+
m[:, j] = rng.permutation(m[:, j])
|
|
94
|
+
finite = np.isfinite(m)
|
|
95
|
+
zeroed = np.where(finite, m, 0.0)
|
|
96
|
+
inf_count = (~finite).sum(axis=1)
|
|
97
|
+
sorted_cols = np.sort(m, axis=0)
|
|
98
|
+
|
|
99
|
+
def value() -> float:
|
|
100
|
+
rows = np.where(inf_count > 0, np.inf, zeroed.sum(axis=1))
|
|
101
|
+
return float(rows.min() if objective == "max-min-row-sum" else rows.max())
|
|
102
|
+
|
|
103
|
+
previous = value()
|
|
104
|
+
converged = False
|
|
105
|
+
sweeps = 0
|
|
106
|
+
for sweep in range(1, sweeps_max + 1):
|
|
107
|
+
sweeps = sweep
|
|
108
|
+
total = zeroed.sum(axis=1)
|
|
109
|
+
for j in range(n_cols):
|
|
110
|
+
others = np.where(inf_count - (~finite[:, j]) > 0, np.inf, total - zeroed[:, j])
|
|
111
|
+
order = np.argsort(others, kind="stable")
|
|
112
|
+
new = np.empty(n_rows)
|
|
113
|
+
new[order] = sorted_cols[::-1, j] # the largest value goes to the row with the smallest rest
|
|
114
|
+
m[:, j] = new
|
|
115
|
+
new_finite = np.isfinite(new)
|
|
116
|
+
new_zeroed = np.where(new_finite, new, 0.0)
|
|
117
|
+
total += new_zeroed - zeroed[:, j]
|
|
118
|
+
inf_count += (~new_finite).astype(int) - (~finite[:, j]).astype(int)
|
|
119
|
+
zeroed[:, j], finite[:, j] = new_zeroed, new_finite
|
|
120
|
+
current = value()
|
|
121
|
+
if current == previous or abs(current - previous) < eps:
|
|
122
|
+
converged = True
|
|
123
|
+
break
|
|
124
|
+
previous = current
|
|
125
|
+
return m, value(), sweeps, converged
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@dataclass(frozen=True)
|
|
129
|
+
class VarBounds:
|
|
130
|
+
"""The rearrangement ranges of the worst and the best VaR, money. `lower_range` is (t_N, t-bar_N), the best VaR (F5
|
|
131
|
+
(21)); `upper_range` is (s_N, s-bar_N), the worst VaR (F5 (19)); `sweeps` are the sweep counts of the four runs in
|
|
132
|
+
the
|
|
133
|
+
order t_N, t-bar_N, s_N, s-bar_N; `converged` is True when all four stopped on `epsilon`."""
|
|
134
|
+
|
|
135
|
+
alpha: float
|
|
136
|
+
n: int
|
|
137
|
+
epsilon: float
|
|
138
|
+
lower_range: tuple[float, float]
|
|
139
|
+
upper_range: tuple[float, float]
|
|
140
|
+
sweeps: tuple[int, int, int, int]
|
|
141
|
+
converged: bool
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _grid(ppfs: Sequence[Ppf], probs: np.ndarray, name: str) -> np.ndarray:
|
|
145
|
+
cols = []
|
|
146
|
+
for j, f in enumerate(ppfs):
|
|
147
|
+
col = np.asarray(f(probs), dtype=float)
|
|
148
|
+
if col.shape != probs.shape or np.any(np.isnan(col)) or np.any(np.isneginf(col)):
|
|
149
|
+
raise ValueError(f"ppfs[{j}] must return {probs.size} values, none NaN or -infinity, on the {name} grid")
|
|
150
|
+
cols.append(col)
|
|
151
|
+
return np.column_stack(cols)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def worst_var_bounds(ppfs: Sequence[Ppf], alpha: float, n: int = 100_000, epsilon: float = 1e-3, max_sweeps: int =
|
|
155
|
+
1_000,
|
|
156
|
+
seed: int = 0) -> VarBounds:
|
|
157
|
+
"""The best and the worst VaR of the total of the marginals `ppfs` at level `alpha` for any dependence, money.
|
|
158
|
+
|
|
159
|
+
The upper bound uses the matrices of F5 (18) over [alpha, 1] (cell edges F_j^-1(alpha + (1 - alpha)(i - 1) / N) and
|
|
160
|
+
F_j^-1(alpha + (1 - alpha) i / N)), the lower bound those of F5 (20) over [0, alpha]; the four runs use the seeds
|
|
161
|
+
`seed`, `seed + 1`, `seed + 2`, `seed + 3`. Golden (Table 4, Pareto(2), N = 1e5, epsilon = 1e-3, d = 8): alpha 0.99
|
|
162
|
+
lower 9.00 - 9.00, upper 141.66 - 141.67; alpha 0.995 lower 13.13 - 13.14, upper 203.65 - 203.66; alpha 0.999 lower
|
|
163
|
+
30.47 - 30.62, upper 465.28 - 465.30.
|
|
164
|
+
"""
|
|
165
|
+
level = check_level(alpha, "alpha")
|
|
166
|
+
cells = positive_int(n, "n")
|
|
167
|
+
if cells < 2:
|
|
168
|
+
raise ValueError(f"n must be at least 2, got {n}")
|
|
169
|
+
if len(ppfs) < 2:
|
|
170
|
+
raise ValueError(f"ppfs must hold at least 2 marginals, got {len(ppfs)}")
|
|
171
|
+
i = np.arange(cells, dtype=float)
|
|
172
|
+
upper = (level + (1.0 - level) * i / cells, level + (1.0 - level) * (i + 1.0) / cells)
|
|
173
|
+
lower = (level * i / cells, level * (i + 1.0) / cells)
|
|
174
|
+
mats = (
|
|
175
|
+
(_grid(ppfs, lower[0], "lower"), "min-max-row-sum"),
|
|
176
|
+
(_grid(ppfs, lower[1], "lower"), "min-max-row-sum"),
|
|
177
|
+
(_grid(ppfs, upper[0], "upper"), "max-min-row-sum"),
|
|
178
|
+
(_grid(ppfs, upper[1], "upper"), "max-min-row-sum"),
|
|
179
|
+
)
|
|
180
|
+
values, sweeps, flags = [], [], []
|
|
181
|
+
for k, (matrix, objective) in enumerate(mats):
|
|
182
|
+
_, v, sw, ok = rearrangement_algorithm(matrix, objective, epsilon, max_sweeps, int(seed) + k)
|
|
183
|
+
values.append(v)
|
|
184
|
+
sweeps.append(sw)
|
|
185
|
+
flags.append(ok)
|
|
186
|
+
if not all(math.isfinite(v) for v in values):
|
|
187
|
+
raise ValueError("n is too small for the unbounded upper tail: s-bar is infinite; use n > the number of "
|
|
188
|
+
"marginals")
|
|
189
|
+
return VarBounds(alpha=level, n=cells, epsilon=float(epsilon), lower_range=(values[0], values[1]),
|
|
190
|
+
upper_range=(values[2], values[3]), sweeps=(sweeps[0], sweeps[1], sweeps[2], sweeps[3]),
|
|
191
|
+
converged=all(flags))
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
"""Rungs 3 and 4 of the aggregation ladder: Gaussian and Student t copula aggregation (dossier 05 G.1 item 3).
|
|
2
|
+
|
|
3
|
+
The copula draw of the uniforms U is restated here from the sources the engine's own `portfolio.copula` docstring cites,
|
|
4
|
+
because `portfolio.copula` keeps its sampler private:
|
|
5
|
+
|
|
6
|
+
- Gaussian copula (Li 2000, doi:10.3905/jfi.2000.319253): Z = L e with L a factor of the correlation matrix R and e
|
|
7
|
+
independent standard normals, U = Phi(Z).
|
|
8
|
+
- Student t copula (Frey and McNeil 2003, doi:10.21314/jor.2003.089; Demarta and McNeil 2005,
|
|
9
|
+
doi:10.1111/j.1751-5823.2005.tb00254.x): W = nu / chi2_nu independent of Z, X = sqrt(W) Z, U = t_nu(X). The t copula
|
|
10
|
+
has
|
|
11
|
+
the symmetric tail dependence of `t_tail_dependence`.
|
|
12
|
+
|
|
13
|
+
The total of the K risks is the row sum of L_k = F_k^-1(U_k) (Sklar). The VaR, ES, EC = VaR - EL and the Monte Carlo
|
|
14
|
+
errors
|
|
15
|
+
of an aggregate are those of the reused `portfolio.portfolio.measures_from_sample`. Clayton sampling and vine copulas
|
|
16
|
+
are
|
|
17
|
+
deferred (BL-078); only the closed forms of the bivariate Clayton copula are here.
|
|
18
|
+
|
|
19
|
+
Randomness: `numpy.random.Generator(numpy.random.PCG64(seed))`; the result is reproducible for the same (seed, n,
|
|
20
|
+
chunk_size) and another chunk size gives a different but equally valid sample. Nothing reads global state, the clock or
|
|
21
|
+
the environment; inputs are never mutated.
|
|
22
|
+
|
|
23
|
+
Contract: `engine-aggregation-api` 1.0.0, module aggregation.copulas.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
import math
|
|
29
|
+
from collections.abc import Callable, Sequence
|
|
30
|
+
from dataclasses import dataclass
|
|
31
|
+
|
|
32
|
+
import numpy as np
|
|
33
|
+
from scipy import special
|
|
34
|
+
|
|
35
|
+
from riskvalidation.aggregation.simple import _matrix, check_correlation
|
|
36
|
+
from riskvalidation.portfolio.portfolio import check_level, measures_from_sample, positive_int
|
|
37
|
+
|
|
38
|
+
DEFAULT_CHUNK = 100_000
|
|
39
|
+
UNIFORM_FLOOR = 1e-16 # keeps a draw strictly inside (0, 1) where Phi or t_nu round to 0 or 1
|
|
40
|
+
PSD_FLOOR = 1e-12 # eigenvalues of a singular correlation below this multiple of K are treated as zero
|
|
41
|
+
|
|
42
|
+
Ppf = Callable[[np.ndarray], np.ndarray]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _vector(x: object, name: str) -> np.ndarray:
|
|
46
|
+
a = np.array(x, dtype=float)
|
|
47
|
+
if a.ndim != 1:
|
|
48
|
+
raise ValueError(f"{name} must be one-dimensional, got shape {a.shape}")
|
|
49
|
+
if not np.all(np.isfinite(a)):
|
|
50
|
+
raise ValueError(f"{name} contains non-finite values")
|
|
51
|
+
return a
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def marginal_ppf_sample(sorted_losses: np.ndarray) -> Callable[[np.ndarray], np.ndarray]:
|
|
55
|
+
"""The quantile function of a loss sample: `ppf(u) = numpy.interp(u, (i - 0.5) / n, sorted_losses)`, linear between
|
|
56
|
+
the Hazen positions and clamped at the ends. Golden: [0, 10] gives 5.0 at 0.5, 0.0 at 0.1 and 10.0 at 0.9."""
|
|
57
|
+
x = _vector(sorted_losses, "sorted_losses")
|
|
58
|
+
if x.size < 2:
|
|
59
|
+
raise ValueError("sorted_losses needs at least 2 values")
|
|
60
|
+
if np.any(np.diff(x) < 0.0):
|
|
61
|
+
raise ValueError("sorted_losses must be sorted ascending")
|
|
62
|
+
positions = (np.arange(1, x.size + 1) - 0.5) / x.size
|
|
63
|
+
|
|
64
|
+
def ppf(u: np.ndarray) -> np.ndarray:
|
|
65
|
+
return np.interp(np.asarray(u, dtype=float), positions, x)
|
|
66
|
+
|
|
67
|
+
return ppf
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def marginal_ppf_pmf(grid: np.ndarray, pmf: np.ndarray) -> Callable[[np.ndarray], np.ndarray]:
|
|
71
|
+
"""The quantile function of a probability mass function on an ascending grid: the smallest grid point whose
|
|
72
|
+
cumulative probability is >= u - 1e-12 (the rule of `oprisk.aggregate.quantile_from_pmf`). Golden: grid [0, 1, 2],
|
|
73
|
+
pmf [0.5, 0.3, 0.2] gives 0, 1, 1 and 2 at 0.5, 0.51, 0.8 and 0.81."""
|
|
74
|
+
g = _vector(grid, "grid")
|
|
75
|
+
p = _vector(pmf, "pmf")
|
|
76
|
+
if g.size != p.size or g.size == 0:
|
|
77
|
+
raise ValueError("grid and pmf must be non-empty and of the same length")
|
|
78
|
+
if np.any(np.diff(g) < 0.0):
|
|
79
|
+
raise ValueError("grid must be sorted ascending")
|
|
80
|
+
if np.any(p < 0.0):
|
|
81
|
+
raise ValueError("pmf must not contain a negative entry")
|
|
82
|
+
if abs(float(p.sum()) - 1.0) > 1e-9:
|
|
83
|
+
raise ValueError(f"pmf must sum to 1 (to 1e-9), got {float(p.sum())}")
|
|
84
|
+
cum = np.cumsum(p)
|
|
85
|
+
|
|
86
|
+
def ppf(u: np.ndarray) -> np.ndarray:
|
|
87
|
+
idx = np.searchsorted(cum, np.asarray(u, dtype=float) - 1e-12, side="left")
|
|
88
|
+
return g[np.minimum(idx, g.size - 1)]
|
|
89
|
+
|
|
90
|
+
return ppf
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _factor(corr: np.ndarray) -> np.ndarray:
|
|
94
|
+
"""A matrix A with A A' = corr: the Cholesky factor, or for a singular positive semi-definite correlation (the
|
|
95
|
+
all-ones matrix of the comonotonic case) the eigen factor with the null eigenvalues set to zero and the rows
|
|
96
|
+
rescaled to unit length, so that every Z_k is exactly standard normal and a unit correlation is exactly
|
|
97
|
+
comonotonic."""
|
|
98
|
+
try:
|
|
99
|
+
return np.linalg.cholesky(corr)
|
|
100
|
+
except np.linalg.LinAlgError:
|
|
101
|
+
w, vec = np.linalg.eigh(0.5 * (corr + corr.T))
|
|
102
|
+
w = np.where(w > PSD_FLOOR * corr.shape[0], w, 0.0)
|
|
103
|
+
a = vec * np.sqrt(w)
|
|
104
|
+
return a / np.linalg.norm(a, axis=1, keepdims=True)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _check_family(family: str, nu: float | None) -> float | None:
|
|
108
|
+
if family == "gaussian":
|
|
109
|
+
if nu is not None:
|
|
110
|
+
raise ValueError("nu must be None for the gaussian family")
|
|
111
|
+
return None
|
|
112
|
+
if family == "t":
|
|
113
|
+
if nu is None:
|
|
114
|
+
raise ValueError("nu is required for the t family and must be above 2")
|
|
115
|
+
v = float(nu)
|
|
116
|
+
if not (math.isfinite(v) and v > 2.0):
|
|
117
|
+
raise ValueError(f"nu must be a finite number above 2, got {nu}")
|
|
118
|
+
return v
|
|
119
|
+
raise ValueError(f"family must be 'gaussian' or 't', got {family!r}")
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _draw(rng: np.random.Generator, factor: np.ndarray, family: str, nu: float | None, n: int) -> np.ndarray:
|
|
123
|
+
z = rng.standard_normal((n, factor.shape[0])) @ factor.T
|
|
124
|
+
if family == "gaussian":
|
|
125
|
+
u = special.ndtr(z)
|
|
126
|
+
else:
|
|
127
|
+
assert nu is not None
|
|
128
|
+
w = nu / rng.chisquare(nu, size=n)
|
|
129
|
+
u = special.stdtr(nu, np.sqrt(w)[:, None] * z)
|
|
130
|
+
return np.clip(u, UNIFORM_FLOOR, 1.0 - UNIFORM_FLOOR)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def simulate_copula_uniforms(corr: np.ndarray, family: str, nu: float | None, n: int, seed: int) -> np.ndarray:
|
|
134
|
+
"""(n, K) uniforms in (0, 1) with the Gaussian or Student t copula of the correlation `corr` (module docstring).
|
|
135
|
+
|
|
136
|
+
The Kendall rank correlation of a pair is (2 / pi) arcsin(rho) for both families, 0.3333 for rho = 0.5."""
|
|
137
|
+
r = _matrix(corr, "corr")
|
|
138
|
+
check_correlation(r)
|
|
139
|
+
nu_v = _check_family(family, nu)
|
|
140
|
+
count = positive_int(n, "n")
|
|
141
|
+
rng = np.random.Generator(np.random.PCG64(int(seed)))
|
|
142
|
+
return _draw(rng, _factor(r), family, nu_v, count)
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def simulate_component_losses(ppfs: Sequence[Ppf], corr: np.ndarray, family: str, nu: float | None, n_draws: int,
|
|
146
|
+
seed: int, chunk_size: int = DEFAULT_CHUNK) -> np.ndarray:
|
|
147
|
+
"""(n_draws, K) money, L_k = ppf_k(U_k) (dossier 05 G.1 item 3, Sklar), drawn in chunks of `chunk_size` rows so the
|
|
148
|
+
working memory of the draw is of the order chunk_size * K * 8 bytes; the returned array is n_draws * K * 8 bytes
|
|
149
|
+
(320 MB at 1e7 draws of 4 risks, the known maximum of the sizing)."""
|
|
150
|
+
r = _matrix(corr, "corr")
|
|
151
|
+
check_correlation(r)
|
|
152
|
+
k = r.shape[0]
|
|
153
|
+
if len(ppfs) != k:
|
|
154
|
+
raise ValueError(f"ppfs must hold one quantile function per risk: got {len(ppfs)} for a {k} x {k} corr")
|
|
155
|
+
nu_v = _check_family(family, nu)
|
|
156
|
+
total = positive_int(n_draws, "n_draws")
|
|
157
|
+
chunk = positive_int(chunk_size, "chunk_size")
|
|
158
|
+
factor = _factor(r)
|
|
159
|
+
rng = np.random.Generator(np.random.PCG64(int(seed)))
|
|
160
|
+
out = np.empty((total, k), dtype=float)
|
|
161
|
+
start = 0
|
|
162
|
+
while start < total:
|
|
163
|
+
m = min(chunk, total - start)
|
|
164
|
+
u = _draw(rng, factor, family, nu_v, m)
|
|
165
|
+
for j in range(k):
|
|
166
|
+
col = np.asarray(ppfs[j](u[:, j]), dtype=float)
|
|
167
|
+
if col.shape != (m,) or not np.all(np.isfinite(col)):
|
|
168
|
+
raise ValueError(f"ppfs[{j}] must return {m} finite losses")
|
|
169
|
+
out[start:start + m, j] = col
|
|
170
|
+
start += m
|
|
171
|
+
return out
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def t_tail_dependence(rho: float, nu: float) -> float:
|
|
175
|
+
"""The symmetric tail dependence coefficient of the bivariate t copula, 2 t_(nu+1)(-sqrt((nu + 1)(1 - rho) / (1 +
|
|
176
|
+
rho))) (dossier 05 G.1 item 3; McNeil, Frey and Embrechts, the chapter number is UNVERIFIED there). Golden: (0.5, 4)
|
|
177
|
+
0.2532, (0, 4) 0.0756, (0.5, 8) 0.1173, (0.5, 30) 0.0030."""
|
|
178
|
+
r, v = float(rho), float(nu)
|
|
179
|
+
if not (math.isfinite(r) and -1.0 < r < 1.0):
|
|
180
|
+
raise ValueError(f"rho must lie in (-1, 1), got {rho}")
|
|
181
|
+
if not (math.isfinite(v) and v > 0.0):
|
|
182
|
+
raise ValueError(f"nu must be positive, got {nu}")
|
|
183
|
+
return float(2.0 * special.stdtr(v + 1.0, -math.sqrt((v + 1.0) * (1.0 - r) / (1.0 + r))))
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def clayton_copula(u: float, v: float, theta: float) -> float:
|
|
187
|
+
"""C_theta(u, v) = (u^-theta + v^-theta - 1)^(-1/theta) (dossier 05 G.1 item 3), bivariate; sampling is deferred
|
|
188
|
+
(BL-078). Golden: (0.5, 0.5, 1) gives 1/3 and C(u, 1) = u."""
|
|
189
|
+
a, b, th = float(u), float(v), float(theta)
|
|
190
|
+
if not (math.isfinite(a) and 0.0 < a <= 1.0):
|
|
191
|
+
raise ValueError(f"u must lie in (0, 1], got {u}")
|
|
192
|
+
if not (math.isfinite(b) and 0.0 < b <= 1.0):
|
|
193
|
+
raise ValueError(f"v must lie in (0, 1], got {v}")
|
|
194
|
+
if not (math.isfinite(th) and th > 0.0):
|
|
195
|
+
raise ValueError(f"theta must be positive, got {theta}")
|
|
196
|
+
return float((a ** -th + b ** -th - 1.0) ** (-1.0 / th))
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def clayton_lower_tail_dependence(theta: float) -> float:
|
|
200
|
+
"""The lower tail dependence of the Clayton copula, 2^(-1 / theta) (dossier 05 G.1 item 3). Goldens: 0.5 at theta 1,
|
|
201
|
+
0.7071 at theta 2."""
|
|
202
|
+
th = float(theta)
|
|
203
|
+
if not (math.isfinite(th) and th > 0.0):
|
|
204
|
+
raise ValueError(f"theta must be positive, got {theta}")
|
|
205
|
+
return float(2.0 ** (-1.0 / th))
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
@dataclass(frozen=True)
|
|
209
|
+
class CopulaAggregate:
|
|
210
|
+
"""An aggregate at one level, money in the caller's currency: `el` is the caller's sum of the marginal expected
|
|
211
|
+
losses, `ec = var - el`; `var_se` and `es_se` (batch means, `portfolio.copula.mc_standard_errors`) are both None or
|
|
212
|
+
both set, None below 200 draws."""
|
|
213
|
+
|
|
214
|
+
family: str
|
|
215
|
+
nu: float | None
|
|
216
|
+
n_draws: int
|
|
217
|
+
seed: int
|
|
218
|
+
chunk_size: int
|
|
219
|
+
level: float
|
|
220
|
+
el: float
|
|
221
|
+
var: float
|
|
222
|
+
es: float
|
|
223
|
+
ec: float
|
|
224
|
+
var_se: float | None
|
|
225
|
+
es_se: float | None
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def copula_aggregate(ppfs: Sequence[Ppf], corr: np.ndarray, family: str, nu: float | None, el: float,
|
|
229
|
+
level: float = 0.999, n_draws: int = 1_000_000, seed: int = 0,
|
|
230
|
+
chunk_size: int = DEFAULT_CHUNK) -> CopulaAggregate:
|
|
231
|
+
"""The VaR, ES and EC = VaR - EL of the row sums of `simulate_component_losses`, computed by the reused
|
|
232
|
+
`measures_from_sample`. `el` money (the sum of the marginal expected losses)."""
|
|
233
|
+
lv = check_level(level, "level")
|
|
234
|
+
e = float(el)
|
|
235
|
+
if not math.isfinite(e):
|
|
236
|
+
raise ValueError("el must be finite")
|
|
237
|
+
losses = simulate_component_losses(ppfs, corr, family, nu, n_draws, seed, chunk_size)
|
|
238
|
+
m = measures_from_sample(losses.sum(axis=1), [lv], e)[0]
|
|
239
|
+
return CopulaAggregate(family=family, nu=None if nu is None else float(nu), n_draws=int(n_draws), seed=int(seed),
|
|
240
|
+
chunk_size=int(chunk_size), level=lv, el=e, var=m.var, es=float(m.es), ec=m.ec,
|
|
241
|
+
var_se=m.var_se, es_se=m.es_se)
|