skfolio.portfolio.MultiPeriodPortfolio

class skfolio.portfolio.MultiPeriodPortfolio(portfolios=None, name=None, tag=None, risk_free_rate=0, annualization_factor=None, fitness_measures=None, compounded=False, sample_weight=None, min_acceptable_return=None, value_at_risk_beta=0.95, entropic_risk_measure_theta=1, entropic_risk_measure_beta=0.95, cvar_beta=0.95, evar_beta=0.95, drawdown_at_risk_beta=0.95, cdar_beta=0.95, edar_beta=0.95, check_observations_order=False, **kwargs)

Multi-Period Portfolio class.

A Multi-Period Portfolio is composed of a list of Portfolio.

Parameters:

portfolioslist[Portfolio], optional

A list of Portfolio. The default (None) is to initialize with an empty list.

namestr, optional

Name of the multi-period portfolio. The default (None) is to use the object id.

tagstr, optional

Tag given to the multi-period portfolio. Tags are used to manipulate groups of portfolios from a Population.

fitness_measureslist[measures], optional

List of fitness measures. Fitness measures are used to compute the portfolio fitness which is used to compute domination. The default (None) is to use the list [PerfMeasure.MEAN, RiskMeasure.VARIANCE]

annualization_factorfloat, default=252.0

Factor used to annualize the below measures using the square-root rule:

• Annualized Mean = Mean * factor

• Annualized Variance = Variance * factor

• Annualized Semi-Variance = Semi-Variance * factor

• Annualized Standard-Deviation = Standard-Deviation * sqrt(factor)

• Annualized Semi-Deviation = Semi-Deviation * sqrt(factor)

• Annualized Sharpe Ratio = Sharpe Ratio * sqrt(factor)

• Annualized Sortino Ratio = Sortino Ratio * sqrt(factor)

risk_free_ratefloat, default=0.0

Risk-free rate. The default value is 0.0.

compoundedbool, default=False

If this is set to True, cumulative returns are compounded. The default is False.

sample_weightndarray of shape (n_observations,), optional

Sample weights for each observation. If None, equal weights are assumed.

min_acceptable_returnfloat, optional

The minimum acceptable return used to distinguish “downside” and “upside” returns for the computation of lower partial moments:

• First Lower Partial Moment

• Semi-Variance

• Semi-Deviation

The default (None) is to use the mean.

value_at_risk_betafloat, default=0.95

The confidence level of the portfolio VaR (Value At Risk) which represents the return on the worst (1-beta)% observations. The default value is 0.95.

entropic_risk_measure_thetafloat, default=1.0

The risk aversion level of the portfolio Entropic Risk Measure. The default value is 1.0.

entropic_risk_measure_betafloat, default=0.95

The confidence level of the portfolio Entropic Risk Measure. The default value is 0.95.

cvar_betafloat, default=0.95

The confidence level of the portfolio CVaR (Conditional Value at Risk) which represents the expected VaR on the worst (1-beta)% observations. The default value is 0.95.

evar_betafloat, default=0.95

The confidence level of the portfolio EVaR (Entropic Value at Risk). The default value is 0.95.

drawdown_at_risk_betafloat, default=0.95

The confidence level of the portfolio Drawdown at Risk (DaR) which represents the drawdown on the worst (1-beta)% observations. The default value is 0.95.

cdar_betafloat, default=0.95

The confidence level of the portfolio CDaR (Conditional Drawdown at Risk) which represents the expected drawdown on the worst (1-beta)% observations. The default value is 0.95.

edar_betafloat, default=0.95

The confidence level of the portfolio EDaR (Entropic Drawdown at Risk). The default value is 0.95.

check_observations_orderbool, default=False

If this is set to True, and if the list of portfolios is not chronologically sorted, an error is raised. The chronological order is determined by comparing the first and last observations of each portfolio. The default is False.

Attributes:

n_observationsfloat

Number of observations.

meanfloat

