fix: VAR & CVAR in Portfilio

get_var_historic and get_cvar_historic in Portfolio class use get_rolling_cumulative_return method.

Several docstrings are inserted.

Author: chilango74

main.py

@@ -1,6 +1,7 @@
 import okama as ok
 
-x = ok.AssetList(['ILSRUB.CBR'])
+x = ok.AssetList(['T.US'])
+print(x.dividend_yield)
 
 
 

notebooks/01 howto.ipynb

@@ -5,7 +5,6 @@
 
 from .macro import Inflation
 from .common.helpers import Float, Frame, Date, Index
-# from .common._decorators import doc
 from .settings import default_ticker, PeriodLength, _MONTHS_PER_YEAR
 from .api.data_queries import QueryData
 from .api.namespaces import get_assets_namespaces
@@ -614,8 +613,7 @@ def describe(self, years: Tuple[int, ...] = (1, 5, 10), tickers: bool = True) ->
     @property
     def mean_return(self) -> pd.Series:
         """
-        TODO: Finish description
-        Calculate mean return (arithmetic mean) for the assets.
+        Calculate annualized mean return (arithmetic mean) for the assets.
         """
         df = self._add_inflation()
         mean = df.mean()
@@ -624,7 +622,9 @@ def mean_return(self) -> pd.Series:
     @property
     def real_mean_return(self) -> pd.Series:
         """
-        Calculates real mean return (arithmetic mean) for the assets.
+        Calculates annualized real mean return (arithmetic mean) for the assets.
+
+        Real rate of return is adjusted for inflation.
         """
         if hasattr(self, 'inflation'):
             df = pd.concat([self.ror, self.inflation_ts], axis=1, join='inner', copy='false')
@@ -635,6 +635,9 @@ def real_mean_return(self) -> pd.Series:
         return (1. + ror_mean) / (1. + infl_mean) - 1.
 
     def _get_asset_dividends(self, tick, remove_forecast=True) -> pd.Series:
+        """
+        Get dividend time series for a single symbol.
+        """
         first_period = pd.Period(self.first_date, freq='M')
         first_day = first_period.to_timestamp(how='Start')
         last_period = pd.Period(self.last_date, freq='M')
@@ -649,6 +652,11 @@ def _get_asset_dividends(self, tick, remove_forecast=True) -> pd.Series:
         return s.add(pad_s, fill_value=0)
 
     def _get_dividends(self, remove_forecast=True) -> pd.DataFrame:
+        """
+        Get dividend time series for all assets.
+
+        If remove_forecast=True all forecasted (future) data is removed from time series.
+        """
         if self._dividends_ts.empty:
             dic = {}
             for tick in self.symbols:
@@ -660,9 +668,11 @@ def _get_dividends(self, remove_forecast=True) -> pd.DataFrame:
     @property
     def dividend_yield(self) -> pd.DataFrame:
         """
-        Calculate last twelve months (LTM) dividend yield time series monthly.
-        Calculates yield assuming original asset currency (not adjusting to AssetList currency).
+        Calculate last twelve months (LTM) dividend yield time series (monthly) for each asset.
+
+        All yields are calculated in the original asset currency (not adjusting to AssetList currency).
         Forecast dividends are removed.
+        Zero value time series are created for assets without dividends.
         """
         if self._dividend_yield.empty:
             frame = {}
@@ -701,14 +711,16 @@ def dividend_yield(self) -> pd.DataFrame:
     @property
     def dividends_annual(self) -> pd.DataFrame:
         """
-        Time series of dividends for a calendar year.
+        Return calendar year dividends time series for each asset.
         """
         return self._get_dividends().resample('Y').sum()
 
     @property
     def dividend_growing_years(self) -> pd.DataFrame:
         """
-        Returns the number of growing dividend years for each asset.
+        Return the number of growing dividend years for each asset.
+
+        TODO: finish description. Insert an example
         """
         div_growth = self.dividends_annual.pct_change()[1:]
         df = pd.DataFrame()
@@ -723,7 +735,7 @@ def dividend_growing_years(self) -> pd.DataFrame:
     @property
     def dividend_paying_years(self) -> pd.DataFrame:
         """
-        Returns the number of years of consecutive dividend payments.
+        Return the number of years of consecutive dividend payments for each asset.
         """
         div_annual = self.dividends_annual
         frame = pd.DataFrame()
