Skip to content

quantpylib.hft.alpha

Alpha

Bases: Simulator

The Alpha class extends the Simulator class for implementing a backtest simulator for high-frequency trading (HFT) strategies.

This class includes functionalities for handling order submissions, fills, and portfolio management. It allows for the simulation of a trading strategy's performance, including tracking inventory, cash, equity, and other portfolio metrics.

Attributes:

Name Type Description
cash float

The initial cash balance.
maker_fees float

The fee rate for maker orders.
taker_fees float

The fee rate for taker orders.
maker_logs ndarray

Array of logs for maker orders.
taker_logs ndarray

Array of logs for taker orders.
maker_fills ndarray

Array of filled maker orders.
portfolio_df DataFrame

DataFrame containing portfolio information including position, equity, and pnl.

__init__(maker_fees=0.0, taker_fees=0.0, cash=10000, **kwargs)

Initializes the Alpha class with trading fees and initial cash.

Parameters:

Name Type Description Default
maker_fees float

The fee rate for maker orders. Defaults to 0.0000. 0.0001 means 0.01%. Negative are rebates.

 0.0
taker_fees float

The fee rate for taker orders. Defaults to 0.0000. 0.0001 means 0.01%. Negative are rebates.

 0.0
cash float

The initial cash balance. Defaults to 10000.

 10000
**kwargs

Additional keyword arguments passed to the Simulator class constructor.

 {}

cloid()

Generate a unique client order ID (cloid), can be used to track orders.

Returns:

Name Type Description
int

A unique client order ID.

df_actions(plot=False, only_fills=True, ax=None)

Generate and optionally plot a DataFrame of actions, including maker and taker fills and logs. In plots, buy/sell orders are green/red. Maker/taker orders are circle/squares. Filled orders shapes colored in, while unfilled orders are not colored in.

Parameters:

Name Type Description Default
plot bool

If True, plot the order logs. Defaults to False.

 False
only_fills bool

If True, only plots filled orders. Defaults to True.

 True
ax Axes

Axis to plot on. Defaults to None.

 None

Returns:

Name Type Description
dict

A dictionary containing maker fills, taker logs, and maker logs.

df_markouts(plot=True)

Calculate and optionally plot markouts for filled trades over different time intervals.

Parameters:

Name Type Description Default
plot bool

If True, plot the markout values. Defaults to True.

 True

Returns:

Type Description

pd.DataFrame: A DataFrame containing the markout values for different time intervals.

df_portfolio(plot=False, plot_portfolio=True, plot_prices=False)

Generate and optionally plot a DataFrame containing portfolio information, including position and pnl.

Parameters:

Name Type Description Default
plot bool

If True, plot the portfolio information. Defaults to False.

 False
plot_portfolio bool

If True, plot the portfolio position and pnl. Defaults to True.

 True
plot_prices bool

If True, overlay price data on the plot. Defaults to False.

 False

Returns:

Type Description

pd.DataFrame: A DataFrame containing portfolio information.

event_orders_fill(cash, equity, position, ts, event_type, event_id, type_id, trade_buffer, ob_timestamps, ob_bids, ob_asks, ob_mids, features, running_event_ids, running_type_ids, orders, filled_orders, is_maker, **kwargs)

Handle filled orders based on market events. Allowed to cancel orders in orders by returning the subset of cloids in orders. Order creation and modification is not allowed on order fill.

Parameters:

Name Type Description Default
cash float

Current cash balance.

 required
equity float

Current equity value.

 required
position int

Current position size.

 required
ts int

Timestamp of the event.

 required
event_type int

Type of the event (e.g., EVENT_CLOCK, EVENT_LOB, EVENT_TRADE).

 required
event_id int

Index of the event among all events.

 required
type_id int

Index of the event among this event type.

 required
trade_buffer ndarray

Array of trade events. If event_type == EVENT_TRADE, the trade event at this event is trade_buffer[type_id].

 required
ob_timestamps ndarray

Array of order book timestamps. If event_type == EVENT_LOB, the orderbook timestamp at this event is ob_timestamp[type_id].

 required
ob_bids ndarray

Array of best bid prices and sizes. If event_type == EVENT_LOB, the orderbook bids at this event is ob_bids[type_id].

 required
ob_asks ndarray

Array of best ask prices and sizes. If event_type == EVENT_LOB, the orderbook asks at this event is ob_asks[type_id].

 required
ob_mids ndarray

