Documented all

garpar/core/__init__.py

@@ -4,4 +4,6 @@
 # License: MIT
 #   Full Text: https://github.com/quatrope/garpar/blob/master/LICENSE
 
+"""Core utilities."""
+
 from .portfolio import GARPAR_METADATA_KEY, Portfolio

garpar/core/covcorr_acc.py

@@ -4,45 +4,132 @@
 # License: MIT
 #   Full Text: https://github.com/quatrope/garpar/blob/master/LICENSE
 
+"""Covariance Accessor."""
+
 import attr
 
 from pypfopt import risk_models
 
 from ..utils import accabc
 
 # =============================================================================
-#
+# COVARIANCE ACCESSOR
 # =============================================================================
 
 
 @attr.s(frozen=True, cmp=False, slots=True, repr=False)
 class CovarianceAccessor(accabc.AccessorABC):
+    """Accessor class for calculating various covariance matrices.
+
+    Attributes
+    ----------
+    _default_kind : str
+        Default kind of covariance matrix.
+    _pf : Portfolio
+        Portfolio object containing prices data.
+
+    Methods
+    -------
+    sample_cov(**kwargs)
+        Compute the sample covariance matrix.
+    exp_cov(**kwargs)
+        Compute the exponentially-weighted covariance matrix.
+    semi_cov(**kwargs)
+        Compute the semi-covariance matrix.
+    ledoit_wolf_cov(shrinkage_target="constant_variance", **kwargs)
+        Compute the Ledoit-Wolf covariance matrix with optional shrinkage target.
+    oracle_approximating_cov(**kwargs)
+        Compute the Oracle-approximating covariance matrix.
+    """
+
     _default_kind = "sample_cov"
 
     _pf = attr.ib()
 
     def sample_cov(self, **kwargs):
+        """Compute the sample covariance matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `risk_models.sample_cov`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Sample covariance matrix.
+        """
         return risk_models.sample_cov(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )
 
     def exp_cov(self, **kwargs):
+        """Compute the exponentially-weighted covariance matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `risk_models.exp_cov`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Exponentially-weighted covariance matrix.
+        """
         return risk_models.exp_cov(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )
 
     def semi_cov(self, **kwargs):
+        """Compute the semi-covariance matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `risk_models.semicovariance`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Semi-covariance matrix.
+        """
         return risk_models.semicovariance(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )
 
     def ledoit_wolf_cov(self, shrinkage_target="constant_variance", **kwargs):
+        """Compute the Ledoit-Wolf covariance matrix with optional shrinkage target.
+
+        Parameters
+        ----------
+        shrinkage_target : str, optional
+            Shrinkage target for Ledoit-Wolf covariance estimation, default is "constant_variance".
+        **kwargs
+            Additional keyword arguments passed to `risk_models.CovarianceShrinkage.ledoit_wolf`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Ledoit-Wolf covariance matrix.
+        """
         covshrink = risk_models.CovarianceShrinkage(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )
         return covshrink.ledoit_wolf(shrinkage_target=shrinkage_target)
 
     def oracle_approximating_cov(self, **kwargs):
+        """Compute the Oracle-approximating covariance matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `risk_models.CovarianceShrinkage.oracle_approximating`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Oracle-approximating covariance matrix.
+        """
         covshrink = risk_models.CovarianceShrinkage(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )
@@ -51,26 +138,109 @@ def oracle_approximating_cov(self, **kwargs):
 
 @attr.s(frozen=True, cmp=False, slots=True, repr=False)
 class CorrelationAccessor(accabc.AccessorABC):
+    """Accessor class for calculating various correlation matrices.
+
+    Attributes
+    ----------
+    _default_kind : str
+        Default kind of correlation matrix.
+    _pf : Portfolio
+        Portfolio object containing prices data.
+
+    Methods
+    -------
+    sample_corr(**kwargs)
+        Compute the sample correlation matrix.
+    exp_corr(**kwargs)
+        Compute the exponentially-weighted correlation matrix.
+    semi_corr(**kwargs)
+        Compute the semi-correlation matrix.
+    ledoit_wolf_corr(**kwargs)
+        Compute the Ledoit-Wolf correlation matrix.
+    oracle_approximating_corr(**kwargs)
+        Compute the Oracle-approximating correlation matrix.
+    """
+
     _default_kind = "sample_corr"
 
     _pf = attr.ib()
 
     def sample_corr(self, **kwargs):
