Examples
Each file demonstrates one mechanism of the engine and stops there. They are documentation that happens to execute, not strategies: several would lose money traded as written, and that is not a defect.
The contract
Every example opens with the same four blocks, in this order:
"""One-line title -- the mechanism, named.
Demonstrates:
- the two or three API surfaces the file exists to show
Data: <provenance>
Usage:
python examples/NN_name.py
"""
Data: is the block that matters most, and it is not optional. An example is
read by someone deciding whether to trust a number, so where the number came
from is part of the example.
The three data provenances
Data: shared store -- real market data from data/, ingested once and
reused. These examples need that store to exist (see below). Their results are
real in the sense that the prices are real; they are still not investment
advice, and none of the strategies is tuned.
Data: self-contained (network) -- the file ingests what it needs on each
run, from a free connector. Runs on a fresh clone, needs a network.
Data: synthetic (seed N) -- the file generates its own series. Always
reproducible, never a market claim.
The rule on synthetic data
Synthetic data is legitimate and often the right choice: it isolates a mechanism from market noise, and it lets an example run anywhere with no dependency. It is used deliberately here, not as a fallback.
The one thing it must never do is let a reader mistake a fixture for a result. So when the construction of the series determines the outcome, the file says so before printing any figure, and marks the affected numbers. Two examples are in that case:
| What the fixture determines | |
|---|---|
21_fill_at_computed_level.py |
the series is detrended, so mean reversion cannot lose on it -- only the gap between two execution prices is meaningful |
25_lookahead_trap.py |
the leak is deliberate; the file exists to show which audits fail to see it |
A synthetic example whose fixture does not predetermine the outcome carries no such warning, because there is nothing to warn about.
The rule on performance
No example is selected, tuned, or presented for its returns. Where a figure appears it illustrates the mechanism under discussion. If an example ever produced a reproducible edge on real data, it would belong in a private repository rather than in documentation.
Running them
pip install manifoldbt # the engine
pip install manifoldbt[plot] # and the charts, if you want them drawn
python examples/13_stochastic_simulation.py
Charts are an optional extra. Without it an example still runs to the end and
skips its chart, saying so -- no file here needs [plot] to be useful, except
06_full_visualization.py, which is nothing but charts.
The shared store
Examples marked Data: shared store read data/ and metadata/, which are
not in the repository: market data does not belong in a git repository.
Download what they need, once, from the repository root:
python examples/setup_data.py
That ingests the ten Binance perpetuals and the one dYdX perpetual these files name, at 1h, over the range they cover. The engine aggregates upwards, so the same 1h store serves the examples running on 12h or daily bars. Both connectors are free on all tiers and need no API key.
Doing it by hand takes one call per symbol, and the asset_class is the part
that is easy to get wrong -- the examples ask for BTC-USDT:perp, and the
default (crypto_spot) stores a symbol they will not find:
import manifoldbt as mbt
mbt.ingest(provider="binance", symbol="BTCUSDT", symbol_id=1, interval="1h",
asset_class="crypto_perp",
start="2021-01-01T00:00:00Z", end="2026-03-01T00:00:00Z")
The self-contained and synthetic examples need none of this.
Index
| Example | Mechanism | Data | |
|---|---|---|---|
| 00 | 00_template.py |
the minimal shape of a backtest | shared store |
| 01 | 01_trend_following.py |
fluent builder, EMA, stop-loss, diagnostics | shared store |
| 02 | 02_mean_reversion.py |
bands, z-score, conditional sizing | shared store |
| 03 | 03_multi_asset_momentum.py |
cross-sectional ranking over a universe | shared store |
| 04 | 04_linear_regression.py |
rolling regression as a signal | shared store |
| 05 | 05_stat_arb.py |
pair spread, cross-asset references | shared store |
| 06 | 06_full_visualization.py |
the whole plotting surface | shared store |
| 07 | 07_walk_forward.py |
fold geometries, out-of-sample selection | shared store |
| 08 | 08_sweep_2d_heatmap.py |
a two-parameter sweep, read as a surface | shared store |
| 09 | 09_surface_3d.py |
the same surface in three dimensions | shared store |
| 10 | 10_monte_carlo.py |
bootstrap resampling, rare-event metrics | shared store |
| 11 | 11_portfolio.py |
several strategies in one book, rebalancing | shared store |
| 12 | 12_diagnostics.py |
look-ahead, exposure, risk checks | shared store |
| 13 | 13_stochastic_simulation.py |
SDE paths from the expression DSL | synthetic |
| 14 | 14_multi_timeframe.py |
higher timeframes, and how periods count | shared store |
| 15 | 15_cross_exchange.py |
signal on one venue, execution on another | shared store |
| 16 | 16_hashrate_exogene.py |
an exogenous series joined onto the bars | shared store |
| 17 | 17_per_venue_fees.py |
per-venue fee schedules in one book | shared store |
| 18 | 18_csv_import.py |
CSV / MT4 / MT5 import | synthetic |
| 19 | 19_custom_indicators.py |
composing an indicator from primitives | shared store |
| 20 | 20_entry_orders.py |
limit, stop and market-if-touched entries | shared store |
| 21 | 21_fill_at_computed_level.py |
filling at a level computed in advance | synthetic ⚠ |
| 22 | 22_yahoo_equities.py |
stocks, ETFs, indices, FX via Yahoo | network |
| 23 | 23_deribit_options.py |
option contracts that expire and settle | network |
| 24 | 24_option_spread.py |
a two-leg option structure | network |
| 25 | 25_lookahead_trap.py |
the look-ahead no re-run can detect | synthetic ⚠ |
| 26 | 26_fill_costs.py |
the same signal filled four ways, and what each costs | shared store |
| 27 | 27_bars_vs_tape.py |
the same bracket resolved on the candle and on the trades inside it | network, Researcher |
| 28 | 28_trade_clock_market_maker.py |
a market maker on the trade clock: queue, latency, and what each fill cost | network, Researcher |
| 29 | 29_reconcile_live_fills.py |
a broker's own fills against the backtest of the same days | network, Researcher |
| 33 | 33_trade_clock_order_flow.py |
an order-flow taker on the trade clock, and the fee it has to beat | network, Researcher |
⚠ marks the two files whose fixture determines the outcome, as described above.
27, 28, 29 and 33 need the Researcher plan. Reading a stored tape or a stored book is a Researcher feature, and a Pro licence does not unlock it. Without it they exit with the refusal message rather than a traceback.
27 is the small door: fill_resolution="ticks" keeps the bar grid and resolves
stop-loss, take-profit, trailing and entry levels against the individual trades
of each bar instead of against its high and low, and result.tape_resolution
counts what the tape decided. 28 is the whole layer on one BTCUSDT day: one
simulation row per print, a quote that lives one second, the queue in front of
it read from a stored book, a twenty millisecond round trip, and
result.fill_marks saying what being quoted actually cost. 29 is the check on
all of it: bt.reconcile puts a journal of the fills a broker really granted
beside the backtest of the same days, marked by the same code and counted the
same way, and says where the two part company -- its journal is SYNTHETIC, the
run's own fill log degraded on purpose, so the file can show what the tables
read like without pretending to data it does not have. Read them in that order;
docs/strategy-authoring.md, "Backtesting on the Tape", is the map.
Two files here are not examples and carry no number:
| File | What it is |
|---|---|
setup_data.py |
downloads the shared store, once |
_bootstrap.py |
opens that store, and reports a missing plotting extra |