feat: Portfolio has .get_cagr method

- Portfolio .cagr property is replaced with .get_cagr ('YTD', period length or no parameters)
- Portfolio .describe shows dividend yield
- EfficientFrontier.__repr__ is fixed
- only relative imports in the package
- tests modules import okama as ok
- several unit tests added

Author: chilango74

README.md

@@ -4,7 +4,7 @@
         <img src="https://img.shields.io/badge/python-v3-brightgreen.svg"
             alt="python"></a> &nbsp;
     <a href="https://pypi.org/project/okama/">
-        <img src="https://img.shields.io/badge/pypi-v0.94-brightgreen.svg"
+        <img src="https://img.shields.io/badge/pypi-v0.95-brightgreen.svg"
             alt="pypi"></a> &nbsp;
     <a href="https://opensource.org/licenses/MIT">
         <img src="https://img.shields.io/badge/license-MIT-brightgreen.svg"

main.py

@@ -1,4 +1,6 @@
 import okama as ok
 
-x = ok.AssetList(['SXR8.XETR', 'SXRG.XETR', 'XRS2.XETR'])
-print(x.get_cagr(5))
+x = ok.Portfolio(symbols=['SBER.MOEX', 'T.US'], ccy='RUB', last_date='2020-01', inflation=True)
+# print(x.get_cagr('YTD'))
+print(x.describe())
+

okama/__init__.py

@@ -33,4 +33,4 @@
 from okama.helpers import Float, Frame, Rebalance, Date
 import okama.settings
 
-__version__ = '0.94'
+__version__ = '0.95'

okama/assets.py

