quantlab.runs.backtest_stats.turnover

quantlab.runs.backtest_stats.turnover(orders, value, init_cash, *, settlements=())

Return the turnover of every bar that had rebalance fills, on a timestamp axis.

Turnover is the one-sided traded notional of the bar (the sum of |size| x price over its orders) divided by the portfolio value of the previous bar, or init_cash for the first bar of the window. One sided means a full buy-in from cash is about 1 and replacing the whole book (sell then buy) about 2. Using the value before the fills keeps the bar’s own profit or loss out of the ratio. A fill that settles a delisted holding is no rebalance’s trade: an order at a settlement’s bar and symbol is left out.

Parameters:

ordersxarray.Dataset

One fill per entry of an order dimension, with the variables timestamp, size (signed or not) and price, and symbol when settlements are given; a dataset without an order dimension means no fills.

valuexarray.DataArray

Portfolio value after each bar, on a timestamp axis that holds every order’s bar.

init_cashfloat

Value before the first bar.

settlementssequence of dict, optional

The delisting settlements among the orders, each with its settlement_timestamp and axis_symbol (the order’s symbol), as SimulationResult.settlements records them.

Returns:

xarray.DataArray

One entry per bar with rebalance fills; empty when there are none.

Raises:

ValueError

If an order timestamp is not on the value axis.

Examples

>>> bars = pd.bdate_range("2024-01-01", periods=3)
>>> value = xr.DataArray([1000.0, 1100.0, 1100.0], dims="timestamp", coords={"timestamp": bars})
>>> orders = xr.Dataset({
...     "timestamp": ("order", bars[[1, 2, 2]].values),
...     "symbol": ("order", ["AAA", "AAA", "BBB"]),
...     "size": ("order", [100.0, -50.0, 40.0]),
...     "price": ("order", [10.0, 11.0, 11.0]),
... })
>>> turnover(orders, value, init_cash=1000.0).values.tolist()
[1.0, 0.9]
>>> settled = [{"settlement_timestamp": bars[2], "axis_symbol": "BBB"}]
>>> turnover(orders, value, init_cash=1000.0, settlements=settled).values.tolist()
[1.0, 0.5]