riskvalidation 0.8.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- riskvalidation/__init__.py +30 -0
- riskvalidation/aggregation/__init__.py +11 -0
- riskvalidation/aggregation/band.py +151 -0
- riskvalidation/aggregation/bounds.py +191 -0
- riskvalidation/aggregation/copulas.py +241 -0
- riskvalidation/aggregation/model_risk.py +133 -0
- riskvalidation/aggregation/simple.py +147 -0
- riskvalidation/ccr/__init__.py +13 -0
- riskvalidation/ccr/collateral.py +175 -0
- riskvalidation/ccr/cva.py +193 -0
- riskvalidation/ccr/exposure.py +192 -0
- riskvalidation/ccr/hw1f.py +426 -0
- riskvalidation/ccr/swaps.py +172 -0
- riskvalidation/core/__init__.py +1 -0
- riskvalidation/core/build.py +57 -0
- riskvalidation/core/hashing.py +48 -0
- riskvalidation/core/policy.py +130 -0
- riskvalidation/core/registry.py +65 -0
- riskvalidation/core/result.py +117 -0
- riskvalidation/core/suite.py +78 -0
- riskvalidation/engines/__init__.py +2 -0
- riskvalidation/engines/low_default.py +170 -0
- riskvalidation/engines/pd_curve.py +529 -0
- riskvalidation/engines/vasicek.py +72 -0
- riskvalidation/fairness/__init__.py +10 -0
- riskvalidation/fairness/_checks.py +115 -0
- riskvalidation/fairness/conditional.py +201 -0
- riskvalidation/fairness/inference.py +64 -0
- riskvalidation/fairness/metrics.py +261 -0
- riskvalidation/fairness/plants.py +240 -0
- riskvalidation/fairness/policy.py +97 -0
- riskvalidation/fairness/replication.py +39 -0
- riskvalidation/fairness/situation.py +307 -0
- riskvalidation/generators/__init__.py +68 -0
- riskvalidation/generators/_base.py +145 -0
- riskvalidation/generators/counts.py +232 -0
- riskvalidation/generators/drift.py +107 -0
- riskvalidation/generators/framingham.py +124 -0
- riskvalidation/generators/paths.py +349 -0
- riskvalidation/generators/ratings.py +186 -0
- riskvalidation/generators/scores.py +347 -0
- riskvalidation/harness/__init__.py +46 -0
- riskvalidation/harness/exact.py +137 -0
- riskvalidation/harness/performance.py +74 -0
- riskvalidation/harness/rates.py +103 -0
- riskvalidation/harness/run.py +197 -0
- riskvalidation/irrbb/__init__.py +9 -0
- riskvalidation/irrbb/behavioural.py +206 -0
- riskvalidation/irrbb/curves.py +286 -0
- riskvalidation/irrbb/eve_nii.py +245 -0
- riskvalidation/irrbb/shocks.py +171 -0
- riskvalidation/irrbb/simulation.py +203 -0
- riskvalidation/irrbb/slotting.py +184 -0
- riskvalidation/lgd_ead/__init__.py +8 -0
- riskvalidation/lgd_ead/_checks.py +50 -0
- riskvalidation/lgd_ead/ccf.py +228 -0
- riskvalidation/lgd_ead/downturn.py +64 -0
- riskvalidation/lgd_ead/floors.py +114 -0
- riskvalidation/lgd_ead/lgd_models.py +297 -0
- riskvalidation/lgd_ead/workout.py +162 -0
- riskvalidation/liquidity/__init__.py +9 -0
- riskvalidation/liquidity/_checks.py +78 -0
- riskvalidation/liquidity/cbc.py +158 -0
- riskvalidation/liquidity/deposits.py +151 -0
- riskvalidation/liquidity/ladder.py +119 -0
- riskvalidation/liquidity/reverse.py +141 -0
- riskvalidation/liquidity/runoff.py +220 -0
- riskvalidation/liquidity/scenarios.py +272 -0
- riskvalidation/market/__init__.py +8 -0
- riskvalidation/market/caviar.py +239 -0
- riskvalidation/market/conventions.py +83 -0
- riskvalidation/market/evt.py +111 -0
- riskvalidation/market/frtb.py +175 -0
- riskvalidation/market/garch.py +204 -0
- riskvalidation/market/gas_fz.py +219 -0
- riskvalidation/market/historical.py +96 -0
- riskvalidation/market/parametric.py +78 -0
- riskvalidation/market/scoring.py +145 -0
- riskvalidation/ml/__init__.py +11 -0
- riskvalidation/ml/_checks.py +67 -0
- riskvalidation/ml/_logistic.py +82 -0
- riskvalidation/ml/cbpe.py +91 -0
- riskvalidation/ml/challenger.py +73 -0
- riskvalidation/ml/conformal.py +116 -0
- riskvalidation/ml/dataquality.py +130 -0
- riskvalidation/ml/effects.py +67 -0
- riskvalidation/ml/explanations.py +125 -0
- riskvalidation/ml/generalisation.py +79 -0
- riskvalidation/ml/leakage.py +99 -0
- riskvalidation/ml/plants.py +425 -0
- riskvalidation/ml/policy.py +182 -0
- riskvalidation/ml/robustness.py +286 -0
- riskvalidation/ml/seeds.py +106 -0
- riskvalidation/oprisk/__init__.py +18 -0
- riskvalidation/oprisk/_checks.py +60 -0
- riskvalidation/oprisk/aggregate.py +375 -0
- riskvalidation/oprisk/distributions.py +758 -0
- riskvalidation/oprisk/scenarios.py +342 -0
- riskvalidation/oprisk/sla.py +80 -0
- riskvalidation/oprisk/sma.py +169 -0
- riskvalidation/policies/__init__.py +4 -0
- riskvalidation/policies/default.json +273 -0
- riskvalidation/portfolio/__init__.py +16 -0
- riskvalidation/portfolio/asrf_fit.py +283 -0
- riskvalidation/portfolio/copula.py +129 -0
- riskvalidation/portfolio/creditrisk_plus.py +232 -0
- riskvalidation/portfolio/euler.py +126 -0
- riskvalidation/portfolio/granularity.py +135 -0
- riskvalidation/portfolio/importance.py +277 -0
- riskvalidation/portfolio/portfolio.py +309 -0
- riskvalidation/provisions/__init__.py +8 -0
- riskvalidation/provisions/_checks.py +100 -0
- riskvalidation/provisions/ecl.py +233 -0
- riskvalidation/provisions/local_cl.py +360 -0
- riskvalidation/provisions/local_es.py +157 -0
- riskvalidation/provisions/overlays.py +102 -0
- riskvalidation/provisions/reconciliation.py +157 -0
- riskvalidation/provisions/staging.py +211 -0
- riskvalidation/provisions/term_structure.py +199 -0
- riskvalidation/regulatory/__init__.py +14 -0
- riskvalidation/regulatory/ba_cva.py +138 -0
- riskvalidation/regulatory/frtb.py +345 -0
- riskvalidation/regulatory/irb.py +314 -0
- riskvalidation/regulatory/lcr_nsfr.py +369 -0
- riskvalidation/regulatory/output_floor.py +45 -0
- riskvalidation/regulatory/sa_ccr.py +486 -0
- riskvalidation/regulatory/standardised.py +348 -0
- riskvalidation/stress/__init__.py +9 -0
- riskvalidation/stress/capital.py +476 -0
- riskvalidation/stress/paths.py +108 -0
- riskvalidation/stress/reverse.py +179 -0
- riskvalidation/stress/satellites.py +268 -0
- riskvalidation/stress/scenario_models.py +274 -0
- riskvalidation/transitions/__init__.py +0 -0
- riskvalidation/transitions/em.py +120 -0
- riskvalidation/transitions/embedding.py +221 -0
- riskvalidation/transitions/estimators.py +213 -0
- riskvalidation/transitions/intervals.py +306 -0
- riskvalidation/transitions/mobility.py +57 -0
- riskvalidation/transitions/ttc.py +171 -0
- riskvalidation/validation/__init__.py +103 -0
- riskvalidation/validation/_common.py +57 -0
- riskvalidation/validation/aggregation.py +425 -0
- riskvalidation/validation/calibration.py +757 -0
- riskvalidation/validation/ccr.py +530 -0
- riskvalidation/validation/discrimination.py +314 -0
- riskvalidation/validation/fairness.py +632 -0
- riskvalidation/validation/ifrs9.py +693 -0
- riskvalidation/validation/irrbb.py +389 -0
- riskvalidation/validation/lgd_ead.py +469 -0
- riskvalidation/validation/liquidity.py +647 -0
- riskvalidation/validation/market.py +807 -0
- riskvalidation/validation/ml.py +958 -0
- riskvalidation/validation/oprisk.py +357 -0
- riskvalidation/validation/portfolio.py +353 -0
- riskvalidation/validation/rating_system.py +245 -0
- riskvalidation/validation/stability.py +256 -0
- riskvalidation/validation/stress.py +552 -0
- riskvalidation/validation/transitions.py +386 -0
- riskvalidation-0.8.0.dist-info/METADATA +136 -0
- riskvalidation-0.8.0.dist-info/RECORD +164 -0
- riskvalidation-0.8.0.dist-info/WHEEL +5 -0
- riskvalidation-0.8.0.dist-info/licenses/LICENSE +21 -0
- riskvalidation-0.8.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,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)))
|