Statistics & Reporting¶

Objective¶

Use the statistics service to record market data and query OHLCV, VWAP, and trade history for analysis and reporting.

Prerequisites¶

Chapters 01–14 completed.
pm-stats running and at least a few trades executed.

Background¶

pm-stats subscribes to trade and book events and records them in a SQLite database at $EDUMATCHER_DATA_DIR/stats.db (this resolves relative to whatever data directory you configured in Chapter 00 — it is not a fixed data/stats.db path in the current working directory). The pm-stats-cli tool lets you query this data without writing SQL.

Exercise 1: Start the Statistics Service¶

pm-stats

Expected (the exact path shown reflects your EDUMATCHER_DATA_DIR):

[INFO] Stats service connected — recording to <EDUMATCHER_DATA_DIR>/stats.db

To confirm the active path with a stable command rather than trusting the log line, run:

pm-stats --help

and check the default shown for --db, or simply verify the file exists after the next exercise:

ls -la "$EDUMATCHER_DATA_DIR/stats.db"

Checkpoint: stats service running and $EDUMATCHER_DATA_DIR/stats.db exists.

Exercise 2: Generate Some Trading Activity¶

Ensure MMs and (optionally) AI traders are running. Execute a few manual trades:

TRADER01> NEW|SYM=AAPL|SIDE=BUY|TYPE=MARKET|QTY=100
TRADER01> NEW|SYM=AAPL|SIDE=SELL|TYPE=MARKET|QTY=50
TRADER01> NEW|SYM=MSFT|SIDE=BUY|TYPE=MARKET|QTY=200

Checkpoint: trades executed and recorded by stats service.

Exercise 3: Query OHLCV Data¶

pm-stats-cli ohlcv --symbol AAPL --interval 1m

Expected output (table or JSON):

timestamp           | open   | high   | low    | close  | volume
2026-06-18 09:30:00 | 150.05 | 150.10 | 149.95 | 150.05 | 350

Checkpoint: OHLCV data returned for AAPL.

Exercise 4: Query VWAP¶

pm-stats-cli vwap --symbol AAPL

Shows the volume-weighted average price across all trades in the current session.

Checkpoint: VWAP value returned.

Exercise 5: Query Trade Log¶

pm-stats-cli trades --symbol AAPL --limit 20

Shows the last 20 trades with timestamp, price, quantity, and aggressor side.

Checkpoint: trade log visible.

Exercise 6: Multi-Symbol Summary¶

pm-stats-cli summary

Shows a per-symbol overview:

Last price, day high, day low
Total volume
Number of trades
Current spread

Checkpoint: summary covers all active symbols.

Exercise 7: Export Data¶

pm-stats-cli trades --symbol AAPL --format csv > aapl_trades.csv

The CSV can be imported into Excel or a Jupyter notebook for further analysis.

Checkpoint: CSV export generated.

What Gets Recorded¶

Event	Stored Fields
Trade	timestamp, symbol, price, qty, aggressor side, buyer/seller gateway
Book snapshot	timestamp, symbol, best bid, best ask, bid size, ask size
OHLCV bar	open, high, low, close, volume per configurable interval
Session event	timestamp, old state, new state

Summary¶

You can now:

Configure and start the full exchange stack.
Provide liquidity with manual MM quotes or pm-mm-bot.
Trade using all order types and TIF values.
Manage orders (amend, cancel, status).
Run auctions and understand equilibrium pricing.
Quote as a market maker with full lifecycle understanding.
Use combo and OCO orders.
Configure and trigger risk controls.
Track P&L and positions.
Subscribe to market data and drop-copy feeds.
Generate realistic flow with AI traders.
Record and query statistics.

Reflection¶

Why does pm-stats need its own subscriber process and SQLite database instead of the engine writing OHLCV/VWAP data directly? What would happen to engine performance or reliability if it had to compute and serve statistics queries itself, in-process, for every connected client?