Source code for economic.BasicG2PP.Validation

# modelx: pseudo-python
# This file is part of a modelx model.
# It can be imported as a Python module, but functions defined herein
# are model formulas and may not be executable as standard Python.

"""Checks of the G2PP space against closed forms and martingale properties.

Every test returns a DataFrame with the columns

* ``mc``: the Monte Carlo estimate over the stochastic scenarios 1 to N,
* ``theory``: the value it should converge to,
* ``se``: its standard error, from antithetic pair means when antithetic variates are on,
* ``z``: :math:`(\\mathrm{mc} - \\mathrm{theory}) / \\mathrm{se}`.

With correct formulas, each z is roughly standard normal, so :math:`|z| > 3` is rare for a
single check. Tests that cover many months or moments contain many z-scores, so a larger
maximum is expected by chance: :func:`summary` compares the largest :math:`|z|` of each
test with a limit that allows for the number of z-scores. Where the estimate is exact by
construction, z is 0 (see ``mcstats.check``).

The tests read the scenarios through the Reference :attr:`g2pp`, so they run on whatever
input the G2PP space uses. Statistical power grows with ``scen_size``; 10,000 antithetic
scenarios is a good setting for validation.

Attributes:

    g2pp: The G2PP space.

    mcstats: User module with :func:`check`, which turns samples into the DataFrame
        above. Saved in the model folder as ``mcstats.py``.

    np: The numpy module.

    pd: The pandas module.

    stats: The scipy.stats module, for the normal distribution.
"""

from modelx.serialize.jsonvalues import *

_formula = None

_bases = []

_allow_none = None

_spaces = []

# ---------------------------------------------------------------------------
# Cells

