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.

The shared store

Examples marked Data: shared store read data/ and metadata/, which are not in the repository. Populate them once:

import manifoldbt as mbt
mbt.ingest(provider="binance", symbol="BTCUSDT", symbol_id=1,
           start="2021-01-01T00:00:00Z", end="2025-01-01T00:00:00Z")

Add the symbols an example asks for; each names them in its universe. 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 ⚠

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