sf_quant.research.generate_quantile_ports

sf_quant.research.generate_quantile_ports(signal: DataFrame, num_bins: int = 10, signal_col: str = 'signal') → DataFrame

Generate quantile portfolios from signal data with vol and beta scaling.

This function bins assets into quantiles based on signal values, calculates equal-weighted returns for each quantile, computes long-short spread, and applies volatility and beta scaling transformations.

Parameters

signalpl.DataFrame

Signal data containing at least:

• date (date): The observation date.

• signal (float): The signal value used for quantile binning.

• return (float): Forward returns for each asset.

num_binsint, optional

Number of quantile bins to create (default: 10). Assets are sorted into equal-sized bins based on signal values within each date.

Returns

pl.DataFrame

A DataFrame with quantile portfolio returns (vol and beta scaled):

• date (date): The observation date.

• p_1, p_2, …, p_{num_bins} (float): Equal-weighted returns for each quantile portfolio, vol-scaled and beta-scaled.

• spread (float): Long-short spread (highest - lowest quantile), vol-scaled and beta-scaled.

• bmk_return (float): Benchmark market returns.

Notes

• Quantiles are computed within each date using qcut.

• Benchmark returns are joined from load_benchmark_returns.

• Volatility scaling uses a 22-day rolling window with 5% target vol.

• Beta scaling uses a 60-day rolling window with target beta of 1.0.

Examples

>>> import polars as pl
>>> import sf_quant.research as sfr
>>> import datetime as dt
>>> signal_df = pl.DataFrame({
...     'date': [dt.date(2024, 1, 2)] * 100,
...     'signal': list(range(100)),
...     'return': [0.01] * 100
... })
>>> quantile_ports = sfr.generate_quantile_ports(signal_df, num_bins=5)
>>> quantile_ports.head()
shape: (5, 8)
┌────────────┬────────┬────────┬────────┬────────┬────────┬────────┬──────────────┐
│ date       ┆ p_1    ┆ p_2    ┆ p_3    ┆ p_4    ┆ p_5    ┆ spread ┆ bmk_return   │
│ ---        ┆ ---    ┆ ---    ┆ ---    ┆ ---    ┆ ---    ┆ ---    ┆ ---          │
│ date       ┆ f64    ┆ f64    ┆ f64    ┆ f64    ┆ f64    ┆ f64    ┆ f64          │
╞════════════╪════════╪════════╪════════╪════════╪════════╪════════╪══════════════╡
│ 2024-01-02 ┆ 0.01   ┆ 0.01   ┆ 0.01   ┆ 0.01   ┆ 0.01   ┆ 0.0    ┆ 0.005        │
│ 2024-01-02 ┆ 0.0095 ┆ 0.0105 ┆ 0.0102 ┆ 0.0098 ┆ 0.0103 ┆ 0.0008 ┆ 0.005        │
│ 2024-01-02 ┆ 0.0092 ┆ 0.0108 ┆ 0.01   ┆ 0.0099 ┆ 0.0107 ┆ 0.0015 ┆ 0.005        │
│ 2024-01-02 ┆ 0.0088 ┆ 0.0112 ┆ 0.0098 ┆ 0.0101 ┆ 0.0112 ┆ 0.0024 ┆ 0.005        │
│ 2024-01-02 ┆ 0.0085 ┆ 0.0115 ┆ 0.0096 ┆ 0.0102 ┆ 0.0118 ┆ 0.0033 ┆ 0.005        │
└────────────┴────────┴────────┴────────┴────────┴────────┴────────┴──────────────┘