@@ -738,7 +750,7 @@ def dividend_paying_years(self) -> pd.DataFrame:
 
     def get_dividend_mean_growth_rate(self, period=5) -> pd.Series:
         """
-        Calculates geometric mean of dividends growth rate time series for a certain period.
+        Calculate geometric mean of dividends growth rate time series for a given period.
         Period should be integer and not exceed the available data period_length.
         """
         if period > self.pl.years or not isinstance(period, int):

notebooks/02 index funds perfomance.ipynb

@@ -15,6 +15,7 @@ class Portfolio:
     Implementation of investment portfolio.
     Arguments are similar to AssetList (weights are added), but different behavior.
     Works with monthly end of day historical rate of return data.
+    TODO: rebalance_period should be an attribute
     """
     def __init__(self,
                  symbols: Optional[List[str]] = None, *,
@@ -266,15 +267,64 @@ def semideviation_annual(self) -> float:
         return Frame.get_semideviation(self.returns_ts) * 12 ** 0.5
 
     def get_var_historic(self, time_frame: int = 12, level=5) -> float:
+        """
+        Calculate historic Value at Risk (VaR) for the portfolio.
+
+        The VaR calculates the potential loss of an investment with a given time frame and confidence level.
+        Loss is a positive number (expressed in cumulative return).
+        If VaR is negative there are gains at this confidence level.
+
+        Parameters
+        ----------
+        time_frame : int, default 12 (12 months)
+        level : int, default 5 (5% quantile)
+
+        Returns
+        -------
+        Float
+
+        Examples
+        --------
+        >>> x = ok.Portfolio(['SP500TR.INDX', 'SP500BDT.INDX'], last_date='2021-01')
+        >>> x.get_var_historic(time_frame=12, level=1)
+        0.24030006476701732
+        """
         rolling = self.get_rolling_cumulative_return(window=time_frame)
         return Frame.get_var_historic(rolling, level)
 
     def get_cvar_historic(self, time_frame: int = 12, level=5) -> float:
+        """
+        Calculate historic Conditional Value at Risk (CVAR, expected shortfall) for the portfolio.
+
+        CVaR is the average loss over a specified time period of unlikely scenarios beyond the confidence level.
+        Loss is a positive number (expressed in cumulative return).
+        If CVaR is negative there are gains at this confidence level.
+
+        Parameters
+        ----------
+        time_frame : int, default 12 (12 months)
+        level : int, default 5 (5% quantile)
+
+        Returns
+        -------
+        Float
+
+        Examples
+        --------
+        >>> x = ok.Portfolio(['USDEUR.FX', 'BTC-USD.CC'], last_date='2021-01')
+        >>> x.get_cvar_historic(time_frame=2, level=1)
+        0.3566909250442616
+        """
         rolling = self.get_rolling_cumulative_return(window=time_frame)
         return Frame.get_cvar_historic(rolling, level)
 
     @property
     def drawdowns(self) -> pd.Series:
+        """
+        Calculate drawdowns time series for the portfolio.
+
+        The drawdown is the percent decline from a previous peak in wealth index.
+        """
         return Frame.get_drawdowns(self.returns_ts)
 
     def describe(self, years: Tuple[int] = (1, 5, 10)) -> pd.DataFrame:
@@ -431,10 +481,18 @@ def _test_forecast_period(self, years):
             raise ValueError(f'Forecast period {years} years is not credible. '
                              f'It should not exceed 1/2 of portfolio history period length {self.period_length / 2} years')
 
-    def percentile_inverse(self, distr: str = 'norm', years: int = 1, score: float = 0, n: Optional[int] = None) -> float:
+    def percentile_inverse(self,
+                           distr: str = 'norm',
+                           years: int = 1,
+                           score: float = 0,
+                           n: Optional[int] = None
+                           ) -> float:
         """
-        Compute the percentile rank of a score relative to an array of CAGR values.
-        A percentile_inverse of, for example, 80% means that 80% of the scores in distr are below the given score.
+        Compute the percentile rank of a score (CAGR value) in a given time frame.
+
+        If percentile_inverse of, for example, 0% (CAGR value) is equal to 8% for 1 year time frame
+        it means that 8% of the CAGR values in the distribution are negative in 1 year periods. Or in other words
+        the probability of getting negative result after 1 year of investments is 8%.
 
         Args:
             distr: norm, lognorm, hist - distribution type (normal or lognormal) or hist for CAGR array from history