skfolio.alpha.AlphaForecastEvaluation#

class skfolio.alpha.AlphaForecastEvaluation(observations, holding_period, n_forward_periods, signal_lag, evaluation_step, annualization_factor, target, cs_weighting, spearman_ic, pearson_ic, rank_weighted_portfolio_return, zscore_weighted_portfolio_return, rank_weighted_turnover, zscore_weighted_turnover, quantile_spread, quantiles, n_valid_assets, coverage, calibration_slope, mean_forecast, std_forecast, mean_target, std_target, calibration_curve, factor_correlation, factor_correlation_method, factor_names, factor_families, holding_period_diagnostics, decay, name=None)[source]#

Out-of-sample alpha forecast evaluation.

Stores cross-sectional diagnostics produced by alpha_forecast_evaluation and provides summary statistics and plots.

The evaluation compares historical alpha forecasts observed at time \(t\) with the forward mean of a target field over \([t + \ell, t + \ell + h)\), where \(h\) is holding_period and \(\ell\) is signal_lag. The default target is idio_returns, which evaluates the alpha component not explained by the factor model.

The core diagnostics are:

IC: cross-sectional correlation between alpha forecasts and future target returns. Spearman IC measures ordering quality. Pearson IC is the weighted Pearson correlation under cs_weighting.
Simple alpha portfolios: 200% gross rank-weighted and z-score-weighted long-short portfolios built directly from the forecast. They measure the realized target return of alpha-only portfolios before the alpha is passed to an optimizer.
Quantile spreads: top-minus-bottom target returns for forecast quantiles, equivalent to 200% gross long-short bucket returns. They measure whether realized returns are concentrated in the highest-scored and lowest-scored assets.
Calibration: scale multiplier from a weighted regression of realized target on forecast with zero intercept. A value near 1 indicates that the forecast is already scaled to realized target units.
Factor correlations: contemporaneous cross-sectional correlation between alpha forecasts and factor exposures. They help assess whether the alpha forecast is cross-sectionally neutral to existing factors.
Holding-period summary: the same forecasts evaluated against cumulative forward target windows.
Decay: the same forecasts evaluated against disjoint forward target windows.

Parameters:

observationsndarray of shape (n_steps,): Observation labels for the evaluated forecast dates.
holding_periodint: Number of observations in the forward target window used for the main evaluation.
n_forward_periodsint: Number of consecutive forward periods used for holding-period and decay diagnostics.
signal_lagint: Number of observations between the forecast date and the first target observation. For a forecast at date \(t\), the target window is \([t + \ell, t + \ell + h)\), where \(\ell\) is signal_lag and \(h\) is holding_period.
evaluation_stepint: Spacing between evaluated forecast dates.
annualization_factorfloat: Number of observations per year used to annualize return statistics in portfolio_summary and quantile_summary.
targetstr: Name of the evaluated target field in the input AssetPanel.
cs_weightingCSWeighting or str: Cross-sectional weighting rule used for Pearson IC and the calibration scale multiplier.
spearman_icndarray of shape (n_steps,): Spearman rank IC over time.
pearson_icndarray of shape (n_steps,): Pearson IC over time using cs_weighting. With CSWeighting.IDENTITY, this is equal-weighted Pearson IC.
rank_weighted_portfolio_returnndarray of shape (n_steps,): Forward target return of a centered-rank long-short portfolio with 200% gross exposure.
zscore_weighted_portfolio_returnndarray of shape (n_steps,): Forward target return of a centered-forecast long-short portfolio with 200% gross exposure.
rank_weighted_turnoverndarray of shape (n_steps,): Turnover of the rank-weighted portfolio. The first value is NaN.
zscore_weighted_turnoverndarray of shape (n_steps,): Turnover of the z-score-weighted portfolio. The first value is NaN.
quantile_spreadndarray of shape (n_steps, n_quantiles): Top-minus-bottom target return for each quantile in quantiles, equivalent to a 200% gross long-short bucket return.
quantilestuple of float: Quantiles evaluated in quantile_spread.
n_valid_assetsndarray of shape (n_steps,): Number of assets with finite forecast and target values.
coveragendarray of shape (n_steps,): Fraction of eligible assets used at each evaluation date.
calibration_slopefloat: Scale multiplier from a weighted regression of realized target on forecast with zero intercept.
mean_forecastfloat: Mean evaluated alpha forecast.
std_forecastfloat: Standard deviation of evaluated alpha forecasts.
mean_targetfloat: Mean evaluated forward target.
std_targetfloat: Standard deviation of evaluated forward targets.
calibration_curveDataFrame: Forecast-bucket calibration table with average forecast and realized target values.
factor_correlationndarray of shape (n_observations, n_factors), optional: Contemporaneous correlation between alpha forecasts and factor exposures. Pearson correlations are weighted by the cross-sectional weights resolved from cs_weighting. None when factor correlation diagnostics were skipped.
factor_correlation_methodCorrelationMethod, optional: Factor correlation method computed from the exposure field. None when factor correlation diagnostics were skipped.
factor_namesndarray of shape (n_factors,): Factor names for factor_correlation.
factor_familiesndarray of shape (n_factors,), optional: Factor family label for each factor. None when the factor exposure field does not define groups.
holding_period_diagnosticsDataFrame: Summary statistics by cumulative holding period.
decayDataFrame: Summary statistics by disjoint forward period.
namestr, optional: Display name for the evaluation.

