Bitstamp¶

Bitstamp-specific components: event loading, trade reading from companion trades.csv, CSV writing, and BitstampSource (the default pipeline source, which does both offline CSV replay and live WebSocket capture).

Modern workflows pair orders.csv with trades.csv (for example from ob-analytics capture bitstamp). The pipeline resolves trades.csv from the same directory as the orders.csv path passed to Pipeline.run.

BitstampLoader ¶

BitstampLoader(
    config: PipelineConfig | None = None,
    *,
    venue: str | None = None,
    symbol: str | None = None,
)

Load raw limit-order events from a Bitstamp-format CSV.

Satisfies the :class:~ob_analytics.protocols.EventLoader protocol.

Parameters:

Name	Type	Description	Default
`config`	`PipelineConfig`	Pipeline configuration. `price_decimals` and `volume_decimals` control rounding precision.	`None`
`venue`	`str`	Optional instrument identity. When either is supplied, the loaded frame gains per-row `venue` / `symbol` columns; `venue` falls back to `"bitstamp"` when only `symbol` is given. Both `None` (the default) leaves the frame untagged.	`None`
`symbol`	`str`	Optional instrument identity. When either is supplied, the loaded frame gains per-row `venue` / `symbol` columns; `venue` falls back to `"bitstamp"` when only `symbol` is given. Both `None` (the default) leaves the frame untagged.	`None`

load ¶

load(source: str | Path) -> pd.DataFrame

Read source CSV and return a cleaned events DataFrame.

Parameters:

Name	Type	Description	Default
`source`	`str or Path`	Path to a Bitstamp-format CSV with columns `id`, `timestamp`, `exchange_timestamp`, `price`, `volume`, `action`, `direction`.	required

Returns:

Type	Description
`DataFrame`	Cleaned events with columns `id`, `timestamp`, `exchange_timestamp`, `price`, `volume`, `action`, `direction`, `event_id`, `fill`, `original_number`.

Notes

Each order's rows come in the order they happened: the created row first, then the rest by timestamp. Rows that share an instant follow the file's sequence column when it has one; a deleted row then goes last, and the rest keep their order in the file. A row with no sequence number keeps its place after the row before it in the file. event_id numbers the rows of all orders by the same keys: time, then sequence, then file order. The order ids take no part. fill is the drop in size from the order's previous row. A row whose size rises (an order changed to a larger amount) has fill 0.

BitstampTradeReader ¶

BitstampTradeReader(config: PipelineConfig | None = None)

Build trades from the companion trades.csv that ob-analytics capture bitstamp writes next to orders.csv.

Reads each row from <source_dir>/trades.csv and projects it into the canonical trades schema, joining against the events frame to resolve buy_order_id / sell_order_id into event_id and original_number references.

A trade is matched to a row of the order it names whose fill is the trade's size, the earliest such row first. Bitstamp does not always report that size: an instant order bought by quote amount is created with size 0 and then shows a size of 0 or one lot, never what it bought. When no row shows the trade's size and the taker the trade names is such an order (one created with size 0), the trade is matched to that order's deleted row, else its latest row, and every such trade of that order names the same row. The order and its type are then right, but its rows show less fill than its trades. :func:~ob_analytics.analytics.data_quality_summary counts these trades as trades_matched_by_order.

Every other trade is matched on size only. A trade stays unresolved (NaN) when no row of its order shows its size: the events have no row of that order, or a message was lost. The same rules apply to captures from other venues read through this reader.

Satisfies the :class:~ob_analytics.protocols.TradeSource protocol.

BitstampWriter ¶

BitstampWriter(config: PipelineConfig | None = None)

Write pipeline events back to Bitstamp-format CSV.

Writes a folder laid out as ob-analytics capture bitstamp lays one out: orders.csv, and trades.csv when the run has trades.

Satisfies the :class:~ob_analytics.protocols.DataWriter protocol.

write ¶

write(
    data: dict[str, DataFrame],
    dest: str | Path,
    **kwargs: Any,
) -> Path

Write the events to <dest>/orders.csv in Bitstamp's format.

When data also carries a "trades" frame, a trades.csv is written next to it in capture format, so that a subsequent :class:BitstampTradeReader can reconstruct trades when the orders.csv is re-read. The events' sequence and origin columns are written too when the events carry them, so a capture read and written again keeps them.

Parameters:

Name	Type	Description	Default
`data`	`dict of str to DataFrame`	Must contain an `"events"` key. An optional `"trades"` key triggers a `trades.csv` in the same folder.	required
`dest`	`str or Path`	Output folder, created when missing.	required

Returns:

Type	Description
`Path`	The written `orders.csv` path.

Raises:

Type	Description
`ConfigError`	If the events have no rows: an L2 run has no per-order events.

BitstampSource ¶

BitstampSource(settings: SourceSettings | None = None)

The Bitstamp source: offline CSV replay and live WebSocket capture.

One descriptor for both ways to get Bitstamp data. It satisfies :class:~ob_analytics.protocols.OfflineSource (the CSV loader / trade reader / writer, inline and dependency-light) and :class:~ob_analytics.live._base.LiveSource (snapshot / stream / shutdown, delegated to a WebSocket engine imported lazily from :mod:ob_analytics.live.bitstamp). The lazy import is what keeps the offline path free of the [live] extra: importing this module never imports websockets; only starting a live capture does.

Conforms structurally to the source protocols — no inheritance required.

preflight ¶

preflight() -> None

Raise the install hint now if the [live] extra is missing (SupportsPreflight).

diagnostics ¶

diagnostics() -> dict[str, Any]

Per-run counters from the live engine (SupportsDiagnostics).