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,179 @@
1
+ """Reverse stress: the most plausible scenario that reaches a pre-defined failure point (dossier 05 H.5, 01 J.4).
2
+
3
+ EBA/GL/2018/04 defines a reverse stress test as one that starts from the identification of a pre-defined outcome and
4
+ then explores the scenarios that might cause it (01 l.884-889). The formal statement is Contraste's, not regulatory text
5
+ (01 l.891-894; 05 H.5): for a loss model `L(x)` over factor deviations `x` from the baseline with covariance `Sigma`,
6
+ the most plausible scenario reaching the loss threshold `l` maximises the factor density, which for Gaussian (and
7
+ elliptical) factors is the minimum Mahalanobis distance scenario
8
+
9
+ x* = argmin x' Sigma^-1 x subject to L(x) >= l,
10
+
11
+ in closed form for a linear loss and by `scipy.optimize` (SLSQP) otherwise, with the plausibility of the solution. The
12
+ attribution of the elliptical result to a specific paper is UNVERIFIED in the dossier (05 l.412). Empirical likelihood
13
+ (Glasserman, Kang and Kang) is out: only its abstract is in the dossier.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import math
19
+ from collections.abc import Callable, Sequence
20
+ from dataclasses import dataclass
21
+
22
+ import numpy as np
23
+ from scipy import optimize, stats
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class ReverseSolution:
28
+ """A reverse stress solution; maps onto the document block `solution`."""
29
+
30
+ method: str # "closed-form-linear" or "scipy-optimize"
31
+ x_star: np.ndarray # (K,) deviation of the factors from the baseline, natural units
32
+ z_star: np.ndarray # (K,) x_star over the factor sd
33
+ distance: float # sqrt(x' Sigma^-1 x)
34
+ loss_at_x: float
35
+ threshold: float
36
+ converged: bool
37
+
38
+
39
+ def _cov(cov: np.ndarray) -> np.ndarray:
40
+ c = np.array(cov, dtype=float)
41
+ if c.ndim != 2 or c.shape[0] != c.shape[1] or c.size == 0:
42
+ raise ValueError(f"cov must be a square matrix, got shape {c.shape}")
43
+ if not np.all(np.isfinite(c)):
44
+ raise ValueError("cov contains non-finite values")
45
+ if not np.allclose(c, c.T, rtol=1e-9, atol=1e-12):
46
+ raise ValueError("cov is not symmetric")
47
+ try:
48
+ np.linalg.cholesky(c)
49
+ except np.linalg.LinAlgError as exc:
50
+ raise ValueError("cov is not positive definite") from exc
51
+ return c
52
+
53
+
54
+ def _threshold(threshold: float, *, positive: bool) -> float:
55
+ v = float(threshold)
56
+ if not np.isfinite(v):
57
+ raise ValueError("threshold is non-finite")
58
+ if v < 0.0 or (positive and v == 0.0):
59
+ raise ValueError(f"threshold must be {'positive' if positive else 'not negative'}, got {v}")
60
+ return v
61
+
62
+
63
+ def reverse_stress_linear(gradient: np.ndarray, cov: np.ndarray, threshold: float) -> ReverseSolution:
64
+ """The closed form for the linear loss `L(x) = g'x`: `x* = Sigma g l / (g' Sigma g)` and `distance = l / sqrt(g'
65
+ Sigma g)`.
66
+ `gradient` (K,) is the loss per unit of each factor (money per unit), `cov` (K, K) the factor covariance,
67
+ `threshold` money."""
68
+ c = _cov(cov)
69
+ g = np.array(gradient, dtype=float)
70
+ if g.shape != (c.shape[0],) or not np.all(np.isfinite(g)):
71
+ raise ValueError(f"gradient must be a finite vector of length {c.shape[0]}, got shape {g.shape}")
72
+ thr = _threshold(threshold, positive=False)
73
+ q = float(g @ c @ g)
74
+ if q <= 0.0:
75
+ raise ValueError("the gradient gives g' Sigma g = 0: the loss does not move with any factor")
76
+ x = c @ g * (thr / q)
77
+ sd = np.sqrt(np.diag(c))
78
+ return ReverseSolution(
79
+ method="closed-form-linear",
80
+ x_star=x,
81
+ z_star=x / sd,
82
+ distance=thr / math.sqrt(q),
83
+ loss_at_x=float(g @ x),
84
+ threshold=thr,
85
+ converged=True,
86
+ )
87
+
88
+
89
+ def reverse_stress(
90
+ loss_fn: Callable[[np.ndarray], float],
91
+ cov: np.ndarray,
92
+ threshold: float,
93
+ starts: Sequence[np.ndarray],
94
+ tolerance: float = 1e-6,
95
+ ) -> tuple[ReverseSolution, tuple[ReverseSolution, ...]]:
96
+ """Minimise `x' Sigma^-1 x` subject to `L(x) >= threshold` with `scipy.optimize` (SLSQP) from each start. Returns
97
+ the best converged solution (the smallest distance) and the per-start results. A start converges when SLSQP succeeds
98
+ and `|L(x) - threshold| / threshold <= tolerance`. At least three starts are required (the search is local: one
99
+ start proves nothing); `ValueError` when no start converges. `loss_fn` maps the factor deviation to money; the
100
+ threshold is
101
+ positive."""
102
+ c = _cov(cov)
103
+ thr = _threshold(threshold, positive=True)
104
+ tol = float(tolerance)
105
+ if not (np.isfinite(tol) and tol > 0.0):
106
+ raise ValueError(f"tolerance must be positive, got {tolerance!r}")
107
+ if len(starts) < 3:
108
+ raise ValueError(f"at least three starts are required, got {len(starts)}")
109
+ k = c.shape[0]
110
+ x0s = []
111
+ for i, s in enumerate(starts):
112
+ a = np.array(s, dtype=float)
113
+ if a.shape != (k,) or not np.all(np.isfinite(a)):
114
+ raise ValueError(f"start {i} must be a finite vector of length {k}, got shape {a.shape}")
115
+ x0s.append(a)
116
+ prec = np.linalg.inv(c)
117
+ sd = np.sqrt(np.diag(c))
118
+ results = []
119
+ for x0 in x0s:
120
+ def con(x: np.ndarray) -> float:
121
+ return float(loss_fn(np.array(x, dtype=float))) / thr - 1.0
122
+
123
+ def con_jac(x: np.ndarray) -> np.ndarray:
124
+ """Central differences: SLSQP's forward differences stall on some SciPy versions."""
125
+ g = np.empty(k)
126
+ for j in range(k):
127
+ h = 1e-6 * max(1.0, abs(x[j]))
128
+ e = np.zeros(k)
129
+ e[j] = h
130
+ g[j] = (con(x + e) - con(x - e)) / (2.0 * h)
131
+ return g
132
+
133
+ res = None
134
+ start = x0
135
+ for _ in range(4): # warm restarts from the last point: a fresh quasi-Newton model
136
+ res = optimize.minimize(
137
+ lambda x: float(x @ prec @ x),
138
+ start,
139
+ jac=lambda x: 2.0 * prec @ x,
140
+ method="SLSQP",
141
+ constraints=[{"type": "ineq", "fun": con, "jac": con_jac}],
142
+ options={"ftol": 1e-14, "maxiter": 1000},
143
+ )
144
+ start = np.array(res.x, dtype=float)
145
+ if res.success and abs(con(start)) <= tol:
146
+ break
147
+ x = np.array(res.x, dtype=float)
148
+ loss = float(loss_fn(x.copy()))
149
+ ok = bool(res.success) and np.all(np.isfinite(x)) and np.isfinite(loss) and abs(loss - thr) / thr <= tol
150
+ results.append(
151
+ ReverseSolution(
152
+ method="scipy-optimize",
153
+ x_star=x,
154
+ z_star=x / sd,
155
+ distance=math.sqrt(float(x @ prec @ x)),
156
+ loss_at_x=loss,
157
+ threshold=thr,
158
+ converged=bool(ok),
159
+ )
160
+ )
161
+ converged = [s for s in results if s.converged]
162
+ if not converged:
163
+ raise ValueError(
164
+ "no start converged: SLSQP did not reach the threshold within the tolerance from any of the "
165
+ f"{len(results)} starts"
166
+ )
167
+ return min(converged, key=lambda s: s.distance), tuple(results)
168
+
169
+
170
+ def plausibility(distance: float, df: int) -> float:
171
+ """`P(chi2_df >= distance^2)`: the tail probability of a scenario at least as far (Mahalanobis distance `distance`)
172
+ from the
173
+ baseline, `df` the number of factors. 1.0 at distance 0, decreasing in the distance."""
174
+ d = float(distance)
175
+ if not np.isfinite(d) or d < 0.0:
176
+ raise ValueError(f"distance must be a finite non-negative number, got {distance!r}")
177
+ if int(df) != df or df < 1:
178
+ raise ValueError(f"df must be an integer of at least 1, got {df!r}")
179
+ return float(stats.chi2.sf(d * d, int(df)))
@@ -0,0 +1,268 @@
1
+ """The satellite of a default or loss rate (dossier 04 I.1, l.785-795; dossier 05 H.1 layer 2, l.399).
2
+
3
+ g(DR_t) = alpha + sum_k phi_k g(DR_(t-k)) + sum_l beta_l' X_(t-l) + eps
4
+
5
+ with `g` the probit (the Vasicek-consistent link: regressing Phi^-1(DR_t) on macro variables is regressing the latent
6
+ credit cycle Z_t on them), the logit, or the identity (the linear form of the Federal Reserve's own PD regression, for
7
+ the segments whose rate is zero or negative in some quarters: net recoveries). It is fitted by OLS in NumPy with
8
+ classical standard errors on an explicit sample window. Regressors are the agency series only (decision Q7 of the unit
9
+ sizing).
10
+
11
+ The conditional PD under a scenario and the implied systematic factor are the engine's existing
12
+ `engines.vasicek.conditional_pd` and `engines.vasicek.implied_factor`; they are reused, not rewritten here.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import datetime as _dt
18
+ from collections.abc import Sequence
19
+ from dataclasses import dataclass
20
+
21
+ import numpy as np
22
+ from scipy.special import expit, ndtr, ndtri
23
+
24
+ LINKS = ("probit", "logit", "identity")
25
+ # : the agency series a satellite may read (decision Q7: the BBB corporate yield and the third-party index levels are
26
+ # not read)
27
+ AGENCY_REGRESSORS = (
28
+ "real_gdp_growth",
29
+ "unemployment_rate",
30
+ "cpi_inflation",
31
+ "treasury_3m",
32
+ "treasury_5y",
33
+ "treasury_10y",
34
+ "mortgage_rate",
35
+ "prime_rate",
36
+ )
37
+ NON_POSITIVE_REASON = (
38
+ "a probit or logit fit on a non-positive rate: the link needs a rate in (0, 1); use the identity link"
39
+ )
40
+
41
+
42
+ def _name(name: str) -> str:
43
+ if name not in LINKS:
44
+ raise ValueError(f"unknown link {name!r}: expected one of {', '.join(LINKS)}")
45
+ return name
46
+
47
+
48
+ def link(name: str, p: np.ndarray) -> np.ndarray:
49
+ """The link value of a rate: `probit` Phi^-1(p), `logit` ln(p / (1 - p)), `identity` p."""
50
+ _name(name)
51
+ a = np.array(p, dtype=float)
52
+ if not np.all(np.isfinite(a)):
53
+ raise ValueError("p contains non-finite values")
54
+ if name == "identity":
55
+ return a
56
+ if np.any(a <= 0.0) or np.any(a >= 1.0):
57
+ raise ValueError(f"a {name} link needs a rate in (0, 1); a non-positive rate: use the identity link")
58
+ return ndtri(a) if name == "probit" else np.log(a / (1.0 - a))
59
+
60
+
61
+ def inverse_link(name: str, x: np.ndarray) -> np.ndarray:
62
+ """The rate of a link value: in (0, 1) for the probit and the logit, the value itself (signed) for the identity."""
63
+ _name(name)
64
+ a = np.array(x, dtype=float)
65
+ if not np.all(np.isfinite(a)):
66
+ raise ValueError("x contains non-finite values")
67
+ if name == "identity":
68
+ return a
69
+ return ndtr(a) if name == "probit" else expit(a)
70
+
71
+
72
+ @dataclass(frozen=True)
73
+ class SatelliteFit:
74
+ """A fitted satellite; maps onto the models document `fit.satellites[*]`."""
75
+
76
+ link: str
77
+ window_start: str # ISO quarter end
78
+ window_end: str
79
+ n_obs: int
80
+ ar_order: int
81
+ regressor_names: tuple[str, ...]
82
+ lags: tuple[int, ...]
83
+ coefficient_names: tuple[str, ...] # "intercept", "ar_1".., "<regressor>_lag<k>"
84
+ estimates: tuple[float, ...]
85
+ std_errors: tuple[float, ...]
86
+ r_squared: float
87
+ residual_sd: float
88
+
89
+
90
+ @dataclass(frozen=True)
91
+ class SatelliteProjection:
92
+ """A projected rate path: the link values and the rates (signed on the identity link, read as net recoveries)."""
93
+
94
+ link_values: np.ndarray # (H,)
95
+ rates: np.ndarray # (H,)
96
+
97
+
98
+ def _quarter_index(iso: str, name: str) -> int:
99
+ """The running quarter number of an ISO quarter-end date; refuses a date that is not a quarter end."""
100
+ try:
101
+ d = _dt.date.fromisoformat(str(iso))
102
+ except ValueError as exc:
103
+ raise ValueError(f"{name} {iso!r} is not an ISO date") from exc
104
+ last_day = (d + _dt.timedelta(days=1)).day == 1
105
+ if d.month not in (3, 6, 9, 12) or not last_day:
106
+ raise ValueError(f"{name} {iso!r} is not a quarter end (an ISO date such as 2019-12-31)")
107
+ return d.year * 4 + d.month // 3 - 1
108
+
109
+
110
+ def _lags(lags: Sequence[int]) -> tuple[int, ...]:
111
+ out = tuple(int(k) for k in lags)
112
+ if not out or any(k < 0 for k in out) or len(set(out)) != len(out) or any(int(k) != k for k in lags):
113
+ raise ValueError("lags must be a non-empty set of distinct non-negative integers")
114
+ return out
115
+
116
+
117
+ def fit_satellite(
118
+ rates: np.ndarray,
119
+ regressors: np.ndarray,
120
+ regressor_names: Sequence[str],
121
+ lags: Sequence[int],
122
+ ar_order: int,
123
+ link_name: str,
124
+ quarters: Sequence[str],
125
+ window_start: str,
126
+ window_end: str,
127
+ ) -> SatelliteFit:
128
+ """OLS by `numpy.linalg.lstsq` of `g(rate_t)` on an intercept, `ar_order` lags of itself and every regressor at
129
+ every lag of `lags`, over the quarters of `[window_start, window_end]` only; classical standard errors
130
+ `sqrt(diag(s^2 (X'X)^-1))`.
131
+
132
+ `rates` is (T,), `regressors` (T, P), `quarters` (T,) ISO quarter ends, ascending and contiguous inside the window.
133
+ Only the quarters inside the window enter, and a lag never reaches before the window start: `n_obs` is the number of
134
+ quarters of the window less the largest lag. Coefficient order: intercept, `ar_1..ar_p`, then for each regressor in
135
+ the given order each lag in the given order. A probit or logit fit on a rate outside (0, 1) is refused (use the
136
+ identity link for net
137
+ recoveries)."""
138
+ if link_name not in LINKS:
139
+ raise ValueError(f"unknown link_name {link_name!r}: expected one of {', '.join(LINKS)}")
140
+ if not isinstance(ar_order, (int, np.integer)) or ar_order < 0:
141
+ raise ValueError(f"ar_order must be a non-negative integer, got {ar_order!r}")
142
+ ar_order = int(ar_order)
143
+ lag_set = _lags(lags)
144
+ names = tuple(str(n) for n in regressor_names)
145
+ bad = [n for n in names if n not in AGENCY_REGRESSORS]
146
+ if bad:
147
+ raise ValueError(
148
+ f"regressor {bad[0]} is outside the agency list ({', '.join(AGENCY_REGRESSORS)}): the BBB corporate "
149
+ f"yield and the third-party index levels are not read"
150
+ )
151
+ y_all = np.array(rates, dtype=float)
152
+ x_all = np.array(regressors, dtype=float)
153
+ q = [str(x) for x in quarters]
154
+ if y_all.ndim != 1 or x_all.ndim != 2 or len(q) != y_all.size or x_all.shape[0] != y_all.size:
155
+ raise ValueError(
156
+ f"rates (T,), regressors (T, P) and quarters (T,) must agree, got {y_all.shape}, {x_all.shape} and {len(q)}"
157
+ )
158
+ if x_all.shape[1] != len(names) or len(names) == 0:
159
+ raise ValueError(f"regressor_names has {len(names)} names for {x_all.shape[1]} regressor columns")
160
+ qi = [_quarter_index(x, "quarters") for x in q]
161
+ lo_q, hi_q = _quarter_index(window_start, "window_start"), _quarter_index(window_end, "window_end")
162
+ if lo_q > hi_q:
163
+ raise ValueError(f"window_start {window_start} is after window_end {window_end}")
164
+ if any(b <= a for a, b in zip(qi, qi[1:], strict=False)):
165
+ raise ValueError("quarters must be ascending")
166
+ if lo_q < qi[0]:
167
+ raise ValueError(f"window_start {window_start} is before the first quarter {q[0]}")
168
+ if hi_q > qi[-1]:
169
+ raise ValueError(f"window_end {window_end} is after the last quarter {q[-1]}")
170
+ inside = [k for k, v in enumerate(qi) if lo_q <= v <= hi_q]
171
+ if len(inside) != hi_q - lo_q + 1 or any(qi[inside[k + 1]] - qi[inside[k]] != 1 for k in range(len(inside) - 1)):
172
+ raise ValueError("quarters have a gap inside the window: a missing quarter is never filled")
173
+ sl = slice(inside[0], inside[-1] + 1)
174
+ y, x = y_all[sl], x_all[sl]
175
+ if not np.all(np.isfinite(y)) or not np.all(np.isfinite(x)):
176
+ raise ValueError("rates or regressors contain non-finite values in the window")
177
+ if link_name != "identity":
178
+ if np.any(y <= 0.0):
179
+ raise ValueError(NON_POSITIVE_REASON)
180
+ if np.any(y >= 1.0):
181
+ raise ValueError("a probit or logit fit on a rate of 1 or more: the link needs a rate in (0, 1)")
182
+ g = link(link_name, y)
183
+ big = max([ar_order, *lag_set])
184
+ n = g.size - big
185
+ cols = (
186
+ ["intercept"]
187
+ + [f"ar_{k}" for k in range(1, ar_order + 1)]
188
+ + [f"{r}_lag{lag}" for r in names for lag in lag_set]
189
+ )
190
+ if n < len(cols) + 1:
191
+ raise ValueError(
192
+ f"fewer observations ({n}) than coefficients ({len(cols)}) plus one residual degree of freedom"
193
+ )
194
+ rows = np.arange(big, g.size)
195
+ design = [np.ones(n)]
196
+ design += [g[rows - k] for k in range(1, ar_order + 1)]
197
+ design += [x[rows - lag, j] for j in range(len(names)) for lag in lag_set]
198
+ xm = np.column_stack(design)
199
+ target = g[rows]
200
+ tss = float(((target - target.mean()) ** 2).sum())
201
+ if np.ptp(target) == 0.0:
202
+ raise ValueError("the link values are constant in the window: R squared is undefined (a constant rate)")
203
+ beta, _, rank, _ = np.linalg.lstsq(xm, target, rcond=None)
204
+ if rank < xm.shape[1]:
205
+ raise ValueError(
206
+ f"the design matrix is rank deficient (rank {rank} of {xm.shape[1]}): a regressor is collinear"
207
+ )
208
+ resid = target - xm @ beta
209
+ rss = float(resid @ resid)
210
+ s2 = rss / (n - xm.shape[1])
211
+ se = np.sqrt(np.diag(s2 * np.linalg.inv(xm.T @ xm)))
212
+ r2 = min(1.0, max(0.0, 1.0 - rss / tss))
213
+ return SatelliteFit(
214
+ link=link_name,
215
+ window_start=str(window_start),
216
+ window_end=str(window_end),
217
+ n_obs=int(n),
218
+ ar_order=ar_order,
219
+ regressor_names=names,
220
+ lags=lag_set,
221
+ coefficient_names=tuple(cols),
222
+ estimates=tuple(float(b) for b in beta),
223
+ std_errors=tuple(float(e) for e in se),
224
+ r_squared=float(r2),
225
+ residual_sd=float(np.sqrt(s2)),
226
+ )
227
+
228
+
229
+ def project_scenario(
230
+ fit: SatelliteFit, last_link_values: np.ndarray, regressor_history: np.ndarray, regressor_path: np.ndarray
231
+ ) -> SatelliteProjection:
232
+ """Plug a regressor path into the recursion of the fit and recover the rate path (dossier 04 l.785-795).
233
+
234
+ `last_link_values` is (ar_order,) the last observed link values, most recent last; `regressor_history` is (max lag,
235
+ P) the last observed regressors, most recent last; `regressor_path` is (H, P). The link value of projected quarter t
236
+ is `alpha + sum_k phi_k g_(t-k) + sum_(j, l) beta_(j,l) X_(j, t-l)`; a lag of a quarter before the first projected
237
+ one reads the
238
+ history."""
239
+ p = len(fit.regressor_names)
240
+ lag_set = fit.lags
241
+ big_lag = max(lag_set)
242
+ last = np.array(last_link_values, dtype=float)
243
+ hist = np.array(regressor_history, dtype=float)
244
+ path = np.array(regressor_path, dtype=float)
245
+ if last.shape != (fit.ar_order,):
246
+ raise ValueError(f"last_link_values must have shape ({fit.ar_order},), got {last.shape}")
247
+ if hist.ndim != 2 or hist.shape != (big_lag, p):
248
+ raise ValueError(f"regressor_history must have shape ({big_lag}, {p}), got {hist.shape}")
249
+ if path.ndim != 2 or path.shape[1] != p or path.shape[0] < 1:
250
+ raise ValueError(f"regressor_path must have shape (H >= 1, {p}), got {path.shape}")
251
+ if not (np.all(np.isfinite(last)) and np.all(np.isfinite(hist)) and np.all(np.isfinite(path))):
252
+ raise ValueError("last_link_values, regressor_history and regressor_path must be finite")
253
+ est = np.array(fit.estimates, dtype=float)
254
+ alpha, phi = est[0], est[1 : 1 + fit.ar_order]
255
+ beta = est[1 + fit.ar_order :].reshape(p, len(lag_set))
256
+ xs = np.vstack([hist, path]) if big_lag else path # row big_lag + h is the regressor of projected quarter h + 1
257
+ values: list[float] = []
258
+ for h in range(path.shape[0]):
259
+ value = alpha
260
+ for k in range(1, fit.ar_order + 1):
261
+ prev = values[h - k] if h - k >= 0 else last[last.size - (k - h)]
262
+ value += phi[k - 1] * prev
263
+ for j in range(p):
264
+ for m, lag in enumerate(lag_set):
265
+ value += beta[j, m] * xs[big_lag + h - lag, j]
266
+ values.append(float(value))
267
+ lv = np.array(values)
268
+ return SatelliteProjection(link_values=lv, rates=np.array(inverse_link(fit.link, lv)))