Factor Reference

Alpha formulas and factor analysis tools.

Back to API Reference

Factor analysis facade.

FactorAnalyzer dataclass

Analyze cross-sectional factor values and forward returns.

__post_init__

__post_init__() -> None

Promote single-index data to MultiIndex to support single-asset analysis.

from_clean_factor_data classmethod

from_clean_factor_data(clean: DataFrame, *, periods: tuple[int, ...] | None = None, annualization_periods: int = 252, quantiles: int = 5) -> MultiPeriodFactorAnalyzer | MultiFactorAnalyzer

Return an analysis object built from clean factor data.

clean is the frame produced by clean_factor_and_forward_returns. A factor_name column produces one multi-period analyzer per factor.

multi_period_summary classmethod

multi_period_summary(clean: DataFrame, *, periods: tuple[int, ...] | None = None, annualization_periods: int = 252, quantiles: int = 5) -> pd.DataFrame

Return summary metrics indexed by prediction horizon.

ic

ic(by_group: bool = False) -> pd.Series | pd.DataFrame

Return per-date Pearson information coefficient.

rank_ic

rank_ic(by_group: bool = False) -> pd.Series | pd.DataFrame

Return per-date Spearman rank information coefficient.

ic_ir

ic_ir() -> float

Return annualized IC information ratio.

quantile_returns

quantile_returns(group_neutral: bool = False) -> pd.DataFrame

Return mean forward returns by factor quantile.

quantile_stats

quantile_stats() -> pd.DataFrame

Return summary statistics by factor quantile.

quantile_counts

quantile_counts() -> pd.DataFrame

Return per-date asset counts by factor quantile.

quantile_forward_returns

quantile_forward_returns() -> pd.DataFrame

Return raw forward return observations with assigned factor quantiles.

quantile_decay

quantile_decay(window: int = 5) -> pd.DataFrame

Return rolling mean returns by factor quantile.

quantile_cumulative_returns

quantile_cumulative_returns() -> pd.DataFrame

Return compounded returns by factor quantile.

quantile_spread

quantile_spread(reverse: bool = False) -> pd.Series

Return top-minus-bottom factor quantile returns.

long_short_returns

long_short_returns() -> pd.DataFrame

Return long, short, and spread factor returns.

long_short_cumulative_returns

long_short_cumulative_returns() -> pd.DataFrame

Return compounded long, short, and spread factor returns.

factor_returns

factor_returns() -> pd.DataFrame

Return quantile returns derived from configured prices.

monthly_ic_heatmap

monthly_ic_heatmap(by_group: bool = False) -> pd.DataFrame

Return mean IC by year and month.

event_returns staticmethod

event_returns(prices: Series, events: MultiIndex, before: int = 5, after: int = 5) -> pd.DataFrame

Return average event-window returns around (date, symbol) events.

turnover

turnover() -> pd.Series

Return factor rank turnover.

autocorrelation

autocorrelation() -> pd.Series

Return factor rank autocorrelation.

events_distribution

events_distribution() -> pd.DataFrame

Return factor observation events for event-count distribution charts.

summary

summary() -> dict[str, float]

Return scalar factor diagnostics.

monotonicity

monotonicity() -> dict[str, float]

Return monotonicity diagnostics for the factor quantile returns.

Checks whether mean returns increase monotonically from Q1 to Q(n). Returns Spearman rank correlation between quantile rank and mean return, and a boolean flag indicating perfect monotonicity.

plot

plot()

Return a Bokeh grid of factor diagnostic charts.

html

html(path: str) -> Path

Write a standalone Alphalens-style factor report and return the output path.

report

report(path: str, format: str | None = None) -> Path

Write a factor report using the user-facing report() entrypoint.

MultiFactorAnalyzer dataclass

Thin facade around one multi-period analyzer per factor.

__getitem__

__getitem__(factor: str) -> MultiPeriodFactorAnalyzer

Return the analyzer for factor.

keys

keys()

Return available factor names.

values

values()

Return analyzers ordered by factor name.

items

items()