Array of mid prices. If event_type == EVENT_LOB, the orderbook mid at this event is ob_mids[type_id].

 required
features dict

Dictionary of computed features, with key as event_type. Feature scalar computed at this timestamp can be referenced using features[event_type][feature_name][type_id].

 required
running_event_ids dict

Dictionary of currently running event IDs with key-value event_type : event_id.

 required
running_type_ids dict

Dictionary of currently active type IDs with key-value event_type : type_id. For instance, at this event, the last-known trade/trade-features can be obtained with trade_buffer[running_type_ids[EVENT_TRADE]] / features[EVENT_TRADE][feature_name][running_type_ids[EVENT_TRADE]].

 required
orders ndarray

Array of current orders.

 required
filled_orders ndarray

Array of filled orders.

 required
is_maker bool

True if the fills are from maker orders, False if from taker orders.

 required
**kwargs

Additional keyword arguments.

 {}

Returns:

Type Description

List of orders to cancel by cloids.

event_orders_update(cash, equity, position, ts, event_type, event_id, type_id, trade_buffer, ob_timestamps, ob_bids, ob_asks, ob_mids, features, open_orders, running_event_ids, running_type_ids, **kwargs)

Update orders on event. Return None for no change to orders, return [] to cancel all orders, otherwise return list of orders, each order is format (price, size, dir, cloid). Market orders are just aggressive taker prices. Cloid is not used in logic, you may set to any value desired.

Parameters:

Name Type Description Default
cash float

Current cash balance.

 required
equity float

Current equity value.

 required
position int

Current position size.

 required
ts int

Timestamp of the event.

 required
event_type int

Type of the event (e.g., EVENT_CLOCK, EVENT_LOB, EVENT_TRADE).

 required
event_id int

Index of the event among all events.

 required
type_id int

Index of the event among this event type.

 required
trade_buffer ndarray

Array of trade events. If event_type == EVENT_TRADE, the trade event at this event is trade_buffer[type_id].

 required
ob_timestamps ndarray

Array of order book timestamps. If event_type == EVENT_LOB, the orderbook timestamp at this event is ob_timestamp[type_id].

 required
ob_bids ndarray

Array of best bid prices and sizes. If event_type == EVENT_LOB, the orderbook bids at this event is ob_bids[type_id].

 required
ob_asks ndarray

Array of best ask prices and sizes. If event_type == EVENT_LOB, the orderbook asks at this event is ob_asks[type_id].

 required
ob_mids ndarray

Array of mid prices. If event_type == EVENT_LOB, the orderbook mid at this event is ob_mids[type_id].

 required
features dict

Dictionary of computed features, with key as event_type. Feature scalar computed at this timestamp can be referenced using features[event_type][feature_name][type_id].

 required
open_orders ndarray

Array of currently open orders.

 required
running_event_ids dict

Dictionary of currently running event IDs with key-value event_type : event_id.

 required
running_type_ids dict

Dictionary of currently active type IDs with key-value event_type : type_id. For instance, at this event, the last-known trade/trade-features can be obtained with trade_buffer[running_type_ids[EVENT_TRADE]] / features[EVENT_TRADE][feature_name][running_type_ids[EVENT_TRADE]].

 required
**kwargs

Additional keyword arguments.

 {}

Returns:

Type Description

List of updated orders. If return None, assume no change in orders (same as return open_orders).

run_simulation()

Run the trading simulation, processing events and updating the portfolio accordingly. On each (except EVENT_TRADE), we are allowed to update orders with self.event_orders_update. EVENT_TRADE is excluded from order updation since the trade event itself creates non-trivial market impact and reaction; new orders created have miscellaneous queue position.

Returns:

Type Description
DataFrame

A DataFrame containing the portfolio's position, equity, and pnl over time.

Model

Bases: Simulator

A model that extends the Simulator class for estimating market features and/or doing fair price estimation.

This class provides additional functionalities for running estimators on market events, computing features, and analyzing fair prices. It includes methods to generate data frames of estimators and fair price statistics.

Attributes:

Name Type Description
estimator_df DataFrame

A DataFrame containing the results of the event estimator.

__init__(**kwargs)

Initializes the Model with inherited Simulator attributes.

Parameters:

Name Type Description Default
**kwargs

Additional keyword arguments passed to the Simulator class initializer.

 {}

df_estimators(include_forwards=True, include_zero=True, return_labels=False)

Generate a DataFrame of estimator values with optional look-forward prices at different intervals for analysis.

Parameters:

