manifoldbt/examples/README.md

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 exit a candle has to guess, put back to the trades	synthetic, not runnable yet

⚠ marks the two files whose fixture determines the outcome, as described above.

27 does not run today, on any licence. The tick layer it uses belongs to the Pro+ tier, and that tier is not on sale: the code ships ahead of the plan that will carry it. The file is there to be read, and it will run unchanged when the tier opens. It is also the only example that wants pandas, for the join between its trade log and its bars.

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