Mean of the portfolio returns.

annualized_meanfloat

Mean annualized by \(mean \times annualization\_factor\)

mean_absolute_deviationfloat

Mean Absolute Deviation. The deviation is the difference between the return and a minimum acceptable return (min_acceptable_return).

first_lower_partial_momentfloat

First Lower Partial Moment. The First Lower Partial Moment is the mean of the returns below a minimum acceptable return (min_acceptable_return).

variancefloat

Variance (Second Moment)

annualized_variancefloat

Variance annualized by \(variance \times annualization\_factor\)

semi_variancefloat

Semi-variance (Second Lower Partial Moment). The semi-variance is the variance of the returns below a minimum acceptable return (min_acceptable_return).

annualized_semi_variancefloat

Semi-variance annualized by \(semi\_variance \times annualization\_factor\)

standard_deviationfloat

Standard Deviation (Square Root of the Second Moment).

annualized_standard_deviationfloat

Standard Deviation annualized by \(standard\_deviation \times \sqrt{annualization\_factor}\)

semi_deviationfloat

Semi-deviation (Square Root of the Second Lower Partial Moment). The Semi Standard Deviation is the Standard Deviation of the returns below a minimum acceptable return (min_acceptable_return).

annualized_semi_deviationfloat

Semi-deviation annualized by \(semi\_deviation \times \sqrt{annualization\_factor}\)

skewfloat

Skew. The Skew is a measure of the lopsidedness of the distribution. A symmetric distribution have a Skew of zero. Higher Skew corresponds to longer right tail.

kurtosisfloat

Kurtosis. It is a measure of the heaviness of the tail of the distribution. Higher Kurtosis corresponds to greater extremity of deviations (fat tails).

fourth_central_momentfloat

Fourth Central Moment.

fourth_lower_partial_momentfloat

Fourth Lower Partial Moment. It is a measure of the heaviness of the downside tail of the returns below a minimum acceptable return (min_acceptable_return). Higher Fourth Lower Partial Moment corresponds to greater extremity of downside deviations (downside fat tail).

worst_realizationfloat

Worst Realization which is the worst return.

value_at_riskfloat

Historical VaR (Value at Risk). The VaR is the maximum loss at a given confidence level (value_at_risk_beta).

cvarfloat

Historical CVaR (Conditional Value at Risk). The CVaR (or Tail VaR) represents the mean shortfall at a specified confidence level (cvar_beta).

entropic_risk_measurefloat

Historical Entropic Risk Measure. It is a risk measure which depends on the risk aversion defined by the investor (entropic_risk_measure_theta) through the exponential utility function at a given confidence level (entropic_risk_measure_beta).

evarfloat

Historical EVaR (Entropic Value at Risk). It is a coherent risk measure which is an upper bound for the VaR and the CVaR, obtained from the Chernoff inequality at a given confidence level (evar_beta). The EVaR can be represented by using the concept of relative entropy.

drawdown_at_riskfloat

Historical Drawdown at Risk. It is the maximum drawdown at a given confidence level (drawdown_at_risk_beta).

cdarfloat

Historical CDaR (Conditional Drawdown at Risk) at a given confidence level (cdar_beta).

max_drawdownfloat

Maximum Drawdown.

average_drawdownfloat

Average Drawdown.

edarfloat

EDaR (Entropic Drawdown at Risk). It is a coherent risk measure which is an upper bound for the Drawdown at Risk and the CDaR, obtained from the Chernoff inequality at a given confidence level (edar_beta). The EDaR can be represented by using the concept of relative entropy.

ulcer_indexfloat

Ulcer Index

gini_mean_differencefloat

Gini Mean Difference (GMD). It is the expected absolute difference between two realizations. The GMD is a superior measure of variability for non-normal distribution than the variance. It can be used to form necessary conditions for second-degree stochastic dominance, while the variance cannot.

mean_absolute_deviation_ratiofloat

