Investing Algorithm Framework Tutorial

This tutorial demonstrates main capabilities of the Investing Algorithm Framework through a series of Jupyter notebooks. Each notebook focuses on a specific aspect of the framework, from data handling to advanced backtesting and analysis.

Note: This tutorial only showcases a subset of the framework's capabilities. Advanced features like cross-sectional pipelines can be explored in the advanced tutorials.

Note: This tutorial uses the Bitvavo exchange with EUR as the trading symbol. You can adapt the examples to other exchanges and symbols supported by the framework.

🎯 Overview

The Investing Algorithm Framework is a comprehensive Python library for building, testing, and deploying algorithmic trading strategies. This tutorial showcases:

Data Management - Download, validate, and fill missing market data
Strategy Visualization - Visualize trading strategies
In sample Parameter Sweeping - Test thousands of parameter combinations with ease through a grid search and vector backtesting.
Out sample Vector Backtesting - Test thousand of strategies out-of-sample with a fast vectorized backtester.
Out sample event based Backtesting - Simulate realistic trade execution with an event-based backtester to validate top strategies from the vector backtest.
Final analysis - Generate reports, rank strategies, and export results for further analysis.

📁 Tutorial Structure

tutorial/
├── README.md                          # This file
├── notebooks/                         # Tutorial notebooks (start here!)
│   ├── 01_data_exploration.ipynb      # Data download and validation
│   ├── 02_strategy_visualization.ipynb # Strategy logic visualization
│   ├── 03_in_sample_param_sweep.ipynb           # In-sample parameter optimization
│   ├── 04_out_sample_vector_backtest.ipynb    # Out-of-sample vector backtesting
│   ├── 05_event_backtest.ipynb        # Out-of-sample event-based backtesting
│   ├── 06_robustness_analysis.ipynb   # Robustness and validation
│   └── 07_final_analysis.ipynb        # Final results and reporting
├── strategies/                        # Strategy implementations
│   └── supertrend_ema_confirmation/   # Example strategy (v9 signal API)
├── data/                              # Downloaded market data
├── backtest_results/                  # Backtest results storage
└── reports/                           # Generated reports / figures

🔧 Prerequisites

Required Knowledge

Basic Python programming
Understanding of financial markets and trading concepts
Familiarity with technical indicators (EMA, RSI, MACD, etc.)
Basic knowledge of Jupyter notebooks

Software Requirements

Python 3.10 or higher
Jupyter Notebook or JupyterLab

Installation

# Install the framework
pip install investing-algorithm-framework

# Install additional dependencies
pip install plotly pyindicators

🚀 Getting Started

Navigate to the tutorial directory:
```
cd examples/tutorial
```
Start Jupyter:
```
jupyter notebook
```
Open the notebooks folder and start with 01_data_exploration.ipynb
Follow the notebooks in order - each builds on the previous one

📓 Notebooks

01 - Data Exploration

File: notebooks/01_data_exploration.ipynb

Learn how to download and manage market data:

download_v2() - Download OHLCV data with path tracking
get_missing_timeseries_data_entries() - Detect gaps in data
fill_missing_timeseries_data() - Fill missing data points
DownloadResult - Access both data and file path

from investing_algorithm_framework import download_v2

result = download_v2(
    symbol="BTC/EUR",
    market="BITVAVO",
    time_frame="2h",
    start_date=start_date,
    end_date=end_date,
    save=True,
    storage_path="./data"
)
print(result.data)  # DataFrame
print(result.path)  # File path where data was saved

02 - Strategy Visualization

File: notebooks/02_strategy_visualization.ipynb

Visualize and understand strategy logic:

Plot indicators (EMA, RSI) on price charts
Visualize buy/sell signals
Understand strategy parameters
Interactive Plotly charts

03 - Parameter Sweep

File: notebooks/03_param_sweep.ipynb

Run your first backtest and then scale up to thousands of parameter combinations:

