skfolio 0.0.1__py3-none-any.whl

skfolio/prior/_black_litterman.py

@@ -0,0 +1,238 @@
+"""Black & Litterman Prior Model estimator."""
+
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+
+import numpy as np
+import numpy.typing as npt
+
+from skfolio.moments import EquilibriumMu
+from skfolio.prior._base import BasePrior, PriorModel
+from skfolio.prior._empirical import EmpiricalPrior
+from skfolio.utils.equations import equations_to_matrix
+from skfolio.utils.tools import check_estimator, input_to_array
+
+
+class BlackLitterman(BasePrior):
+    """Black & Litterman Prior Model estimator.
+
+    The Black & Litterman model [1]_ takes a Bayesian approach by using a prior estimate
+    of the assets expected returns and covariance matrix which are updated using the
+    analyst views to get a posterior estimate.
+
+    Parameters
+    ----------
+    views : array-like of floats of shape (n_views,)
+        The analyst views about the assets expected returns.
+        The views must match the following patterns:
+
+            * Absolute view: "asset_i = a"
+            * Relative view: "asset_i - asset_j = b"
+
+        With "asset_i" and "asset_j" the assets names and "a" and "b" the analyst views
+        about the assets expected returns expressed in the same frequency as the
+        returns `X`.
+
+        Examples:
+
+            * "SPX = 0.00015" --> the SPX will have a daily expected return of 0.015%
+            * "SX5E - TLT = 0.00039" --> the SX5E will outperform the TLT by a daily expected return of 0.039%
+            * "SX5E - SPX = -0.0002" --> the SX5E will underperform the SPX by a daily expected return of 0.02%
+            * "Equity = 0.00010" --> the sum of Equity assets will have a daily expected return of 0.01%
+            * "Europe - US = 0.0004" --> the sum of European assets will outperform the sum of US assets by a daily expected return of 0.04%
+
+    groups : dict[str, list[str]] or array-like of strings of shape (n_groups, n_assets), optional
+        The assets groups to be referenced in `views`.
+        If a dictionary is provided, its (key/value) pair must be the
+        (asset name/asset groups) and the input `X` of the `fit` methods must be a
+        DataFrame with the assets names in columns.
+
+        Examples:
+
+            * groups = {"SX5E": ["Equity", "Europe"], "SPX": ["Equity", "US"], "TLT": ["Bond", "US"]}
+            * groups = [["Equity", "Equity", "Bond"], ["Europe", "US", "US"]]
+
+    prior_estimator : BasePrior, optional
+        The assets' :ref:`prior model estimator <prior>`. It is used to estimate
+        the :class:`~skfolio.prior.PriorModel` containing the estimation of the assets
+        expected returns, covariance matrix, returns and Cholesky decomposition.
+        The default (`None`) is to use `EmpiricalPrior(mu_estimator=EquilibriumMu())`.
+
+    tau : float, default=0.05
+        Tau controls the degree of uncertainty given to the analyst views. A low value
+        means high uncertainty and will put less weight on the analyst views compared to
+        the prior returns. The default value is `0.05`.
+        Other common values used in the literature are `1.0` or the inverse of the
+        number of observations.
+
+    view_confidences : array-like of floats of shape (n_views,), optional
+        Instead of using a diagonal uncertainty matrix (Omega) proportional to the prior
+        covariance matrix, you can provide the vector of view confidences (between 0
+        and 1) as describe by the Idzorek's method [2]_.
+
+    risk_free_rate : float, default=0.0
+        The risk-free rate.
+
+    Attributes
+    ----------
+    prior_model_ : PriorModel
+        The :class:`~skfolio.prior.PriorModel`.
+
+    groups_ : ndarray of shape(n_groups, n_assets)
+        Assets names and groups converted to an 2D array.
+
+    views_ : ndarray of shape (n_views,)
+        The analyst views converted to a ndarray of floats.
+
+    picking_matrix_ : ndarray of shape (n_views, n_assets)
+        Picking matrix computed from the views and assets names/groups.
+
+    prior_estimator_ : BasePrior
+        Fitted `prior_estimator`.
+
+    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.
+
+    References
+    ----------
+    .. [1]  "Combining investor views with market equilibrium",
+        The Journal of Fixed Income,
+        Fischer Black and Robert Litterman, 1991.
+
+    .. [2]  "A step-by-step guide to the Black-Litterman model : Incorporating
+        user-specified confidence",
+        Forecasting Expected Returns in the Financial Markets,
+        Idzorek T, 2007.
+    """
+
+    groups_: np.ndarray
+    views_: np.ndarray
+    picking_matrix_: np.ndarray
+    prior_estimator_: BasePrior
+
+    def __init__(
+        self,
+        views: npt.ArrayLike,
+        groups: dict[str, list[str]] | npt.ArrayLike | None = None,
+        prior_estimator: BasePrior | None = None,
+        tau: float = 0.05,
+        view_confidences: npt.ArrayLike | None = None,
+        risk_free_rate: float = 0,
+    ):
+        self.views = views
+        self.groups = groups
+        self.prior_estimator = prior_estimator
+        self.tau = tau
+        self.view_confidences = view_confidences
+        self.risk_free_rate = risk_free_rate
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "BlackLitterman":
+        """Fit the Black & Litterman 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 : BlackLitterman
+            Fitted estimator.
+        """
+        self.prior_estimator_ = check_estimator(
+            self.prior_estimator,
+            default=EmpiricalPrior(mu_estimator=EquilibriumMu()),
+            check_type=BasePrior,
+        )
+        # fitting prior estimator
+        self.prior_estimator_.fit(X)
+
+        prior_mu = self.prior_estimator_.prior_model_.mu
+        prior_covariance = self.prior_estimator_.prior_model_.covariance
+        prior_returns = self.prior_estimator_.prior_model_.returns
+
+        # we validate after all models have been fitted to keep features names
+        # information.
+        self._validate_data(X)
+
+        n_assets = prior_returns.shape[1]
+        views = np.asarray(self.views)
+        if views.ndim != 1:
+            raise ValueError(f"`views` must be a 1D array, got a {views.ndim}D array.")
+        if self.groups is None:
+            if not hasattr(self, "feature_names_in_"):
+                raise ValueError(
+                    "You must provide either `groups`"
+                    " or `X` as a DataFrame with asset names in columns"
+                )
+            self.groups_ = np.asarray([self.feature_names_in_])
+        else:
+            self.groups_ = input_to_array(
+                items=self.groups,
+                n_assets=n_assets,
+                fill_value="",
+                dim=2,
+                assets_names=(
+                    self.feature_names_in_
+                    if hasattr(self, "feature_names_in_")
+                    else None
+                ),
+                name="groups",
+            )
+        self.picking_matrix_, self.views_ = equations_to_matrix(
+            groups=self.groups_,
+            equations=views,
+            sum_to_one=True,
+            raise_if_group_missing=True,
+            names=("groups", "views"),
+        )
+
+        if self.view_confidences is None:
+            omega = np.diag(
+                np.diag(
+                    self.tau
+                    * self.picking_matrix_
+                    @ prior_covariance
+                    @ self.picking_matrix_.T
+                )
+            )
+        else:
+            # Idzorek's method using Jay Walters closed form solution
+            view_confidences = np.asarray(self.view_confidences)
+            if np.any(view_confidences < 0) or np.any(view_confidences > 1):
+                raise ValueError(
+                    "all values of view_confidences must be between 0 and 1"
+                )
+            view_confidences[view_confidences == 0] = 1e-16
+            alphas = 1 / view_confidences - 1
+            omega = np.diag(
+                np.diag(
+                    self.tau
+                    * alphas[:, np.newaxis]
+                    * self.picking_matrix_
+                    @ prior_covariance
+                    @ self.picking_matrix_.T
+                )
+            )
+
+        # solving linear system instead of matrix inversion
+        _v = self.tau * prior_covariance @ self.picking_matrix_.T
+        _a = self.picking_matrix_ @ _v + omega
+        _b = self.views_ - self.picking_matrix_ @ prior_mu
+        posterior_mu = prior_mu + _v @ np.linalg.solve(_a, _b) + self.risk_free_rate
+        posterior_covariance = (
+            prior_covariance
+            + self.tau * prior_covariance
+            - _v @ np.linalg.solve(_a, _v.T)
+        )
+        self.prior_model_ = PriorModel(
+            mu=posterior_mu, covariance=posterior_covariance, returns=prior_returns
+        )
+        return self

