Analyzing bot data with Jupyter notebooks

You can analyze the results of backtests and trading history easily using Jupyter notebooks. Sample notebooks are located at user_data/notebooks/ after initializing the user directory with freqtrade create-userdir --userdir user_data.

Quick start with docker

Freqtrade provides a docker-compose file which starts up a jupyter lab server. You can run this server using the following command:

docker compose -f docker/docker-compose-jupyter.yml up

This will create a dockercontainer running jupyter lab, which will be accessible using https://127.0.0.1:8888/lab.

Please use the link that's printed in the console after startup for simplified login.

For more information, Please visit the Data analysis with Docker section.

Pro tips

• See jupyter.org for usage instructions.
• Don't forget to start a Jupyter notebook server from within your conda or venv environment or use nb_conda_kernels*
• Copy the example notebook before use so your changes don't get overwritten with the next freqtrade update.

Using virtual environment with system-wide Jupyter installation

Sometimes it can be desired to use a system-wide installation of Jupyter notebook, and use a jupyter kernel from the virtual environment.

This prevents you from installing the full jupyter suite multiple times per system, and provides an easy way to switch between tasks (freqtrade / other analytics tasks).

For this to work, first activate your virtual environment and run the following commands:

# Activate virtual environment
source .venv/bin/activate

pip install ipykernel
ipython kernel install --user --name=freqtrade
# Restart jupyter (lab / notebook)
# select kernel "freqtrade" in the notebook

note

This section is provided for completeness, the Freqtrade Team won't provide full support for problems with this setup and will recommend to install Jupyter in the virtual environment directly, as that is the easiest way to get jupyter notebooks up and running. For help with this setup please refer to the Project Jupyter documentation or help channels.

warning

Some tasks don't work especially well in notebooks. For example, anything using asynchronous execution is a problem for Jupyter. Also, freqtrade's primary entry point is the shell cli, so using pure python in a notebook bypasses arguments that provide required objects and parameters to helper functions. You may need to set those values or create expected objects manually.

Recommended workflow

Task	Tool
Bot operations	CLI
Repetitive tasks	Shell scripts
Data analysis & visualization	Notebook

1. Use the CLI to

   • download historical data
   • run a backtest
   • run with real-time data
   • export results

2. Collect these actions in shell scripts

   • save complicated commands with arguments
   • execute multi-step operations
   • automate testing strategies and preparing data for analysis

3. Use a notebook to

   • visualize data
   • mangle and plot to generate insights

Example utility snippets

Change directory to root

Jupyter notebooks execute from the notebook directory. The following snippet searches for the project root, so relative paths remain consistent.

import os
from pathlib import Path

# Change directory
# Modify this cell to insure that the output shows the correct path.
# Define all paths relative to the project root shown in the cell output
project_root = "somedir/freqtrade"
i=0
try:
    os.chdir(project_root)
    assert Path('LICENSE').is_file()
except:
    while i<4 and (not Path('LICENSE').is_file()):
        os.chdir(Path(Path.cwd(), '../'))
        i+=1
    project_root = Path.cwd()
print(Path.cwd())

Load multiple configuration files

This option can be useful to inspect the results of passing in multiple configs. This will also run through the whole Configuration initialization, so the configuration is completely initialized to be passed to other methods.

import json
from freqtrade.configuration import Configuration

# Load config from multiple files
config = Configuration.from_files(["config1.json", "config2.json"])

# Show the config in memory
print(json.dumps(config['original_config'], indent=2))

For Interactive environments, have an additional configuration specifying user_data_dir and pass this in last, so you don't have to change directories while running the bot.

Best avoid relative paths, since this starts at the storage location of the jupyter notebook, unless the directory is changed.

{
    "user_data_dir": "~/.freqtrade/"
}

Load and analyze backtest results

import pandas as pd
from freqtrade.data.btanalysis import load_backtest_data

# Load backtest results
backtest_dir = "user_data/backtest_results"
trades = load_backtest_data(backtest_dir)

# Basic statistics
print(f"Total trades: {len(trades)}")
print(f"Profitable trades: {len(trades[trades['profit_abs'] > 0])}")
print(f"Win rate: {len(trades[trades['profit_abs'] > 0]) / len(trades) * 100:.2f}%")
print(f"Total profit: {trades['profit_abs'].sum():.2f}")

Analyze strategy performance by pair

# Group by pair and analyze performance
pair_performance = trades.groupby('pair').agg({
    'profit_abs': ['sum', 'mean', 'count'],
    'profit_ratio': ['mean', 'std']
}).round(4)

pair_performance.columns = ['Total Profit', 'Avg Profit', 'Trade Count', 'Avg %', 'Std %']
print(pair_performance.sort_values('Total Profit', ascending=False))

Plot profit over time

import matplotlib.pyplot as plt

# Calculate cumulative profit
trades_sorted = trades.sort_values('close_date')
trades_sorted['cumulative_profit'] = trades_sorted['profit_abs'].cumsum()

