<a id="skfolio-alpha-alphaforecastevaluation"></a>

# skfolio.alpha.AlphaForecastEvaluation

<a id="skfolio.alpha.AlphaForecastEvaluation"></a>

### *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)

Out-of-sample alpha forecast evaluation.

Stores cross-sectional diagnostics produced by
[`alpha_forecast_evaluation`](https://skfolio.org/generated/skfolio.alpha.alpha_forecast_evaluation.html.md#skfolio.alpha.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:**
  **observations** *ndarray of shape (n_steps,)*
  : Observation labels for the evaluated forecast dates.

  **holding_period** *int*
  : Number of observations in the forward target window used for the main
    evaluation.

  **n_forward_periods** *int*
  : Number of consecutive forward periods used for holding-period and decay
    diagnostics.

  **signal_lag** *int*
  : 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_step** *int*
  : Spacing between evaluated forecast dates.

  **annualization_factor** *float*
  : Number of observations per year used to annualize return statistics in
    `portfolio_summary` and `quantile_summary`.

  **target** *str*
  : Name of the evaluated target field in the input `AssetPanel`.

  **cs_weighting** *CSWeighting or str*
  : Cross-sectional weighting rule used for Pearson IC and the calibration
    scale multiplier.

  **spearman_ic** *ndarray of shape (n_steps,)*
  : Spearman rank IC over time.

  **pearson_ic** *ndarray of shape (n_steps,)*
  : Pearson IC over time using `cs_weighting`. With
    `CSWeighting.IDENTITY`, this is equal-weighted Pearson IC.

  **rank_weighted_portfolio_return** *ndarray of shape (n_steps,)*
  : Forward target return of a centered-rank long-short portfolio with
    200% gross exposure.

  **zscore_weighted_portfolio_return** *ndarray of shape (n_steps,)*
  : Forward target return of a centered-forecast long-short portfolio with
    200% gross exposure.

  **rank_weighted_turnover** *ndarray of shape (n_steps,)*
  : Turnover of the rank-weighted portfolio. The first value is `NaN`.

  **zscore_weighted_turnover** *ndarray of shape (n_steps,)*
  : Turnover of the z-score-weighted portfolio. The first value is `NaN`.

  **quantile_spread** *ndarray 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.

  **quantiles** *tuple of float*
  : Quantiles evaluated in `quantile_spread`.

  **n_valid_assets** *ndarray of shape (n_steps,)*
  : Number of assets with finite forecast and target values.

  **coverage** *ndarray of shape (n_steps,)*
  : Fraction of eligible assets used at each evaluation date.

  **calibration_slope** *float*
  : Scale multiplier from a weighted regression of realized target on
    forecast with zero intercept.

  **mean_forecast** *float*
  : Mean evaluated alpha forecast.

  **std_forecast** *float*
  : Standard deviation of evaluated alpha forecasts.

  **mean_target** *float*
  : Mean evaluated forward target.

  **std_target** *float*
  : Standard deviation of evaluated forward targets.

  **calibration_curve** *DataFrame*
  : Forecast-bucket calibration table with average forecast and realized
    target values.

  **factor_correlation** *ndarray 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_method** *CorrelationMethod, optional*
  : Factor correlation method computed from the exposure field. `None`
    when factor correlation diagnostics were skipped.

  **factor_names** *ndarray of shape (n_factors,)*
  : Factor names for `factor_correlation`.

  **factor_families** *ndarray of shape (n_factors,), optional*
  : Factor family label for each factor. `None` when the factor exposure
    field does not define groups.

  **holding_period_diagnostics** *DataFrame*
  : Summary statistics by cumulative holding period.

  **decay** *DataFrame*
  : Summary statistics by disjoint forward period.

  **name** *str, optional*
  : Display name for the evaluation.
* **Attributes:**
  **name**

### Methods

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

<a id="skfolio.alpha.AlphaForecastEvaluation.calibration_summary"></a>

#### calibration_summary()

Forecast scale calibration summary.

<a id="skfolio.alpha.AlphaForecastEvaluation.coverage_summary"></a>

#### coverage_summary()

Coverage summary over evaluated forecast dates.

<a id="skfolio.alpha.AlphaForecastEvaluation.decay_summary"></a>

#### decay_summary()

Alpha decay summary by disjoint forward period.

<a id="skfolio.alpha.AlphaForecastEvaluation.factor_correlation_summary"></a>

#### 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}$. 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:**
  **factors** *list of str, optional*
  : Explicit factor names to include. Takes precedence over `families`.

  **families** *str, list of str, optional*
  : Factor families to include. `None` includes all factors.
* **Returns:**
  **summary** *DataFrame*
  : Rows are factors and columns are `mean`, `std`, `ir`, `t_stat` and
    `hit_rate`.

<a id="skfolio.alpha.AlphaForecastEvaluation.holding_period_summary"></a>

#### holding_period_summary()

Alpha diagnostics by cumulative holding period.

<a id="skfolio.alpha.AlphaForecastEvaluation.ic_summary"></a>

#### ic_summary()

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.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_calibration"></a>

#### plot_calibration(title=None)

Plot realized target by forecast bucket.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_cumulative_ic"></a>

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

Plot cumulative IC over time.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_cumulative_returns"></a>

#### plot_cumulative_returns(title=None)

Plot cumulative returns of 200% gross simple alpha portfolios.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_factor_correlation"></a>

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

Plot mean alpha-factor correlations.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_ic_by_holding_period"></a>

#### plot_ic_by_holding_period(title=None)

Plot mean IC by cumulative holding period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_ic_decay"></a>

#### plot_ic_decay(title=None)

Plot mean IC by disjoint forward period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_by_holding_period"></a>

#### plot_portfolio_by_holding_period(title=None)

Plot simple portfolio IR by cumulative holding period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_decay"></a>

#### plot_portfolio_decay(title=None)

Plot simple portfolio IR by disjoint forward period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_quantile_returns"></a>

#### plot_quantile_returns(title=None)

Plot cumulative top-minus-bottom quantile spreads.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_rolling_ic"></a>

#### plot_rolling_ic(window=50, title=None)

Plot rolling mean IC over time.

<a id="skfolio.alpha.AlphaForecastEvaluation.portfolio_summary"></a>

#### portfolio_summary()

Annualized 200% gross simple alpha portfolio summary.

<a id="skfolio.alpha.AlphaForecastEvaluation.quantile_summary"></a>

#### quantile_summary()

Annualized top-minus-bottom quantile spread summary by tail quantile.