Migration Guide#

skfolio follows semantic versioning. The public API remains backward compatible within a major series. Deprecated functionality raises a FutureWarning and is removed in the next major release.

This page documents the changes required to upgrade between major versions.

Migrating to 1.0#

Version 1.0 introduces the stable public API. The parameters and aliases deprecated during the 0.x series are removed in this release.

Exponentially Weighted Moments#

EWMu and EWCovariance no longer accept alpha. Use half_life, the number of observations for a weight to decay to 50%.

Before:

EWMu(alpha=0.2)
EWCovariance(alpha=0.2)

After:

EWMu(half_life=3.11)
EWCovariance(half_life=3.11)

The half-life equivalent of a given alpha is

\[\text{half-life} = \frac{-1}{\log_2(1 - \alpha)}\]

For example, alpha=0.2 corresponds to a half_life of approximately \(3.11\) and alpha=0.02 to \(34.31\). The decay factor is \(\lambda = 2^{-1/\text{half-life}}\), computed by half_life_to_decay_factor.

Passing alpha raises a TypeError.

Walk-Forward Cross-Validation#

WalkForward no longer accepts expend_train. Use expand_train, which has identical behavior.

Before:

WalkForward(test_size=60, train_size=252, expend_train=True)

After:

WalkForward(test_size=60, train_size=252, expand_train=True)

Factor Models#

The FactorModel prior estimator is replaced by TimeSeriesFactorModel, and factors is now a keyword-only argument of fit.

Before:

from skfolio.optimization import MeanRisk
from skfolio.prior import FactorModel

model = MeanRisk(prior_estimator=FactorModel())
model.fit(X_train, y_train)

After:

from skfolio.optimization import MeanRisk
from skfolio.prior import TimeSeriesFactorModel

model = MeanRisk(prior_estimator=TimeSeriesFactorModel())
model.fit(X_train, factors=factors_train)

Warning

FactorModel now refers to a different object: the fitted factor model container exposed on factor_model, holding the loading matrix, the factor and idiosyncratic moments, and the realized factor returns. The import therefore still resolves, and estimator arguments passed to FactorModel raise a TypeError for unexpected keyword arguments rather than an ImportError.

CharacteristicsFactorModel provides a cross-sectional alternative, fitted from point-in-time asset characteristics rather than factor return time series. See Factor Models.

Uncertainty Sets#

UncertaintySet now describes a general norm-ball rather than an ellipsoid, which allows box and diamond sets to use the same representation. The ellipsoid is the \(p = 2\) case.

The field names changed as follows:

Before

After

Description

k

radius

Size \(\kappa\) of the normalized uncertainty ball.

sigma

geometry

Linear map \(L\) with \(S = L L^{T}\) for an ellipsoid with shape matrix \(S\). May be low-rank.

not applicable

norm

Norm \(p\) selecting the shape, defaulting to \(2\) for an ellipsoid.

This only affects code that constructs an UncertaintySet directly or reads the fitted uncertainty_set_ attribute. Passing an uncertainty set estimator to MeanRisk is unchanged.

Two factor-model estimators are added: OrthogonalMuUncertaintySet and OrthogonalCovarianceUncertaintySet. See Uncertainty Set.

Scheduled for Removal in 2.0#

The following remain available throughout 1.x and raise a FutureWarning: