Okama

New examples for investment portfolios with cash flow in [04 investment portfolios with DCF.ipynb](https://github.com/mbk-dev/okama/blob/master/examples/04%20investment%20portfolios%20with%20DCF.ipynb).

Several bugs in Portfolio and PortfolioDCF are fixed.

Fixed:
- `Portfolio.dcf.initial_investment_pv` must return None if cash flow parameters are not defined
- add `use_discounted_values` parameter `to helpers.Frame.get_wealth_indexes_with_cashflow`
- use `self.use_discounted_values = False` in `plot_forecast_monte_carlo` for any value of backtest parameter
- clean up Portfolio dat cache if symbol changed

Okama 1.4.3 is dedicated to Cash Flow strategies and Monte Carlos simulations.

New features
3 new classes to set up Cash Flow strategies
Cash flow parameters for investment portfolios are now configured in the corresponding classes.

- `IndexationStrategy` for strategies with regular indexed withdrawals / contributions
- `PercentageStrategy` for strategies weith regualr fixed percentage withdrawals / contributions
- `TimeSeriesStrategy` for strategies with user-defined withdrawals and contributions. Withdrawals, contributions, as well as their dates, are defined in the dictionary.

All 3 classes are inhereted from parent class `CashFlow`.
`Portfolio` class does not have cash flow parameters (`initial_amount`, `cashflow`, `discount_rate`) anymore.

New class to set up Monte Carlo simulation parameters
`MonteCarlos` class has several properties:

- `distribution` - the type of a distribution to generate random rate of return
- `period` - forecast period in years for portfolio wealth index time series
- `number` - number of random wealth indexes to generate with Monte Carlo simulation

All Monte Carlos properties are linked to `PortfolioDCF` instance and can be accessed by `Portfolio().dcf.mc` construction. For example the type of random distribution is available through `Portfolio().dcf.mc.disctribution`.

New methods and properties in PortfolioDCF
PortfolioDCF has a new parameter `use_discounted_values` (default is False). Id defines whether to use discounted values in backtesting wealth indexes (initial investments, withdrawal or contribution size). `discount_rate` parameter is shifted from `Portfolio` to `PortfolioDCF`.

- `find_the_largest_withdrawals_size` - find the largest withdrawals size for Monte Carlo simulation according to Cashflow Strategy. This method works with `IndexationStrategy` and `PercentageStrategy`
- `initial_investment_fv` property to calculate the future value (FV) of the initial investments at the end of forecast period.
- `initial_investment_pv` property to calculate the discounted value (PV) of the initial investments at the historical first date
- `wealth_index_with_assets` works as the same property of `Portfolio` but considers cash flow (contributions and withdrawals)
- `set_mc_parameters` method is a shortcut to add Monte Carlo simulation parameters

Changes in methods and properties in PortfolioDCF
- `monte_carlo_survival_period`, `survival_date_hist` and `survival_period_hist` methods have now new parameter `threshold`. The threshold defines the percentage of the initial investments when the portfolio balance considered voided
- `plot_forecast_monte_carlo` number of parameters is reduced to: `backtest` and `figsize`

Okama 1.4.1 adds custom exceptions for time period and Student's t distribution for Monte-Carlo methods in Portfolio and AssetList.

New features
Custom exceptions for time periods issues
- `ShortPeriodLengthError` is raised when an asset has less then 3 months of history in AssetList, Portfolio and EfficentFrontier classes
- `RollingWindowLengthBelowOneYearError` is raised when rolling windows size is below one year
- `LongRollingWindowLengthError` is raised when rolling window size is more than data history depth

Student's t distribution in Monte-Carlo methods
- set `distr="t"` in methods like `Portfolio.dcf.monte_carlo_wealth` or `AssetList.kstest`

Changes in existing methods & properties
- `Portfolio.dcf.monte_carlo_wealth` uses `initial_amount` value by default.

Bugs fixed
- wrong formula for 0 period rate of return in `helpers.Rebalance.return_ror_ts`

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`)

Okama now supports **Panadas 2.0.0** and further versions. There is no backward compatibility with previous Pandas versions.

New features:
- **New rebalancing periods** for portfolios: "half-year" and "quarter"
- new `set_values_monthly()` method in Inflation to forecast data and change previos values
- new `dividend_yield_annual` property in AssetList calculates dividend yield time series for calendar years
- new `get_dividend_mean_yield()` method in AssetList shows mean dividend yield for a given period
- `plot_cml()` has new `y_axe` parameter to switch from CAGR to mean rate of returns in the plots
- `asset_dividend_yield` property renamed to `dividend_yield` in AssetList

okama works with Python 3.11 now.

FIX:
- aliases `symbols_in_namespace` and `no_dividends_namespaces` were not imported in `__init__.py`