Name Type Description Default
include_forwards bool

If True, includes forward prices in the returned DataFrame. Defaults to True.

 True
include_zero bool

If True and include_forwards=True, include the last-known orderbook mid price in the returned DataFrame. Defaults to True.

 True
return_labels bool

If True, returns the estimator DataFrame along with forward looking second intervals and labels. Defaults to False.

 False

Returns:

Type Description

pd.DataFrame or tuple: A DataFrame of estimator values and forward prices, and optionally intervals and labels if return_labels is True.

df_fairprices(plot=True)

If the estimators returned in event_estimator are fair price estimators, this utility function gives useful statistical properties about the estimator, as well as estimation errors. Optionally plot the results.

Parameters:

Name Type Description Default
plot bool

If True, plots the fair price differences. Defaults to True.

 True

Returns:

Name Type Description
tuple

A tuple containing: - statistics (dict): A dictionary of statistical measures for each estimator and interval. - estimator_df (pd.DataFrame): A DataFrame of estimator and forward-looking feature values.

event_estimator(ts, event_type, event_id, type_id, trade_buffer, ob_timestamps, ob_bids, ob_asks, ob_mids, features, running_event_ids, running_type_ids, **kwargs)

Estimate market features based on events. Returned dictionary should be a key-value pair of estimator_name : estimator_scalar at this event. Return None or empty dictionary if no estimate is made.

Parameters:

Name Type Description Default
ts int

The timestamp of the event.

 required
event_type int

The type of the event (e.g., EVENT_CLOCK, EVENT_LOB, EVENT_TRADE).

 required
event_id int

The index of the event among all events.

 required
type_id int

The index of the event among this event type.

 required
trade_buffer ndarray

Array of trade events. If event_type == EVENT_TRADE, the trade event at this event is trade_buffer[type_id].

 required
ob_timestamps ndarray

Array of order book timestamps. If event_type == EVENT_LOB, the orderbook timestamp at this event is ob_timestamp[type_id].

 required
ob_bids ndarray

Array of best bid prices and sizes. If event_type == EVENT_LOB, the orderbook bids at this event is ob_bids[type_id].

 required
ob_asks ndarray

Array of best ask prices and sizes. If event_type == EVENT_LOB, the orderbook asks at this event is ob_asks[type_id].

 required
ob_mids ndarray

Array of mid prices. If event_type == EVENT_LOB, the orderbook mid at this event is ob_mids[type_id].

 required
features dict

Dictionary of computed features, with key as event_type. Feature scalar computed at this timestamp can be referenced using features[event_type][feature_name][type_id].

 required
running_event_ids dict

Dictionary of currently running event IDs with key-value event_type : event_id.

 required
running_type_ids dict

Dictionary of currently active type IDs with key-value event_type : type_id. For instance, at this event, the last-known trade/trade-features can be obtained with trade_buffer[running_type_ids[EVENT_TRADE]] / features[EVENT_TRADE][feature_name][running_type_ids[EVENT_TRADE]].

 required
**kwargs

Additional keyword arguments.

 {}

Returns:

Name Type Description
dict

A dictionary of estimated features for the event.

run_estimator()

Run through the events and collect estimators from self.event_estimator.

Returns:

Type Description

pd.DataFrame: A DataFrame containing the estimates for all events.

Simulator

A simulator for modeling hft events. Base class for the quantpylib.hft.alpha.Model, which is a statistical modeller for fair price estimation and other related estimators, as well as for the quantpylib.hft.alpha.Alpha, which is a backtest simulator. Simulator instances compute estimators (Model) and actions (Alpha) at events. Each event has an event type marked by an integer. EVENT_CLOCK:0, EVENT_LOB:1, EVENT_TRADE:2 are reserved since they are typical hft events for which one may decide to take action, such as in a clock-driven market-maker or event-driven market-maker. Simulation is performed in two-steps: data-preprocessing and data-processing on the fly. In the pre-processing stage, we may compute vectorized features that do not require event-states, and only require the loaded data. This makes it performance-efficient. For instance, orderbook features, trade features and clock-based features may be computed in compute_lob_features, compute_trade_features, compute_clock_features, each returning numpy arrays with scalar features. The second-part computes the estimators/actions chronologically, and may access the features computed, event states such as inventory, pnl and so on.

Attributes:

Name Type Description
ob_timestamps ndarray

Array of order book timestamps.
ob_bids ndarray

Array of best bid prices and sizes.
ob_asks ndarray

