feat: #64 add dividend_yeld_annual property in Portfolio like the same property in the AssetList

Author: vkhomyakov

main.py

@@ -10,8 +10,7 @@
 #pf.wealth_index_with_assets.plot()
 #plt.show()
 
-
 import matplotlib.pyplot as plt
-pf = ok.Portfolio(['SPY.US', 'BND.US'], ccy='USD', last_date='07-2021', rebalancing_period="monthly")
-pf.dividends_annual.plot(kind='bar')
+pf = ok.Portfolio(['SPY.US', 'BND.US'], ccy='USD', last_date='07-2021')
+pf.dividend_yield_annual.plot(kind='bar')
 plt.show()

okama/asset_list.py

@@ -916,7 +916,7 @@ def dividend_yield_annual(self):
         --------
         >>> import matplotlib.pyplot as plt
         >>> x = ok.AssetList(['T.US', 'XOM.US'], first_date='2010-01', last_date='2020-12')
-        >>> x.dividends_annual.plot(kind='bar')
+        >>> x.dividend_yield_annual.plot(kind='bar')
         >>> plt.show()
         """
         return self._assets_dividend_yield.resample(rule="Y").last()

okama/portfolio.py

@@ -839,6 +839,42 @@ def dividends_annual(self) -> pd.DataFrame:
         """
         return self._get_assets_dividends().resample("Y").sum()
 
+    @property
+    def dividend_yield_annual(self):
+        """
+        Calculate last twelve months (LTM) dividend yield annual time series.
+
+        Time series is based on the dividend yield for the end of calendar year.
+
+        LTM dividend yield is the sum trailing twelve months of common dividends per share divided by
+        the current price per share.
+
+        All yields are calculated in the asset list base currency after adjusting the dividends and price time series.
+        Forecasted (future) dividends are removed.
+
+        Returns
+        -------
+        DataFrame
+            Time series of LTM dividend yield for each asset.
+
+        See Also
+        --------
+        dividend_yield : Dividend yield time series.
+        dividends_annual : Calendar year dividends time series.
+        dividend_paying_years : Number of years of consecutive dividend payments.
+        dividend_growing_years : Number of years when the annual dividend was growing.
+        get_dividend_mean_yield : Arithmetic mean for annual dividend yield.
+        get_dividend_mean_growth_rate : Geometric mean of annual dividends growth rate.
+
+        Examples
+        --------
+        >>> import matplotlib.pyplot as plt
+        >>> pf = ok.Portfolio(['SPY.US', 'BND.US'], ccy='USD', last_date='07-2021')
+        >>> pf.dividend_yield_annual.plot(kind='bar')
+        >>> plt.show()
+        """
+        return self._assets_dividend_yield.resample(rule="Y").last()
+
     @property
     def assets_dividend_yield(self):
         """

tests/test_portfolio.py

@@ -145,6 +145,8 @@ def test_dividend_yield(portfolio_dividends):
 def test_dividends_annual(portfolio_dividends):
     assert portfolio_dividends.dividends_annual.iloc[-1].sum() == approx(32.778668, rel=1e-3)
 
+def test_dividend_yield_annual(portfolio_dividends):
+    assert portfolio_dividends.dividend_yield_annual.iloc[0, 0] == approx(0.004444, abs=1e-3)
 
 def test_risk(portfolio_rebalanced_month):
     assert portfolio_rebalanced_month.risk_monthly == approx(0.02233, rel=1e-1)