O20 · example_orders_20_futures_donchian_contracts.py

O20 Futures Donchian Contracts

A diversified 55-day Donchian breakout across index, energy, and metal futures. Orders are whole contracts sized by ATR risk, gross notional, and the reference initial margin carried in ContractSpec.

Review the source on GitHub or return to all strategies.

What this example shows

This example shows how to build a daily-bar order-based order-mode example with signal-to-order conversion, fills, positions, cash accounting and run artifacts.

The goal is educational: to demonstrate the full workflow for universe definition, signal generation, order construction, fill simulation, cash and position accounting, diagnostics and reproducible reporting.

Full performance run. Full performance run on the published example setup. It shows the observed behavior of runnable research code; it is not presented as optimized alpha or an investment recommendation.

Run setup

The ordinary configuration used by the published run—kept visible here and in the Python source.

UniverseMES=F · MNQ=F · CL=F · GC=F

Configured period2019-05-06 → 2026-01-01

BenchmarkSPY · SPDR S&P 500 ETF Trust

Initial capital$2,000,000

Data sourceyfinance

Engine / snapshot0.10.0 · fc003e63847e1cad

Order ModeMode

1dGranularity

4Instruments

42Published plots

passedRun status

Dashboard

Compact evidence view built from the same run packet: metrics, plots and run metadata.

4.67% CAGR

0.30 Sharpe

-16.70% Max DD

35.50% Total return

11.13% Volatility

Selected plot gallery

42 published PNG artifacts. Charts marked Pro are generated by the hosted platform report pack; the rest come from the open-source engine output.

O20 Futures Donchian Contracts Cumulative Returns — Cumulative Returns PNG

O20 Futures Donchian Contracts Portfolio Drawdown — Portfolio Drawdown PNG

O20 Futures Donchian Contracts Monthly Returns Heatmap — Monthly Returns Heatmap PNG

O20 Futures Donchian Contracts Annual Returns — Annual Returns PNG

O20 Futures Donchian Contracts Nav Composition — Nav Composition Pro PNG

O20 Futures Donchian Contracts Percentage Weights — Percentage Weights PNG

O20 Futures Donchian Contracts Crisis Summary — Crisis Summary Pro PNG

O20 Futures Donchian Contracts Correlation Heatmap — Correlation Heatmap PNG

O20 Futures Donchian Contracts Blotter Trade Pnl — Blotter Trade Pnl Pro PNG

O20 Futures Donchian Contracts Blotter Cumulative Pnl — Blotter Cumulative Pnl Pro PNG

Performance

O20 Futures Donchian Contracts Cumulative Log Returns — Cumulative Log Returns PNG

Risk and exposure

O20 Futures Donchian Contracts Asset Risk Contribution — Asset Risk Contribution Pro PNG

Crisis and regimes

O20 Futures Donchian Contracts Benchmark Regime Analysis — Benchmark Regime Analysis Pro PNG

O20 Futures Donchian Contracts Crisis Periods — Crisis Periods Pro PNG

O20 Futures Donchian Contracts Cumulative Returns With Regime — Cumulative Returns With Regime Pro PNG

Execution

O20 Futures Donchian Contracts Blotter Costs — Blotter Costs Pro PNG

O20 Futures Donchian Contracts Blotter Frequency — Blotter Frequency Pro PNG

O20 Futures Donchian Contracts Blotter Holding Periods — Blotter Holding Periods Pro PNG

O20 Futures Donchian Contracts Blotter Instrument Pnl — Blotter Instrument Pnl Pro PNG

O20 Futures Donchian Contracts Blotter Trade Size — Blotter Trade Size Pro PNG

O20 Futures Donchian Contracts Blotter Trade Timeline — Blotter Trade Timeline Pro PNG

O20 Futures Donchian Contracts Turnover Vs Performance — Turnover Vs Performance Pro PNG

Portfolio accounting

O20 Futures Donchian Contracts Composition — Composition PNG

Drawdown

O20 Futures Donchian Contracts Time Underwater — Time Underwater PNG

Distribution and optimization

O20 Futures Donchian Contracts Efficient Frontier — Efficient Frontier Pro PNG

Expected Return Profile Pro PNG

O20 Futures Donchian Contracts Omega Curve — Omega Curve Pro PNG

O20 Futures Donchian Contracts Return Quantiles — Return Quantiles PNG

O20 Futures Donchian Contracts Returns Distribution — Returns Distribution Pro PNG

Rolling diagnostics

O20 Futures Donchian Contracts Rolling Max Dd — Rolling Max Dd Pro PNG

O20 Futures Donchian Contracts Rolling Sharpe — Rolling Sharpe Pro PNG