Return (factor, analyzer) pairs ordered by factor name.

summary

summary() -> pd.DataFrame

Return summary metrics indexed by (factor, period).

ic

ic(by_group: bool = False) -> pd.DataFrame

Return IC series with (factor, period) columns.

rank_ic

rank_ic(by_group: bool = False) -> pd.DataFrame

Return rank IC series with (factor, period) columns.

report

report(path: str, format: str | None = None) -> Path

Write a multi-factor report using the user-facing report() entrypoint.

html

html(path: str) -> Path

Write one HTML report containing every factor and prediction horizon.

MultiPeriodFactorAnalyzer dataclass

Thin facade around one FactorAnalyzer per prediction horizon.

__getitem__

__getitem__(period: int) -> FactorAnalyzer

Return the analyzer for period.

keys

keys()

Return available prediction horizons.

values

values()

Return analyzers ordered by prediction horizon.

items

items()

Return (period, analyzer) pairs ordered by prediction horizon.

summary

summary() -> pd.DataFrame

Return summary metrics indexed by prediction horizon.

ic

ic(by_group: bool = False) -> pd.Series | pd.DataFrame

Return IC series for every prediction horizon.

rank_ic

rank_ic(by_group: bool = False) -> pd.Series | pd.DataFrame

Return rank IC series for every prediction horizon.

quantile_returns

quantile_returns(period: int | None = None) -> pd.DataFrame | dict[int, pd.DataFrame]

Return quantile returns for one or all prediction horizons.

plot

plot(period: int | None = None)

Return factor diagnostic charts for a selected prediction horizon.

html

html(path: str, period: int | None = None) -> Path

Write a standalone factor report for a selected prediction horizon.

report

report(path: str, format: str | None = None, period: int | None = None) -> Path

Write a factor report for a selected prediction horizon.

FactorRiskModel dataclass

Static or dated multi-factor risk model.

Parameters

exposures Asset factor exposure matrix. Use a symbol index for a static model, or a (date, symbol) MultiIndex for dated exposures. factor_cov Factor covariance matrix with factor names as index and columns. specific_var Asset-specific variance by symbol. Missing symbols default to zero.

portfolio_exposure

portfolio_exposure(weights: Series | dict[str, float], date=None) -> pd.Series

Return weighted factor exposure for a portfolio.

portfolio_variance

portfolio_variance(weights: Series | dict[str, float], date=None) -> float

Return total portfolio variance from factor and specific risk.

portfolio_risk

portfolio_risk(weights: Series | dict[str, float], date=None) -> float

Return portfolio volatility.

risk_contribution

risk_contribution(weights: Series | dict[str, float], date=None) -> pd.DataFrame

Return variance contribution by factor plus specific risk.

active_risk

active_risk(portfolio_weights: Series | dict[str, float], benchmark_weights: Series | dict[str, float], date=None) -> float

Return active risk against a benchmark weight vector.

PerformanceAttribution dataclass

Attribute strategy returns to factor and specific returns.

The data contract follows the same shape as pyfolio: positions are wide by asset, factor_returns are wide by factor, and dated factor_loadings use a (date, symbol) MultiIndex.

exposures

exposures() -> pd.DataFrame

Return daily portfolio factor exposures.

attribution

attribution() -> pd.DataFrame

Return factor, common, specific, and total return attribution.

summary

summary() -> tuple[dict[str, float], pd.DataFrame]

Return scalar return attribution and factor exposure summaries.

clean_factor_and_forward_returns

clean_factor_and_forward_returns(factors: DataFrame, *, factor: str | Sequence[str], prices: Series | DataFrame, periods: tuple[int, ...] = (1,), quantiles: int = 5, groupby: str | Series | None = None, nan_policy: NanPolicy = 'drop') -> pd.DataFrame

Return an Alphalens-style clean factor frame.

factors is a factor table indexed by (date, symbol). factor names the column or columns to analyze, and prices supplies aligned close prices. Output is indexed by (date, symbol) and contains factor, forward_return_N columns, factor_quantile, and optional group.