"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Risk measures: VaR/CVaR, drawdown, Monte Carlo simulation and EVT tail fitting.
SIGN CONVENTION -- read this before using anything here
------------------------------------------------------
**A loss is a positive number.** Every risk *magnitude* this module returns is
non-negative and grows as the risk gets worse:
* ``historical_var`` / ``parametric_var`` -- ``0.028`` means "a 2.8% loss".
* ``historical_cvar`` -- ``0.042`` means "a 4.2% average loss in the tail".
* ``max_drawdown_analysis()["max_drawdown"]`` -- ``0.325`` means "a 32.5%
peak-to-trough decline". Note this is the opposite of the ``-0.325`` that a
raw ``(equity / equity.cummax() - 1).min()`` produces; it is flipped here so
that one rule covers the whole module.
* ``analyze_mc_results()["var"|"cvar"]`` -- same, positive losses.
Quantities that are *returns* rather than *losses* keep their natural sign and
are named ``*_return`` so the two can never be confused: ``mean_return``,
``worst_5pct_return`` and ``best_5pct_return`` are all signed returns, so a bad
outcome there is negative.
The invariant ``cvar >= var`` holds by construction for every pair of measures
computed from the same sample at the same confidence level. Note that this is
**not** ``cvar >= var >= 0``: the magnitudes are not clipped, so a sample whose
tail holds no actual loss reports a *negative* loss, i.e. a gain. Do not assert
non-negativity on a VaR; assert the ordering.
Quantile convention
-------------------
``historical_var`` uses a *non-interpolating lower order statistic*: with the
returns sorted ascending, it takes element ``ceil((1 - confidence) * n) - 1``
and negates it. No blending between neighbouring observations, so the result is
always an actually-observed return. ``historical_cvar`` averages every return at
or below that same order statistic (inclusive), which is the standard expected
shortfall and is what guarantees ``cvar >= var``.
"""
from __future__ import annotations
from collections.abc import Sequence
import math
from decimal import Decimal
import numpy as np
import pandas as pd
from scipy.stats import genpareto, norm
__all__ = [
"historical_var",
"parametric_var",
"historical_cvar",
"drawdown_series",
"max_drawdown_analysis",
"drawdown_distribution_analysis",
"ulcer_index",
"pain_index",
"monte_carlo_gbm",
"analyze_mc_results",
"fit_gpd_tail",
]
TRADING_DAYS_PER_YEAR = 252
"""Day count used to annualise drift/volatility and to size a simulation step."""
GPD_SHAPE_SIGNIFICANCE_SIGMAS = 2.0
"""Standard errors a GPD shape must clear before ``fit_gpd_tail`` calls the tail
fat or bounded rather than exponential.
Measured over 200 refits per case: at 2.0 a truly exponential tail is labelled
``"exponential"`` 96.5% of the time, while ``xi = +0.40`` and ``xi = -0.35``
(n=3000) are still labelled correctly 100% of the time and ``xi = +0.10``
(n=2000) 98.5%. At 1.0 the exponential case drops to 70.5%, which is why the
band is not a single standard error.
"""
def _clean_returns(returns: pd.Series | np.ndarray | Sequence[float]) -> np.ndarray:
"""Coerce a return series to a finite 1-D float array.
Args:
returns: Return observations as a pandas Series, numpy array or any
sequence of floats. NaN and infinite values are dropped.
Returns:
A 1-D float64 array of the finite observations, in input order.
Raises:
ValueError: If the input is not 1-D or holds no finite observation.
"""
values = np.asarray(returns, dtype=float)
if values.ndim > 1:
raise ValueError(f"returns must be 1-D, got shape {values.shape}")
values = values.ravel()
finite = values[np.isfinite(values)]
if finite.size == 0:
raise ValueError("returns contains no finite observation")
return finite
def _validate_confidence(confidence: float) -> None:
"""Check that a confidence level is a strict probability.
Args:
confidence: Confidence level, e.g. 0.95.
Raises:
ValueError: If ``confidence`` is not strictly between 0 and 1.
"""
if not 0.0 < confidence < 1.0:
raise ValueError(f"confidence must be in (0, 1), got {confidence}")
def _validate_horizon(horizon: int) -> None:
"""Check that a holding period is a positive whole number of periods.
Args:
horizon: Holding period in periods (days for a daily return series).
Raises:
ValueError: If ``horizon`` is less than 1.
"""
if horizon < 1:
raise ValueError(f"horizon must be >= 1, got {horizon}")
def _tail_index(n: int, confidence: float) -> int:
"""Position of the VaR order statistic in an ascending-sorted sample.
Args:
n: Number of observations, at least 1.
confidence: Confidence level in (0, 1).
Returns:
The index ``ceil((1 - confidence) * n) - 1`` clamped into ``[0, n - 1]``.
Interpret the confidence's decimal spelling before subtracting. Binary
cancellation can otherwise move an exact rank above its integer (for
example ``(1 - 0.95) * 100 > 5``) and select an extra observation. No
rounding tolerance is applied, so nearby distinct probabilities keep
their own ranks.
"""
rank = (Decimal(1) - Decimal(str(confidence))) * n
return int(min(max(math.ceil(rank) - 1, 0), n - 1))
def historical_var(
returns: pd.Series | np.ndarray | Sequence[float],
confidence: float = 0.95,
horizon: int = 1,
) -> float:
"""Value at Risk from the empirical distribution of past returns.
Makes no distributional assumption: it simply reads the loss off the sorted
sample at the ``1 - confidence`` order statistic (see the module docstring
for the exact, non-interpolating convention).
Args:
returns: Periodic (usually daily) return series.
confidence: Confidence level, commonly 0.95 or 0.99.
horizon: Holding period in periods, scaled by the square-root-of-time
rule. That rule assumes i.i.d. returns and understates risk when
returns are autocorrelated.
Returns:
The VaR as a positive loss magnitude, e.g. 0.028 for a 2.8% loss. A
sample with no losses in the tail yields a negative-signed "loss", i.e.
a gain, which is reported as-is rather than clipped.
Raises:
ValueError: If ``returns`` has no finite observation, ``confidence`` is
outside (0, 1), or ``horizon`` is below 1.
"""
_validate_confidence(confidence)
_validate_horizon(horizon)
values = np.sort(_clean_returns(returns))
quantile_return = values[_tail_index(values.size, confidence)]
return float(-quantile_return * np.sqrt(horizon))
def parametric_var(
returns: pd.Series | np.ndarray | Sequence[float],
confidence: float = 0.95,
horizon: int = 1,
) -> float:
"""Value at Risk under a fitted normal distribution.
Cheap and smooth, but it sees only a mean and a variance, so it misses fat
tails. The direction of that error depends on the confidence level and is
not uniform: a fat tail inflates the fitted sigma, which pushes the normal
quantile *outward* at moderate confidence, where the empirical quantile is
still in the well-behaved body. Measured over 300 t(4) samples of 750 daily
returns, this function reads *above* ``historical_var`` in 100% of samples
at 90% confidence and 92.7% at 95%, and only *below* it -- the classic
understatement -- in 94.7% of samples at 99%. Compare the two at 99% or
deeper if the point is to expose the tail.
Args:
returns: Periodic (usually daily) return series. The mean and the
sample standard deviation (ddof=1) are estimated from it.
confidence: Confidence level, commonly 0.95 or 0.99.
horizon: Holding period in periods, scaled by square-root-of-time.
Returns:
The VaR as a positive loss magnitude: ``-(mu + z * sigma) * sqrt(horizon)``
where ``z = norm.ppf(1 - confidence)``.
Raises:
ValueError: If ``returns`` holds fewer than two finite observations,
``confidence`` is outside (0, 1), or ``horizon`` is below 1.
"""
_validate_confidence(confidence)
_validate_horizon(horizon)
values = _clean_returns(returns)
if values.size < 2:
raise ValueError("parametric_var needs at least 2 observations for a std estimate")
mu = float(values.mean())
sigma = float(values.std(ddof=1))
z = float(norm.ppf(1.0 - confidence))
return float(-(mu + z * sigma) * np.sqrt(horizon))
def historical_cvar(
returns: pd.Series | np.ndarray | Sequence[float],
confidence: float = 0.95,
horizon: int = 1,
) -> float:
"""Conditional VaR (expected shortfall) from the empirical distribution.
The average loss *given* that the VaR threshold was breached. Unlike VaR it
is subadditive, so it can be decomposed across a portfolio, which is why
Basel III moved to it.
Args:
returns: Periodic (usually daily) return series.
confidence: Confidence level, commonly 0.95 or 0.99.
horizon: Holding period in periods, scaled by square-root-of-time.
Returns:
The CVaR as a positive loss magnitude. Always greater than or equal to
``historical_var`` on the same inputs, because it averages the VaR order
statistic together with everything worse than it.
Raises:
ValueError: If ``returns`` has no finite observation, ``confidence`` is
outside (0, 1), or ``horizon`` is below 1.
"""
_validate_confidence(confidence)
_validate_horizon(horizon)
values = np.sort(_clean_returns(returns))
tail = values[: _tail_index(values.size, confidence) + 1]
return float(-tail.mean() * np.sqrt(horizon))
def drawdown_series(equity: pd.Series | np.ndarray | Sequence[float]) -> pd.Series:
"""Compute continuous percentage drawdown from running peak as a positive loss fraction.
Args:
equity: Net-value / equity series, strictly positive.
Returns:
A pandas Series of drawdown fractions in ``[0.0, 1.0)`` where 0.0 means
at peak and 0.25 means 25% below the running peak.
Raises:
ValueError: If ``equity`` is not 1-D, has no finite observations, or contains values <= 0.
"""
if not isinstance(equity, pd.Series):
array = np.asarray(equity, dtype=float)
if array.ndim > 1:
raise ValueError(f"equity must be 1-D, got shape {array.shape}")
series = pd.Series(array)
else:
series = equity.copy()
series = series.astype(float)
series = series[np.isfinite(series.to_numpy())]
if series.empty:
raise ValueError("equity contains no finite observation")
values = series.to_numpy()
if (values <= 0.0).any():
raise ValueError("equity must be strictly positive to express drawdown as a fraction")
running_peak = np.maximum.accumulate(values)
dd = -(values / running_peak - 1.0) # non-negative loss fraction
return pd.Series(dd, index=series.index, name="drawdown")
def ulcer_index(equity: pd.Series | np.ndarray | Sequence[float]) -> float:
"""Calculate Peter Martin's Ulcer Index measuring downside drawdown volatility.
Ulcer Index is the root-mean-square percentage drawdown:
UI = sqrt( (1/N) * sum( (DD_t)^2 ) )
Args:
equity: Net-value / equity series, strictly positive.
Returns:
Ulcer Index as a positive decimal fraction.
Raises:
ValueError: If ``equity`` is not 1-D, has no finite observations, or contains values <= 0.
"""
dd = drawdown_series(equity).to_numpy()
return float(np.sqrt(np.mean(dd**2)))
def pain_index(equity: pd.Series | np.ndarray | Sequence[float]) -> float:
"""Calculate the Pain Index measuring mean absolute drawdown depth and duration.
Pain Index is the average drawdown over the entire investment history:
PI = (1/N) * sum( DD_t )
Args:
equity: Net-value / equity series, strictly positive.
Returns:
Pain Index as a positive decimal fraction.
Raises:
ValueError: If ``equity`` is not 1-D, has no finite observations, or contains values <= 0.
"""
dd = drawdown_series(equity).to_numpy()
return float(np.mean(dd))
def drawdown_distribution_analysis(
equity: pd.Series | np.ndarray | Sequence[float],
) -> dict:
"""Decompose an equity curve into discrete drawdown episodes and aggregate risk metrics.
Args:
equity: Net-value / equity series, strictly positive.
Returns:
dict with keys:
* ``max_drawdown`` (float): Worst peak-to-trough decline (positive fraction).
* ``max_drawdown_duration`` (int): Longest peak-to-recovery duration (observations).
* ``avg_drawdown_depth`` (float): Mean depth across all drawdown episodes.
* ``avg_drawdown_duration`` (float): Mean duration across all completed episodes.
* ``ulcer_index`` (float): Root-mean-square drawdown.
* ``pain_index`` (float): Mean drawdown over the entire series.
* ``episode_count`` (int): Total number of discrete drawdown episodes.
* ``episodes`` (list[dict]): Details for each episode (peak, trough, recovery, depth, duration, recovered).
Raises:
ValueError: If ``equity`` is not 1-D, has no finite observations, or contains values <= 0.
"""
if not isinstance(equity, pd.Series):
array = np.asarray(equity, dtype=float)
if array.ndim > 1:
raise ValueError(f"equity must be 1-D, got shape {array.shape}")
series = pd.Series(array)
else:
series = equity.copy()
series = series.astype(float)
series = series[np.isfinite(series.to_numpy())]
if series.empty:
raise ValueError("equity contains no finite observation")
values = series.to_numpy()
if (values <= 0.0).any():
raise ValueError("equity must be strictly positive to express drawdown as a fraction")
n = len(values)
running_peak = np.maximum.accumulate(values)
dd = -(values / running_peak - 1.0)
ui = float(np.sqrt(np.mean(dd**2)))
pi = float(np.mean(dd))
episodes: list[dict] = []
in_drawdown = False
curr_peak_idx = 0
curr_trough_idx = 0
curr_max_depth = 0.0
index = series.index
for i in range(n):
if values[i] >= values[curr_peak_idx]:
if in_drawdown:
# Recovery reached
duration = i - curr_peak_idx
episodes.append(
{
"peak_index": index[curr_peak_idx],
"trough_index": index[curr_trough_idx],
"recovery_index": index[i],
"max_depth": float(curr_max_depth),
"duration": duration,
"recovered": True,
}
)
in_drawdown = False
curr_peak_idx = i
curr_trough_idx = i
curr_max_depth = 0.0
else:
in_drawdown = True
depth = dd[i]
if depth > curr_max_depth:
curr_max_depth = depth
curr_trough_idx = i
if in_drawdown:
# Ongoing unrecovered drawdown at the end of the series
duration = (n - 1) - curr_peak_idx
episodes.append(
{
"peak_index": index[curr_peak_idx],
"trough_index": index[curr_trough_idx],
"recovery_index": None,
"max_depth": float(curr_max_depth),
"duration": duration,
"recovered": False,
}
)
if episodes:
max_dd = float(max(e["max_depth"] for e in episodes))
max_dur = int(max(e["duration"] for e in episodes))
avg_depth = float(np.mean([e["max_depth"] for e in episodes]))
completed_durations = [e["duration"] for e in episodes if e["recovered"]]
avg_dur = float(np.mean(completed_durations)) if completed_durations else 0.0
else:
max_dd = 0.0
max_dur = 0
avg_depth = 0.0
avg_dur = 0.0
return {
"max_drawdown": max_dd,
"max_drawdown_duration": max_dur,
"avg_drawdown_depth": avg_depth,
"avg_drawdown_duration": avg_dur,
"ulcer_index": ui,
"pain_index": pi,
"episode_count": len(episodes),
"episodes": episodes,
}
def max_drawdown_analysis(equity: pd.Series | np.ndarray | Sequence[float]) -> dict:
"""Locate the worst peak-to-trough decline of an equity curve and its recovery.
Args:
equity: Net-value / equity series, strictly positive. A pandas Series
keeps its index, so ``peak_date`` and friends come back as index
labels; anything else is wrapped in a RangeIndex and the ``*_days``
calendar fields are then None.
Returns:
dict with keys:
max_drawdown (float): Worst decline as a **positive** fraction, so
0.25 means the curve fell 25% below its running peak. 0.0 when
the curve never declines.
peak_date: Index label of the most recent running peak preceding
the trough; revisiting that peak resets the underwater period.
trough_date: Index label of the deepest point.
recovery_date: Index label of the first observation at or above the
peak value, searched from the trough onward; None if the series
ends still underwater.
recovered (bool): Whether ``recovery_date`` was found.
peak_to_trough_periods (int): Observations from peak to trough.
trough_to_recovery_periods (int | None): Observations from trough to
recovery, None if never recovered.
underwater_days (int | None): Calendar days peak to trough; None
unless the index is a DatetimeIndex.
recovery_days (int | None): Calendar days trough to recovery; None
unless the index is a DatetimeIndex and recovery happened.
Raises:
ValueError: If ``equity`` is not one-dimensional, has no finite
observation, or any value is not strictly positive (a drawdown ratio
is undefined at or below zero).
"""
if not isinstance(equity, pd.Series):
array = np.asarray(equity, dtype=float)
if array.ndim > 1:
# Flattening an (n, k) matrix concatenates unrelated curves into one
# nonsense path and reports a drawdown for it. _clean_returns
# already refuses this shape; refuse it here too.
raise ValueError(f"equity must be 1-D, got shape {array.shape}")
equity = pd.Series(array)
series = equity
series = series.astype(float)
series = series[np.isfinite(series.to_numpy())]
if series.empty:
raise ValueError("equity contains no finite observation")
values = series.to_numpy()
if (values <= 0.0).any():
raise ValueError("equity must be strictly positive to express drawdown as a fraction")
running_peak = np.maximum.accumulate(values)
drawdown = values / running_peak - 1.0 # <= 0 everywhere
trough_pos = int(np.argmin(drawdown))
# A revisit closes the previous drawdown: start at the latest peak.
peak_pos = int(np.flatnonzero(values[: trough_pos + 1] == running_peak[trough_pos])[-1])
# A flat/rising curve has drawdown 0 at the trough, so the trough itself
# already satisfies "back at the peak" and recovery is instantaneous.
at_or_above_peak = np.flatnonzero(values[trough_pos:] >= values[peak_pos])
recovery_pos = int(trough_pos + at_or_above_peak[0]) if at_or_above_peak.size else None
index = series.index
is_dated = isinstance(index, pd.DatetimeIndex)
return {
"max_drawdown": float(-drawdown[trough_pos]),
"peak_date": index[peak_pos],
"trough_date": index[trough_pos],
"recovery_date": index[recovery_pos] if recovery_pos is not None else None,
"recovered": recovery_pos is not None,
"peak_to_trough_periods": trough_pos - peak_pos,
"trough_to_recovery_periods": None if recovery_pos is None else recovery_pos - trough_pos,
"underwater_days": _civil_days(index[trough_pos], index[peak_pos]) if is_dated else None,
"recovery_days": (
_civil_days(index[recovery_pos], index[trough_pos])
if is_dated and recovery_pos is not None
else None
),
}
def _civil_days(later, earlier) -> int:
"""Whole calendar days from ``earlier`` to ``later``.
``Timedelta.days`` counts 24-hour blocks. Across a spring-forward, midnight
to the next midnight is 23 hours and that count is 0, so a drawdown that
lasted the whole civil day was reported as underwater for none.
"""
return (pd.Timestamp(later).date() - pd.Timestamp(earlier).date()).days
def monte_carlo_gbm(
s0: float,
mu: float,
sigma: float,
n_steps: int = TRADING_DAYS_PER_YEAR,
n_paths: int = 10_000,
*,
seed: int | None = None,
steps_per_year: int = TRADING_DAYS_PER_YEAR,
) -> np.ndarray:
"""Simulate price paths under geometric Brownian motion.
Each step applies ``(mu - 0.5 * sigma**2) * dt + sigma * sqrt(dt) * Z`` in
log space, so the terminal expectation is ``s0 * exp(mu * n_steps / steps_per_year)``.
Args:
s0: Initial price, strictly positive.
mu: Annualised drift of the arithmetic return.
sigma: Annualised volatility, non-negative. Zero gives a deterministic
path, which is useful as a test fixture.
n_steps: Number of simulated steps, at least 1.
n_paths: Number of paths, at least 1. Use 10,000 or more before reading
anything off the tail.
seed: Seed for ``numpy.random.default_rng``. Keyword-only. Pass an int
for a reproducible run; None draws fresh OS entropy and the result
is then NOT reproducible.
steps_per_year: Steps per year, i.e. ``dt = 1 / steps_per_year``.
Defaults to the 252-day trading year.
Returns:
Price matrix of shape ``(n_paths, n_steps + 1)``. Column 0 is exactly
``s0`` on every path, so ``paths[:, -1] / paths[:, 0] - 1`` is the total
return over the whole simulation.
Raises:
ValueError: If ``s0`` is not positive, ``sigma`` is negative, or any of
``n_steps`` / ``n_paths`` / ``steps_per_year`` is below 1.
"""
if s0 <= 0.0:
raise ValueError(f"s0 must be > 0, got {s0}")
if sigma < 0.0:
raise ValueError(f"sigma must be >= 0, got {sigma}")
if n_steps < 1 or n_paths < 1:
raise ValueError(f"n_steps and n_paths must be >= 1, got {n_steps} and {n_paths}")
if steps_per_year < 1:
raise ValueError(f"steps_per_year must be >= 1, got {steps_per_year}")
dt = 1.0 / steps_per_year
rng = np.random.default_rng(seed)
shocks = rng.standard_normal((n_paths, n_steps))
log_returns = (mu - 0.5 * sigma**2) * dt + sigma * np.sqrt(dt) * shocks
paths = np.empty((n_paths, n_steps + 1), dtype=float)
paths[:, 0] = s0
paths[:, 1:] = s0 * np.exp(np.cumsum(log_returns, axis=1))
return paths
def analyze_mc_results(paths: np.ndarray, confidence: float = 0.95) -> dict:
"""Summarise the terminal distribution of a simulated price matrix.
Args:
paths: Price matrix of shape ``(n_paths, n_steps + 1)`` as returned by
``monte_carlo_gbm``; column 0 is the starting price.
confidence: Confidence level for the VaR/CVaR of the terminal return.
Returns:
dict with keys:
mean_return, median_return, std_return (float): Signed total
returns over the simulation, so a bad outcome is negative.
var, cvar (float): Positive loss magnitudes, computed with the same
order-statistic convention as ``historical_var`` /
``historical_cvar``, so ``cvar >= var``.
prob_loss (float): Fraction of paths ending below their start.
worst_5pct_return, best_5pct_return (float): Signed 5th and 95th
percentiles of the terminal return (linear interpolation).
Raises:
ValueError: If ``paths`` is not 2-D with at least two columns, holds a
non-positive starting price, or ``confidence`` is outside (0, 1).
"""
_validate_confidence(confidence)
matrix = np.asarray(paths, dtype=float)
if matrix.ndim != 2 or matrix.shape[1] < 2:
raise ValueError(f"paths must be 2-D with >= 2 columns, got shape {matrix.shape}")
start = matrix[:, 0]
if (start <= 0.0).any():
raise ValueError("paths column 0 (the starting price) must be strictly positive")
returns = matrix[:, -1] / start - 1.0
return {
"mean_return": float(np.mean(returns)),
"median_return": float(np.median(returns)),
"std_return": float(np.std(returns, ddof=1)) if returns.size > 1 else 0.0,
"var": historical_var(returns, confidence),
"cvar": historical_cvar(returns, confidence),
"prob_loss": float(np.mean(returns < 0.0)),
"worst_5pct_return": float(np.percentile(returns, 5.0)),
"best_5pct_return": float(np.percentile(returns, 95.0)),
}
def fit_gpd_tail(
returns: pd.Series | np.ndarray | Sequence[float],
threshold_pct: float = 5.0,
) -> dict:
"""Fit the loss tail with a generalised Pareto distribution (POT method).
Extreme value theory says the exceedances over a high enough threshold
converge to a GPD regardless of the parent distribution, which is what makes
this usable where a normal fit is not. The location is pinned at zero
because exceedances are non-negative by construction.
``tail_type`` is decided against ``shape_stderr``, not against exact zero. A
maximum-likelihood shape is a float and is therefore never exactly ``0.0``,
so a hard ``shape > 0`` test would label a genuinely exponential tail "fat"
or "bounded" on the sign of estimation noise alone and would make the
``"exponential"`` label unreachable in practice.
Args:
returns: Periodic (usually daily) return series.
threshold_pct: Percentile defining the left tail, e.g. 5.0 keeps the
worst 5% of returns. Must be in (0, 100).
Returns:
dict with keys:
threshold (float): The signed return at ``threshold_pct``; losses
worse than this are the exceedances.
n_exceedances (int): Number of observations in the tail.
exceedance_rate (float): ``n_exceedances / n_observations``.
shape_xi (float): GPD shape. ``> 0`` fat tail, ``== 0`` exponential
tail, ``< 0`` bounded tail.
shape_stderr (float): Asymptotic standard error of ``shape_xi``,
``|1 + xi| / sqrt(n_exceedances)``. Only valid for ``xi > -0.5``;
below that the GPD likelihood is non-regular and the figure is
indicative at best.
scale_sigma (float): GPD scale, in units of loss magnitude.
tail_type (str): ``"fat"`` when ``shape_xi`` clears
``GPD_SHAPE_SIGNIFICANCE_SIGMAS * shape_stderr``, ``"bounded"``
when it clears it on the negative side, otherwise
``"exponential"`` -- i.e. a shape indistinguishable from zero at
this sample size is reported as exponential rather than being
rounded into one of the two extremes.
Raises:
ValueError: If ``threshold_pct`` is outside (0, 100), ``returns`` has no
finite observation, or the threshold leaves fewer than 2 exceedances
to fit.
"""
if not 0.0 < threshold_pct < 100.0:
raise ValueError(f"threshold_pct must be in (0, 100), got {threshold_pct}")
values = _clean_returns(returns)
threshold = float(np.percentile(values, threshold_pct))
# Exceedances are loss magnitudes, hence non-negative: a positive number is
# "how far below the threshold this return fell".
exceedances = threshold - values[values < threshold]
if exceedances.size < 2:
raise ValueError(
f"need at least 2 exceedances to fit a GPD, got {exceedances.size} "
f"at threshold_pct={threshold_pct}"
)
shape, _loc, scale = genpareto.fit(exceedances, floc=0.0)
# Asymptotic MLE standard error of the GPD shape. Empirically checked
# against the spread of 12 refits per shape at n=2000: predicted
# 0.0291/0.0246/0.0224/0.0179 vs observed 0.0313/0.0244/0.0212/0.0162 for
# true xi of +0.30/+0.10/0.00/-0.20.
shape_stderr = float(abs(1.0 + shape) / np.sqrt(exceedances.size))
band = GPD_SHAPE_SIGNIFICANCE_SIGMAS * shape_stderr
if shape > band:
tail_type = "fat"
elif shape < -band:
tail_type = "bounded"
else:
tail_type = "exponential"
return {
"threshold": threshold,
"n_exceedances": int(exceedances.size),
"exceedance_rate": float(exceedances.size / values.size),
"shape_xi": float(shape),
"shape_stderr": shape_stderr,
"scale_sigma": float(scale),
"tail_type": tail_type,
}