skfolio.distance.CovarianceDistance#

class skfolio.distance.CovarianceDistance(covariance_estimator=None, absolute=False, power=1)[source]#

Covariance Distance estimator.

The codependence is computed from the correlation matrix of a chosen covariance estimator to which is applied a power and/or absolute transformation. This codependence is then used to compute the distance matrix. Some widely used distances are:

Standard angular distance = \(\sqrt{0.5 \times (1 - corr)}\)

Absolute angular distance = \(\sqrt{1 - |corr|}\)

Squared angular distance = \(\sqrt{1 - corr^2}\)

Parameters:

covariance_estimatorBaseCovariance or {“precomputed”}, optional: Covariance estimator. The default (None) is to use GerberCovariance. With "precomputed", fit converts a covariance matrix directly. NaN diagonal entries exclude assets, whose output rows and columns stay NaN. The available block must be symmetric and positive semidefinite, with strictly positive variances. Validation allows float64 roundoff of 64 * eps * n_available_assets in the implied correlation. No repair is applied.
absolutebool, default=False: If this is set to True, the absolute transformation is applied to the correlation matrix. The default is False.
powerfloat, default=1: Exponent of the power transformation applied to the correlation matrix. Must be finite and strictly positive, with an integer value when absolute=False. The default value is 1.

Attributes:

codependence_ndarray of shape (n_assets, n_assets): Codependence matrix.
distance_ndarray of shape (n_assets, n_assets): Distance matrix.
covariance_estimator_BaseCovariance or None: Fitted covariance estimator, or None in precomputed mode.
n_features_in_int: Number of assets seen during fit.
feature_names_in_ndarray of shape (n_features_in_,): Names of assets seen during fit. Defined only when X has assets names that are all strings.

Methods

`fit`(X[, y])	Fit the Covariance Distance estimator.
`get_metadata_routing`()	Get metadata routing for this estimator.
`get_params`([deep])	Get parameters for this estimator.
`partial_fit`(X[, y])	Update covariance from new returns and recompute the distance.
`set_params`(**params)	Set the parameters of this estimator.

Notes

Both learned and precomputed covariances must be symmetric and positive semidefinite within numerical tolerance. Singular covariances are accepted. Invalid covariances raise ValueError. For covariance estimators supporting nearest, keep nearest=True to repair their output before conversion. Precomputed covariance can be repaired explicitly with cov_nearest.

References

[1]

“Building Diversified Portfolios that Outperform Out-of-Sample”, López de Prado, Journal of Portfolio Management (2016)

fit(X, y=None, **fit_params)[source]#

Fit the Covariance Distance estimator.

Parameters:

Xarray-like of shape (n_observations, n_assets) or (n_assets, n_assets): Returns in learned mode, or a covariance matrix in precomputed mode.
yIgnored: Not used, present for API consistency by convention.
**fit_paramsdict: Metadata routed to the covariance estimator.

Returns:

selfCovarianceDistance: Fitted estimator.

get_metadata_routing()[source]#

Get metadata routing for this estimator.

Routes metadata to the corresponding fit or partial_fit method of covariance_estimator.

Returns:

routingMetadataRouter: Metadata routing configuration.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

partial_fit(X, y=None, **fit_params)[source]#

Update covariance from new returns and recompute the distance.

The covariance estimator must implement partial_fit. The first call also uses the child’s partial_fit. With covariance_estimator="precomputed", call fit with the updated covariance matrix instead.

Parameters:

Xarray-like of shape (n_observations, n_assets): New asset returns with the same full schema as previous calls.
yIgnored: Not used, present for API consistency by convention.
**fit_paramsdict: Metadata routed to the covariance estimator’s partial_fit.

Returns:

selfCovarianceDistance: Updated estimator.

Raises:

TypeError: If the covariance estimator does not implement partial_fit or covariance_estimator="precomputed".

property requires_covariance_input#: Whether covariance_estimator is set to "precomputed".

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.