From 85e00c7e5d54bad7af86b486a2a31cbe0bfba1bb Mon Sep 17 00:00:00 2001
From: Vladimir Khomyakov <vkhomyakov15@yandex.ru>
Date: Tue, 26 Dec 2023 14:02:24 +0300
Subject: [PATCH] feat: #64 add dividend_yeld_annual property in Portfolio like
 the same property in the AssetList

---
 main.py                 |  5 ++---
 okama/asset_list.py     |  2 +-
 okama/portfolio.py      | 36 ++++++++++++++++++++++++++++++++++++
 tests/test_portfolio.py |  2 ++
 4 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/main.py b/main.py
index 81f7c34..0f2494c 100644
--- a/main.py
+++ b/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()
\ No newline at end of file
diff --git a/okama/asset_list.py b/okama/asset_list.py
index 8647610..621856b 100644
--- a/okama/asset_list.py
+++ b/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()
diff --git a/okama/portfolio.py b/okama/portfolio.py
index 5abeec1..c2237fd 100644
--- a/okama/portfolio.py
+++ b/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):
         """
diff --git a/tests/test_portfolio.py b/tests/test_portfolio.py
index 0e8b03c..da54d7d 100644
--- a/tests/test_portfolio.py
+++ b/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)