run_backtest() - Single strategy backtest (the baseline run)
run_backtests() - Batch backtesting across many strategies
Study - Bundles the universe, date range(s), and engine choice (set engines=[BacktestEngine.VECTOR] for the fast vectorized engine)
BacktestReport - Generate HTML reports
rank_results() - Rank strategies by performance
create_weights() - Custom ranking weights
Window filtering - Filter after each date range
Final filtering - Filter combined results

from investing_algorithm_framework import Study, Universe, \
    BacktestWindow, BacktestEngine

study = Study(
    universe=Universe(market="BITVAVO", trading_symbol="EUR"),
    initial_capital=1000,
    risk_free_rate=0.027,
    backtest_windows=[BacktestWindow(train_range=date_range)],
    engines=[BacktestEngine.VECTOR],
)

# Baseline run
backtests = app.run_backtest(strategy=strategy, study=study)
backtest = backtests[0]
BacktestReport(backtest).show(browser=True)

# Parameter grid
params = {
    'ema_short_period': [20, 50, 75],
    'ema_long_period': [100, 150, 200],
    'rsi_period': [14, 21],
}
strategies = [Strategy(**p) for p in generate_combinations(params)]

sweep_study = Study(
    universe=Universe(market="BITVAVO", trading_symbol="EUR"),
    initial_capital=1000,
    backtest_windows=[
        BacktestWindow(train_range=dr) for dr in date_ranges
    ],
    engines=[BacktestEngine.VECTOR],
)
backtests = app.run_backtests(
    strategies=strategies,
    study=sweep_study,
    window_filter_function=window_filter,
    final_filter_function=final_filter,
    show_progress=True
)

ranked = rank_results(
    backtests,
    focus=BacktestEvaluationFocus.BALANCED
)

04 - Backtest Optimized

File: notebooks/04_backtest_optimized.ipynb

Advanced backtesting features:

Parallel processing - Use multiple CPU cores
Checkpointing - Save/resume long experiments
Storage directories - Persist results to disk

backtests = app.run_backtests(
    strategies=strategies,
    study=sweep_study,
    n_workers=-1,  # Use all CPU cores
    use_checkpoints=True,
    backtest_storage_directory="./backtests/experiment_1",
    show_progress=True
)

05 - Event Backtest

File: notebooks/05_event_backtest.ipynb

Realistic trade simulation:

run_backtest() - Event-based backtesting
run_backtests() - Batch event-based backtesting
Simulates real-time order execution
More accurate slippage and fill modeling

event_study = Study(
    universe=Universe(market="BITVAVO", trading_symbol="EUR"),
    initial_capital=1000,
    backtest_windows=[BacktestWindow(train_range=date_range)],
    engines=[BacktestEngine.EVENT_DRIVEN],
)

# Single event-based backtest
backtests = app.run_backtest(strategy=strategy, study=event_study)
backtest = backtests[0]

# Batch event-based backtests
sweep_event_study = Study(
    universe=Universe(market="BITVAVO", trading_symbol="EUR"),
    initial_capital=1000,
    backtest_windows=[
        BacktestWindow(train_range=dr) for dr in date_ranges
    ],
    engines=[BacktestEngine.EVENT_DRIVEN],
)
backtests = app.run_backtests(
    strategies=strategies,
    study=sweep_event_study,
    n_workers=4
)

06 - Robustness Analysis

File: notebooks/06_robustness_analysis.ipynb

Validate strategy robustness:

Walk-forward analysis - Rolling window validation
generate_rolling_backtest_windows() - Create train/test splits
Out-of-sample testing
Parameter stability analysis

from investing_algorithm_framework import generate_rolling_backtest_windows

windows = generate_rolling_backtest_windows(
    start_date=start_date,
    end_date=end_date,
    train_days=365,
    step_days=90
)

for window in windows:
    train_range = window["train_range"]
    test_range = window["test_range"]
    # Train on train_range, validate on test_range

07 - Final Analysis

File: notebooks/07_final_analysis.ipynb

Generate final reports and analysis:

create_markdown_table() - Format results as markdown
BacktestReport - Interactive HTML reports
Export results for further analysis
Compare top strategies

