Temporal Fusion Transformer

A Temporal Fusion Transformer (TFT) is a neural network architecture for multi-horizon time-series forecasting. It handles many related series, many covariates, inputs that are known ahead of time like calendars or prices, and static metadata like a store or a ticker. It also shows which inputs mattered.

Its output is usually a set of quantile forecasts such as p10, p50 and p90. Pelican uses a sequence TFT to rescore option-spread candidates from market, options, calendar, and news state.

Summary

TFT is a supervised deep-learning model that takes a lookback window and produces forecasts for several future horizons. It separates its inputs into three kinds: static features, time-varying features observed in the past, and time-varying features known for the future. Each kind enters the model through its own path.

The model then selects which inputs matter, models short-term sequence behavior with LSTMs, uses attention to pick the important past time points, and outputs a forecast with its uncertainty.

The architecture was introduced in "Temporal Fusion Transformers for Interpretable Multi-horizon Time Series Forecasting" by Lim et al. It combines covariate-aware forecasting, recurrent sequence modeling, temporal attention, static conditioning, feature selection, gating, residual learning, and quantile loss.

Architecture Diagram

This diagram shows the data flow. The exact tensor shapes vary by implementation. Static metadata conditions the network. Past and future covariates pass through variable selection. LSTMs encode local sequence behavior, attention decides which encoded time points matter for each forecast horizon, and the output head emits quantiles.

Temporal Fusion Transformer architecture A block diagram showing static inputs, past observed inputs, future known inputs, variable selection, static enrichment, recurrent encoders, gated residual networks, interpretable attention, and quantile forecast heads. Temporal Fusion Transformer data flow Solid arrows are main data flow. Dashed arrows are conditioning and gating paths from static context. Static inputs entity id, sector, geography store type, ticker metadata Past observed inputs target history y[t-k:t] observed covariates lagged signals, realized state Future known inputs calendar, price plan events, scheduled actions forecast horizon markers Static covariate encoder creates context vectors for selection, LSTM state, enrichment, and gating Past variable selection network per-time-step feature weights choose useful historical inputs Future variable selection network weights known future features for each forecast horizon LSTM encoder reads selected past sequence captures local order, recency, short-run dynamics LSTM decoder rolls through future-known covariates for horizons t+1 ... t+H GRN + gates skip, suppress, refine nonlinear transforms Static enrichment injects entity context into each temporal representation before attention Interpretable multi-head attention which historical time points matter for each horizon? Quantile heads p10, p50, p90 forecasts for every horizon Forecast distribution y_hat[t+1:t+H, q] static context conditions feature weights static context initializes and gates sequence path attention weights are inspectable across time
Inputs Variable selection Sequential modeling Attention Forecast output

How We Use It in Pelican

In Pelican, the TFT is a sequence model inside a defined-risk options decision system. The active production family is tft_classical_sequence_v1. It rescores option-spread candidates after the system has built current market features, generated candidate spreads, and checked each candidate's quote and structure.

The forecast is made for each candidate. A row is one ticker at one timestamp with one bull-put or bear-call structure, its expiry, strikes, width, quote, liquidity, and history. That makes the forecast usable for ranking and sizing trades.

1. Snapshot Market state arrives

Price, option chains, volume, open interest, implied distributions, calendar state, and news-derived state.

2. Sequence 28 observed steps

The encoder sees a recent sequence of market snapshots, including freshness and missingness signals.

3. Candidate Spread is specified

Structure, expiry, strikes, width, credit, Greeks, moneyness, bid-ask, quote age, OI, and volume.

4. Forecast TFT + GBM distribution

The TFT forecast is blended with a GBM quantile ensemble through a calibrated CDF mixture.

5. Decision Edge after costs

The distribution becomes candidate EV, tail risk, p20 sizing edge, a rank, and the reasons shown when there is no trade.

The model does not approve trades. Its forecast goes into a decision path with candidate generation, calibrated distribution pricing, liquidity checks, duplicate checks, risk limits, and execution gates. When no candidate is eligible, the operator sees the reasons.

