Skip to content

Flow Toxicity Metrics

Market microstructure measures for detecting informed trading and quantifying price impact.

Functions

compute_vpin 

compute_vpin(
    trades: DataFrame,
    bucket_volume: float,
    n_buckets: int = 50,
    sign_method: str | None = None,
    quotes: DataFrame | None = None,
) -> pd.DataFrame

Compute the Volume-Synchronized Probability of Informed Trading.

Partitions cumulative trade volume into equal-sized buckets and measures the normalised buy/sell imbalance within each bucket. The trailing average of vpin over n_buckets is the headline VPIN metric.

Works on feeds without a native aggressor side. When the trades frame has no direction, the buy/sell split is inferred with a trade-sign classifier (see sign_method), so VPIN runs on L2 / aggregated captures too.

Parameters:

Name Type Description Default
trades DataFrame

Trades with at least timestamp, price, and volume. A direction column ("buy" / "sell", the taker side) is used when present; otherwise it is inferred — see sign_method.

 required
bucket_volume float

Total volume per bucket. This is highly instrument-specific — a reasonable starting point is average daily volume / 50.

 required
n_buckets int

Window length (in buckets) for the trailing VPIN average. Default is 50, following the original paper.

 50
sign_method str

How to obtain the buy/sell split when there is no native direction. None (default) uses an existing direction if present, else falls back to a per-trade classifier (Lee–Ready when quotes are given, otherwise the tick rule). "tick" / "lee_ready" force a per-trade classifier (:func:~ob_analytics.trade_sign.classify_trade_sign), overriding any native direction. "bvc" splits each volume bar with bulk volume classification (:func:~ob_analytics.trade_sign.bulk_volume_classification) — the VPIN-native estimator, which needs no per-trade sign at all.

 None
quotes DataFrame

Quote frame for sign_method="lee_ready" (or the None fallback when quotes are available) — passed through to :func:~ob_analytics.trade_sign.classify_trade_sign.

 None

Returns:

Type Description
DataFrame

One row per completed bucket with columns:

  • bucket — zero-based bucket index
  • timestamp_start — first trade timestamp in the bucket
  • timestamp_end — last trade timestamp in the bucket
  • buy_volume — total buy volume in the bucket
  • sell_volume — total sell volume in the bucket
  • vpin — |buy_volume - sell_volume| / bucket_volume
  • vpin_avg — trailing mean of vpin over n_buckets

Raises:

Type Description
ConfigError

If required columns are missing.
ObAnalyticsError

If trades is empty.
ValueError

If bucket_volume is not positive.

compute_kyle_lambda 

compute_kyle_lambda(
    trades: DataFrame, window: str = "5min"
) -> KyleLambdaResult

Estimate Kyle's Lambda via OLS regression.

For each time window, computes:

  • ΔPrice = last trade price − first trade price
  • signed_volume = Σ(buy volume) − Σ(sell volume)

Then regresses ΔPrice on signed_volume across all windows. The slope (λ) measures how much the price moves per unit of net order flow — a proxy for market illiquidity and adverse selection.

Parameters:

Name Type Description Default
trades DataFrame

Trades with timestamp, price, volume, direction.

 required
window str

Pandas frequency string for grouping trades. Default "5min".

 '5min'

Returns:

Type Description
KyleLambdaResult

Frozen dataclass with lambda_, t_stat, r_squared, n_windows, and regression_df.

Raises:

Type Description
ConfigError

If required columns are missing.
ObAnalyticsError

If trades is empty.

order_flow_imbalance 

order_flow_imbalance(
    trades: DataFrame,
    window: str = "1min",
    sign_method: str | None = None,
    quotes: DataFrame | None = None,
) -> pd.DataFrame

Compute normalised order flow imbalance per time window.

For each window:

  • ofi = (buy_volume − sell_volume) / (buy_volume + sell_volume)

Values range from −1 (all sells) to +1 (all buys). Zero indicates balanced flow.

Works on feeds without a native aggressor side: when the trades frame has no direction, it is inferred with a per-trade trade-sign classifier (see sign_method).

Parameters:

Name Type Description Default
trades DataFrame

Trades with timestamp and volume. A direction column ("buy" / "sell") is used when present; otherwise it is inferred — see sign_method (which additionally requires price).

 required
window str

Pandas frequency string. Default "1min".

 '1min'
sign_method str

How to obtain the buy/sell split when there is no native direction. None (default) uses an existing direction if present, else falls back to a per-trade classifier (Lee–Ready when quotes are given, otherwise the tick rule). "tick" / "lee_ready" force a per-trade classifier, overriding any native direction. ("bvc" is VPIN-native; use :func:compute_vpin.)

 None
quotes DataFrame

Quote frame for sign_method="lee_ready" — passed through to :func:~ob_analytics.trade_sign.classify_trade_sign.

 None

Returns:

Type Description
DataFrame

Columns: timestamp, buy_volume, sell_volume, net_volume, ofi.

Raises:

Type Description
ConfigError

If required columns are missing.
ObAnalyticsError

If trades is empty.

Models

KyleLambdaResult dataclass 

KyleLambdaResult(
    lambda_: float,
    t_stat: float,
    r_squared: float,
    n_windows: int,
    regression_df: DataFrame = pd.DataFrame(),
)

Result of a Kyle's λ OLS regression.

Attributes:

Name Type Description
lambda_ float

Slope — price change per unit signed order flow (higher = less liquid).
t_stat float

t-statistic for lambda_.
r_squared float

Fraction of ΔPrice variance explained by signed order flow.
n_windows int

Number of time windows in the regression.
regression_df DataFrame

Per-window timestamp/delta_price/signed_volume data.