from investing_algorithm_framework import create_markdown_table

# Create summary table
table = create_markdown_table(
    backtests,
    sort_by="sharpe_ratio",
    top_n=10
)
print(table)

🔑 Key Framework Features

Strategy API (v9)

Strategies declare what to do; the framework handles how much and how. The example SupertrendEmaConfirmationStrategy implements both signal methods so it works in either backtest mode:

Method	Used by	Returns
`generate_signals(context, data)`	event backtest / live	one or more `Signal(symbol, side, ...)` for the latest bar
`generate_signal_series(data)`	vector backtest	one `SignalSeries` per `(symbol, side)` covering the whole window

Sizing lives on the class as a list of PositionSize rules (percentage_of_portfolio=... or fixed_amount=...). Risk attachments (StopLossRule, TakeProfitRule, ScalingRule, CooldownRule) attach to orders automatically. See docs/architecture/strategy.md for the full contract.

Data Management

Function	Description
`download()`	Download market data
`download_v2()`	Download with path tracking
`fill_missing_timeseries_data()`	Fill gaps in time series
`get_missing_timeseries_data_entries()`	Detect missing data

Backtesting

Function	Description
`run_backtest()`	Single strategy backtest (vector or event engine, via `Study.engines`)
`run_backtests()`	Batch backtest across many strategies (vector or event engine, via `Study.engines`)

Analysis & Ranking

Function	Description
`rank_results()`	Rank backtests by metrics
`create_weights()`	Custom ranking weights
`BacktestEvaluationFocus`	Predefined ranking focuses
`create_markdown_table()`	Format results as markdown

Storage & Checkpointing

Feature	Description
`backtest_storage_directory`	Persist results to disk
`use_checkpoints`	Save/resume experiments
`load_backtests_from_directory()`	Load saved backtests

Parallel Processing

Feature	Description
`n_workers`	Number of parallel workers
`batch_size`	Strategies per batch

🎓 Next Steps

After completing this tutorial:

Create your own strategy using the example as a template
Test on different markets and time periods
Deploy to paper trading to validate in real-time
Go live with the framework's production capabilities

Additional Resources

Documentation: See docusaurus/docs/ for full documentation
Example Strategies: See examples/strategies_showcase/
Advanced Topics:
- docusaurus/docs/Advanced Concepts/vector-backtesting.md
- docusaurus/docs/Advanced Concepts/PARALLEL_PROCESSING_GUIDE.md

📧 Support

Check the main framework documentation
Review example strategies in examples/
Open an issue on GitHub

Happy Trading! 🚀📈

Remember: Past performance does not guarantee future results. Always test thoroughly and use proper risk management.

Navigation Menu

Uh oh!

Investing Algorithm Framework Tutorial

📋 Table of Contents

🎯 Overview

📁 Tutorial Structure

🔧 Prerequisites

Required Knowledge

Software Requirements

Installation

🚀 Getting Started

📓 Notebooks

01 - Data Exploration

02 - Strategy Visualization

03 - Parameter Sweep

04 - Backtest Optimized

05 - Event Backtest

06 - Robustness Analysis

07 - Final Analysis

🔑 Key Framework Features

Strategy API (v9)

Data Management

Backtesting

Analysis & Ranking

Storage & Checkpointing

Parallel Processing

🎓 Next Steps

Additional Resources

📧 Support

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Investing Algorithm Framework Tutorial

📋 Table of Contents

🎯 Overview

📁 Tutorial Structure

🔧 Prerequisites

Required Knowledge

Software Requirements

Installation

🚀 Getting Started

📓 Notebooks

01 - Data Exploration

02 - Strategy Visualization

03 - Parameter Sweep

04 - Backtest Optimized

05 - Event Backtest

06 - Robustness Analysis

07 - Final Analysis

🔑 Key Framework Features

Strategy API (v9)

Data Management

Backtesting

Analysis & Ranking

Storage & Checkpointing

Parallel Processing

🎓 Next Steps

Additional Resources

📧 Support