Show both downturn severities in the parameter stress

The SBA data holds one macro downturn (2008) but supports a two-level
stress ladder read off realised cohorts:
- adverse  = crisis cohort pooled (2006-08): EL rate 15.3% (3.1x)
- severe   = single worst vintage, auto-detected (2007 peak): EL 17.6% (3.6x)

credit_risk_parameters_stress now reports TTC + adverse + severe with
multipliers; report §10d, README §4 and the stress chart (3-bar ladder)
updated. README §4 also notes the two stress lenses in the repo: this
parameter stress (whole-book baseline) vs the limit-linked charge-off
stress in §9 (seasoned baseline). Tests updated (33 pass).

Author: Jane511

README.md

@@ -143,26 +143,37 @@ cost, opex and a capital charge. It varies ~9× across sectors:
 
 ## 4. Stress test — downturn PD / LGD / EL
 
-The 2006–08 financial-crisis vintages the data already contains are a **realised
-downturn scenario**. Both **PD and LGD rise**, so EL rises multiplicatively —
-the downturn-PD / downturn-LGD inputs for stressed pricing and capital
+The SBA data (FY2000–2019) contains **one** macro downturn — the 2008 financial
+crisis — but it supports a **two-level stress ladder** read straight off the
+realised cohorts (both are fully seasoned, so near-final):
+
+- **Adverse** = the crisis cohort pooled (2006–08)
+- **Severe** = the single worst vintage, the peak of the crisis (**2007**, auto-detected)
+
+Both **PD and LGD rise**, so EL rises multiplicatively
 ([09_…stress.csv](outputs/tables/09_credit_risk_parameters_stress.csv)):
 
-| Parameter | Through-the-cycle | Crisis / downturn (2006–08) | Stress multiplier |
-|---|---:|---:|---:|
-| PD — default rate (obligor-weighted) | 12.2% | 25.9% | **2.1×** |
-| PD — default rate (exposure-weighted) | 7.7% | 21.9% | **2.8×** |
-| LGD — loss given default | 64.0% | 70.0% | **1.1×** |
-| EAD — avg exposure per loan | $264,769 | $154,065 | 0.6× |
-| **EL rate — expected loss / exposure** | **4.9%** | **15.3%** | **3.1×** |
-
-![Parameter stress — downturn vs through-the-cycle](outputs/charts/parameters_stress.png)
-
-The headline: **expected loss roughly triples (4.9% → 15.3%)** in a downturn,
-driven mostly by PD doubling with LGD adding ~9% on top. (EAD *falls* — crisis
-cohorts were smaller loans — so it is not a stress driver; exposure is fixed at
-approval.) This feeds the limit-linked charge-off stress in report §9 and
-[08_stress_scenario.csv](outputs/tables/08_stress_scenario.csv).
+| Parameter | Through-the-cycle | Adverse (2006–08) | × | Severe (2007) | × |
+|---|---:|---:|---:|---:|---:|
+| PD — default rate (obligor-weighted) | 12.2% | 25.9% | **2.1×** | 28.8% | **2.4×** |
+| PD — default rate (exposure-weighted) | 7.7% | 21.9% | **2.8×** | 24.4% | **3.2×** |
+| LGD — loss given default | 64.0% | 70.0% | **1.1×** | 71.9% | **1.1×** |
+| EAD — avg exposure per loan | $264,769 | $154,065 | 0.6× | $142,500 | 0.5× |
+| **EL rate — expected loss / exposure** | **4.9%** | **15.3%** | **3.1×** | **17.6%** | **3.6×** |
+
+![Parameter stress ladder — adverse & severe vs through-the-cycle](outputs/charts/parameters_stress.png)
+
+The headline: **expected loss roughly triples** in a downturn (4.9% → 15.3%
+adverse → 17.6% severe), driven mostly by PD doubling with LGD adding ~9–12% on
+top. (EAD *falls* — crisis cohorts were smaller loans — so it is not a stress
+driver; exposure is fixed at approval.)
+
+> **Two stress views in the repo, by design.** This *parameter* stress (PD/LGD/EAD/EL,
+> whole-book TTC baseline) sits alongside the limit-linked **charge-off-rate
+> stress** in report §9 / [08_stress_scenario.csv](outputs/tables/08_stress_scenario.csv),
+> which uses a *seasoned-only* baseline (13.5%) so it can be re-tested against the
+> risk-appetite charge-off limit. Same crisis, two lenses — pricing/ECL inputs
+> here, appetite-limit breach there.
 
 ---
 