skfolio/prior/_empirical.py

@@ -0,0 +1,163 @@
+"""Empirical Prior Model estimator."""
+
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+import numpy as np
+import numpy.typing as npt
+
+from skfolio.moments import BaseCovariance, BaseMu, EmpiricalCovariance, EmpiricalMu
+from skfolio.prior._base import BasePrior, PriorModel
+from skfolio.utils.tools import check_estimator
+
+
+class EmpiricalPrior(BasePrior):
+    """Empirical Prior estimator.
+
+    The Empirical Prior estimates the :class:`~skfolio.prior.PriorModel` by fitting a
+    `mu_estimator` and a `covariance_estimator` separately.
+
+    Parameters
+    ----------
+    mu_estimator : BaseMu, optional
+        The assets :ref:`expected returns estimator <mu_estimator>`.
+        The default (`None`) is to use :class:`~skfolio.moments.EmpiricalMu`.
+
+    covariance_estimator : BaseCovariance , optional
+        The assets :ref:`covariance matrix estimator <covariance_estimator>`.
+        The default (`None`) is to use  :class:`~skfolio.moments.EmpiricalCovariance`.
+
+    is_log_normal : bool, default=False
+        If this is set to True, the moments are estimated on the logarithmic returns
+        as opposed to the linear returns. Then the moments estimations of the
+        logarithmic returns are projected to the investment horizon and transformed
+        to obtain the moments estimation of the linear returns at the investment
+        horizon. If True, `investment_horizon` must be provided. The input `X` must be
+        **linear returns**. They will be converted into logarithmic returns only for the
+        moments estimation.
+
+        .. seealso::
+
+            :ref:`data preparation <data_preparation>`
+
+
+    investment_horizon : float, optional
+        The investment horizon used for the moments estimation of the linear returns
+        when `is_log_normal` is `True`.
+
+    Attributes
+    ----------
+    prior_model_ : PriorModel
+        The assets :class:`~skfolio.prior.PriorModel`.
+
+    mu_estimator_ : BaseMu
+        Fitted `mu_estimator`.
+
+    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 features seen during `fit`. Defined only when `X`
+       has feature names that are all strings.
+
+    References
+    ----------
+    .. [1]  "Linear vs. Compounded Returns – Common Pitfalls in Portfolio Management".
+        GARP Risk Professional.
+        Attilio Meucci (2010).
+    """
+
+    mu_estimator_: BaseMu
+    covariance_estimator_: BaseCovariance
+
+    def __init__(
+        self,
+        mu_estimator: BaseMu | None = None,
+        covariance_estimator: BaseCovariance | None = None,
+        is_log_normal: bool = False,
+        investment_horizon: float | None = None,
+    ):
+        self.mu_estimator = mu_estimator
+        self.covariance_estimator = covariance_estimator
+        self.is_log_normal = is_log_normal
+        self.investment_horizon = investment_horizon
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "EmpiricalPrior":
+        """Fit the Empirical Prior 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 : EmpiricalPrior
+            Fitted estimator.
+        """
+        self.mu_estimator_ = check_estimator(
+            self.mu_estimator,
+            default=EmpiricalMu(),
+            check_type=BaseMu,
+        )
+        self.covariance_estimator_ = check_estimator(
+            self.covariance_estimator,
+            default=EmpiricalCovariance(),
+            check_type=BaseCovariance,
+        )
+        # fitting estimators
+        if not self.is_log_normal:
+            if self.investment_horizon is not None:
+                raise ValueError(
+                    "`investment_horizon` must be `None` when "
+                    "`is_log_normal` is `False`"
+                )
+            # Expected returns
+            self.mu_estimator_.fit(X)
+            mu = self.mu_estimator_.mu_
+
+            # Covariance
+            self.covariance_estimator_.fit(X)
+            covariance = self.covariance_estimator_.covariance_
+        else:
+            if self.investment_horizon is None:
+                raise ValueError(
+                    "`investment_horizon` must be provided when "
+                    "`is_log_normal` is `True`"
+                )
+            # Convert linear returns to log returns
+            X_log = np.log(1 + X)
+
+            # Estimates the moments on the log returns
+            # Expected returns
+            self.mu_estimator_.fit(X_log)
+            mu = self.mu_estimator_.mu_
+
+            # Covariance
+            self.covariance_estimator_.fit(X_log)
+            covariance = self.covariance_estimator_.covariance_
+
+            # Using the property of aggregation across time we scale this distribution
+            # to the investment horizon by the “square-root rule”.
+            mu *= self.investment_horizon
+            covariance *= self.investment_horizon
+
+            # We convert it into a distribution of linear returns over the investment
+            # horizon
+            mu = np.exp(mu + 0.5 * np.diag(covariance))
+            covariance = np.outer(mu, mu) * (np.exp(covariance) - 1)
+
+        # we validate and convert to numpy after all models have been fitted to keep
+        # features names information.
+        X = self._validate_data(X)
+        self.prior_model_ = PriorModel(
+            mu=mu,
+            covariance=covariance,
+            returns=X,
+        )
+        return self

