"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Credit-risk primitives: Altman Z-Score, Merton/KMV, CDS pricing, and spread analytics.
All rates and ratios are decimals unless a name ends in ``_bp``.
"""
from __future__ import annotations
import math
from collections.abc import Mapping
from dataclasses import dataclass
import numpy as np
import pandas as pd
from scipy.optimize import fsolve
from scipy.stats import norm
__all__ = [
"ALTMAN_MODELS",
"AltmanModelSpec",
"AltmanZScore",
"MertonResult",
"SPREAD_INPUT_UNITS",
"EDF_REFERENCE_BANDS",
"MERTON_SOLVER_RESTARTS",
"MERTON_SOLVER_STEP_TOL",
"ZONE_LABELS_ZH",
"altman_z_score",
"merton_asset_solve",
"merton_model",
"distance_to_default",
"kmv_default_point",
"kmv_distance_to_default",
"edf_reference_band",
"credit_spread_analysis",
"spread_term_structure",
"hazard_rate_to_survival_probability",
"survival_probability_to_hazard_rate",
"cds_price",
"expected_loss",
"vasicek_credit_var",
"credit_spread_dv01",
]
@dataclass(frozen=True)
class AltmanModelSpec:
"""Coefficients and cut-offs of one Altman Z-Score variant.
Attributes:
coefficients: Weights on ``(X1, X2, X3, X4, X5)``. ``X5`` carries a
weight of 0.0 in variants that drop the asset-turnover term.
safe_threshold: Scores strictly above this sit in the safe zone.
distress_threshold: Scores strictly below this sit in the distress zone.
uses_x5: Whether the variant needs a revenue figure at all.
equity_basis: What ``equity_value`` must be for this variant --
``"market"`` for the market capitalisation, ``"book"`` for the book
value of equity.
"""
coefficients: tuple[float, float, float, float, float]
safe_threshold: float
distress_threshold: float
uses_x5: bool
equity_basis: str
#: The three published Altman variants carried by the credit-analysis skill.
ALTMAN_MODELS: Mapping[str, AltmanModelSpec] = {
# Altman (1968), listed manufacturers.
"original": AltmanModelSpec((1.2, 1.4, 3.3, 0.6, 1.0), 2.99, 1.81, True, "market"),
# Z' -- privately held firms; X4 switches to book equity.
"prime": AltmanModelSpec((0.717, 0.847, 3.107, 0.420, 0.998), 2.90, 1.23, True, "book"),
# Z'' -- non-manufacturers / emerging markets; X5 dropped entirely.
"double_prime": AltmanModelSpec((6.56, 3.26, 6.72, 1.05, 0.0), 2.60, 1.10, False, "book"),
}
#: Chinese labels for the three Z-Score zones, as printed in the skill.
ZONE_LABELS_ZH: Mapping[str, str] = {
"safe": "安全区(低违约风险)",
"grey": "灰色区(需深入分析)",
"distress": "危险区(高违约风险)",
}
@dataclass(frozen=True)
class AltmanZScore:
"""Outcome of an Altman Z-Score evaluation.
Attributes:
z_score: The composite score.
model: Which variant produced it; a key of :data:`ALTMAN_MODELS`.
zone: ``"safe"``, ``"grey"`` or ``"distress"``.
label_zh: The Chinese zone label from :data:`ZONE_LABELS_ZH`.
components: The ``X1``..``X5`` ratios. ``x5`` is ``None`` for variants
that do not use it.
safe_threshold: Cut-off above which the zone is ``"safe"``.
distress_threshold: Cut-off below which the zone is ``"distress"``.
"""
z_score: float
model: str
zone: str
label_zh: str
components: Mapping[str, float | None]
safe_threshold: float
distress_threshold: float
def _require_finite(value: float, name: str) -> float:
"""Check a value is a finite number, refusing NaN and infinity.
Args:
value: The candidate value.
name: Field name for the error message.
Returns:
``value`` unchanged (its int/float type is preserved).
Raises:
ValueError: If the value is not a finite number. A non-finite input
here would otherwise flow through the range guards (which are all
false for NaN) and surface as a NaN score, probability or zone.
"""
if not math.isfinite(value):
raise ValueError(f"{name} must be a finite number, got {value!r}")
return value
def altman_z_score(
*,
working_capital: float,
retained_earnings: float,
ebit: float,
equity_value: float,
total_liabilities: float,
total_assets: float,
revenue: float | None = None,
model: str = "original",
) -> AltmanZScore:
"""Score a firm's distress risk with one of the three Altman variants.
Every argument is keyword-only, deliberately. Six interchangeable float
parameters is exactly the shape where a positional call silently computes
the wrong answer, and this signature does not match the argument order of
the markdown block it replaced -- ``revenue`` and ``total_assets`` are
swapped relative to it. A positional call written from memory of the old
block would divide by revenue and return a confident, wrong Z with no
error. Keyword-only makes that a ``TypeError`` instead.
Args:
working_capital: Current assets less current liabilities.
retained_earnings: Cumulative retained earnings.
ebit: Earnings before interest and tax.
equity_value: Market capitalisation for ``"original"``; book value of
equity for ``"prime"`` and ``"double_prime"``. The required basis is
recorded on each :class:`AltmanModelSpec`.
total_liabilities: Book value of *all* liabilities, not just interest
bearing debt. This is the X4 denominator in Altman's definition.
total_assets: Total assets; the denominator of X1, X2, X3 and X5.
revenue: Sales for the period. Required unless the variant drops X5.
model: A key of :data:`ALTMAN_MODELS`.
Returns:
An :class:`AltmanZScore` with the score, the zone and every input ratio.
Raises:
ValueError: If ``model`` is unknown, a denominator is zero, or the
variant needs ``revenue`` and it was not supplied.
"""
spec = ALTMAN_MODELS.get(model)
if spec is None:
raise ValueError(
f"unknown model {model!r}; expected one of {tuple(ALTMAN_MODELS)}"
)
working_capital = _require_finite(working_capital, "working_capital")
retained_earnings = _require_finite(retained_earnings, "retained_earnings")
ebit = _require_finite(ebit, "ebit")
equity_value = _require_finite(equity_value, "equity_value")
total_liabilities = _require_finite(total_liabilities, "total_liabilities")
total_assets = _require_finite(total_assets, "total_assets")
if revenue is not None:
revenue = _require_finite(revenue, "revenue")
if total_assets == 0:
raise ValueError("total_assets must be non-zero")
if total_liabilities == 0:
raise ValueError("total_liabilities must be non-zero")
if spec.uses_x5 and revenue is None:
raise ValueError(f"model {model!r} needs revenue for the X5 term")
x1 = working_capital / total_assets
x2 = retained_earnings / total_assets
x3 = ebit / total_assets
x4 = equity_value / total_liabilities
x5 = revenue / total_assets if spec.uses_x5 else None
weights = spec.coefficients
z = weights[0] * x1 + weights[1] * x2 + weights[2] * x3 + weights[3] * x4
if x5 is not None:
z += weights[4] * x5
if z > spec.safe_threshold:
zone = "safe"
elif z < spec.distress_threshold:
zone = "distress"
else:
zone = "grey"
return AltmanZScore(
z_score=float(z),
model=model,
zone=zone,
label_zh=ZONE_LABELS_ZH[zone],
components={"x1": x1, "x2": x2, "x3": x3, "x4": x4, "x5": x5},
safe_threshold=spec.safe_threshold,
distress_threshold=spec.distress_threshold,
)
@dataclass(frozen=True)
class MertonResult:
"""Solved Merton structural model for one issuer.
Attributes:
asset_value: Implied market value of assets, in the units of the inputs.
asset_vol: Implied annualised asset volatility as a decimal.
d1: Black-Scholes ``d1`` on the asset value.
d2: Black-Scholes ``d2``; equals the risk-neutral distance to default.
distance_to_default: Distance to default at ``asset_drift``. When the
drift is the risk-free rate this is exactly ``d2``.
default_probability: Risk-neutral default probability ``N(-d2)``.
debt_value: Present value of the risky zero-coupon debt.
credit_spread: Continuously compounded spread over the risk-free rate,
as a decimal.
"""
asset_value: float
asset_vol: float
d1: float
d2: float
distance_to_default: float
default_probability: float
debt_value: float
credit_spread: float
@property
def credit_spread_bp(self) -> float:
"""Credit spread expressed in basis points.
Returns:
``credit_spread`` multiplied by 10000.
"""
return self.credit_spread * 1e4
def _merton_d1_d2(
asset_value: float,
asset_vol: float,
debt_face: float,
risk_free: float,
horizon: float,
) -> tuple[float, float]:
"""Black-Scholes ``d1``/``d2`` for equity written on the firm's assets.
Args:
asset_value: Market value of assets.
asset_vol: Annualised asset volatility as a decimal.
debt_face: Face value of the zero-coupon debt.
risk_free: Continuously compounded risk-free rate as a decimal.
horizon: Years to the debt's maturity.
Returns:
Tuple ``(d1, d2)``.
"""
vol_t = asset_vol * math.sqrt(horizon)
d1 = (
math.log(asset_value / debt_face) + (risk_free + 0.5 * asset_vol**2) * horizon
) / vol_t
return d1, d1 - vol_t
#: Step tolerance handed to the Merton root finder (pinned near machine precision in log space).
MERTON_SOLVER_STEP_TOL: float = 1e-13
#: Extra solves started from the previous answer when the residual still misses.
MERTON_SOLVER_RESTARTS: int = 2
def merton_asset_solve(
equity_value: float,
equity_vol: float,
debt_face: float,
risk_free: float,
horizon: float,
tolerance: float = 1e-8,
) -> tuple[float, float]:
"""Back out asset value and asset volatility from observable equity.
Solves the standard pair of equations simultaneously::
E = V*N(d1) - D*exp(-r*T)*N(d2)
sigma_E = N(d1) * sigma_V * V / E
The unknowns are solved in log space to enforce strictly positive domain.
Args:
equity_value: Market capitalisation.
equity_vol: Annualised equity volatility as a decimal.
debt_face: Face value of debt, treated as a single zero-coupon claim.
risk_free: Continuously compounded risk-free rate as a decimal.
horizon: Years to the debt's maturity.
tolerance: Largest acceptable relative residual to ``equity_value``.
Returns:
Tuple ``(asset_value, asset_vol)``.
Raises:
ValueError: If any input is non-positive or system fails to converge.
"""
equity_value = _require_finite(equity_value, "equity_value")
equity_vol = _require_finite(equity_vol, "equity_vol")
debt_face = _require_finite(debt_face, "debt_face")
risk_free = _require_finite(risk_free, "risk_free")
horizon = _require_finite(horizon, "horizon")
if min(equity_value, equity_vol, debt_face, horizon) <= 0:
raise ValueError(
"equity_value, equity_vol, debt_face and horizon must all be positive"
)
def residuals(log_params: np.ndarray) -> list[float]:
asset_value, asset_vol = np.exp(log_params)
d1, d2 = _merton_d1_d2(asset_value, asset_vol, debt_face, risk_free, horizon)
equity_eq = (
asset_value * norm.cdf(d1)
- debt_face * math.exp(-risk_free * horizon) * norm.cdf(d2)
- equity_value
)
vol_eq = norm.cdf(d1) * asset_vol * asset_value - equity_vol * equity_value
return [equity_eq / equity_value, vol_eq / equity_value]
start_value = equity_value + debt_face * math.exp(-risk_free * horizon)
point = np.log([start_value, equity_vol * equity_value / start_value])
for _ in range(MERTON_SOLVER_RESTARTS + 1):
point = fsolve(
residuals, point, full_output=True, xtol=MERTON_SOLVER_STEP_TOL
)[0]
worst = max(abs(r) for r in residuals(point))
if math.isfinite(worst) and worst <= tolerance:
break
else:
raise ValueError(
"Merton system did not converge: worst scaled residual "
f"{worst:.3g} exceeds tolerance {tolerance:g}"
)
asset_value, asset_vol = (float(v) for v in np.exp(point))
return asset_value, asset_vol
def merton_model(
equity_value: float,
equity_vol: float,
debt_face: float,
risk_free: float,
horizon: float,
asset_drift: float | None = None,
) -> MertonResult:
"""Estimate default probability and credit spread from equity market data.
Args:
equity_value: Market capitalisation.
equity_vol: Annualised equity volatility as a decimal.
debt_face: Face value of debt, treated as a single zero-coupon claim.
risk_free: Continuously compounded risk-free rate as a decimal.
horizon: Years to the debt's maturity.
asset_drift: Expected asset return used for the real-world distance to
default. Defaults to ``risk_free``, which is what the markdown did;
supplying an equity-style drift instead gives the KMV reading.
Returns:
A :class:`MertonResult`.
Raises:
ValueError: If an input is non-positive or the asset system does not
converge.
"""
asset_value, asset_vol = merton_asset_solve(
equity_value, equity_vol, debt_face, risk_free, horizon
)
d1, d2 = _merton_d1_d2(asset_value, asset_vol, debt_face, risk_free, horizon)
drift = risk_free if asset_drift is None else asset_drift
discounted_face = debt_face * math.exp(-risk_free * horizon)
debt_value = float(
discounted_face * norm.cdf(d2) + asset_value * norm.cdf(-d1)
)
spread = -math.log(debt_value / discounted_face) / horizon
return MertonResult(
asset_value=asset_value,
asset_vol=asset_vol,
d1=d1,
d2=d2,
distance_to_default=distance_to_default(
asset_value, asset_vol, debt_face, horizon, drift
),
default_probability=float(norm.cdf(-d2)),
debt_value=debt_value,
credit_spread=spread,
)
def distance_to_default(
asset_value: float,
asset_vol: float,
default_point: float,
horizon: float,
drift: float = 0.0,
) -> float:
"""Merton distance to default, in standard deviations of log asset value.
Args:
asset_value: Market value of assets.
asset_vol: Annualised asset volatility as a decimal.
default_point: Asset level at which default is triggered. Merton uses
the full face value of debt; KMV uses :func:`kmv_default_point`.
horizon: Years to the measurement date.
drift: Expected asset return. Pass the risk-free rate for the
risk-neutral reading, an expected return for the real-world one.
Returns:
Distance to default. Larger is safer; under a lognormal assumption the
matching default probability is ``N(-dd)``.
Raises:
ValueError: If any of the value, volatility, default point or horizon is
non-positive.
"""
asset_value = _require_finite(asset_value, "asset_value")
asset_vol = _require_finite(asset_vol, "asset_vol")
default_point = _require_finite(default_point, "default_point")
horizon = _require_finite(horizon, "horizon")
drift = _require_finite(drift, "drift")
if min(asset_value, asset_vol, default_point, horizon) <= 0:
raise ValueError(
"asset_value, asset_vol, default_point and horizon must all be positive"
)
numerator = math.log(asset_value / default_point) + (
drift - 0.5 * asset_vol**2
) * horizon
return numerator / (asset_vol * math.sqrt(horizon))
def kmv_default_point(
short_term_debt: float,
long_term_debt: float,
long_term_weight: float = 0.5,
) -> float:
"""KMV default point: all short-term debt plus part of the long-term book.
Args:
short_term_debt: Debt maturing inside one year.
long_term_debt: Debt maturing beyond one year.
long_term_weight: Fraction of long-term debt included. Moody's KMV uses
0.5; it is an argument because the calibration is a convention, not
a result.
Returns:
The default point in the units of the inputs.
Raises:
ValueError: If either debt figure is negative, or the weight is outside
``[0, 1]``.
"""
short_term_debt = _require_finite(short_term_debt, "short_term_debt")
long_term_debt = _require_finite(long_term_debt, "long_term_debt")
long_term_weight = _require_finite(long_term_weight, "long_term_weight")
if short_term_debt < 0 or long_term_debt < 0:
raise ValueError("debt figures must be non-negative")
if not 0.0 <= long_term_weight <= 1.0:
raise ValueError(f"long_term_weight must lie in [0, 1], got {long_term_weight}")
return short_term_debt + long_term_weight * long_term_debt
def kmv_distance_to_default(
asset_value: float,
asset_vol: float,
default_point: float,
) -> float:
"""KMV's linear distance to default, ``(V - DP) / (V * sigma_V)``.
This is the form the skill documents for KMV and is *not* the same quantity
as :func:`distance_to_default`: it measures the gap in units of the asset
value's own standard deviation rather than in log space, and it carries no
horizon or drift. Keep the two apart -- KMV then maps this number to an
empirical EDF rather than through the normal CDF.
Args:
asset_value: Market value of assets.
asset_vol: Annualised asset volatility as a decimal.
default_point: Output of :func:`kmv_default_point`.
Returns:
Distance to default in standard deviations. Larger is safer; negative
means assets already sit below the default point.
Raises:
ValueError: If ``asset_value`` or ``asset_vol`` is non-positive.
"""
asset_value = _require_finite(asset_value, "asset_value")
asset_vol = _require_finite(asset_vol, "asset_vol")
default_point = _require_finite(default_point, "default_point")
if asset_value <= 0 or asset_vol <= 0:
raise ValueError("asset_value and asset_vol must be positive")
return (asset_value - default_point) / (asset_value * asset_vol)
#: Reference DD-to-EDF bands from the skill, as ``(dd_floor, edf_low, edf_high)``
#: with EDF as decimals. ``math.inf`` marks an open end.
EDF_REFERENCE_BANDS: tuple[tuple[float, float, float], ...] = (
(4.0, 0.0, 0.001),
(2.0, 0.001, 0.01),
(1.0, 0.01, 0.05),
(-math.inf, 0.05, math.inf),
)
def edf_reference_band(dd: float) -> tuple[float, float]:
"""Look up the indicative EDF range for a distance to default.
This is the skill's published rule of thumb, not a fitted mapping. A real
KMV EDF comes from a proprietary default database; treat the output as a
sanity band and never as a calibrated probability.
Args:
dd: Distance to default.
Returns:
Tuple ``(edf_low, edf_high)`` as decimals; the upper end is
``math.inf`` for the worst band.
Raises:
ValueError: If ``dd`` is not a finite number.
"""
if not math.isfinite(dd):
raise ValueError(f"dd must be finite, got {dd}")
for floor, low, high in EDF_REFERENCE_BANDS:
if dd > floor:
return low, high
return EDF_REFERENCE_BANDS[-1][1], EDF_REFERENCE_BANDS[-1][2]
#: Multipliers turning a yield difference into basis points, by input unit.
SPREAD_INPUT_UNITS: Mapping[str, float] = {
"decimal": 10_000.0,
"percent": 100.0,
"bp": 1.0,
}
def _bp_multiplier(input_unit: str) -> float:
"""Resolve a yield input unit to its basis-point multiplier.
Args:
input_unit: A key of :data:`SPREAD_INPUT_UNITS`.
Returns:
The multiplier that converts the input unit to basis points.
Raises:
ValueError: If the unit is not recognised.
"""
try:
return SPREAD_INPUT_UNITS[input_unit]
except KeyError:
raise ValueError(
f"unknown input_unit {input_unit!r}; expected one of "
f"{tuple(SPREAD_INPUT_UNITS)}"
) from None
def credit_spread_analysis(
bond_yields: pd.Series,
risk_free_yields: pd.Series,
window: int = 252,
lookback_periods: int = 21,
signal_z: float = 1.5,
input_unit: str = "percent",
) -> pd.DataFrame:
"""Time-series view of an issuer's spread: level, z-score and percentile.
.. warning::
``historical_percentile`` is a **whole-sample** rank, carried over from
the markdown template this replaced. Every row is ranked against the
rows that come *after* it as well, so the column is look-ahead biased
and must never be fed to a backtest as a signal -- the same date will
report a different percentile once more data arrives. It is a
descriptive summary of the sample you are holding. ``z_score`` and
``signal`` are rolling and therefore causal; use those instead.
Args:
bond_yields: Credit yields indexed by date.
risk_free_yields: Matching risk-free yields on the *same* index. An
index mismatch raises rather than silently producing NaN, which is
what plain pandas subtraction would have done.
window: Rolling window, in observations, for the mean and standard
deviation. 252 is one trading year.
lookback_periods: Horizon for the slower change column; 21 is one
trading month.
signal_z: Absolute z-score at which the row is flagged rich or cheap.
input_unit: Unit of the two yield series -- a key of
:data:`SPREAD_INPUT_UNITS`. Defaults to ``"percent"``, matching the
markdown template's implicit assumption.
Returns:
A DataFrame on the input index with columns ``spread_bp``,
``rolling_mean_bp``, ``rolling_std_bp``, ``z_score``,
``historical_percentile``, ``change_1p_bp``, ``change_lookback_bp`` and
``signal``. ``signal`` is one of ``"rich"``, ``"neutral"``, ``"cheap"``.
Every column except ``historical_percentile`` is causal; see the warning
above.
Raises:
ValueError: If the two series do not share an index, if ``window`` or
``lookback_periods`` is not positive, or if ``input_unit`` is
unknown.
"""
window = _require_finite(window, "window")
lookback_periods = _require_finite(lookback_periods, "lookback_periods")
signal_z = _require_finite(signal_z, "signal_z")
if window <= 0 or lookback_periods <= 0:
raise ValueError("window and lookback_periods must be positive")
if len(bond_yields) != len(risk_free_yields) or not bond_yields.index.equals(
risk_free_yields.index
):
raise ValueError("bond_yields and risk_free_yields must share one index")
spread_bp = (bond_yields - risk_free_yields) * _bp_multiplier(input_unit)
rolling_mean = spread_bp.rolling(window).mean()
rolling_std = spread_bp.rolling(window).std()
z_score = (spread_bp - rolling_mean) / rolling_std
result = pd.DataFrame(
{
"spread_bp": spread_bp,
"rolling_mean_bp": rolling_mean,
"rolling_std_bp": rolling_std,
"z_score": z_score,
"historical_percentile": spread_bp.rank(pct=True),
"change_1p_bp": spread_bp.diff(),
"change_lookback_bp": spread_bp.diff(lookback_periods),
}
)
result["signal"] = "neutral"
result.loc[z_score < -signal_z, "signal"] = "rich"
result.loc[z_score > signal_z, "signal"] = "cheap"
return result
def spread_term_structure(
issuers: Mapping[str, Mapping[float, float]],
risk_free_curve: Mapping[float, float] | pd.Series,
input_unit: str = "decimal",
decimals: int | None = 1,
) -> pd.DataFrame:
"""Cross-sectional spread grid: one row per issuer, one column per tenor.
Args:
issuers: ``{issuer: {tenor_years: yield}}``.
risk_free_curve: ``{tenor_years: yield}`` on the same unit basis. Tenors
missing from the curve produce NaN rather than an error, so a
partially quoted issuer still yields a row.
input_unit: Unit of every yield passed in -- a key of
:data:`SPREAD_INPUT_UNITS`. Defaults to ``"decimal"``, matching the
markdown template's implicit assumption. Note this differs from
:func:`credit_spread_analysis`, whose template assumed percent.
decimals: Rounding applied to the basis-point output; ``None`` keeps
full precision.
Returns:
A DataFrame indexed by issuer with one ``"{tenor}Y_spread_bp"`` column
per tenor seen.
Raises:
ValueError: If ``issuers`` is empty or ``input_unit`` is unknown.
"""
if not issuers:
raise ValueError("issuers must contain at least one entry")
multiplier = _bp_multiplier(input_unit)
curve = dict(risk_free_curve)
records = []
for issuer, tenor_curve in issuers.items():
row: dict[str, float] = {}
for tenor, yld in tenor_curve.items():
reference = curve.get(tenor, np.nan)
spread = (yld - reference) * multiplier
row[f"{_format_tenor(tenor)}Y_spread_bp"] = (
spread if decimals is None else round(spread, decimals)
)
records.append(pd.Series(row, name=issuer))
return pd.DataFrame(records)
def _format_tenor(tenor: float) -> str:
"""Canonical column-name spelling for a tenor, so ``5`` and ``5.0`` from
different issuers land in the same column instead of silently splitting
the grid into duplicate NaN-filled columns."""
value = float(tenor)
return str(int(value)) if value.is_integer() else str(value)
def hazard_rate_to_survival_probability(hazard_rate: float, tenor_years: float) -> float:
"""Convert a constant hazard rate lambda to cumulative survival probability Q(T) = exp(-lambda * T).
Args:
hazard_rate: Annualised default intensity / hazard rate lambda >= 0.
tenor_years: Time horizon in years >= 0.
Returns:
Survival probability in [0.0, 1.0].
Raises:
ValueError: If hazard_rate or tenor_years is negative.
"""
hazard_rate = _require_finite(hazard_rate, "hazard_rate")
tenor_years = _require_finite(tenor_years, "tenor_years")
if hazard_rate < 0.0 or tenor_years < 0.0:
raise ValueError(f"hazard_rate and tenor_years must be non-negative, got {hazard_rate}, {tenor_years}")
return float(np.exp(-hazard_rate * tenor_years))
def survival_probability_to_hazard_rate(survival_prob: float, tenor_years: float) -> float:
"""Convert a survival probability Q(T) to implied constant hazard rate lambda = -ln(Q(T)) / T.
Args:
survival_prob: Survival probability in (0.0, 1.0].
tenor_years: Time horizon in years > 0.
Returns:
Annualised hazard rate lambda.
Raises:
ValueError: If survival_prob is not in (0.0, 1.0] or tenor_years <= 0.
"""
survival_prob = _require_finite(survival_prob, "survival_prob")
tenor_years = _require_finite(tenor_years, "tenor_years")
if survival_prob <= 0.0 or survival_prob > 1.0:
raise ValueError(f"survival_prob must be in (0.0, 1.0], got {survival_prob}")
if tenor_years <= 0.0:
raise ValueError(f"tenor_years must be strictly positive, got {tenor_years}")
return float(-np.log(survival_prob) / tenor_years)
def cds_price(
spread_bps: float,
recovery_rate: float = 0.40,
tenor_years: float = 5.0,
risk_free_rate: float = 0.03,
coupon_bps: float = 100.0,
notional: float = 10_000_000.0,
payment_frequency: int = 4,
) -> dict:
"""Flat-hazard single-name Credit Default Swap (CDS) valuation engine.
Computes the implied hazard rate, survival probability curve, Risky Present Value
of a Basis Point (RPV01), protection leg PV, premium leg PV, fair par spread,
and mark-to-market (MTM) upfront cash payment.
The hazard rate comes from the credit triangle (``lambda = s / (1 - R)``) rather
than being bootstrapped by root-finding the way the ISDA Standard Model does, so
``par_spread_bps`` -- recomputed from the discretised legs -- lands near, not
exactly on, the quoted ``spread_bps`` (~0.4% apart for a 5y investment-grade
name). Value the contract against ``par_spread_bps``; read ``hazard_rate`` as the
triangle approximation it is.
Args:
spread_bps: Market quoted par CDS spread in basis points (e.g. 150.0 for 150 bps).
recovery_rate: Expected recovery rate on default in [0.0, 1.0) (standard senior unsecured = 0.40).
tenor_years: Contract maturity in years > 0 (standard benchmark = 5.0 years).
risk_free_rate: Continuously compounded annual risk-free discount rate.
coupon_bps: Fixed running coupon in basis points (standard 100 bps IG, 500 bps HY).
notional: Contract notional amount in currency units.
payment_frequency: Premium coupon payment frequency per year (standard quarterly = 4).
Returns:
dict with keys:
* ``hazard_rate`` (float): Implied constant hazard rate (default intensity).
* ``survival_probability`` (float): Probability of survival to maturity Q(T).
* ``default_probability`` (float): Cumulative probability of default 1 - Q(T).
* ``rpv01`` (float): Risky annuity (present value of unit running spread per dollar notional).
* ``protection_leg_pv`` (float): Present value of default protection per dollar notional.
* ``premium_leg_pv`` (float): Present value of fixed running premium per dollar notional.
* ``par_spread_bps`` (float): Model par spread in basis points.
* ``upfront_pct`` (float): Upfront payment as decimal fraction of notional.
* ``upfront_amount`` (float): Net upfront cash payment (positive = buyer pays seller).
* ``buyer_mtm`` (float): Mark-to-market value for the protection buyer.
Raises:
ValueError: If spread_bps < 0, recovery_rate not in [0, 1), tenor_years <= 0, or notional <= 0.
"""
spread_bps = _require_finite(spread_bps, "spread_bps")
recovery_rate = _require_finite(recovery_rate, "recovery_rate")
tenor_years = _require_finite(tenor_years, "tenor_years")
risk_free_rate = _require_finite(risk_free_rate, "risk_free_rate")
coupon_bps = _require_finite(coupon_bps, "coupon_bps")
notional = _require_finite(notional, "notional")
payment_frequency = _require_finite(payment_frequency, "payment_frequency")
if spread_bps < 0.0:
raise ValueError(f"spread_bps must be non-negative, got {spread_bps}")
if not (0.0 <= recovery_rate < 1.0):
raise ValueError(f"recovery_rate must be in [0.0, 1.0), got {recovery_rate}")
if tenor_years <= 0.0:
raise ValueError(f"tenor_years must be strictly positive, got {tenor_years}")
if notional <= 0.0:
raise ValueError(f"notional must be strictly positive, got {notional}")
if payment_frequency <= 0:
raise ValueError(f"payment_frequency must be positive, got {payment_frequency}")
s_dec = spread_bps / 10_000.0
c_dec = coupon_bps / 10_000.0
lgd = 1.0 - recovery_rate
# Implied hazard rate lambda ≈ s / LGD
lambda_hazard = float(s_dec / lgd) if lgd > 0 else 0.0
n_periods = max(1, int(np.ceil(tenor_years * payment_frequency)))
# Keep regular premium dates fixed at the requested frequency; only the
# last period is a stub when maturity falls between coupon dates.
t_grid = np.r_[
np.arange(1, n_periods, dtype=float) / payment_frequency, tenor_years
]
t_prev = np.r_[0.0, t_grid[:-1]]
dts = t_grid - t_prev
t_mid = 0.5 * (t_prev + t_grid)
# Survival probabilities Q(t) = exp(-lambda * t)
q_grid = np.exp(-lambda_hazard * t_grid)
q_prev = np.r_[1.0, q_grid[:-1]]
# Discount factors D(t) = exp(-r * t)
df_grid = np.exp(-risk_free_rate * t_grid)
df_mid = np.exp(-risk_free_rate * t_mid)
# Premium leg / RPV01: sum(dt_i * D(t_i) * Q(t_i)) + accrual on default
premium_cashflow = np.sum(dts * df_grid * q_grid)
accrual_cashflow = np.sum(0.5 * dts * df_mid * (q_prev - q_grid))
rpv01 = float(premium_cashflow + accrual_cashflow)
# Protection leg: sum( LGD * D(t_mid) * (Q(t_{i-1}) - Q(t_i)) )
default_prob_steps = q_prev - q_grid
prot_leg_pv = float(lgd * np.sum(df_mid * default_prob_steps))
# Par spread in bps
par_spread = float((prot_leg_pv / rpv01) * 10_000.0) if rpv01 > 0 else spread_bps
# Premium leg PV for running coupon c
prem_leg_pv = float(c_dec * rpv01)
# Upfront percentage and amount
upfront_pct = float(prot_leg_pv - prem_leg_pv)
upfront_amt = float(upfront_pct * notional)
survival_T = float(np.exp(-lambda_hazard * tenor_years))
default_prob_T = float(1.0 - survival_T)
return {
"hazard_rate": lambda_hazard,
"survival_probability": survival_T,
"default_probability": default_prob_T,
"rpv01": rpv01,
"protection_leg_pv": prot_leg_pv,
"premium_leg_pv": prem_leg_pv,
"par_spread_bps": par_spread,
"upfront_pct": upfront_pct,
"upfront_amount": upfront_amt,
"buyer_mtm": upfront_amt,
}
def expected_loss(ead: float, pd: float, lgd: float) -> float:
"""Compute regulatory Expected Loss (EL = EAD * PD * LGD).
Args:
ead: Exposure at Default in currency units >= 0.
pd: Probability of Default in [0.0, 1.0].
lgd: Loss Given Default in [0.0, 1.0].
Returns:
Expected loss amount in currency units.
Raises:
ValueError: If ead < 0, pd not in [0, 1], or lgd not in [0, 1].
"""
ead = _require_finite(ead, "ead")
pd = _require_finite(pd, "pd")
lgd = _require_finite(lgd, "lgd")
if ead < 0.0:
raise ValueError(f"ead must be non-negative, got {ead}")
if not (0.0 <= pd <= 1.0):
raise ValueError(f"pd must be in [0.0, 1.0], got {pd}")
if not (0.0 <= lgd <= 1.0):
raise ValueError(f"lgd must be in [0.0, 1.0], got {lgd}")
return float(ead * pd * lgd)
def vasicek_credit_var(
ead: float,
pd: float,
lgd: float,
asset_correlation: float,
confidence: float = 0.999,
) -> dict:
"""Vasicek single-factor asymptotic credit risk portfolio model (Basel II/III capital framework).
Under the Asymptotic Single Risk Factor (ASRF) model, conditional default
probability at confidence level alpha is:
WCDR(alpha) = Phi( (Phi^{-1}(PD) + sqrt(rho) * Phi^{-1}(alpha)) / sqrt(1 - rho) )
where rho is the pairwise asset return correlation.
Args:
ead: Exposure at Default in currency units (positive).
pd: Probability of Default in (0.0, 1.0).
lgd: Loss Given Default fraction in [0.0, 1.0].
asset_correlation: Pairwise systematic asset correlation rho in [0.0, 1.0).
confidence: VaR confidence level in (0.0, 1.0) (Basel standard = 0.999).
Returns:
dict with keys:
* ``expected_loss`` (float): Base expected loss (EL).
* ``wcdr`` (float): Worst-case conditional default rate at confidence.
* ``worst_case_loss`` (float): Total portfolio loss at confidence (WCL).
* ``unexpected_loss`` (float): Economic capital / Credit VaR (WCL - EL).
* ``capital_ratio`` (float): Capital required as decimal fraction of EAD.
Raises:
ValueError: If parameters violate domain constraints.
"""
ead = _require_finite(ead, "ead")
pd = _require_finite(pd, "pd")
lgd = _require_finite(lgd, "lgd")
asset_correlation = _require_finite(asset_correlation, "asset_correlation")
confidence = _require_finite(confidence, "confidence")
if ead <= 0.0:
raise ValueError(f"ead must be strictly positive, got {ead}")
if not (0.0 < pd < 1.0):
raise ValueError(f"pd must be in (0.0, 1.0), got {pd}")
if not (0.0 <= lgd <= 1.0):
raise ValueError(f"lgd must be in [0.0, 1.0], got {lgd}")
if not (0.0 <= asset_correlation < 1.0):
raise ValueError(f"asset_correlation must be in [0.0, 1.0), got {asset_correlation}")
if not (0.0 < confidence < 1.0):
raise ValueError(f"confidence must be in (0.0, 1.0), got {confidence}")
rho = asset_correlation
inv_pd = float(norm.ppf(pd))
inv_conf = float(norm.ppf(confidence))
numerator = inv_pd + np.sqrt(rho) * inv_conf
denominator = np.sqrt(1.0 - rho)
wcdr = float(norm.cdf(numerator / denominator))
el = expected_loss(ead, pd, lgd)
wcl = float(ead * lgd * wcdr)
ul = float(max(0.0, wcl - el))
capital_ratio = float(ul / ead) if ead > 0 else 0.0
return {
"expected_loss": el,
"wcdr": wcdr,
"worst_case_loss": wcl,
"unexpected_loss": ul,
"capital_ratio": capital_ratio,
}
def credit_spread_dv01(
spread_duration: float,
price: float = 100.0,
face: float = 100.0,
par_amount: float = 1_000_000.0,
) -> float:
"""Calculate Credit Spread DV01 (CS01 / Spread DV01) - dollar value of a 1 bp widening in credit spread.
CS01 = Spread Duration * (Price / Face) * 0.0001 * Par Position
Args:
spread_duration: Modified/spread duration in years.
price: Current clean market price of the credit instrument.
face: Quoted par base (standard 100.0).
par_amount: Total par notional held in position.
Returns:
Dollar loss for a 1 bp increase in credit spread (positive float).
Raises:
ValueError: If price, face, or par_amount is not positive, or if
spread_duration is negative.
"""
spread_duration = _require_finite(spread_duration, "spread_duration")
price = _require_finite(price, "price")
face = _require_finite(face, "face")
par_amount = _require_finite(par_amount, "par_amount")
if face <= 0.0 or price <= 0.0 or par_amount <= 0.0 or spread_duration < 0.0:
raise ValueError("price, face, par_amount must be positive and spread_duration non-negative")
return float(spread_duration * (price / face) * 1e-4 * par_amount)