skfolio 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

skfolio/moments/covariance/_detone_covariance.py

@@ -0,0 +1,158 @@
+"""Covariance Detoning Estimators."""
+
+# Copyright (c) 2023
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+# Implementation derived from:
+# scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
+# Grisel Licensed under BSD 3 clause.
+
+import numpy as np
+import numpy.typing as npt
+import sklearn.utils.metadata_routing as skm
+
+from skfolio.moments.covariance._base import BaseCovariance
+from skfolio.moments.covariance._empirical_covariance import EmpiricalCovariance
+from skfolio.utils.stats import corr_to_cov, cov_to_corr
+from skfolio.utils.tools import check_estimator
+
+
+class DetoneCovariance(BaseCovariance):
+    """Covariance Detoning estimator.
+
+    Financial covariance matrices usually incorporate a market component corresponding
+    to the first eigenvectors [1]_.
+    For some applications like clustering, removing the market component (loud tone)
+    allow a greater portion of the covariance to be explained by components that affect
+    specific subsets of the securities.
+
+    Parameters
+    ----------
+    covariance_estimator : BaseCovariance, optional
+        :ref:`Covariance estimator <covariance_estimator>` to estimate the covariance
+        matrix prior detoning.
+        The default (`None`) is to use :class:`~skfolio.moments.EmpiricalCovariance`.
+
+    n_markets : int, default=1
+        Number of eigenvectors related to the market.
+        The default value is `1`.
+
+    nearest : bool, default=True
+        If this is set to True, the covariance is replaced by the nearest covariance
+        matrix that is positive definite and with a Cholesky decomposition than can be
+        computed. The variance is left unchanged.
+        A covariance matrix that is not positive definite often occurs in high
+        dimensional problems. It can be due to multicollinearity, floating-point
+        inaccuracies, or when the number of observations is smaller than the number of
+        assets. For more details, see :func:`~skfolio.utils.stats.cov_nearest`.
+        The default is `True`.
+
+    higham : bool, default=False
+        If this is set to True, the Higham & Nick (2002) algorithm is used to find the
+        nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
+        above zeros (1e-13). The default is `False` and use the clipping method as the
+        Higham & Nick algorithm can be slow for large datasets.
+
+    higham_max_iteration : int, default=100
+        Maximum number of iteration of the Higham & Nick (2002) algorithm.
+        The default value is `100`.
+
+    Attributes
+    ----------
+    covariance_ : ndarray of shape (n_assets, n_assets)
+        Estimated covariance.
+
+    covariance_estimator_ : BaseCovariance
+        Fitted `covariance_estimator`.
+
+    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.
+
+    References
+    ----------
+    .. [1]  "Machine Learning for Asset Managers".
+        Elements in Quantitative Finance.
+        Lòpez de Prado (2020).
+    """
+
+    covariance_estimator_: BaseCovariance
+
+    def __init__(
+        self,
+        covariance_estimator: BaseCovariance | None = None,
+        n_markets: float = 1,
+        nearest: bool = True,
+        higham: bool = False,
+        higham_max_iteration: int = 100,
+    ):
+        super().__init__(
+            nearest=nearest,
+            higham=higham,
+            higham_max_iteration=higham_max_iteration,
+        )
+        self.covariance_estimator = covariance_estimator
+        self.n_markets = n_markets
+
+    def get_metadata_routing(self):
+        # noinspection PyTypeChecker
+        router = skm.MetadataRouter(owner=self.__class__.__name__).add(
+            covariance_estimator=self.covariance_estimator,
+            method_mapping=skm.MethodMapping().add(caller="fit", callee="fit"),
+        )
+        return router
+
+    def fit(self, X: npt.ArrayLike, y=None, **fit_params) -> "DetoneCovariance":
+        """Fit the Covariance Detoning estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+          Price returns of the assets.
+
+        y : Ignored
+           Not used, present for API consistency by convention.
+
+        **fit_params : dict
+            Parameters to pass to the underlying estimators.
+            Only available if `enable_metadata_routing=True`, which can be
+            set by using ``sklearn.set_config(enable_metadata_routing=True)``.
+            See :ref:`Metadata Routing User Guide <metadata_routing>` for
+            more details.
+
+        Returns
+        -------
+        self : DetoneCovariance
+           Fitted estimator.
+        """
+        routed_params = skm.process_routing(self, "fit", **fit_params)
+
+        # fitting estimators
+        self.covariance_estimator_ = check_estimator(
+            self.covariance_estimator,
+            default=EmpiricalCovariance(),
+            check_type=BaseCovariance,
+        )
+        # noinspection PyArgumentList
+        self.covariance_estimator_.fit(X, y, **routed_params.covariance_estimator.fit)
+
+        # we validate and convert to numpy after all models have been fitted to keep
+        # features names information.
+        _ = self._validate_data(X)
+        corr, std = cov_to_corr(self.covariance_estimator_.covariance_)
+        e_val, e_vec = np.linalg.eigh(corr)
+        indices = e_val.argsort()[::-1]
+        e_val, e_vec = e_val[indices], e_vec[:, indices]
+        # market eigenvalues and eigenvectors
+        market_e_val, market_e_vec = e_val[: self.n_markets], e_vec[:, : self.n_markets]
+        # market correlation
+        market_corr = market_e_vec @ np.diag(market_e_val) @ market_e_vec.T
+        # Removing the market correlation
+        corr -= market_corr
+        corr, _ = cov_to_corr(corr)
+        covariance = corr_to_cov(corr, std)
+        self._set_covariance(covariance)
+        return self

