Okama: Investment Portfolio Analysis & Optimization

Okama is a Python library for investment portfolio analysis and optimization using quantitative finance concepts.

Key Capabilities:

• Optimization: Constrained Markowitz Mean-Variance Analysis (MVA) and multi-period Efficient Frontier optimization with rebalancing constraints.
• Simulation & Risk: Monte Carlo simulations, DCF (Discounted Cash Flow) with contribution/withdrawal flows, and risk metrics (VaR, CVaR, semideviation, variance, drawdowns).
• Forecasting: Models based on normal, lognormal, and Student's t distributions, including distribution fitting.
• Analysis: Backtesting asset/index performance, tracking ETF performance against benchmarks, and dividend yield indicators.
• Visualization: Matplotlib-based plots for Efficient Frontier, Transition Maps, and risk/return performance.

When constructing financial plans, okama enforces several constraints to ensure simulation integrity:

FinPlanStage Constraints:

• period must be an integer and must be at least 1.
• distribution must be one of ('norm', 'lognorm', 't').
• cashflow_parameters must be a CashFlow instance whose parent is the same as the stage's portfolio.

FinPlan Constraints:

• stages cannot be empty (must contain at least one stage).
• All portfolios within the provided stages must have the same currency.
• initial_investment must be greater than 0.

When using time_series to inject extra cash flows into a simulation, Okama applies a uniform recursion for every month in the period:

balance = balance * (1 + r) + cash_flow

This ensures that the first month of a period containing an extra cash flow still earns its return, and that the internal balance tracking correctly includes both the return and the extra flow. This is critical for sizing subsequent percentage-based withdrawals correctly.

Okama provides two ways to calculate ex-post tracking error, which differ in how they treat the mean of the return differences:

1. RMS (method="rms"): This is the uncentered root-mean-square of the differences. It does not subtract the mean of the differences from each observation. Consequently, if there is a systematic lag or bias between the asset and the benchmark (a non-zero tracking difference), it is captured in the result.

2. STD (method="std"): This is the centered sample standard deviation of the differences (using Bessel's correction, ddof=1). It measures the pure volatility of the deviations from the benchmark, effectively ignoring the systematic tracking difference (the mean deviation).

Both methods are annualized for monthly time series by multiplying by sqrt(12).

The Monte Carlo (MC) cash-flow engine in Okama is designed to provide vectorized performance for financial simulations. It consists of a shared core simulation method, _simulate_paths_mc(ror, params, discount_rate), which returns both wealth and cash_flow data.

This core is accessed via two thin public wrappers:

1. monte_carlo_cash_flow: Returns the cash flow time series.
2. monte_carlo_irr: Returns the Internal Rate of Return (IRR) calculations.

Both methods utilize existing DCF-level caches (PortfolioDCF._monte_carlo_wealth_fv and ._monte_carlo_cash_flow_fv) to avoid redundant computations. These caches are automatically cleared when updating cash flow strategies or Monte Carlo parameters.

Okama provides access to free historical market data and macroeconomic indicators via its API.

End-of-day historical data includes:

• Stocks and ETFs for major world markets
• Mutual funds
• Commodities
• Currencies
• Stock indexes

Macroeconomic indicators (available for USA, UK, EU, Russia, and Israel):

• Inflation
• Central bank rates
• CAPE10 (Shiller P/E) ratios

Other data:

• Real estate prices
• Top bank rates

Strategies utilize time_series (a monthly Series from time_series_dic) and time_series_discounted_values.

If time_series_discounted_values is set to False, the values are multiplied by (1 + monthly_discount_rate) ** arange(T), where: monthly_discount_rate = (1 + discount_rate) ** (1/12) - 1.

The VanguardDynamicSpending strategy supports floor_ceiling limits to bound withdrawals.

When floor_ceiling is set (e.g., (0.0, 0.0) to force constant withdrawals), the withdrawal size is calculated based on the previous period's withdrawal amount, adjusted by indexation and adjust_floor_ceiling.

Important: In recent versions, these limits are correctly applied within wealth-index calculations, ensuring that the last_withdrawal state is tracked across periods so that floor/ceiling bounds remain active.

vds = ok.VanguardDynamicSpending(
    pf_single,
    initial_investment=10_000,
    percentage=-0.10,
    floor_ceiling=(0.0, 0.0),
    adjust_floor_ceiling=False,
    indexation=0.0,
)

In Monte Carlo simulations, a path might hit a zero or negative balance (a 'void'). Okama provides a vectorized way to handle this using zero_wealth_after_first_void.

Instead of processing each path individually, this function scans the entire wealth DataFrame. For every column (path), it identifies the first non-positive value and replaces it, and every subsequent value in that column, with 0.0. This ensures that once a portfolio is 'voided', it stays at zero for the remainder of the simulation horizon.

# Internal logic used by monte_carlo_wealth(include_negative_values=False)
from okama.portfolios import dcf_calculations

# wealth is a pd.DataFrame of Monte Carlo paths
masked_wealth = dcf_calculations.zero_wealth_after_first_void(wealth)