skfolio.portfolio.Portfolio

class skfolio.portfolio.Portfolio(X, weights, previous_weights=None, transaction_costs=None, management_fees=None, risk_free_rate=0, name=None, tag=None, annualized_factor=252, fitness_measures=None, compounded=False, 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)

Portfolio class.

Portfolio is returned by the predict method of Optimization estimators. It is homogenous to the convex optimization problems meaning that Portfolio is the dot product of the assets weights with the assets returns.

Parameters:

Xarray-like of shape (n_observations, n_assets)

Price returns of the assets. If X is a DataFrame or another array containers that implements ‘columns’ and ‘index’, the columns will be considered as assets names and the indices will be considered as observations. Otherwise, we use ["x0", "x1", ..., "x(n_assets - 1)"] as asset names and [0, 1, ..., n_observations] as observations.

weightsarray-like of shape (n_assets,) | dict[str, float]

Portfolio weights. If a dictionary is provided, its (key/value) pair must be the (asset name/asset weight) and X must be a DataFrame with assets names in columns.

transaction_costsfloat | dict[str, float] | array-like of shape (n_assets, ), optional

Linear transaction costs of the assets. The Portfolio total transaction cost is:

\[total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|\]

with \(c_{i}\) the transaction cost of asset i, \(w_{i}\) its weight and \(w\_prev_{i}\) its previous weight (defined in previous_weights). The float \(total\_cost\) is used in the portfolio returns:

\[ptf\_returns = R \cdot w - total\_cost\]

with \(R\) the matrix af assets returns and \(w\) the vector of assets weights.

If a float is provided, it is applied to each asset. If a dictionary is provided, its (key/value) pair must be the (asset name/asset weight) and X must be a DataFrame with assets names in columns. The default (None) means no transaction costs.

Warning

To be homogenous to the optimization problems, the periodicity of the transaction costs needs to be homogenous to the periodicity of the returns X. For example, if X is composed of daily returns, the transaction_costs need to be expressed in daily transaction costs.

management_feesfloat | dict[str, float] | array-like of shape (n_assets, ), optional

Linear management fees of the assets. The Portfolio total management cost is:

\[total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}\]

with \(f_{i}\) the management fee of asset i and \(w_{i}\) its weight. The float \(total\_fee\) is used in the portfolio returns:

\[ptf\_returns = R \cdot w - total\_fee\]

with \(R\) the matrix af assets returns and \(w\) the vector of assets weights.

If a float is provided, it is applied to each asset. If a dictionary is provided, its (key/value) pair must be the (asset name/asset weight) and X must be a DataFrame with assets names in columns. The default (None) means no management fees.

Warning

To be homogenous to the optimization problems, the periodicity of the management fees needs to be homogenous to the periodicity of the returns X. For example, if X is composed of daily returns, the management_fees need to be expressed in daily fees.

previous_weightsfloat | dict[str, float] | array-like of shape (n_assets, ), optional

Previous portfolio weights. Previous weights are used to compute the total portfolio cost. If transaction_costs is 0, previous_weights will have no impact. If a float is provided, it is applied to each asset. If a dictionary is provided, its (key/value) pair must be the (asset name/asset previous weight) and X must be a DataFrame with assets names in columns. The default (None) means no previous weights.

namestr, optional

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

tagstr, optional

Tag given to the 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]

annualized_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.

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.

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

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.
copy()	Copy the Portfolio attributes without its measures values.
dominates(other[, idx])	Portfolio domination.
expected_returns_from_assets(...)	Compute the Portfolio expected returns from the assets expected returns, weights, management costs and transaction fees.
get_measure(measure)	Returns the value of a given measure.
get_weight(asset)	Get the weight of a given asset.
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_returns([idx])	Plot the Portfolio returns
plot_rolling_measure([measure, window])	Plot the measure over a rolling window.
rolling_measure([measure, window])	Compute the measure over a rolling window.
summary([formatted])	Portfolio summary of all its measures.
variance_from_assets(assets_covariance)	Compute the Portfolio variance expectation from the assets covariance and weights.

property annualized_factor

Portfolio annualized factor.

clear()

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

property composition

DataFrame of the Portfolio composition.

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

Compute 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}\)

to_dfbool, default=False

If set to True, a DataFrame with asset names in index is returned, otherwise a numpy array is returned. When a DataFrame is returned, the values are sorted in descending order and assets with zero weights are removed.

Returns:

valuesnumpy array of shape (n_assets,) or DataFrame

The measure contribution of each asset.

copy()

Copy the Portfolio attributes without its measures values.

cumulative_returns

Portfolio cumulative returns array.

property cumulative_returns_df

Portfolio cumulative returns Series.

property diversification

Weighted average of volatility divided by the portfolio volatility.

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 effective_number_assets

Computes the effective number of assets, defined as the inverse of the Herfindahl index [1]:

\[N_{eff} = \frac{1}{\Vert w \Vert_{2}^{2}}\]

It quantifies portfolio concentration, with a higher value indicating a more diversified portfolio.

Returns:

valuefloat

Effective number of assets.

References

[1]

“Banking and Financial Institutions Law in a Nutshell”. Lovett, William Anthony (1988)

expected_returns_from_assets(assets_expected_returns)

Compute the Portfolio expected returns from the assets expected returns, weights, management costs and transaction fees.

Parameters:

assets_expected_returnsndarray of shape (n_assets,)

The vector of assets expected returns.

Returns:

valuefloat

The Portfolio expected returns.

fitness

The 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.

get_weight(asset)

Get the weight of a given asset.

Parameters:

assetstr

Name of the asset.

Returns:

weightfloat

Weight of the asset.

property measures_df

DataFrame of all measures.

property n_observations

Number of observations

nonzero_assets

Invested asset \(abs(weights) > 0.001%\)

nonzero_assets_index

Indices of invested asset \(abs(weights) > 0.001%\)

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 cumulative returns start at 0. Compounded cumulative returns are rescaled to start at 1000.

Parameters:

log_scalebool, default=False

If this is set to True, the cumulative returns are displayed with a logarithm scale on the y-axis and rebased at 1000. 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_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_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window.

Parameters:

measurect.Measure, default = RatioMeasure.SHARPE_RATIO

The measure.

windowint, default=30

The window size.

Returns:

plotFigure

Returns the plot Figure object

property returns_df

Portfolio returns DataFrame.

rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window.

Parameters:

measurect.Measure, 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.

property sric

Sharpe Ratio Information Criterion (SRIC).

It is an unbiased estimator of the Sharpe Ratio adjusting for both sources of bias which are noise fit and estimation error [1].

References

[1]

“Noise Fit, Estimation Error and a Sharpe Information Criterion”, Dirk Paulsen (2019)

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.

variance_from_assets(assets_covariance)

Compute the Portfolio variance expectation from the assets covariance and weights.

Parameters:

assets_covariancendarray of shape (n_assets,n_assets)

The matrix of assets covariance expectation.

Returns:

valuefloat

The Portfolio variance from the assets covariance.

property weights_per_observation

DataFrame of the Portfolio weights per observation.