ob-analytics 0.1.0

Limit order book analytics and visualization — reconstruct trades, classify orders, and visualize market microstructure from raw exchange events.

ob-analytics

Limit order book analytics and visualization for Python.

Reconstruct trades from raw exchange events, classify order types, compute depth metrics, and visualize market microstructure — from Bitstamp-style CSVs or LOBSTER message and orderbook files.

Ported from the R obAnalytics CRAN package. Now a standalone Python package with a pipeline API, pluggable formats, flow-toxicity metrics, and Matplotlib/Plotly backends.

---

Installation

pip install ob-analytics

With uv:

uv add ob-analytics

Optional extras:

pip install "ob-analytics[interactive]"   # Plotly figures
pip install "ob-analytics[live]"          # live exchange capture (websockets)

From source

Latest main, or a local clone for development:

pip install git+https://github.com/mczielinski/ob-analytics.git

# or
git clone https://github.com/mczielinski/ob-analytics.git
cd ob-analytics
pip install -e ".[interactive,live]"

Requires Python 3.11+. Core dependencies: NumPy, pandas, matplotlib, seaborn, pydantic, pyarrow, loguru.

Scale: in-memory (pandas) — comfortable to ~5M events (~5 GiB, session-scale data); for larger inputs, pre-slice by time window. See Scale envelope.

---

Quickstart

Bitstamp (bundled sample)

A 30-minute Bitstamp BTC/USD live capture (~314k events, ~280 trades) is bundled with the package as paired orders.csv.gz + trades.csv. Point the pipeline at the orders path; the companion trades file is auto-resolved:

from ob_analytics import Pipeline, sample_csv_path

result = Pipeline().run(sample_csv_path())

result.events         # enriched events with order types and aggressiveness
result.trades         # trades from the live feed, with maker/taker attribution
result.depth          # price-level volume time series
result.depth_summary  # best bid/ask, BPS bins, spread

LOBSTER

trading_date lives on RunContext, not on LobsterFormat:

from ob_analytics import Pipeline, LobsterFormat, RunContext

result = Pipeline(
    format=LobsterFormat(),
    ctx=RunContext(trading_date="2012-06-21"),
).run("/path/to/lobster_data")

Flow-toxicity metrics

Flow-toxicity metrics are plain functions you call on result.trades after the run — no pipeline configuration, no plugin registry:

from ob_analytics import Pipeline, compute_vpin, compute_kyle_lambda, sample_csv_path

result = Pipeline().run(sample_csv_path())
vpin = compute_vpin(result.trades, bucket_volume=10.0)
kyle = compute_kyle_lambda(result.trades)

Add your own by writing a function over a trades DataFrame — see the Extending guide.

Live capture (Bitstamp)

With the [live] extra installed, capture a live order book straight to orders.csv / trades.csv that the pipeline understands:

ob-analytics capture bitstamp --pair btcusd --out ./capture --minutes 30

ob-analytics capture --list shows registered venues. Add new ones by implementing the LiveCapturer protocol in ob_analytics.live.

See the full quickstart for step-by-step usage, configuration, custom loaders, flow-toxicity metrics, CLI commands, and demo scripts.

---

Development

The project uses uv for dependency management. A uv.lock lockfile is committed for reproducible installs.

git clone https://github.com/mczielinski/ob-analytics.git
cd ob-analytics
uv sync --group dev --extra interactive

Pre-commit hooks (Ruff lint/format, ty type check) are configured in .pre-commit-config.yaml:

uv run pre-commit install

Testing & CI

uv run pytest tests/ -v
uv run ruff check ob_analytics/ tests/
uv run ty check ob_analytics/

CI runs automatically on push/PR via GitHub Actions — lint, type check, pytest on Python 3.11/3.12/3.13, and Codecov coverage upload.

See ARCHITECTURE.md (or the rendered Architecture page) for design decisions, the module map, and class diagrams. See CHANGELOG.md for the release history.

---

Documentation

API reference generated from docstrings using Zensical (installed as a dev dependency):

uv run zensical serve      # local preview at http://localhost:8000
uv run zensical build      # static site in site/

---

Contributing

See CONTRIBUTING.md for development setup, code style, and conventions for adding new formats.

License

ob-analytics is licensed under the GNU General Public License v2.0 or later (GPL-2.0-or-later) — see LICENSE.md.

It is a Python port of the R obAnalytics package (© 2015–2016 Philip Stubbings), which is GPL-2.0-or-later; that copyleft is inherited here.

Citation

If you use ob-analytics in published work, please cite it — GitHub's Cite this repository button reads CITATION.cff, which also credits the original R obAnalytics lineage.