Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
The universal-portfolios package is designed to provide unified tools for Online Portfolio Selection (OLPS) algorithms. Its primary purpose is to allow developers and researchers to implement, run, and analyze strategies that choose portfolio weights in every period to maximize final wealth.
This guide covers the basic workflow: installing the library, running a predefined algorithm using the quickrun utility, and understanding the core components that facilitate backtesting and performance measurement.
Sources: README.md:14-16, README.md:47-49
Core Components
The architecture consists of three main pillars: data management, algorithm implementation, and result analysis.
System Architecture
The following diagram illustrates the relationship between the algorithm execution and the results processing:
The flow starts with input data (price relatives), which is processed by an algorithm's run method to produce weights, finally yielding an AlgoResult object for analysis.
Sources: README.md:92-95, universal/result.py:31-35
Key Classes and Modules
| Component | Module | Description |
|---|---|---|
| Tools | universal.tools | Contains utility functions for quick execution, random portfolio generation, and optimization. |
| Algorithms | universal.algos | Implementations of OLPS strategies like CRP, UP, and MPT. |
| Result | universal.result | Computes wealth, metrics (Sharpe, Drawdown), and handles plotting. |
| Estimators | universal.algos.estimators | Provides mu and covariance estimation logic for MPT-based strategies. |
Sources: README.md:82-95, universal/algos/mpt.py:23-28, universal/result.py:31-40
Basic Usage
To get started quickly, the tools.quickrun function automates the process of generating data (if none provided), running the algorithm, and displaying a summary with plots.
from universal import tools
from universal.algos import CRP
if __name__ == '__main__':
# Run Constant Rebalanced Portfolio on generated data
tools.quickrun(CRP())
Sources: README.md:100-104, universal/tools.py:84-93
The Run Workflow
When an algorithm's run method is invoked, it typically follows a sequence of initialization followed by iterative weight calculations:
The quickrun utility encapsulates the timing, execution, and immediate visualization of the algorithm's performance.
Sources: universal/tools.py:84-93, universal/algos/up.py:44-53, universal/algos/cwmr.py:53-70
Performance Metrics
The AlgoResult class provides a variety of financial metrics derived from the portfolio's performance over time.
| Metric | Property | Description |
|---|---|---|
| Total Wealth | total_wealth | The final product of all period returns. |
| Sharpe Ratio | sharpe | Annualized risk-adjusted return relative to the risk-free rate. |
| Max Drawdown | max_drawdown | The largest peak-to-trough decline in equity. |
| Turnover | turnover | Rate of portfolio rebalancing over time. |
| Winning Pct | winning_pct | Percentage of periods with positive log returns. |
Sources: universal/result.py:145-215, universal/result.py:246-250
Transaction Fees
Fees can be applied to the result to simulate realistic trading costs. The fee is expressed as a percentage for a one-round trade.
result = algo.run(data)
result.fee = 0.001 # 0.1% transaction fee
print(result.summary())
Sources: universal/result.py:82-95
Advanced Configuration: MPT Example
For strategies requiring statistical estimation like Modern Portfolio Theory (MPT), the package allows configuration of mu and covariance estimators.
from universal.algos import MPT
# Initialize MPT with a specific window and estimator type
algo = MPT(window=252, mu_estimator='sharpe', cov_estimator='ledoit-wolf')
Sources: universal/algos/mpt.py:32-55
Conclusion
The universal-portfolios library provides a streamlined interface for testing financial strategies. By using tools.quickrun, users can immediately validate algorithm implementations against generated or historical data, while the AlgoResult system ensures standardized performance reporting across different OLPS methods.
Sources: README.md:14-16, universal/tools.py:84-93