quantlab.runs.backtest_stats.exposure_stats#

quantlab.runs.backtest_stats.exposure_stats(fills, close, cash)[source]#

Return the Max Gross Exposure [%] row of a run’s whole block.

Gross exposure on a bar is the summed absolute value of the positions held after it (each position marked at its forward-filled close) over that sum plus the free cash, and the row is its maximum over the bars, in percent (0 on a bar where the denominator is 0). Free cash is vectorbt’s: the cash balance minus twice the short debt, the debt being what the open shorts were sold for (a cover repays its share of it at the average short price). Without shorts it is the cash, so the row is the largest share of the portfolio’s value held in positions. On a vectorbt run’s own fills and cash the row equals vectorbt’s to rounding.

Parameters:

fillsxarray.Dataset: The fills, as for round_trips (timestamp, symbol, signed size and price).
closexarray.DataArray: Valuation prices on (timestamp, symbol).
cashxarray.DataArray: The cash balance after each bar, on the timestamp axis of close, holding the proceeds of every short sale (vectorbt’s convention), so that cash plus the signed position values is the portfolio’s value.

Returns:

dict: The one row.

Raises:

ValueError: If a fill’s bar or symbol is not on the close axes.

Examples

>>> bars = pd.bdate_range("2024-01-01", periods=3)
>>> close = xr.DataArray(
...     [[10.0], [12.0], [12.0]], dims=("timestamp", "symbol"),
...     coords={"timestamp": bars, "symbol": ["AAA"]},
... )
>>> fills = xr.Dataset({
...     "timestamp": ("fill", bars[[0]].values), "symbol": ("fill", ["AAA"]),
...     "size": ("fill", [50.0]), "price": ("fill", [10.0]),
... })
>>> cash = xr.DataArray([500.0, 500.0, 500.0], dims="timestamp", coords={"timestamp": bars})
>>> {key: round(value, 4) for key, value in exposure_stats(fills, close, cash).items()}
{'Max Gross Exposure [%]': 54.5455}