O20 Futures Donchian Contracts Rolling Volatility — Rolling Volatility Pro PNG

O20 Futures Donchian Contracts Rolling Alpha — Rolling Alpha Pro PNG

O20 Futures Donchian Contracts Rolling Asset Correlations — Rolling Asset Correlations PNG

O20 Futures Donchian Contracts Rolling Beta — Rolling Beta Pro PNG

O20 Futures Donchian Contracts Rolling Sortino Ratio — Rolling Sortino Ratio PNG

O20 Futures Donchian Contracts Rolling Tail Risk — Rolling Tail Risk Pro PNG

O20 Futures Donchian Contracts Rolling Var Cvar — Rolling Var Cvar PNG

Simulation

Metrics

Parsed from performance_report.txt.

Executive Summary

Metric	Value	What it tells you
CAGR	4.67%	Annualized compound growth rate across the full backtest period.
Net Profit	$710,019	Dollar profit generated above the initial capital after the simulated run.
Sharpe Ratio	0.30	Excess return per unit of volatility using the configured risk-free rate.
Max Drawdown	-16.70%	Largest peak-to-trough portfolio decline in percentage terms.

Performance Breakdown

Metric	Value	What it tells you
MTD	0.86%	Month-to-date return at the report date.
QTD	4.51%	Quarter-to-date return at the report date.
YTD	8.17%	Year-to-date return at the report date.
1Y	8.17%	Trailing one-year return.
3Y (ann.)	4.09%	Annualized return over the trailing three-year window.
5Y (ann.)	3.50%	Annualized return over the trailing five-year window.
ITD	35.50%	Inception-to-date total return.
Cumulative Return	35.50%	Total compounded return over the full backtest period.
ATH Value	1.3779	Highest portfolio value reached when normalized to the initial portfolio base.
Drawdown from ATH	-1.66%	Current distance below the all-time high at the report date.

Risk-Adjusted Metrics

Metric	Value	What it tells you
Sharpe Ratio	0.30	Excess return divided by total volatility.
Smart Sharpe Ratio	0.30	Sharpe variant adjusted for serial correlation effects.
Sortino Ratio	0.43	Excess return divided by downside volatility only.
Smart Sortino Ratio	0.43	Sortino variant adjusted for serial correlation effects.
Calmar Ratio	0.28	Annualized return divided by absolute max drawdown.
Omega Ratio	1.09	Ratio of gains above a threshold to losses below it.
Information Ratio	-0.48	Active return divided by tracking error versus the benchmark.

Benchmark Comparison

Metric	Value	What it tells you
Benchmark Name	SPDR S&P 500 …	Benchmark used for comparison, beta, active return and information ratio.
Benchmark MTD	0.08%	Benchmark month-to-date return.
Benchmark QTD	2.67%	Benchmark quarter-to-date return.
Benchmark YTD	17.72%	Benchmark year-to-date return.
Benchmark 1Y	15.95%	Benchmark trailing one-year return.
Benchmark 3Y (ann.)	22.82%	Benchmark annualized trailing three-year return.
Benchmark 5Y (ann.)	14.72%	Benchmark annualized trailing five-year return.
Benchmark ITD	157.81%	Benchmark inception-to-date total return over the strategy sample.
Excess Return YTD	-9.38%	Strategy return minus benchmark return for the year-to-date window.
Active Return YTD (ann.)	-9.46%	Annualized active return for the year-to-date window.
Excess Return Full Period	-122.14%	Arithmetic difference of cumulative returns in percentage points — strategy minus benchmark over the whole sample.
Active Return Full Period (ann.)	-10.62%	Annualized active return across the full sample.

Risk Metrics

Metric	Value	What it tells you
Vol (Recent Window)	8.99%	Annualized volatility over the most recent rolling window.
Vol (Rolling Window)	11.13%	Annualized volatility over the configured rolling window.
Vol Recent Obs	30	Number of observations used for recent volatility.
Vol Rolling Obs	252	Number of observations in the rolling volatility window.
Peak Vol (95%)	15.06%	High-end volatility estimate from the rolling distribution.
VaR (95%) CF Normal	0.62%	One-period 95% Value-at-Risk under a normal approximation.
VaR (95%) Stress Vol	1.39%	Stress-calibrated 95% Value-at-Risk estimate.
Expected Shortfall	1.88%	Average loss conditional on being beyond the VaR threshold.
Stress Tail Obs	330
Tracking Error	23.39%	Annualized volatility of active return versus the benchmark.
Max Drawdown	-16.70%	Worst percentage peak-to-trough decline.
Max Drawdown ($)	-$449,409	Worst peak-to-trough decline translated into dollars for the configured capital.
Distribution Skewness	1.0645	Asymmetry of the return distribution.
Distribution Kurtosis	18.8965	Tail heaviness relative to a normal distribution.
Tail Risk Ratio	1.0495	Upside tail magnitude divided by downside tail magnitude.
Worst Loss Magnitude	2.82%	Worst single-period loss in the report frequency.
5 Worst Days Avg Loss	2.74%	Average return across the five worst days.