# Plot
plt.figure(figsize=(12, 6))
plt.plot(trades_sorted['close_date'], trades_sorted['cumulative_profit'])
plt.title('Cumulative Profit Over Time')
plt.xlabel('Date')
plt.ylabel('Profit')
plt.xticks(rotation=45)
plt.grid(True)
plt.tight_layout()
plt.show()

Analyze drawdown periods

# Calculate running maximum and drawdown
trades_sorted['running_max'] = trades_sorted['cumulative_profit'].expanding().max()
trades_sorted['drawdown'] = trades_sorted['cumulative_profit'] - trades_sorted['running_max']

# Find maximum drawdown
max_drawdown = trades_sorted['drawdown'].min()
max_drawdown_date = trades_sorted[trades_sorted['drawdown'] == max_drawdown]['close_date'].iloc[0]

print(f"Maximum Drawdown: {max_drawdown:.2f}")
print(f"Max Drawdown Date: {max_drawdown_date}")

# Plot drawdown
plt.figure(figsize=(12, 6))
plt.fill_between(trades_sorted['close_date'], trades_sorted['drawdown'], 0, alpha=0.3, color='red')
plt.title('Drawdown Over Time')
plt.xlabel('Date')
plt.ylabel('Drawdown')
plt.xticks(rotation=45)
plt.grid(True)
plt.tight_layout()
plt.show()

Load and analyze live trading data

from freqtrade.persistence import Trade
from freqtrade.configuration import Configuration

# Load configuration
config = Configuration.from_files(["config.json"])

# Initialize database
Trade.use_db(config['db_url'])

# Query trades
trades_query = Trade.get_trades()
live_trades = pd.DataFrame([{
    'pair': t.pair,
    'open_date': t.open_date,
    'close_date': t.close_date,
    'profit_abs': t.close_profit_abs,
    'profit_ratio': t.close_profit,
    'duration': t.close_date - t.open_date if t.close_date else None
} for t in trades_query])

print(f"Live trades loaded: {len(live_trades)}")

Advanced Analysis Examples

Strategy comparison

# Compare multiple strategies
strategy_results = {}
for strategy in ['Strategy1', 'Strategy2', 'Strategy3']:
    results = load_backtest_data(f"user_data/backtest_results/{strategy}")
    strategy_results[strategy] = {
        'total_profit': results['profit_abs'].sum(),
        'win_rate': len(results[results['profit_abs'] > 0]) / len(results),
        'avg_profit': results['profit_abs'].mean(),
        'max_drawdown': calculate_max_drawdown(results)
    }

comparison_df = pd.DataFrame(strategy_results).T
print(comparison_df)

Market condition analysis

# Analyze performance in different market conditions
from freqtrade.data.history import load_pair_history

# Load price data
candles = load_pair_history(
    datadir="user_data/data/binance",
    timeframe="1d",
    pair="BTC/USDT"
)

# Define market conditions based on price movement
candles['market_condition'] = 'sideways'
candles.loc[candles['close'].pct_change(7) > 0.05, 'market_condition'] = 'bull'
candles.loc[candles['close'].pct_change(7) < -0.05, 'market_condition'] = 'bear'

# Merge with trades and analyze
trades_with_market = trades.merge(
    candles[['date', 'market_condition']], 
    left_on='open_date', 
    right_on='date', 
    how='left'
)

market_performance = trades_with_market.groupby('market_condition').agg({
    'profit_abs': ['sum', 'mean', 'count'],
    'profit_ratio': 'mean'
})

print(market_performance)

Further Data analysis documentation

• Strategy debugging - also available as Jupyter notebook (user_data/notebooks/strategy_analysis_example.ipynb)
• Plotting
• Tag Analysis

Feel free to submit an issue or Pull Request enhancing this document if you would like to share ideas on how to best analyze the data.

Best Practices

Performance Tips

1. Use vectorized operations with pandas for better performance
2. Load data once and reuse it across analyses
3. Use appropriate time ranges to avoid memory issues
4. Cache expensive calculations using pickle or joblib

Visualization Tips

1. Use consistent color schemes across charts
2. Add proper labels and titles to all plots
3. Include grid lines for better readability
4. Use subplots for related metrics

Analysis Tips

1. Always validate your data before analysis
2. Consider transaction costs in profit calculations
3. Account for market conditions when comparing strategies
4. Use statistical significance tests for strategy comparisons
5. Document your analysis process for reproducibility

Troubleshooting

Common Issues

1. Memory errors: Reduce data size or use chunking
2. Missing data: Check data download and timeframes
3. Incorrect paths: Use absolute paths or proper relative paths
4. Version conflicts: Ensure compatible package versions

Performance Issues

1. Slow loading: Use parquet format for large datasets
2. Memory usage: Use data types optimization (int32 vs int64)
3. Plotting performance: Reduce data points for large time series
4. Calculation speed: Use numpy operations where possible