ExPostFacto

A comprehensive backtesting library for trading strategies written in Elixir.

Important

This library is under active, pre 1.0 development. The APIs are not to be considered stable. Calculations may not be correct. See the LICENSE but use at your own risk.

ExPostFacto empowers traders and developers to test their trading strategies against historical data with confidence. Built with Elixir's concurrency and fault-tolerance in mind, it provides enterprise-grade backtesting capabilities with an intuitive API.

🚀 Why ExPostFacto?

• 🎯 Easy to Use: Simple API that gets you backtesting in minutes
• 📊 Professional Grade: Comprehensive statistics and performance metrics
• 🔧 Flexible: Support for simple functions or advanced strategy behaviours
• ⚡ Fast: Concurrent optimization and streaming for large datasets
• 🧹 Robust: Built-in data validation, cleaning, and error handling
• 📈 Complete: 20+ technical indicators and optimization algorithms

✨ Key Features

Multiple Input Formats

• CSV files - Load data directly from CSV files
• JSON - Parse JSON market data
• Lists of maps - Use runtime data structures
• Streaming - Handle large datasets efficiently

Data Validation & Cleaning

• Comprehensive OHLCV validation with detailed error messages
• Automatic data cleaning - Remove invalid points, sort by timestamp
• Enhanced timestamp handling - Support for multiple date formats
• Duplicate detection and removal

Flexible Strategy Framework

• Simple MFA functions for quick prototypes
• Advanced Strategy behaviour with state management
• Built-in helper functions - buy(), sell(), position(), etc.
• 20+ technical indicators - SMA, EMA, RSI, MACD, Bollinger Bands, and more

Performance & Optimization

• Parameter optimization with grid search, random search, walk-forward analysis
• Concurrent processing for large parameter spaces
• Memory-efficient streaming for massive datasets
• Performance profiling and bottleneck identification

Comprehensive Analytics

• 30+ performance metrics - Sharpe ratio, CAGR, max drawdown, profit factor
• Trade analysis - Win rate, best/worst trades, trade duration
• Risk metrics - Drawdown analysis, volatility measures
• Visual data - Heatmaps for parameter optimization

See ENHANCED_DATA_HANDLING_EXAMPLES.md for detailed usage examples.

LiveBook Integration

ExPostFacto works seamlessly with LiveBook for interactive backtesting and analysis:

# In LiveBook, install dependencies:
Mix.install([
  {:ex_post_facto, "~> 0.2.0"},
  {:kino, "~> 0.12.0"},
  {:kino_vega_lite, "~> 0.1.0"}
])

# Run interactive backtests with rich visualizations
{:ok, result} = ExPostFacto.backtest(data, {MyStrategy, :call, []})

See LiveBook Integration Guide for comprehensive examples, interactive forms, and visualization techniques.

📖 Quick Start

Installation

Add ExPostFacto to your mix.exs:

def deps do
  [
    {:ex_post_facto, "~> 0.2.0"}
  ]
end

Your First Backtest

# Sample market data
market_data = [
  %{open: 100.0, high: 105.0, low: 98.0, close: 102.0, timestamp: "2023-01-01"},
  %{open: 102.0, high: 108.0, low: 101.0, close: 106.0, timestamp: "2023-01-02"},
  %{open: 106.0, high: 110.0, low: 104.0, close: 108.0, timestamp: "2023-01-03"}
]

# Simple buy-and-hold strategy
{:ok, result} = ExPostFacto.backtest(
  market_data,
  {ExPostFacto.ExampleStrategies.SimpleBuyHold, []},
  starting_balance: 10_000.0
)

# View results
IO.puts("Total return: $#{result.result.total_profit_and_loss}")
IO.puts("Win rate: #{result.result.win_rate}%")

Load Data from CSV

# ExPostFacto automatically handles CSV files
{:ok, result} = ExPostFacto.backtest(
  "path/to/market_data.csv",
  {MyStrategy, :call, []},
  starting_balance: 100_000.0
)

🎯 Strategy Development

Simple Function Strategy (MFA)

defmodule SimpleThresholdStrategy do
  def call(data, _result) do
    if data.close > 105.0, do: :buy, else: :sell
  end
end

{:ok, result} = ExPostFacto.backtest(
  market_data,
  {SimpleThresholdStrategy, :call, []},
  starting_balance: 10_000.0
)

Advanced Strategy Behaviour

defmodule MovingAverageStrategy do
  use ExPostFacto.Strategy

  def init(opts) do
    {:ok, %{
      fast_period: Keyword.get(opts, :fast_period, 10),
      slow_period: Keyword.get(opts, :slow_period, 20),
      price_history: []
    }}
  end

  def next(state) do
    current_price = data().close
    price_history = [current_price | state.price_history]

    if length(price_history) >= state.slow_period do
      fast_sma = indicator(:sma, price_history, state.fast_period)
      slow_sma = indicator(:sma, price_history, state.slow_period)

      if List.first(fast_sma) > List.first(slow_sma) do
        buy()
      else
        sell()
      end
    end

    {:ok, %{state | price_history: price_history}}
  end
end

# Run with custom parameters
{:ok, result} = ExPostFacto.backtest(
  market_data,
  {MovingAverageStrategy, [fast_period: 5, slow_period: 15]},
  starting_balance: 10_000.0
)

