Okama Documentation

okama is a Python library for investment portfolio analysis and optimization. It applies concepts commonly used in quantitative finance.

okama provides access to free end-of-day historical market data and macroeconomic indicators through an API.

…entities should not be multiplied without necessity

– William of Ockham (c. 1287–1347)

Okama main features

Constrained Markowitz Mean-Variance Analysis (MVA) and portfolio optimization
Multi-period Efficient Frontier optimization with rebalancing constraints
Investment portfolios with contribution and withdrawal cash flows (DCF)
Monte Carlo simulations for financial assets and investment portfolios
Popular risk metrics: VaR, CVaR, semideviation, variance, and drawdowns
Forecasting models based on normal, lognormal, and Student’s t distributions
Distribution fitting and goodness-of-fit testing on historical data
Dividend yield and other dividend indicators for stocks
Backtesting and comparing the historical performance of a broad range of assets and indexes in multiple currencies
Methods for tracking the performance of index funds (ETFs) and comparing them with benchmarks
Main macroeconomic indicators: inflation, central bank rates, and financial ratios
Matplotlib visualizations for the Efficient Frontier, Transition Map, and asset risk/return performance

Financial data and macroeconomic indicators

okama can work with free financial data available through its API.

End of day historical data

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

Macroeconomic indicators

For several countries, including the USA, the United Kingdom, the European Union, Russia, and Israel:

Inflation
Central bank rates
CAPE10 (Shiller P/E), or cyclically adjusted price-to-earnings ratios

Other historical data

Real estate prices
Top bank rates

Installation

Okama can be installed from PyPI:

pip install okama

For development, install uv and clone the repository. The contributor environment defaults to Python 3.14; the library supports Python 3.11–3.14.

git clone -b dev https://github.com/mbk-dev/okama.git
cd okama
uv sync
uv run python -c "import okama; print(okama.__version__)"

Warning

The development version of okama may have technical and financial issues. Use it carefully and at your own risk.

Quick Start

Index Funds Performance

Investment Portfolios

Main

Assets & Portfolio

`okama.Asset`([symbol, first_date, last_date])	A financial asset, that could be used in a list of assets or in portfolio.
`okama.AssetList`([assets, first_date, ...])	List of financial assets.
`okama.Portfolio`([assets, first_date, ...])	Investment portfolio.
`okama.Rebalance`([period, abs_deviation, ...])	Rebalancing strategy for an investment portfolio.

Cash Flows & DCF

`okama.PortfolioDCF`(parent[, discount_rate])	Discounted cash flow (DCF) methods for a Portfolio.
`okama.MonteCarlo`(parent[, distribution, ...])	Monte Carlo simulation parameters for an investment portfolio.
`okama.IndexationStrategy`(parent[, ...])	Cash flow strategy with regular indexed withdrawals or contributions.
`okama.PercentageStrategy`(parent[, ...])	Cash flow strategy with regular fixed percentage withdrawals or contributions.
`okama.TimeSeriesStrategy`(parent[, ...])	Cash flow strategy with user-defined withdrawals and contributions.
`okama.VanguardDynamicSpending`(parent[, ...])	Vanguard Dynamic Spending strategy.
`okama.CutWithdrawalsIfDrawdown`(parent[, ...])	Withdrawal strategy that reduces the withdrawal amount if the portfolio drawdown exceeds a certain threshold.

Financial Plan

Reading and reusing a financial plan

`okama.FinPlan`(stages[, initial_investment, ...])	A financial plan: an ordered sequence of portfolio stages.
`okama.FinPlanStage`(portfolio, period[, ...])	One stage of a financial plan: a portfolio held for a number of years.

Efficient Frontier

okama.EfficientFrontier([assets, ...])

Efficient Frontier with multi-period optimization.

Macroeconomics

`okama.Inflation`([symbol, first_date, last_date])	Inflation related data and methods.
`okama.Rate`([symbol, first_date, last_date])	Rates of central banks and banks.
`okama.Indicator`([symbol, first_date, last_date])	Macroeconomic indicators and ratios.

Data Access & Search

okama.search(): Search symbols by ticker, name, or ISIN.
okama.symbols_in_namespace(): Return all symbols available in a namespace.
okama.namespaces: Returns a dictionary of available data namespaces and their descriptions.

Performance reports

The Calculation performance work summarizes measured calculation improvements, workloads and cache limits. Benchmark data and source links point to the versioned repository so they remain available alongside the hosted reports.