Array of best ask prices and sizes.
ob_mids ndarray

Array of mid prices.
trade_buffer ndarray

Array of trade events with timestamps, prices, sizes, and directions.
clock_interval float

The interval for the event clock in seconds.
custom_events dict

Dictionary of custom events with event IDs as keys and timestamps as values.
custom_data dict

Dictionary of additional data for custom events.

__init__(lob=None, trades=None, ob_timestamps=None, ob_bids=None, ob_asks=None, ob_mids=None, trade_buffer=None, clock_interval=1000000000.0, custom_events={}, custom_data={})

Initializes the Simulator with optional order book and trade data. One of lob or (ob_timestamps,ob_bids,ob_asks,ob_mids) are to provided. One of trades or trade_buffer is to be provided.

Parameters:

Name Type Description Default
lob `quantpylib.hft.lob.LOB`

Orderbook object with filled data buffers. Defaults to None.

 None
trades `quantpylib.hft.trades.Trades`

Trades object with filled trade data buffers. Defaults to None.

 None
ob_timestamps ndarray

Array of order book timestamps. Defaults to None. 1-dimensional.

 None
ob_bids ndarray

Array of best bid prices and sizes. Defaults to None. 3-dimensional (time, price, size)

 None
ob_asks ndarray

Array of best ask prices and sizes. Defaults to None. 3-dimensional (time, price, size)

 None
ob_mids ndarray

Array of mid prices. Defaults to None. 1-dimensional.

 None
trade_buffer ndarray

Array of trade events. Defaults to None.

 None
clock_interval float

Interval for the event clock in seconds. Defaults to 1e9 (no clock events).

 1000000000.0
custom_events dict

Dictionary of custom events with key as integer event id and an array of timestamps for that event. Defaults to {}.

 {}
custom_data dict

Dictionary of additional data for custom events. No enforced data schema. Defaults to {}.

 {}

Raises:

Type Description
ValueError

If reserved event IDs (0, 1, 2) are used in custom_events.

compute_clock_features(clock_timestamps)

Compute features based on clock events. Returned dictionary should be a key-value pair, where the key is feature-name and value is a 1-d np.ndarray of same dimensions as clock_timestamps. Features unavailable at particular indices should be given np.nan.

Parameters:

Name Type Description Default
clock_timestamps ndarray

Array of clock event timestamps.

 required

Returns:

Name Type Description
dict

Dictionary of computed clock features.

compute_custom_features(event_id, timestamps, custom_data)

Compute features for custom events. Returned dictionary should be a key-value pair, where the key is feature-name and value is a 1-d np.ndarray of same dimensions as timestamps. Features unavailable at particular indices should be given np.nan.

Parameters:

Name Type Description Default
event_id int

The ID of the custom event.

 required
timestamps ndarray

Array of custom event timestamps.

 required
custom_data dict

Additional data for custom events.

 required

Returns:

Name Type Description
dict

Dictionary of computed custom features.

compute_lob_features(lob_timestamps, lob_mids, lob_bids, lob_asks)

Compute features based on limit order book events. Returned dictionary should be a key-value pair, where the key is feature-name and value is a 1-d np.ndarray of same dimensions as lob_timestamps. Features unavailable at particular indices should be given np.nan.

Parameters:

Name Type Description Default
lob_timestamps ndarray

Array of order book timestamps.

 required
lob_mids ndarray

Array of mid prices.

 required
lob_bids ndarray

Array of best bid prices and sizes.

 required
lob_asks ndarray

Array of best ask prices and sizes.

 required

Returns:

Name Type Description
dict

Dictionary of computed limit order book features.

compute_trade_features(trade_buffer)

Compute features based on trade events. Returned dictionary should be a key-value pair, where the key is feature-name and value is a 1-d np.ndarray of same length as trade_buffer. Features unavailable at particular indices should be given np.nan.

Parameters:

Name Type Description Default
trade_buffer ndarray

Array of trade events with timestamps, prices, sizes, and directions.

 required

Returns:

Name Type Description
dict

Dictionary of computed trade features.

df_prices(plot=False, ax=None)

Generate a DataFrame of bid, ask, and mid prices, with optional plotting.

Parameters:

Name Type Description Default
plot bool

If True, plots the price data. Defaults to False.

 False
ax Axes

Matplotlib axis object for plotting. Defaults to None.

 None

Returns:

Type Description

pd.DataFrame: DataFrame with columns for bid, ask, and mid prices indexed by timestamp.