Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(quantlib): add drawdown distribution analytics and Ulcer/Pain indices

santhreal349ecdb1a992
diff --git a/agent/src/quantlib/risk.py b/agent/src/quantlib/risk.py
index 92a391b00..d4001aa7f 100644
--- a/agent/src/quantlib/risk.py
+++ b/agent/src/quantlib/risk.py
@@ -48,7 +48,11 @@ __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",
@@ -247,6 +251,187 @@ def historical_cvar(
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.
+ """
+ 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.
+ """
+ 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 float(max_dur)
+ 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.
diff --git a/agent/tests/quantlib/test_risk.py b/agent/tests/quantlib/test_risk.py
index b3fd55977..bce3cee16 100644
--- a/agent/tests/quantlib/test_risk.py
+++ b/agent/tests/quantlib/test_risk.py
@@ -12,12 +12,16 @@ from scipy.stats import genpareto, norm
from src.quantlib.risk import (
analyze_mc_results,
+ drawdown_distribution_analysis,
+ drawdown_series,
fit_gpd_tail,
historical_cvar,
historical_var,
max_drawdown_analysis,
monte_carlo_gbm,
+ pain_index,
parametric_var,
+ ulcer_index,
)
# 20 observations, already ascending: -0.10, -0.09, ..., 0.09.
@@ -521,3 +525,55 @@ def test_fit_gpd_tail_rejects_a_threshold_with_too_few_exceedances():
def test_fit_gpd_tail_rejects_an_out_of_range_threshold(threshold_pct):
with pytest.raises(ValueError, match="threshold_pct"):
fit_gpd_tail(FIXED_RETURNS, threshold_pct=threshold_pct)
+
+# --------------------------------------------------------------------------
+# drawdown_series, ulcer_index, pain_index, drawdown_distribution_analysis
+# --------------------------------------------------------------------------
+
+
+def test_drawdown_series_exact_fractions():
+ equity = _dated([100.0, 120.0, 90.0, 100.0, 120.0])
+ dd = drawdown_series(equity)
+
+ assert dd.iloc[0] == pytest.approx(0.0)
+ assert dd.iloc[1] == pytest.approx(0.0)
+ assert dd.iloc[2] == pytest.approx(0.25) # (120 - 90)/120 = 30/120 = 0.25
+ assert dd.iloc[3] == pytest.approx(20.0 / 120.0) # (120 - 100)/120 = 1/6
+ assert dd.iloc[4] == pytest.approx(0.0)
+
+
+def test_ulcer_and_pain_index_computations():
+ equity = _dated([100.0, 120.0, 90.0, 120.0])
+ # dd values: [0.0, 0.0, 0.25, 0.0]
+ # PI = (0 + 0 + 0.25 + 0) / 4 = 0.0625
+ # UI = sqrt( (0 + 0 + 0.25^2 + 0) / 4 ) = sqrt( 0.0625 / 4 ) = 0.125
+ ui = ulcer_index(equity)
+ pi = pain_index(equity)
+
+ assert pi == pytest.approx(0.0625)
+ assert ui == pytest.approx(0.125)
+
+
+def test_drawdown_distribution_analysis_multiple_episodes():
+ # Episode 1: Peak at 100 (t=0), Trough at 80 (t=1), Recovery at 110 (t=2) -> max_depth=0.20, dur=2, recovered=True
+ # Episode 2: Peak at 110 (t=2), Trough at 99 (t=3), Recovery at 110 (t=4) -> max_depth=0.10, dur=2, recovered=True
+ # Episode 3: Peak at 120 (t=5), Trough at 108 (t=6), ongoing (t=6) -> max_depth=0.10, dur=1, recovered=False
+ equity = _dated([100.0, 80.0, 110.0, 99.0, 110.0, 120.0, 108.0])
+ result = drawdown_distribution_analysis(equity)
+
+ assert result["episode_count"] == 3
+ assert result["max_drawdown"] == pytest.approx(0.20)
+ assert result["max_drawdown_duration"] == 2
+ assert result["avg_drawdown_depth"] == pytest.approx((0.20 + 0.10 + 0.10) / 3.0)
+ assert result["avg_drawdown_duration"] == pytest.approx(2.0) # completed episodes duration
+ assert result["ulcer_index"] > 0.0
+ assert result["pain_index"] > 0.0
+
+ episodes = result["episodes"]
+ assert len(episodes) == 3
+ assert episodes[0]["recovered"] is True
+ assert episodes[0]["max_depth"] == pytest.approx(0.20)
+ assert episodes[1]["recovered"] is True
+ assert episodes[1]["max_depth"] == pytest.approx(0.10)
+ assert episodes[2]["recovered"] is False
+ assert episodes[2]["max_depth"] == pytest.approx(0.10)