+        """Compute the sample correlation matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `self._pf.covariance.sample_cov`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Sample correlation matrix.
+        """
         cov = self._pf.covariance.sample_cov(**kwargs)
         return risk_models.cov_to_corr(cov)
 
     def exp_corr(self, **kwargs):
+        """Compute the exponentially-weighted correlation matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `self._pf.covariance.exp_cov`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Exponentially-weighted correlation matrix.
+        """
         cov = self._pf.covariance.exp_cov(**kwargs)
         return risk_models.cov_to_corr(cov)
 
     def semi_corr(self, **kwargs):
+        """Compute the semi-correlation matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `self._pf.covariance.semi_cov`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Semi-correlation matrix.
+        """
         cov = self._pf.covariance.semi_cov(**kwargs)
         return risk_models.cov_to_corr(cov)
 
     def ledoit_wolf_corr(self, **kwargs):
+        """Compute the Ledoit-Wolf correlation matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `self._pf.covariance.ledoit_wolf_cov`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Ledoit-Wolf correlation matrix.
+        """
         cov = self._pf.covariance.ledoit_wolf_cov(**kwargs)
         return risk_models.cov_to_corr(cov)
 
     def oracle_approximating_corr(self, **kwargs):
+        """Compute the Oracle-approximating correlation matrix.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to `self._pf.covariance.oracle_approximating_cov`.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Oracle-approximating correlation matrix.
+        """
         cov = self._pf.covariance.oracle_approximating_cov(**kwargs)
         return risk_models.cov_to_corr(cov)

garpar/core/ereturns_acc.py

@@ -4,38 +4,95 @@
 # License: MIT
 #   Full Text: https://github.com/quatrope/garpar/blob/master/LICENSE
 
+"""Expected Returns Accessor."""
+
 import attr
 
 from pypfopt import expected_returns
 
 from ..utils import accabc
 
 # =============================================================================
-#
+# EXPECTED RETURNS
 # =============================================================================
 
 
 @attr.s(frozen=True, cmp=False, slots=True, repr=False)
 class ExpectedReturnsAccessor(accabc.AccessorABC):
+    """Accessor class for computing expected returns of a portfolio.
+
+    Attributes
+    ----------
+    _default_kind : str
+        Default method for computing expected returns.
+    _pf : Portfolio
+        Portfolio object containing prices data.
+
+    Methods
+    -------
+    capm(**kwargs)
+        Compute expected returns using the CAPM method.
+    mah(**kwargs)
+        Compute expected returns using the mean historical method.
+    emah(**kwargs)
+        Compute expected returns using the exponential moving average historical method.
+    """
+
     _default_kind = "capm"
 
     _pf = attr.ib()
 
     def capm(self, **kwargs):
+        """Compute expected returns using the CAPM (Capital Asset Pricing Model) method.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to expected_returns.capm_return.
+
+        Returns
+        -------
+        pandas.Series
+            Series containing computed expected returns with name "CAPM".
+        """
         returns = expected_returns.capm_return(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )
         returns.name = "CAPM"
         return returns
 
     def mah(self, **kwargs):
+        """Compute expected returns using the mean historical method.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to expected_returns.mean_historical_return.
+
+        Returns
+        -------
+        pandas.Series
+            Series containing computed expected returns with name "MAH".
+        """
         returns = expected_returns.mean_historical_return(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )
         returns.name = "MAH"
         return returns
 
     def emah(self, **kwargs):
+        """Compute expected returns using the exponential moving average historical method.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional keyword arguments passed to expected_returns.ema_historical_return.
+
+        Returns
+        -------
+        pandas.Series
+            Series containing computed expected returns with name "EMAH".
+        """
         returns = expected_returns.ema_historical_return(
             prices=self._pf._prices_df, returns_data=False, **kwargs
         )