feat: Portfolio.recovery_period must return a time series of recovery periods

Author: chilango74

examples/01 howto.ipynb

@@ -615,7 +615,7 @@
     }
    ],
    "source": [
-    "x.assets_dividend_yield"
+    "x.dividend_yield"
    ]
   },
   {
@@ -642,7 +642,7 @@
     }
    ],
    "source": [
-    "x.assets_dividend_yield.plot();"
+    "x.dividend_yield.plot();"
    ]
   },
   {

examples/03 investment portfolios.ipynb

@@ -2,17 +2,17 @@
 
 import okama as ok
 # Portfolio WithDrawls
-weights = [0.32, 0.31,  0.18, .19]
-portf = ok.Portfolio(['RGBITR.INDX', 'RUCBTRNS.INDX', 'MCFTR.INDX', 'GC.COMM'],
-                     ccy="RUB",
-                     weights=weights,
-                     inflation=False,
-                     symbol="retirement_portf.PF",
-                     rebalancing_period='year',
-                     cashflow=-150_000,
-                     initial_amount=39_000_000,
-                     discount_rate=0.01
-                     )
+# weights = [0.32, 0.31,  0.18, .19]
+# portf = ok.Portfolio(['RGBITR.INDX', 'RUCBTRNS.INDX', 'MCFTR.INDX', 'GC.COMM'],
+#                      ccy="RUB",
+#                      weights=weights,
+#                      inflation=False,
+#                      symbol="retirement_portf.PF",
+#                      rebalancing_period='year',
+#                      cashflow=-150_000,
+#                      initial_amount=39_000_000,
+#                      discount_rate=0.01
+#                      )
 
 # print(portf.discount_rate)
 # print(portf)
@@ -24,14 +24,14 @@
 #
 # portf.plot_forecast_monte_carlo(distr="norm", years=30, backtest=True, n=100)
 
-s_periods = portf.monte_carlo_survival_period(distr="lognorm", years=25, n=10)
-print(f"медиана {s_periods.quantile(50 / 100)}")
+# s_periods = portf.monte_carlo_survival_period(distr="lognorm", years=25, n=10)
+# print(f"медиана {s_periods.quantile(50 / 100)}")
 # print(f"первый порцентиль {s_periods.quantile(1 / 100)}")
 # print(f"99й порцентиль {s_periods.quantile(99 / 100)}")
 # print(f"минимум {s_periods.min()}")
 # print(f"среднее {s_periods.mean()}")
 
-plt.show()
+# plt.show()
 
 # Rolling / Expanding Risk
 # al = ok.AssetList(['DJI.INDX',
@@ -46,3 +46,9 @@
 # pf = ok.Portfolio(['SPY.US',
 #                    'BND.US'
 #                    ])
+rf3 = ok.Portfolio(
+    ["BND.US", "VTI.US", "VXUS.US"],
+    weights=[0.40, 0.40, 0.20],
+    rebalancing_period="year",
+)
+print(rf3.recovery_period)

main.py

@@ -267,7 +267,7 @@ def _get_single_asset_dividends(self, tick: str, remove_forecast: bool = True) -
         if asset.currency != self.currency:
             s = self._adjust_price_to_currency_monthly(s, asset.currency)
         if remove_forecast:
-            s = s[: pd.Period.now("M")]  # Period.now() must be without arguments to be compatible with pandas 2.0
+            s = s[: pd.Period.now(freq="M")]  # Period.now() must be without arguments to be compatible with pandas 2.0
         # Create time series with zeros to pad the empty spaces in dividends time series
         index = pd.date_range(start=self.first_date, end=self.last_date, freq="MS")  # 'MS' to include the last period
         period = index.to_period("M")

okama/common/make_asset_list.py

@@ -1301,47 +1301,44 @@ def drawdowns(self) -> pd.Series:
         return helpers.Frame.get_drawdowns(self.ror)
 
     @property
-    def recovery_period(self) -> int:
+    def recovery_period(self) -> pd.Series:
         """
-        Calculate the longest recovery period for the portfolio assets value.
+        Get recovery period time series for the portfolio value.
 
         The recovery period (drawdown duration) is the number of months to reach the value of the last maximum.
 
         Returns
         -------
-        Integer
-            Max recovery period for the protfolio assets value in months.
+        pd.Series
+            Recovery period time series for the portfolio value
 
         Notes
         -----
-        If the last maximum value is not recovered NaN is returned.
         The largest recovery period does not necessary correspond to the max drawdown.
 
         Examples
         --------
         >>> pf = ok.Portfolio(['SPY.US', 'AGG.US'], weights=[0.5, 0.5])
-        >>> pf.recovery_period
-        35
+        >>> pf.recovery_period.nlargest()
+        date
+        2010-10    35
+        2004-10     7
+        2012-01     7
+        2019-03     6
+        2018-07     5
+        Freq: M, Name: portfolio_5724.PF, dtype: int32
 
         See Also
         --------
         drawdowns : Calculate drawdowns time series.
         """
-        if hasattr(self, "inflation"):
-            w_index = self.wealth_index.drop(columns=[self.inflation])
-        else:
-            w_index = self.wealth_index
-        if isinstance(w_index, pd.DataFrame):
-            # time series should be a Series to use groupby
-            w_index = w_index.squeeze()
+        w_index = self.wealth_index_with_assets[self.symbol]
         cummax = w_index.cummax()
         s = cummax.pct_change()[1:]
         s1 = s.where(s == 0).notnull().astype(int)
         s1_1 = s.where(s == 0).isnull().astype(int).cumsum()
         s2 = s1.groupby(s1_1).cumsum()
-        # Max recovery period date should not be in the border (means it's not recovered)
-        max_period = s2.max() if s2.idxmax().to_timestamp() != self.last_date else np.NAN
-        return max_period
+        return s2[s2.shift(-1) < s2]
 
     def describe(self, years: Tuple[int] = (1, 5, 10)) -> pd.DataFrame:
         """

okama/portfolio.py

@@ -176,7 +176,7 @@ def test_drawdowns(portfolio_not_rebalanced):
 
 
 def test_recovery_period(portfolio_not_rebalanced):
-    assert portfolio_not_rebalanced.recovery_period == 6
+    assert portfolio_not_rebalanced.recovery_period.max() == 6
 
 
 def test_get_cagr(portfolio_rebalanced_month, portfolio_no_inflation):