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,273 @@
1
+ {
2
+ "policy_id": "riskvalidation-default",
3
+ "version": "2026.10.1",
4
+ "description": "Conventional thresholds for illustration and comparison. They are policy choices, not regulatory thresholds: the ECB 2019 IRB validation-reporting instructions set no pass or fail thresholds, and each entry names where its convention comes from. Institutions replace this file with their own policy.",
5
+ "thresholds": {
6
+ "pd.jeffreys": {
7
+ "kind": "p_value",
8
+ "amber": 0.05,
9
+ "red": 0.01,
10
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
11
+ },
12
+ "pd.binomial": {
13
+ "kind": "p_value",
14
+ "amber": 0.05,
15
+ "red": 0.01,
16
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
17
+ },
18
+ "pd.binomial_vasicek": {
19
+ "kind": "p_value",
20
+ "amber": 0.05,
21
+ "red": 0.01,
22
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
23
+ },
24
+ "pd.chi2_grades": {
25
+ "kind": "p_value",
26
+ "amber": 0.05,
27
+ "red": 0.01,
28
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
29
+ },
30
+ "pd.default_profile": {
31
+ "kind": "p_value",
32
+ "amber": 0.05,
33
+ "red": 0.01,
34
+ "source": "convention: 5% and 1% significance levels; Tasche (2013) reads the 2009 fit (p 9%) as rejectable at 10%, and the ECB (2019) instructions and BCBS WP14 set no thresholds"
35
+ },
36
+ "pd.hosmer_lemeshow": {
37
+ "kind": "p_value",
38
+ "amber": 0.05,
39
+ "red": 0.01,
40
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
41
+ },
42
+ "pd.spiegelhalter": {
43
+ "kind": "p_value",
44
+ "amber": 0.05,
45
+ "red": 0.01,
46
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
47
+ },
48
+ "pd.normal_multiperiod": {
49
+ "kind": "p_value",
50
+ "amber": 0.05,
51
+ "red": 0.01,
52
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
53
+ },
54
+ "pd.traffic_lights": {
55
+ "kind": "p_value",
56
+ "amber": 0.05,
57
+ "red": 0.01,
58
+ "source": "convention: 5% and 1% on P(V <= v); BCBS WP14 defines v_alpha for a chosen confidence level"
59
+ },
60
+ "disc.auc_vs_initial": {
61
+ "kind": "p_value",
62
+ "amber": 0.05,
63
+ "red": 0.01,
64
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
65
+ },
66
+ "disc.delong": {
67
+ "kind": "p_value",
68
+ "amber": 0.05,
69
+ "red": 0.01,
70
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
71
+ },
72
+ "rating.migration_ztests": {
73
+ "kind": "p_value",
74
+ "amber": 0.05,
75
+ "red": 0.01,
76
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
77
+ },
78
+ "rating.hhi": {
79
+ "kind": "p_value",
80
+ "amber": 0.05,
81
+ "red": 0.01,
82
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
83
+ },
84
+ "stability.psi": {
85
+ "kind": "p_value",
86
+ "amber": 0.05,
87
+ "red": 0.01,
88
+ "source": "Yurdakul and Naranjo (2020) chi-square benchmark at 5% and 1%; the 0.10/0.25 bands are reported beside it as a rule of thumb without error control"
89
+ },
90
+ "stability.csi": {
91
+ "kind": "p_value",
92
+ "amber": 0.05,
93
+ "red": 0.01,
94
+ "source": "Yurdakul and Naranjo (2020) chi-square benchmark at 5% and 1%; the 0.10/0.25 bands are reported beside it as a rule of thumb without error control"
95
+ },
96
+ "stability.chi2": {
97
+ "kind": "p_value",
98
+ "amber": 0.05,
99
+ "red": 0.01,
100
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
101
+ },
102
+ "stability.ks": {
103
+ "kind": "p_value",
104
+ "amber": 0.05,
105
+ "red": 0.01,
106
+ "source": "convention: 5% and 1% significance levels; the ECB (2019) instructions and BCBS WP14 set no thresholds"
107
+ },
108
+ "rating.time_homogeneity": {
109
+ "kind": "p_value",
110
+ "amber": 0.05,
111
+ "red": 0.01,
112
+ "source": "convention: 5% and 1% significance levels; no supervisory text sets thresholds for these tests"
113
+ },
114
+ "rating.markov_order": {
115
+ "kind": "p_value",
116
+ "amber": 0.05,
117
+ "red": 0.01,
118
+ "source": "convention: 5% and 1% significance levels; no supervisory text sets thresholds for these tests"
119
+ },
120
+ "rating.matrix_reference": {
121
+ "kind": "p_value",
122
+ "amber": 0.05,
123
+ "red": 0.01,
124
+ "source": "convention: 5% and 1% significance levels; no supervisory text sets thresholds for these tests"
125
+ },
126
+ "rating.momentum": {
127
+ "kind": "p_value",
128
+ "amber": 0.05,
129
+ "red": 0.01,
130
+ "source": "convention: 5% and 1% significance levels; no supervisory text sets thresholds for these tests"
131
+ },
132
+ "fair.demographic_parity": {
133
+ "kind": "upper_bad",
134
+ "amber": 0.05000000000000001,
135
+ "red": 2.0,
136
+ "source": "convention: the amber tolerance 0.05 on the largest absolute selection-rate gap is proposed, no dossier value; strict (a gap equal to the tolerance is green); red 2.0 is a sentinel above the metric's range: never red"
137
+ },
138
+ "fair.two_proportion_z": {
139
+ "kind": "p_value",
140
+ "amber": 0.05,
141
+ "red": 0.01,
142
+ "source": "convention: the engine's default p-value cut points (5% and 1%); dossier 06 C.7 l.1036-1039"
143
+ },
144
+ "fair.fisher_exact": {
145
+ "kind": "p_value",
146
+ "amber": 0.05,
147
+ "red": 0.01,
148
+ "source": "convention: the engine's default p-value cut points (5% and 1%); dossier 06 C.7 l.1036-1039"
149
+ },
150
+ "fair.equalized_odds": {
151
+ "kind": "upper_bad",
152
+ "amber": 0.05,
153
+ "red": 0.1,
154
+ "source": "convention: proposed for the Taiwan battery, no dossier value (06 C.7 l.1029-1033)"
155
+ },
156
+ "fair.equal_opportunity": {
157
+ "kind": "upper_bad",
158
+ "amber": 0.05,
159
+ "red": 0.1,
160
+ "source": "convention: proposed for the Taiwan battery, no dossier value (06 C.7 l.1029-1033)"
161
+ },
162
+ "fair.calibration_within_groups": {
163
+ "kind": "upper_bad",
164
+ "amber": 0.05,
165
+ "red": 0.1,
166
+ "source": "convention: proposed for the Taiwan battery, no dossier value (04 J.3 l.904-905)"
167
+ },
168
+ "fair.auc_by_group": {
169
+ "kind": "upper_bad",
170
+ "amber": 0.05,
171
+ "red": 0.1,
172
+ "source": "convention: proposed for the Taiwan battery, no dossier value (04 J.3 l.904-905)"
173
+ },
174
+ "fair.situation_testing": {
175
+ "kind": "upper_bad",
176
+ "amber": 0.2,
177
+ "red": 2.0,
178
+ "source": "convention: the amber share 0.20 of significant complainants, set on the measured size 0.039 and power 1.000 at n 400 and k 30 (docs/fairness/06), no source value; red 2.0 is a sentinel above the metric's range: never red"
179
+ },
180
+ "ml.robustness": {
181
+ "kind": "upper_bad",
182
+ "amber": 0.020000000000000004,
183
+ "red": 0.04000000000000001,
184
+ "source": "AUC degradation at the preset scale: amber above perturbation_tolerance (0.02), red above twice it, a delta equal to the tolerance green; convention (engine-ml-api 2.0.0, Policy thresholds)"
185
+ },
186
+ "ml.shift_resilience": {
187
+ "kind": "p_value",
188
+ "amber": 0.05,
189
+ "red": 0.01,
190
+ "source": "Monte Carlo p-value of the AUC drop on the worst subsample by shift score against the drop of random development subsets of the evaluation size (06 C.7 l.1013-1015 gives the construction only): the engine default p-value cut points (alpha_amber 0.05, alpha_red 0.01); convention (engine-ml-api 2.0.0, Policy thresholds)"
191
+ },
192
+ "ml.seed_stability": {
193
+ "kind": "upper_bad",
194
+ "amber": 0.01,
195
+ "red": 0.02,
196
+ "source": "standard deviation of the AUC across seeds: proposed, about the sampling standard error of a Taiwan holdout AUC (0.008); convention (engine-ml-api 2.0.0, Policy thresholds)"
197
+ },
198
+ "ml.reason_code_stability": {
199
+ "kind": "lower_bad",
200
+ "amber": 0.8,
201
+ "red": 0.6,
202
+ "source": "mean top-four reason overlap across refits: proposed, no dossier value (04 J.2 l.881-883); convention (engine-ml-api 2.0.0, Policy thresholds)"
203
+ },
204
+ "ml.effect_agreement": {
205
+ "kind": "lower_bad",
206
+ "amber": 0.7,
207
+ "red": 0.4,
208
+ "source": "Spearman rho of mean absolute SHAP against the range of the ALE curve: proposed, no dossier value (06 C.7 l.1006-1008); convention (engine-ml-api 2.0.0, Policy thresholds)"
209
+ },
210
+ "ml.additivity": {
211
+ "kind": "upper_bad",
212
+ "amber": 1.0000000000000003e-09,
213
+ "red": 1.0000000000000003e-09,
214
+ "source": "maximum Shapley additivity gap: red above the numeric tolerance (1e-09); convention (engine-ml-api 2.0.0, Policy thresholds)"
215
+ },
216
+ "ml.overfit": {
217
+ "kind": "upper_bad",
218
+ "amber": 0.05000000000000001,
219
+ "red": 0.05000000000000001,
220
+ "source": "train minus holdout AUC gap: red above overfit_tolerance (0.05); convention (engine-ml-api 2.0.0, Policy thresholds)"
221
+ },
222
+ "ml.weak_spot": {
223
+ "kind": "upper_bad",
224
+ "amber": 2.0000000000000004,
225
+ "red": 1000000000000.0001,
226
+ "source": "error ratio of the worst slice to the average error: amber above weak_spot_multiple (2.0); red 1e12 is a sentinel no ratio reaches, so never red; convention (engine-ml-api 2.0.0, Policy thresholds)"
227
+ },
228
+ "ml.conformal_coverage": {
229
+ "kind": "p_value",
230
+ "amber": 0.05,
231
+ "red": 0.01,
232
+ "source": "Beta-Binomial p-value of the coverage against 1 - alpha given the calibration size: the engine default p-value cut points (alpha_amber 0.05, alpha_red 0.01); convention (engine-ml-api 2.0.0, Policy thresholds)"
233
+ },
234
+ "ml.leakage_screen.single_feature_auc": {
235
+ "kind": "upper_bad",
236
+ "amber": 0.9500000000000001,
237
+ "red": 0.9500000000000001,
238
+ "source": "largest single-feature max(AUC, 1 - AUC): near-perfect above 0.95, no dossier value; convention (engine-ml-api 2.0.0, Policy thresholds)"
239
+ },
240
+ "ml.leakage_screen.resemblance_auc": {
241
+ "kind": "upper_bad",
242
+ "amber": 0.7000000000000001,
243
+ "red": 0.7000000000000001,
244
+ "source": "cross-fitted development against out-of-time AUC: proposed, no dossier value; convention (engine-ml-api 2.0.0, Policy thresholds)"
245
+ },
246
+ "ml.leakage_screen.temporal_order": {
247
+ "kind": "upper_bad",
248
+ "amber": 1.0,
249
+ "red": 1.0,
250
+ "source": "feature values dated after the observation date: one is a leak by definition (06 C.7 l.1048-1051); rule, not a convention (engine-ml-api 2.0.0, Policy thresholds)"
251
+ },
252
+ "ml.leakage_screen.entity_overlap": {
253
+ "kind": "upper_bad",
254
+ "amber": 1.0,
255
+ "red": 1.0,
256
+ "source": "any test entity present in training (the indicator 1 when the overlap share is above 0): a leak by definition; rule, not a convention (engine-ml-api 2.0.0, Policy thresholds)"
257
+ },
258
+ "ml.data_quality": {
259
+ "kind": "upper_bad",
260
+ "amber": 0.01,
261
+ "red": 0.05,
262
+ "source": "largest share of failed checks over the dq_ counts: proposed, no dossier value (06 C.7 l.1045-1047); convention (engine-ml-api 2.0.0, Policy thresholds)"
263
+ }
264
+ },
265
+ "descriptive_without_thresholds": [
266
+ "pd.brier",
267
+ "pd.ece",
268
+ "disc.auc",
269
+ "disc.ks",
270
+ "rating.mwb",
271
+ "stability.wasserstein"
272
+ ]
273
+ }
@@ -0,0 +1,16 @@
1
+ """Portfolio credit capital: the loss distribution of a credit portfolio by the rungs of dossier 04 and its Euler
2
+ contributions.
3
+
4
+ Rungs: C1 the large homogeneous portfolio (`portfolio.lhp_measures`, from `riskvalidation.engines.vasicek`), C2 and C3
5
+ the Gaussian and Student-t copula Monte Carlo (`copula`), C4 CreditRisk+ with the stable recursion
6
+ (`creditrisk_plus`), C5 the granularity adjustment of Gordy and Lutkebohmert (`granularity`), C6 importance sampling
7
+ (`importance`); the Euler contributions and the concentration measures (`euler`); the fit of the Vasicek distribution
8
+ to a series of yearly loss rates (`asrf_fit`). The validation tests of an economic capital model are in
9
+ ``riskvalidation.validation.portfolio``.
10
+
11
+ Modules are imported by path (for example ``from riskvalidation.portfolio import copula``); nothing is re-exported
12
+ here. The engine computes and states no compliance claim: confidence levels, tolerances, light parameters and seeds
13
+ are parameters the caller supplies or Contraste internal gates. Money is in the portfolio currency and never
14
+ converted. A value that cannot be computed is a ValueError or a not_evaluated result, never a placeholder number.
15
+ Contract: ``engine-portfolio-api`` 1.0.0.
16
+ """
@@ -0,0 +1,283 @@
1
+ """The fit of the Vasicek distribution to a series of yearly loss or default rates (dossier 04 C.4; contract
2
+ `engine-portfolio-api`).
3
+
4
+ In the large homogeneous portfolio the yearly loss rate is p(Z) with Z ~ N(0, 1) and p the conditional PD of
5
+ `engines.vasicek`, with the density `engines.vasicek.lhp_pdf` and the quantile function `lhp_quantile`. Two
6
+ estimators:
7
+
8
+ - maximum likelihood on the density: (pd, rho) maximising sum_t ln lhp_pdf(rate_t; pd, rho), by Nelder-Mead on the
9
+ logit scale from
10
+ a fixed start with a fixed tolerance (deterministic);
11
+ - the method of moments: pd = mean(rates) and rho the root of E[L^2] = P(two obligors default) = Phi_2(G(pd),
12
+ G(pd); rho) =
13
+ mean(rates^2) (the second moment of the large-portfolio default fraction is the joint default probability of two
14
+ names).
15
+
16
+ The uncertainty of the correlation: the profile log-likelihood and the likelihood-ratio interval (the parameter values
17
+ whose profile log-likelihood is at least max - chi2_1(level) / 2), and a seeded parametric bootstrap. The implied
18
+ factor series is the Z-factor of dossier 04 C.4, z_t = (G(pd) - sqrt(1 - rho) G(rate_t)) / sqrt(rho) (a derivation,
19
+ not a quoted formula).
20
+
21
+ A rate that is NaN is a year the table lacks: it is excluded, counted in `n_missing` and never interpolated. A PD, a
22
+ correlation and a loss rate are open at every estimate site: a value outside (0, 1) raises ValueError.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import math
28
+ from dataclasses import dataclass
29
+ from typing import Any
30
+
31
+ import numpy as np
32
+ from scipy import integrate, stats
33
+ from scipy.optimize import brentq, minimize, minimize_scalar
34
+ from scipy.special import expit, logit
35
+
36
+ from riskvalidation.engines.vasicek import conditional_pd, implied_factor, lhp_pdf
37
+ from riskvalidation.portfolio.portfolio import check_level, float_vector, positive_int
38
+
39
+ BOUND_LOW = 1e-4 # an interval endpoint that reaches the parameter space is returned as these bounds
40
+ BOUND_HIGH = 0.9999
41
+ MIN_YEARS = 3
42
+ PD_SEARCH = (1e-6, 0.99) # the search range of the PD at a fixed correlation
43
+ RHO_SEARCH = (1e-4, 0.9999)
44
+ GRID_POINTS = 41
45
+ MIN_BOOT = 100
46
+ PENALTY = 1e300
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class AsrfFit:
51
+ """A fit: 0 < pd < 1, 0 < rho < 1, the log-likelihood in nats, how the estimate was reached and the years used."""
52
+
53
+ pd: float
54
+ rho: float
55
+ log_likelihood: float
56
+ converged: bool
57
+ method: str
58
+ n_years: int
59
+ n_missing: int
60
+
61
+
62
+ class BootstrapIntervals(dict):
63
+ """The percentile intervals {"pd": (low, high), "rho": (low, high)}, with how many refits were dropped."""
64
+
65
+ n_boot: int
66
+ n_dropped: int
67
+
68
+
69
+ def _clean(rates: Any) -> tuple[np.ndarray, int]:
70
+ """The usable rates (NaN removed) and the number of NaN; a value outside (0, 1) or infinite raises ValueError."""
71
+ a = np.array(rates, dtype=float)
72
+ if a.ndim != 1:
73
+ raise ValueError(f"rates must be one-dimensional, got shape {a.shape}")
74
+ miss = np.isnan(a)
75
+ good = a[~miss]
76
+ if np.any(np.isinf(good)) or np.any(good <= 0.0) or np.any(good >= 1.0):
77
+ raise ValueError("every rate must lie strictly between 0 and 1 (NaN marks a missing year)")
78
+ return good, int(miss.sum())
79
+
80
+
81
+ def log_likelihood(rates: np.ndarray, pd: float, rho: float) -> float:
82
+ """sum_t ln lhp_pdf(rate_t; pd, rho); permutation-invariant. NaN rates are the callers' to exclude and count."""
83
+ a = float_vector(rates, "rates")
84
+ if np.any(a <= 0.0) or np.any(a >= 1.0):
85
+ raise ValueError("every rate must lie strictly between 0 and 1")
86
+ with np.errstate(divide="ignore", over="ignore", invalid="ignore"):
87
+ return float(np.sum(np.log(lhp_pdf(a, pd, rho))))
88
+
89
+
90
+ def _usable(rates: Any) -> tuple[np.ndarray, int]:
91
+ r, miss = _clean(rates)
92
+ if r.size < MIN_YEARS:
93
+ raise ValueError(f"at least {MIN_YEARS} usable years are needed, got {r.size}")
94
+ return r, miss
95
+
96
+
97
+ def _no_spread(r: np.ndarray) -> bool:
98
+ return float(np.ptp(r)) <= 1e-12 * max(1.0, float(np.max(np.abs(r))))
99
+
100
+
101
+ def fit_ml(rates: np.ndarray) -> AsrfFit:
102
+ """The maximum-likelihood (pd, rho). Raises ValueError for fewer than 3 usable years or a series with zero spread.
103
+
104
+ `converged` is False when the optimiser stops at its iteration cap or at the bound of the parameter space (rho or
105
+ pd outside [1e-4, 0.9999]).
106
+ """
107
+ r, miss = _usable(rates)
108
+ if _no_spread(r):
109
+ raise ValueError("the rates have zero spread: the correlation is not identified")
110
+
111
+ def nll(t: np.ndarray) -> float:
112
+ v = log_likelihood(r, float(expit(t[0])), float(expit(t[1])))
113
+ return -v if math.isfinite(v) else PENALTY
114
+
115
+ x0 = np.array([logit(min(max(float(r.mean()), BOUND_LOW), BOUND_HIGH)), logit(0.1)])
116
+ opts = {"xatol": 1e-10, "fatol": 1e-12, "maxiter": 4000, "maxfev": 8000}
117
+ res = minimize(nll, x0, method="Nelder-Mead", options=opts)
118
+ res = minimize(nll, res.x, method="Nelder-Mead", options=opts) # one restart from the optimum: simplex stalls
119
+ pd, rho = float(expit(res.x[0])), float(expit(res.x[1]))
120
+ inside = BOUND_LOW < rho < BOUND_HIGH and BOUND_LOW < pd < BOUND_HIGH
121
+ return AsrfFit(pd=pd, rho=rho, log_likelihood=-float(res.fun), converged=bool(res.success and inside),
122
+ method="maximum-likelihood", n_years=int(r.size), n_missing=miss)
123
+
124
+
125
+ def _joint_default(pd: float, rho: float) -> float:
126
+ """E[p(Z)^2] = P(two obligors default) by quadrature of the engine's conditional PD."""
127
+ def integrand(z: float) -> float:
128
+ return float(conditional_pd(pd, rho, z)) ** 2 * math.exp(-0.5 * z * z) / math.sqrt(2.0 * math.pi)
129
+
130
+ val, _ = integrate.quad(integrand, -12.0, 12.0, epsabs=1e-16, epsrel=1e-12, limit=200)
131
+ return float(val)
132
+
133
+
134
+ def fit_moments(rates: np.ndarray) -> AsrfFit:
135
+ """pd = mean(rates) and rho solving E[p(Z)^2] = mean(rates^2).
136
+
137
+ When mean(rates^2) <= pd^2 there is no excess dispersion, the correlation is not identified and ValueError is
138
+ raised (never 0). `log_likelihood` is evaluated at the moment estimates for comparison.
139
+ """
140
+ r, miss = _usable(rates)
141
+ pd = float(r.mean())
142
+ m2 = float(np.mean(r * r))
143
+ if m2 <= pd * pd * (1.0 + 1e-12):
144
+ raise ValueError("no excess dispersion: mean(rates^2) <= pd^2, the correlation is not identified")
145
+ lo, hi = 1e-9, 1.0 - 1e-9
146
+
147
+ def gap(rho: float) -> float:
148
+ return _joint_default(pd, rho) - m2
149
+
150
+ if gap(hi) < 0.0:
151
+ raise ValueError("the second moment is above the joint default probability at rho = 1 - 1e-9: "
152
+ "no correlation fits")
153
+ rho = float(brentq(gap, lo, hi, xtol=1e-14, rtol=1e-13))
154
+ return AsrfFit(pd=pd, rho=rho, log_likelihood=log_likelihood(r, pd, rho), converged=True, method="moments",
155
+ n_years=int(r.size), n_missing=miss)
156
+
157
+
158
+ def _maximize_logit(fun, lo: float, hi: float) -> tuple[float, float]:
159
+ """The maximiser x in (lo, hi) of fun by a coarse grid on the logit scale and a bounded refinement; (x, fun(x))."""
160
+ grid = np.linspace(logit(lo), logit(hi), GRID_POINTS)
161
+ vals = np.array([fun(float(expit(t))) for t in grid])
162
+ vals = np.where(np.isfinite(vals), vals, -PENALTY)
163
+ i = int(np.argmax(vals))
164
+ a, b = grid[max(i - 1, 0)], grid[min(i + 1, GRID_POINTS - 1)]
165
+ res = minimize_scalar(lambda t: -fun(float(expit(t))), bounds=(a, b), method="bounded", options={"xatol": 1e-10})
166
+ best_x, best_v = float(expit(res.x)), -float(res.fun)
167
+ if vals[i] > best_v:
168
+ best_x, best_v = float(expit(grid[i])), float(vals[i])
169
+ return best_x, best_v
170
+
171
+
172
+ def _profile_at_rho(r: np.ndarray, rho: float) -> tuple[float, float]:
173
+ pd, v = _maximize_logit(lambda p: log_likelihood(r, p, rho), *PD_SEARCH)
174
+ return v, pd
175
+
176
+
177
+ def _profile_at_pd(r: np.ndarray, pd: float) -> tuple[float, float]:
178
+ rho, v = _maximize_logit(lambda p: log_likelihood(r, pd, p), *RHO_SEARCH)
179
+ return v, rho
180
+
181
+
182
+ def profile_likelihood(rates: np.ndarray, rho_grid: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
183
+ """(log_likelihood, pd_at_rho): at each correlation of a strictly increasing grid in (0, 1), the PD that
184
+ maximises the likelihood (a one-dimensional bounded search) and the maximised log-likelihood. NaN rates are
185
+ excluded."""
186
+ r, _ = _usable(rates)
187
+ g = float_vector(rho_grid, "rho_grid")
188
+ if np.any(g <= 0.0) or np.any(g >= 1.0) or np.any(np.diff(g) <= 0.0):
189
+ raise ValueError("rho_grid must be strictly increasing inside (0, 1)")
190
+ out = [_profile_at_rho(r, float(rho)) for rho in g]
191
+ return np.array([o[0] for o in out]), np.array([o[1] for o in out])
192
+
193
+
194
+ def _endpoint(profile, start: float, bound: float, cutoff: float) -> float:
195
+ """Where the profile (a function of one parameter) falls to the cutoff going from `start` to `bound`."""
196
+ pts = expit(np.linspace(logit(start), logit(bound), GRID_POINTS))
197
+ prev = float(pts[0])
198
+ for x in pts[1:]:
199
+ if profile(float(x)) < cutoff:
200
+ return float(brentq(lambda t: profile(t) - cutoff, prev, float(x), xtol=1e-9, rtol=1e-10))
201
+ prev = float(x)
202
+ return float(bound)
203
+
204
+
205
+ def profile_interval(rates: np.ndarray, level: float = 0.95) -> dict[str, tuple[float, float]]:
206
+ """The likelihood-ratio interval {"pd": (low, high), "rho": (low, high)}: the values whose profile log-likelihood is
207
+ at least max - chi2_1(level) / 2 (for 0.95 the cutoff is max - 1.920729). An endpoint that reaches the
208
+ parameter space is returned as the bound (1e-4 or 0.9999); no error is raised. Deterministic."""
209
+ level = check_level(level, "level")
210
+ r, _ = _usable(rates)
211
+ est = fit_ml(r)
212
+ cut_drop = float(stats.chi2.ppf(level, 1)) / 2.0
213
+ top = max(est.log_likelihood, _profile_at_rho(r, est.rho)[0], _profile_at_pd(r, est.pd)[0])
214
+ cutoff = top - cut_drop
215
+
216
+ def p_rho(x: float) -> float:
217
+ return _profile_at_rho(r, x)[0]
218
+
219
+ def p_pd(x: float) -> float:
220
+ return _profile_at_pd(r, x)[0]
221
+
222
+ rho_hat = min(max(est.rho, BOUND_LOW), BOUND_HIGH)
223
+ pd_hat = min(max(est.pd, BOUND_LOW), BOUND_HIGH)
224
+ return {
225
+ "pd": (_endpoint(p_pd, pd_hat, BOUND_LOW, cutoff), _endpoint(p_pd, pd_hat, BOUND_HIGH, cutoff)),
226
+ "rho": (_endpoint(p_rho, rho_hat, BOUND_LOW, cutoff), _endpoint(p_rho, rho_hat, BOUND_HIGH, cutoff)),
227
+ }
228
+
229
+
230
+ def bootstrap_interval(rates: np.ndarray, estimator: str, n_boot: int, seed: int,
231
+ level: float = 0.95) -> dict[str, tuple[float, float]]:
232
+ """A parametric bootstrap: fit the estimator, draw `n_boot` series of the same length with z_t ~ N(0, 1) and
233
+ rate_t = conditional_pd(pd, rho, z_t), refit each, and return the (1 - level)/2 and (1 + level)/2 percentiles of
234
+ the refits.
235
+
236
+ A refit that fails (a ValueError: moments with no excess dispersion, a series with no spread) is dropped and
237
+ counted in the `n_dropped` attribute of the result; a maximum-likelihood refit that stops at a bound is kept.
238
+ Reproducible for a seed. The interval is not required to contain the estimate (a skewed refit distribution).
239
+ """
240
+ fitters = {"maximum-likelihood": fit_ml, "moments": fit_moments}
241
+ if estimator not in fitters:
242
+ raise ValueError(f"estimator must be one of {sorted(fitters)}, got {estimator!r}")
243
+ nb = positive_int(n_boot, "n_boot")
244
+ if nb < MIN_BOOT:
245
+ raise ValueError(f"n_boot must be at least {MIN_BOOT}")
246
+ level = check_level(level, "level")
247
+ fit = fitters[estimator](rates)
248
+ t = fit.n_years
249
+ z = np.random.Generator(np.random.PCG64(int(seed))).standard_normal((nb, t))
250
+ pds, rhos = [], []
251
+ for row in z:
252
+ sim = np.asarray(conditional_pd(fit.pd, fit.rho, row))
253
+ try:
254
+ refit = fitters[estimator](sim)
255
+ except ValueError:
256
+ continue
257
+ pds.append(refit.pd)
258
+ rhos.append(refit.rho)
259
+ if len(pds) < 2:
260
+ raise ValueError("fewer than 2 bootstrap refits succeeded: no interval")
261
+ lo, hi = 100.0 * (1.0 - level) / 2.0, 100.0 * (1.0 + level) / 2.0
262
+ out = BootstrapIntervals(
263
+ pd=(float(np.percentile(pds, lo)), float(np.percentile(pds, hi))),
264
+ rho=(float(np.percentile(rhos, lo)), float(np.percentile(rhos, hi))),
265
+ )
266
+ out.n_boot = nb
267
+ out.n_dropped = nb - len(pds)
268
+ return out
269
+
270
+
271
+ def implied_factors(rates: np.ndarray, pd: float, rho: float) -> np.ndarray:
272
+ """z_t = implied_factor(rate_t; pd, rho) elementwise (decreasing in the rate), NaN where the rate is NaN."""
273
+ a = np.array(rates, dtype=float)
274
+ if a.ndim != 1:
275
+ raise ValueError(f"rates must be one-dimensional, got shape {a.shape}")
276
+ implied_factor(0.5, pd, rho) # validates pd and rho
277
+ miss = np.isnan(a)
278
+ out = np.full(a.shape, np.nan)
279
+ if np.any((a[~miss] <= 0.0) | (a[~miss] >= 1.0)):
280
+ raise ValueError("every rate must lie strictly between 0 and 1")
281
+ if (~miss).any():
282
+ out[~miss] = implied_factor(a[~miss], pd, rho)
283
+ return out