Reading Trade, Cash-Flow, and Option Lifecycle Backtest Exports
Summary
The document explains what strategy trade exports contain and how to use them when reviewing a backtest. HTML and tabular files report order timing and prices, the traded asset, cash balances, raw portfolio value, and a cash-adjusted equity series intended to support performance review when account cash flows occur. The CSV and Parquet event stream also records deposits, withdrawals, interest, and fees, with fields that identify the event type, amount, direction, reason, and whether it is an external flow. The HTML view marks these events alongside fills.
For options backtests, exports distinguish cash settlement, assignment, exercise, and expiration. When physical settlement delivers the underlying, the delivery is represented as a separate trade event linked to the lifecycle outcome. These fields help analysts distinguish ordinary fills from cash movements and expiration mechanics. The documentation describes the available reporting structure; it provides no strategy results or guidance on interpreting performance beyond the listed measures. Analysts still need to account for their own assumptions about cash flows, option settlement, and portfolio valuation when comparing results.
Key ideas
- Trade exports include order details, cash, raw portfolio value, and a cash-adjusted portfolio series.
- Cash-flow events appear in the same event stream as trades and are marked in the HTML report.
- Options backtests label settlement, assignment, exercise, and expiration outcomes explicitly.
- Physical option settlement can create a separate underlying delivery event linked to the lifecycle status.
- The document describes reporting fields but does not provide performance evidence or an interpretation method.
Tags
Full text
# backtesting.trades files .. _backtesting.trades_files: Trades Files ============ .. meta:: :description: The Trades HTML and Trades CSV files provide detailed information about each trade executed by the strategy. This includes: LumiBot documentation. The **Trades HTML** and **Trades CSV** files provide detailed information about each trade executed by the strategy. This includes: - **Buy and Sell Orders:** The times and prices at which buy or sell orders were placed, along with the asset involved (e.g., option strike price or stock ticker). - **Cash-Adjusted Portfolio Value:** The primary strategy-equity line used for cashflow-correct performance review. - **Portfolio Value:** The raw account value at each time point. - **Cash:** The amount of cash available at each time point. Cash Events ----------- `trades.csv` / `trades.parquet` now also contain non-trade cash-impacting events in the same event stream. - Trade rows use ``event_kind=trade``. - Cash rows use ``event_kind=cash_event``. - Cash rows can include: - ``cash_event_type`` (for example ``deposit``, ``withdrawal``, ``interest``, ``fee``) - ``cash_event_amount`` - ``cash_event_reason`` - ``cash_event_direction`` - ``is_external_cash_flow`` `trades.html` renders these cash rows as chart markers so deposits, withdrawals, and financing events are visible in the same review artifact as trade fills. See also: :doc:`cash_accounting` When ``benchmark_asset=None``, the trade CSV is still exported. Without a benchmark comparison plot it uses the full trade-event format, including ``status=fill`` rows. Disabling a benchmark must not remove execution evidence. Option Lifecycle Statuses ------------------------- For options backtests, expiration outcomes are exported as explicit lifecycle events in the trade artifacts. - ``cash_settled``: cash settlement at intrinsic value (used for cash-settled products, such as index options). - ``assigned``: short in-the-money physically-settled option assignment at expiration. - ``exercised``: long in-the-money physically-settled option exercise at expiration. - ``expired``: out-of-the-money expiration (or long ITM contracts that cannot be exercised due to account constraints in simulation). When physical settlement occurs, LumiBot also writes the underlying delivery row as a separate trade event (``status=fill``) with ``type`` set to the originating lifecycle event (for example, ``type=assigned`` or ``type=exercised``). This allows downstream charting/reporting systems to distinguish ordinary trades from assignment/exercise delivery. .. figure:: _html/images/trades_example.png :alt: Trades example :width: 600px :align: center
Shown in full with attribution under the source's licence. Licence: GPL-3.0
This summary was written by Stratmill's research agent from the original; it is not a copy of the source.