Mean Absolute Deviation ratio. It is the excess mean (mean - risk_free_rate) divided by the MaD.

first_lower_partial_moment_ratiofloat

First Lower Partial Moment ratio. It is the excess mean (mean - risk_free_rate) divided by the First Lower Partial Moment.

sharpe_ratiofloat

Sharpe ratio. It is the excess mean (mean - risk_free_rate) divided by the standard-deviation.

annualized_sharpe_ratiofloat

Sharpe ratio annualized by \(sharpe\_ratio \times \sqrt{annualization\_factor}\).

sortino_ratiofloat

Sortino ratio. It is the excess mean (mean - risk_free_rate) divided by the semi standard-deviation.

annualized_sortino_ratiofloat

Sortino ratio annualized by \(sortino\_ratio \times \sqrt{annualization\_factor}\).

value_at_risk_ratiofloat

VaR ratio. It is the excess mean (mean - risk_free_rate) divided by the Value at Risk (VaR).

cvar_ratiofloat

CVaR ratio. It is the excess mean (mean - risk_free_rate) divided by the Conditional Value at Risk (CVaR).

entropic_risk_measure_ratiofloat

Entropic risk measure ratio. It is the excess mean (mean - risk_free_rate) divided by the Entropic risk measure.

evar_ratiofloat

EVaR ratio. It is the excess mean (mean - risk_free_rate) divided by the EVaR (Entropic Value at Risk).

worst_realization_ratiofloat

Worst Realization ratio. It is the excess mean (mean - risk_free_rate) divided by the Worst Realization (worst return).

drawdown_at_risk_ratiofloat

Drawdown at Risk ratio. It is the excess mean (mean - risk_free_rate) divided by the drawdown at risk.

cdar_ratiofloat

CDaR ratio. It is the excess mean (mean - risk_free_rate) divided by the CDaR (conditional drawdown at risk).

calmar_ratiofloat

Calmar ratio. It is the excess mean (mean - risk_free_rate) divided by the Maximum Drawdown.

average_drawdown_ratiofloat

Average Drawdown ratio. It is the excess mean (mean - risk_free_rate) divided by the Average Drawdown.

edar_ratiofloat

EDaR ratio. It is the excess mean (mean - risk_free_rate) divided by the EDaR (Entropic Drawdown at Risk).

ulcer_index_ratiofloat

Ulcer Index ratio. It is the excess mean (mean - risk_free_rate) divided by the Ulcer Index.

gini_mean_difference_ratiofloat

Gini Mean Difference ratio. It is the excess mean (mean - risk_free_rate) divided by the Gini Mean Difference.

Methods

append(portfolio)	Append a Portfolio to the Portfolio list.
clear()	Clear all measures, fitness, cumulative returns and drawdowns in slots.
contribution(measure[, spacing, to_df])	Compute the contribution of each asset to a given measure for each portfolio.
copy()	Copy the Portfolio attributes without its measures values.
dominates(other[, idx])	Portfolio domination.
get_measure(measure)	Returns the value of a given measure.
plot_composition()	Plot the Portfolio composition.
plot_contribution(measure[, spacing])	Plot the contribution of each asset to a given measure.
plot_cumulative_returns([log_scale, idx])	Plot the Portfolio cumulative returns.
plot_drawdowns([idx])	Plot the Portfolio drawdowns.
plot_long_short_exposure()	Plot long, short, net and gross exposure per observation.
plot_returns([idx])	Plot the Portfolio returns.
plot_returns_distribution([percentile_cutoff])	Plot the Portfolio returns distribution using Gaussian KDE.
plot_rolling_measure([measure, window])	Plot the measure over a rolling window.
plot_weights_per_observation()	Plot portfolio weights per observation as a stacked-area chart.
predicted_attribution(factor_model[, ...])	Ex-ante (predicted) factor attribution for the last portfolio.
realized_attribution(factor_model[, ...])	Realized (ex-post) factor attribution aggregated over all periods.
rolling_measure([measure, window])	Compute the measure over a rolling window.
rolling_realized_attribution(factor_model[, ...])	Rolling realized (ex-post) factor attribution over all periods.
summary([formatted])	Portfolio summary of all its measures.