skfolio/prior/_factor_model.py

@@ -0,0 +1,268 @@
+"""Factor Model estimator"""
+
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+import numpy.typing as npt
+import sklearn.base as skb
+import sklearn.linear_model as skl
+import sklearn.multioutput as skm
+
+from skfolio.prior._base import BasePrior, PriorModel
+from skfolio.prior._empirical import EmpiricalPrior
+from skfolio.utils.stats import cov_nearest
+from skfolio.utils.tools import check_estimator
+
+
+class BaseLoadingMatrix(skb.BaseEstimator, ABC):
+    """Base class for all Loading Matrix estimators.
+
+    Notes
+    -----
+    All estimators should specify all the parameters that can be set
+    at the class level in their ``__init__`` as explicit keyword
+    arguments (no ``*args`` or ``**kwargs``).
+    """
+
+    loading_matrix_: np.ndarray
+    intercepts_: np.ndarray
+
+    @abstractmethod
+    def fit(self, X: npt.ArrayLike, y: npt.ArrayLike):
+        pass
+
+
+class LoadingMatrixRegression(BaseLoadingMatrix):
+    """Loading Matrix Regression estimator.
+
+    Estimate the loading matrix by fitting one linear regressor per asset.
+
+    Parameters
+    ----------
+    linear_regressor : BaseEstimator, optional
+       Linear regressor used to fit the factors on each asset separately.
+       The default (`None`) is to use `LassoCV(fit_intercept=False)`.
+
+    n_jobs : int, optional
+        The number of jobs to run in parallel.
+
+        When individual estimators are fast to train or predict,
+        using ``n_jobs > 1`` can result in slower performance due
+        to the parallelism overhead.
+
+        The value `-1` means using all processors.
+        The default (`None`) means 1 unless in a `joblib.parallel_backend` context.
+
+    Attributes
+    ----------
+    loading_matrix_ : ndarray of shape (n_assets, n_factors)
+        The loading matrix.
+
+    intercepts_: ndarray of shape (n_assets,)
+        The intercepts.
+
+    multi_output_regressor_: MultiOutputRegressor
+        Fitted `sklearn.multioutput.MultiOutputRegressor`
+    """
+
+    multi_output_regressor_: skm.MultiOutputRegressor
+
+    def __init__(
+        self,
+        linear_regressor: skb.BaseEstimator | None = None,
+        n_jobs: int | None = None,
+    ):
+        self.linear_regressor = linear_regressor
+        self.n_jobs = n_jobs
+
+    def fit(self, X: npt.ArrayLike, y: npt.ArrayLike):
+        """Fit the Loading Matrix Regression Estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+            Price returns of the assets.
+
+        y : array-like of shape (n_observations, n_factors)
+            Price returns of the factors.
+
+        Returns
+        -------
+        self : LoadingMatrixRegression
+            Fitted estimator.
+        """
+        _linear_regressor = check_estimator(
+            self.linear_regressor,
+            default=skl.LassoCV(fit_intercept=False),
+            check_type=skb.BaseEstimator,
+        )
+
+        self.multi_output_regressor_ = skm.MultiOutputRegressor(
+            _linear_regressor, n_jobs=self.n_jobs
+        )
+        self.multi_output_regressor_.fit(X=y, y=X)
+        # noinspection PyUnresolvedReferences
+        n_assets = X.shape[1]
+        self.loading_matrix_ = np.array(
+            [self.multi_output_regressor_.estimators_[i].coef_ for i in range(n_assets)]
+        )
+        self.intercepts_ = np.array(
+            [
+                self.multi_output_regressor_.estimators_[i].intercept_
+                for i in range(n_assets)
+            ]
+        )
+
+
+class FactorModel(BasePrior):
+    """Factor Model estimator.
+
+    The purpose of Factor Models is to impose a structure on financial variables and
+    their covariance matrix by explaining them through a small number of common factors.
+    This can help to overcome estimation error by reducing the number of parameters,
+    i.e. the dimensionality of the estimation problem, making portfolio optimization
+    more robust against noise in the data. Factor Models also provide a decomposition of
+    financial risk to systematic and security specific components.
+
+    Parameters
+    ----------
+    loading_matrix_estimator : LoadingMatrixEstimator, optional
+        Estimator of the loading matrix (betas) of the factors.
+        The default (`None`) is to use :class:`LoadingMatrixRegression` which fit the
+        factors using `LassoCV` on each asset separately.
+
+    factor_prior_estimator : BasePrior, optional
+        The factors :ref:`prior estimator <prior>`.
+        It is used to estimate the :class:`~skfolio.prior.PriorModel` containing the
+        factors expected returns and covariance matrix.
+        The default (`None`) is to use :class:`~skfolio.prior.EmpiricalPrior`.
+
+    residual_variance : bool, default=True
+        If this is set to True, the diagonal term of the residuals covariance
+        (residuals variance) is added to the factor model covariance.
+
+    higham : bool, default=False
+        If this is set to True, we use the Higham & Nick (2002) algorithm to find the
+        nearest covariance matrix that is positive semi-definite. It is more accurate
+        but slower that the default clipping method. For more information
+        see :func:`~skfolio.utils.stats.cov_nearest`.
+
+    max_iteration : int, default=100
+        Only used when `higham` is set to True. Maximum number of iterations of the
+        Higham & Nick (2002) algorithm.
+
+    Attributes
+    ----------
+    prior_model_ : PriorModel
+        The :class:`~skfolio.prior.PriorModel`.
+
+    factor_prior_estimator_ : BasePrior
+        Fitted `factor_prior_estimator`.
+
+    loading_matrix_estimator_ : BaseLoadingMatrix
+        Fitted `loading_matrix_estimator`.
+
+    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.
+    """
+
+    factor_prior_estimator_: BasePrior
+    loading_matrix_estimator_: BaseLoadingMatrix
+
+    def __init__(
+        self,
+        loading_matrix_estimator: BaseLoadingMatrix | None = None,
+        factor_prior_estimator: BasePrior | None = None,
+        residual_variance: bool = True,
+        higham: bool = False,
+        max_iteration: int = 100,
+    ):
+        self.loading_matrix_estimator = loading_matrix_estimator
+        self.factor_prior_estimator = factor_prior_estimator
+        self.residual_variance = residual_variance
+        self.higham = higham
+        self.max_iteration = max_iteration
+
+    # noinspection PyMethodOverriding, PyPep8Naming
+    def fit(self, X: npt.ArrayLike, y: any):
+        """Fit the Factor Model estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+            Price returns of the assets.
+
+        y : array-like of shape (n_observations, n_factors)
+            Factors' returns.
+
+        Returns
+        -------
+        self : FactorModel
+            Fitted estimator.
+        """
+        self.factor_prior_estimator_ = check_estimator(
+            self.factor_prior_estimator,
+            default=EmpiricalPrior(),
+            check_type=BasePrior,
+        )
+        self.loading_matrix_estimator_ = check_estimator(
+            self.loading_matrix_estimator,
+            default=LoadingMatrixRegression(),
+            check_type=BaseLoadingMatrix,
+        )
+
+        # Fitting prior estimator
+        self.factor_prior_estimator_.fit(y)
+        factor_mu = self.factor_prior_estimator_.prior_model_.mu
+        factor_covariance = self.factor_prior_estimator_.prior_model_.covariance
+
+        # Fitting loading matrix estimator
+        self.loading_matrix_estimator_.fit(X, y)
+        loading_matrix = self.loading_matrix_estimator_.loading_matrix_
+        intercepts = self.loading_matrix_estimator_.intercepts_
+
+        # we validate and convert to numpy after all models have been fitted to keep
+        # features names information.
+        X, y = self._validate_data(X, y, multi_output=True)
+        n_assets = X.shape[1]
+        n_factors = y.shape[1]
+
+        if loading_matrix.shape != (n_assets, n_factors):
+            raise ValueError(
+                "`loading_matrix_estimator.loading_matrix_` must ba a 2D array of"
+                f" shape {(n_assets, n_factors)}, got"
+                f" {loading_matrix.shape} instead."
+            )
+
+        if intercepts.shape != (n_assets,):
+            raise ValueError(
+                "`loading_matrix_estimator.intercepts_` must ba a 1D array of "
+                f"shape {(n_assets,)}, got {intercepts.shape} instead."
+            )
+
+        mu = loading_matrix @ factor_mu + intercepts
+        covariance = loading_matrix @ factor_covariance @ loading_matrix.T
+        returns = y @ loading_matrix.T + intercepts
+        cholesky = loading_matrix @ np.linalg.cholesky(factor_covariance)
+
+        if self.residual_variance:
+            err = X - returns
+            err_cov = np.diag(np.var(err, ddof=1, axis=0))
+            covariance += err_cov
+            cholesky = np.hstack((cholesky, np.sqrt(err_cov)))
+
+        covariance = cov_nearest(
+            covariance, higham=self.higham, higham_max_iteration=self.max_iteration
+        )
+
+        self.prior_model_ = PriorModel(
+            mu=mu, covariance=covariance, returns=returns, cholesky=cholesky
+        )
+        return self