Welcome to Universal Portfolios
Relevant source files
The following files were used as context for generating this wiki page:
Universal Portfolios is a Python package designed to aggregate various Online Portfolio Selection (OLPS) algorithms and provide unified tools for their analysis. The primary objective of OLPS is to dynamically choose portfolio weights in every period to maximize final wealth based on historical price relatives. The package implements several state-of-the-art algorithms from academic literature, ranging from classical Modern Portfolio Theory (MPT) to Universal Portfolios.
Sources: README.md:14-23
The architecture is built around three core pillars: implementation of algorithms (hosted in universal.algos), a general base class for portfolio logic (universal.algo), and comprehensive performance metrics and visualization tools (universal.result). It supports Python 3.8+ and leverages standard scientific libraries like pandas, scipy, and scikit-learn for data manipulation and optimization.
Sources: README.md:32-41, pyproject.toml:14-30
System Architecture
The project follows a modular structure where algorithms are decoupled from the evaluation engine. This allows for standardized testing and comparison across different strategies.
Component Overview
| Component | Description | Primary Files |
|---|---|---|
| Algos | Implementations of specific OLPS strategies (e.g., UP, EG, PAMR, MPT). | universal/algos/ |
| Base Algo | Abstract class defining the lifecycle of a portfolio selection strategy. | universal/algo.py |
| Estimators | Tools for estimating mean returns ($\mu$) and covariance matrices ($\Sigma$). | universal/algos/estimators.py |
| Result Engine | Calculates wealth, sharpe ratio, drawdown, and handles plotting. | universal/result.py |
| Tools | Utility functions for data loading, simplex projection, and optimization. | universal/tools.py |
Sources: README.md:32-45, universal/algos/estimators.py:101-140
Core Logic Flow
The following diagram illustrates the lifecycle of a portfolio simulation, from initial price data to final performance reporting.
The run method iterates through the price history, invoking the step method at each interval to determine the new portfolio distribution.
Sources: universal/algos/mpt.py:173-210, universal/result.py:27-50
Key Modules and Logic
Algorithm Base Implementation
The Algo class serves as the foundation for all strategies. It defines the interface for init_weights, init_step, and the core step function which must be implemented by subclasses to return the portfolio weights for a given timestamp.
Sources: universal/algos/up.py:20-53, universal/algos/mpt.py:30-100
Modern Portfolio Theory (MPT)
The MPT class implements classical mean-variance optimization. It supports various estimation methods for returns and risk, including empirical covariance, Ledoit-Wolf, and GraphLasso.
- Methods: Supports "mpt" (mean-variance), "sharpe" (maximize Sharpe ratio), and "variance" (minimize risk for a target return).
- Optimization: Uses
cvxoptfor quadratic programming to solve the optimization problem under constraints such asmax_leverageorbounds.
Sources: universal/algos/mpt.py:30-74, universal/algos/mpt.py:212-250
Performance Analysis
The AlgoResult class provides extensive financial metrics derived from the simulated weights.
Metrics*: Calculations include Annualized Return, Volatility, Sharpe Ratio, Ulcer Index, and Information Ratio.
- Fees: Supports transaction cost modeling through the
feesetter, which triggers a_recalculateof equity curves. - Turnover: Calculated via the
turnoverproperty based on weight changes between periods.
Sources: universal/result.py:27-100, universal/result.py:165-220
Statistical Estimators
The package includes specialized estimators in universal.algos.estimators.py to handle the noise in financial data.
- CovarianceEstimator: Wraps
sklearncovariance models and adds frequency-based caching and standardization. - SharpeEstimator: Estimates returns by assuming a global Sharpe ratio and scaling it by asset volatility, while accounting for ETF expenses.
- TaxAdjustment: Provides logic to adjust mean returns based on unrealized profits and local tax rates.
Sources: universal/algos/estimators.py:101-125, universal/algos/estimators.py:180-210, universal/algos/estimators.py:465-480
Execution Example
A quick simulation can be executed using the tools.quickrun function, which handles data generation (or loading), algorithm execution, and result display in a single call.
from universal import tools
from universal.algos import CRP
# Run Constant Rebalanced Portfolio on random data
tools.quickrun(CRP())
Sources: README.md:49-56, universal/tools.py:65-78
Summary
Universal Portfolios provides a robust framework for quantitative finance researchers to implement and backtest online portfolio selection strategies. By unifying algorithm implementation with the Algo base class and providing the AlgoResult engine for standardized metrics, the project ensures that diverse strategies—from mean-reversion (PAMR, OLMAR) to trend-following (UP)—can be compared objectively.