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 scripts/collect_bitstamp_btcusd.py). 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`.

BitstampTradeReader ¶

BitstampTradeReader(config: PipelineConfig | None = None)

Build trades from the companion trades.csv produced by scripts/collect_bitstamp_btcusd.py.

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.

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

write ¶

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

Write the events DataFrame to a Bitstamp-format CSV.

When data also carries a "trades" frame, a companion trades.csv is written next to dest in capture format, so that a subsequent :class:BitstampTradeReader can reconstruct trades when the orders.csv is re-read.

Parameters:

Name	Type	Description	Default
`data`	`dict of str to DataFrame`	Must contain an `"events"` key. An optional `"trades"` key triggers a companion `trades.csv` alongside dest.	required
`dest`	`str or Path`	Output CSV file path.	required

Returns:

Type	Description
`Path`	The written events CSV path.

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).