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

skfolio/moments/covariance/_ledoit_wolf.py

@@ -0,0 +1,140 @@
+"""LedoitWolf 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 sklearn.covariance as skc
+
+from skfolio.moments.covariance._base import BaseCovariance
+
+
+class LedoitWolf(BaseCovariance, skc.LedoitWolf):
+    """LedoitWolf Covariance Estimator.
+
+    Ledoit-Wolf is a particular form of shrinkage, where the shrinkage
+    coefficient is computed using O. Ledoit and M. Wolf's formula as
+    described in [1]_.
+
+    Read more in `scikit-learn
+    <https://scikit-learn.org/stable/modules/generated/sklearn.covariance.ShrunkCovariance.html>`_.
+
+    Parameters
+    ----------
+    store_precision : bool, default=True
+        Specify if the estimated precision is stored.
+
+    assume_centered : bool, default=False
+        If True, data will not be centered before computation.
+        Useful when working with data whose mean is almost, but not exactly
+        zero.
+        If False (default), data will be centered before computation.
+
+    block_size : int, default=1000
+        Size of blocks into which the covariance matrix will be split
+        during its Ledoit-Wolf estimation. This is purely a memory
+        optimization and does not affect results.
+
+    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.
+
+    location_ : ndarray of shape (n_assets,)
+        Estimated location, i.e. the estimated mean.
+
+    precision_ : ndarray of shape (n_assets, n_assets)
+        Estimated pseudo inverse matrix.
+        (stored only if store_precision is True)
+
+    shrinkage_ : float
+        Coefficient in the convex combination used for the computation
+        of the shrunk estimate. Range is [0, 1].
+
+    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.
+
+    Notes
+    -----
+    The regularised covariance is:
+
+    (1 - shrinkage) * cov + shrinkage * mu * np.identity(n_features)
+
+    where mu = trace(cov) / n_features
+    and shrinkage is given by the Ledoit and Wolf formula (see References)
+
+    References
+    ----------
+    .. [1]  "A Well-Conditioned Estimator for Large-Dimensional Covariance Matrices".
+        Ledoit and Wolf, Journal of Multivariate Analysis, Volume 88, Issue 2.
+        February 2004, pages 365-41.
+    """
+
+    def __init__(
+        self,
+        store_precision=True,
+        assume_centered=False,
+        block_size=1000,
+        nearest: bool = True,
+        higham: bool = False,
+        higham_max_iteration: int = 100,
+    ):
+        super().__init__(
+            nearest=nearest,
+            higham=higham,
+            higham_max_iteration=higham_max_iteration,
+        )
+        skc.LedoitWolf.__init__(
+            self,
+            store_precision=store_precision,
+            assume_centered=assume_centered,
+            block_size=block_size,
+        )
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "LedoitWolf":
+        """Fit the Ledoit-Wolf shrunk covariance model to X.
+
+        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 : LedoitWolf
+          Fitted estimator.
+        """
+        skc.LedoitWolf.fit(self, X)
+        self._set_covariance(self.covariance_)
+        return self

skfolio/moments/covariance/_oas.py

@@ -0,0 +1,115 @@
+"""Oracle Approximating Shrinkage 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 sklearn.covariance as skc
+
+from skfolio.moments.covariance._base import BaseCovariance
+
+
+class OAS(BaseCovariance, skc.OAS):
+    """Oracle Approximating Shrinkage Estimator as proposed in [1]_.
+
+    Read more in `scikit-learn
+    <https://scikit-learn.org/stable/modules/generated/sklearn.covariance.ShrunkCovariance.html>`_.
+
+    Parameters
+    ----------
+    store_precision : bool, default=True
+        Specify if the estimated precision is stored.
+
+    assume_centered : bool, default=False
+        If True, data will not be centered before computation.
+        Useful when working with data whose mean is almost, but not exactly
+        zero.
+        If False (default), data will be centered before computation.
+
+    Attributes
+    ----------
+    covariance_ : ndarray of shape (n_assets, n_assets)
+        Estimated covariance.
+
+    location_ : ndarray of shape (n_assets,)
+        Estimated location, i.e. the estimated mean.
+
+    precision_ : ndarray of shape (n_assets, n_assets)
+        Estimated pseudo inverse matrix.
+        (stored only if store_precision is True)
+
+    shrinkage_ : float
+        Coefficient in the convex combination used for the computation
+        of the shrunk estimate. Range is [0, 1].
+
+    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.
+
+    Notes
+    -----
+    The regularised covariance is:
+
+    (1 - shrinkage) * cov + shrinkage * mu * np.identity(n_features),
+
+    where mu = trace(cov) / n_features and shrinkage is given by the OAS formula
+    (see [1]_).
+
+    The shrinkage formulation implemented here differs from Eq. 23 in [1]_. In
+    the original article, formula (23) states that 2/p (p being the number of
+    features) is multiplied by Trace(cov*cov) in both the numerator and
+    denominator, but this operation is omitted because for a large p, the value
+    of 2/p is so small that it doesn't affect the value of the estimator.
+
+    References
+    ----------
+    .. [1] "Shrinkage algorithms for MMSE covariance estimation".
+        Chen, Y., Wiesel, A., Eldar, Y. C., & Hero, A. O.
+        IEEE Transactions on Signal Processing, 58(10), 5016-5029, 2010.
+    """
+
+    def __init__(
+        self,
+        store_precision=True,
+        assume_centered=False,
+        nearest: bool = True,
+        higham: bool = False,
+        higham_max_iteration: int = 100,
+    ):
+        super().__init__(
+            nearest=nearest,
+            higham=higham,
+            higham_max_iteration=higham_max_iteration,
+        )
+        skc.OAS.__init__(
+            self,
+            store_precision=store_precision,
+            assume_centered=assume_centered,
+        )
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "OAS":
+        """Fit the Oracle Approximating Shrinkage covariance model to X.
+
+        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 : OAS
+          Fitted estimator.
+        """
+        skc.OAS.fit(self, X)
+        self._set_covariance(self.covariance_)
+        return self

