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,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)
|