property annualization_factor

Portfolio annualization factor.

property annualized_factor

Deprecated alias for annualization_factor.

append(portfolio)

Append a Portfolio to the Portfolio list.

Parameters:

portfolioPortfolio

The Portfolio to append.

property assets

List of assets names in each Portfolio.

clear()

Clear all measures, fitness, cumulative returns and drawdowns in slots.

property composition

DataFrame of the Portfolio composition.

contribution(measure, spacing=None, to_df=True)

Compute the contribution of each asset to a given measure for each portfolio.

Parameters:

measureMeasure

The measure used for the contribution computation.

spacingfloat, optional

Spacing “h” of the finite difference: \(contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}\)

to_dfbool, default=False

If this is set to True, a DataFrame with asset names in index and portfolio names in columns is returned, otherwise a list of numpy array is returned. When a DataFrame is returned, the assets with zero weights are removed.

Returns:

valueslist of numpy array of shape (n_assets,) for each portfolio or a DataFrame

The measure contribution of each asset for each portfolio.

copy()

Copy the Portfolio attributes without its measures values.

cumulative_returns

Portfolio cumulative returns array. Non-compounded (arithmetic) cumulative returns start at 0. Compounded (geometric) cumulative returns are expressed as a wealth index, starting at 1.0 (i.e., the value of $1 invested).

property cumulative_returns_df

Portfolio cumulative returns Series. Non-compounded (arithmetic) cumulative returns start at 0. Compounded (geometric) cumulative returns are expressed as a wealth index, starting at 1.0 (i.e., the value of $1 invested).

dominates(other, idx=None)

Portfolio domination.

Returns true if each objective of the current portfolio fitness is not strictly worse than the corresponding objective of the other portfolio fitness and at least one objective is strictly better.

Parameters:

otherBasePortfolio

The other portfolio.

idxslice | array, optional

Indexes or slice indicating on which objectives the domination is performed. The default (None) is to use all objectives.

Returns:

valuebool

Returns True if the Portfolio dominates the other one.

drawdowns

Portfolio drawdowns array.

property drawdowns_df

Portfolio drawdowns Series.

property failed_portfolios

Return the list of FailedPortfolio in the multi-period portfolio.

property fallback_portfolios

Return the list of portfolios in the multi-period portfolio that used a fallback (i.e., have a non-None fallback_chain). This includes FailedPortfolio instances when fallbacks were attempted.

fitness

Portfolio fitness.

property fitness_measures

Portfolio fitness measures.

get_measure(measure)

Returns the value of a given measure.

Parameters:

measurePerfMeasure | RiskMeasure | ExtraRiskMeasure | RatioMeasure

The input measure.

Returns:

valuefloat

The measure value.

property long_short_exposure

DataFrame of long, short, net and gross exposure per observation.

The long exposure is the sum of positive weights. The short exposure is the sum of negative weights. Net exposure is the sum of all weights and gross exposure is the sum of absolute weights.

property measures_df

DataFrame of all measures.

property n_failed_portfolios

Number of FailedPortfolio in the multi-period portfolio.

property n_fallback_portfolios

Number of portfolios in the multi-period portfolio with a fallback.

property n_observations

Number of observations.

plot_composition()

Plot the Portfolio composition.

Returns:

plotFigure

Returns the plot Figure object.

plot_contribution(measure, spacing=None)

Plot the contribution of each asset to a given measure.

Parameters:

measureMeasure

The measure used for the contribution computation.

spacingfloat, optional

Spacing “h” of the finite difference: \(contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}\)

Returns:

plotFigure

The plotly Figure of assets contribution to the measure.

plot_cumulative_returns(log_scale=False, idx=None)

