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,529 @@
1
+ """PD curve calibration (Tasche 2013, "The art of probability-of-default curve calibration", Journal of Credit Risk
2
+ 9(4):63-103, doi:10.21314/jcr.2013.169, arXiv 1212.3716).
3
+
4
+ A rating model is the joint distribution of a borrower's grade X at the start of a period and its state at the end
5
+ (default D or survival N). The unconditional rating profile Pr[X = x] and the PD curve Pr[D | X = x] fix it; so do the
6
+ unconditional PD p with the two conditional profiles Pr[X = x | D] and Pr[X = x | N], or p with the likelihood ratio
7
+ lambda(x) = Pr[X = x | N] / Pr[X = x | D] (Proposition 3.1, equation 3.8). Calibrating a PD curve to a forecast period
8
+ (subscript 1) from an estimation period (subscript 0) means choosing which of these stays invariant, and the choice
9
+ depends on what is known at the start of the forecast period (section 4):
10
+
11
+ - case 1, the forecast rating profile and PD known (4.2): invariant default profile (4.2, implemented as approach ii of
12
+ 4.2.1), invariant accuracy ratio (4.3, section 4.2.2), scaled PDs (4.4, 4.7a), scaled likelihood ratio (4.5, 4.8a to
13
+ 4.8d);
14
+ - case 2, only the forecast PD known (4.3): invariant likelihood ratio (4.10, 4.11), Elkan's change in base rate;
15
+ - case 3, only the forecast rating profile known (4.4): invariant PD curve (4.12, 4.13), invariant conditional profiles
16
+ fitted by least squares (4.14b) or least chi-square, then (4.15, 4.16), and invariant likelihood ratio (4.10 with the
17
+ PD of theorem 3.3).
18
+
19
+ Quasi moment matching (appendix A) smooths a PD curve: the robust logistic curve Pr[D | X = x] = 1 / (1 + exp(alpha +
20
+ beta Phi^{-1}(F~_N(x)))) (A.8), F~_N the average of the survival distribution function and its left-continuous version
21
+ (A.9), with alpha and beta chosen so that the unconditional PD (3.5a) and the accuracy ratio (A.11b) hit their targets;
22
+ the binormal model gives the initial values (A.2c, A.2d, A.6).
23
+
24
+ The goodness of fit of a calibrated curve is tested with Pearson's chi-square test (Pearson 1900): of the implied
25
+ default profile against the observed default numbers, with a Monte Carlo p-value (the registered test
26
+ ``pd.default_profile``), and of an implied rating profile against the observed grade frequencies (:func:`profile_chi2`).
27
+
28
+ Grades are passed best first, as the paper's tables list them; internally the paper's numbering is used (grade 1 the
29
+ least creditworthy). Every function refuses, with :class:`ImproperModel`, a model that is not a proper joint
30
+ distribution of grade and state.
31
+ """
32
+
33
+ from __future__ import annotations
34
+
35
+ import math
36
+ from collections.abc import Sequence
37
+
38
+ import numpy as np
39
+ from scipy import optimize, stats
40
+ from scipy.special import ndtri
41
+
42
+ TASCHE_2013 = (
43
+ "Tasche (2013), The art of probability-of-default curve calibration, Journal of Credit Risk 9(4), "
44
+ "doi:10.21314/jcr.2013.169"
45
+ )
46
+ _EPS = float(np.finfo(float).eps)
47
+
48
+
49
+ class ImproperModel(ValueError):
50
+ """The approach yields no proper joint distribution of grade and state for these inputs."""
51
+
52
+
53
+ # ---------------------------------------------------------------------------------------------------------------------
54
+ # validation and ordering helpers; arrays named *_w are worst first (the paper's numbering)
55
+
56
+
57
+ def _w(a: Sequence[float]) -> np.ndarray:
58
+ return np.asarray(a, dtype=float)[::-1]
59
+
60
+
61
+ def _b(a: np.ndarray) -> list[float]:
62
+ return [float(v) for v in np.asarray(a)[::-1]]
63
+
64
+
65
+ def _profile(a: Sequence[float], what: str = "a profile") -> np.ndarray:
66
+ x = np.asarray(a, dtype=float)
67
+ if x.ndim != 1 or x.size < 2 or not np.all(np.isfinite(x)) or np.any(x < 0) or x.sum() <= 0:
68
+ raise ValueError(f"{what} needs at least two non-negative weights with a positive sum")
69
+ return x / x.sum()
70
+
71
+
72
+ def _curve(a: Sequence[float], *, open_interval: bool = True) -> np.ndarray:
73
+ c = np.asarray(a, dtype=float)
74
+ bad = (c <= 0) | (c >= 1) if open_interval else (c < 0) | (c > 1)
75
+ if c.ndim != 1 or c.size < 2 or not np.all(np.isfinite(c)) or np.any(bad):
76
+ span = "(0, 1)" if open_interval else "[0, 1]"
77
+ raise ValueError(f"a PD curve needs one PD in {span} per grade, at least two grades")
78
+ return c
79
+
80
+
81
+ def _rate(p: float, what: str = "the unconditional PD") -> float:
82
+ if not 0.0 < p < 1.0:
83
+ raise ValueError(f"{what} must lie in (0, 1)")
84
+ return float(p)
85
+
86
+
87
+ def _same_length(*arrays: np.ndarray) -> None:
88
+ if len({a.size for a in arrays}) != 1:
89
+ raise ValueError("every per-grade input needs one value per grade")
90
+
91
+
92
+ def _ar_profiles(dp_w: np.ndarray, sp_w: np.ndarray) -> float:
93
+ """(3.7): sum_{x>=2} P(x | N) P(X <= x - 1 | D) - sum_{x<=k-1} P(x | N) P(X >= x + 1 | D)."""
94
+ below = np.concatenate([[0.0], np.cumsum(dp_w)[:-1]])
95
+ above = np.concatenate([np.cumsum(dp_w[::-1])[::-1][1:], [0.0]])
96
+ return float(np.sum(sp_w * below) - np.sum(sp_w * above))
97
+
98
+
99
+ def _ar_curve(cur_w: np.ndarray, pi_w: np.ndarray) -> float:
100
+ """(A.11b), the accuracy ratio from a PD curve on a finite grade scale."""
101
+ p = float(np.sum(cur_w * pi_w))
102
+ riskier = np.concatenate([[0.0], np.cumsum(cur_w * pi_w)[:-1]]) # sum_{t < x} Pr[D | t] Pr[X = t]
103
+ total = 2.0 * np.sum((1.0 - cur_w) * pi_w * riskier) + np.sum(cur_w * (1.0 - cur_w) * pi_w**2)
104
+ return float(total / (p * (1.0 - p)) - 1.0)
105
+
106
+
107
+ def _f_tilde(sp_w: np.ndarray) -> np.ndarray:
108
+ """(A.9): the average of Pr[X < x | N] and Pr[X <= x | N]."""
109
+ c = np.cumsum(sp_w)
110
+ return (np.concatenate([[0.0], c[:-1]]) + c) / 2.0
111
+
112
+
113
+ # ---------------------------------------------------------------------------------------------------------------------
114
+ # section 3: the model and its identities
115
+
116
+
117
+ def model_from_counts(obligors: Sequence[int], defaults: Sequence[int]) -> dict:
118
+ """The empirical model of one period from grade counts (best first): the rating profile, the grade default rates,
119
+ the unconditional default rate, the conditional profiles and the accuracy ratio by (3.7)."""
120
+ n = np.asarray(obligors, dtype=float)
121
+ d = np.asarray(defaults, dtype=float)
122
+ if n.ndim != 1 or n.size < 2 or n.shape != d.shape:
123
+ raise ValueError("obligors and defaults are one count per grade, at least two grades")
124
+ if np.any(n <= 0) or np.any(d < 0) or np.any(d > n) or d.sum() <= 0 or d.sum() >= n.sum():
125
+ raise ValueError("each grade needs obligors > 0 and 0 <= defaults <= obligors, with defaults and survivors")
126
+ dp, sp = d / d.sum(), (n - d) / (n - d).sum()
127
+ return {
128
+ "profile": [float(v) for v in n / n.sum()],
129
+ "default_rate": [float(v) for v in d / n],
130
+ "pd": float(d.sum() / n.sum()),
131
+ "default_profile": [float(v) for v in dp],
132
+ "survival_profile": [float(v) for v in sp],
133
+ "accuracy_ratio": _ar_profiles(dp[::-1], sp[::-1]),
134
+ "obligors": int(n.sum()),
135
+ "defaults": int(d.sum()),
136
+ }
137
+
138
+
139
+ def unconditional_pd(pd_curve: Sequence[float], profile: Sequence[float]) -> float:
140
+ """(3.5a): p = sum_x Pr[D | X = x] Pr[X = x]."""
141
+ c, pi = _curve(pd_curve, open_interval=False), _profile(profile)
142
+ _same_length(c, pi)
143
+ return float(np.sum(c * pi))
144
+
145
+
146
+ def implied_default_profile(pd_curve: Sequence[float], profile: Sequence[float]) -> list[float]:
147
+ """(3.5b): Pr[X = x | D] = Pr[D | X = x] Pr[X = x] / p."""
148
+ c, pi = _curve(pd_curve, open_interval=False), _profile(profile)
149
+ _same_length(c, pi)
150
+ return [float(v) for v in c * pi / np.sum(c * pi)]
151
+
152
+
153
+ def implied_survival_profile(pd_curve: Sequence[float], profile: Sequence[float]) -> list[float]:
154
+ """(3.5c): Pr[X = x | N] = (1 - Pr[D | X = x]) Pr[X = x] / (1 - p)."""
155
+ c, pi = _curve(pd_curve, open_interval=False), _profile(profile)
156
+ _same_length(c, pi)
157
+ return [float(v) for v in (1.0 - c) * pi / np.sum((1.0 - c) * pi)]
158
+
159
+
160
+ def accuracy_ratio(default_profile: Sequence[float], survival_profile: Sequence[float]) -> float:
161
+ """(3.7), the accuracy ratio from the conditional profiles (best first)."""
162
+ dp, sp = _profile(default_profile, "a default profile"), _profile(survival_profile, "a survival profile")
163
+ _same_length(dp, sp)
164
+ return _ar_profiles(dp[::-1], sp[::-1])
165
+
166
+
167
+ def accuracy_ratio_from_curve(pd_curve: Sequence[float], profile: Sequence[float]) -> float:
168
+ """(A.11b), the accuracy ratio from a PD curve and the rating profile (best first)."""
169
+ c, pi = _curve(pd_curve, open_interval=False), _profile(profile)
170
+ _same_length(c, pi)
171
+ p = float(np.sum(c * pi))
172
+ if not 0.0 < p < 1.0:
173
+ raise ValueError("the accuracy ratio needs an unconditional PD in (0, 1)")
174
+ return _ar_curve(c[::-1], pi[::-1])
175
+
176
+
177
+ def likelihood_ratio(pd_curve: Sequence[float], pd: float) -> list[float]:
178
+ """(3.9b): lambda(x) = (1 - Pr[D | X = x]) / Pr[D | X = x] * p / (1 - p)."""
179
+ c, p = _curve(pd_curve), _rate(pd)
180
+ return [float(v) for v in (1.0 - c) / c * p / (1.0 - p)]
181
+
182
+
183
+ def pd_curve_from_likelihood_ratio(likelihood: Sequence[float], pd: float) -> list[float]:
184
+ """(3.9a): Pr[D | X = x] = p / (p + (1 - p) lambda(x))."""
185
+ lam, p = np.asarray(likelihood, dtype=float), _rate(pd)
186
+ if lam.ndim != 1 or np.any(~np.isfinite(lam)) or np.any(lam <= 0):
187
+ raise ValueError("a likelihood ratio needs one positive value per grade")
188
+ return [float(v) for v in p / (p + (1.0 - p) * lam)]
189
+
190
+
191
+ def pd_from_likelihood_ratio(profile: Sequence[float], likelihood: Sequence[float]) -> float:
192
+ """Theorem 3.3: the unconditional PD p in [0, 1) solving 1 = sum_x Pr[X = x] / (p + (1 - p) lambda(x)) (3.11a).
193
+
194
+ For a non-constant likelihood ratio a solution exists if and only if sum_x Pr[X = x] / lambda(x) >= 1 and
195
+ sum_x Pr[X = x] lambda(x) > 1 (3.11b); it is unique, and it is 0 if and only if the first sum equals 1 (3.11c).
196
+ """
197
+ pi = _profile(profile)
198
+ lam = np.asarray(likelihood, dtype=float)
199
+ _same_length(pi, lam)
200
+ if np.any(~np.isfinite(lam)) or np.any(lam <= 0):
201
+ raise ValueError("a likelihood ratio needs one positive value per grade")
202
+ if np.ptp(lam) <= 1e-12 * float(np.max(lam)):
203
+ raise ValueError("a constant likelihood ratio does not determine the unconditional PD (theorem 3.3)")
204
+ inv, fwd = float(np.sum(pi / lam)), float(np.sum(pi * lam))
205
+ if inv < 1.0 - 1e-12 or fwd <= 1.0:
206
+ raise ImproperModel(
207
+ f"theorem 3.3: sum Pr[X = x] / lambda(x) = {inv:.6g} (needs >= 1) and sum Pr[X = x] lambda(x) = {fwd:.6g} "
208
+ "(needs > 1); no unconditional PD makes this profile and likelihood ratio a proper model"
209
+ )
210
+ if inv <= 1.0 + 1e-12:
211
+ return 0.0
212
+
213
+ def f(p: float) -> float:
214
+ return float(np.sum(pi / (p + (1.0 - p) * lam))) - 1.0
215
+
216
+ # f(0) > 0, f(1) = 0 and f'(1) = sum pi lambda - 1 > 0: the root sits where f turns negative short of 1
217
+ hi = 1.0 - 1e-3
218
+ while f(hi) >= 0.0:
219
+ hi = 1.0 - (1.0 - hi) / 1e3
220
+ if 1.0 - hi < 1e-15:
221
+ raise ImproperModel("theorem 3.3: no unconditional PD below 1 solves (3.11a) at double precision")
222
+ return float(optimize.brentq(f, 0.0, hi, xtol=1e-16, rtol=4 * _EPS))
223
+
224
+
225
+ # ---------------------------------------------------------------------------------------------------------------------
226
+ # appendix A: quasi moment matching
227
+
228
+
229
+ def _bracket(f, centre: float, *, width: float = 1.0, limit: int = 60) -> tuple[float, float]:
230
+ """An interval around ``centre`` on which the decreasing ``f`` changes sign, found by doubling its half-width."""
231
+ for _ in range(limit):
232
+ lo, hi = centre - width, centre + width
233
+ if f(lo) >= 0.0 >= f(hi):
234
+ return lo, hi
235
+ width *= 2.0
236
+ raise ImproperModel("no sign change found for a monotone equation; the targets are outside its range")
237
+
238
+
239
+ def qmm(
240
+ profile: Sequence[float],
241
+ pd_target: float,
242
+ ar_target: float,
243
+ survival_profile: Sequence[float] | None = None,
244
+ ) -> dict:
245
+ """Quasi moment matching (appendix A): the robust logistic PD curve (A.8) on the grades (best first) whose
246
+ unconditional PD (3.5a) is ``pd_target`` and whose accuracy ratio (A.11b) is ``ar_target``.
247
+
248
+ ``survival_profile`` (best first) defines F~_N (A.9); in the estimation period it is the empirical one (step 3 of
249
+ A.2: by (3.5c) from the profile, the grade default rates and the unconditional default rate). Without it the
250
+ unconditional profile stands in for it, as section 4.2.2 does in a forecast period where the survival profile
251
+ cannot be observed.
252
+ """
253
+ pi = _profile(profile)[::-1]
254
+ sp = _profile(survival_profile, "a survival profile")[::-1] if survival_profile is not None else pi
255
+ _same_length(pi, sp)
256
+ p = _rate(pd_target, "the target PD")
257
+ if not 0.0 < ar_target < 1.0:
258
+ raise ValueError("the target accuracy ratio must lie in (0, 1)")
259
+ z = ndtri(np.clip(_f_tilde(sp), 1e-15, 1.0 - 1e-15))
260
+
261
+ def curve(alpha: float, beta: float) -> np.ndarray:
262
+ return 1.0 / (1.0 + np.exp(np.clip(alpha + beta * z, -700.0, 700.0)))
263
+
264
+ # step 4: initial values from the binormal model (A.2c, A.2d, A.6), mu and tau^2 the mean and variance of
265
+ # Phi^{-1}(F~_N(X)) under the rating profile
266
+ mu = float(np.sum(pi * z))
267
+ tau2 = float(np.sum(pi * (z - mu) ** 2))
268
+ c = math.sqrt(2.0) * float(ndtri((ar_target + 1.0) / 2.0))
269
+ sigma2 = tau2 / (1.0 + p * (1.0 - p) * c**2)
270
+ sigma = math.sqrt(sigma2)
271
+ mu_n, mu_d = mu + p * sigma * c, mu - (1.0 - p) * sigma * c
272
+ start = ((mu_d**2 - mu_n**2) / (2.0 * sigma2) + math.log((1.0 - p) / p), (mu_n - mu_d) / sigma2)
273
+
274
+ # step 5: the two equations, solved as nested bracketed roots, which converge whenever a solution exists. For a
275
+ # slope beta the unconditional PD falls strictly as alpha grows (one root alpha(beta)); along alpha(beta) the
276
+ # accuracy ratio rises from 0 at beta = 0 towards the largest one the grade scale and profile allow.
277
+ def alpha_for(beta: float) -> float:
278
+ def f(a: float) -> float:
279
+ return float(np.sum(curve(a, beta) * pi)) - p
280
+
281
+ lo, hi = _bracket(f, start[0] + (start[1] - beta) * mu)
282
+ return float(optimize.brentq(f, lo, hi, xtol=1e-14, rtol=4 * _EPS))
283
+
284
+ def g(beta: float) -> float:
285
+ return _ar_curve(curve(alpha_for(beta), beta), pi) - ar_target
286
+
287
+ hi = max(start[1], 1e-3)
288
+ while g(hi) < 0.0:
289
+ hi *= 2.0
290
+ if hi > 1e4:
291
+ raise ImproperModel(
292
+ f"quasi moment matching: an accuracy ratio of {ar_target:.4g} is not attainable on this grade scale "
293
+ "and profile"
294
+ )
295
+ lo = hi / 2.0
296
+ while lo > 1e-12 and g(lo) > 0.0:
297
+ lo /= 2.0
298
+ beta = float(optimize.brentq(g, lo, hi, xtol=1e-14, rtol=4 * _EPS))
299
+ alpha = alpha_for(beta)
300
+ cur = curve(alpha, beta)
301
+ return {
302
+ "pd_curve": _b(cur),
303
+ "alpha": alpha,
304
+ "beta": beta,
305
+ "scores": _b(z),
306
+ "start": [float(v) for v in start],
307
+ "pd": float(np.sum(cur * pi)),
308
+ "accuracy_ratio": _ar_curve(cur, pi),
309
+ "reference": f"{TASCHE_2013}, appendix A",
310
+ }
311
+
312
+
313
+ # ---------------------------------------------------------------------------------------------------------------------
314
+ # section 4.2, case 1: the forecast rating profile and the forecast PD are known
315
+
316
+
317
+ def invariant_default_profile(default_profile_0: Sequence[float], profile_1: Sequence[float], pd_1: float) -> dict:
318
+ """Approach (4.2), Pr1[X = x | D] = Pr0[X = x | D], implemented as approach (ii) of section 4.2.1: the observed
319
+ estimation default profile and the forecast profile give a raw survival profile by (3.5c) with (4.6b), the two
320
+ give a forecast accuracy ratio by (3.7), and QMM fits the forecast curve to it and to ``pd_1``. Proper if and only
321
+ if p1 Pr0[X = x | D] <= Pr1[X = x] and p1 (1 - Pr0[X = x | D]) <= 1 - Pr1[X = x] for every grade (4.6a)."""
322
+ dp0, pi1 = _profile(default_profile_0, "a default profile"), _profile(profile_1)
323
+ _same_length(dp0, pi1)
324
+ p1 = _rate(pd_1, "the forecast PD")
325
+ tol = 1e-12
326
+ bad = np.flatnonzero((p1 * dp0 > pi1 + tol) | (p1 * (1.0 - dp0) > 1.0 - pi1 + tol))
327
+ if bad.size:
328
+ raise ImproperModel(
329
+ f"invariant default profile: condition (4.6a) fails at grade(s) {', '.join(str(int(i) + 1) for i in bad)} "
330
+ "(counted best first); no proper model keeps this default profile at this forecast PD"
331
+ )
332
+ raw = np.clip((pi1 - p1 * dp0) / (1.0 - p1), 0.0, None)
333
+ ar1 = _ar_profiles(dp0[::-1], raw[::-1] / raw.sum())
334
+ if not 0.0 < ar1 < 1.0:
335
+ raise ImproperModel(
336
+ f"invariant default profile: the implied forecast accuracy ratio {ar1:.4g} is not in (0, 1)"
337
+ )
338
+ out = qmm(pi1, p1, ar1, survival_profile=raw)
339
+ out.update(
340
+ {
341
+ "accuracy_ratio_target": ar1,
342
+ "raw_survival_profile": [float(v) for v in raw / raw.sum()],
343
+ "reference": f"{TASCHE_2013}, equations 4.2, 4.6a, 4.6b and section 4.2.1 (ii)",
344
+ }
345
+ )
346
+ return out
347
+
348
+
349
+ def invariant_accuracy_ratio(profile_1: Sequence[float], pd_1: float, ar_0: float) -> dict:
350
+ """Approach (4.3), AR1 = AR0: QMM to the forecast PD and the estimation accuracy ratio, the survival profile
351
+ approximated by the forecast unconditional profile (section 4.2.2)."""
352
+ out = qmm(profile_1, pd_1, ar_0)
353
+ out["reference"] = f"{TASCHE_2013}, equation 4.3 and section 4.2.2"
354
+ return out
355
+
356
+
357
+ def scaled_pds(pd_curve_0: Sequence[float], profile_1: Sequence[float], pd_1: float) -> dict:
358
+ """Approach (4.4), Pr1[D | X = x] = c_PD Pr0[D | X = x] with c_PD = p1 / sum_x Pr0[D | X = x] Pr1[X = x] (4.7a);
359
+ improper when a scaled PD exceeds one (section 4.2.3). The implied default profile is (4.7b)."""
360
+ c0, pi1 = _curve(pd_curve_0), _profile(profile_1)
361
+ _same_length(c0, pi1)
362
+ p1 = _rate(pd_1, "the forecast PD")
363
+ c_pd = p1 / float(np.sum(c0 * pi1))
364
+ cur = c_pd * c0
365
+ if np.any(cur >= 1.0):
366
+ raise ImproperModel(
367
+ f"scaled PDs: c_PD = {c_pd:.4g} lifts a grade's PD to {float(cur.max()):.4g}, which is not a probability"
368
+ )
369
+ return {
370
+ "pd_curve": [float(v) for v in cur],
371
+ "c_pd": c_pd,
372
+ "default_profile": [float(v) for v in cur * pi1 / p1],
373
+ "reference": f"{TASCHE_2013}, equations 4.4, 4.7a and 4.7b",
374
+ }
375
+
376
+
377
+ def scaled_likelihood_ratio(pd_curve_0: Sequence[float], pd_0: float, profile_1: Sequence[float], pd_1: float) -> dict:
378
+ """Approach (4.5), lambda1 = c_LR lambda0, with c_LR the root of 1 = sum_x Pr1[X = x] / (p1 + (1 - p1) c_LR
379
+ lambda0(x)) (4.8a). The right-hand side falls strictly from 1 / p1 to 0 as c_LR grows, so the root always exists
380
+ and is unique, and the model is always proper (section 4.2.4); it lies inside the bracket (4.8b). The curve is
381
+ (4.8d) and the default profile (4.8c)."""
382
+ lam0 = np.asarray(likelihood_ratio(pd_curve_0, pd_0))
383
+ pi1 = _profile(profile_1)
384
+ _same_length(lam0, pi1)
385
+ p1 = _rate(pd_1, "the forecast PD")
386
+ lo, hi = 1.0 / float(np.sum(pi1 * lam0)), float(np.sum(pi1 / lam0))
387
+
388
+ def f(c: float) -> float:
389
+ return float(np.sum(pi1 / (p1 + (1.0 - p1) * c * lam0))) - 1.0
390
+
391
+ c_lr = float(optimize.brentq(f, lo / 2.0, 2.0 * hi, xtol=1e-300, rtol=4 * _EPS))
392
+ denominator = p1 + (1.0 - p1) * c_lr * lam0
393
+ return {
394
+ "pd_curve": [float(v) for v in p1 / denominator],
395
+ "c_lr": c_lr,
396
+ "bracket": [lo, hi],
397
+ "default_profile": [float(v) for v in pi1 / denominator],
398
+ "reference": f"{TASCHE_2013}, equations 4.5 and 4.8a to 4.8d",
399
+ }
400
+
401
+
402
+ # ---------------------------------------------------------------------------------------------------------------------
403
+ # sections 4.3 and 4.4, cases 2 and 3: only the forecast PD, or only the forecast rating profile, is known
404
+
405
+
406
+ def invariant_likelihood_ratio(
407
+ pd_curve_0: Sequence[float],
408
+ pd_0: float,
409
+ *,
410
+ pd_1: float | None = None,
411
+ profile_1: Sequence[float] | None = None,
412
+ ) -> dict:
413
+ """Assumption (4.10), lambda1 = lambda0. Give exactly one of ``pd_1`` (case 2, section 4.3: the curve is (4.11),
414
+ Elkan's change in base rate) or ``profile_1`` (case 3, section 4.4.3: the forecast PD is the unique solution of
415
+ (3.11a) by theorem 3.3, which exists only under (3.11b), and then the curve is (4.11))."""
416
+ if (pd_1 is None) == (profile_1 is None):
417
+ raise ValueError("give exactly one of pd_1 (case 2) or profile_1 (case 3)")
418
+ lam0 = likelihood_ratio(pd_curve_0, pd_0)
419
+ if pd_1 is not None:
420
+ p1, ref = _rate(pd_1, "the forecast PD"), "equations 4.10 and 4.11 (case 2)"
421
+ else:
422
+ p1, ref = pd_from_likelihood_ratio(profile_1, lam0), "equation 4.10, theorem 3.3 and section 4.4.3 (case 3)"
423
+ if p1 <= 0.0:
424
+ raise ImproperModel("invariant likelihood ratio: theorem 3.3 gives a forecast PD of zero (3.11c)")
425
+ return {"pd_curve": pd_curve_from_likelihood_ratio(lam0, p1), "pd": p1, "reference": f"{TASCHE_2013}, {ref}"}
426
+
427
+
428
+ def invariant_pd_curve(pd_curve_0: Sequence[float], profile_1: Sequence[float]) -> dict:
429
+ """Assumption (4.12), Pr1[D | X = x] = Pr0[D | X = x]; the forecast PD follows from the forecast profile by (4.13).
430
+ Section 4.4.1 warns that this carries the estimation period's unconditional PD into the forecast."""
431
+ c0 = _curve(pd_curve_0)
432
+ return {
433
+ "pd_curve": [float(v) for v in c0],
434
+ "pd": unconditional_pd(c0, profile_1),
435
+ "reference": f"{TASCHE_2013}, equations 4.12 and 4.13",
436
+ }
437
+
438
+
439
+ def invariant_conditional_profiles(
440
+ default_profile_0: Sequence[float],
441
+ survival_profile_0: Sequence[float],
442
+ profile_1: Sequence[float],
443
+ *,
444
+ fit: str = "least_squares",
445
+ ) -> dict:
446
+ """Assumption (4.9), both conditional profiles invariant (case 3, section 4.4.2). The constraint (3.4a) is
447
+ overdetermined, so the forecast PD is fitted: by least squares, p1* by (4.14b), or by minimising the Pearson
448
+ chi-square distance of the forecast profile from p1 Pr0[X = x | D] + (1 - p1) Pr0[X = x | N] (``fit="least_chi2"``).
449
+ The implied rating profile is (4.15) and the curve (4.16); test the profile with :func:`profile_chi2` before using
450
+ the curve."""
451
+ dp0 = _profile(default_profile_0, "a default profile")
452
+ sp0 = _profile(survival_profile_0, "a survival profile")
453
+ pi1 = _profile(profile_1)
454
+ _same_length(dp0, sp0, pi1)
455
+ diff = dp0 - sp0
456
+ if not np.any(np.abs(diff) > 0):
457
+ raise ValueError("identical conditional profiles do not determine a forecast PD")
458
+ if fit == "least_squares":
459
+ p1 = float(np.clip(np.sum((pi1 - sp0) * diff) / np.sum(diff**2), 0.0, 1.0))
460
+ ref = "equations 4.9, 4.14b, 4.15 and 4.16"
461
+ elif fit == "least_chi2":
462
+
463
+ def distance(p: float) -> float:
464
+ e = p * dp0 + (1.0 - p) * sp0
465
+ return float(np.sum((pi1 - e) ** 2 / e))
466
+
467
+ res = optimize.minimize_scalar(distance, bounds=(1e-12, 1.0 - 1e-12), method="bounded",
468
+ options={"xatol": 1e-14, "maxiter": 2000})
469
+ p1 = float(res.x)
470
+ ref = "equations 4.9, 4.15 and 4.16, the least chi-square variant of 4.14b (section 4.4.2)"
471
+ else:
472
+ raise ValueError('fit is "least_squares" or "least_chi2"')
473
+ implied = p1 * dp0 + (1.0 - p1) * sp0
474
+ if not 0.0 < p1 < 1.0 or np.any(implied <= 0):
475
+ raise ImproperModel(f"invariant conditional profiles: the fitted forecast PD {p1:.4g} gives no proper model")
476
+ return {
477
+ "pd_curve": [float(v) for v in p1 * dp0 / implied],
478
+ "pd": p1,
479
+ "profile": [float(v) for v in implied],
480
+ "fit": fit,
481
+ "reference": f"{TASCHE_2013}, {ref}",
482
+ }
483
+
484
+
485
+ def profile_chi2(counts: Sequence[int], profile: Sequence[float]) -> dict:
486
+ """Pearson's chi-square test (Pearson 1900) of grade counts against a rating profile, with k - 1 degrees of
487
+ freedom: the check section 4.4.2 asks for before a profile implied by (4.15) is used; it gives the p-values of
488
+ Table 8."""
489
+ n = np.asarray(counts, dtype=float)
490
+ pi = _profile(profile)
491
+ _same_length(n, pi)
492
+ if np.any(n < 0) or n.sum() <= 0:
493
+ raise ValueError("counts need non-negative values with a positive sum")
494
+ if np.any(pi <= 0):
495
+ raise ValueError("the profile tested against needs a positive weight in every grade")
496
+ expected = n.sum() * pi
497
+ stat = float(np.sum((n - expected) ** 2 / expected))
498
+ dof = int(n.size - 1)
499
+ return {
500
+ "statistic": stat,
501
+ "dof": dof,
502
+ "p_value": float(stats.chi2.sf(stat, dof)),
503
+ "reference": "Pearson (1900), Philosophical Magazine 50(302):157-175, doi:10.1080/14786440009463897; "
504
+ f"{TASCHE_2013}, section 2.1",
505
+ }
506
+
507
+
508
+ __all__ = [
509
+ "TASCHE_2013",
510
+ "ImproperModel",
511
+ "accuracy_ratio",
512
+ "accuracy_ratio_from_curve",
513
+ "implied_default_profile",
514
+ "implied_survival_profile",
515
+ "invariant_accuracy_ratio",
516
+ "invariant_conditional_profiles",
517
+ "invariant_default_profile",
518
+ "invariant_likelihood_ratio",
519
+ "invariant_pd_curve",
520
+ "likelihood_ratio",
521
+ "model_from_counts",
522
+ "pd_curve_from_likelihood_ratio",
523
+ "pd_from_likelihood_ratio",
524
+ "profile_chi2",
525
+ "qmm",
526
+ "scaled_likelihood_ratio",
527
+ "scaled_pds",
528
+ "unconditional_pd",
529
+ ]
@@ -0,0 +1,72 @@
1
+ """The one-factor (Vasicek) model and its large homogeneous portfolio limit.
2
+
3
+ Obligor i defaults when its asset return A_i = sqrt(rho) Z + sqrt(1 - rho) e_i falls below G(PD), with Z and e_i
4
+ independent standard normals (Vasicek 2002; Gordy 2003, doi:10.1016/S1042-9573(03)00040-8). Given the systematic
5
+ factor Z = z the default probability is
6
+
7
+ p(z) = N((G(PD) - sqrt(rho) z) / sqrt(1 - rho)),
8
+
9
+ and in the infinitely granular portfolio the default fraction converges to p(Z), so
10
+
11
+ P(L <= x) = N((sqrt(1 - rho) G(x) - G(PD)) / sqrt(rho)), q-quantile N((G(PD) + sqrt(rho) G(q)) / sqrt(1 - rho)).
12
+
13
+ The IRB formula's conditional PD is this quantile at q = 0.999 (BCBS explanatory note, 2005). An observed default rate
14
+ DR implies the factor z = (G(PD) - sqrt(1 - rho) G(DR)) / sqrt(rho), the inverse of p(z): the credit-cycle index of a
15
+ through-the-cycle PD (dossier 04 C.1, the Z-factor of Belkin, Suchower and Forest 1998).
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import math
21
+
22
+ import numpy as np
23
+ from scipy.special import ndtr, ndtri
24
+
25
+ VASICEK_2002 = "Vasicek (2002), Loan portfolio value, Risk, December 2002, 160-162"
26
+ GORDY_2003 = (
27
+ "Gordy (2003), A risk-factor model foundation for ratings-based bank capital rules, "
28
+ "doi:10.1016/S1042-9573(03)00040-8"
29
+ )
30
+
31
+
32
+ def _check(pd: float, rho: float) -> None:
33
+ if not 0.0 < pd < 1.0:
34
+ raise ValueError("pd must lie in (0, 1)")
35
+ if not 0.0 < rho < 1.0:
36
+ raise ValueError("rho must lie in (0, 1)")
37
+
38
+
39
+ def conditional_pd(pd: float, rho: float, z: float | np.ndarray) -> float | np.ndarray:
40
+ """The PD given the systematic factor z (a low z is a bad state of the economy)."""
41
+ _check(pd, rho)
42
+ return ndtr((ndtri(pd) - math.sqrt(rho) * np.asarray(z, dtype=float)) / math.sqrt(1.0 - rho))
43
+
44
+
45
+ def lhp_cdf(x: float | np.ndarray, pd: float, rho: float) -> float | np.ndarray:
46
+ """P(L <= x) for the default fraction L of the large homogeneous portfolio."""
47
+ _check(pd, rho)
48
+ x = np.clip(np.asarray(x, dtype=float), 0.0, 1.0)
49
+ with np.errstate(divide="ignore"):
50
+ return ndtr((math.sqrt(1.0 - rho) * ndtri(x) - ndtri(pd)) / math.sqrt(rho))
51
+
52
+
53
+ def lhp_quantile(q: float | np.ndarray, pd: float, rho: float) -> float | np.ndarray:
54
+ """The q-quantile of the default fraction of the large homogeneous portfolio."""
55
+ _check(pd, rho)
56
+ return ndtr((ndtri(pd) + math.sqrt(rho) * ndtri(np.asarray(q, dtype=float))) / math.sqrt(1.0 - rho))
57
+
58
+
59
+ def lhp_pdf(x: float | np.ndarray, pd: float, rho: float) -> float | np.ndarray:
60
+ """The density of the default fraction on (0, 1)."""
61
+ _check(pd, rho)
62
+ g = ndtri(np.asarray(x, dtype=float))
63
+ return math.sqrt((1.0 - rho) / rho) * np.exp(0.5 * g**2 - (math.sqrt(1.0 - rho) * g - ndtri(pd)) ** 2 / (2.0 * rho))
64
+
65
+
66
+ def implied_factor(default_rate: float | np.ndarray, pd: float, rho: float) -> float | np.ndarray:
67
+ """The systematic factor z at which the conditional PD equals the observed default rate."""
68
+ _check(pd, rho)
69
+ dr = np.asarray(default_rate, dtype=float)
70
+ if np.any((dr <= 0.0) | (dr >= 1.0)):
71
+ raise ValueError("an implied factor needs a default rate in (0, 1)")
72
+ return (ndtri(pd) - math.sqrt(1.0 - rho) * ndtri(dr)) / math.sqrt(rho)
@@ -0,0 +1,10 @@
1
+ """Fairness: group metrics, inference on selection rates, conditional disparity, replication, situation testing and
2
+ planted-bias generators.
3
+
4
+ Modules are imported by path (for example ``from riskvalidation.fairness.metrics import four_fifths_flag``); nothing is
5
+ re-exported here, because `fairness.metrics` and `validation.fairness` each define a `calibration_within_groups` and an
6
+ `auc_by_group` (the pure metrics and the `TestResult` functions). The engine states no legal claim: the four-fifths line
7
+ is an employment benchmark (29 CFR 1607.4(D)) and never a credit-law threshold, and the outcome-conditioned metrics
8
+ never run on a dataset with no outcome. The `TestResult` functions are in ``riskvalidation.validation.fairness``.
9
+ Contract: ``engine-fairness-api`` 1.0.0.
10
+ """