sf_quant.performance.generate_drawdown_summary_table#

sf_quant.performance.generate_drawdown_summary_table(drawdown: DrawdownSchema) → DataFrame#

Generate a summary statistics table for portfolio drawdowns.

This function calculates summary metrics for portfolio drawdowns, including mean, min (max drawdown), current drawdown, and longest drawdown period.

Parameters#

drawdownDrawdownSchema

Portfolio drawdowns validated against DrawdownSchema. Must include the following columns:

  • date (date): The observation date.

  • drawdown (float): Daily portfolio drawdown (≤ 0).

Returns#

pl.DataFrame

A single-row DataFrame containing drawdown summary statistics:

  • Count (int): Number of days in the sample.

  • Mean Drawdown (%) (float): Average drawdown (in percent).

  • Max Drawdown (%) (float): Maximum drawdown (in percent).

  • Current Drawdown (%) (float): Most recent drawdown (in percent).

  • Longest Drawdown (days) (int): Longest consecutive period in drawdown.

Notes#

  • Drawdowns are expressed as negative percentages.

  • A drawdown of 0% indicates the portfolio is at a new peak.

  • Max Drawdown represents the largest peak-to-trough decline.

  • Longest Drawdown counts consecutive days where drawdown < 0.

Examples#

>>> import polars as pl
>>> import sf_quant.performance as sfp
>>> import datetime as dt
>>> weights = pl.DataFrame(
...     {
...         'date': [dt.date(2024, 1, 2), dt.date(2024, 1, 2), dt.date(2024, 1, 3), dt.date(2024, 1, 3)],
...         'barrid': ['USA06Z1', 'USA0771', 'USA06Z1', 'USA0771'],
...         'weight': [0.5, 0.5, 0.3, 0.7]
...     }
... )
>>> returns = sfp.generate_returns_from_weights(weights)
>>> drawdown = sfp.generate_drawdown_from_returns(returns)
>>> summary = sfp.generate_drawdown_summary_table(drawdown)
>>> summary
shape: (1, 5)
┌───────┬────────────────────┬──────────────────┬──────────────────────┬───────────────────────┐
│ Count ┆ Mean Drawdown (%)  ┆ Max Drawdown (%) ┆ Current Drawdown (%) ┆ Longest Drawdown (da… │
│ ---   ┆ ---                ┆ ---              ┆ ---                  ┆ ---                   │
│ u32   ┆ f64                ┆ f64              ┆ f64                  ┆ i64                   │
╞═══════╪════════════════════╪══════════════════╪══════════════════════╪═══════════════════════╡
│ 2     ┆ -0.81              ┆ -1.62            ┆ -1.62                ┆ 1                     │
└───────┴────────────────────┴──────────────────┴──────────────────────┴───────────────────────┘