Implementation:Nautechsystems Nautilus trader TradeTickDataWrangler Process
| Field | Value |
|---|---|
| sources | https://github.com/nautechsystems/nautilus_trader , https://nautilustrader.io/docs/ |
| domains | data engineering, backtesting, market data transformation |
| last_updated | 2026-02-10 12:00 GMT |
Overview
Concrete tool for transforming raw trade-tick DataFrames into typed TradeTick objects provided by NautilusTrader.
Description
The TradeTickDataWrangler class is a Cython extension type that takes an Instrument at construction time and exposes a process() method that converts a pandas DataFrame of trade data into a list of TradeTick objects. It handles UTC normalization, timestamp pairing (ts_event / ts_init), optional raw-data descaling, and aggressor-side inference from side or buyer_maker columns. A companion method process_bar_data() synthesizes trade ticks from OHLCV bars.
Usage
Import and instantiate TradeTickDataWrangler whenever you have a pandas DataFrame of historical trade data and need to convert it into NautilusTrader TradeTick objects suitable for injection into a BacktestEngine.
Code Reference
- Source location:
nautilus_trader/persistence/wranglers.pyx, lines 510--701 - Signature:
class TradeTickDataWrangler:
def __init__(self, instrument: Instrument) -> None
def process(
self,
data: pd.DataFrame,
ts_init_delta: int = 0,
is_raw: bool = False,
) -> list[TradeTick]
- Import:
from nautilus_trader.persistence.wranglers import TradeTickDataWrangler
I/O Contract
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
instrument (constructor) |
Instrument |
Yes | The instrument whose precision settings govern price/size construction. |
data |
pd.DataFrame |
Yes | DataFrame with columns price, quantity, trade_id, and optionally side or buyer_maker. Index must be a DatetimeIndex.
|
ts_init_delta |
int |
No | Nanosecond offset added to ts_event to produce ts_init. Simulates data latency. Default 0.
|
is_raw |
bool |
No | If True, price and quantity values are divided by FIXED_SCALAR (Nautilus fixed-point descaling). Default False.
|
Outputs:
| Output | Type | Description |
|---|---|---|
| Trade ticks | list[TradeTick] |
Ordered list of TradeTick objects with nanosecond-precision timestamps, instrument-correct price/size precision, and inferred aggressor side.
|
Raises:
| Exception | Condition |
|---|---|
ValueError |
The input DataFrame is empty. |
Usage Examples
Basic trade tick wrangling from a CSV:
import pandas as pd
from nautilus_trader.persistence.wranglers import TradeTickDataWrangler
from nautilus_trader.test_kit.providers import TestInstrumentProvider
# Load instrument definition
instrument = TestInstrumentProvider.ethusdt_binance()
# Load raw trade data
df = pd.read_csv("trades.csv", index_col="timestamp", parse_dates=True)
# Wrangle into TradeTick objects
wrangler = TradeTickDataWrangler(instrument)
ticks = wrangler.process(df)
print(f"Produced {len(ticks)} trade ticks")
print(ticks[0])
Wrangling with simulated latency:
# Simulate 50 microseconds of data latency
ticks = wrangler.process(df, ts_init_delta=50_000)
Synthesizing trade ticks from OHLCV bar data:
bars_df = pd.read_csv("bars_1min.csv", index_col="timestamp", parse_dates=True)
ticks = wrangler.process_bar_data(
bars_df,
ts_init_delta=0,
offset_interval_ms=100,
timestamp_is_close=True,
random_seed=42,
)