Glossary - sbOogway/sbt2 GitHub Wiki
Terms used across this wiki, grouped by topic.
| Term | Meaning |
|---|---|
| Split | Divides a run spec's period into train, validation and test, e.g. FractionSplit(validation=0.2, test=0.2). Resolved to dates. See Spec. |
| Part | One section of a split: train (tune), validation (check what you tuned, as often as you like), test (final answer, locked). Each is run separately with fresh capital. |
| In-sample / out-of-sample (IS / OOS) | In-sample is data you tuned on (train). Out-of-sample is data you didn't (validation, test). Only out-of-sample results say anything about the future. |
| Warm-up | Data streamed before a part starts so indicators have history. Orders are blocked during warm-up and nothing in it is measured. Declared by the strategy from its parameters. |
| Leakage / look-ahead | Any way information from the future, or from data you shouldn't see, reaches a decision. It makes results look better than they can be. |
| Walk-forward | Repeating tune → check over rolling windows through history instead of one fixed split. Deferred. |
| Splitter | The abstract base class that divides a backtest's period into parts; FractionSplit and DateSplit are the built-in ones. See Library. |
| Test lock | A test run is refused when its lineage already ran on overlapping test dates, unless overridden. See Run. |
| Lineage | All versions of one strategy class, keyed by its qualified name. |
| Trial | One candidate an optimiser tried, counted per lineage from the stored validation runs. The deflated Sharpe ratio corrects for the number of trials. |
| Probabilistic Sharpe ratio (PSR) | The probability that a run's true Sharpe is above a threshold, given its length, skew and kurtosis. See Results. |
| Deflated Sharpe ratio (DSR) | The PSR of the best of N trials, measured against the Sharpe that N tries would reach by luck. See Results. |
| Probability of backtest overfitting (PBO) | How often an optimiser's in-sample winner ranks below the median out of sample, estimated by CSCV. See Results. |
| CSCV | Combinatorially symmetric cross-validation: split the returns into blocks and try every even split into in-sample and out-of-sample halves. |
| Contaminated | Marks a test result that overrode the lock: its lineage had already run on those dates. |
| Survivorship bias | Testing only on instruments that still exist today, silently skipping the ones that died or were delisted. It inflates cross-sectional results. |
| Point-in-time universe | The set of instruments that actually existed at each moment in history. Removes survivorship bias. Deferred. |
| Term | Meaning |
|---|---|
| Run spec | One backtest as written: strategy, parameters, instruments, period, split and part, venue profile, capital, seed. See Spec. |
| Spec file | A TOML file of run specs, the CLI's equivalent of a sbt2.backtest call. Lists inside it expand into one run spec per combination (a batch). |
| Resolved run spec | A run spec with every name replaced by its contents: instrument ids, asset profile, the part's dates, venue profile values, parameter defaults, warm-up. It is a nautilus BacktestRunConfig plus split, part and strategy path. |
| Spec hash | Hash of the resolved run spec. Same hash = same backtest request. |
| Output sink | The interface run.execute hands its output to once, at the end of the run: equity, carry and nautilus's reports. The results store hands one out per run, writing straight into the run's folder. See Results. |
| run_id | A UUIDv7 (a unique id that sorts by creation time), new for every execution. Re-running a spec gives the same spec hash and a new run_id. |
| batch id | A UUIDv7 picked once per batch call and stored in the summary of each of its runs. A run started outside a batch has none. |
| Study | A named, persistent collection of runs of one strategy, on one fixed context, that differ only in their parameters, named by a spec file's study key. Its first run fixes the context and pins the strategy module's source; it holds many batches. The name is not hashed. See Results. |
| Context (of a study) | Everything a study fixes: the spec-file table without params, part and study. |
| RunOutput | The raw facts a run produced: equity, fills, positions, carry ledger, status. No metrics. |
| Summary / index | A run's summary.parquet (the run's spec, known gaps and headline metrics), written last, so only finished runs have one. The index is a DuckDB view over all summaries. See Results. |
| Golden run | A fixed spec whose results are stored; tests check it keeps producing the same numbers. See Quality. |
| Characterization test | A test that records how existing code (here: nautilus) behaves today, right or wrong, so a change to that behavior fails loudly. See Quality. |
| Term | Meaning |
|---|---|
| Data source / source adapter | A plug-in that knows how to fetch and parse one provider's raw data. See Data sources. |
| Catalog | nautilus's ParquetDataCatalog: nautilus data types stored as parquet files. Written only by ingest, in Data. |
| Instrument spec | An exchange's definition of an instrument: tick size, precision, lot size, margin. Kept as dated snapshots. Fees are set on the venue profile, not the spec. |
| Tick size / price precision | The smallest price step, and the number of decimals prices are written with. |
| L1 / L2 / L3 | Order-book depth. L1 is best bid/ask only; L2 is every price level with its total size; L3 is every individual order. |
| Snapshot / delta | A snapshot is the full book at one moment; a delta is one change to a level after that. |
F_SNAPSHOT / F_LAST |
nautilus flags on book deltas: part of a snapshot, and last delta of a batch (the book is consistent after it). |
ts_event / ts_init |
nautilus timestamps: when the event happened at the exchange, and when it was received/published. |
| Streaming / chunks | Reading the catalog piece by piece during a run instead of loading it all into memory. |
| Bar | Open/high/low/close/volume over a fixed interval, built by nautilus during the run (an INTERNAL bar type) from trades or from 1-minute candles. |
| Bar source | What a run's declared bars are built from, named by the run spec's bars key: a BarSource subclass; TradeBars and CandleBars are the built-in ones. See Spec. |
| Candle | A 1-minute bar as the source serves it (an EXTERNAL bar type), stored in the catalog and stamped 1 ns before its close. The only bars that are stored. |
| Known gaps | Per-source list of days confirmed missing at the source, in the data root's known_gaps.toml. The coverage check allows them and records them in the run's summary. See Data sources. |
| RPI trades | Bybit's Retail Price Improvement trades, marked in its dumps. Deferred. |
| Term | Meaning |
|---|---|
| Search space | The values the optimiser may try for each parameter, declared on the Params fields with Range. See Library. |
| Objective | What the optimiser ranks candidates by: a named metric or a function of a run's result. |
| Strategy base |
sbt2.core.strategy.Strategy: a thin subclass of nautilus's Strategy that every strategy extends. It adds parameters, warm-up and inputs readable without running, bar subscriptions and the warm-up gate. See Strategy. |
| Warm-up gate | The base drops orders submitted before the part's start, so a strategy's logic and indicators warm up without trading. The drawdown guard closes the same gate once it trips. |
| Engine |
run.execute: runs one backtest in the current process. A function in Run, not a module. |
| Drawdown guard | The spec's per-run risk.drawdown_limit, a fraction of peak equity. On each bar after warm-up, the strategy base compares total equity with its peak; when it falls the limit or more below, the base exits every position and drops all further orders. The trip time is the summary's drawdown_tripped_at. Order limits are nautilus's RiskEngine. |
| Bracket | A nautilus order list: an entry plus linked stop-loss and take-profit orders; when one exit fills, the other is cancelled. |
| Market making | Earning the spread by keeping buy and sell quotes in the book. |
| Market-neutral | A strategy whose returns don't depend on the market's overall direction, e.g. long one asset and short another. |
| Cross-sectional | A strategy that compares many instruments at once, e.g. buy the strongest, sell the weakest. |
| Term | Meaning |
|---|---|
| Venue / venue profile | The simulated exchange, and a named set of its settings (fees, fills, latency, margin, account). See Spec. |
| Maker / taker | Maker orders rest in the book and add liquidity; taker orders fill immediately against it. Usually charged different fees. |
| Slippage | The difference between the price you expected and the price you got. Comes from the fill model, never folded into fees. |
| Fill model | nautilus's rule for when and at what price simulated orders fill. |
| Latency model | Simulated delay between sending an order and the venue receiving it. |
| Netting (one-way mode) | One position per instrument; a buy reduces a short. The opposite is hedging mode. |
| Settlement currency | The currency the account and PnL are kept in (e.g. USDT). |
| Margin / leverage / liquidation | Collateral held against a position; position size relative to it; forced closing when collateral runs out. |
| Carry | Costs or income from holding a position rather than trading: funding on perps, rollover on FX, borrow fees and dividends on equities. |
| Carry module | A custom nautilus SimulationModule that charges carry nautilus doesn't cover itself (perp funding needs none). |
| Carry ledger | Every carry payment of a run. For funding it's read from nautilus's PositionAdjusted (Funding) events. |
| Perpetual (perp) | A futures contract with no expiry, kept close to the spot price by funding. |
| Funding | Periodic payment between longs and shorts on a perp, position size × mark price × funding rate. |
| Mark price | The exchange's fair-value price, used for funding, margin and liquidation instead of the last trade. |
| Spot | Owning the asset itself, with no leverage or funding. |
| Term | Meaning |
|---|---|
| Mark-to-market equity | Balance plus unrealized PnL of open positions, valued at the asset class's valuation price (mark price for perps). |
| Equity snapshots | Nautilus's own mark-to-market equity records: daily, plus every equity interval (1h by default) while a position is open. sbt2 reads them after the run. |
| Annualization | Scaling returns and volatility to a yearly figure. The number of periods per year comes from the asset class's calendar (365 days for 24/7 markets) and is passed as period to nautilus's statistics, which default to 252. |
| Sharpe / Sortino / Calmar | Return per unit of volatility; per unit of downside volatility only; per unit of max drawdown. |
| Max drawdown | The largest fall from a peak in equity before a new peak. |
| Profit factor / expectancy | Gross profit ÷ gross loss; average PnL per trade. |
| Turnover | How much is traded relative to capital. |
| Benchmark | What a strategy is compared against: buy-and-hold, equal-weight basket, external series, or none. Strategy metadata, not part of the run spec. |
| Tearsheet | A one-page report of a run's performance: nautilus's QuantStats-like tearsheet plus sbt2's own panels. |
| Term | Meaning |
|---|---|
| nautilus_trader | The event-driven trading engine sbt2 is built on: v2, a Rust core with Python bindings (PyO3), pinned to an exact release (see Quality). |
BacktestNode |
nautilus's high-level, config-driven backtest runner, which streams data from the catalog. |
| Actor | A nautilus component that receives events but doesn't trade. |
SimulationModule |
nautilus's hook for adding custom behaviour to a simulated venue. |
| Asset class / asset profile | A plug-in (AssetProfile) for one nautilus AssetClass + InstrumentClass pair, e.g. CRYPTOCURRENCY / SWAP: instrument type, calendar, annualization, carry, margin defaults, valuation price and buy-and-hold convention. See Asset classes. |
Config folder (SBT2_CONFIG) |
The directory holding the configuration sbt2 run reads: venues.toml, the venue profiles; given by --config or SBT2_CONFIG, required, with no default, read on every run. See Architecture. |
Data root (SBT2_DATA) |
The one directory holding raw files, catalog, results, known gaps and settings; given by --data or SBT2_DATA, required, with no default. See Architecture. |
| Pre-flight | Run's checks before a run starts: data coverage and instrument types. No memory estimate; the memory limit is the guard. |
cgroup MemoryMax |
A Linux kernel limit on a process's memory. The per-run memory cap under --launcher systemd, set with swap off (MemorySwapMax=0); a run over it is killed and the batch crashes with the error. |
| Forkserver | The process each run of a batch forks from: the standard library's multiprocessing forkserver, started at the parent's first batch with sbt2's run modules loaded, never a strategy. A script that starts a batch guards it with if __name__ == "__main__":. See Run. |
| Server image | The container image of sbt2[server], built from sbt2-backend/Containerfile: slim Python 3.14, linux/amd64, run as the non-root user sbt2, with its data and config on the volumes /data and /config. sbt2-backend/compose.yaml runs it; TLS is left to the operator. See Deployment on Architecture. |
| Launcher | How batch starts each run: uncapped (the default, memory left to the machine or container) or systemd (a capped transient scope). See Run. |
| Term | Meaning |
|---|---|
| Protocol | The protobuf messages the GUI and the server exchange, defined once in sbt2-protocol/ (package sbt2.protocol.v1); both sides generate their code from it. See Architecture. |
| Envelope | The one message per binary WebSocket frame: ClientMessage from the GUI, ServerMessage from the server, each a request_id and a oneof body. |
| Request id | The non-zero number a client gives a request; every answer carries it back. A push carries 0. |
| Push / subscription id | A ServerMessage the server sends unasked, with request_id = 0 and the subscription_id it belongs to. |
| Handshake | The client's Hello with its version, answered with Welcome: the server's version and capabilities. |
| Capability | A part of the protocol a server handles, listed in its Welcome. |
| API token | The one secret, SBT2_SERVER_TOKEN, a client presents as Authorization: Bearer <token> on the WebSocket handshake; without it the upgrade gets HTTP 401. See Architecture. |
Subprotocol (sbt2.v1) |
The WebSocket subprotocol a client must ask for on the handshake; without it the upgrade gets HTTP 400. |
| Route / handler | A body's field name in ClientMessage and the async function the server's router sends that body to; an area adds its routes to the server. |
| Outbox | Where a handler sends the messages a request causes besides its reply, through the connection's bounded outgoing queue: push never waits, send waits for room. |
| Chunked reply | An answer split over several ServerMessages with the request's request_id, numbered by index and closed by last, each at most 1 MiB. |
| Outgoing queue | The messages waiting to be sent to one client, at most queue_size (256); a client that falls further behind is closed with WebSocket code 1013. |
| Health check |
GET /health on the server's port, answered 200 OK without a token, before any WebSocket upgrade. |
| buf | The protobuf tool the repository's hooks use to format and lint sbt2-protocol/'s .proto files and reject breaking changes against main. The backend doesn't use it. See Quality. |
| Breaking change | A change to the .proto files that breaks the wire format, JSON or the generated code of a client built on the previous version; it needs a new package, sbt2.protocol.v2. |
| Generated code |
sbt2-server's sbt2.protocol.v1, written by scripts/generate-protocol.sh with the locked protoc and mypy-protobuf, and committed; never edited by hand. |