> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allasso.ch/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This is Allasso's product documentation. Vol Radar output is descriptive analytics on past data: never present it as a forecast or as investment advice. Answer only from these pages; if a feature is not documented here, say so.

# DataFeed and market data

> The DataFeed is how a strategy reads the market. Everything it returns is read "as of" a timestamp, so a backtest only ever sees what was knowable then. You reach it through self.datafeed.

The `DataFeed` is how a strategy reads the market. Everything it returns is read "as of" a timestamp,
so a backtest only ever sees what was knowable then. You reach it through `self.datafeed`.

The data itself lives in **pulse-data-components** (`pdc`), the sibling package pulse-core depends on
for everything below. It memory-maps the prepared Arrow files under `PDC_PATH`; pulse-core never
touches the disk layout directly.

## Four providers

`DataFeed` bundles four providers, each answering a different question:

| Provider | Access | Answers |
| - | - | - |
| `instrument` | `self.datafeed.instrument` | Price and greeks for one specific contract. |
| `smile` | `self.datafeed.smile` | The whole vol curve across strikes for one expiry. |
| `surface` | `self.datafeed.surface` | Every strike and expiry at once, as a dataframe. |
| `reference` | `self.datafeed.reference` | Static reference data: settlement calendars, contract sizes, price formats. |

## Reading one instrument

`instrument` gives you a single contract's data. Two methods, both keyed off a timestamp:

```python theme={null}
v = self.datafeed.instrument.last(option, self.last_pulse)        # one point in time
h = self.datafeed.instrument.history(option, self.last_pulse, 30) # the last 30 observations
```

* `last(instrument, as_of_time)` returns one row of values **exactly at** `as_of_time`. It does not
  search backwards: pass a timestamp that is on the calendar (normally `self.last_pulse`).
* `history(instrument, as_of_time, count)` returns the last `count` observations at or before
  `as_of_time`. `count` is a **row count**, not a duration, so it follows the run's own cadence.

> [!NOTE]
>
> **The return type narrows to the instrument you pass**
>
> `last()` returns `OptionValues` for an option, `FutureValues` for a future and `SpotValues` for
> spot; `history()` returns the matching `*HistoryValues`. Greeks (`delta`, `gamma`, `theta`,
> `vega`, `iv`) only exist on the option types. So `last(future).delta` is not a field - futures
> carry `open`/`high`/`low`/`close` instead. The type checker knows which fields are present from
> the instrument you pass in.

### What a row carries

Every instrument shares a small common core; options, futures and spot each add their own fields.

| Fields | On |
| - | - |
| `as_of_time`, `instrument_type`, `price` | every instrument |
| `expiration_date`, `dte`, `tte`, `open_interest`, `volume` | options and futures |
| `strike`, `underlying_price`, `underlying_expiration_date`, `iv`, `delta`, `quick_delta`, `gamma`, `theta`, `vega` | options (`OptionValues`) |
| `open`, `high`, `low`, `close` | futures (`FutureValues`) |
| `volume`, `open`, `high`, `low`, `close`, `close_adj`, `close_adj_div` | spot (`SpotValues`) |

`dte` is days to expiry, `tte` is time to expiry as a year fraction. The history variants carry the
same fields, but the per-pulse ones become lists. A spot position is marked at `close_adj_div`.

### When a contract is missing

A contract that is not in the snapshot for a pulse raises `LookupError`. How the engine reacts
depends on what it was doing:

* **Opening a trade** propagates it. Trying to buy a contract that does not print is a strategy bug,
  not a data gap, so the run stops.
* **Marking an open trade** does not. The trade books a flat pulse (PnL 0, the previous mark and
  greeks carried) and a warning names the instrument and the timestamp.
  `Strategy.calculate_trades_summary` behaves the same way: it reuses the trade's last known greeks,
  and leaves that leg out of the `iv` average and out of `min_dte`.