outputs/charts/parameters_stress.png

@@ -255,15 +255,15 @@ _Realised, **through-the-cycle** parameters read off the FY2000-2019 outcome dat
 | Collateral | Secured | 436,969 | 8.8% | 62.9% | $410,653 | 3.4% |
 | Collateral | Unsecured | 650,050 | 14.5% | 64.8% | $166,705 | 7.5% |
 
-**10d. Parameter stress test — through-the-cycle vs the downturn (2006, 2007, 2008).** The financial-crisis vintages are a realised, data-grounded downturn: **both PD and LGD rise**, so EL rises multiplicatively. These are the downturn-PD / downturn-LGD inputs for stressed pricing and capital:
+**10d. Parameter stress test — the two downturn severities in the data.** The SBA data holds one macro downturn (the 2008 crisis) but supports a two-level stress ladder read off realised cohorts: **adverse** = the crisis cohort pooled (2006, 2007, 2008); **severe** = the single worst vintage (2007, the peak). PD and LGD both rise, so EL rises multiplicatively — downturn-PD / downturn-LGD inputs for stressed pricing and capital:
 
-| Parameter | Through-the-cycle | Crisis / downturn | Stress multiplier |
-|---|---|---|---|
-| PD — default rate (obligor-weighted) | 12.2% | 25.9% | 2.13x |
-| PD — default rate (exposure-weighted) | 7.7% | 21.9% | 2.85x |
-| LGD — loss given default | 64.0% | 70.0% | 1.09x |
-| EAD — avg exposure per loan ($) | $264,769 | $154,065 | 0.58x |
-| EL rate — expected loss / exposure | 4.9% | 15.3% | 3.11x |
+| Parameter | Through-the-cycle | Adverse (2006, 2007, 2008) | × | Severe (2007) | × |
+|---|---|---|---|---|---|
+| PD — default rate (obligor-weighted) | 12.2% | 25.9% | 2.13x | 28.8% | 2.36x |
+| PD — default rate (exposure-weighted) | 7.7% | 21.9% | 2.85x | 24.4% | 3.18x |
+| LGD — loss given default | 64.0% | 70.0% | 1.09x | 71.9% | 1.12x |
+| EAD — avg exposure per loan ($) | $264,769 | $154,065 | 0.58x | $142,500 | 0.54x |
+| EL rate — expected loss / exposure | 4.9% | 15.3% | 3.11x | 17.6% | 3.57x |
 
 ## Notes — APS 330 / Pillar 3 & governance
 

outputs/reports/report.md

@@ -1,6 +1,6 @@
-metric_key,parameter,through_the_cycle,crisis_downturn,stress_multiplier,crisis_vintages
-pd_count,PD — default rate (obligor-weighted),0.122,0.2594,2.13,"2006, 2007, 2008"
-pd_dollar,PD — default rate (exposure-weighted),0.0769,0.2188,2.85,"2006, 2007, 2008"
-lgd,LGD — loss given default,0.6401,0.6998,1.09,"2006, 2007, 2008"
-ead_avg,EAD — avg exposure per loan ($),264769.0,154065.0,0.58,"2006, 2007, 2008"
-el_rate,EL rate — expected loss / exposure,0.0492,0.1531,3.11,"2006, 2007, 2008"
+metric_key,parameter,through_the_cycle,adverse_downturn,adverse_multiplier,severe,severe_multiplier,adverse_vintages,severe_vintage
+pd_count,PD — default rate (obligor-weighted),0.122,0.2594,2.13,0.2882,2.36,"2006, 2007, 2008",2007
+pd_dollar,PD — default rate (exposure-weighted),0.0769,0.2188,2.85,0.2442,3.18,"2006, 2007, 2008",2007
+lgd,LGD — loss given default,0.6401,0.6998,1.09,0.719,1.12,"2006, 2007, 2008",2007
+ead_avg,EAD — avg exposure per loan ($),264769.0,154065.0,0.58,142500.0,0.54,"2006, 2007, 2008",2007
+el_rate,EL rate — expected loss / exposure,0.0492,0.1531,3.11,0.1756,3.57,"2006, 2007, 2008",2007