The Training Data

The training store has a sequence side, a candidate side, and a label: the underlying return to the candidate's expiry-aligned close. The no-leakage proof for the current store passes.

3,105encoder sequences
86,605sequence time steps
4,969candidate rows and training rows
28observed steps per encoder sequence

Sequence features

The encoder sees market and options state over time: implied-distribution percentiles, IV rank, put-call ratios, open-interest and volume structure, spread quality, realized-volatility context, cross-sectional ranks, macro-calendar distances, day-of-week features, earnings flags, freshness indicators, missingness indicators, and a 64-dimensional news state.

Candidate features

Each candidate row describes the spread being considered: bull put or bear call, expiration, candidate DTE, short and long strikes, width, bid/mid/ask credit, bid-ask width, leg Greeks, IV, moneyness, distance to strikes, leg open interest, leg volume, quote age, and guard/funnel metadata.

Labels

The target is label_return: the underlying return from the decision snapshot to the candidate's expiry-aligned close. The spread candidate supplies the horizon, structure, strikes, width, and quote context used to turn a return distribution into a payoff.

Leakage control

Features are split into what is observed at decision time and what is known by contract, and the candidate store carries a no-leakage proof. A feature that is not available on the live path should not be used in training.

The Features We Use

The inputs are the same facts the live decision uses: what the option surface looked like, which spread was executable, how fresh the data was, which events were nearby, and whether the sequence had gaps. Training and inference use the same feature names.

Feature family Concrete examples Why it matters
Option surface and chain state atm_iv, atm_iv_xrank, chain_impl_ret_p10, chain_impl_ret_p50, chain_impl_width, chain_pc_oi_ratio, chain_total_oi, chain_median_spread_pct Shows what the options market is implying about distribution shape, liquidity, crowding, and transaction quality.
Candidate contract structure, candidate_dte, short_strike, long_strike, width, entry_credit_mid, spread_bid_ask_width, net_delta, short_leg_oi, long_leg_volume Makes the forecast about one executable bull-put or bear-call spread.
Event and calendar state days_to_earnings, days_to_fomc, days_to_cpi, days_to_nfp, days_to_monthly_opex, dow_sin Lets the model separate ordinary drift from known event-risk windows and recurring market-calendar effects.
News and text state news_state_00 through news_state_63, plus news-state freshness fields. Condenses recent text context into stable numeric state without letting the model read future news.
Freshness and missingness row_observed_mask, feature_observed_mask, feature_age_minutes, source_age_minutes, option_surface_age_minutes, candidate_quote_age_seconds Keeps stale or missing data from looking like a confident number.

An AAPL example sequence

One historical AAPL training example used a full 28-step encoder ending near the 2026-02-11 close. The sequence covered snapshots from 2026-02-05 20:30 UTC through 2026-02-11 20:30 UTC, with no missing steps. The table below shows how a few real inputs changed from the first to the last observed step.

Feature First observed step Last observed step Interpretation
atm_iv 0.2948 0.2477 At-the-money implied volatility compressed across the lookback window.
chain_impl_ret_p10 -2.09% -3.36% The option-implied lower-return tail became more negative.
chain_pc_oi_ratio 0.458 0.619 Put-call open-interest balance moved toward more put weight.
chain_total_oi 551,792 212,969 Total open interest fell, so liquidity changed.
chain_median_spread_pct 4.19% 6.03% The chain became more expensive to trade on median spread quality.
news_state_00 0.286 0.180 The news state changed.

The Predictions

The output is a forecast distribution of the underlying return over the candidate's horizon, given the sequence and the spread candidate. Pelican maps that distribution through the spread payoff and asks four questions. What is the median payoff? How bad is the lower tail? Is the expected value still positive after spread cost, slippage, and execution penalties? Is the edge robust enough across model seeds to size the trade?

