skfolio.prior.ReturnDistribution

class skfolio.prior.ReturnDistribution(mu, covariance, returns, sample_weight=None, factor_model=None)

Return distribution estimated by a prior estimator.

Prior estimators always return the full universe (all assets that have ever been part of the investment universe). Assets that are not investable at the current point in time (e.g. delisted, not yet listed, warm-up period) are represented with NaN in mu, covariance, and/or returns.

An asset is considered investable when both mu[i] and covariance[i, i] are finite. The investable_mask property infers this condition on first access and reconciles warm-up periods across independent moment estimators.

NaN values in returns are restricted to the columns of non-investable assets. Prior estimators resolve missing observations of investable assets into finite scenario values (for example, EmpiricalPrior zero-fills them), so that investable_subset returns fully finite arrays.

Use investable_subset before passing the distribution to downstream routines that operate only on the investable universe.

Attributes:

mundarray of shape (n_assets,)

Estimation of expected asset returns.

covariancendarray of shape (n_assets, n_assets)

Estimation of the assets covariance matrix.

returnsndarray of shape (n_observations, n_assets)

Estimation of the assets returns.

sample_weightndarray of shape (n_observations,), optional

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

factor_modelFactorModel, optional

Factor model decomposition and diagnostics. The default is None.

Methods

investable_subset([slim])

Return a ReturnDistribution restricted to investable assets.

property covariance_sqrt

Covariance square root for SOC-based optimization.

When a FactorModel is available, delegates to FactorModel.covariance_sqrt to exploit the low-rank factor structure. Otherwise, falls back to the Cholesky decomposition of covariance.

When non-investable assets are represented with NaN entries and no factor model is available, callers should apply investable_subset first.

Returns:

CovarianceSqrt

property investable_mask

Boolean mask where True marks investable assets.

The mask is inferred as the intersection of finite mu values and a finite diagonal in covariance. Returns None when all assets are investable.

Raises:

ValueError

If no asset is investable (all NaN in mu and/or covariance).

investable_subset(slim=False)

Return a ReturnDistribution restricted to investable assets.

Parameters:

slimbool, default=False

When True, heavy diagnostic fields on the nested FactorModel (e.g. exposures, idio_returns, idio_variances, benchmark_weights) are set to None to reduce memory usage. This is typically used by optimization estimators that only need loading_matrix, covariance, and return series.

Returns:

subsetReturnDistribution

Distribution over the investable assets only. If all assets are already investable and slim=False, self is returned.

property n_assets

Total number of assets in the full universe.

property n_investable_assets

Number of investable assets.