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,469 @@
|
|
|
1
|
+
"""The LGD and EAD validation tests (dossier 04 F.3 and G.3): each returns one `TestResult`.
|
|
2
|
+
|
|
3
|
+
Acceptance gates are Contraste internal gates, stated as such, not regulatory thresholds. Each function states its light
|
|
4
|
+
rule in its docstring and records its parameters in `policy_version`, in `alpha_amber` and `alpha_red` where a
|
|
5
|
+
p-value is
|
|
6
|
+
used, and in `extras["thresholds"]` for the other parameters (`rho_green`, `rho_amber`, `gap_amber`, `gap_red`,
|
|
7
|
+
`tolerance`), so that a view can explain a light. A test that cannot be evaluated returns the light `not_evaluated` with
|
|
8
|
+
its reason in `notes` and a null statistic, p-value and metric once serialised, never a fabricated number. LGD
|
|
9
|
+
calibration
|
|
10
|
+
is judged by mean realised against mean predicted by segment and over time, not by R2 alone.
|
|
11
|
+
|
|
12
|
+
The tests are plain functions that do not read the registry or the default policy: their rules are the contract's
|
|
13
|
+
(`engine-lgd-ead-api`, module validation.lgd_ead). They state no compliance claim.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import math
|
|
19
|
+
from collections.abc import Mapping
|
|
20
|
+
from typing import Any
|
|
21
|
+
|
|
22
|
+
import numpy as np
|
|
23
|
+
from scipy import stats
|
|
24
|
+
|
|
25
|
+
from riskvalidation.core.hashing import inputs_hash
|
|
26
|
+
from riskvalidation.core.registry import register
|
|
27
|
+
from riskvalidation.core.result import Light, TestResult
|
|
28
|
+
from riskvalidation.lgd_ead._checks import same_length, scalar, vec
|
|
29
|
+
|
|
30
|
+
POLICY_LABEL = "contraste-lgd-ead-battery-1.0.0"
|
|
31
|
+
NAN = float("nan")
|
|
32
|
+
ZERO_SPREAD = 1e-12 # a spread or a mean below this (relative to max(1, the largest value)) is zero
|
|
33
|
+
EPS = 1e-12 # tolerance on a gate comparison, so that a value exactly on a gate is not moved by rounding
|
|
34
|
+
|
|
35
|
+
LOTERMAN_2012 = (
|
|
36
|
+
"Loterman, Brown, Martens, Mues and Baesens (2012), Benchmarking regression algorithms for loss given default "
|
|
37
|
+
"modeling, Int. J. Forecasting 28(1):161-170, doi:10.1016/j.ijforecast.2011.01.006"
|
|
38
|
+
)
|
|
39
|
+
QI_ZHAO_2011 = (
|
|
40
|
+
"Qi and Zhao (2011), Comparison of modeling methods for Loss Given Default, J. Banking and Finance "
|
|
41
|
+
"35(11):2842-2855, doi:10.1016/j.jbankfin.2011.03.011"
|
|
42
|
+
)
|
|
43
|
+
TONG_2016 = (
|
|
44
|
+
"Tong, Mues, Brown and Thomas (2016), Exposure at default models with and without the credit conversion factor, "
|
|
45
|
+
"EJOR 252(3):910-920, doi:10.1016/j.ejor.2016.01.054"
|
|
46
|
+
)
|
|
47
|
+
QI_2009 = (
|
|
48
|
+
"Qi (2009), Exposure at default of unsecured credit cards, OCC Economics Working Paper 2009-2, "
|
|
49
|
+
"https://www.occ.gov/publications-and-resources/publications/economics/working-papers-archived/"
|
|
50
|
+
"pub-econ-working-paper-2009-2.pdf"
|
|
51
|
+
)
|
|
52
|
+
EBA_DOWNTURN = (
|
|
53
|
+
"EBA/GL/2019/03 and EBA/RTS/2018/04 are cross-references only; the add-on is Contraste's cohort-based one "
|
|
54
|
+
"(dossier 04 F.4)"
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _version(**params: Any) -> str:
|
|
59
|
+
return "; ".join([POLICY_LABEL, *(f"{k}={v}" for k, v in params.items())])
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _not_evaluated(test_id: str, h0: str, alternative: str, reference: str, version: str, reason: str, *,
|
|
63
|
+
model_id: str | None = None, segment: str | None = None, n: int | None = None,
|
|
64
|
+
alpha_amber: float | None = None, alpha_red: float | None = None,
|
|
65
|
+
extras: Mapping[str, Any] | None = None) -> TestResult:
|
|
66
|
+
"""No number is carried: the statistic is NaN (null once serialised), the metric and the p-value are None."""
|
|
67
|
+
return TestResult(
|
|
68
|
+
test_id=test_id, h0=h0, alternative=alternative, reference=reference, policy_version=version,
|
|
69
|
+
light=Light.NOT_EVALUATED, statistic=NAN, notes=f"not evaluated: {reason}", model_id=model_id,
|
|
70
|
+
segment=segment, n=n, alpha_amber=alpha_amber, alpha_red=alpha_red, extras=dict(extras or {}),
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _check_alphas(alpha_amber: float, alpha_red: float) -> None:
|
|
75
|
+
if not (0.0 < alpha_red <= alpha_amber < 1.0):
|
|
76
|
+
raise ValueError(f"alpha_red and alpha_amber must satisfy 0 < alpha_red <= alpha_amber < 1, got "
|
|
77
|
+
f"{alpha_red} and {alpha_amber}")
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _p_light(p: float, alpha_amber: float, alpha_red: float) -> Light:
|
|
81
|
+
if p >= alpha_amber:
|
|
82
|
+
return Light.GREEN
|
|
83
|
+
return Light.AMBER if p >= alpha_red else Light.RED
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _scale(d: np.ndarray) -> float:
|
|
87
|
+
return ZERO_SPREAD * max(1.0, float(np.max(np.abs(d))))
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _no_spread(d: np.ndarray) -> bool:
|
|
91
|
+
return float(np.std(d, ddof=1)) <= _scale(d)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _zero_mean(d: np.ndarray) -> bool:
|
|
95
|
+
return abs(float(d.mean())) <= _scale(d)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _paired_t(d: np.ndarray) -> tuple[float, float, float, float]:
|
|
99
|
+
"""(t, two-sided p, mean, standard error) of a sample of gaps with at least 2 values and a nonzero spread."""
|
|
100
|
+
n = d.size
|
|
101
|
+
mean = float(d.mean())
|
|
102
|
+
se = float(np.std(d, ddof=1)) / math.sqrt(n)
|
|
103
|
+
t = mean / se
|
|
104
|
+
return t, float(2.0 * stats.t.sf(abs(t), n - 1)), mean, se
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
# ----------------------------------------------------------------------------------------------------------------
|
|
108
|
+
# LGD calibration and discrimination
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
@register(
|
|
112
|
+
"lgd_ead.lgd_calibration_by_segment",
|
|
113
|
+
family="lgd_ead",
|
|
114
|
+
name="LGD calibration by segment",
|
|
115
|
+
h0="the mean realised LGD equals the mean predicted LGD in the segment",
|
|
116
|
+
reference=f"{LOTERMAN_2012}; {QI_ZHAO_2011}; dossier 04 F.3 (calibration by segment, not R2 alone)",
|
|
117
|
+
decision="p_value",
|
|
118
|
+
)
|
|
119
|
+
def lgd_calibration_by_segment(realised: np.ndarray, predicted: np.ndarray, segment: str | None = None,
|
|
120
|
+
model_id: str | None = None, alpha_amber: float = 0.05,
|
|
121
|
+
alpha_red: float = 0.01) -> TestResult:
|
|
122
|
+
"""The mean realised LGD against the mean predicted LGD of one segment: a paired t of d = realised - predicted.
|
|
123
|
+
|
|
124
|
+
statistic = mean(d) / (sd(d) / sqrt(N)) with N - 1 degrees of freedom (sd with ddof = 1), p_value two-sided,
|
|
125
|
+
metric = mean(d). extras: mean_realised, mean_predicted, ci_low and ci_high (95% interval of the mean gap), and the
|
|
126
|
+
counts of realised values below 0 and above 1 (kept, not clipped). N < 2: not_evaluated. No spread in d: red with a
|
|
127
|
+
null statistic and p_value and the gap in the metric when mean(d) is not zero (a certain gap), green when it is
|
|
128
|
+
zero.
|
|
129
|
+
Light (a Contraste internal gate): green when p_value >= `alpha_amber`, amber when `alpha_red` <= p_value <
|
|
130
|
+
`alpha_amber`, red below `alpha_red`.
|
|
131
|
+
"""
|
|
132
|
+
test_id = "lgd_ead.lgd_calibration_by_segment"
|
|
133
|
+
reference = f"{LOTERMAN_2012}; {QI_ZHAO_2011}; dossier 04 F.3 (calibration by segment, not R2 alone)"
|
|
134
|
+
h0 = "the mean realised LGD equals the mean predicted LGD in the segment"
|
|
135
|
+
alt = "the mean realised LGD differs from the mean predicted LGD"
|
|
136
|
+
_check_alphas(alpha_amber, alpha_red)
|
|
137
|
+
real, pred = vec(realised, "realised", allow_empty=True), vec(predicted, "predicted", allow_empty=True)
|
|
138
|
+
same_length(realised=real, predicted=pred)
|
|
139
|
+
version = _version(alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
140
|
+
n = int(real.size)
|
|
141
|
+
kw = dict(model_id=model_id, segment=segment, n=n, alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
142
|
+
if n < 2:
|
|
143
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "fewer than 2 observations", **kw)
|
|
144
|
+
d = real - pred
|
|
145
|
+
mean = float(d.mean())
|
|
146
|
+
extras: dict[str, Any] = {
|
|
147
|
+
"mean_realised": float(real.mean()), "mean_predicted": float(pred.mean()),
|
|
148
|
+
"n_below_zero": int((real < 0.0).sum()), "n_above_one": int((real > 1.0).sum()),
|
|
149
|
+
}
|
|
150
|
+
common = dict(test_id=test_id, h0=h0, alternative=alt, reference=reference, policy_version=version,
|
|
151
|
+
inputs_hash=inputs_hash(real, pred), **kw)
|
|
152
|
+
if _no_spread(d):
|
|
153
|
+
extras.update(ci_low=mean, ci_high=mean, note="no spread in the gaps: the gap is certain")
|
|
154
|
+
zero = _zero_mean(d)
|
|
155
|
+
return TestResult(light=Light.GREEN if zero else Light.RED, metric=0.0 if zero else mean, extras=extras,
|
|
156
|
+
notes="no spread in the gaps (sd = 0): " + ("no gap" if zero else "a certain gap"), **common)
|
|
157
|
+
t, p, mean, se = _paired_t(d)
|
|
158
|
+
half = float(stats.t.ppf(0.975, n - 1)) * se
|
|
159
|
+
extras.update(ci_low=mean - half, ci_high=mean + half)
|
|
160
|
+
return TestResult(light=_p_light(p, alpha_amber, alpha_red), statistic=t, p_value=p, metric=mean, extras=extras,
|
|
161
|
+
**common)
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
@register(
|
|
165
|
+
"lgd_ead.lgd_calibration_over_time",
|
|
166
|
+
family="lgd_ead",
|
|
167
|
+
name="LGD calibration over time",
|
|
168
|
+
h0="in every period the mean realised LGD equals the mean predicted LGD",
|
|
169
|
+
reference=f"{LOTERMAN_2012}; {QI_ZHAO_2011}; dossier 04 F.3 (calibration over time)",
|
|
170
|
+
decision="p_value",
|
|
171
|
+
)
|
|
172
|
+
def lgd_calibration_over_time(realised: np.ndarray, predicted: np.ndarray, period: np.ndarray,
|
|
173
|
+
model_id: str | None = None, alpha_amber: float = 0.05,
|
|
174
|
+
alpha_red: float = 0.01) -> TestResult:
|
|
175
|
+
"""The paired t of the segment test per period (a default year or a cohort index) with at least 2 observations and a
|
|
176
|
+
nonzero spread. statistic = the largest |t| over those periods, p_value = min(1, K p_min) (Bonferroni, K the periods
|
|
177
|
+
tested), metric = the largest |mean(d)| over every period with at least one observation (tested or not).
|
|
178
|
+
extras["periods"] lists period, n, mean_gap, t and p of each period (t and p null where not tested) and
|
|
179
|
+
extras["excluded"] each period not tested with its period, n and reason. A period with zero spread and mean(d) not
|
|
180
|
+
zero makes the light red (with a null statistic and p_value when no period was tested); no period tested and no such
|
|
181
|
+
period: not_evaluated. Light (a Contraste internal gate): as `lgd_calibration_by_segment`, on the adjusted p_value.
|
|
182
|
+
"""
|
|
183
|
+
test_id = "lgd_ead.lgd_calibration_over_time"
|
|
184
|
+
reference = f"{LOTERMAN_2012}; {QI_ZHAO_2011}; dossier 04 F.3 (calibration over time)"
|
|
185
|
+
h0 = "in every period the mean realised LGD equals the mean predicted LGD"
|
|
186
|
+
alt = "in at least one period the mean realised LGD differs from the mean predicted LGD"
|
|
187
|
+
_check_alphas(alpha_amber, alpha_red)
|
|
188
|
+
real, pred = vec(realised, "realised", allow_empty=True), vec(predicted, "predicted", allow_empty=True)
|
|
189
|
+
per = np.array(period)
|
|
190
|
+
if per.ndim != 1 or (per.size and per.dtype.kind not in "iu"):
|
|
191
|
+
raise ValueError("period must be a one-dimensional integer array")
|
|
192
|
+
same_length(realised=real, predicted=pred, period=per)
|
|
193
|
+
version = _version(alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
194
|
+
n = int(real.size)
|
|
195
|
+
kw = dict(model_id=model_id, n=n, alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
196
|
+
rows: list[dict[str, Any]] = []
|
|
197
|
+
excluded: list[dict[str, Any]] = []
|
|
198
|
+
tested: list[dict[str, Any]] = []
|
|
199
|
+
certain_gap = False
|
|
200
|
+
d_all = real - pred
|
|
201
|
+
for key in np.unique(per):
|
|
202
|
+
d = d_all[per == key]
|
|
203
|
+
row: dict[str, Any] = {"period": int(key), "n": int(d.size), "mean_gap": float(d.mean()), "t": None, "p": None}
|
|
204
|
+
if d.size < 2:
|
|
205
|
+
excluded.append({"period": int(key), "n": int(d.size), "reason": "fewer than 2 observations"})
|
|
206
|
+
elif _no_spread(d):
|
|
207
|
+
excluded.append({"period": int(key), "n": int(d.size), "reason": "zero spread"})
|
|
208
|
+
certain_gap = certain_gap or not _zero_mean(d)
|
|
209
|
+
else:
|
|
210
|
+
t, p, mean, _ = _paired_t(d)
|
|
211
|
+
row.update(t=t, p=p)
|
|
212
|
+
tested.append(row)
|
|
213
|
+
rows.append(row)
|
|
214
|
+
extras: dict[str, Any] = {"periods": rows, "excluded": excluded, "n_periods_tested": len(tested)}
|
|
215
|
+
if not tested and not certain_gap:
|
|
216
|
+
return _not_evaluated(test_id, h0, alt, reference, version,
|
|
217
|
+
"no period with at least 2 observations and a nonzero spread", extras=extras, **kw)
|
|
218
|
+
common = dict(test_id=test_id, h0=h0, alternative=alt, reference=reference, policy_version=version,
|
|
219
|
+
inputs_hash=inputs_hash(real, pred, per), extras=extras, **kw)
|
|
220
|
+
metric = max(abs(r["mean_gap"]) for r in rows)
|
|
221
|
+
if not tested:
|
|
222
|
+
return TestResult(light=Light.RED, metric=metric,
|
|
223
|
+
notes="no period with a spread; a period with zero spread has a certain gap", **common)
|
|
224
|
+
p_adj = min(1.0, len(tested) * min(r["p"] for r in tested))
|
|
225
|
+
light = Light.RED if certain_gap else _p_light(p_adj, alpha_amber, alpha_red)
|
|
226
|
+
return TestResult(light=light, statistic=max(abs(r["t"]) for r in tested), p_value=p_adj, metric=metric,
|
|
227
|
+
notes="a period with zero spread has a certain gap" if certain_gap else "", **common)
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
@register(
|
|
231
|
+
"lgd_ead.lgd_discrimination",
|
|
232
|
+
family="lgd_ead",
|
|
233
|
+
name="LGD rank discrimination",
|
|
234
|
+
h0="predicted and realised LGD are rank-independent",
|
|
235
|
+
reference=f"{LOTERMAN_2012}; Spearman (1904), doi:10.2307/1412159",
|
|
236
|
+
decision="metric",
|
|
237
|
+
)
|
|
238
|
+
def lgd_discrimination(realised: np.ndarray, predicted: np.ndarray, segment: str | None = None,
|
|
239
|
+
model_id: str | None = None, rho_green: float = 0.30, rho_amber: float = 0.10) -> TestResult:
|
|
240
|
+
"""The Spearman rank correlation of predicted and realised LGD (ties by average rank).
|
|
241
|
+
|
|
242
|
+
statistic = metric = rho in [-1, 1], p_value the two-sided p of the rank correlation. N < 3 or a constant input:
|
|
243
|
+
not_evaluated. Light (a Contraste internal gate, not a regulatory one; LGD rank power is modest in the
|
|
244
|
+
literature, R2
|
|
245
|
+
between 4% and 43% in Loterman et al. 2012): green when rho >= `rho_green`, amber when `rho_amber` <= rho <
|
|
246
|
+
`rho_green`, red below. extras["thresholds"] carries `rho_green` and `rho_amber`.
|
|
247
|
+
"""
|
|
248
|
+
test_id = "lgd_ead.lgd_discrimination"
|
|
249
|
+
reference = f"{LOTERMAN_2012}; Spearman (1904), doi:10.2307/1412159"
|
|
250
|
+
h0 = "predicted and realised LGD are rank-independent"
|
|
251
|
+
alt = "predicted and realised LGD are rank-correlated"
|
|
252
|
+
if not rho_amber <= rho_green:
|
|
253
|
+
raise ValueError(f"rho_amber must not exceed rho_green, got {rho_amber} and {rho_green}")
|
|
254
|
+
real, pred = vec(realised, "realised", allow_empty=True), vec(predicted, "predicted", allow_empty=True)
|
|
255
|
+
same_length(realised=real, predicted=pred)
|
|
256
|
+
version = _version(rho_green=rho_green, rho_amber=rho_amber)
|
|
257
|
+
n = int(real.size)
|
|
258
|
+
kw = dict(model_id=model_id, segment=segment, n=n)
|
|
259
|
+
extras = {"thresholds": {"rho_green": float(rho_green), "rho_amber": float(rho_amber)}}
|
|
260
|
+
if n < 3:
|
|
261
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "fewer than 3 observations", extras=extras, **kw)
|
|
262
|
+
if np.ptp(real) == 0.0 or np.ptp(pred) == 0.0:
|
|
263
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "constant input (no rank variation)",
|
|
264
|
+
extras=extras, **kw)
|
|
265
|
+
res = stats.spearmanr(real, pred)
|
|
266
|
+
rho, p = float(res.statistic), float(res.pvalue)
|
|
267
|
+
if not math.isfinite(rho):
|
|
268
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "the rank correlation is undefined",
|
|
269
|
+
extras=extras, **kw)
|
|
270
|
+
if rho >= rho_green - EPS:
|
|
271
|
+
light = Light.GREEN
|
|
272
|
+
elif rho >= rho_amber - EPS:
|
|
273
|
+
light = Light.AMBER
|
|
274
|
+
else:
|
|
275
|
+
light = Light.RED
|
|
276
|
+
return TestResult(
|
|
277
|
+
test_id=test_id, h0=h0, alternative=alt, reference=reference, policy_version=version, light=light,
|
|
278
|
+
statistic=rho, p_value=min(1.0, max(0.0, p)), metric=rho, inputs_hash=inputs_hash(real, pred), extras=extras,
|
|
279
|
+
**kw,
|
|
280
|
+
)
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
# ----------------------------------------------------------------------------------------------------------------
|
|
284
|
+
# downturn coverage
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
@register(
|
|
288
|
+
"lgd_ead.downturn_coverage",
|
|
289
|
+
family="lgd_ead",
|
|
290
|
+
name="Downturn coverage",
|
|
291
|
+
h0="the mean realised downturn LGD does not exceed the downturn LGD estimate",
|
|
292
|
+
reference=f"{EBA_DOWNTURN}; {LOTERMAN_2012}",
|
|
293
|
+
decision="p_value",
|
|
294
|
+
)
|
|
295
|
+
def downturn_coverage(estimate: float, realised_downturn: np.ndarray, segment: str | None = None,
|
|
296
|
+
model_id: str | None = None, alpha_amber: float = 0.05, alpha_red: float = 0.01) -> TestResult:
|
|
297
|
+
"""Does the downturn LGD estimate cover the realised LGD of the defaults in the downturn period?
|
|
298
|
+
|
|
299
|
+
h0: the mean realised downturn LGD does not exceed the estimate; alternative: it does. statistic = (mean(realised) -
|
|
300
|
+
estimate) / (sd / sqrt(N)), one-sided upper p_value with N - 1 degrees of freedom, metric = max(0, mean(realised) -
|
|
301
|
+
estimate) (the shortfall of `downturn.coverage_shortfall`). N < 2: not_evaluated. No spread: red with a null
|
|
302
|
+
statistic and p_value and the shortfall in the metric when there is a shortfall, green when there is none.
|
|
303
|
+
Light (a Contraste internal gate): green when p_value >= `alpha_amber`, amber when `alpha_red` <= p_value <
|
|
304
|
+
`alpha_amber`, red below `alpha_red`. The downturn period is the caller's (a supplied macro path); no regulatory
|
|
305
|
+
approach is claimed.
|
|
306
|
+
"""
|
|
307
|
+
test_id = "lgd_ead.downturn_coverage"
|
|
308
|
+
reference = f"{EBA_DOWNTURN}; {LOTERMAN_2012}"
|
|
309
|
+
h0 = "the mean realised downturn LGD does not exceed the downturn LGD estimate"
|
|
310
|
+
alt = "the mean realised downturn LGD exceeds the estimate (the estimate does not cover the downturn losses)"
|
|
311
|
+
_check_alphas(alpha_amber, alpha_red)
|
|
312
|
+
est = scalar(estimate, "estimate")
|
|
313
|
+
real = vec(realised_downturn, "realised_downturn", allow_empty=True)
|
|
314
|
+
version = _version(alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
315
|
+
n = int(real.size)
|
|
316
|
+
kw = dict(model_id=model_id, segment=segment, n=n, alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
317
|
+
if n < 2:
|
|
318
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "fewer than 2 observations", **kw)
|
|
319
|
+
gap = float(real.mean()) - est
|
|
320
|
+
extras = {"estimate": est, "mean_realised": float(real.mean())}
|
|
321
|
+
common = dict(test_id=test_id, h0=h0, alternative=alt, reference=reference, policy_version=version,
|
|
322
|
+
inputs_hash=inputs_hash(est, real), extras=extras, **kw)
|
|
323
|
+
if _no_spread(real):
|
|
324
|
+
shortfall = gap > _scale(real)
|
|
325
|
+
return TestResult(light=Light.RED if shortfall else Light.GREEN, metric=max(0.0, gap) if shortfall else 0.0,
|
|
326
|
+
notes="no spread in the realised downturn LGD (sd = 0): "
|
|
327
|
+
+ ("a certain shortfall" if shortfall else "no shortfall"), **common)
|
|
328
|
+
t = gap / (float(np.std(real, ddof=1)) / math.sqrt(n))
|
|
329
|
+
p = float(stats.t.sf(t, n - 1))
|
|
330
|
+
return TestResult(light=_p_light(p, alpha_amber, alpha_red), statistic=t, p_value=p, metric=max(0.0, gap), **common)
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
# ----------------------------------------------------------------------------------------------------------------
|
|
334
|
+
# EAD back-test and CCF estimator bias
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
@register(
|
|
338
|
+
"lgd_ead.ead_backtest_by_band",
|
|
339
|
+
family="lgd_ead",
|
|
340
|
+
name="EAD backtest by band",
|
|
341
|
+
h0="the predicted EAD equals the realised EAD in every utilisation band",
|
|
342
|
+
reference=f"{TONG_2016}; {QI_2009}; dossier 04 G.3 (back-test in currency by utilisation band)",
|
|
343
|
+
decision="metric",
|
|
344
|
+
)
|
|
345
|
+
def ead_backtest_by_band(predicted_ead: np.ndarray, realised_ead: np.ndarray, utilisation: np.ndarray,
|
|
346
|
+
band_edges: np.ndarray, model_id: str | None = None, gap_amber: float = 0.10,
|
|
347
|
+
gap_red: float = 0.25) -> TestResult:
|
|
348
|
+
"""Predicted against realised EAD in currency, by utilisation band (not only as a CCF; dossier 04 G.3).
|
|
349
|
+
|
|
350
|
+
Bands are [edge_i, edge_i+1), the last closed; a utilisation outside the edges raises. Per band gap =
|
|
351
|
+
sum(predicted) -
|
|
352
|
+
sum(realised) and relative_gap = gap / sum(realised); statistic = the relative gap of the total (null when the total
|
|
353
|
+
realised EAD is 0), metric = max over the bands of |relative_gap|, p_value null; extras["bands"] lists lower,
|
|
354
|
+
upper, n,
|
|
355
|
+
predicted_ead, realised_ead, gap and relative_gap (null for a band with no observation, which does not enter the
|
|
356
|
+
metric; null relative_gap and a listed gap for a band whose realised EAD is 0, which does not enter it either).
|
|
357
|
+
Every band empty, or no band with a realised EAD: not_evaluated. Light (a Contraste internal gate): green when
|
|
358
|
+
metric
|
|
359
|
+
<= `gap_amber`, amber when metric <= `gap_red`, red above. extras["thresholds"] carries `gap_amber` and `gap_red`.
|
|
360
|
+
"""
|
|
361
|
+
test_id = "lgd_ead.ead_backtest_by_band"
|
|
362
|
+
reference = f"{TONG_2016}; {QI_2009}; dossier 04 G.3 (back-test in currency by utilisation band)"
|
|
363
|
+
h0 = "the predicted EAD equals the realised EAD in every utilisation band"
|
|
364
|
+
alt = "the predicted EAD differs from the realised EAD in at least one utilisation band"
|
|
365
|
+
if not 0.0 <= gap_amber <= gap_red:
|
|
366
|
+
raise ValueError(f"gap_amber and gap_red must satisfy 0 <= gap_amber <= gap_red, got {gap_amber} and {gap_red}")
|
|
367
|
+
pred = vec(predicted_ead, "predicted_ead", allow_empty=True)
|
|
368
|
+
real = vec(realised_ead, "realised_ead", allow_empty=True)
|
|
369
|
+
util = vec(utilisation, "utilisation", allow_empty=True)
|
|
370
|
+
same_length(predicted_ead=pred, realised_ead=real, utilisation=util)
|
|
371
|
+
edges = vec(band_edges, "band_edges")
|
|
372
|
+
if edges.size < 2 or np.any(np.diff(edges) <= 0.0):
|
|
373
|
+
raise ValueError("band_edges must hold at least 2 strictly increasing values")
|
|
374
|
+
if np.any(real < 0.0):
|
|
375
|
+
raise ValueError("realised_ead must be non-negative") # a predicted EAD may be negative (utilisation change)
|
|
376
|
+
if util.size and (util.min() < edges[0] or util.max() > edges[-1]):
|
|
377
|
+
raise ValueError(f"utilisation must lie within the band edges [{edges[0]}, {edges[-1]}]")
|
|
378
|
+
version = _version(gap_amber=gap_amber, gap_red=gap_red)
|
|
379
|
+
n = int(pred.size)
|
|
380
|
+
kw = dict(model_id=model_id, n=n)
|
|
381
|
+
thresholds = {"thresholds": {"gap_amber": float(gap_amber), "gap_red": float(gap_red)}}
|
|
382
|
+
if n == 0:
|
|
383
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "no observation", extras=thresholds, **kw)
|
|
384
|
+
nb = edges.size - 1
|
|
385
|
+
idx = np.minimum(np.searchsorted(edges, util, side="right") - 1, nb - 1)
|
|
386
|
+
bands: list[dict[str, Any]] = []
|
|
387
|
+
rels: list[float] = []
|
|
388
|
+
for b in range(nb):
|
|
389
|
+
m = idx == b
|
|
390
|
+
row: dict[str, Any] = {"lower": float(edges[b]), "upper": float(edges[b + 1]), "n": int(m.sum()),
|
|
391
|
+
"predicted_ead": None, "realised_ead": None, "gap": None, "relative_gap": None}
|
|
392
|
+
if m.any():
|
|
393
|
+
p_sum, r_sum = float(pred[m].sum()), float(real[m].sum())
|
|
394
|
+
row.update(predicted_ead=p_sum, realised_ead=r_sum, gap=p_sum - r_sum)
|
|
395
|
+
if r_sum > 0.0:
|
|
396
|
+
row["relative_gap"] = (p_sum - r_sum) / r_sum
|
|
397
|
+
rels.append(abs(row["relative_gap"]))
|
|
398
|
+
bands.append(row)
|
|
399
|
+
extras = {"bands": bands, **thresholds}
|
|
400
|
+
total_real = float(real.sum())
|
|
401
|
+
if not rels:
|
|
402
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "the realised EAD is zero in every band",
|
|
403
|
+
extras=extras, **kw)
|
|
404
|
+
metric = max(rels)
|
|
405
|
+
light = Light.GREEN if metric <= gap_amber + EPS else Light.AMBER if metric <= gap_red + EPS else Light.RED
|
|
406
|
+
statistic = (float(pred.sum()) - total_real) / total_real if total_real > 0.0 else NAN
|
|
407
|
+
return TestResult(
|
|
408
|
+
test_id=test_id, h0=h0, alternative=alt, reference=reference, policy_version=version, light=light,
|
|
409
|
+
statistic=statistic, metric=metric, inputs_hash=inputs_hash(pred, real, util, edges), extras=extras, **kw,
|
|
410
|
+
)
|
|
411
|
+
|
|
412
|
+
|
|
413
|
+
@register(
|
|
414
|
+
"lgd_ead.ccf_estimator_bias",
|
|
415
|
+
family="lgd_ead",
|
|
416
|
+
name="CCF estimator bias",
|
|
417
|
+
h0="the estimator is unbiased (the mean estimate equals the known CCF)",
|
|
418
|
+
reference=f"{TONG_2016}; {QI_2009}; dossier 04 G.1 to G.3 (the CCF estimators and their reference-date designs)",
|
|
419
|
+
decision="metric",
|
|
420
|
+
)
|
|
421
|
+
def ccf_estimator_bias(estimates: np.ndarray, truth: float, tolerance: float, model_id: str | None = None,
|
|
422
|
+
alpha_amber: float = 0.05, alpha_red: float = 0.01) -> TestResult:
|
|
423
|
+
"""The bias of a CCF estimator against the known CCF of the C09 generator, over R independent replications.
|
|
424
|
+
|
|
425
|
+
With e = estimates - truth: metric = mean(e) (the bias, equal to `ccf.ccf_bias(mean(estimates), truth)`),
|
|
426
|
+
statistic =
|
|
427
|
+
mean(e) / (sd(e) / sqrt(R)), p_value two-sided with R - 1 degrees of freedom; extras: rmse, ci_low, ci_high
|
|
428
|
+
(null for
|
|
429
|
+
R < 2), within_tolerance and thresholds (`tolerance`). R < 2 or no spread leaves the statistic and p_value null; the
|
|
430
|
+
light depends only on |metric| against the tolerance and is kept for R >= 1; R < 1 is not_evaluated. Light (a
|
|
431
|
+
Contraste internal gate): green when |metric| <= `tolerance`, amber when |metric| <= 2 `tolerance`, red above; the
|
|
432
|
+
p-value is informative (a statistically significant bias inside the tolerance stays green, and the view shows both).
|
|
433
|
+
"""
|
|
434
|
+
test_id = "lgd_ead.ccf_estimator_bias"
|
|
435
|
+
reference = f"{TONG_2016}; {QI_2009}; dossier 04 G.1 to G.3 (the CCF estimators and their reference-date designs)"
|
|
436
|
+
h0 = "the estimator is unbiased (the mean estimate equals the known CCF)"
|
|
437
|
+
alt = "the estimator is biased (the mean estimate differs from the known CCF)"
|
|
438
|
+
_check_alphas(alpha_amber, alpha_red)
|
|
439
|
+
est = vec(estimates, "estimates", allow_empty=True)
|
|
440
|
+
tr = scalar(truth, "truth")
|
|
441
|
+
tol = scalar(tolerance, "tolerance")
|
|
442
|
+
if tol < 0.0:
|
|
443
|
+
raise ValueError(f"tolerance must be non-negative, got {tolerance!r}")
|
|
444
|
+
version = _version(tolerance=tol, alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
445
|
+
r = int(est.size)
|
|
446
|
+
kw = dict(model_id=model_id, n=r, alpha_amber=alpha_amber, alpha_red=alpha_red)
|
|
447
|
+
thresholds = {"tolerance": tol}
|
|
448
|
+
if r < 1:
|
|
449
|
+
return _not_evaluated(test_id, h0, alt, reference, version, "no replication",
|
|
450
|
+
extras={"thresholds": thresholds}, **kw)
|
|
451
|
+
e = est - tr
|
|
452
|
+
mean = float(e.mean())
|
|
453
|
+
ab = abs(mean)
|
|
454
|
+
light = Light.GREEN if ab <= tol + EPS else Light.AMBER if ab <= 2.0 * tol + EPS else Light.RED
|
|
455
|
+
extras: dict[str, Any] = {"rmse": float(math.sqrt(np.mean(e * e))), "ci_low": None, "ci_high": None,
|
|
456
|
+
"within_tolerance": bool(ab <= tol + EPS), "truth": tr, "thresholds": thresholds}
|
|
457
|
+
common = dict(test_id=test_id, h0=h0, alternative=alt, reference=reference, policy_version=version, light=light,
|
|
458
|
+
metric=mean, inputs_hash=inputs_hash(est, tr, tol), **kw)
|
|
459
|
+
if r < 2:
|
|
460
|
+
return TestResult(extras=extras, notes="fewer than 2 replications: no statistic and no p-value", **common)
|
|
461
|
+
if _no_spread(e):
|
|
462
|
+
extras.update(ci_low=mean, ci_high=mean)
|
|
463
|
+
return TestResult(extras=extras,
|
|
464
|
+
notes="no spread across the replications (sd = 0): no statistic and no p-value",
|
|
465
|
+
**common)
|
|
466
|
+
t, p, mean, se = _paired_t(e)
|
|
467
|
+
half = float(stats.t.ppf(0.975, r - 1)) * se
|
|
468
|
+
extras.update(ci_low=mean - half, ci_high=mean + half)
|
|
469
|
+
return TestResult(statistic=t, p_value=p, extras=extras, **common)
|