qis.BenchmarkReturnsQuantilesRegime

class qis.BenchmarkReturnsQuantilesRegime(freq='QE', return_type=ReturnTypes.RELATIVE, q=None, regime_ids_colors=None)[source]

Bases: RegimeClassifier

Regime classifier based on benchmark return quantiles.

Classifies periods into regimes based on quantiles of benchmark returns, enabling analysis of performance in different market environments (e.g., bear, normal, bull markets).

Parameters:
__init__(freq='QE', return_type=ReturnTypes.RELATIVE, q=None, regime_ids_colors=None)[source]

Initialize benchmark returns quantiles regime classifier.

Parameters:

  • freq (str) – Sampling frequency (default: ‘QE’ for quarter-end)

  • return_type (ReturnTypes) – Type of returns to compute

  • q (ndarray | int) – Quantile boundaries or number of quantiles (default: [0.0, 0.16, 0.84, 1.0], the one-sigma cut: P(Z < -1) = 15.87% rounds to 16%, central mass 68% against the normal’s 68.27%. Changed from [0.0, 0.17, 0.83, 1.0] in 5.0.7)

  • regime_ids_colors (Dict[str, str]) – Mapping of regime names to colors

Methods

__init__([freq, return_type, q, ...])

Initialize benchmark returns quantiles regime classifier.

class_data_to_colors(regime_data)

Map regime IDs to colors for visualization.

compute_regimes_pa_perf_table(prices, ...[, ...])

Compute regime performance attribution table.

compute_sampled_returns_with_regime_id(...)

Classify periods by benchmark return quantiles.

get_regime_ids()

Get ordered list of regime IDs.

get_regime_ids_colors()

Get mapping of regime IDs to visualization colors.

to_dict()

Convert regime parameters to dictionary.

Attributes

REGIME_COLUMN

compute_sampled_returns_with_regime_id(prices, benchmark, include_start_date=True, include_end_date=True, **kwargs)[source]

Classify periods by benchmark return quantiles.

Parameters:

  • prices (DataFrame | Series) – Asset prices

  • benchmark (str) – Benchmark column name

  • include_start_date (bool) – Include first period

  • include_end_date (bool) – Include last period

Returns:

DataFrame with returns and regime classification

Raises:

ValueError – If insufficient data for classification, or if the benchmark returns are degenerate (constant / too many ties) so that quantile bin edges are not unique.

Return type:

DataFrame

compute_regimes_pa_perf_table(prices, benchmark, perf_params, drop_benchmark=False, **kwargs)[source]

Compute regime performance attribution table.

Parameters:

  • prices (DataFrame) – Asset prices

  • benchmark (str) – Benchmark asset name

  • perf_params (PerfParams) – Performance parameters; perf_params.sharpe_convention selects the regime-Sharpe convention (PA default, ARITHMETIC/LOG exactly additive)

  • drop_benchmark (bool) – Exclude benchmark from results

Returns:

Tuple of (performance table, regime data dictionary)

Return type:

Tuple[DataFrame, Dict[RegimeData, DataFrame]]