Plot the Portfolio cumulative returns. Non-compounded (arithmetic) cumulative returns start at 0. Compounded (geometric) cumulative returns are expressed as a wealth index, starting at 1.0 (i.e., the value of $1 invested).

Parameters:

log_scalebool, default=False

If this is set to True, the cumulative returns are displayed with a logarithm scale on the y-axis. The cumulative returns must be compounded otherwise an exception is raised.

idxslice | array, optional

Indexes or slice of the observations to plot. The default (None) is to plot all observations.

Returns:

plotFigure

Returns the plot Figure object.

plot_drawdowns(idx=None)

Plot the Portfolio drawdowns.

Parameters:

idxslice | array, optional

Indexes or slice of the observations to plot. The default (None) is to plot all observations.

Returns:

plotFigure

Returns the plot Figure object.

plot_long_short_exposure()

Plot long, short, net and gross exposure per observation.

Returns:

plotFigure

Returns the plot Figure object.

plot_returns(idx=None)

Plot the Portfolio returns.

Parameters:

idxslice | array, optional

Indexes or slice of the observations to plot. The default (None) is to plot all observations.

Returns:

plotFigure

Returns the plot Figure object

plot_returns_distribution(percentile_cutoff=None)

Plot the Portfolio returns distribution using Gaussian KDE.

Parameters:

percentile_cutofffloat, default=None

Percentile cutoff for tail truncation (percentile), in percent. If a float p is provided, the distribution support is truncated at the p-th and (100 - p)-th percentiles. If None, no truncation is applied (uses full min/max of returns).

Returns:

plotFigure

Returns the plot Figure object

plot_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window.

Parameters:

measureMeasure, default = RatioMeasure.SHARPE_RATIO

The measure.

windowint, default=30

The window size.

Returns:

plotFigure

Returns the plot Figure object

plot_weights_per_observation()

Plot portfolio weights per observation as a stacked-area chart.

This shows the composition of the portfolio over time, with each asset’s weight stacked to illustrate how allocations shift.

Returns:

plotFigure

Returns the plot Figure object.

property portfolios

List of portfolios composing the mutli-period portfolio.

predicted_attribution(factor_model, compute_asset_breakdowns=True)

Ex-ante (predicted) factor attribution for the last portfolio.

Returns the predicted attribution for the most recent (last) portfolio in the walk-forward sequence, which represents the current allocation.

The last portfolio’s weights are aligned to factor_model.asset_names: assets not in the portfolio receive zero weight, and assets not in the factor model raise an error.

Predicted attribution uses the factor model’s latest forecast estimates (loading_matrix, factor_covariance, idio_covariance, factor_mu, idio_mu), so no observation alignment is performed.

The annualization scaling uses self.annualization_factor.

See predicted_factor_attribution for the full mathematical description.

Parameters:

factor_modelFactorModel

Factor model whose latest forecast estimates are used. Every asset held by the last portfolio must appear in factor_model.asset_names.

compute_asset_breakdownsbool, default=True

If True, compute per-asset systematic/idiosyncratic decomposition. Set to False for faster computation when only portfolio-level results are needed.

Returns:

attributionAttribution

Component-level, factor-level, and optionally asset-level attribution results for the last portfolio.

Raises:

ValueError

If the multi-period portfolio is empty, the last portfolio is a FailedPortfolio, or it holds assets not covered by the factor model.

property previous_weights_dict

Dictionary mapping Portfolio name to its previous asset weight allocation.

realized_attribution(factor_model, compute_asset_breakdowns=True, compute_uncertainty=True)

Realized (ex-post) factor attribution aggregated over all periods.

Builds a time-varying weight matrix from the non-failed child portfolios and computes a single realized attribution over the full walk-forward observation window.

Each child portfolio’s static weight vector is broadcast across its observations. Failed portfolios are skipped (their observations and returns are excluded).

Weights are aligned to factor_model.asset_names: assets not in a given portfolio receive zero weight, and assets not in the factor model raise an error.

