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.
Files changed (164) hide show
  1. riskvalidation/__init__.py +30 -0
  2. riskvalidation/aggregation/__init__.py +11 -0
  3. riskvalidation/aggregation/band.py +151 -0
  4. riskvalidation/aggregation/bounds.py +191 -0
  5. riskvalidation/aggregation/copulas.py +241 -0
  6. riskvalidation/aggregation/model_risk.py +133 -0
  7. riskvalidation/aggregation/simple.py +147 -0
  8. riskvalidation/ccr/__init__.py +13 -0
  9. riskvalidation/ccr/collateral.py +175 -0
  10. riskvalidation/ccr/cva.py +193 -0
  11. riskvalidation/ccr/exposure.py +192 -0
  12. riskvalidation/ccr/hw1f.py +426 -0
  13. riskvalidation/ccr/swaps.py +172 -0
  14. riskvalidation/core/__init__.py +1 -0
  15. riskvalidation/core/build.py +57 -0
  16. riskvalidation/core/hashing.py +48 -0
  17. riskvalidation/core/policy.py +130 -0
  18. riskvalidation/core/registry.py +65 -0
  19. riskvalidation/core/result.py +117 -0
  20. riskvalidation/core/suite.py +78 -0
  21. riskvalidation/engines/__init__.py +2 -0
  22. riskvalidation/engines/low_default.py +170 -0
  23. riskvalidation/engines/pd_curve.py +529 -0
  24. riskvalidation/engines/vasicek.py +72 -0
  25. riskvalidation/fairness/__init__.py +10 -0
  26. riskvalidation/fairness/_checks.py +115 -0
  27. riskvalidation/fairness/conditional.py +201 -0
  28. riskvalidation/fairness/inference.py +64 -0
  29. riskvalidation/fairness/metrics.py +261 -0
  30. riskvalidation/fairness/plants.py +240 -0
  31. riskvalidation/fairness/policy.py +97 -0
  32. riskvalidation/fairness/replication.py +39 -0
  33. riskvalidation/fairness/situation.py +307 -0
  34. riskvalidation/generators/__init__.py +68 -0
  35. riskvalidation/generators/_base.py +145 -0
  36. riskvalidation/generators/counts.py +232 -0
  37. riskvalidation/generators/drift.py +107 -0
  38. riskvalidation/generators/framingham.py +124 -0
  39. riskvalidation/generators/paths.py +349 -0
  40. riskvalidation/generators/ratings.py +186 -0
  41. riskvalidation/generators/scores.py +347 -0
  42. riskvalidation/harness/__init__.py +46 -0
  43. riskvalidation/harness/exact.py +137 -0
  44. riskvalidation/harness/performance.py +74 -0
  45. riskvalidation/harness/rates.py +103 -0
  46. riskvalidation/harness/run.py +197 -0
  47. riskvalidation/irrbb/__init__.py +9 -0
  48. riskvalidation/irrbb/behavioural.py +206 -0
  49. riskvalidation/irrbb/curves.py +286 -0
  50. riskvalidation/irrbb/eve_nii.py +245 -0
  51. riskvalidation/irrbb/shocks.py +171 -0
  52. riskvalidation/irrbb/simulation.py +203 -0
  53. riskvalidation/irrbb/slotting.py +184 -0
  54. riskvalidation/lgd_ead/__init__.py +8 -0
  55. riskvalidation/lgd_ead/_checks.py +50 -0
  56. riskvalidation/lgd_ead/ccf.py +228 -0
  57. riskvalidation/lgd_ead/downturn.py +64 -0
  58. riskvalidation/lgd_ead/floors.py +114 -0
  59. riskvalidation/lgd_ead/lgd_models.py +297 -0
  60. riskvalidation/lgd_ead/workout.py +162 -0
  61. riskvalidation/liquidity/__init__.py +9 -0
  62. riskvalidation/liquidity/_checks.py +78 -0
  63. riskvalidation/liquidity/cbc.py +158 -0
  64. riskvalidation/liquidity/deposits.py +151 -0
  65. riskvalidation/liquidity/ladder.py +119 -0
  66. riskvalidation/liquidity/reverse.py +141 -0
  67. riskvalidation/liquidity/runoff.py +220 -0
  68. riskvalidation/liquidity/scenarios.py +272 -0
  69. riskvalidation/market/__init__.py +8 -0
  70. riskvalidation/market/caviar.py +239 -0
  71. riskvalidation/market/conventions.py +83 -0
  72. riskvalidation/market/evt.py +111 -0
  73. riskvalidation/market/frtb.py +175 -0
  74. riskvalidation/market/garch.py +204 -0
  75. riskvalidation/market/gas_fz.py +219 -0
  76. riskvalidation/market/historical.py +96 -0
  77. riskvalidation/market/parametric.py +78 -0
  78. riskvalidation/market/scoring.py +145 -0
  79. riskvalidation/ml/__init__.py +11 -0
  80. riskvalidation/ml/_checks.py +67 -0
  81. riskvalidation/ml/_logistic.py +82 -0
  82. riskvalidation/ml/cbpe.py +91 -0
  83. riskvalidation/ml/challenger.py +73 -0
  84. riskvalidation/ml/conformal.py +116 -0
  85. riskvalidation/ml/dataquality.py +130 -0
  86. riskvalidation/ml/effects.py +67 -0
  87. riskvalidation/ml/explanations.py +125 -0
  88. riskvalidation/ml/generalisation.py +79 -0
  89. riskvalidation/ml/leakage.py +99 -0
  90. riskvalidation/ml/plants.py +425 -0
  91. riskvalidation/ml/policy.py +182 -0
  92. riskvalidation/ml/robustness.py +286 -0
  93. riskvalidation/ml/seeds.py +106 -0
  94. riskvalidation/oprisk/__init__.py +18 -0
  95. riskvalidation/oprisk/_checks.py +60 -0
  96. riskvalidation/oprisk/aggregate.py +375 -0
  97. riskvalidation/oprisk/distributions.py +758 -0
  98. riskvalidation/oprisk/scenarios.py +342 -0
  99. riskvalidation/oprisk/sla.py +80 -0
  100. riskvalidation/oprisk/sma.py +169 -0
  101. riskvalidation/policies/__init__.py +4 -0
  102. riskvalidation/policies/default.json +273 -0
  103. riskvalidation/portfolio/__init__.py +16 -0
  104. riskvalidation/portfolio/asrf_fit.py +283 -0
  105. riskvalidation/portfolio/copula.py +129 -0
  106. riskvalidation/portfolio/creditrisk_plus.py +232 -0
  107. riskvalidation/portfolio/euler.py +126 -0
  108. riskvalidation/portfolio/granularity.py +135 -0
  109. riskvalidation/portfolio/importance.py +277 -0
  110. riskvalidation/portfolio/portfolio.py +309 -0
  111. riskvalidation/provisions/__init__.py +8 -0
  112. riskvalidation/provisions/_checks.py +100 -0
  113. riskvalidation/provisions/ecl.py +233 -0
  114. riskvalidation/provisions/local_cl.py +360 -0
  115. riskvalidation/provisions/local_es.py +157 -0
  116. riskvalidation/provisions/overlays.py +102 -0
  117. riskvalidation/provisions/reconciliation.py +157 -0
  118. riskvalidation/provisions/staging.py +211 -0
  119. riskvalidation/provisions/term_structure.py +199 -0
  120. riskvalidation/regulatory/__init__.py +14 -0
  121. riskvalidation/regulatory/ba_cva.py +138 -0
  122. riskvalidation/regulatory/frtb.py +345 -0
  123. riskvalidation/regulatory/irb.py +314 -0
  124. riskvalidation/regulatory/lcr_nsfr.py +369 -0
  125. riskvalidation/regulatory/output_floor.py +45 -0
  126. riskvalidation/regulatory/sa_ccr.py +486 -0
  127. riskvalidation/regulatory/standardised.py +348 -0
  128. riskvalidation/stress/__init__.py +9 -0
  129. riskvalidation/stress/capital.py +476 -0
  130. riskvalidation/stress/paths.py +108 -0
  131. riskvalidation/stress/reverse.py +179 -0
  132. riskvalidation/stress/satellites.py +268 -0
  133. riskvalidation/stress/scenario_models.py +274 -0
  134. riskvalidation/transitions/__init__.py +0 -0
  135. riskvalidation/transitions/em.py +120 -0
  136. riskvalidation/transitions/embedding.py +221 -0
  137. riskvalidation/transitions/estimators.py +213 -0
  138. riskvalidation/transitions/intervals.py +306 -0
  139. riskvalidation/transitions/mobility.py +57 -0
  140. riskvalidation/transitions/ttc.py +171 -0
  141. riskvalidation/validation/__init__.py +103 -0
  142. riskvalidation/validation/_common.py +57 -0
  143. riskvalidation/validation/aggregation.py +425 -0
  144. riskvalidation/validation/calibration.py +757 -0
  145. riskvalidation/validation/ccr.py +530 -0
  146. riskvalidation/validation/discrimination.py +314 -0
  147. riskvalidation/validation/fairness.py +632 -0
  148. riskvalidation/validation/ifrs9.py +693 -0
  149. riskvalidation/validation/irrbb.py +389 -0
  150. riskvalidation/validation/lgd_ead.py +469 -0
  151. riskvalidation/validation/liquidity.py +647 -0
  152. riskvalidation/validation/market.py +807 -0
  153. riskvalidation/validation/ml.py +958 -0
  154. riskvalidation/validation/oprisk.py +357 -0
  155. riskvalidation/validation/portfolio.py +353 -0
  156. riskvalidation/validation/rating_system.py +245 -0
  157. riskvalidation/validation/stability.py +256 -0
  158. riskvalidation/validation/stress.py +552 -0
  159. riskvalidation/validation/transitions.py +386 -0
  160. riskvalidation-0.8.0.dist-info/METADATA +136 -0
  161. riskvalidation-0.8.0.dist-info/RECORD +164 -0
  162. riskvalidation-0.8.0.dist-info/WHEEL +5 -0
  163. riskvalidation-0.8.0.dist-info/licenses/LICENSE +21 -0
  164. 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)