skfolio/moments/covariance/_empirical_covariance.py

@@ -0,0 +1,100 @@
+"""Empirical Covariance Estimators."""
+
+# Copyright (c) 2023
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+# Implementation derived from:
+# scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
+# Grisel Licensed under BSD 3 clause.
+
+import numpy as np
+import numpy.typing as npt
+
+from skfolio.moments.covariance._base import BaseCovariance
+
+
+class EmpiricalCovariance(BaseCovariance):
+    """Empirical Covariance estimator.
+
+    Parameters
+    ----------
+    window_size : int, optional
+        Window size. The model is fitted on the last `window_size` observations.
+        The default (`None`) is to use all the data.
+
+    ddof : int, default=1
+        Normalization is by `(n_observations - ddof)`.
+        Note that `ddof=1` will return the unbiased estimate, and `ddof=0`
+        will return the simple average. The default value is `1`.
+
+    nearest : bool, default=True
+        If this is set to True, the covariance is replaced by the nearest covariance
+        matrix that is positive definite and with a Cholesky decomposition than can be
+        computed. The variance is left unchanged.
+        A covariance matrix that is not positive definite often occurs in high
+        dimensional problems. It can be due to multicollinearity, floating-point
+        inaccuracies, or when the number of observations is smaller than the number of
+        assets. For more details, see :func:`~skfolio.utils.stats.cov_nearest`.
+        The default is `True`.
+
+    higham : bool, default=False
+        If this is set to True, the Higham & Nick (2002) algorithm is used to find the
+        nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
+        above zeros (1e-13). The default is `False` and use the clipping method as the
+        Higham & Nick algorithm can be slow for large datasets.
+
+    higham_max_iteration : int, default=100
+        Maximum number of iteration of the Higham & Nick (2002) algorithm.
+        The default value is `100`.
+
+    Attributes
+    ----------
+    covariance_ : ndarray of shape (n_assets, n_assets)
+        Estimated covariance matrix.
+
+    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.
+    """
+
+    def __init__(
+        self,
+        window_size: int | None = None,
+        ddof: int = 1,
+        nearest: bool = True,
+        higham: bool = False,
+        higham_max_iteration: int = 100,
+    ):
+        super().__init__(
+            nearest=nearest,
+            higham=higham,
+            higham_max_iteration=higham_max_iteration,
+        )
+        self.window_size = window_size
+        self.ddof = ddof
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "EmpiricalCovariance":
+        """Fit the empirical covariance estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+           Price returns of the assets.
+
+        y : Ignored
+            Not used, present for API consistency by convention.
+
+        Returns
+        -------
+        self : EmpiricalCovariance
+            Fitted estimator.
+        """
+        X = self._validate_data(X)
+        if self.window_size is not None:
+            X = X[-int(self.window_size) :]
+        covariance = np.cov(X.T, ddof=self.ddof)
+        self._set_covariance(covariance)
+        return self

skfolio/moments/covariance/_ew_covariance.py