[docs] def martingale_test(): r"""Mean deflator against the initial curve, for every month :math:`E[D(t_i)] = P^M(0, t_i)` for i = 0 to n. Returns: pandas.DataFrame indexed by month ``t``, columns ``mc``, ``theory``, ``se``, ``z`` """ paths = g2pp.disc_factor_paths() return mcstats.check(paths[1:], paths[0], g2pp.antithetic(), pd.RangeIndex(paths.shape[1], name="t"))
[docs] def fund_martingale_test(): r"""Deflated value of the selected fund against 1, for every month :math:`E[D(t_i) AV(t_i)/AV_0] = 1` with :math:`AV(t_i)/AV_0 = \prod_{k<i}(1 + R^F_k)`, because the fund trades only bonds and the bank account. For an all-cash fund this holds in every scenario, so z is 0. Returns: pandas.DataFrame indexed by month ``t``, columns ``mc``, ``theory``, ``se``, ``z`` """ returns = g2pp.fund_return_paths() growth = np.cumprod(np.hstack([np.ones((len(returns), 1)), 1 + returns]), axis=1) values = g2pp.disc_factor_paths() * growth return mcstats.check(values[1:], 1.0, g2pp.antithetic(), pd.RangeIndex(values.shape[1], name="t"))
[docs] def curve_fit_test(): r"""Spot rates implied by the mean deflators against the input curve At each maturity of the selected curve that is a whole number of months no later than :math:`t_n`, the spot rate implied by the mean of :math:`D(t)` (compounded as the input) against the input spot rate. The standard error comes from that of :func:`martingale_test` by the delta method. Returns: pandas.DataFrame indexed by ``maturity`` in years, columns ``mc``, ``theory``, ``se``, ``z`` """ col = g2pp.curve_table()[g2pp.curve_id()].dropna() years = col.index.to_numpy(dtype=float) months = np.round(years * 12).astype(int) keep = (np.abs(years * 12 - months) < 1e-9) & (months <= g2pp.step_size()) years, months, spot = years[keep], months[keep], col.to_numpy(dtype=float)[keep] mart = martingale_test() mean, se_mean = mart["mc"].to_numpy()[months], mart["se"].to_numpy()[months] if g2pp.compounding() == "annual": implied = mean ** (-1 / years) - 1 slope = mean ** (-1 / years - 1) / years else: implied = -np.log(mean) / years slope = 1 / (mean * years) se = slope * se_mean return pd.DataFrame({"mc": implied, "theory": spot, "se": se, "z": (implied - spot) / se}, index=pd.Index(years, name="maturity"))
[docs] def zcb_martingale_test(i, j): r"""Deflated bond prices: :math:`E[D(t_i) P(t_i, t_j)] = P^M(0, t_j)` Returns: pandas.DataFrame with one row indexed by (``i``, ``j``) """ values = g2pp.disc_factor(i) * g2pp.P_t_T(i, j) return mcstats.check(values, g2pp.mkt_zcb(j), g2pp.antithetic(), pd.MultiIndex.from_tuples([(i, j)], names=["i", "j"]))
[docs] def moments_test(): r"""Means, variances and covariance of :math:`x`, :math:`y` and :math:`r`, every year At each whole year up to :math:`t_n` (or at :math:`t_n` if the run is shorter than a year), against .. math:: E[x] = E[y] = 0, \quad E[r] = \varphi(t), \quad \mathrm{Var}[x] = \frac{\sigma^2}{2a}(1 - e^{-2at}), \quad \mathrm{Var}[y] = \frac{\eta^2}{2b}(1 - e^{-2bt}), \quad \mathrm{Cov}[x, y] = \frac{\rho\sigma\eta}{a + b}(1 - e^{-(a+b)t}) and :math:`\mathrm{Var}[r]` from ``Var_rt``. With antithetic variates the three means are exact by construction, so their z is 0. Returns: pandas.DataFrame indexed by (``t``, ``moment``), columns ``mc``, ``theory``, ``se``, ``z`` """ a, b, s, e, r = g2pp.a(), g2pp.b(), g2pp.sigma(), g2pp.eta(), g2pp.rho() n = g2pp.step_size() names = ["mean x", "mean y", "mean r", "var x", "var y", "cov xy", "var r"] frames = [] for i in list(range(12, n + 1, 12)) or [n]: t = g2pp.t_(i) x, y, rate = g2pp.x(i), g2pp.y(i), g2pp.short_rate(i) dx, dy, dr = x - x.mean(), y - y.mean(), rate - rate.mean() samples = np.column_stack([x, y, rate, dx**2, dy**2, dx * dy, dr**2]) theory = [0.0, 0.0, g2pp.phi(i), s**2 / (2 * a) * -np.expm1(-2 * a * t), e**2 / (2 * b) * -np.expm1(-2 * b * t), r * s * e / (a + b) * -np.expm1(-(a + b) * t), g2pp.Var_rt()[i]] index = pd.MultiIndex.from_product([[i], names], names=["t", "moment"]) frames.append(mcstats.check(samples, theory, g2pp.antithetic(), index)) return pd.concat(frames)
[docs] def zbp_cf(i, j, K): r"""Closed-form price of a put on a zero-coupon bond (Brigo and Mercurio, section 4.2) The price at time 0 of a European put with expiry :math:`T = t_i` and strike :math:`K` on the bond maturing at :math:`S = t_j`: .. math:: \mathrm{ZBP} = K P^M(0, T)\Phi(-h + \Sigma) - P^M(0, S)\Phi(-h), \quad h = \frac{1}{\Sigma}\ln\frac{P^M(0, S)}{K P^M(0, T)} + \frac{\Sigma}{2} \Sigma^2 = \frac{\sigma^2}{2a^3}(1 - e^{-a(S-T)})^2(1 - e^{-2aT}) + \frac{\eta^2}{2b^3}(1 - e^{-b(S-T)})^2(1 - e^{-2bT}) + \frac{2\rho\sigma\eta}{ab(a+b)}(1 - e^{-a(S-T)})(1 - e^{-b(S-T)})(1 - e^{-(a+b)T}) """ a, b, s, e, r = g2pp.a(), g2pp.b(), g2pp.sigma(), g2pp.eta(), g2pp.rho() T, S = g2pp.t_(i), g2pp.t_(j) var = (s**2 / (2 * a**3) * np.expm1(-a * (S - T))**2 * -np.expm1(-2 * a * T) + e**2 / (2 * b**3) * np.expm1(-b * (S - T))**2 * -np.expm1(-2 * b * T) + 2 * r * s * e / (a * b * (a + b)) * np.expm1(-a * (S - T)) * np.expm1(-b * (S - T)) * -np.expm1(-(a + b) * T)) vol = np.sqrt(var) p_T, p_S = g2pp.mkt_zcb(i), g2pp.mkt_zcb(j) h = np.log(p_S / (K * p_T)) / vol + vol / 2 return float(K * p_T * stats.norm.cdf(-h + vol) - p_S * stats.norm.cdf(-h))
[docs] def zbp_mc(i, j, K): r"""Monte Carlo price of the bond put of :func:`zbp_cf`, against the closed form The mean of :math:`D(t_i)\max(K - P(t_i, t_j), 0)`. Returns: pandas.DataFrame with one row indexed by (``i``, ``j``, ``K``) """ values = g2pp.disc_factor(i) * np.maximum(K - g2pp.P_t_T(i, j), 0) return mcstats.check(values, zbp_cf(i, j, K), g2pp.antithetic(), pd.MultiIndex.from_tuples([(i, j, K)], names=["i", "j", "K"]))
[docs] def deflator_call_test(i, k): r"""Call on the deflator :math:`D(t_i)` with strike :math:`K = k P^M(0, t_i)` :math:`\ln D(T) \sim N(\ln P^M(0, T) - V/2, V)` with :math:`V = V(0, T)`, so .. math:: E[(D(T) - K)^+] = P^M(0, T)\Phi(d_1) - K\Phi(d_1 - \sqrt{V}), \quad d_1 = \frac{\ln(P^M(0, T)/K) + V/2}{\sqrt{V}} This is also the GMAB of a single-premium policy whose fund is all cash, per unit of sum assured, with :math:`k = AV_0 / (SA\, P^M(0, T))`. Returns: pandas.DataFrame with one row indexed by (``i``, ``k``) """ p = g2pp.mkt_zcb(i) strike = k * p var = g2pp.V_t_T(0, i) d1 = (np.log(p / strike) + var / 2) / np.sqrt(var) theory = p * stats.norm.cdf(d1) - strike * stats.norm.cdf(d1 - np.sqrt(var)) values = np.maximum(g2pp.disc_factor(i) - strike, 0) return mcstats.check(values, theory, g2pp.antithetic(), pd.MultiIndex.from_tuples([(i, k)], names=["i", "k"]))
[docs] def summary(): r"""Largest :math:`|z|` of each test on the current input, against its limit Runs every test, with the bond tests at :math:`t_i`, i = n // 2: the deflated bond and the at-the-money bond put maturing five years later, and the deflator call with k = 0.9. A test with m z-scores passes if its largest :math:`|z|` is below :math:`\Phi^{-1}(1 - 0.00135/m)`. That keeps the chance of a false alarm at that of a single 3-sigma check, 0.27%, if the z-scores were independent; positively correlated ones, such as those of neighbouring months, make it smaller still. The limit is 3 for a single check and about 4.5 for 600 months. Returns: pandas.DataFrame indexed by test, columns ``checks`` (number of z-scores), ``max_abs_z``, ``limit``, ``ok`` and ``at`` (the row of the largest :math:`|z|`) """ i = max(1, g2pp.step_size() // 2) j = i + 60 atm = g2pp.mkt_zcb(j) / g2pp.mkt_zcb(i) tests = { "martingale_test()": martingale_test(), "fund_martingale_test()": fund_martingale_test(), "curve_fit_test()": curve_fit_test(), "moments_test()": moments_test(), f"zcb_martingale_test({i}, {j})": zcb_martingale_test(i, j), f"zbp_mc({i}, {j}, at the money)": zbp_mc(i, j, atm), f"deflator_call_test({i}, 0.9)": deflator_call_test(i, 0.9), } rows = {} for name, df in tests.items(): z = df["z"].abs() m = int(z.notna().sum()) limit = float(stats.norm.isf(0.00135 / m)) rows[name] = {"checks": m, "max_abs_z": z.max(), "limit": limit, "ok": bool(z.max() < limit), "at": z.idxmax()} return pd.DataFrame.from_dict(rows, orient="index")
# --------------------------------------------------------------------------- # References g2pp = ("Interface", ("..", "G2PP"), "auto") np = ("Module", "numpy") pd = ("Module", "pandas") stats = ("Module", "scipy.stats") mcstats = ("IOSpec", 1) # ModuleData path='mcstats.py'