skfolio.alpha.alpha_forecast_evaluation

skfolio.alpha.alpha_forecast_evaluation(estimator, X, *, target='idio_returns', holding_period=1, signal_lag=1, evaluation_step=None, n_forward_periods=10, cs_weighting=IDENTITY, factor_exposures='exposures', factor_correlation_method=PEARSON, quantiles=(0.1,), annualization_factor=252.0, min_count=3, params=None, name=None)

Evaluate alpha forecast quality.

The function fits estimator with fit_transform, obtains historical alpha forecasts, and compares them with a forward mean target built from an AssetPanel field. The default target is idio_returns, which evaluates the idiosyncratic component forecast by the alpha estimators used by CharacteristicsFactorModel.

The diagnostics evaluate alpha forecasts before the alpha is passed to an optimizer. IC measures cross-sectional ordering and Pearson correlation. Simple rank-weighted and z-score-weighted portfolios measure the realized target return of 200% gross alpha-only long-short portfolios. The calibration slope estimates the scale multiplier needed to map forecast values to realized target units. Holding-period diagnostics evaluate the same forecasts against cumulative target windows. Decay diagnostics evaluate the same forecasts against disjoint future target windows. Diagnostics are computed on the final alpha forecast returned by the estimator. For rank-transformed forecasts, pearson_ic and zscore_weighted_portfolio evaluate the transformed rank scores, not raw descriptor magnitudes. If factor_exposures is available and factor_correlation_method is not None, the evaluation also measures contemporaneous correlation between the alpha forecast and factor exposures. Holding-period and decay diagnostics use the same evaluation dates as the main evaluation.

For example, with holding_period=5, signal_lag=1 and n_forward_periods=3, decay_summary computes IC on disjoint windows: \(corr(\alpha_t, \bar{y}_{t+1:t+5})\), \(corr(\alpha_t, \bar{y}_{t+6:t+10})\) and \(corr(\alpha_t, \bar{y}_{t+11:t+15})\). holding_period_summary computes IC on cumulative windows: \(corr(\alpha_t, \bar{y}_{t+1:t+5})\), \(corr(\alpha_t, \bar{y}_{t+1:t+10})\) and \(corr(\alpha_t, \bar{y}_{t+1:t+15})\). With holding_period=5 and n_forward_periods=79, the last cumulative window is \(corr(\alpha_t, \bar{y}_{t+1:t+395})\).

Parameters:

estimatorBaseEstimator or Pipeline

Alpha estimator exposing fit_transform and returning historical alpha forecasts with shape (n_observations, n_assets).

XAssetPanel or AssetPanelView

Point-in-time asset panel containing target and all fields required by estimator.

targetstr, default=”idio_returns”

Name of the 2D target field in X.

holding_periodint, default=1

Number of observations in the forward target window used for the main evaluation. For a forecast at date \(t\), the target is the mean value over \([t + \ell, t + \ell + h)\), where \(\ell\) is signal_lag and \(h\) is holding_period.

signal_lagint, default=1

Number of observations between the forecast date and the first target observation. signal_lag=1 evaluates next-period targets and avoids same-period look-ahead when forecasts are observed after the current target is known. signal_lag=0 evaluates same-period targets.

evaluation_stepint, optional

Spacing between evaluated forecast dates. The default None uses holding_period, which produces mostly non-overlapping target windows for the main evaluation. evaluation_step=1 evaluates every valid forecast date, which is common for signal research and creates overlapping forward targets when holding_period > 1. Values greater than holding_period produce a sparse evaluation. When evaluation_step < holding_period, summary means remain descriptive diagnostics, but IC t-statistics and IR should be interpreted with the serial dependence from overlapping targets in mind.

n_forward_periodsint, default=10

Number of consecutive forward periods used for holding-period and decay diagnostics. holding_period_summary evaluates cumulative windows from \(1 \times h\) to \(n \times h\). decay_summary evaluates \(n\) disjoint forward windows of length \(h\), where \(h\) is holding_period and \(n\) is n_forward_periods.

cs_weightingCSWeighting or str, default=CSWeighting.IDENTITY

Cross-sectional weighting for Pearson IC and the calibration scale multiplier. A string is interpreted as a 2D field name in X. Descriptive forecast, target and calibration-curve statistics are unweighted.

factor_exposuresstr, optional, default=”exposures”

Name of a 3D field in AssetPanel X containing factor exposures used to compute alpha-factor correlation diagnostics. If the default field is not present, factor correlation diagnostics are skipped. Passing None skips them explicitly.

factor_correlation_methodCorrelationMethod, optional, default=CorrelationMethod.PEARSON

Factor correlation method to compute. PEARSON measures linear tilt of forecast values to factor exposures and is weighted by cs_weighting. SPEARMAN measures monotonic alignment of forecast ordering with exposure ordering and is more expensive for large exposure tensors. Passing None skips factor correlation diagnostics.

quantilestuple of float, default=(0.1,)

Forecast quantiles for top-minus-bottom spread diagnostics. Each value must be in (0, 0.5].

annualization_factorfloat, default=252.0

Number of observations per year used to annualize return statistics in portfolio_summary and quantile_summary.

min_countint, default=3

Minimum number of valid assets required for each cross-sectional diagnostic.

paramsdict, optional

Parameters routed to estimator.fit_transform.

namestr, optional

Display name for the evaluation. Defaults to str(estimator).

Returns:

evaluationAlphaForecastEvaluation

Frozen dataclass with diagnostic series, summary statistics and plots.