📈 Technical Indicators

ExPostFacto includes 20+ built-in technical indicators:

# Available indicators
prices = [100, 101, 102, 103, 104, 105]

sma_20 = indicator(:sma, prices, 20)
ema_12 = indicator(:ema, prices, 12)
rsi_14 = indicator(:rsi, prices, 14)
{macd, signal, histogram} = indicator(:macd, prices)
{bb_upper, bb_middle, bb_lower} = indicator(:bollinger_bands, prices)

# Crossover detection
if crossover?(fast_sma, slow_sma) do
  buy()
end

🎛️ Strategy Optimization

Find optimal parameters automatically:

# Grid search optimization
{:ok, result} = ExPostFacto.optimize(
  market_data,
  MovingAverageStrategy,
  [fast_period: 5..15, slow_period: 20..30],
  maximize: :sharpe_ratio
)

IO.puts("Best parameters: #{inspect(result.best_params)}")
IO.puts("Best Sharpe ratio: #{result.best_score}")

# Walk-forward analysis for robust testing
{:ok, result} = ExPostFacto.optimize(
  market_data,
  MovingAverageStrategy,
  [fast_period: 5..15, slow_period: 20..30],
  method: :walk_forward,
  training_window: 252,  # 1 year
  validation_window: 63  # 3 months
)

🧹 Data Validation & Cleaning

ExPostFacto ensures your data is clean and valid:

# Validate data
case ExPostFacto.validate_data(market_data) do
  :ok -> IO.puts("Data is valid!")
  {:error, reason} -> IO.puts("Validation error: #{reason}")
end

# Clean messy data automatically
{:ok, clean_data} = ExPostFacto.clean_data(dirty_data)

# Enhanced error handling
{:ok, result} = ExPostFacto.backtest(
  market_data,
  strategy,
  enhanced_validation: true,
  debug: true
)

📊 Example Strategies

ExPostFacto includes several example strategies:

# Moving Average Crossover
{:ok, result} = ExPostFacto.backtest(
  data,
  {ExPostFacto.ExampleStrategies.SmaStrategy, [fast_period: 10, slow_period: 20]}
)

# RSI Mean Reversion
{:ok, result} = ExPostFacto.backtest(
  data,
  {ExPostFacto.ExampleStrategies.RSIMeanReversionStrategy, [
    rsi_period: 14,
    oversold_threshold: 30,
    overbought_threshold: 70
  ]}
)

# Bollinger Band Strategy
{:ok, result} = ExPostFacto.backtest(
  data,
  {ExPostFacto.ExampleStrategies.BollingerBandStrategy, [period: 20, std_dev: 2.0]}
)

# Breakout Strategy
{:ok, result} = ExPostFacto.backtest(
  data,
  {ExPostFacto.ExampleStrategies.BreakoutStrategy, [
    lookback_period: 20,
    breakout_threshold: 0.02
  ]}
)

📚 Documentation & Learning

Complete Documentation

• Getting Started Guide - Step-by-step introduction
• Interactive Tutorial - Livebook tutorial with examples
• Strategy API Guide - Comprehensive strategy development
• Technical Indicators - All available indicators and usage
• Best Practices - Guidelines for effective strategies
• Migration Guide - Moving from other libraries

Data Handling

• Enhanced Data Handling - Data formats and validation
• Error Handling - Debugging and validation

Advanced Features

• Optimization Guide - Parameter optimization techniques
• Comprehensive Metrics - Performance analysis

🔧 Advanced Features

Streaming for Large Datasets

# Handle massive datasets efficiently
{:ok, result} = ExPostFacto.backtest_stream(
  "very_large_dataset.csv",
  {MyStrategy, []},
  chunk_size: 1000,
  memory_limit_mb: 100
)

Concurrent Optimization

# Leverage all CPU cores for optimization
{:ok, result} = ExPostFacto.optimize(
  data,
  MyStrategy,
  parameter_ranges,
  method: :random_search,
  samples: 1000,
  max_concurrent: System.schedulers_online()
)

Heatmap Visualization

# Generate parameter heatmaps
{:ok, optimization_result} = ExPostFacto.optimize(data, MyStrategy, param_ranges)
{:ok, heatmap} = ExPostFacto.heatmap(optimization_result, :param1, :param2)

# Use heatmap data for visualization
IO.inspect(heatmap.scores)  # 2D array of performance scores

🆚 Comparison with Other Libraries

Feature	ExPostFacto	backtesting.py	Backtrader	QuantConnect
Language	Elixir	Python	Python	C#/Python
Concurrency	✅ Native	❌	❌	✅
Memory Efficiency	✅ Streaming	❌	❌	✅
Data Validation	✅ Built-in	❌	❌	✅
Walk-Forward	✅	❌	✅	✅
Easy Setup	✅	✅	❌	❌

🤝 Contributing

We welcome contributions! Please see our contributing guidelines and check out the open issues.

📄 License

ExPostFacto is released under the MIT License. See LICENSE for details.

🙏 Acknowledgments

Inspired by Python's backtesting.py and other excellent backtesting libraries. Built with the power and elegance of Elixir.

---

Ready to backtest your trading strategies? Get started now! 🚀