Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(quantlib): preserve exact decimal tail ranks in historical risk (#1950)

Rudy Mizrahi Celeklief767b16c6ff
diff --git a/agent/src/quantlib/risk.py b/agent/src/quantlib/risk.py
index 7b7adba33..cfba0cb4a 100644
--- a/agent/src/quantlib/risk.py
+++ b/agent/src/quantlib/risk.py
@@ -39,6 +39,7 @@ from __future__ import annotations
from collections.abc import Sequence
import math
+from decimal import Decimal
import numpy as np
import pandas as pd
@@ -132,15 +133,14 @@ def _tail_index(n: int, confidence: float) -> int:
Returns:
The index ``ceil((1 - confidence) * n) - 1`` clamped into ``[0, n - 1]``.
- This is the textbook lower quantile. The floor form ``floor((1-c)*n)``
- agrees with it at every confidence level anyone uses -- 0.90, 0.95,
- 0.99 and friends are not exact binary fractions, so ``(1-c)*n`` is never
- exactly an integer and the two expressions coincide. They diverge only
- at levels like 0.5, 0.6 and 0.75, where the floor form picks the next
- observation up and understates the loss. Being right by construction
- rather than by floating-point accident costs nothing here.
+ 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.
"""
- return int(min(max(math.ceil((1.0 - confidence) * n) - 1, 0), n - 1))
+ rank = (Decimal(1) - Decimal(str(confidence))) * n
+ return int(min(max(math.ceil(rank) - 1, 0), n - 1))
def historical_var(
diff --git a/agent/tests/quantlib/test_historical_tail_decimal_boundary.py b/agent/tests/quantlib/test_historical_tail_decimal_boundary.py
new file mode 100644
index 000000000..8ec2a71c2
--- /dev/null
+++ b/agent/tests/quantlib/test_historical_tail_decimal_boundary.py
@@ -0,0 +1,35 @@
+"""Exact hand-ranked tails at decimal confidence boundaries."""
+
+import numpy as np
+import pytest
+
+from src.quantlib.risk import historical_cvar, historical_var
+
+
+ "n,confidence,tail_count",
+ [
+ (20, 0.95, 1),
+ (100, 0.95, 5),
+ (100, 0.99, 1),
+ (50, 0.9, 5),
+ (100, 0.975, 3),
+ (20, 0.75, 5),
+ (100, 0.9500000000000001, 5),
+ (100, 0.9499999999999998, 6),
+ ],
+)
[email protected]("measure", ["var", "cvar"])
+def test_historical_tail_matches_explicit_rank(n, confidence, tail_count, measure):
+ # The ranks are specified independently above: e.g. five losses in a 100-row
+ # lower 5% tail, and one loss in a 20-row lower 5% tail. No floating-point
+ # subtraction or quantile routine is used to calculate this oracle.
+ returns = -np.arange(n, 0, -1, dtype=float) / n
+ expected_var = (n - tail_count + 1) / n
+ expected_cvar = (n + (n - tail_count + 1)) / (2 * n)
+ function, expected = (
+ (historical_var, expected_var)
+ if measure == "var"
+ else (historical_cvar, expected_cvar)
+ )
+ assert function(returns[::-1], confidence) == pytest.approx(expected)
diff --git a/agent/tests/quantlib/test_risk.py b/agent/tests/quantlib/test_risk.py
index bce3cee16..da6e54936 100644
--- a/agent/tests/quantlib/test_risk.py
+++ b/agent/tests/quantlib/test_risk.py
@@ -25,7 +25,7 @@ from src.quantlib.risk import (
)
# 20 observations, already ascending: -0.10, -0.09, ..., 0.09.
-# The 95% VaR order statistic is index floor(0.05 * 20) = 1, i.e. -0.09.
+# The 95% lower tail has one observation: index ceil(0.05 * 20) - 1 = 0.
FIXED_RETURNS = np.round(np.arange(-0.10, 0.10, 0.01), 10)
@@ -42,8 +42,8 @@ def test_fixture_is_the_array_the_hand_computations_assume():
def test_historical_var_is_the_hand_computed_order_statistic():
- # index floor((1 - 0.95) * 20) = 1 -> second smallest = -0.09 -> loss 0.09
- assert historical_var(FIXED_RETURNS, confidence=0.95) == pytest.approx(0.09)
+ # index ceil((1 - 0.95) * 20) - 1 = 0 -> smallest = -0.10
+ assert historical_var(FIXED_RETURNS, confidence=0.95) == pytest.approx(0.10)
def test_historical_var_at_99_takes_the_worst_observation():
@@ -66,7 +66,7 @@ def test_historical_var_scales_with_square_root_of_time():
def test_historical_var_ignores_nan():
with_nan = np.concatenate([FIXED_RETURNS, [np.nan, np.inf, -np.inf]])
- assert historical_var(with_nan, confidence=0.95) == pytest.approx(0.09)
+ assert historical_var(with_nan, confidence=0.95) == pytest.approx(0.10)
# --------------------------------------------------------------------------
@@ -175,9 +175,8 @@ def test_a_bigger_loss_is_a_bigger_number_for_every_measure():
def test_historical_cvar_is_the_hand_computed_tail_mean():
- # Tail at 95% is everything at or below the VaR order statistic (-0.09),
- # i.e. {-0.10, -0.09}; mean -0.095 -> loss 0.095.
- assert historical_cvar(FIXED_RETURNS, confidence=0.95) == pytest.approx(0.095)
+ # Tail at 95% is the single worst observation (-0.10).
+ assert historical_cvar(FIXED_RETURNS, confidence=0.95) == pytest.approx(0.10)
def test_historical_cvar_at_99_is_the_single_worst_observation():
@@ -393,9 +392,11 @@ def _paths_with_terminal_returns(returns):
def test_analyze_mc_results_reuses_the_var_convention():
- summary = analyze_mc_results(_paths_with_terminal_returns(FIXED_RETURNS), confidence=0.95)
- assert summary["var"] == pytest.approx(0.09)
- assert summary["cvar"] == pytest.approx(0.095)
+ summary = analyze_mc_results(
+ _paths_with_terminal_returns(FIXED_RETURNS), confidence=0.95
+ )
+ assert summary["var"] == pytest.approx(0.10)
+ assert summary["cvar"] == pytest.approx(0.10)
assert summary["cvar"] >= summary["var"]
assert summary["mean_return"] == pytest.approx(FIXED_RETURNS.mean())
assert summary["median_return"] == pytest.approx(np.median(FIXED_RETURNS))
@@ -412,8 +413,8 @@ def test_analyze_mc_results_tail_mask_is_not_fooled_by_an_all_negative_sample():
summary = analyze_mc_results(_paths_with_terminal_returns(returns), confidence=0.95)
assert summary["prob_loss"] == pytest.approx(1.0)
assert summary["cvar"] >= summary["var"] > 0
- # Tail of 5 worst of 100: index floor(0.05 * 100) = 5 -> 6 observations.
- assert summary["cvar"] == pytest.approx(-np.sort(returns)[:6].mean())
+ # Tail of five worst of 100: index ceil(0.05 * 100) - 1 = 4.
+ assert summary["cvar"] == pytest.approx(-np.sort(returns)[:5].mean())
def test_analyze_mc_results_on_a_simulated_run():