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, *, _evaluation_positions=None)

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()

Forecast scale calibration summary.

coverage_summary()

Coverage summary over evaluated forecast dates.

decay_summary()

Alpha decay summary by disjoint forward period.

All rows use the same forecast dates. Each row measures how well those forecasts predict a later window of length holding_period. The IC t-statistics, p-values and confidence intervals use the method described in ic_summary. The minimum history is 10 times holding_period for every row, regardless of how far ahead its window starts.

Returns:

summaryDataFrame

Copy of the diagnostics indexed by forward period, starting at 1. Columns follow holding_period_summary.

factor_correlation_summary(factors=None, families=None)

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}\). Pearson correlations use the cross-sectional weights specified by cs_weighting.

The t-statistic, p-value and confidence interval follow ic_summary and use all forecast dates regardless of evaluation_step. They require at least 20 valid correlations and enough variation to estimate a nonzero standard error. The minimum history of 10 holding periods does not apply because these correlations compare forecasts and exposures at the same date.

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, p_value, mean_ci_lower, mean_ci_upper and hit_rate.

holding_period_summary()

Alpha diagnostics by cumulative holding period.

Each holding period is evaluated using the same forecast dates. The IC t-statistics, p-values and confidence intervals use the method described in ic_summary. The minimum history is 10 times the holding period of each row. For example, a 15-observation holding period requires a history spanning at least 150 observations.

Returns:

summaryDataFrame

Copy of the diagnostics indexed by holding period. Includes mean IC, ICIR, portfolio statistics and coverage. The IC inference columns are ic_t_stat, ic_p_value, mean_ic_ci_lower and mean_ic_ci_upper, each prefixed with spearman_ or pearson_.

ic_summary()

Information Coefficient summary.

Returns one row for Spearman IC and one row for Pearson IC. The mean, standard deviation, icir and hit rate describe the observed IC values. The icir is \(\bar{IC} / \sigma_{IC}\).

The t_stat divides the mean IC by a quadratic spectral heteroskedasticity and autocorrelation consistent (HAC) standard error, accounting for changing volatility and dependence between dates, including overlapping forward returns. Its reference distribution comes from a Gaussian wild bootstrap. The resulting two-sided p_value tests whether the mean IC is zero, with an approximate 95% confidence interval given by mean_ci_lower and mean_ci_upper. Significance at the 5% level corresponds to a p-value below 0.05 and an interval that excludes zero.

Returns:

summaryDataFrame

Rows are spearman_ic and pearson_ic. Columns are mean, std, icir, t_stat, p_value, mean_ci_lower, mean_ci_upper and hit_rate. The confidence interval bounds are in IC units.

Notes

The method follows [1]. The bandwidth is 10% of the evaluation history, including gaps between valid ICs. The bootstrap uses 9,999 independent Gaussian draws and a fixed seed. The smallest reported p-value is 0.0001.

The t-statistic, p-value and confidence interval require at least 20 valid ICs spanning 10 holding periods. They are NaN if these conditions are unmet, ICs are nearly constant or the standard error is zero. Descriptive statistics are still returned.

References

[1]

“Robust Fixed-b Inference in the Presence of Time-Varying Volatility”. Econometrics and Statistics, 37, 154-173. Demetrescu, Hanck and Kruse-Becher (2026).

plot_calibration(title=None)

Plot realized target by forecast bucket.

plot_cumulative_ic(*, include_pearson=True, title=None)

Plot cumulative IC over time.

plot_cumulative_returns(title=None)

Plot cumulative returns of 200% gross simple alpha portfolios.

plot_factor_correlation(factors=None, families=None, top_n=20, title=None)

Plot mean alpha-factor correlations.

plot_ic_by_holding_period(title=None)

Plot mean IC by cumulative holding period.

plot_ic_decay(title=None)

Plot mean IC by disjoint forward period.

plot_portfolio_by_holding_period(title=None)

Plot simple portfolio IR by cumulative holding period.

plot_portfolio_decay(title=None)

Plot simple portfolio IR by disjoint forward period.

plot_quantile_returns(title=None)

Plot cumulative top-minus-bottom quantile spreads.

plot_rolling_ic(window=50, title=None)

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.