Realized attribution is computed on the overlapping observation window between the multi-period portfolio and the factor model. Portfolio observations outside the factor model window, commonly caused by factor-model warmup or exposure lag, are excluded. Missing portfolio observations inside the overlapping window raise ValueError. Time-varying exposures follow the as-of indexing convention described in realized_factor_attribution: when exposure_lag > 0, exposures known at observation \(t-\ell\) are aligned with returns at observation \(t\).

The annualization scaling uses self.annualization_factor.

See realized_factor_attribution for the full mathematical description.

Parameters:

factor_modelFactorModel

Factor model containing time-varying fields (factor_returns, exposures, idio_returns) that overlap with the observation periods of non-failed child portfolios. Every asset held by any child portfolio must appear in factor_model.asset_names.

compute_asset_breakdownsbool, default=True

If True, compute per-asset systematic/idiosyncratic attribution. Set to False for faster computation when only portfolio-level results are needed.

compute_uncertaintybool, default=True

If True, compute attribution uncertainty (standard errors on the factor and idiosyncratic mean-return split).

Returns:

attributionAttribution

Component-level, factor-level, and optionally asset-level attribution results aggregated over all non-failed periods.

Raises:

ValueError

If the multi-period portfolio is empty, all child portfolios are failed, any child portfolio holds assets not covered by the factor model, no portfolio observations overlap with the factor model, or portfolio observations are missing inside the overlapping window.

property returns_df

Portfolio returns DataFrame.

rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window.

Parameters:

measureMeasure, default=RatioMeasure.SHARPE_RATIO

The measure. The default measure is the Sharpe Ratio.

windowint, default=30

The window size. The default value is 30 observations.

Returns:

seriespandas Series

The rolling measure Series.

rolling_realized_attribution(factor_model, window_size=60, step=21, compute_asset_breakdowns=True, compute_asset_factor_contribs=False, compute_uncertainty=True)

Rolling realized (ex-post) factor attribution over all periods.

Builds a time-varying weight matrix from the non-failed child portfolios and computes rolling realized attribution over the full walk-forward observation window.

Each child portfolio’s static weight vector is broadcast across its observations. Failed portfolios are skipped.

Rolling realized attribution is computed on the overlapping observation window between the multi-period portfolio and the factor model. Portfolio observations outside the factor model window, commonly caused by factor-model warmup or exposure lag, are excluded. Missing portfolio observations inside the overlapping window raise ValueError. Time-varying exposures follow the as-of indexing convention described in rolling_realized_factor_attribution.

See rolling_realized_factor_attribution for the full mathematical description.

Parameters:

factor_modelFactorModel

Factor model containing time-varying fields that overlap with the observation periods of non-failed child portfolios.

window_sizeint, default=60

Number of effective return periods in each rolling window.

stepint, default=21

Number of observations to advance between consecutive windows. The default of 21 produces approximately monthly output for daily data.

compute_asset_breakdownsbool, default=True

If True, compute per-asset attribution for each window.

compute_asset_factor_contribsbool, default=False

If True, compute asset-factor matrix for each window.

compute_uncertaintybool, default=True

If True, compute per-window attribution uncertainty.

Returns:

attributionAttribution

Rolling attribution results with an additional leading dimension for the number of windows.

Raises:

ValueError

If the multi-period portfolio is empty, all child portfolios are failed, any child portfolio holds assets not covered by the factor model, no portfolio observations overlap with the factor model, or window_size exceeds the number of overlapping observations.

property sample_weight

Observations sample weights.

summary(formatted=True)

Portfolio summary of all its measures.

Parameters:

formattedbool, default=True

If this is set to True, the measures are formatted into rounded string with units.

Returns:

summaryseries

Portfolio summary of all its measures.

property weights_dict

Dictionary mapping each Portfolio name to its asset weight allocation.

property weights_per_observation

DataFrame of the Portfolio weights per observation.