skfolio/moments/covariance/_shrunk_covariance.py

@@ -0,0 +1,104 @@
+"""Shrunk 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 sklearn.covariance as skc
+
+from skfolio.moments.covariance._base import BaseCovariance
+
+
+class ShrunkCovariance(BaseCovariance, skc.ShrunkCovariance):
+    """Covariance estimator with shrinkage.
+
+    Read more in `scikit-learn
+    <https://scikit-learn.org/stable/modules/generated/sklearn.covariance.ShrunkCovariance.html>`_.
+
+    Parameters
+    ----------
+    store_precision : bool, default=True
+        Specify if the estimated precision is stored.
+
+    assume_centered : bool, default=False
+        If True, data will not be centered before computation.
+        Useful when working with data whose mean is almost, but not exactly
+        zero.
+        If False (default), data will be centered before computation.
+
+    shrinkage : float, default=0.1
+        Coefficient in the convex combination used for the computation
+        of the shrunk estimate. Range is [0, 1].
+
+    Attributes
+    ----------
+    covariance_ : ndarray of shape (n_assets, n_assets)
+        Estimated covariance.
+
+    location_ : ndarray of shape (n_assets,)
+        Estimated location, i.e. the estimated mean.
+
+    precision_ : ndarray of shape (n_assets, n_assets)
+        Estimated pseudo inverse matrix.
+        (stored only if store_precision is True)
+
+    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.
+
+    Notes
+    -----
+    The regularized covariance is given by:
+
+    (1 - shrinkage) * cov + shrinkage * mu * np.identity(n_features)
+
+    where mu = trace(cov) / n_features
+    """
+
+    def __init__(
+        self,
+        store_precision=True,
+        assume_centered=False,
+        shrinkage=0.1,
+        nearest: bool = True,
+        higham: bool = False,
+        higham_max_iteration: int = 100,
+    ):
+        super().__init__(
+            nearest=nearest,
+            higham=higham,
+            higham_max_iteration=higham_max_iteration,
+        )
+        skc.ShrunkCovariance.__init__(
+            self,
+            store_precision=store_precision,
+            assume_centered=assume_centered,
+            shrinkage=shrinkage,
+        )
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "ShrunkCovariance":
+        """Fit the shrunk covariance model to X.
+
+        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 : ShrunkCovariance
+          Fitted estimator.
+        """
+        skc.ShrunkCovariance.fit(self, X)
+        self._set_covariance(self.covariance_)
+        return self

skfolio/moments/expected_returns/__init__.py

@@ -3,13 +3,10 @@
 from skfolio.moments.expected_returns._base import (
     BaseMu,
 )
-from skfolio.moments.expected_returns._expected_returns import (
-    EWMu,
-    EmpiricalMu,
-    EquilibriumMu,
-    ShrunkMu,
-    ShrunkMuMethods,
-)
+from skfolio.moments.expected_returns._empirical_mu import EmpiricalMu
+from skfolio.moments.expected_returns._equilibrium_mu import EquilibriumMu
+from skfolio.moments.expected_returns._ew_mu import EWMu
+from skfolio.moments.expected_returns._shrunk_mu import ShrunkMu, ShrunkMuMethods
 
 __all__ = [
     "BaseMu",

skfolio/moments/expected_returns/_empirical_mu.py

@@ -0,0 +1,63 @@
+"""Empirical Expected Returns (Mu) Estimator."""
+
+# 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.expected_returns._base import BaseMu
+
+
+class EmpiricalMu(BaseMu):
+    """Empirical Expected Returns (Mu) estimator.
+
+    Estimates the expected returns with the historical mean.
+
+    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.
+
+    Attributes
+    ----------
+    mu_ : ndarray of shape (n_assets,)
+        Estimated expected returns of the assets.
+
+    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):
+        self.window_size = window_size
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "EmpiricalMu":
+        """Fit the Mu Empirical estimator model.
+
+        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 : EmpiricalMu
+            Fitted estimator.
+        """
+        X = self._validate_data(X)
+        if self.window_size is not None:
+            X = X[-self.window_size :]
+        self.mu_ = np.mean(X, axis=0)
+        return self