@@ -108,17 +108,16 @@ def __init__(self,
             self.inflation_ts: pd.Series = self._inflation_instance.values_ts
             self.inflation_first_date: pd.Timestamp = self._inflation_instance.first_date
             self.inflation_last_date: pd.Timestamp = self._inflation_instance.last_date
-            self.first_date: pd.Timestamp = max(self.first_date, self.inflation_first_date)
+            self.first_date = max(self.first_date, self.inflation_first_date)
             self.last_date: pd.Timestamp = min(self.last_date, self.inflation_last_date)
             # Add inflation to the date range dict
             self.assets_first_dates.update({self.inflation: self.inflation_first_date})
             self.assets_last_dates.update({self.inflation: self.inflation_last_date})
         if first_date:
-            self.first_date: pd.Timestamp = max(self.first_date, pd.to_datetime(first_date))
+            self.first_date = max(self.first_date, pd.to_datetime(first_date))
         self.ror = self.ror[self.first_date:]
         if last_date:
-            # TODO: self.assets_last_dates should be less or equal to self.last_date
-            self.last_date: pd.Timestamp = min(self.last_date, pd.to_datetime(last_date))
+            self.last_date = min(self.last_date, pd.to_datetime(last_date))
         self.ror: pd.DataFrame = self.ror[self.first_date: self.last_date]
         self.period_length: float = round((self.last_date - self.first_date) / np.timedelta64(365, 'D'), ndigits=1)
         self.pl = PeriodLength(self.ror.shape[0] // _MONTHS_PER_YEAR, self.ror.shape[0] % _MONTHS_PER_YEAR)
@@ -148,6 +147,7 @@ def __make_asset_list(self, ls: list) -> None:
         last_dates: Dict[str, pd.Timestamp] = {}
         names: Dict[str, str] = {}
         currencies: Dict[str, str] = {}
+        df = pd.DataFrame()
         for i, x in enumerate(ls):
             asset = Asset(x)
             if i == 0:
@@ -169,8 +169,8 @@ def __make_asset_list(self, ls: list) -> None:
         first_dates.update({self.currency.name: self.currency.first_date})
         last_dates.update({self.currency.name: self.currency.last_date})
 
-        first_dates_sorted = sorted(first_dates.items(), key=lambda x: x[1])
-        last_dates_sorted = sorted(last_dates.items(), key=lambda x: x[1])
+        first_dates_sorted = sorted(first_dates.items(), key=lambda y: y[1])
+        last_dates_sorted = sorted(last_dates.items(), key=lambda y: y[1])
         self.first_date: pd.Timestamp = first_dates_sorted[-1][1]
         self.last_date: pd.Timestamp = last_dates_sorted[0][1]
         self.newest_asset: str = first_dates_sorted[-1][0]
@@ -254,7 +254,7 @@ def semideviation_annual(self) -> float:
         """
         Returns semideviation annual values for each asset (full period).
         """
-        return Frame.get_semideviation(self.returns_ts) * 12 ** 0.5
+        return Frame.get_semideviation(self.ror) * 12 ** 0.5
 
     def get_var_historic(self, level: int = 5) -> pd.Series:
         """
@@ -292,7 +292,7 @@ def get_cagr(self, period: Union[str, int, None] = None) -> pd.Series:
 
         if not period:
             cagr = Frame.get_cagr(df)
-        elif period == 'YTD':
+        elif str(period).lower() == 'ytd':
             year = dt0.year
             cagr = (df[str(year):] + 1.).prod() - 1.
         elif isinstance(period, int):
@@ -665,7 +665,7 @@ def jarque_bera(self):
         """
         return Frame.jarque_bera_dataframe(self.ror)
 
-    def kstest(self, distr: str = 'norm') -> dict:
+    def kstest(self, distr: str = 'norm') -> pd.DataFrame:
         """
         Perform Kolmogorov-Smirnov test for goodness of fit the asset returns to a given distribution.
 

okama/frontier/multi_period.py

@@ -6,9 +6,9 @@
 
 from scipy.optimize import minimize
 
-from okama.helpers import Float, Frame, Rebalance
-from okama.assets import AssetList
-from okama.settings import _MONTHS_PER_YEAR
+from ..helpers import Float, Frame, Rebalance
+from ..assets import AssetList
+from ..settings import _MONTHS_PER_YEAR
 
 
 class EfficientFrontierReb(AssetList):

okama/frontier/single_period.py

@@ -43,7 +43,6 @@ def __repr__(self):
             'first date': self.first_date.strftime("%Y-%m"),
             'last_date': self.last_date.strftime("%Y-%m"),
             'period length': self._pl_txt,
-            'rebalancing period': self.reb_period,
             'inflation': self.inflation if hasattr(self, 'inflation') else 'None',
         }
         return repr(pd.Series(dic))

okama/helpers.py

@@ -207,7 +207,8 @@ def get_semideviation(ror: Union[pd.DataFrame, pd.Series]) -> Union[pd.Series, f
         Returns semideviation for each asset given returns time series.
         """
         is_negative = ror < 0
-        return ror[is_negative].std(ddof=0)
+        sem = ror[is_negative].std(ddof=0)
+        return sem
 
     @staticmethod
     def get_var_historic(ror: Union[pd.DataFrame, pd.Series], level: int = 5) -> Union[pd.Series, float]:
@@ -269,7 +270,7 @@ def skewness_rolling(ror: Union[pd.DataFrame, pd.Series], window: int = 60) -> U
         return sk
 
     @staticmethod
-    def kurtosis(ror: pd.Series):
+    def kurtosis(ror: Union[pd.Series, pd.DataFrame]):
         """
         Calculate expanding Fisher (normalized) kurtosis time series.
         Kurtosis should be close to zero for normal distribution.
@@ -286,8 +287,7 @@ def kurtosis_rolling(ror: Union[pd.Series, pd.DataFrame], window: int = 60):
         """
         check_rolling_window(window, ror)
         kt = ror.rolling(window=window).kurt()
-        kt.dropna(inplace=True)
-        return kt
+        return kt.dropna()
 
     @staticmethod
     def jarque_bera_series(ror: pd.Series) -> dict:

okama/macro.py

@@ -1,16 +1,21 @@
 from abc import ABC, abstractmethod
+from typing import Union
 
 import numpy as np
 import pandas as pd
 
-from okama.api.data_queries import QueryData
-from okama.api.namespaces import get_macro_namespaces
-from okama.helpers import Float, Frame, Date
-from okama.settings import default_macro, PeriodLength, _MONTHS_PER_YEAR
+from .api.data_queries import QueryData
+from .api.namespaces import get_macro_namespaces
+from .helpers import Float, Frame, Date
+from .settings import default_macro, PeriodLength, _MONTHS_PER_YEAR
 
 
 class MacroABC(ABC):
-    def __init__(self, symbol: str = default_macro, first_date: str = '1800-01', last_date: str = '2030-01'):
+    def __init__(self,
+                 symbol: str = default_macro,
+                 first_date: Union[str, pd.Timestamp] = '1800-01',
+                 last_date: Union[str, pd.Timestamp] = '2030-01'
+                 ):
         self.symbol: str = symbol
         self._check_namespace()
         self._get_symbol_data(symbol)

okama/plots.py

@@ -100,10 +100,10 @@ def plot_transition_map(self, bounds=None, full_frontier=False, cagr=True) -> pl
                                n_points=10
                                ).ef_points
         self._verify_axes()
-        x_axe = 'CAGR (approx)' if cagr else 'Risk'
+        x_axe = 'CAGR' if cagr else 'Risk'
         fig = plt.figure(figsize=(12, 6))
         for i in ef:
-            if i not in ('Risk', 'Mean return', 'CAGR (approx)'):  # select only columns with tickers
+            if i not in ('Risk', 'Mean return', 'CAGR'):  # select only columns with tickers
                 self.ax.plot(ef[x_axe], ef.loc[:, i], label=i)
         self.ax.set_xlim(ef[x_axe].min(), ef[x_axe].max())
         if cagr:

okama/portfolio.py

@@ -117,13 +117,34 @@ def mean_return_monthly(self) -> float:
     def mean_return_annual(self) -> float:
         return Float.annualize_return(self.mean_return_monthly)
 
-    @property
-    def cagr(self) -> Union[pd.Series, float]:
+    def get_cagr(self, period: Union[str, int, None] = None) -> pd.Series:
+        """
+        Calculates Compound Annual Growth Rate (CAGR) for a given period:
+        None: full time
+        'YTD': Year To Date compound rate of return (formally not a CAGR)
+        Integer: several years
+        """
         if hasattr(self, 'inflation'):
             df = pd.concat([self.returns_ts, self.inflation_ts], axis=1, join='inner', copy='false')
         else:
             df = self.returns_ts
-        return Frame.get_cagr(df)
+        dt0 = self.last_date
+
+        if not period:
+            cagr = Frame.get_cagr(df)
+        elif str(period).lower() == 'ytd':
+            year = dt0.year
+            cagr = (df[str(year):] + 1.).prod() - 1.
+        elif isinstance(period, int):
+            dt = Date.subtract_years(dt0, period)
+            if dt >= self.first_date:
+                cagr = Frame.get_cagr(df[dt:])
+            else:
+                row = {x: None for x in df.columns}
+                cagr = pd.Series(row)
+        else:
+            raise ValueError(f'{period} is not a valid value for period')
+        return cagr
 
     @property
     def annual_return_ts(self) -> pd.DataFrame:
@@ -134,6 +155,8 @@ def dividend_yield(self) -> pd.DataFrame:
         """
         Calculates dividend yield time series in all base currencies of portfolio assets.
         For every currency dividend yield is a weighted sum of the assets dividend yields.
+        Portfolio asset allocation (weights) is a constant (monthly rebalanced portfolios).
+        TODO: calculate for not rebalance portfolios (and arbitrary reb period).
         """
         div_yield_assets = self._list.dividend_yield
         currencies_dict = self._list.currencies
@@ -144,6 +167,7 @@ def dividend_yield(self) -> pd.DataFrame:
         for currency in currencies_list:
             assets_with_the_same_currency = [x for x in currencies_dict if currencies_dict[x] == currency]
             df = div_yield_assets[assets_with_the_same_currency]
+            # for monthly rebalanced portfolio
             weights = [self.assets_weights[k] for k in self.assets_weights if k in assets_with_the_same_currency]
             weighted_weights = np.asarray(weights) / np.asarray(weights).sum()
             div_yield_series = Frame.get_portfolio_return_ts(weighted_weights, df)
@@ -223,10 +247,10 @@ def describe(self, years: Tuple[int] = (1, 5, 10)) -> pd.DataFrame:
         else:
             row = {'portfolio': value}
         row.update({'period': 'YTD'})
-        row.update({'rebalancing': 'Not rebalanced'})
+        row.update({'rebalancing': '1 year'})
         row.update({'property': 'compound return'})
         description = description.append(row, ignore_index=True)
-        # CAGR for a list of periods (rebalanced 1 month)
+        # CAGR for a list of periods (rebalanced 1 year)
         for i in years:
             dt = Date.subtract_years(dt0, i)
             if dt >= self.first_date:
@@ -258,7 +282,7 @@ def describe(self, years: Tuple[int] = (1, 5, 10)) -> pd.DataFrame:
         row.update({'property': 'CAGR'})
         description = description.append(row, ignore_index=True)
         # CAGR rebalanced 1 month
-        value = self.cagr
+        value = self.get_cagr()
         if hasattr(self, 'inflation'):
             row = value.to_dict()
             full_inflation = value.loc[self.inflation]  # full period inflation is required for following calc
@@ -278,6 +302,15 @@ def describe(self, years: Tuple[int] = (1, 5, 10)) -> pd.DataFrame:
         row.update({'rebalancing': 'Not rebalanced'})
         row.update({'property': 'CAGR'})
         description = description.append(row, ignore_index=True)
+        # Dividend Yield
+        dy = self.dividend_yield
+        for i, ccy in enumerate(dy):
+            value = self.dividend_yield.iloc[-1, i]
+            row = {'portfolio': value}
+            row.update({'period': 'LTM'})
+            row.update({'rebalancing': '1 month'})
+            row.update({'property': f'Dividend yield ({ccy})'})
+            description = description.append(row, ignore_index=True)
         # risk (rebalanced 1 month)
         row = {'portfolio': self.risk_annual}
         row.update({'period': f'{self.period_length} years'})
@@ -319,8 +352,9 @@ def table(self) -> pd.DataFrame:
     def get_rolling_cagr(self, years: int = 1) -> pd.Series:
         """
         Rolling portfolio CAGR (annualized rate of return) time series.
-        TODO: check if self.period_length is below 1 year
         """
+        if self.pl.years < 1:
+            raise ValueError('Portfolio history data period length should be at least 12 months.')
         rolling_return = (self.returns_ts + 1.).rolling(_MONTHS_PER_YEAR * years).apply(np.prod, raw=True) ** (1 / years) - 1.
         rolling_return.dropna(inplace=True)
         return rolling_return