@@ -0,0 +1,109 @@
+"""Exponentially Weighted Covariance Estimators."""
+
+# Copyright (c) 2023
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+# Implementation derived from:
+# scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
+# Grisel Licensed under BSD 3 clause.
+
+import numpy.typing as npt
+import pandas as pd
+
+from skfolio.moments.covariance._base import BaseCovariance
+
+
+class EWCovariance(BaseCovariance):
+    r"""Exponentially Weighted Covariance estimator.
+
+    Estimator of the covariance using the historical exponentially weighted returns.
+
+    Parameters
+    ----------
+    window_size : int, optional
+        Window size. The model is fitted on the last `window_size` observations.
+        The default (`None`) is to use all the data.
+
+    alpha : float, default=0.2
+       Exponential smoothing factor. The default value is `0.2`.
+
+       :math:`0 < \alpha \leq 1`.
+
+    nearest : bool, default=True
+        If this is set to True, the covariance is replaced by the nearest covariance
+        matrix that is positive definite and with a Cholesky decomposition than can be
+        computed. The variance is left unchanged.
+        A covariance matrix that is not positive definite often occurs in high
+        dimensional problems. It can be due to multicollinearity, floating-point
+        inaccuracies, or when the number of observations is smaller than the number of
+        assets. For more details, see :func:`~skfolio.utils.stats.cov_nearest`.
+        The default is `True`.
+
+    higham : bool, default=False
+        If this is set to True, the Higham & Nick (2002) algorithm is used to find the
+        nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
+        above zeros (1e-13). The default is `False` and use the clipping method as the
+        Higham & Nick algorithm can be slow for large datasets.
+
+    higham_max_iteration : int, default=100
+        Maximum number of iteration of the Higham & Nick (2002) algorithm.
+        The default value is `100`.
+
+    Attributes
+    ----------
+    covariance_ : ndarray of shape (n_assets, n_assets)
+        Estimated covariance.
+
+    n_features_in_ : int
+       Number of assets seen during `fit`.
+
+    feature_names_in_ : ndarray of shape (`n_features_in_`,)
+       Names of features seen during `fit`. Defined only when `X`
+       has feature names that are all strings.
+    """
+
+    def __init__(
+        self,
+        window_size: int | None = None,
+        alpha: float = 0.2,
+        nearest: bool = True,
+        higham: bool = False,
+        higham_max_iteration: int = 100,
+    ):
+        super().__init__(
+            nearest=nearest,
+            higham=higham,
+            higham_max_iteration=higham_max_iteration,
+        )
+        self.window_size = window_size
+        self.alpha = alpha
+
+    def fit(self, X: npt.ArrayLike, y=None):
+        """Fit the Exponentially Weighted Covariance estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+         Price returns of the assets.
+
+        y : Ignored
+          Not used, present for API consistency by convention.
+
+        Returns
+        -------
+        self : EWCovariance
+          Fitted estimator.
+        """
+        X = self._validate_data(X)
+        if self.window_size is not None:
+            X = X[-int(self.window_size) :]
+        n_observations = X.shape[0]
+        covariance = (
+            pd.DataFrame(X)
+            .ewm(alpha=self.alpha)
+            .cov()
+            .loc[(n_observations - 1, slice(None)), :]
+            .to_numpy()
+        )
+        self._set_covariance(covariance)
+        return self

skfolio/moments/covariance/_gerber_covariance.py