Market Dynamics

Metric	Value	What it tells you
CAPM Alpha (ann.)	3.72%	Annualized return unexplained by benchmark beta in a CAPM-style regression.
Beta	-0.04	Sensitivity to benchmark moves.
Up Capture	4.85%	How much of benchmark upside the strategy captures in up markets.
Down Capture	23.89%	How much of benchmark downside the strategy captures in down markets.
R-Squared	0.01	Share of strategy return variation explained by benchmark variation.
Correlation	-0.08	Linear co-movement between strategy and benchmark returns.

Strat Characteristics

Metric	Value	What it tells you
Inception Date	2019-05-06	First date included in the performance track record.
Current Date	2025-12-31	Final report date for the sample.
Track Record	6Y 7M	Length of the tested track record.
Strategy Type	Long / Short …	Strategy can be long or flat in cash rather than always invested or short.
Base Currency	USD	Currency used for capital, PnL and dollar metrics.
Long Exposure	64.55%	Current or average long exposure depending on report configuration.
Short Exposure	21.19%
Gross Exposure	85.73%	Total absolute exposure across long and short positions.
Position Count	4	Number of instruments in the active universe or current holdings.
Concentration	18.84%	Largest or representative concentration measure in the portfolio.
Raw Concentration	25.63%	Concentration before final clipping, accounting or reporting adjustments.
Effective Positions	4	Diversification estimate based on concentration rather than simple instrument count.

Exposure Path Checks

Metric	Value	What it tells you
Max Gross Exposure	95.16%	Highest gross exposure reached during the run.
Avg Gross Exposure	75.04%	Average absolute exposure across the backtest.
Max Long Exposure	95.16%	Highest long-side exposure reached during the run.
Max Short Exposure	68.18%
Min Cash Sleeve	4.84%	Lowest cash percentage observed in the simulated portfolio.
Max Cash Sleeve	168.18%	Highest cash percentage observed in the simulated portfolio.
Cash Sleeve Nonnegative	✓	Sanity check that cash did not go below zero when it should not.
Finite Weights	✓	Sanity check that target weights are finite numbers.

Trading Analytics

Metric	Value	What it tells you
Win Rate (Trade)	48.00%	Percentage of trades that were profitable.
Win Rate (Day)	51.31%	Percentage of daily observations with positive return.
Win Rate (Month)	56.25%	Percentage of positive months.
Profit Factor (Trade)	1.34	Gross winning trade PnL divided by gross losing trade PnL.
Recovery Factor	0.28	Net profit divided by maximum drawdown.
Expectancy	$119.64	Average expected profit per trade.
Avg Gain/Loss Ratio (Trade)	1.45	Average winning trade size divided by average losing trade size.
Largest Win	$19,885.32	Largest single winning trade.
Largest Loss	-$26,487.58	Largest single losing trade.
Average Win	$988.69	Mean profit across winning trades.
Average Loss	-$682.70	Mean loss across losing trades.
Max Consecutive Win Days	10	Longest streak of positive daily returns.
Max Consecutive Loss Days	10	Longest streak of negative daily returns.
Total Trades	978	Total buy and sell trade events.
Buy Trades	475	Number of buy-side trade events.
Sell Trades	503	Number of sell-side trade events.
Total FIFO Lot RTs	852	Matched entry-exit trade cycles.
Long FIFO Lot RTs	458	Round trips for long positions.
Short FIFO Lot RTs	394
Avg Lot Holding Period	101 days	Average time a matched position remains open.
Median Lot Holding Period	68 days	Median matched holding period.
Turnover (ann.)	277.14%	Annualized trading activity relative to portfolio value.
Avg Trade Size	$90,389	Average notional size of trade events.

Advanced Risk

Metric	Value	What it tells you
CVaR / Expected Shortfall (95%)	1.88%	Average loss conditional on being beyond the VaR threshold.
Serenity Index	0.93	Return quality measure that penalizes drawdown severity and persistence.

Advanced Trading