skfolio/moments/expected_returns/_equilibrium_mu.py

@@ -0,0 +1,124 @@
+"""Equilibrium Expected Returns (Mu) 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 import BaseCovariance, EmpiricalCovariance
+from skfolio.moments.expected_returns._base import BaseMu
+from skfolio.utils.tools import check_estimator
+
+
+class EquilibriumMu(BaseMu):
+    r"""Equilibrium Expected Returns (Mu) estimator.
+
+    The Equilibrium is defined as:
+
+        .. math:: risk\_aversion \times \Sigma \cdot w^T
+
+    For Market Cap Equilibrium, the weights are the assets Market Caps.
+    For Equal-weighted Equilibrium, the weights are equal-weighted (1/N).
+
+    Parameters
+    ----------
+    risk_aversion : float, default=1.0
+        Risk aversion factor.
+        The default value is `1.0`.
+
+    weights : array-like of shape (n_assets,), optional
+        Asset weights used to compute the Expected Return Equilibrium.
+        The default is to use the equal-weighted equilibrium (1/N).
+        For a Market Cap weighted equilibrium, you must provide the asset Market Caps.
+
+    covariance_estimator : BaseCovariance, optional
+        :ref:`Covariance estimator <covariance_estimator>` used to estimate the
+        covariance in the equilibrium formula.
+        The default (`None`) is to use :class:`~skfolio.moments.EmpiricalCovariance`.
+
+    Attributes
+    ----------
+    mu_ : ndarray of shape (n_assets,)
+          Estimated expected returns of the assets.
+
+    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.
+    """
+
+    covariance_estimator_: BaseCovariance
+
+    def __init__(
+        self,
+        risk_aversion: float = 1,
+        weights: np.ndarray | None = None,
+        covariance_estimator: BaseCovariance | None = None,
+    ):
+        self.risk_aversion = risk_aversion
+        self.weights = weights
+        self.covariance_estimator = covariance_estimator
+
+    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) -> "EquilibriumMu":
+        """Fit the EquilibriumMu estimator model.
+
+        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 : EquilibriumMu
+            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.
+        X = self._validate_data(X)
+        n_assets = X.shape[1]
+        if self.weights is None:
+            weights = np.ones(n_assets) / n_assets
+        else:
+            weights = np.asarray(self.weights)
+        self.mu_ = self.risk_aversion * self.covariance_estimator_.covariance_ @ weights
+        return self

skfolio/moments/expected_returns/_ew_mu.py

@@ -0,0 +1,69 @@
+"""Exponentially Weighted Expected Returns (Mu) 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.expected_returns._base import BaseMu
+
+
+class EWMu(BaseMu):
+    r"""Exponentially Weighted Expected Returns (Mu) estimator.
+
+    Estimates the expected returns with the exponentially weighted mean (EWM).
+
+    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`.
+
+    Attributes
+    ----------
+    mu_ : ndarray of shape (n_assets,)
+       Estimated expected returns of the assets.
+
+    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, alpha: float = 0.2):
+        self.window_size = window_size
+        self.alpha = alpha
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "EWMu":
+        """Fit the EWMu estimator model.
+
+        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 : EWMu
+            Fitted estimator.
+        """
+        X = self._validate_data(X)
+        if self.window_size is not None:
+            X = X[-self.window_size :]
+        self.mu_ = pd.DataFrame(X).ewm(alpha=self.alpha).mean().iloc[-1, :].to_numpy()
+        return self