outputs/tables/09_credit_risk_parameters_stress.csv

@@ -136,22 +136,34 @@ def credit_risk_parameters_by_product(df: pd.DataFrame) -> pd.DataFrame:
 
 def credit_risk_parameters_stress(df: pd.DataFrame,
                                   config: dict | None = None) -> pd.DataFrame:
-    """Stress the parameters: through-the-cycle book vs the 2006-08 downturn.
-
-    The financial-crisis vintages the data already contains are used as a
-    realised, data-grounded downturn scenario. For each parameter we report the
-    through-the-cycle (whole-book) value, the crisis-cohort value, and the
-    implied **stress multiplier** (crisis / TTC). PD and LGD both rise in the
-    downturn, so EL rises multiplicatively — a downturn-PD / downturn-LGD view
-    for capital and limit-setting (the crisis vintages are fully seasoned, so
-    these are near-final outcomes).
+    """Stress the parameters using the two downturn severities the data contains.
+
+    The SBA data (FY2000-2019) holds one macro downturn — the 2008 financial
+    crisis — but it supports a two-level stress *ladder* read straight off the
+    realised cohorts:
+
+      * **Adverse / downturn** — the crisis cohort pooled (config
+        ``stress.crisis_vintages``, 2006-08).
+      * **Severe** — the single worst seasoned vintage (the peak of the crisis,
+        auto-detected by charge-off rate — 2007).
+
+    For each parameter we report the through-the-cycle (whole-book) value and
+    both stressed values with their multiplier vs TTC. PD and LGD both rise, so
+    EL rises multiplicatively — the downturn-PD / downturn-LGD inputs for
+    stressed pricing and capital. (Crisis vintages are fully seasoned, so these
+    are near-final outcomes.)
     """
     cfg = config or load_config()
     crisis_vintages = sorted(set(cfg["stress"]["crisis_vintages"]))
 
     ttc = _parameter_frame(df, None, "ttc").iloc[0]
-    crisis = _parameter_frame(
-        df[df["vintage"].isin(crisis_vintages)], None, "crisis").iloc[0]
+    downturn = _parameter_frame(
+        df[df["vintage"].isin(crisis_vintages)], None, "downturn").iloc[0]
+
+    # Severe = the single worst seasoned vintage by charge-off rate (auto).
+    seasoned = df[df["fully_seasoned"]]
+    peak_vintage = int(seasoned.groupby("vintage")["is_default"].mean().idxmax())
+    severe = _parameter_frame(df[df["vintage"] == peak_vintage], None, "severe").iloc[0]
 
     specs = [
         ("pd_count", "PD — default rate (obligor-weighted)"),
@@ -162,22 +174,24 @@ def credit_risk_parameters_stress(df: pd.DataFrame,
     ]
     rows = []
     for key, label in specs:
-        b, s = float(ttc[key]), float(crisis[key])
+        b, d, s = float(ttc[key]), float(downturn[key]), float(severe[key])
         rows.append({
             "metric_key": key,
             "parameter": label,
             "through_the_cycle": round(b, 4),
-            "crisis_downturn": round(s, 4),
-            "stress_multiplier": round(s / b, 2) if b else float("nan"),
+            "adverse_downturn": round(d, 4),
+            "adverse_multiplier": round(d / b, 2) if b else float("nan"),
+            "severe": round(s, 4),
+            "severe_multiplier": round(s / b, 2) if b else float("nan"),
         })
     out = pd.DataFrame(rows)
-    out["crisis_vintages"] = ", ".join(str(v) for v in crisis_vintages)
+    out["adverse_vintages"] = ", ".join(str(v) for v in crisis_vintages)
+    out["severe_vintage"] = peak_vintage
     _log.info(
-        "Parameter stress (crisis %s): PD %.1f%%->%.1f%%, LGD %.1f%%->%.1f%%, "
-        "EL %.1f%%->%.1f%%", crisis_vintages,
-        ttc["pd_count"] * 100, crisis["pd_count"] * 100,
-        ttc["lgd"] * 100, crisis["lgd"] * 100,
-        ttc["el_rate"] * 100, crisis["el_rate"] * 100,
+        "Parameter stress — EL rate: TTC %.1f%% -> adverse %.1f%% (%s) -> "
+        "severe %.1f%% (%d peak)",
+        ttc["el_rate"] * 100, downturn["el_rate"] * 100, crisis_vintages,
+        severe["el_rate"] * 100, peak_vintage,
     )
     return out
 

src/credit_parameters.py

@@ -421,20 +421,23 @@ def build_markdown_report(
             a("")
 
         if credit_params_stress is not None and not credit_params_stress.empty:
-            vint = credit_params_stress["crisis_vintages"].iloc[0]
-            a(f"**10d. Parameter stress test — through-the-cycle vs the downturn "
-              f"({vint}).** The financial-crisis vintages are a realised, "
-              "data-grounded downturn: **both PD and LGD rise**, so EL rises "
-              "multiplicatively. These are the downturn-PD / downturn-LGD inputs "
-              "for stressed pricing and capital:")
+            adv = credit_params_stress["adverse_vintages"].iloc[0]
+            sev = int(credit_params_stress["severe_vintage"].iloc[0])
+            a("**10d. Parameter stress test — the two downturn severities in the "
+              "data.** The SBA data holds one macro downturn (the 2008 crisis) "
+              "but supports a two-level stress ladder read off realised cohorts: "
+              f"**adverse** = the crisis cohort pooled ({adv}); **severe** = the "
+              f"single worst vintage ({sev}, the peak). PD and LGD both rise, so "
+              "EL rises multiplicatively — downturn-PD / downturn-LGD inputs for "
+              "stressed pricing and capital:")
             a("")
-            a("| Parameter | Through-the-cycle | Crisis / downturn | Stress multiplier |")
-            a("|---|---|---|---|")
+            a(f"| Parameter | Through-the-cycle | Adverse ({adv}) | × | Severe ({sev}) | × |")
+            a("|---|---|---|---|---|---|")
             for _, r in credit_params_stress.iterrows():
-                money = r["metric_key"] == "ead_avg"
-                fmt = _fmt_money if money else _fmt_pct
+                fmt = _fmt_money if r["metric_key"] == "ead_avg" else _fmt_pct
                 a(f"| {r['parameter']} | {fmt(r['through_the_cycle'])} | "
-                  f"{fmt(r['crisis_downturn'])} | {r['stress_multiplier']:.2f}x |")
+                  f"{fmt(r['adverse_downturn'])} | {r['adverse_multiplier']:.2f}x | "
+                  f"{fmt(r['severe'])} | {r['severe_multiplier']:.2f}x |")
             a("")
 
     a("## Notes — APS 330 / Pillar 3 & governance")

src/report.py

@@ -329,11 +329,13 @@ def test_credit_parameters_by_structure(base):
 def test_credit_parameters_stress(base, cfg):
     out = cp.credit_risk_parameters_stress(base, config=cfg)
     assert {"pd_count", "lgd", "el_rate"} <= set(out["metric_key"])
-    assert {"through_the_cycle", "crisis_downturn", "stress_multiplier"} <= set(out.columns)
-    # Crisis cohorts default worse → PD and EL multipliers exceed 1 in the fixture.
-    pd_row = out.set_index("metric_key").loc["pd_count"]
-    assert pd_row["crisis_downturn"] > pd_row["through_the_cycle"]
-    assert out.set_index("metric_key").loc["el_rate", "stress_multiplier"] > 1.0
+    assert {"through_the_cycle", "adverse_downturn", "adverse_multiplier",
+            "severe", "severe_multiplier"} <= set(out.columns)
+    s = out.set_index("metric_key")
+    # Crisis cohorts default worse than the book; severe (peak) >= adverse (pooled).
+    assert s.loc["pd_count", "adverse_downturn"] > s.loc["pd_count", "through_the_cycle"]
+    assert s.loc["el_rate", "adverse_multiplier"] > 1.0
+    assert s.loc["el_rate", "severe"] >= s.loc["el_rate", "adverse_downturn"]
 
 
 # --------------------------------------------------------------------------- #

tests/test_pipeline.py

@@ -118,26 +118,32 @@ def _barh_labels(ax, values, fmt="{:.1f}%"):
 ax.grid(axis="y", alpha=0)
 save(fig, "el_by_sector.png")
 
-# 6. Parameter stress — downturn vs through-the-cycle ------------------------
+# 6. Parameter stress — the two downturn severities in the data --------------
 st = pd.read_csv(TAB / "09_credit_risk_parameters_stress.csv").set_index("metric_key")
-vint = str(st["crisis_vintages"].iloc[0])
+adv_v = str(st["adverse_vintages"].iloc[0])
+sev_v = int(st["severe_vintage"].iloc[0])
 keys = ["pd_count", "lgd", "el_rate"]
 labels = ["PD\n(default rate)", "LGD\n(loss given default)", "EL rate\n(expected loss)"]
 ttc = [st.loc[k, "through_the_cycle"] * 100 for k in keys]
-cri = [st.loc[k, "crisis_downturn"] * 100 for k in keys]
-mult = [st.loc[k, "stress_multiplier"] for k in keys]
+adv = [st.loc[k, "adverse_downturn"] * 100 for k in keys]
+sev = [st.loc[k, "severe"] * 100 for k in keys]
+adv_m = [st.loc[k, "adverse_multiplier"] for k in keys]
+sev_m = [st.loc[k, "severe_multiplier"] for k in keys]
 x = np.arange(len(keys))
-w = 0.38
-fig, ax = plt.subplots(figsize=(8.8, 5.4))
-ax.bar(x - w / 2, ttc, w, label="through-the-cycle (FY2000–2019)", color=BLUE)
-b2 = ax.bar(x + w / 2, cri, w, label=f"crisis / downturn ({vint})", color=RED)
-for xi, c, m in zip(x, cri, mult):
-    ax.text(xi + w / 2, c, f"{m:.1f}×", ha="center", va="bottom", fontsize=11, fontweight="bold")
+w = 0.27
+fig, ax = plt.subplots(figsize=(9.6, 5.6))
+ax.bar(x - w, ttc, w, label="through-the-cycle (FY2000–2019)", color=BLUE)
+ax.bar(x, adv, w, label=f"adverse — crisis cohort ({adv_v})", color="#ef8a62")
+ax.bar(x + w, sev, w, label=f"severe — peak vintage ({sev_v})", color=RED)
+for xi, v, m in zip(x, adv, adv_m):
+    ax.text(xi, v, f"{m:.1f}×", ha="center", va="bottom", fontsize=9.5)
+for xi, v, m in zip(x, sev, sev_m):
+    ax.text(xi + w, v, f"{m:.1f}×", ha="center", va="bottom", fontsize=9.5, fontweight="bold")
 ax.set_xticks(x)
 ax.set_xticklabels(labels)
 ax.set_ylabel("rate (%)")
-ax.set_title("Parameter stress test — downturn vs through-the-cycle")
-ax.legend(frameon=False)
+ax.set_title("Parameter stress ladder — adverse & severe vs through-the-cycle")
+ax.legend(frameon=False, fontsize=10)
 ax.grid(axis="x", alpha=0)
 save(fig, "parameters_stress.png")