skfolio 0.0.1__py3-none-any.whl

skfolio/optimization/convex/_maximum_diversification.py

@@ -0,0 +1,417 @@
+"""Maximum Diversification Optimization estimator."""
+
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+
+import numpy as np
+import numpy.typing as npt
+
+import skfolio.typing as skt
+from skfolio.measures import RiskMeasure
+from skfolio.optimization.convex._base import ObjectiveFunction
+from skfolio.optimization.convex._mean_risk import MeanRisk
+from skfolio.prior import BasePrior
+
+
+class MaximumDiversification(MeanRisk):
+    r"""Maximum Diversification Optimization estimator.
+
+    Maximizes the diversification ratio which is the ratio of the weighted volatilities
+    over the total volatility.
+
+    It is a special case of the :class:`~skfolio.optimization.MeanRisk` estimator where
+    the expected return from the objective function is replaced by the weighted
+    volatilies.
+
+    Parameters
+    ----------
+    prior_estimator : BasePrior, optional
+        :ref:`Prior estimator <prior>`.
+        The prior estimator is used to estimate the :class:`~skfolio.prior.PriorModel`
+        containing the estimation of assets expected returns, covariance matrix,
+        returns and Cholesky decomposition of the covariance.
+        The default (`None`) is to use :class:`~skfolio.prior.EmpiricalPrior`.
+
+    min_weights : float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0
+        Minimum assets weights (weights lower bounds).
+        If a float is provided, it is applied to each asset.
+        `None` is equivalent to `-np.Inf` (no lower bound).
+        If a dictionary is provided, its (key/value) pair must be the
+        (asset name/asset minium weight) and the input `X` of the `fit` methods must
+        be a DataFrame with the assets names in columns.
+        When using a dictionary, assets values that are not provided are assigned
+        a minimum weight of `0.0`.
+        The default value is `0.0` (no short selling).
+
+        Example:
+
+           * `min_weights = 0` --> long only portfolio (no short selling).
+           * `min_weights = None` --> no lower bound (same as `-np.Inf`).
+           * `min_weights = -2` --> each weight must be above -200%.
+           * `min_weights = {"SX5E": 0, "SPX": -2}`
+           * `min_weights = [0, -2]`
+
+    max_weights : float | dict[str, float] | array-like of shape (n_assets, ) | None, default=1.0
+        Maximum assets weights (weights upper bounds).
+        If a float is provided, it is applied to each asset.
+        `None` is equivalent to `+np.Inf` (no upper bound).
+        If a dictionary is provided, its (key/value) pair must be the
+        (asset name/asset maximum weight) and the input `X` of the `fit` methods must
+        be a DataFrame with the assets names in columns.
+        When using a dictionary, assets values that are not provided are assigned
+        a minimum weight of `1.0`.
+        The default value is `1.0` (each asset is below 100%).
+
+        Example:
+
+           * `max_weights = 0` --> no long position (short only portfolio).
+           * `max_weights = None` --> no upper bound.
+           * `max_weights = 2` --> each weight must be below 200%.
+           * `max_weights = {"SX5E": 1, "SPX": 2}`
+           * `max_weights = [1, 2]`
+
+    budget : float | None, default=1.0
+        Investment budget. It is the sum of long positions and short positions (sum of
+        all weights). `None` means no budget constraints.
+        The default value is `1.0` (fully invested portfolio).
+
+        Examples:
+
+             * `budget = 1` --> fully invested portfolio.
+             * `budget = 0` --> market neutral portfolio.
+             * `budget = None` --> no constraints on the sum of weights.
+
+    min_budget : float, optional
+        Minimum budget. It is the lower bound of the sum of long and short positions
+        (sum of all weights). If provided, you must set `budget=None`.
+        The default (`None`) means no minimum budget constraint.
+
+    max_budget :  float, optional
+        Maximum budget. It is the upper bound of the sum of long and short positions
+        (sum of all weights). If provided, you must set `budget=None`.
+        The default (`None`) means no maximum budget constraint.
+
+    max_short : float, optional
+        Maximum short position. The short position is defined as the sum of negative
+        weights (in absolute term).
+        The default (`None`) means no maximum short position.
+
+    max_long : float, optional
+        Maximum long position. The long position is defined as the sum of positive
+        weights.
+        The default (`None`) means no maximum long position.
+
+    transaction_costs : float | dict[str, float] | array-like of shape (n_assets, ), default=0.0
+        Transaction costs of the assets. It is used to add linear transaction costs to
+        the optimization problem:
+
+        .. math:: total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
+
+        with :math:`c_{i}` the transaction cost of asset i, :math:`w_{i}` its weight
+        and :math:`w\_prev_{i}` its previous weight (defined in `previous_weights`).
+        The float :math:`total\_cost` is used in the portfolio expected return:
+
+        .. math:: expected\_return = \mu^{T} \cdot w - total\_cost
+
+        with :math:`\mu` the vector af assets' expected returns and :math:`w` the
+        vector of assets weights.
+
+        If a float is provided, it is applied to each asset.
+        If a dictionary is provided, its (key/value) pair must be the
+        (asset name/asset cost) and the input `X` of the `fit` methods must be a
+        DataFrame with the assets names in columns.
+        The default value is `0.0`.
+
+        .. warning::
+
+            Based on the above formula, the periodicity of the transaction costs
+            needs to be homogenous to the periodicity of :math:`\mu`. For example, if
+            the input `X` is composed of **daily** returns, the `transaction_costs` need
+            to be expressed in **daily** costs.
+            (See :ref:`sphx_glr_auto_examples_1_mean_risk_plot_6_transaction_costs.py`)
+
+    management_fees : float | dict[str, float] | array-like of shape (n_assets, ), default=0.0
+        Management fees of the assets. It is used to add linear management fees to the
+        optimization problem:
+
+        .. math:: total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
+
+        with :math:`f_{i}` the management fee of asset i and :math:`w_{i}` its weight.
+        The float :math:`total\_fee` is used in the portfolio expected return:
+
+        .. math:: expected\_return = \mu^{T} \cdot w - total\_fee
+
+        with :math:`\mu` the vector af assets expected returns and :math:`w` the vector
+        of assets weights.
+
+        If a float is provided, it is applied to each asset.
+        If a dictionary is provided, its (key/value) pair must be the
+        (asset name/asset fee) and the input `X` of the `fit` methods must be a
+        DataFrame with the assets names in columns.
+        The default value is `0.0`.
+
+        .. warning::
+
+            Based on the above formula, the periodicity of the management fees needs to
+            be homogenous to the periodicity of :math:`\mu`. For example, if the input
+            `X` is composed of **daily** returns, the `management_fees` need to be
+            expressed in **daily** fees.
+
+        .. note::
+
+            Another approach is to directly impact the management fees to the input `X`
+            in order to express the returns net of fees. However, when estimating the
+            :math:`\mu` parameter using for example Shrinkage estimators, this approach
+            would mix a deterministic value with an uncertain one leading to unwanted
+            bias in the management fees.
+
+    previous_weights : float | dict[str, float] | array-like of shape (n_assets, ), optional
+        Previous weights of the assets. Previous weights are used to compute the
+        portfolio cost and the portfolio turnover.
+        If a float is provided, it is applied to each asset.
+        If a dictionary is provided, its (key/value) pair must be the
+        (asset name/asset previous weight) and the input `X` of the `fit` methods must
+        be a DataFrame with the assets names in columns.
+        The default (`None`) means no previous weights.
+
+    l1_coef : float, default=0.0
+        L1 regularization coefficient.
+        It is used to penalize the objective function by the L1 norm:
+
+        .. math:: l1\_coef \times \Vert w \Vert_{1} = l1\_coef \times \sum_{i=1}^{N} |w_{i}|
+
+        Increasing this coefficient will reduce the number of non-zero weights
+        (cardinality). It tends to increase robustness (out-of-sample stability) but
+        reduces diversification.
+        The default value is `0.0`.
+
+    l2_coef : float, default=0.0
+        L2 regularization coefficient.
+        It is used to penalize the objective function by the L2 norm:
+
+        .. math:: l2\_coef \times \Vert w \Vert_{2}^{2} = l2\_coef \times \sum_{i=1}^{N} w_{i}^2
+
+        It tends to increase robustness (out-of-sample stability).
+        The default value is `0.0`.
+
+    linear_constraints : array-like of shape (n_constraints,), optional
+        Linear constraints.
+        The linear constraints must match any of following patterns:
+
+           * "2.5 * ref1 + 0.10 * ref2 + 0.0013 <= 2.5 * ref3"
+           * "ref1 >= 2.9 * ref2"
+           * "ref1 <= ref2"
+           * "ref1 >= ref1"
+
+        With "ref1", "ref2" ... the assets names or the groups names provided
+        in the parameter `groups`. Assets names can be referenced without the need of
+        `groups` if the input `X` of the `fit` methods is a DataFrame with these
+        assets names in columns.
+
+        Examples:
+
+            * "SPX >= 0.10" --> SPX weight must be greater than 10% (note that you can also use `min_weights`)
+            * "SX5E + TLT >= 0.2" --> the sum of SX5E and TLT weights must be greater than 20%
+            * "US >= 0.7" --> the sum of all US weights must be greater than 70%
+            * "Equity <= 3 * Bond" --> the sum of all Equity weights must be less or equal to 3 times the sum of all Bond weights.
+            * "2*SPX + 3*Europe <= Bond + 0.05" --> mixing assets and group constraints
+
+    groups : dict[str, list[str]] or array-like of shape (n_groups, n_assets), optional
+        The assets groups referenced in `linear_constraints`.
+        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"]]
+
+    left_inequality : array-like of shape (n_constraints, n_assets), optional
+        Left inequality matrix :math:`A` of the linear
+        constraint :math:`A \cdot w \leq b`.
+
+    right_inequality : array-like of shape (n_constraints, ), optional
+        Right inequality vector :math:`b` of the linear
+        constraint :math:`A \cdot w \leq b`.
+
+    risk_free_rate : float, default=0.0
+        Risk-free interest rate.
+        The default value is `0.0`.
+
+    max_tracking_error : float, optional
+        Upper bound constraint on the tracking error.
+        The tracking error is defined as the RMSE (root-mean-square error) of the
+        portfolio returns compared to a target returns. If `max_tracking_error` is
+        provided, the target returns `y` must be provided in the `fit` method.
+
+    max_turnover : float, optional
+        Upper bound constraint of the turnover.
+        The turnover is defined as the absolute difference between the portfolio weights
+        and the `previous_weights`. Note that another way to control for turnover is by
+        using the `transaction_costs` parameter.
+
+    min_return : float | array-like of shape (n_optimization), optional
+        Lower bound constraint on the expected return.
+
+    min_return : float | array-like of shape (n_optimization), optional
+        Lower bound constraint on the expected return.
+
+    add_objective : Callable[[cp.Variable], cp.Expression], optional
+        Add a custom objective to the existing objective expression.
+        It is a function that must take as argument the weights `w` and returns a
+        CVXPY expression.
+
+    add_constraints : Callable[[cp.Variable], cp.Expression|list[cp.Expression]], optional
+        Add a custom constraint or a list of constraints to the existing constraints.
+        It is a function that must take as argument the weights `w` and returns a
+        CVPXY expression or a list of CVPXY expressions.
+
+    solver : str, optional
+        The solver to use. For example, "ECOS", "SCS", or "OSQP".
+        The default (`None`) is set depending on the problem.
+        For more details about available solvers, check the CVXPY documentation:
+        https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver
+
+    solver_params : dict, optional
+        Solver parameters. For example, `solver_params=dict(verbose=True)`.
+        For more details about solver arguments, check the CVXPY documentation:
+        https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options
+
+    scale_objective : float, optional
+        Scale each objective element by this value.
+        It can be used to increase the optimization accuracies in specific cases.
+        The default (`None`) is set depending on the problem.
+
+    scale_constraints : float, optional
+        Scale each constraint element by this value.
+        It can be used to increase the optimization accuracies in specific cases.
+        The default (`None`) is set depending on the problem.
+
+    raise_on_failure : bool, default=True
+        If this is set to True, an error is raised when the optimization fail otherwise
+        it passes with a warning.
+
+    portfolio_params :  dict, optional
+        Portfolio parameters passed to the portfolio evaluated by the `predict` and
+        `score` methods. If not provided, the `name`, `transaction_costs`,
+        `management_fees` and `previous_weights` are copied from the optimization
+        model and systematically passed to the portfolio.
+
+    Attributes
+    ----------
+    weights_ : ndarray of shape (n_assets,) or (n_optimizations, n_assets)
+        Weights of the assets.
+
+    problem_: cvxpy.Problem
+        CVXPY problem used for the optimization.
+
+    problem_values_ :  dict[str, float] | list[dict[str, float]] of size n_optimizations
+        Expression values retrieved from the CVXPY problem.
+
+    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 assets seen during `fit`. Defined only when `X`
+        has assets names that are all strings.
+    """
+
+    def __init__(
+        self,
+        prior_estimator: BasePrior | None = None,
+        min_weights: skt.MultiInput | None = 0.0,
+        max_weights: skt.MultiInput | None = 1.0,
+        budget: float | None = 1.0,
+        min_budget: float | None = None,
+        max_budget: float | None = None,
+        max_short: float | None = None,
+        max_long: float | None = None,
+        transaction_costs: skt.MultiInput = 0.0,
+        management_fees: skt.MultiInput = 0.0,
+        previous_weights: skt.MultiInput | None = None,
+        groups: skt.Groups | None = None,
+        linear_constraints: skt.LinearConstraints | None = None,
+        left_inequality: skt.Inequality | None = None,
+        right_inequality: skt.Inequality | None = None,
+        l1_coef: float = 0.0,
+        l2_coef: float = 0.0,
+        risk_free_rate: float = 0.0,
+        min_return: skt.Target | None = None,
+        max_tracking_error: skt.Target | None = None,
+        max_turnover: skt.Target | None = None,
+        solver: str | None = None,
+        solver_params: dict | None = None,
+        scale_objective: float | None = None,
+        scale_constraints: float | None = None,
+        raise_on_failure: bool = True,
+        add_objective: skt.ExpressionFunction | None = None,
+        add_constraints: skt.ExpressionFunction | None = None,
+        portfolio_params: dict | None = None,
+    ):
+        super().__init__(
+            objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
+            risk_measure=RiskMeasure.VARIANCE,
+            prior_estimator=prior_estimator,
+            min_weights=min_weights,
+            max_weights=max_weights,
+            budget=budget,
+            min_budget=min_budget,
+            max_budget=max_budget,
+            max_short=max_short,
+            max_long=max_long,
+            transaction_costs=transaction_costs,
+            management_fees=management_fees,
+            previous_weights=previous_weights,
+            groups=groups,
+            linear_constraints=linear_constraints,
+            left_inequality=left_inequality,
+            right_inequality=right_inequality,
+            l1_coef=l1_coef,
+            l2_coef=l2_coef,
+            risk_free_rate=risk_free_rate,
+            min_return=min_return,
+            max_tracking_error=max_tracking_error,
+            max_turnover=max_turnover,
+            solver=solver,
+            solver_params=solver_params,
+            scale_objective=scale_objective,
+            scale_constraints=scale_constraints,
+            raise_on_failure=raise_on_failure,
+            add_objective=add_objective,
+            add_constraints=add_constraints,
+            portfolio_params=portfolio_params,
+        )
+
+    def fit(
+        self, X: npt.ArrayLike, y: npt.ArrayLike | None = None
+    ) -> "MaximumDiversification":
+        """Fit the Maximum Diversification Optimization estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+           Price returns of the assets.
+
+        y : array-like of shape (n_observations, n_targets), optional
+            Price returns of factors or a target benchmark.
+            The default is `None`.
+
+        Returns
+        -------
+        self : MaximumDiversification
+           Fitted estimator.
+        """
+        self._check_feature_names(X, reset=True)
+
+        def func(w, obj):
+            """weighted volatilities"""
+            covariance = obj.prior_estimator_.prior_model_.covariance
+            return np.sqrt(np.diag(covariance)) @ w
+
+        self.overwrite_expected_return = func
+        super().fit(X, y)
+        return self