sf_quant.performance.generate_leverage_summary_table#

sf_quant.performance.generate_leverage_summary_table(leverage: LeverageSchema) → DataFrame#

Generate a summary statistics table for portfolio leverage.

This function calculates summary metrics for portfolio leverage, including mean, min, max, and standard deviation.

Parameters#

leverageLeverageSchema

Portfolio leverage validated against LeverageSchema. Must include the following columns:

  • date (date): The observation date.

  • leverage (float): Daily portfolio leverage.

Returns#

pl.DataFrame

A single-row DataFrame containing leverage summary statistics:

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

  • Mean Leverage (float): Average leverage.

  • Min Leverage (float): Minimum leverage.

  • Max Leverage (float): Maximum leverage.

  • Std Leverage (float): Standard deviation of leverage.

Notes#

  • Leverage values are not annualized or converted to percentages.

  • Leverage = 1.0 indicates fully invested with no leverage or shorting.

  • Leverage > 1.0 indicates use of margin or shorting.

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]
...     }
... )
>>> leverage = sfp.generate_leverage_from_weights(weights)
>>> summary = sfp.generate_leverage_summary_table(leverage)
>>> summary
shape: (1, 5)
┌───────┬────────────────┬──────────────┬──────────────┬──────────────┐
│ Count ┆ Mean Leverage  ┆ Min Leverage ┆ Max Leverage ┆ Std Leverage │
│ ---   ┆ ---            ┆ ---          ┆ ---          ┆ ---          │
│ u32   ┆ f64            ┆ f64          ┆ f64          ┆ f64          │
╞═══════╪════════════════╪══════════════╪══════════════╪══════════════╡
│ 2     ┆ 1.0            ┆ 1.0          ┆ 1.0          ┆ 0.0          │
└───────┴────────────────┴──────────────┴──────────────┴──────────────┘