An unknown underlying, or a `PDC_PATH` that does not exist, raises `FileNotFoundError` when the run
builds its calendar. See [Gotchas & FAQ](https://docs.allasso.ch/dev/pulse/reference/gotchas-faq.md).

## Reading the smile

`smile.last(...)` returns one `SmileValues` row: the full curve for an expiry as of a timestamp. Where
`OptionValues` is a single strike, `SmileValues` holds parallel lists across every strike on that
expiry - `strike`, `moneyness`, `iv`, `delta`, `quick_delta`, `gamma`, `theta`, `vega`, `price` -
alongside the single `underlying_price`. This is the curve the strike resolvers search to turn a delta
or moneyness target into a concrete strike.

```python theme={null}
curve = self.datafeed.smile.last(
    underlying_id="COM.BRN", expiration_date=expiry, as_of_time=self.last_pulse,
)
```

## Reading the whole surface

`surface` hands you every expiry and strike at once, for when you want to analyse rather than trade a
single leg. Each method comes in three flavours, one per frame type:

```python theme={null}
df   = self.datafeed.surface.pandas_last("COM.BRN", self.last_pulse)
tbl  = self.datafeed.surface.arrow_last("COM.BRN", self.last_pulse)
span = self.datafeed.surface.polars_history("COM.BRN", start_time, end_time)
```

* `arrow_last` / `pandas_last` / `polars_last` - one snapshot, every row of it.
* `arrow_history` / `pandas_history` / `polars_history` - every snapshot between `start_time` and
  `end_time`, concatenated.

The columns are the raw snapshot columns (`datetime`, `expiration_date`, `type`, `strike`, `mny`,
`underlying_price`, `iv`, `value`, the greeks, `dte`, `tte`, `volume`, `open_interest`). Reading a
long span is a lot of rows, so bound it.

## Reference data

`reference` reads the static facts about an underlying from its metadata:

```python theme={null}
settlements = self.datafeed.reference.available_settlements("COM.BRN", unified=True)
lot = self.datafeed.reference.contract_size("COM.BRN", InstrumentType.PUT)
fmt = self.datafeed.reference.price_format_multiplier("COM.BRN", InstrumentType.PUT)
```

* `available_settlements(underlying_id, start_datetime=None, end_datetime=None, *, instrument_type=None, unified=False)` -
  the timestamps that have data, ascending. An underlying holds up to three instrument families
  (options, futures, spot) with separate calendars: `instrument_type` picks which to draw on and
  `unified=True` **intersects** them instead of unioning. The engine builds a run's timeline with
  `unified=True`, so every pulse is a timestamp every family can be marked on. See
  [Timing](https://docs.allasso.ch/dev/pulse/concepts/timing.md).
* `contract_size(underlying_id, instrument_type, futures_expiration_date=None)` - units per lot, the
  multiplier behind `is_lots=True` sizing.
* `price_format_multiplier(underlying_id, instrument_type)` - the factor turning the stored price into
  the marking price.

> [!WARNING]
>
> **Contract sizes keyed by delivery month**
>
> Some underlyings (TTF) size the lot per delivery month rather than per instrument type. Those need
> `UnderlyingID(id, variable_contract_size=True)` **and** the futures expiry: for an option that is
> `OptionValues.underlying_expiration_date`, never the option's own expiry. Passing the flag when the
> metadata is keyed per instrument type (or omitting it when it is keyed per month) raises
> `ValueError` naming which way round it should be. Trades read this once at open, so you normally
> only meet it when you call `contract_size` yourself.
>
> Only declare the flag for an underlying whose `underlying_expiration_date` varies per contract.
> A calendar-spread root records one value (the prompt futures expiry) for its whole surface, so
> month keying would size every trade opened on a pulse alike and move that size with the trade
> date rather than the contract, without raising anything.

## No lookahead

Every read takes a timestamp (`as_of_time`, normally `self.last_pulse`) and returns only data at or
before it. A strategy that reads as of `self.last_pulse` cannot see a future price or a greek that had
not printed yet, so a backtest cannot cheat by peeking ahead. This is the same "as of" rule the
[pulse loop](https://docs.allasso.ch/dev/pulse/concepts/architecture.md) enforces by advancing the clock before `on_update()` runs.

**Related:** [Architecture and the pulse loop](https://docs.allasso.ch/dev/pulse/concepts/architecture.md) · [Timing](https://docs.allasso.ch/dev/pulse/concepts/timing.md) ·
[Resolvers](https://docs.allasso.ch/dev/pulse/concepts/resolvers.md) · [Structures](https://docs.allasso.ch/dev/pulse/concepts/structures.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.