Attributes:

name

Methods

`calibration_summary`()	Forecast scale calibration summary.
`coverage_summary`()	Coverage summary over evaluated forecast dates.
`decay_summary`()	Alpha decay summary by disjoint forward period.
`factor_correlation_summary`([factors, families])	Alpha-factor correlation summary.
`holding_period_summary`()	Alpha diagnostics by cumulative holding period.
`ic_summary`()	Information Coefficient summary.
`plot_calibration`([title])	Plot realized target by forecast bucket.
`plot_cumulative_ic`(*[, include_pearson, title])	Plot cumulative IC over time.
`plot_cumulative_returns`([title])	Plot cumulative returns of 200% gross simple alpha portfolios.
`plot_factor_correlation`([factors, families, ...])	Plot mean alpha-factor correlations.
`plot_ic_by_holding_period`([title])	Plot mean IC by cumulative holding period.
`plot_ic_decay`([title])	Plot mean IC by disjoint forward period.
`plot_portfolio_by_holding_period`([title])	Plot simple portfolio IR by cumulative holding period.
`plot_portfolio_decay`([title])	Plot simple portfolio IR by disjoint forward period.
`plot_quantile_returns`([title])	Plot cumulative top-minus-bottom quantile spreads.
`plot_rolling_ic`([window, title])	Plot rolling mean IC over time.
`portfolio_summary`()	Annualized 200% gross simple alpha portfolio summary.
`quantile_summary`()	Annualized top-minus-bottom quantile spread summary by tail quantile.

calibration_summary()[source]#: Forecast scale calibration summary.

coverage_summary()[source]#: Coverage summary over evaluated forecast dates.

decay_summary()[source]#: Alpha decay summary by disjoint forward period.

factor_correlation_summary(factors=None, families=None)[source]#

Alpha-factor correlation summary.

Measures contemporaneous cross-sectional correlation between alpha forecasts and factor exposures. This helps assess whether the alpha forecast is cross-sectionally neutral to existing factors. The ir column is \(\bar{\rho} / \sigma_{\rho}\). The t_stat column is the date-level t-statistic of the mean correlation. Pearson correlations are weighted by the cross-sectional weights resolved from cs_weighting.

Parameters:

factorslist of str, optional: Explicit factor names to include. Takes precedence over families.
familiesstr, list of str, optional: Factor families to include. None includes all factors.

Returns:

summaryDataFrame: Rows are factors and columns are mean, std, ir, t_stat and hit_rate.

holding_period_summary()[source]#: Alpha diagnostics by cumulative holding period.

ic_summary()[source]#

Information Coefficient summary.

Returns one row for Spearman IC and one row for Pearson IC. The icir column is \(\bar{IC} / \sigma_{IC}\). The t_stat column is the date-level t-statistic of the mean IC.

plot_calibration(title=None)[source]#: Plot realized target by forecast bucket.

plot_cumulative_ic(*, include_pearson=True, title=None)[source]#: Plot cumulative IC over time.

plot_cumulative_returns(title=None)[source]#: Plot cumulative returns of 200% gross simple alpha portfolios.

plot_factor_correlation(factors=None, families=None, top_n=20, title=None)[source]#: Plot mean alpha-factor correlations.

plot_ic_by_holding_period(title=None)[source]#: Plot mean IC by cumulative holding period.

plot_ic_decay(title=None)[source]#: Plot mean IC by disjoint forward period.

plot_portfolio_by_holding_period(title=None)[source]#: Plot simple portfolio IR by cumulative holding period.

plot_portfolio_decay(title=None)[source]#: Plot simple portfolio IR by disjoint forward period.

plot_quantile_returns(title=None)[source]#: Plot cumulative top-minus-bottom quantile spreads.

plot_rolling_ic(window=50, title=None)[source]#: Plot rolling mean IC over time.

portfolio_summary()[source]#: Annualized 200% gross simple alpha portfolio summary.

quantile_summary()[source]#: Annualized top-minus-bottom quantile spread summary by tail quantile.