@@ -0,0 +1,157 @@
+"""Gerber Covariance Estimators."""
+
+# Copyright (c) 2023
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+# Implementation derived from:
+# scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
+# Grisel Licensed under BSD 3 clause.
+
+import numpy as np
+import numpy.typing as npt
+
+from skfolio.moments.covariance._base import BaseCovariance
+from skfolio.utils.stats import corr_to_cov
+
+
+class GerberCovariance(BaseCovariance):
+    """Gerber Covariance estimator.
+
+    Robust co-movement measure which ignores fluctuations below a certain threshold
+    while simultaneously limiting the effects of extreme movements.
+    The Gerber statistic extends Kendall's Tau by counting the proportion of
+    simultaneous co-movements in series when their amplitudes exceed data-dependent
+    thresholds.
+
+    Three variant has been published:
+
+        * Gerber et al. (2015): tend to produce matrices that are non-PSD.
+        * Gerber et al. (2019): alteration of the denominator of the above statistic.
+        * Gerber et al. (2022): final alteration to ensure PSD matrix.
+
+    The last two variants are implemented.
+
+    Parameters
+    ----------
+    window_size : int, optional
+        Window size. The model is fitted on the last `window_size` observations.
+        The default (`None`) is to use all the data.
+
+    threshold : float, default=0.5
+        Gerber threshold. The default value is `0.5`.
+
+    psd_variant : bool, default=True
+        If this is set to True, the Gerber et al. (2022) variant is used to ensure a
+        positive semi-definite matrix.
+        Otherwise, the Gerber et al. (2019) variant is used.
+        The default is `True`.
+
+    nearest : bool, default=True
+        If this is set to True, the covariance is replaced by the nearest covariance
+        matrix that is positive definite and with a Cholesky decomposition than can be
+        computed. The variance is left unchanged.
+        A covariance matrix that is not positive definite often occurs in high
+        dimensional problems. It can be due to multicollinearity, floating-point
+        inaccuracies, or when the number of observations is smaller than the number of
+        assets. For more details, see :func:`~skfolio.utils.stats.cov_nearest`.
+        The default is `True`.
+
+    higham : bool, default=False
+        If this is set to True, the Higham & Nick (2002) algorithm is used to find the
+        nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
+        above zeros (1e-13). The default is `False` and use the clipping method as the
+        Higham & Nick algorithm can be slow for large datasets.
+
+    higham_max_iteration : int, default=100
+        Maximum number of iteration of the Higham & Nick (2002) algorithm.
+        The default value is `100`.
+
+    Attributes
+    ----------
+    covariance_ : ndarray of shape (n_assets, n_assets)
+        Estimated covariance.
+
+    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.
+
+    References
+    ----------
+    .. [1]  "The gerber statistic: A robust co-movement measure for portfolio
+        optimization".
+        The Journal of Portfolio Management.
+        Gerber, S., B. Javid, H. Markowitz, P. Sargen, and D. Starer (2022).
+
+    .. [2]  "The gerber statistic: A robust measure of correlation".
+        Gerber, S., B. Javid, H. Markowitz, P. Sargen, and D. Starer (2019).
+
+    .. [3]  "Enhancing multi-asset portfolio construction under modern portfolio theory
+        with a robust co-movement measure".
+        Social Science Research network Working Paper Series.
+        Gerber, S., H. Markowitz, and P. Pujara (2015).
+
+    .. [4]  "Deconstructing the Gerber Statistic".
+        Flint & Polakow, 2023.
+    """
+
+    def __init__(
+        self,
+        window_size: int | None = None,
+        threshold: float = 0.5,
+        psd_variant: bool = True,
+        nearest: bool = True,
+        higham: bool = False,
+        higham_max_iteration: int = 100,
+    ):
+        super().__init__(
+            nearest=nearest,
+            higham=higham,
+            higham_max_iteration=higham_max_iteration,
+        )
+        self.window_size = window_size
+        self.threshold = threshold
+        self.psd_variant = psd_variant
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "GerberCovariance":
+        """Fit the Gerber covariance estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+          Price returns of the assets.
+
+        y : Ignored
+           Not used, present for API consistency by convention.
+
+        Returns
+        -------
+        self : GerberCovariance
+           Fitted estimator.
+        """
+        X = self._validate_data(X)
+        if self.window_size is not None:
+            X = X[-self.window_size :]
+        if not (1 > self.threshold > 0):
+            raise ValueError("The threshold must be between 0 and 1")
+        n_observations = X.shape[0]
+        std = X.std(axis=0).reshape((-1, 1))
+        u = X >= std.T * self.threshold
+        d = X <= -std.T * self.threshold
+        n = np.invert(u) & np.invert(d)  # np.invert preferred that ~ for type hint
+        n = n.astype(int)
+        u = u.astype(int)
+        d = d.astype(int)
+        concordant = u.T @ u + d.T @ d
+        discordant = u.T @ d + d.T @ u
+        h = concordant - discordant
+        if self.psd_variant:
+            corr = h / (n_observations - n.T @ n)
+        else:
+            h_sqrt = np.sqrt(np.diag(h)).reshape((-1, 1))
+            corr = h / (h_sqrt @ h_sqrt.T)
+        covariance = corr_to_cov(corr, std.reshape(-1))
+        self._set_covariance(covariance)
+        return self