Okama 1.4.0 introduces investment strategies with contributions and withdrawals in `Portfolio` class. New methods support discounted cash flows (DCF) and Monte Carlo simulation for portfolio longevity.
<img src="https://github.com/mbk-dev/okama/assets/29829921/68dfc965-0663-48f1-a08e-f26d47b2f892" width=70%>
New features
DCF methods for contributions and withdrawals in `Portfolio` class
**New `Portfolio` class attributes (all are optional):**
- `initial_amount` - Portfolio initial investment FV (at last_date)
- `cashflow` - portfolio monthly cash flow FV (at last_date). Negative value corresponds to withdrawals.
Positive value corresponds to contributions. Cash flow value is indexed each month by inflation.
- `discount_rate` - cash flow discount rate required to calculate PV values.
**New `dcf.` methods in `Portfolio` class:**
- `dcf.plot_forecast_monte_carlo()` method to plot Monte Carlo simulation for portfolio future wealth indexes optionally together with historical wealth index.
- `dcf.monte_carlo_survival_period()` method to generate a survival period distribution for a portfolio with cash flows by Monte Carlo simulation.
- `dcf.wealth_index` property to calculate wealth index time series for the portfolio with contributions and
withdrawals.
- `dcf.survival_period` property to calculate the period when the portfolio has positive balance considering withdrawals on the historical data.
- `dcf.survival_date` property to get the date when the portfolio balance become negative considering withdrawals on the historical data.
- `dcf.cashflow_pv` property to calculate the discounted value (PV) of the cash flow amount at the historical `first_date`.
- `dcf.initial_amount_pv` property to calculate the discounted value (PV) of the initial investments at the historical `first_date`.
New properties in `Portfolio` class
- `assets_dividend_yield` property to calculate last twelve months (LTM) dividend yield time series (monthly) for each asset
- `dividends_annual` property to get calendar year dividends sum time series for each asset.
New methods and properties in `AssetList` class
- `get_rolling_risk_annual()` method to calculate annualized risk rolling time series for each asset.
- `get_dividend_mean_yield()` method to calculate the arithmetic mean for annual dividend yield over a specified period.
- `dividend_yield_annual` property to calculate last twelve months (LTM) dividend yield annual time series.
Changes in existing methods & properties
- `Asset_List.risk_annual` returns expanding risk time series (not float)
- `Portfolio.recovery_period` returns time series of recovery periods over historical data (not a single period)
- `describe()` method shows the rate of return arithmetic mean (expected return) in `Portfolio`, `AssetList` classes
- new `xy_text` argument in `plot_assets()` method to position better point labels
in `Portofolio`, `AssetList` classes
New Jupyter Notebooks with examples
- [04 investment portfolios with DCF.ipynb](https://github.com/mbk-dev/okama/blob/master/examples/04%20investment%20portfolios%20with%20DCF.ipynb) for investment strategies with cash flow - portfolio withdrawals / contributions. Backtest the portfolio and forecast portfolio longevity with Monte Carlo simulation.
- [05 macroeconomics - inflation rates.ipynb](https://github.com/mbk-dev/okama/blob/master/examples/05%20macroeconomics%20-%20inflation%20rates.ipynb) to analyze inflation, key rates and other macro indicators historical data.
Bugs fixed
- Duplicate tickers in the assets are no longer allowed and are automatically corrected (`AssetList`, `Portfolio`, `EfficientFrontier`, `EfficientFrontierReb`)