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,342 @@
1
+ """Scenario analysis and its combination with loss data (dossier 05 F.5).
2
+
3
+ Scenarios are expert estimates of the frequency and severity of rare large events. The combination methods are (i)
4
+ scenario points as pseudo-observations appended to the tail sample, (ii) the body fitted to internal data and the tail
5
+ to scenario-implied quantiles, (iii) Bayesian credibility with the scenarios as the prior for the tail parameters
6
+ (Shevchenko and Wuthrich 2006, J. Operational Risk 1(3):3-26: a Gamma prior on the Pareto shape, section 3.3).
7
+ Validation must test the sensitivity of capital to each scenario point (the scenario influence function). Contract:
8
+ ``engine-oprisk-api`` 1.0.0, module scenarios.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import math
14
+ from collections.abc import Callable, Sequence
15
+ from dataclasses import dataclass
16
+
17
+ import numpy as np
18
+ from scipy import optimize, stats
19
+
20
+ from riskvalidation.oprisk._checks import positive, scalar, vec
21
+ from riskvalidation.oprisk.distributions import SeverityFit
22
+
23
+ KINDS = ("percentile", "individual")
24
+ PRIOR_KIND = "unrestricted-gamma-on-pareto-shape"
25
+ _NAN = math.nan
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class ScenarioPoint:
30
+ """One scenario: ``kind`` in ``{"percentile", "individual"}`` (the template of the 2008 LDCE scenarios, dossier 05
31
+ F.5, restricted to the two the C17 document carries); ``loss`` in EUR; ``exceedance_frequency`` the expected number
32
+ of
33
+ losses of at least ``loss`` per year (one in ten years is ``0.1``)."""
34
+
35
+ scenario_id: str
36
+ kind: str
37
+ loss: float
38
+ exceedance_frequency: float
39
+
40
+ def __post_init__(self) -> None:
41
+ if self.kind not in KINDS:
42
+ raise ValueError(f"kind must be one of {KINDS}, got {self.kind!r}")
43
+ positive(self.loss, "loss")
44
+ positive(self.exceedance_frequency, "exceedance_frequency")
45
+
46
+
47
+ def scenario_pseudo_observations(points: Sequence[ScenarioPoint], n_years: float) -> tuple[np.ndarray, np.ndarray]:
48
+ """Method (i): ``(losses, weights)``, each ``(P,)``: the loss of each point in EUR and its pseudo-count
49
+ ``exceedance_frequency * n_years``."""
50
+ n_years = positive(n_years, "n_years")
51
+ if len(points) == 0:
52
+ raise ValueError("no scenario points")
53
+ losses = np.array([p.loss for p in points], dtype=float)
54
+ weights = np.array([p.exceedance_frequency * n_years for p in points], dtype=float)
55
+ return losses, weights
56
+
57
+
58
+ # ----------------------------------------------------------------------------------------------------------------
59
+ # method (ii): the tail fitted to scenario-implied quantiles
60
+
61
+
62
+ def _log_excess_residuals(xi: float, beta: float, cond: np.ndarray, u: np.ndarray) -> np.ndarray:
63
+ """``ln(q_model(p) - threshold) - ln(loss - threshold)`` with ``q_model(p) - threshold = beta / xi (cond^(-xi) -
64
+ 1)``
65
+ and ``cond = 1 - p`` the conditional exceedance probability of each point (the objective of dossier 05 F.6)."""
66
+ return np.log(beta / xi * np.expm1(-xi * np.log(cond))) - np.log(u)
67
+
68
+
69
+ _STARTS = (0.05, 0.2, 0.5, 1.0, 2.0)
70
+ XI_BOUNDS = (1e-3, 50.0)
71
+
72
+
73
+ def _fit_scenario_gpd(cond: np.ndarray, u: np.ndarray, starts: Sequence[float] = _STARTS,
74
+ warm: tuple[float, float] | None = None) -> tuple[float, float, optimize.OptimizeResult]:
75
+ """Least squares on the log excess quantiles from several deterministic starts (and, when given, a warm start): the
76
+ best optimum. The search is bounded in log space (``xi`` in [1e-3, 50], ``beta`` within twelve decades of the
77
+ excesses) so that no start wanders into an overflow."""
78
+ best: optimize.OptimizeResult | None = None
79
+ i = int(np.argmax(u))
80
+ lo = np.array([math.log(XI_BOUNDS[0]), math.log(float(u.min()) * 1e-6)])
81
+ hi = np.array([math.log(XI_BOUNDS[1]), math.log(float(u.max()) * 1e6)])
82
+ initial = [(xi0, xi0 * u[i] / math.expm1(-xi0 * math.log(cond[i]))) for xi0 in starts]
83
+ if warm is not None:
84
+ initial.insert(0, warm)
85
+ for xi0, beta0 in initial:
86
+ start = np.clip(np.array([math.log(xi0), math.log(beta0)]), lo + 1e-9, hi - 1e-9)
87
+ res = optimize.least_squares(lambda z: _log_excess_residuals(math.exp(z[0]), math.exp(z[1]), cond, u), start,
88
+ bounds=(lo, hi), method="trf", xtol=1e-15, ftol=1e-15, gtol=1e-15, max_nfev=20000)
89
+ if best is None or res.cost < best.cost - 1e-300:
90
+ best = res
91
+ assert best is not None
92
+ return math.exp(best.x[0]), math.exp(best.x[1]), best
93
+
94
+
95
+ def _on_search_bound(xi: float, beta: float, u: np.ndarray) -> bool:
96
+ """True when the optimum sits on the box of ``_fit_scenario_gpd``: such a value is the box, not a statistic."""
97
+ tol = 1e-6
98
+ lo_b, hi_b = float(u.min()) * 1e-6, float(u.max()) * 1e6
99
+ return bool(xi <= XI_BOUNDS[0] * (1 + tol) or xi >= XI_BOUNDS[1] * (1 - tol)
100
+ or beta <= lo_b * (1 + tol) or beta >= hi_b * (1 - tol))
101
+
102
+
103
+ def _scenario_inputs(points: Sequence[ScenarioPoint], threshold: float,
104
+ frequency_above_threshold: float) -> tuple[float, float, list[ScenarioPoint]]:
105
+ h = scalar(threshold, "threshold")
106
+ fa = positive(frequency_above_threshold, "frequency_above_threshold")
107
+ pts = list(points)
108
+ if len(pts) < 2:
109
+ raise ValueError("at least two scenario points are needed")
110
+ if len({p.loss for p in pts}) < 2:
111
+ raise ValueError("at least two scenario points with distinct losses are needed")
112
+ if any(p.loss <= h for p in pts):
113
+ raise ValueError("every scenario loss must exceed the threshold")
114
+ return h, fa, pts
115
+
116
+
117
+ def _conditional(freq: np.ndarray, fa: float) -> np.ndarray:
118
+ cond = freq / fa
119
+ if np.any(cond <= 0.0) or np.any(cond >= 1.0):
120
+ raise ValueError("a scenario point implies a conditional exceedance probability outside (0, 1)")
121
+ return cond
122
+
123
+
124
+ def fit_tail_to_scenarios(points: Sequence[ScenarioPoint], threshold: float,
125
+ frequency_above_threshold: float) -> SeverityFit:
126
+ """Method (ii): a ``"gpd"`` ``SeverityFit`` with location ``threshold`` fitted by least squares on the log excess
127
+ quantiles. Each point implies ``P(X > loss | X > threshold) = exceedance_frequency / frequency_above_threshold``,
128
+ i.e.
129
+ the conditional quantile level ``p = 1 - exceedance_frequency / frequency_above_threshold``; the fit minimises
130
+ ``sum_s (ln(q_model(p_s) - threshold) - ln(loss_s - threshold))^2``, the objective with which dossier 05 F.6 fits
131
+ the LDCE percentiles. At least two points with distinct losses, every loss above the threshold and every conditional
132
+ probability in (0, 1). Exact when the points lie on a GPD (zero residual). The fit has no likelihood (``loglik`` is
133
+ ``nan``); its standard errors come from the residual variance and are ``nan`` with two points; ``converged`` is the
134
+ least squares solver's and is False when the optimum sits on the search bound of ``xi`` or ``beta`` (a bound is
135
+ not a statistic).
136
+ """
137
+ h, fa, pts = _scenario_inputs(points, threshold, frequency_above_threshold)
138
+ cond = _conditional(np.array([p.exceedance_frequency for p in pts]), fa)
139
+ u = np.array([p.loss - h for p in pts])
140
+ xi, beta, best = _fit_scenario_gpd(cond, u)
141
+ n = len(pts)
142
+ se = (_NAN, _NAN, 0.0)
143
+ if n > 2:
144
+ centre = np.array([xi, beta])
145
+ eps = 1e-6 * centre
146
+
147
+ def resid(p: np.ndarray) -> np.ndarray:
148
+ return _log_excess_residuals(p[0], p[1], cond, u)
149
+
150
+ jac = np.column_stack([
151
+ (resid(centre + np.eye(2)[k] * eps[k]) - resid(centre - np.eye(2)[k] * eps[k])) / (2.0 * eps[k])
152
+ for k in range(2)
153
+ ])
154
+ s2 = 2.0 * best.cost / (n - 2)
155
+ try:
156
+ diag = np.diag(s2 * np.linalg.inv(jac.T @ jac))
157
+ if np.all(diag >= 0.0):
158
+ se = (math.sqrt(float(diag[0])), math.sqrt(float(diag[1])), 0.0)
159
+ except np.linalg.LinAlgError:
160
+ pass
161
+ return SeverityFit("gpd", (xi, beta, h), se, h, True, n, _NAN,
162
+ bool(best.success and not _on_search_bound(xi, beta, u)))
163
+
164
+
165
+ # ----------------------------------------------------------------------------------------------------------------
166
+ # method (iii): Bayesian credibility (Shevchenko and Wuthrich 2006)
167
+
168
+
169
+ @dataclass(frozen=True)
170
+ class GammaPrior:
171
+ """A Gamma prior on the Pareto shape ``alpha = 1 / xi`` (dimensionless; ``xi`` the tail index): ``shape`` and
172
+ ``rate`` (``mean = shape / rate``), ``interval`` the expert interval of ``alpha`` and ``interval_level`` its
173
+ probability mass.
174
+ ``kind`` is always ``"unrestricted-gamma-on-pareto-shape"``, repeated on every C17 document (decision D4: Shevchenko
175
+ and Wuthrich restrict the prior to ``alpha`` above 1, a finite mean, which would exclude the true value of the tail
176
+ index 1.1 variant, ``alpha = 0.909``; this prior is unrestricted and says so)."""
177
+
178
+ shape: float
179
+ rate: float
180
+ mean: float
181
+ interval: tuple[float, float]
182
+ interval_level: float
183
+ kind: str = PRIOR_KIND
184
+
185
+ def __post_init__(self) -> None:
186
+ positive(self.shape, "shape")
187
+ positive(self.rate, "rate")
188
+ if abs(self.mean - self.shape / self.rate) > 1e-12 * max(1.0, abs(self.mean)):
189
+ raise ValueError("mean must equal shape / rate")
190
+ if self.kind != PRIOR_KIND:
191
+ raise ValueError(f"kind must be {PRIOR_KIND!r}")
192
+
193
+
194
+ def gamma_prior_from_mean_interval(mean: float, lower: float, upper: float, interval_level: float = 0.9) -> GammaPrior:
195
+ """The Gamma ``(shape, rate = shape / mean)`` whose probability of ``[lower, upper]`` is ``interval_level``
196
+ (Shevchenko and Wuthrich 2006, section 4.3: the prior from an expert's mean and interval probability), found by
197
+ bracketed root
198
+ finding on the shape in ``[1e-3, 1e6]``. Needs ``0 < lower < mean < upper``."""
199
+ mean, lower, upper = positive(mean, "mean"), positive(lower, "lower"), positive(upper, "upper")
200
+ level = scalar(interval_level, "interval_level")
201
+ if not 0.0 < level < 1.0:
202
+ raise ValueError(f"interval_level must lie in (0, 1), got {level}")
203
+ if not lower < mean < upper:
204
+ raise ValueError("the mean must lie strictly inside the interval")
205
+
206
+ def excess(k: float) -> float:
207
+ scale = mean / k
208
+ return float(stats.gamma.cdf(upper, k, scale=scale) - stats.gamma.cdf(lower, k, scale=scale)) - level
209
+
210
+ grid = np.logspace(-3.0, 6.0, 181)
211
+ values = np.array([excess(float(k)) for k in grid])
212
+ flips = np.nonzero((values[:-1] < 0.0) & (values[1:] >= 0.0))[0]
213
+ if flips.size == 0:
214
+ raise ValueError("no Gamma shape in [1e-3, 1e6] gives the interval its probability mass")
215
+ k = float(optimize.brentq(excess, float(grid[flips[0]]), float(grid[flips[0] + 1]), xtol=1e-14, rtol=1e-14))
216
+ return GammaPrior(shape=k, rate=k / mean, mean=mean, interval=(lower, upper), interval_level=level)
217
+
218
+
219
+ def gamma_prior_from_scenarios(points: Sequence[ScenarioPoint], threshold: float, frequency_above_threshold: float,
220
+ basis_years: float, n_bootstrap: int = 1000, seed: int = 0,
221
+ interval_level: float = 0.9) -> GammaPrior:
222
+ """The mapping of the C17 scenario points to the expert input of Shevchenko and Wuthrich (decision D4).
223
+
224
+ (1) ``fit_tail_to_scenarios`` gives a GPD with tail index ``xi_s``; ``alpha_s = 1 / xi_s`` is the prior mean. (2) A
225
+ parametric bootstrap gives the expert interval: each exceedance frequency is redrawn as ``k / basis_years`` with
226
+ ``k`` Poisson with mean ``exceedance_frequency * basis_years`` (a count of 0 is replaced by 0.5), the GPD is
227
+ refitted (from the point estimate as the start), and
228
+ the 5th and 95th percentiles of ``alpha`` over ``n_bootstrap`` replications
229
+ (``numpy.random.Generator(PCG64(seed))``) form the interval of mass ``interval_level``. (3)
230
+ ``gamma_prior_from_mean_interval`` solves the Gamma shape and rate.
231
+ ``basis_years`` is the number of years of experience each scenario frequency is worth (a policy parameter of the
232
+ caller). Deterministic for the same ``seed``; the prior is never truncated to ``alpha`` above 1. ``ValueError`` when
233
+ a point is worth less than one expected event in the basis years (``exceedance_frequency * basis_years < 1``: most
234
+ redraws are then 0 and the refits collapse onto the search bound), when the point estimate or any bootstrap
235
+ replicate sits on the search bound of the least squares fit (the share is named; a bound is never put into the
236
+ percentiles), and when a replicate's redrawn frequency reaches ``frequency_above_threshold``.
237
+ """
238
+ h, fa, pts = _scenario_inputs(points, threshold, frequency_above_threshold)
239
+ basis = positive(basis_years, "basis_years")
240
+ level = scalar(interval_level, "interval_level")
241
+ if not 0.0 < level < 1.0:
242
+ raise ValueError(f"interval_level must lie in (0, 1), got {level}")
243
+ if int(n_bootstrap) != n_bootstrap or n_bootstrap < 2:
244
+ raise ValueError(f"n_bootstrap must be an integer of at least 2, got {n_bootstrap}")
245
+ if int(seed) != seed or seed < 0:
246
+ raise ValueError(f"seed must be a non-negative integer, got {seed}")
247
+ freq = np.array([p.exceedance_frequency for p in pts])
248
+ if np.any(freq * basis < 1.0):
249
+ raise ValueError("every scenario point must be worth at least one expected event in basis_years "
250
+ f"(exceedance_frequency * basis_years >= 1); the smallest is "
251
+ f"{float(np.min(freq * basis)):.3g}")
252
+ base = fit_tail_to_scenarios(pts, h, fa)
253
+ if not base.converged:
254
+ raise ValueError("the scenario fit sits on the search bound: the points do not define a tail")
255
+ alpha_s = 1.0 / base.params[0]
256
+ u = np.array([p.loss - h for p in pts])
257
+ rng = np.random.Generator(np.random.PCG64(int(seed)))
258
+ alphas = np.empty(int(n_bootstrap))
259
+ on_bound = 0
260
+ for b in range(int(n_bootstrap)):
261
+ counts = rng.poisson(freq * basis)
262
+ redrawn = np.where(counts == 0, 0.5, counts) / basis
263
+ xi_b, beta_b, _ = _fit_scenario_gpd(_conditional(redrawn, fa), u, starts=(), warm=tuple(base.params[:2]))
264
+ on_bound += _on_search_bound(xi_b, beta_b, u)
265
+ alphas[b] = 1.0 / xi_b
266
+ if on_bound:
267
+ raise ValueError(f"{on_bound} of {int(n_bootstrap)} bootstrap refits sit on the search bound: the interval "
268
+ "would end at the bound, not at a statistic; raise basis_years or use more frequent points")
269
+ lo, hi = (float(v) for v in np.percentile(alphas, [50.0 * (1.0 - level), 50.0 * (1.0 + level)]))
270
+ return gamma_prior_from_mean_interval(alpha_s, lo, hi, level)
271
+
272
+
273
+ @dataclass(frozen=True)
274
+ class CredibilityFit:
275
+ """The posterior of the Pareto shape given the tail data: ``posterior_shape`` and ``posterior_rate`` (the Gamma
276
+ posterior), ``alpha_mean`` its mean, ``alpha_mle = n / sum ln(x_i / L)`` (None when ``n = 0``),
277
+ ``credibility_weight`` ``w = sum ln(x_i / L) / (sum ln(x_i / L) + rate)`` (Shevchenko and Wuthrich eq. 25) with
278
+ ``alpha_mean = w alpha_mle + (1 - w) prior.mean``; ``xi = 1 / alpha_mean``, ``beta = xi L`` and ``location = L``
279
+ (EUR) the GPD that is the one-parameter Pareto with shape ``alpha_mean`` above ``L``; ``infinite_mean`` is
280
+ ``alpha_mean <= 1`` (a tail index of
281
+ 1 or more); ``n`` the number of excesses."""
282
+
283
+ prior: GammaPrior
284
+ posterior_shape: float
285
+ posterior_rate: float
286
+ alpha_mean: float
287
+ alpha_mle: float | None
288
+ credibility_weight: float
289
+ xi: float
290
+ beta: float
291
+ location: float
292
+ infinite_mean: bool
293
+ n: int
294
+
295
+
296
+ def credibility_pareto(prior: GammaPrior, losses: np.ndarray, threshold: float) -> CredibilityFit:
297
+ """Bayesian credibility of the one-parameter Pareto ``f(x | alpha) = (alpha / L)(x / L)^(-alpha - 1)`` for ``x >=
298
+ L`` with the Gamma(``shape``, ``rate``) prior on ``alpha``: the Gamma posterior has shape ``shape + N`` and rate
299
+ ``rate + sum ln(x_i / L)`` (Shevchenko and Wuthrich 2006, section 3.3, eqs. 21 to 25), whose mean is the credibility
300
+ weighting of the maximum likelihood estimate and the prior mean. ``N = 0`` returns the prior. The prior is
301
+ unrestricted, so ``alpha_mean`` may be 1 or below and then ``infinite_mean`` is true and no mean-based number
302
+ follows. Raises when a loss is below ``threshold`` or when ``sum ln(x_i / L) = 0`` with ``N > 0``.
303
+ """
304
+ if not isinstance(prior, GammaPrior):
305
+ raise ValueError("prior must be a GammaPrior")
306
+ big_l = positive(threshold, "threshold")
307
+ x = vec(losses, "losses", allow_empty=True)
308
+ if np.any(x < big_l):
309
+ raise ValueError("a loss lies below the threshold")
310
+ n = int(x.size)
311
+ s = float(np.sum(np.log(x / big_l))) if n else 0.0
312
+ if n and not s > 0.0:
313
+ raise ValueError("every loss equals the threshold: sum ln(x / L) = 0, the shape cannot be updated")
314
+ shape, rate = prior.shape + n, prior.rate + s
315
+ alpha_mean = shape / rate
316
+ xi = 1.0 / alpha_mean
317
+ return CredibilityFit(prior=prior, posterior_shape=shape, posterior_rate=rate, alpha_mean=alpha_mean,
318
+ alpha_mle=(n / s if n else None), credibility_weight=s / (s + prior.rate), xi=xi,
319
+ beta=xi * big_l, location=big_l, infinite_mean=bool(alpha_mean <= 1.0), n=n)
320
+
321
+
322
+ # ----------------------------------------------------------------------------------------------------------------
323
+ # the scenario influence function
324
+
325
+
326
+ def scenario_influence(points: Sequence[ScenarioPoint],
327
+ capital_fn: Callable[[Sequence[ScenarioPoint]], float]) -> np.ndarray:
328
+ """``influence_i = (capital(all) - capital(all without i)) / capital(all)``, dimensionless, ``(P,)``. ``capital_fn``
329
+ maps a set of scenario points to the 99.9 percent capital in EUR (the caller closes over the losses, the threshold
330
+ and the
331
+ prior weight); it is called ``P + 1`` times. Raises when ``capital(all) <= 0``."""
332
+ pts = list(points)
333
+ if not pts:
334
+ raise ValueError("no scenario points")
335
+ base = scalar(capital_fn(list(pts)), "capital(all)")
336
+ if base <= 0.0:
337
+ raise ValueError(f"capital(all) must be positive, got {base}")
338
+ out = np.empty(len(pts))
339
+ for i in range(len(pts)):
340
+ without = scalar(capital_fn(pts[:i] + pts[i + 1:]), f"capital(without {i})")
341
+ out[i] = (base - without) / base
342
+ return out
@@ -0,0 +1,80 @@
1
+ """The single loss approximation (SLA) of dossier 05 F.4.
2
+
3
+ For a subexponential severity ``F`` and a frequency with ``sum_n (1 + eps)^n P(N = n) < infinity``,
4
+ ``1 - H(z) ~ E[N] (1 - F(z))`` as ``z -> infinity`` (Embrechts, Kluppelberg and Mikosch 1997, Theorem 1.3.9, as cited by
5
+ Shevchenko eq. 69), hence ``VaR_alpha[Z] ~ F^{-1}(1 - (1 - alpha) / E[N])`` (Shevchenko eq. 70; Bocker and Kluppelberg
6
+ 2005, Risk 18(12):90-93). Shevchenko shows that it converges for heavy tails and is poor for LN(0, 1) at practical
7
+ quantiles.
8
+
9
+ The mean-corrected form ``F^{-1}(1 - (1 - alpha) / E[N]) + E[N] E[X]`` is the "commonly quoted corrected form" of
10
+ dossier 05 F.4, which was **not checked** against Bocker and Sprittulla, "Operational VaR: meaningful means" (Risk 2006)
11
+ or Degen (J. Operational Risk 5(4):3-17, 2010): it is UNVERIFIED, and its result says so. A severity with an infinite
12
+ mean (a GPD tail index of 1 or more) has no correction: the function raises. Contract: ``engine-oprisk-api`` 1.0.0,
13
+ module sla.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import math
19
+ from collections.abc import Sequence
20
+ from dataclasses import dataclass
21
+
22
+ import numpy as np
23
+
24
+ from riskvalidation.oprisk._checks import level_in_open_unit, positive
25
+ from riskvalidation.oprisk.distributions import severity_isf, severity_moment
26
+
27
+
28
+ def sla_var(frequency_mean: float, sev_law: str, sev_params: Sequence[float], level: float) -> float:
29
+ """``F^{-1}(1 - (1 - level) / E[N])`` in EUR (Shevchenko eq. 70). Raises when ``E[N] <= 1 - level`` (the argument of
30
+ ``F^{-1}`` would not be in (0, 1)); nondecreasing in ``E[N]`` and in ``level``."""
31
+ en = positive(frequency_mean, "frequency_mean")
32
+ level = level_in_open_unit(level)
33
+ tail = (1.0 - level) / en
34
+ if not tail < 1.0:
35
+ raise ValueError(f"E[N] = {en} is not above 1 - level = {1.0 - level}: the single loss approximation is "
36
+ "undefined")
37
+ return float(severity_isf(sev_law, sev_params, np.array([tail]))[0])
38
+
39
+
40
+ def sla_var_poisson_gpd(lam: float, xi: float, beta: float, level: float, location: float = 0.0) -> float:
41
+ """``location + beta / xi ((lam / (1 - level))^xi - 1)``: the closed form for a Poisson count and a GPD severity
42
+ (dossier 05 F.4); it scales like ``lam^xi``. Equal to ``sla_var(lam, "gpd", (xi, beta, location), level)``."""
43
+ lam = positive(lam, "lam")
44
+ xi = positive(xi, "xi")
45
+ beta = positive(beta, "beta")
46
+ level = level_in_open_unit(level)
47
+ ratio = lam / (1.0 - level)
48
+ if not ratio > 1.0:
49
+ raise ValueError(f"lam = {lam} is not above 1 - level = {1.0 - level}: the approximation is undefined")
50
+ return float(location) + beta / xi * math.expm1(xi * math.log(ratio))
51
+
52
+
53
+ @dataclass(frozen=True)
54
+ class SlaResult:
55
+ """The mean-corrected single loss approximation, in EUR: ``var = var_first_order + mean_correction``. ``status`` is
56
+ always ``"UNVERIFIED"``: the corrected form was not checked against its primary text (dossier 05 F.4), and the
57
+ result says so."""
58
+
59
+ level: float
60
+ var_first_order: float
61
+ mean_correction: float
62
+ var: float
63
+ status: str
64
+
65
+
66
+ def sla_var_mean_corrected(frequency_mean: float, sev_law: str, sev_params: Sequence[float], level: float) -> SlaResult:
67
+ """The first-order SLA plus ``E[N] E[X]`` (UNVERIFIED: dossier 05 F.4 did not check this form against Bocker and
68
+ Sprittulla 2006 or Degen 2010; a changed form is a new minor version of the contract).
69
+
70
+ Raises ``ValueError("infinite mean")`` when the severity mean is infinite (a GPD tail index of 1 or more): the
71
+ correction does not exist, and the C17 bake then writes the rung as null with that reason.
72
+ """
73
+ first = sla_var(frequency_mean, sev_law, sev_params, level)
74
+ mean = severity_moment(sev_law, sev_params, 1)
75
+ if math.isinf(mean):
76
+ raise ValueError("infinite mean: the severity has no mean (tail index of 1 or more), so the mean correction "
77
+ "does not exist")
78
+ correction = float(frequency_mean) * mean
79
+ return SlaResult(level=float(level), var_first_order=first, mean_correction=correction, var=first + correction,
80
+ status="UNVERIFIED")
@@ -0,0 +1,169 @@
1
+ """The Basel III standardised approach of OPE25 (dossier 01 section F; OPE25 in force 2023-01-01, published 2024-07-05;
2
+ the version in force 2027-01-01 only rewords OPE25.10 and OPE25.27(5), formulas unchanged).
3
+
4
+ ``ORC = BIC x ILM`` and ``RWA_op = 12.5 x ORC`` (OPE25.2); ``BI = ILDC + SC + FC`` (OPE25.4);
5
+ ``ILDC = min(avg |II - IE|, 2.25% x avg IEA) + avg DI``, ``SC = max(avg OOI, avg OOE) + max(avg FI, avg FE)``,
6
+ ``FC = avg |Net P&L_TB| + avg |Net P&L_BB|``, a bar being the three-year average over ``t, t-1, t-2`` with the absolute
7
+ values of net items taken year by year before averaging (OPE25.5 and footnote 1); the BIC with the marginal coefficients
8
+ 12 percent to EUR 1bn, 15 percent from 1bn to 30bn and 18 percent above (OPE25.7 Table 1); ``ILM = ln(exp(1) - 1 +
9
+ (LC / BIC)^0.8)`` with ``LC = 15 x`` the average annual operational risk losses over the previous 10 years (OPE25.8);
10
+ ILM = 1 when LC = BIC and ILM > 1 when LC > BIC (OPE25.9). Loss data rules and discretions: 10 years of high-quality
11
+ loss data, a transitional minimum of 5 years, and under 5 years the capital is the BIC only (OPE25.10, OPE25.15); losses
12
+ net of recoveries (FAQ1 to OPE25.10); bucket 1 banks have ILM = 1 unless national discretion allows inclusion, and
13
+ supervisors may set ILM = 1 for all banks of the jurisdiction (OPE25.11); collection threshold EUR 20,000, national
14
+ discretion EUR 100,000 for buckets 2 and 3 (OPE25.18).
15
+
16
+ The engine computes and states no compliance claim; disclosures stay the caller's. Money is in the caller's currency
17
+ (the thresholds of the buckets are in EUR). Contract: ``engine-oprisk-api`` 1.0.0, module sma.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import math
23
+ from dataclasses import dataclass
24
+
25
+ import numpy as np
26
+
27
+ from riskvalidation.oprisk._checks import scalar, vec
28
+
29
+ BUCKET_1_LIMIT = 1e9
30
+ BUCKET_2_LIMIT = 30e9
31
+ COEFFICIENTS = (0.12, 0.15, 0.18)
32
+ ILDC_CAP = 0.0225
33
+ LC_MULTIPLE = 15.0
34
+ ILM_EXPONENT = 0.8
35
+ RWA_FACTOR = 12.5
36
+ OPE25_MINIMUM_YEARS = 5
37
+
38
+
39
+ def _three(x: np.ndarray, name: str) -> np.ndarray:
40
+ a = vec(x, name)
41
+ if a.size != 3:
42
+ raise ValueError(f"{name} must hold the 3 years t, t-1, t-2, got {a.size}")
43
+ return a
44
+
45
+
46
+ def ildc(ii: np.ndarray, ie: np.ndarray, iea: np.ndarray, di: np.ndarray) -> float:
47
+ """``min(mean(|ii - ie|), 0.0225 mean(iea)) + mean(di)`` (OPE25.5), the absolute value taken year by year."""
48
+ ii, ie, iea, di = _three(ii, "ii"), _three(ie, "ie"), _three(iea, "iea"), _three(di, "di")
49
+ return float(min(np.mean(np.abs(ii - ie)), ILDC_CAP * np.mean(iea)) + np.mean(di))
50
+
51
+
52
+ def service_component(ooi: np.ndarray, ooe: np.ndarray, fi: np.ndarray, fe: np.ndarray) -> float:
53
+ """``max(mean(ooi), mean(ooe)) + max(mean(fi), mean(fe))`` (OPE25.5)."""
54
+ ooi, ooe, fi, fe = _three(ooi, "ooi"), _three(ooe, "ooe"), _three(fi, "fi"), _three(fe, "fe")
55
+ return float(max(np.mean(ooi), np.mean(ooe)) + max(np.mean(fi), np.mean(fe)))
56
+
57
+
58
+ def financial_component(pl_tb: np.ndarray, pl_bb: np.ndarray) -> float:
59
+ """``mean(|pl_tb|) + mean(|pl_bb|)`` with the absolute value taken year by year (OPE25.5 footnote 1)."""
60
+ return float(np.mean(np.abs(_three(pl_tb, "pl_tb"))) + np.mean(np.abs(_three(pl_bb, "pl_bb"))))
61
+
62
+
63
+ def business_indicator(ildc_value: float, sc_value: float, fc_value: float) -> float:
64
+ """``BI = ILDC + SC + FC`` (OPE25.4); a negative component raises."""
65
+ parts = (scalar(ildc_value, "ildc_value"), scalar(sc_value, "sc_value"), scalar(fc_value, "fc_value"))
66
+ if min(parts) < 0.0:
67
+ raise ValueError("the components of the business indicator must not be negative")
68
+ return float(sum(parts))
69
+
70
+
71
+ def _bi(bi: float) -> float:
72
+ v = scalar(bi, "bi")
73
+ if v < 0.0:
74
+ raise ValueError(f"bi must not be negative, got {v}")
75
+ return v
76
+
77
+
78
+ def bic_bucket(bi: float) -> int:
79
+ """1 for ``bi <= 1e9``, 2 for ``1e9 < bi <= 30e9``, 3 above (OPE25.7 Table 1)."""
80
+ v = _bi(bi)
81
+ return 1 if v <= BUCKET_1_LIMIT else 2 if v <= BUCKET_2_LIMIT else 3
82
+
83
+
84
+ def bic(bi: float) -> float:
85
+ """``0.12 min(bi, 1e9) + 0.15 (min(bi, 30e9) - 1e9)^+ + 0.18 (bi - 30e9)^+`` (OPE25.7 Table 1)."""
86
+ v = _bi(bi)
87
+ c1, c2, c3 = COEFFICIENTS
88
+ middle = max(min(v, BUCKET_2_LIMIT) - BUCKET_1_LIMIT, 0.0)
89
+ return c1 * min(v, BUCKET_1_LIMIT) + c2 * middle + c3 * max(v - BUCKET_2_LIMIT, 0.0)
90
+
91
+
92
+ def loss_component(annual_losses: np.ndarray, window_years: int = 10) -> float:
93
+ """``LC = 15 x`` the mean of the most recent ``window_years`` annual losses (net of recoveries, oldest first;
94
+ OPE25.8).
95
+ The minimum-years rule is applied by ``sma_capital``, not here."""
96
+ x = vec(annual_losses, "annual_losses")
97
+ if int(window_years) != window_years or window_years < 1:
98
+ raise ValueError(f"window_years must be a positive integer, got {window_years}")
99
+ if np.any(x < 0.0):
100
+ raise ValueError("annual losses must not be negative")
101
+ return float(LC_MULTIPLE * np.mean(x[-int(window_years):]))
102
+
103
+
104
+ def ilm(loss_component_value: float, bic_value: float) -> float:
105
+ """``ILM = ln(e - 1 + (LC / BIC)^0.8)`` (OPE25.8); exactly 1 when ``LC = BIC`` (OPE25.9)."""
106
+ lc, b = scalar(loss_component_value, "loss_component_value"), scalar(bic_value, "bic_value")
107
+ if b <= 0.0:
108
+ raise ValueError("bic_value must be positive")
109
+ if lc < 0.0:
110
+ raise ValueError("loss_component_value must not be negative")
111
+ return math.log(math.e - 1.0 + (lc / b) ** ILM_EXPONENT)
112
+
113
+
114
+ @dataclass(frozen=True)
115
+ class SmaResult:
116
+ """The standardised approach for one bank: money fields in EUR; ``basis`` is ``"bic-times-ilm"`` or ``"bic-only"``;
117
+ ``discretion_applied`` is ``"none"``, ``"bucket-1-ilm-one"``, ``"national-ilm-one"`` or ``"transitional-bic-only"``;
118
+ ``rwa = 12.5 x orc``. ``basis == "bic-only"`` exactly when ``loss_component`` and ``ilm`` are None, ``reason`` is a
119
+ string and the discretion is ``"transitional-bic-only"``."""
120
+
121
+ bi: float
122
+ bic: float
123
+ bucket: int
124
+ years_used: int
125
+ basis: str
126
+ loss_component: float | None
127
+ ilm: float | None
128
+ discretion_applied: str
129
+ orc: float
130
+ rwa: float
131
+ reason: str | None
132
+
133
+
134
+ def sma_capital(bi: float, annual_losses: np.ndarray, bucket1_uses_losses: bool = False, national_ilm_one: bool = False,
135
+ minimum_years: int = 5, window_years: int = 10) -> SmaResult:
136
+ """Operational risk capital of OPE25: ``ORC = BIC x ILM``, ``RWA = 12.5 ORC``.
137
+
138
+ Order of the rules: (1) fewer than ``minimum_years`` years of loss data: the capital is the BIC only (OPE25.10,
139
+ OPE25.15), no LC and no ILM, a reason, discretion ``transitional-bic-only`` (never an ILM on too little data);
140
+ (2) ``national_ilm_one``: ILM = 1, discretion ``national-ilm-one`` (OPE25.11; disclosure stays the caller's);
141
+ (3) bucket 1 and not ``bucket1_uses_losses``: ILM = 1, discretion ``bucket-1-ilm-one`` (OPE25.11); (4) otherwise
142
+ ``ILM = ilm(LC, BIC)``. In (2) and (3) the loss component is still computed and reported. ``minimum_years`` below 5
143
+ raises (5 years is the transitional minimum of OPE25.15; a national discretion would be a different, explicit
144
+ function).
145
+ """
146
+ b = _bi(bi)
147
+ x = vec(annual_losses, "annual_losses", allow_empty=True)
148
+ if int(minimum_years) != minimum_years or minimum_years < OPE25_MINIMUM_YEARS:
149
+ raise ValueError(f"minimum_years must be an integer of at least {OPE25_MINIMUM_YEARS} (the transitional "
150
+ f"minimum of OPE25.15), got {minimum_years}: an ILM on fewer years is unreachable through "
151
+ "this function")
152
+ bic_value = bic(b)
153
+ bucket = bic_bucket(b)
154
+ years = int(x.size)
155
+ if years < minimum_years:
156
+ reason = (f"{years} years of loss data, fewer than the {int(minimum_years)} required (OPE25.10, OPE25.15): "
157
+ "the capital is the business indicator component only")
158
+ return SmaResult(b, bic_value, bucket, years, "bic-only", None, None, "transitional-bic-only", bic_value,
159
+ RWA_FACTOR * bic_value, reason)
160
+ lc = loss_component(x, window_years)
161
+ used = min(years, int(window_years))
162
+ if national_ilm_one:
163
+ value, discretion = 1.0, "national-ilm-one"
164
+ elif bucket == 1 and not bucket1_uses_losses:
165
+ value, discretion = 1.0, "bucket-1-ilm-one"
166
+ else:
167
+ value, discretion = ilm(lc, bic_value), "none"
168
+ orc = bic_value * value
169
+ return SmaResult(b, bic_value, bucket, used, "bic-times-ilm", lc, value, discretion, orc, RWA_FACTOR * orc, None)
@@ -0,0 +1,4 @@
1
+ """Packaged validation policies (JSON).
2
+
3
+ Thresholds are policy choices, documented per test, never regulation.
4
+ """