risk_analysis max_drawdown ignores a loss in the first period

[Astralchemist]

Bug Description

risk_analysis in qlib/contrib/evaluate.py builds the running peak only from the observed cumulative curve so the starting value is never treated as a peak and a loss in the first period is never part of max_drawdown

A series that opens with a 10% loss and then recovers reports a max drawdown of 0 in both sum and product mode and a series that opens with two 5% losses reports half of its real drawdown in sum mode

This is not about the absolute vs relative question in #1615 since the sum mode convention stays as it is and the only change is that the curve starts from 0 in sum mode and from 1 in product mode before the first period

To Reproduce

Steps to reproduce the behavior:

1. Install qlib from main at be72549
2. Run the script below
3. Compare the printed max drawdown with the returns

import pandas as pd
from qlib.contrib.evaluate import risk_analysis

# -10% on the first day, then a recovery
r = pd.Series([-0.10, 0.05, 0.06, 0.02, 0.01], index=pd.date_range("2024-01-02", periods=5, freq="B"))
print(risk_analysis(r, N=252, mode="sum").loc["max_drawdown", "risk"])
print(risk_analysis(r, N=252, mode="product").loc["max_drawdown", "risk"])

# two -5% days, then a recovery
r = pd.Series([-0.05, -0.05, 0.03, 0.04, 0.02], index=pd.date_range("2024-01-02", periods=5, freq="B"))
print(risk_analysis(r, N=252, mode="sum").loc["max_drawdown", "risk"])
print(risk_analysis(r, N=252, mode="product").loc["max_drawdown", "risk"])

Output on main

0.0
0.0
-0.05
-0.04999999999999993

Expected Behavior

• the first series should report a max drawdown of -0.10 in both modes
• the second should report -0.10 in sum mode and -0.0975 in product mode
• empyrical max_drawdown gives -0.10 and -0.0975 for the same two series

Screenshot

Not needed since the output above shows it

Environment

• Qlib version: 0.9.8.dev34 installed from main
• Python version: 3.12.14
• OS (Windows, Linux, MacOS): MacOS
• Commit number (optional, please provide it if you are using the dev version): be72549

Additional Notes

• risk_analysis is what PortAnaRecord writes to port_analysis.pkl so this is the max drawdown shown for excess return with and without cost in the standard workflow and the first day with cost starts with the opening trades
• the same pattern is in _calculate_mdd in qlib/contrib/report/analysis_position/report.py which draws the drawdown lines in the report and in get_max_drawdown_from_series in qlib/contrib/evaluate_portfolio.py
• open PR feat(evaluate): add Sortino, Calmar, and max drawdown duration to risk_analysis #2189 builds Calmar on this max drawdown and returns inf when it is 0 so a run that only loses on its first day would get an infinite Calmar
• the fix is to clip the running peak at the starting value

max_drawdown = (r.cumsum() - r.cumsum().cummax().clip(lower=0)).min()  # sum
max_drawdown = (cumulative_curve / cumulative_curve.cummax().clip(lower=1) - 1).min()  # product

• I have a branch with this fix in all three places and tests that fail on main and pass with it and I am happy to sign the CLA and open a PR

[arhancanli]

Confirmed on be72549, and the same pattern sits in two more places, so a fix to risk_analysis alone would leave the numbers disagreeing between qlib's own outputs:

• qlib/contrib/evaluate_portfolio.py, get_max_drawdown_from_series (line 190): (1 + r).cumprod() against its own cummax(), with no starting value of 1. On your two series it returns 0.0 and -0.05 (expected -0.10 and -0.0975).
• qlib/contrib/report/analysis_position/report.py, _calculate_mdd (line 32), which builds the four *_mdd columns of the position report (return_wo_mdd, return_w_cost_mdd and the two cum_ex_return_*_mdd): series - series.cummax() on a cumsum curve, so the drawdown chart also starts at 0 after a first-day loss, and the idxmin() near the top of that file that picks the drawdown period works from the same columns. For the first series the minimum is 0.0.

A single helper used by all three would keep them consistent, e.g. for the product convention:

def _drawdown(r: pd.Series, mode: str = "product") -> pd.Series:
    if mode == "sum":
        curve = r.cumsum()
        peak = curve.cummax().clip(lower=0.0)      # starting value 0 is a peak
        return curve - peak
    curve = (1 + r).cumprod()
    peak = curve.cummax().clip(lower=1.0)          # starting value 1 is a peak
    return curve / peak - 1

Clipping the running peak at the starting value is equivalent to prepending it, but keeps the index unchanged, which matters for _calculate_report_data since it aligns the drawdown columns with the dates. A regression test with your two series against all three call sites would pin it.

[Astralchemist]

Thanks for confirming it on be72549, and for tracing the other two call sites. #2359 already applies the same clip to both: get_max_drawdown_from_series clips its peak at 1 and _calculate_mdd at 0, and tests/misc/test_risk_analysis.py checks all three against the two series from the issue. I clipped rather than prepended for the reason you give, so the drawdown columns keep their dates.

One part the PR leaves alone is where the report's shaded drawdown window starts. _calculate_maximum now gets the right end date from idxmin(), but the start is still the idxmax() of the cumulative curve before that date, so when the drawdown runs from the starting value the window begins at the highest point the curve reached, not at the first date. For returns [-0.05, 0.02, -0.10, 0.04] the max drawdown is -0.13 from the start, but the window is drawn from the second day. It only affects the shading, and I can add it to #2359 if a maintainer wants it there.