Add numpy-style docstrings to efficient_cvar, efficient_semivariance, efficient_cdar modules

Co-authored-by: tschm <[email protected]>

Author: Copilot

pypfopt/efficient_frontier/efficient_cdar.py

@@ -1,6 +1,8 @@
 """
-The ``efficient_cdar`` submodule houses the EfficientCDaR class, which
-generates portfolios along the mean-CDaR (conditional drawdown-at-risk) frontier.
+The ``efficient_cdar`` submodule houses the EfficientCDaR class.
+
+This module generates portfolios along the mean-CDaR
+(conditional drawdown-at-risk) frontier.
 """
 
 import warnings
@@ -14,35 +16,37 @@
 
 class EfficientCDaR(EfficientFrontier):
     """
-    The EfficientCDaR class allows for optimisation along the mean-CDaR frontier, using the
-    formulation of Chekhlov, Ursayev and Zabarankin (2005).
-
-    Instance variables:
-
-    - Inputs:
-
-        - ``n_assets`` - int
-        - ``tickers`` - str list
-        - ``bounds`` - float tuple OR (float tuple) list
-        - ``returns`` - pd.DataFrame
-        - ``expected_returns`` - np.ndarray
-        - ``solver`` - str
-        - ``solver_options`` - {str: str} dict
-
-    - Output: ``weights`` - np.ndarray
-
-    Public methods:
-
-    - ``min_cdar()`` minimises the CDaR
-    - ``efficient_risk()`` maximises return for a given CDaR
-    - ``efficient_return()`` minimises CDaR for a given target return
-    - ``add_objective()`` adds a (convex) objective to the optimisation problem
-    - ``add_constraint()`` adds a (linear) constraint to the optimisation problem
-
-    - ``portfolio_performance()`` calculates the expected return and CDaR of the portfolio
-    - ``set_weights()`` creates self.weights (np.ndarray) from a weights dict
-    - ``clean_weights()`` rounds the weights and clips near-zeros.
-    - ``save_weights_to_file()`` saves the weights to csv, json, or txt.
+    Optimization along the mean-CDaR (Conditional Drawdown at Risk) frontier.
+
+    The EfficientCDaR class allows for optimisation along the mean-CDaR
+    frontier, using the formulation of Chekhlov, Ursayev and Zabarankin (2005).
+
+    Attributes
+    ----------
+    n_assets : int
+        Number of assets.
+    tickers : list
+        List of asset tickers.
+    bounds : tuple or list
+        Weight bounds for each asset.
+    returns : pd.DataFrame
+        Historical returns data.
+    expected_returns : np.ndarray
+        Expected returns for each asset.
+    solver : str
+        CVXPY solver name.
+    solver_options : dict
+        Solver parameters.
+    weights : np.ndarray
+        Optimized portfolio weights.
+
+    Examples
+    --------
+    >>> from pypfopt import EfficientCDaR, expected_returns
+    >>> # mu = expected_returns.mean_historical_return(prices)
+    >>> # returns = expected_returns.returns_from_prices(prices)
+    >>> # ef = EfficientCDaR(mu, returns)
+    >>> # weights = ef.min_cdar()
     """
 
     def __init__(
@@ -56,24 +60,35 @@ def __init__(
         solver_options=None,
     ):
         """
-        :param expected_returns: expected returns for each asset. Can be None if
-                                optimising for CDaR only.
-        :type expected_returns: pd.Series, list, np.ndarray
-        :param returns: (historic) returns for all your assets (no NaNs).
-                                 See ``expected_returns.returns_from_prices``.
-        :type returns: pd.DataFrame or np.array
-        :param beta: confidence level, defaults to 0.95 (i.e expected drawdown on the worst (1-beta) days).
-        :param weight_bounds: minimum and maximum weight of each asset OR single min/max pair
-                              if all identical, defaults to (0, 1). Must be changed to (-1, 1)
-                              for portfolios with shorting.
-        :type weight_bounds: tuple OR tuple list, optional
-        :param solver: name of solver. list available solvers with: `cvxpy.installed_solvers()`
-        :type solver: str
-        :param verbose: whether performance and debugging info should be printed, defaults to False
-        :type verbose: bool, optional
-        :param solver_options: parameters for the given solver
-        :type solver_options: dict, optional
-        :raises TypeError: if ``expected_returns`` is not a series, list or array
+        Initialize the EfficientCDaR object.
+
+        Parameters
+        ----------
+        expected_returns : pd.Series, list, or np.ndarray
+            Expected returns for each asset. Can be None if
+            optimising for CDaR only.
+        returns : pd.DataFrame or np.ndarray
+            (Historic) returns for all your assets (no NaNs).
+            See ``expected_returns.returns_from_prices``.
+        beta : float, optional
+            Confidence level, defaults to 0.95 (i.e expected drawdown
+            on the worst (1-beta) days).
+        weight_bounds : tuple or list, optional
+            Minimum and maximum weight of each asset OR single min/max pair
+            if all identical, defaults to (0, 1). Must be changed to (-1, 1)
+            for portfolios with shorting.
+        solver : str, optional
+            Name of solver. List available solvers with ``cvxpy.installed_solvers()``.
+        verbose : bool, optional
+            Whether performance and debugging info should be printed,
+            defaults to False.
+        solver_options : dict, optional
+            Parameters for the given solver.
+
+        Raises
+        ------
+        TypeError
+            If ``expected_returns`` is not a series, list or array.
         """
         super().__init__(
             expected_returns=expected_returns,
@@ -91,10 +106,36 @@ def __init__(
         self._z = cp.Variable(len(self.returns))
 
     def set_weights(self, input_weights):
+        """
+        Override parent method.
+
+        Raises
+        ------
+        NotImplementedError
+            Always, as set_weights is not available in EfficientCDaR.
+        """
         raise NotImplementedError("Method not available in EfficientCDaR.")
 
     @staticmethod
     def _validate_beta(beta):
+        """
+        Validate the beta (confidence level) parameter.
+
+        Parameters
+        ----------
+        beta : float
+            Confidence level.
+
+        Returns
+        -------
+        float
+            Validated beta value.
+
+        Raises
+        ------
+        ValueError
+            If beta is not between 0 and 1.
+        """
         if not (0 <= beta < 1):
             raise ValueError("beta must be between 0 and 1")
         if beta <= 0.2:
@@ -105,23 +146,59 @@ def _validate_beta(beta):
         return beta
 
     def min_volatility(self):
+        """
+        Override parent method.
+
+        Raises
+        ------
+        NotImplementedError
+            Always, as min_volatility is not available in EfficientCDaR.
+            Use min_cdar instead.
+        """
         raise NotImplementedError("Please use min_cdar instead.")
 
     def max_sharpe(self, risk_free_rate=0.0):
+        """
+        Override parent method.
+
+        Raises
+        ------
+        NotImplementedError
+            Always, as max_sharpe is not available in EfficientCDaR.
+        """
         raise NotImplementedError("Method not available in EfficientCDaR.")
 
     def max_quadratic_utility(self, risk_aversion=1, market_neutral=False):
+        """
+        Override parent method.
+
+        Raises
+        ------
+        NotImplementedError
+            Always, as max_quadratic_utility is not available in EfficientCDaR.
+        """
         raise NotImplementedError("Method not available in EfficientCDaR.")
 
     def min_cdar(self, market_neutral=False):
         """
-        Minimise portfolio CDaR (see docs for further explanation).
-
-        :param market_neutral: whether the portfolio should be market neutral (weights sum to zero),
-                               defaults to False. Requires negative lower weight bound.
-        :param market_neutral: bool, optional
-        :return: asset weights for the volatility-minimising portfolio
-        :rtype: OrderedDict
+        Minimise portfolio CDaR (Conditional Drawdown at Risk).
+
+        Parameters
+        ----------
+        market_neutral : bool, optional
+            Whether the portfolio should be market neutral (weights sum to zero),
+            defaults to False. Requires negative lower weight bound.
+
+        Returns
+        -------
+        OrderedDict
+            Asset weights for the CDaR-minimising portfolio.
+
+        Examples
+        --------
+        >>> from pypfopt import EfficientCDaR
+        >>> # ef = EfficientCDaR(mu, returns)
+        >>> # weights = ef.min_cdar()
         """
         self._objective = self._alpha + 1.0 / (
             len(self.returns) * (1 - self._beta)
@@ -138,15 +215,30 @@ def efficient_return(self, target_return, market_neutral=False):
         """
         Minimise CDaR for a given target return.
 
-        :param target_return: the desired return of the resulting portfolio.
-        :type target_return: float
-        :param market_neutral: whether the portfolio should be market neutral (weights sum to zero),
-                               defaults to False. Requires negative lower weight bound.
-        :type market_neutral: bool, optional
-        :raises ValueError: if ``target_return`` is not a positive float
-        :raises ValueError: if no portfolio can be found with return equal to ``target_return``
-        :return: asset weights for the optimal portfolio
-        :rtype: OrderedDict
+        Parameters
+        ----------
+        target_return : float
+            The desired return of the resulting portfolio.
+        market_neutral : bool, optional
+            Whether the portfolio should be market neutral (weights sum to zero),
+            defaults to False. Requires negative lower weight bound.
+
+        Returns
+        -------
+        OrderedDict
+            Asset weights for the optimal portfolio.
+
+        Raises
+        ------
+        ValueError
+            If ``target_return`` is not a positive float.
+            If no portfolio can be found with return equal to ``target_return``.
+
+        Examples
+        --------
+        >>> from pypfopt import EfficientCDaR
+        >>> # ef = EfficientCDaR(mu, returns)
+        >>> # weights = ef.efficient_return(target_return=0.15)
         """
 
         update_existing_parameter = self.is_parameter_defined("target_return")
@@ -165,16 +257,28 @@ def efficient_return(self, target_return, market_neutral=False):
     def efficient_risk(self, target_cdar, market_neutral=False):
         """
         Maximise return for a target CDaR.
+
         The resulting portfolio will have a CDaR less than the target
         (but not guaranteed to be equal).
 
-        :param target_cdar: the desired maximum CDaR of the resulting portfolio.
-        :type target_cdar: float
-        :param market_neutral: whether the portfolio should be market neutral (weights sum to zero),
-                               defaults to False. Requires negative lower weight bound.
-        :param market_neutral: bool, optional
-        :return: asset weights for the efficient risk portfolio
-        :rtype: OrderedDict
+        Parameters
+        ----------
+        target_cdar : float
+            The desired maximum CDaR of the resulting portfolio.
+        market_neutral : bool, optional
+            Whether the portfolio should be market neutral (weights sum to zero),
+            defaults to False. Requires negative lower weight bound.
+
+        Returns
+        -------
+        OrderedDict
+            Asset weights for the efficient risk portfolio.
+
+        Examples
+        --------
+        >>> from pypfopt import EfficientCDaR
+        >>> # ef = EfficientCDaR(mu, returns)
+        >>> # weights = ef.efficient_risk(target_cdar=0.10)
         """
 
         update_existing_parameter = self.is_parameter_defined("target_cdar")
@@ -202,6 +306,12 @@ def efficient_risk(self, target_cdar, market_neutral=False):
         return self._solve_cvxpy_opt_problem()
 
     def _add_cdar_constraints(self) -> None:
+        """
+        Add the CDaR-specific constraints to the optimization problem.
+
+        This method adds the constraints required for CDaR optimization
+        to the CVXPY problem.
+        """
         self.add_constraint(lambda _: self._z >= self._u[1:] - self._alpha)
         self.add_constraint(
             lambda w: self._u[1:] >= self._u[:-1] - self.returns.values @ w
@@ -212,14 +322,32 @@ def _add_cdar_constraints(self) -> None:
 
     def portfolio_performance(self, verbose=False):
         """
-        After optimising, calculate (and optionally print) the performance of the optimal
-        portfolio, specifically: expected return, CDaR
-
-        :param verbose: whether performance should be printed, defaults to False
-        :type verbose: bool, optional
-        :raises ValueError: if weights have not been calculated yet
-        :return: expected return, CDaR.
-        :rtype: (float, float)
+        Calculate the performance of the optimal portfolio.
+
+        After optimising, calculate (and optionally print) the performance
+        of the optimal portfolio, specifically: expected return, CDaR.
+
+        Parameters
+        ----------
+        verbose : bool, optional
+            Whether performance should be printed, defaults to False.
+
+        Returns
+        -------
+        tuple
+            A tuple of (expected return, CDaR).
+
+        Raises
+        ------
+        ValueError
+            If weights have not been calculated yet.
+
+        Examples
+        --------
+        >>> from pypfopt import EfficientCDaR
+        >>> # ef = EfficientCDaR(mu, returns)
+        >>> # ef.min_cdar()
+        >>> # mu, cdar = ef.portfolio_performance(verbose=True)
         """
         mu = objective_functions.portfolio_return(
             self.weights, self.expected_returns, negative=False