Quick Start Guide¶

This 15-minute walkthrough covers the essentials so you can ingest data, build a portfolio, and run a backtest quickly. For the canonical step-by-step narrative (with expected outputs and verification snippets), see the First Steps Tutorial.

Prerequisites¶

Python 3.10 or higher
pip package manager
~500 MB disk space for sample data

Installation (5 minutes)¶

1. Clone the Repository¶

git clone https://github.com/jc1122/portfolio_management.git
cd portfolio_management

2. Install Dependencies¶

# Install core dependencies
pip install -r requirements.txt

# Optional: Install fast IO backends for faster CSV processing
pip install polars pyarrow

3. Verify Installation¶

# Run a quick smoke test
pytest tests/ -m "not slow" -x

Expected: 600+ tests pass (one may xfail because of CVXPY solver quirks).

Quick Demo (10 minutes)¶

Scenario: Build an Equal-Weight Portfolio¶

We'll use the pre-configured core_global universe (35 GBP ETFs) to generate returns, construct an equal-weight portfolio, and backtest it over 2020-2023.

Step 1: Prepare Sample Data¶

python scripts/prepare_tradeable_data.py \
    --data-dir data/stooq \
    --tradeable-dir tradeable_instruments \
    --metadata-output data/metadata/stooq_index.csv \
    --match-report data/metadata/tradeable_matches.csv \
    --prices-output data/processed/tradeable_prices \
    --incremental

First run: ~3-5 minutes (indexes 70k+ files)
Subsequent runs: < 5 seconds with --incremental

Step 2: Generate Universe Returns¶

python scripts/manage_universes.py load core_global \
    --output-dir outputs/quickstart

This single command selects assets, classifies them, and calculates monthly returns (see config/universes.yaml for the universe blueprint).

Step 3: Construct Portfolio¶

python scripts/construct_portfolio.py \
    --returns outputs/quickstart/core_global_returns.csv \
    --strategy equal_weight \
    --max-weight 0.25 \
    --output outputs/quickstart/portfolio_weights.csv

Outputs a CSV of 35 tickers at ~2.86% each (equal-weight) and enforces the 25% max per asset guardrail.

Step 4: Run Backtest¶

python scripts/run_backtest.py equal_weight \
    --start-date 2020-01-01 \
    --end-date 2023-12-31 \
    --returns outputs/quickstart/core_global_returns.csv \
    --output-dir outputs/quickstart/backtest \
    --rebalance-frequency quarterly \
    --visualize

Outputs: equity/drawdown/rolling metrics CSVs, trades.csv, and performance_metrics.json.

Step 5: Inspect Performance¶

cat outputs/quickstart/backtest/equal_weight/performance_metrics.json

Key expectations (2020-2023):

Total return: 15-30%
Sharpe ratio: 0.8-1.5
Max drawdown: 15-25%
Annual volatility: 10-15%

What Just Happened?¶

Universal pipeline (manage_universes.py) selected, classified, and calculated returns for core_global assets.
Portfolio construction (construct_portfolio.py) applied the equal-weight strategy, enforced constraints, and exported weights.
Backtesting (run_backtest.py) simulated quarterly rebalances, applied transaction costs, and saved visualizations and metrics.

Next Steps¶

Try other strategies¶

python scripts/construct_portfolio.py \
    --returns outputs/quickstart/core_global_returns.csv \
    --strategy risk_parity \
    --output outputs/quickstart/portfolio_riskparity.csv

python scripts/construct_portfolio.py \
    --returns outputs/quickstart/core_global_returns.csv \
    --strategy mean_variance_max_sharpe \
    --max-equity 0.85 \
    --min-bond 0.15 \
    --output outputs/quickstart/portfolio_mv.csv

python scripts/construct_portfolio.py \
    --returns outputs/quickstart/core_global_returns.csv \
    --compare \
    --output outputs/quickstart/comparison.csv

Add factor preselection¶

python scripts/run_backtest.py risk_parity \
    --returns outputs/quickstart/core_global_returns.csv \
    --start-date 2020-01-01 \
    --preselection-factors momentum,quality,lowvol \
    --output-dir outputs/quickstart/preselection_backtest