Depth Metrics¶

Order book depth computation: price-level volume tracking, depth summary metrics in basis-point bins, spread extraction, and depth filtering.

DepthMetricsEngine ¶

DepthMetricsEngine(config: PipelineConfig | None = None)

Incrementally compute order book depth metrics.

Replaces the monolithic :func:depth_metrics function with a stateful, testable class. :meth:compute processes a whole depth frame; internally each event is applied via :meth:update_side, which writes one metrics row into a pre-allocated numpy buffer.

Each book side is held as a pair of parallel numpy arrays sorted ascending by integer price: best lookup is O(1) (asks at index 0, bids at index -1), membership is O(log L) via searchsorted, crossed-level eviction is a contiguous slice, and BPS-bin sums vectorize over the in-window slice instead of iterating every active level in Python (levels average ~1.8k per side on the bundled sample, making that iteration the pipeline's former hot loop).

Output is written into a pre-allocated numpy matrix and converted to a DataFrame once at the end; bin boundaries are @lru_cache-d.

Parameters:

Name	Type	Description	Default
`config`	`PipelineConfig`	Pipeline configuration.	`None`

compute ¶

compute(depth: DataFrame) -> pd.DataFrame

Process an entire depth DataFrame and return metrics.

This is the main entry point, equivalent to the legacy :func:depth_metrics function.

Parameters:

Name	Type	Description	Default
`depth`	`DataFrame`	Price-level volume data with columns `timestamp`, `price`, `volume`, `direction`.	required

Returns:

Type	Description
`DataFrame`	Depth summary with `timestamp`, `best_bid_price`, `best_bid_vol`, `best_ask_price`, `best_ask_vol`, and volume-in-BPS-bin columns (e.g. `bid_vol25bps`).

update_side ¶

update_side(
    price: int, volume: float, side: int, out: ndarray
) -> None

Process one depth event and write a metrics row into out.

Parameters:

Name	Type	Description	Default
`price`	`int`	Price in integer units (e.g. cents).	required
`volume`	`float`	Volume at this price level (0 means deletion).	required
`side`	`int`	0 = bid, 1 = ask.	required
`out`	`ndarray`	Pre-allocated 1-D array of length `row_len` to fill.	required

depth_metrics ¶

depth_metrics(
    depth: DataFrame, bps: int = 25, bins: int = 20
) -> pd.DataFrame

Compute limit order book depth metrics.

This is a convenience wrapper around :class:DepthMetricsEngine.

Parameters:

Name	Type	Description	Default
`depth`	`DataFrame`	DataFrame containing depth data.	required
`bps`	`int`	Basis points increment for volume bins. Default is 25.	`25`
`bins`	`int`	Number of bins to use for volume aggregation. Default is 20.	`20`

Returns:

Type	Description
`DataFrame`	DataFrame containing depth metrics over time.

price_level_volume ¶

price_level_volume(events: DataFrame) -> pd.DataFrame

Calculate the cumulative volume for each price level over time.

Parameters:

Name	Type	Description	Default
`events`	`DataFrame`	A pandas DataFrame containing limit order events.	required

Returns:

Type	Description
`DataFrame`	A pandas DataFrame with the cumulative volume for each price level.

filter_depth ¶

filter_depth(
    d: DataFrame,
    from_timestamp: Timestamp,
    to_timestamp: Timestamp,
) -> pd.DataFrame

Filter depth data within a specified time range.

Parameters:

Name	Type	Description	Default
`d`	`DataFrame`	DataFrame containing depth data.	required
`from_timestamp`	`Timestamp`	Start of the time range.	required
`to_timestamp`	`Timestamp`	End of the time range.	required

Returns:

Type	Description
`DataFrame`	Filtered depth data within the specified time range.

get_spread ¶

get_spread(depth_summary: DataFrame) -> pd.DataFrame

Extract the bid/ask spread from the depth summary.

Parameters:

Name	Type	Description	Default
`depth_summary`	`DataFrame`	A pandas DataFrame containing depth summary statistics.	required

Returns:

Type	Description
`DataFrame`	A pandas DataFrame with the bid/ask spread data.