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,100 @@
1
+ """Input checks shared by the provisions modules.
2
+
3
+ Every check names the field in its message, so that a refusal says which input broke which rule of the contract
4
+ (`engine-provisions-api`, conventions).
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import math
10
+ from typing import Any
11
+
12
+ import numpy as np
13
+
14
+ WEIGHT_TOLERANCE = 1e-9
15
+
16
+
17
+ def float_array(x: Any, name: str, ndim: int | None = None) -> np.ndarray:
18
+ """A new float64 array, finite, optionally of a fixed number of dimensions. Empty arrays are allowed."""
19
+ a = np.array(x, dtype=float) # a copy: inputs are never aliased
20
+ if ndim is not None and a.ndim != ndim:
21
+ raise ValueError(f"{name} must have {ndim} dimension(s), got shape {a.shape}")
22
+ if not np.all(np.isfinite(a)):
23
+ raise ValueError(f"{name} contains non-finite values")
24
+ return a
25
+
26
+
27
+ def open_unit(x: Any, name: str) -> np.ndarray:
28
+ """A PD at an estimate site: strictly between 0 and 1."""
29
+ a = np.array(x, dtype=float)
30
+ if not np.all(np.isfinite(a)) or np.any(a <= 0.0) or np.any(a >= 1.0):
31
+ raise ValueError(f"{name} must lie strictly between 0 and 1 (open interval)")
32
+ return a
33
+
34
+
35
+ def closed_unit(x: Any, name: str) -> np.ndarray:
36
+ """A rate in [0, 1]: LGD, CCF, a coverage rate, a share."""
37
+ a = np.array(x, dtype=float)
38
+ if not np.all(np.isfinite(a)) or np.any(a < 0.0) or np.any(a > 1.0):
39
+ raise ValueError(f"{name} must lie in [0, 1]")
40
+ return a
41
+
42
+
43
+ def non_negative(x: Any, name: str) -> np.ndarray:
44
+ a = np.array(x, dtype=float)
45
+ if not np.all(np.isfinite(a)) or np.any(a < 0.0):
46
+ raise ValueError(f"{name} must be finite and non-negative")
47
+ return a
48
+
49
+
50
+ def scalar_open_unit(x: float, name: str) -> float:
51
+ v = float(x)
52
+ if not math.isfinite(v) or not 0.0 < v < 1.0:
53
+ raise ValueError(f"{name} must lie strictly between 0 and 1 (open interval), got {x!r}")
54
+ return v
55
+
56
+
57
+ def months_array(months: Any, name: str = "months") -> np.ndarray:
58
+ """Strictly increasing positive integer end months, as int64."""
59
+ raw = np.asarray(months)
60
+ if raw.ndim != 1 or raw.size == 0:
61
+ raise ValueError(f"{name} must be a non-empty one-dimensional array of integer months")
62
+ if raw.dtype.kind not in "iu":
63
+ f = raw.astype(float)
64
+ if not np.all(np.isfinite(f)) or np.any(f != np.floor(f)):
65
+ raise ValueError(f"{name} must hold integer months")
66
+ raw = f
67
+ m = raw.astype(np.int64)
68
+ if m[0] <= 0 or np.any(np.diff(m) <= 0):
69
+ raise ValueError(f"{name} must be positive and strictly increasing")
70
+ return m
71
+
72
+
73
+ def same_length(arrays: dict[str, np.ndarray]) -> int:
74
+ sizes = {k: v.shape[0] for k, v in arrays.items()}
75
+ if len(set(sizes.values())) > 1:
76
+ raise ValueError(f"{', '.join(sizes)} must have the same length, got {sizes}")
77
+ return next(iter(sizes.values()))
78
+
79
+
80
+ def weights_array(weights: Any, n: int | None = None, name: str = "weights") -> np.ndarray:
81
+ """Probability weights: in [0, 1], summing to 1 within 1e-9, at least two scenarios (IFRS 9 B5.5.42)."""
82
+ w = np.array(weights, dtype=float)
83
+ if w.ndim != 1:
84
+ raise ValueError(f"{name} must be one-dimensional, got shape {w.shape}")
85
+ if w.size < 2:
86
+ raise ValueError(f"{name}: at least two scenarios are required when scenarios are used (IFRS 9 B5.5.42)")
87
+ if n is not None and w.size != n:
88
+ raise ValueError(f"{name} has {w.size} entries for {n} scenarios")
89
+ if not np.all(np.isfinite(w)) or np.any(w < 0.0) or np.any(w > 1.0):
90
+ raise ValueError(f"{name} must lie in [0, 1]")
91
+ if abs(float(np.sum(w)) - 1.0) > WEIGHT_TOLERANCE:
92
+ raise ValueError(f"{name} must sum to 1 within {WEIGHT_TOLERANCE:g}, got {float(np.sum(w))!r}")
93
+ return w
94
+
95
+
96
+ def bool_array(x: Any, name: str) -> np.ndarray:
97
+ a = np.asarray(x)
98
+ if a.dtype != bool:
99
+ raise ValueError(f"{name} must be a boolean array, got dtype {a.dtype}")
100
+ return a.copy()
@@ -0,0 +1,233 @@
1
+ """Measurement: ECL as a sum of discounted marginal losses, probability weighting, Stage 3, POCI, the simplified
2
+ approach and the portfolio allowance (dossier 02 B.3, B.4, B.5, B.7, A.5, A.6; IFRS 9 5.5.17 to 5.5.20,
3
+ B5.5.28 to B5.5.55).
4
+
5
+ ECL_{i,s}(T) = sum_{t <= T} q_D(t) LGD(t) EAD(t) DF(t), DF(t) = (1 + EIR)^(-delta(t) / 12)
6
+
7
+ with `delta(t)` the months from the reporting date to the loss date of period t (mid-period or end-of-period). The
8
+ discounting is at the original EIR to the reporting date, never at a risk-free rate and never to the default date.
9
+ Overlays are separate lines (see `overlays`) and never enter the model ECL. This module states no compliance claim.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import math
15
+ from collections.abc import Sequence
16
+ from dataclasses import dataclass
17
+
18
+ import numpy as np
19
+
20
+ from riskvalidation.provisions._checks import (
21
+ closed_unit,
22
+ float_array,
23
+ months_array,
24
+ non_negative,
25
+ open_unit,
26
+ same_length,
27
+ weights_array,
28
+ )
29
+ from riskvalidation.provisions.overlays import Overlay, check_unique
30
+
31
+ CONVENTIONS = ("mid-period", "end-of-period")
32
+ STAGE_KEYS = ("stage1", "stage2", "stage3", "poci")
33
+
34
+
35
+ def discount_factors(eir: np.ndarray, months: np.ndarray, convention: str = "mid-period") -> np.ndarray:
36
+ """DF (A, T) = (1 + eir)^(-delta / 12) to the reporting date; the first period's length is `months[0]`.
37
+
38
+ `mid-period`: delta = month - Delta / 2 (the midpoint of the period); `end-of-period`: delta = month.
39
+ """
40
+ if convention not in CONVENTIONS:
41
+ raise ValueError(f"convention must be one of {CONVENTIONS}, got {convention!r}")
42
+ r = non_negative(eir, "eir")
43
+ if r.ndim != 1:
44
+ raise ValueError(f"eir must be one-dimensional (A,), got shape {r.shape}")
45
+ m = months_array(months)
46
+ ends = m.astype(float)
47
+ delta = ends if convention == "end-of-period" else ends - np.diff(m, prepend=0).astype(float) / 2.0
48
+ return (1.0 + r[:, None]) ** (-delta[None, :] / 12.0)
49
+
50
+
51
+ def _per_period(x: object, name: str, n_accounts: int, n_periods: int, closed: bool) -> np.ndarray:
52
+ """A scalar, (A,) or (A, T) parameter broadcast to (A, T)."""
53
+ a = closed_unit(x, name) if closed else non_negative(x, name)
54
+ if a.ndim == 0:
55
+ return np.full((n_accounts, n_periods), float(a))
56
+ if a.ndim == 1:
57
+ if a.shape[0] != n_accounts:
58
+ raise ValueError(f"{name} has {a.shape[0]} entries for {n_accounts} accounts")
59
+ return np.repeat(a[:, None], n_periods, axis=1)
60
+ if a.shape != (n_accounts, n_periods):
61
+ raise ValueError(f"{name} must be a scalar, (A,) or (A, T) = {(n_accounts, n_periods)}, got shape {a.shape}")
62
+ return a
63
+
64
+
65
+ def ecl_scenario(marginal_pd: np.ndarray, lgd: np.ndarray, ead: np.ndarray, eir: np.ndarray, months: np.ndarray,
66
+ horizon_months: int, convention: str = "mid-period") -> np.ndarray:
67
+ """The ECL (A,) of one scenario: the sum over the periods with `months <= horizon_months` of q_D LGD EAD DF.
68
+
69
+ `horizon_months` is 12 for the 12-month ECL and the expected life (5.5.19, 5.5.20) for the lifetime ECL; it must
70
+ be a member of `months` or at least `months[-1]` (no proration of a straddling period).
71
+ """
72
+ m = months_array(months)
73
+ q = np.array(marginal_pd, dtype=float)
74
+ if q.ndim != 2 or q.shape[1] != m.size:
75
+ raise ValueError(f"marginal_pd must have shape (A, {m.size}), got {q.shape}")
76
+ open_unit(q, "marginal_pd")
77
+ n_accounts = q.shape[0]
78
+ h = int(horizon_months)
79
+ if h not in m and h < int(m[-1]):
80
+ raise ValueError(
81
+ f"horizon_months={horizon_months} is neither a member of months {m.tolist()} nor at least months[-1]: "
82
+ "a straddling period is never prorated"
83
+ )
84
+ lgd_t = _per_period(lgd, "lgd", n_accounts, m.size, closed=True)
85
+ ead_t = _per_period(ead, "ead", n_accounts, m.size, closed=False)
86
+ r = non_negative(eir, "eir")
87
+ if r.shape != (n_accounts,):
88
+ raise ValueError(f"eir must have shape ({n_accounts},), got {r.shape}")
89
+ df = discount_factors(r, m, convention)
90
+ inside = (m <= h)[None, :]
91
+ return np.sum(np.where(inside, q * lgd_t * ead_t * df, 0.0), axis=1)
92
+
93
+
94
+ def probability_weighted_ecl(ecl_by_scenario: np.ndarray, weights: np.ndarray) -> np.ndarray:
95
+ """sum_s w_s ECL_s over at least two scenarios (5.5.17(a), B5.5.42); (S, A) or (S,) in, (A,) or scalar out."""
96
+ e = float_array(ecl_by_scenario, "ecl_by_scenario")
97
+ if e.ndim not in (1, 2):
98
+ raise ValueError(f"ecl_by_scenario must be (S, A) or (S,), got shape {e.shape}")
99
+ if np.any(e < 0.0):
100
+ raise ValueError("ecl_by_scenario must not hold a negative ECL (an expected credit loss is not negative)")
101
+ w = weights_array(weights, e.shape[0])
102
+ return np.tensordot(w, e, axes=(0, 0))
103
+
104
+
105
+ def non_linearity_index(ecl_weighted: float, ecl_at_mean_path: float) -> float:
106
+ """NL = ecl_weighted / ecl_at_mean_path - 1; raises when the denominator is not positive."""
107
+ if not float(ecl_at_mean_path) > 0.0:
108
+ raise ValueError(f"ecl_at_mean_path must be positive, got {ecl_at_mean_path!r}")
109
+ return float(ecl_weighted) / float(ecl_at_mean_path) - 1.0
110
+
111
+
112
+ def weight_sensitivity(ecl_by_scenario: np.ndarray, reference_index: int) -> np.ndarray:
113
+ """ECL_s - ECL_ref: the derivative dECL/dw_s when weight moves from the reference scenario to s (staging frozen)."""
114
+ e = float_array(ecl_by_scenario, "ecl_by_scenario", ndim=1)
115
+ ref = int(reference_index)
116
+ if not 0 <= ref < e.size:
117
+ raise ValueError(f"reference_index must lie in [0, {e.size - 1}], got {reference_index!r}")
118
+ return e - e[ref]
119
+
120
+
121
+ def stage3_ecl(gross_carrying_amount: np.ndarray, expected_recoveries: np.ndarray, recovery_months: np.ndarray,
122
+ eir: np.ndarray) -> np.ndarray:
123
+ """GCA - sum_k CF_k (1 + eir)^(-months_k / 12), clipped at 0 (B5.5.33): the credit-impaired, non-POCI ECL."""
124
+ gca = non_negative(gross_carrying_amount, "gross_carrying_amount")
125
+ cf = non_negative(expected_recoveries, "expected_recoveries")
126
+ mo = non_negative(recovery_months, "recovery_months")
127
+ r = non_negative(eir, "eir")
128
+ if gca.ndim != 1:
129
+ raise ValueError("gross_carrying_amount must be one-dimensional (A,)")
130
+ if cf.ndim != 2 or cf.shape[0] != gca.size:
131
+ raise ValueError(f"expected_recoveries must have shape (A, K) with A = {gca.size}, got {cf.shape}")
132
+ if mo.shape != cf.shape:
133
+ raise ValueError(f"recovery_months must have the shape of expected_recoveries {cf.shape}, got {mo.shape}")
134
+ if r.shape != gca.shape:
135
+ raise ValueError(f"eir must have shape {gca.shape}, got {r.shape}")
136
+ present_value = np.sum(cf * (1.0 + r[:, None]) ** (-mo / 12.0), axis=1)
137
+ return np.maximum(gca - present_value, 0.0)
138
+
139
+
140
+ def poci_allowance(ecl_lifetime_now: np.ndarray, ecl_lifetime_initial: np.ndarray) -> np.ndarray:
141
+ """now - initial, both lifetime ECLs at the credit-adjusted EIR (5.5.13); may be negative (5.5.14), not clipped."""
142
+ now = float_array(ecl_lifetime_now, "ecl_lifetime_now", ndim=1)
143
+ initial = float_array(ecl_lifetime_initial, "ecl_lifetime_initial", ndim=1)
144
+ same_length({"ecl_lifetime_now": now, "ecl_lifetime_initial": initial})
145
+ return now - initial
146
+
147
+
148
+ def simplified_matrix_ecl(gross_carrying_amount_by_bucket: np.ndarray, loss_rate_by_bucket: np.ndarray,
149
+ forward_looking_multiplier: float = 1.0) -> float:
150
+ """min(sum(gca), m sum(gca rate)): the provision matrix of the simplified approach (B5.5.35)."""
151
+ g = non_negative(gross_carrying_amount_by_bucket, "gross_carrying_amount_by_bucket")
152
+ rate = closed_unit(loss_rate_by_bucket, "loss_rate_by_bucket")
153
+ if g.ndim != 1 or rate.shape != g.shape:
154
+ raise ValueError(
155
+ "gross_carrying_amount_by_bucket and loss_rate_by_bucket must be one-dimensional and equal in shape"
156
+ )
157
+ m = float(forward_looking_multiplier)
158
+ if not math.isfinite(m) or m < 0.0:
159
+ raise ValueError(
160
+ f"forward_looking_multiplier must be finite and non-negative, got {forward_looking_multiplier!r}"
161
+ )
162
+ return float(min(float(np.sum(g)), m * float(np.sum(g * rate))))
163
+
164
+
165
+ def commitment_ead(drawn: np.ndarray, undrawn: np.ndarray, ccf: np.ndarray) -> np.ndarray:
166
+ """drawn + ccf * undrawn (B5.5.30, B5.5.31), between `drawn` and `drawn + undrawn`."""
167
+ d = non_negative(drawn, "drawn")
168
+ u = non_negative(undrawn, "undrawn")
169
+ c = closed_unit(ccf, "ccf")
170
+ return d + c * u
171
+
172
+
173
+ @dataclass(frozen=True)
174
+ class AllowanceBreakdown:
175
+ """Model ECL by stage (the four keys), the model total, the overlay total and the total allowance."""
176
+
177
+ by_stage: dict[str, float]
178
+ model_total: float
179
+ overlay_total: float
180
+ total: float
181
+
182
+
183
+ def portfolio_allowance(stage: np.ndarray, ecl_12m: np.ndarray, ecl_lifetime: np.ndarray, ecl_stage3: np.ndarray,
184
+ poci: np.ndarray | None = None, poci_delta: np.ndarray | None = None,
185
+ overlays: Sequence[Overlay] = ()) -> AllowanceBreakdown:
186
+ """LA = sum_S1 ECL_12m + sum_S2 ECL_life + sum_S3 ECL_D + sum_POCI delta + sum_k OVL_k (dossier 02 B.5).
187
+
188
+ A POCI account is excluded from stages 1 to 3 whatever its `stage` value and counts once, in `poci`. Overlays are
189
+ added to the total only and never enter `by_stage`. The model ECL of an account of stages 1 to 3 is not negative
190
+ (`ValueError`); only the POCI delta may be.
191
+ """
192
+ st = np.asarray(stage)
193
+ if st.ndim != 1:
194
+ raise ValueError(f"stage must be one-dimensional (A,), got shape {st.shape}")
195
+ e12 = np.array(ecl_12m, dtype=float)
196
+ life = np.array(ecl_lifetime, dtype=float)
197
+ s3 = np.array(ecl_stage3, dtype=float)
198
+ n = same_length({"stage": st, "ecl_12m": e12, "ecl_lifetime": life, "ecl_stage3": s3})
199
+ if poci is None:
200
+ is_poci = np.zeros(n, dtype=bool)
201
+ else:
202
+ is_poci = np.asarray(poci)
203
+ if is_poci.dtype != bool or is_poci.shape != (n,):
204
+ raise ValueError(f"poci must be a boolean array of shape ({n},)")
205
+ if np.any(~np.isin(st[~is_poci], (1, 2, 3))):
206
+ raise ValueError("stage must lie in {1, 2, 3} for every non-POCI account")
207
+ delta_total = 0.0
208
+ if is_poci.any():
209
+ if poci_delta is None:
210
+ raise ValueError("poci_delta is required where poci is true")
211
+ delta = np.asarray(poci_delta, dtype=float)
212
+ if delta.shape != (n,):
213
+ raise ValueError(f"poci_delta must have shape ({n},), got {delta.shape}")
214
+ if not np.all(np.isfinite(delta[is_poci])):
215
+ raise ValueError("poci_delta must be finite where poci is true")
216
+ delta_total = math.fsum(delta[is_poci].tolist())
217
+
218
+ def pick(values: np.ndarray, stage_no: int) -> float:
219
+ chosen = values[(st == stage_no) & ~is_poci]
220
+ if not np.all(np.isfinite(chosen)):
221
+ raise ValueError(f"ECL of stage {stage_no} accounts must be finite")
222
+ if np.any(chosen < 0.0):
223
+ raise ValueError(
224
+ f"ECL of stage {stage_no} accounts must not be negative (only a POCI allowance may be negative)"
225
+ )
226
+ return math.fsum(chosen.tolist())
227
+
228
+ by_stage = {"stage1": pick(e12, 1), "stage2": pick(life, 2), "stage3": pick(s3, 3), "poci": delta_total}
229
+ check_unique(overlays)
230
+ model_total = math.fsum(by_stage[k] for k in STAGE_KEYS)
231
+ overlay_sum = math.fsum(float(o.amount) for o in overlays)
232
+ return AllowanceBreakdown(by_stage=by_stage, model_total=model_total, overlay_total=overlay_sum,
233
+ total=model_total + overlay_sum)