Prediction surface What it means How the decision path uses it
Candidate quantiles A calibrated underlying-return distribution conditioned on a specific spread candidate. Prices the spread's post-cost EV and tail risk instead of ranking on raw heuristics.
GBM/TFT blend A CDF mixture of a tree ensemble and the sequence TFT. Combines the tree model on tabular features with the TFT on the sequence.
Seed/member robustness Model-member disagreement and lower-tail edge estimates. Feeds p20-style sizing, so position size uses a robust edge as well as the mean edge.
Gate-visible reasons Why a candidate did or did not survive model, quote, liquidity, risk, duplicate, and timing gates. Shows the operator why there was no trade.

The TFT is one part of the ranking. The decision also depends on fresh quotes, liquidity, strike validity, expiry lane, portfolio exposure, replacement logic, and realized fills and slippage.

Labels and an AAPL Example

The label is label_return = (expiry-aligned close - snapshot close) / snapshot close. It is the return of the underlying, and it is separate from the P&L of the option spread. The model first learns a calibrated distribution of the price return. The spread payoff, quote, cost, and execution gates are applied after that.

Historical label example

AAPL, 2026-02-11 21:00 UTC snapshot, 2026-03-13 expiry, bear_call, 280/285 strikes, 5-point width. The stored label_return is -9.42%. For that structure a move down in the underlying is favorable, but the label is still the underlying move. The payoff is computed after the distribution is mapped through the spread.

Its sequence

The same row links to encoder sequence seq-c9ea29edf44ea084ca9e: 28 observed steps, full coverage, ending at 2026-02-11 20:30 UTC. The candidate row carries the 30-DTE contract, strikes, width, credit, moneyness, quote age, and funnel metadata.

An AAPL bull put decision

A production decision from 2026-05-14 15:03 ET scored an AAPL bull_put candidate: short 290, long 285, expiring 2026-06-05, with AAPL at 298.52. The executable credit was 0.92 on a 5-point-wide spread, so the max profit was 0.92 and the max loss was 4.08.

Decision field Value Meaning
Horizon 22 DTE The model scored the return distribution to the spread's expiry horizon.
Encoder quality 28 observed steps, sequence score pass The sequence TFT had the expected recent market context available.
Blended fair credit 0.64 vs market credit 0.92 The model's fair value was below the market credit. That difference is the edge.
Profit probability 85.8% The payoff map estimated high probability of finishing above breakeven.
Payoff distribution p05 -4.08, p50 0.92, p95 0.92 The trade is defined-risk: lower tail loses the spread max loss; upper outcomes cap at the credit.
Ranking edge 6.87% Positive model edge before the execution and sizing checks.
Post-cost EV 0.188 per contract after execution penalty The candidate still had positive expected value after the learned execution penalty.
Robust sizing edge -15.74% p20 seed edge The lower seed/member view was not robust enough to size aggressively.
Final gate Dropped: width 1.67% of spot < 2.00% minimum The system did not submit it, because the spread was narrower than the minimum-width gate allows.

In this example the TFT helped estimate the distribution. The trading system priced the spread, checked robustness, charged execution cost, applied the width, liquidity and risk rules, and recorded why it did not trade.

The Architecture Pieces

Each module of the TFT has one job. The table lists them and how Pelican uses each.

Module Role Pelican interpretation
Typed inputs Separate static, past-observed, and future-known covariates. Keep live-available market state separate from label-only future outcomes.
Variable selection Learn which features matter for this entity, time, and horizon. Let option-surface, news, calendar, and quote features matter differently by ticker and regime.
Static context Condition the whole network on entity identity. Let AAPL, SPY, NVDA, and IWM share structure while their signals can differ.
LSTM path Model local sequence order, recency, and short-run dynamics. Read the 28-step market sequence before scoring the current spread candidate.
Gated residual networks Apply nonlinear transforms only when they help. Reduce brittleness when some feature blocks are stale, noisy, or low-signal.
Attention Retrieve the historical time steps most relevant to the forecast horizon. Show which recent market windows influenced the score.
Quantile heads Train with pinball loss to produce calibrated lower, median, and upper outcomes. Turn one forecast into fair value, lower-tail payoff, profit probability, and seed-robust sizing inputs.