Metric	Value	What it tells you
Gain-to-Pain Ratio	1.09	Total gains divided by total losses over the period.
Drawdown-Vol Adj. Return	0.08	Return adjusted by both drawdown and volatility pressure.
Win Streak Concentration	0.02	Measures whether gains are concentrated in short winning streaks.
Kelly Criterion (Daily Returns)	0.94%	Theoretical capital fraction implied by win/loss profile.
Tail Ratio	1.05	Upper-tail return magnitude divided by lower-tail magnitude.

Operational Metrics

Metric	Value	What it tells you
Total Commission	$5,772.50	Total simulated commission paid across all trade events.
Commission (% Vol)	0.01%	Commission as a percentage of traded volume.
Total Volume	$88,400,925	Total simulated notional traded.
Instruments	4	Number of instruments traded or evaluated.

Consistency Checks

Metric	Value	What it tells you
Trade/2x FIFO Lot RT	0.57	Compares trade count to twice the FIFO lot round-trip count.
Avg Trades / FIFO Lot RT	1.15	Average number of trade events per FIFO lot round trip.
Strict Lot-Match Check	✗	Boolean check that FIFO lot matching completed cleanly.
Volume Consistency	0.19	Internal consistency score for volume reconstruction.
Volume Consistent	✗	Boolean sanity check for volume accounting.
RT Position-Day Load	51.05	Round-trip position-day load used to reconcile holding-period and exposure behavior.
RT Granularity	fifo_lot_level	Round-trip matching level used for trade analytics.

Execution Context

Metric	Value	What it tells you
Backtester Version	0.10.0+privat…	Version of the engine that generated the report.
Data Start	2019-05-06	First date available in the input data.
Data End	2026-01-01	Final date available in the input data.
Trading Days	1678	Number of trading-day observations in the dataset.
Reporting Frequency	daily	Frequency used for returns and report metrics.
Reporting Observations	1678	Number of observations used in the report calculations.
Reporting Periods/Year	252	Annualization factor used for daily metrics.
Initial Capital	$2,000,000	Starting capital used for dollar PnL and trade sizing.
Risk-Free Rate	2.00%	Risk-free rate used in excess-return calculations.
Slippage Model	FixedBpsSlipp…	Name of the slippage model used in the run.
Commission Model	PerShareCommi…	Name of the commission model used in the run.
Fill At	open	Configured fill timing convention for order-mode or execution assumptions.

Reproducibility

Metric	Value	What it tells you
Fingerprint	085b24af1ae03…	Run fingerprint tying configuration and data context to this output.
Config Hash	91a8de030457d…	Hash of configuration choices used by the run.
Data Hash	f3d701a8b481f…	Hash of input data used by the run.
Sanity Checks Passed	✗	Summary flag over the packet’s internal consistency checks: holding-period coverage, trade-to-round-trip lot matching, volume reconstruction and NAV reconciliation.

Interesting Times

Metric	Value	What it tells you
Crises Evaluated	9	Number of crisis windows that overlapped the strategy sample and were evaluated.
Crises Defined	20	Total crisis windows available in the library definition.
Avg Crisis Return	1.21%	Average strategy return across evaluated crisis windows.
Worst Crisis	2022 Rate Sho…	Crisis window with the worst strategy result.
Best Crisis	COVID Recovery	Crisis or recovery window with the best strategy result.
Crisis Hit Rate	33.33%	Share of evaluated crisis windows with positive strategy return.

Artifacts

Stable links that can be referenced from GitHub README files or external docs.

Run log run.log Text report performance_report.txt Published source snapshot strategy.py Structured report performance_report.json GitHub source example_orders_20_futures_donchian_contracts.py

Run log

Tail of the execution log for this packet.

Running strategy: example_orders_20_futures_donchian_contracts
File: <QJ_BACKTESTER_REPO>/strategies/example_orders_20_futures_donchian_contracts.py
Python: <QJ_BACKTESTER_REPO>/.venv/bin/python
Backtester: v0.10.0
Theme: quantjourney
Plot DPI: 300
Log Level: ERROR
Output: reports/canonical-suite-20260711


============================================================
  Strategy: ExampleOrders20_FuturesDonchianContracts
  Backtester: v0.10.0
  Period:   2019-05-06 → 2025-12-31
  Assets:   MES=F, MNQ=F, CL=F, GC=F
────────────────────────────────────────────────────────────
  Initial NAV:  $  2,000,000.00
  Final NAV:    $  2,710,018.60
  Total Return:         35.50%
  Ann. Volatility:      10.55%
  Max Drawdown:        -16.70%
  Sharpe Ratio:        0.2957
────────────────────────────────────────────────────────────
  Runtime Total:        22.78s
  Data Fetch:            2.80s
  Data Prep:             0.15s
  Calculation:           2.07s
  Reporting:            17.74s
============================================================

Share product feedback

Thank you.