Energy · Futures · Risk decomposition
ICE energy futures contract decomposition
Every ICE energy contract — outright, strip, calendar spread, CSO, bullet option, basis, or refining crack — decomposed in your browser into dated factor legs with per-leg ICE codes. 108 atomic risk factors, 107 contracts, a Python reference engine and a JavaScript browser engine that match cell-for-cell.
Drive it below — hit "Load sample" for a mixed portfolio (NG basis, TTF Cal strip, Brent cal spread, German peak, NBP, coal, a TTF option, a 3:2:1 crack), or paste your own CSV. Full detail on what the dashboard does, what's under the hood, and its limitations is below the dashboard.
The thesis
Energy portfolios live or die by how positions are decomposed.
A calendar spread isn't one exposure — it's a pair of dated legs whose basis can dominate the P&L. A power Cal-strip doesn't scale evenly across months because peak-hour counts differ. A 3:2:1 crack's constituents move on different ICE codes. If your risk system papers over any of that, every downstream report carries an invisible error.
This project is what happens when you take that observation seriously: a decomposition library — ice_energy_decomp — that expands every contract type into dated factor legs with per-leg ICE codes, and a browser dashboard whose calculation engine is checked cell-for-cell against the Python reference. The point isn't the dashboard itself. The point is that the decomposition is what every downstream calculation (margin, P&L, scenario, value-at-risk) needs to start from.
The features, illustrated
What the dashboard does — view by view.
Feature index
Click a feature to jump
Overview — your book in one frame
A KPI strip (positions, unique factors, tenor span, gross exposure, mark-to-market), the net factor exposure list ranked by abs(qty) with left/right bars, and a sector breakdown donut. Compare a second portfolio side-by-side from the switcher.
Sector donut tells you instantly whether your gross is concentrated in one sector or spread across the complex — the single most underrated risk visualization for a multi-commodity book.
Positions — what's actually in the book
Sortable table of every parsed position with trade ID, contract code, direction (L/S), lots, tenor, structure, and metadata. The structure column now auto-detects basis swaps, cracks, options, and other multi-leg contract types rather than just labeling everything 'OUTRIGHT'.
Every basis swap shows BASIS, every crack shows CRACK, every option shows OPTION — at a glance you know which positions decompose into multiple factor legs vs. which are flat exposures.
Cross-Commodity — heat-rate pairs + leg provenance
The engine looks at your portfolio and identifies implicit gas-to-power heat-rate exposures using a delivery-point lookup table (Algonquin→ISONE, Transco Z6 NY→NYISO J, TETCO M3→NYC, etc.). Each pair shows gas qty (MMBtu), power qty (MWh), implied heat rate vs. the 7.5 reference, spark-spread interpretation, and the residual after HR matching. Below the pairs: every basis swap, crack, and calendar spread broken into its constituent factor legs.
Drop a long Algonquin basis + long ISONE Mass Peak into the book and the engine tells you it's an aligned long at 7.5 HR — no manual matching, no spreadsheet. Same delivery geography a desk would reason through, automated.
Risk — named macro scenarios
Pre-configured deterministic shocks for the scenarios that actually matter in energy markets — Strait of Hormuz disruption, US cold snap, EU storage build, OPEC+ cut, heat dome, refinery outage, hydro drought, EUA squeeze, demand shock. Each scenario applies factor-level shocks and returns scenario P&L plus a factor-by-factor contribution breakdown. Edit the shocks to run custom what-ifs.
Pick Hormuz, see exactly which factors are driving the +$874K scenario P&L and what shock magnitude each carries — instantly. The shock vectors are editable, so it's also the simplest way to roll your own scenario without building a spreadsheet.
P&L Overlay — marks in, attribution out
Paste factor,price rows in the marks box or load the bundled market snapshot. The dashboard applies the marks to the net factor exposure and returns mark-to-market by factor plus a total. Switch options between delta and full-notional to see how option exposure rolls through. A snapshot loader pulls in a public-source EOD reference set with the as-of date displayed.
The same factor decomposition that drives the Overview and Risk tabs also drives this — paste marks once and the P&L attribution is consistent end-to-end across every view in the dashboard.
Hub Map — the geography behind the numbers
Three hierarchies, switchable from the sidebar: a natural gas hub tree (Henry Hub and the basis points around it — Transco, TETCO, Algonquin, Chicago, Waha; TTF/NBP/THE/PEG/PSV/ZTP for Europe); a crude → refined → petrochemical value chain showing WTI/Brent/LLS/Mars/WCS feeding USGC refining yields and downstream petchem; and a power ISO map (PJM, MISO, ERCOT, CAISO, NYISO, ISONE) with spark-spread relationships showing each ISO's typical heat rate and primary gas input.
The crude value chain is the cleanest single view of how a refining margin actually works — from input grade through 65% USGC yield to which petrochemical streams come off each cut.
Contract Reference — every contract, every leg
Faceted browser for all 107 contracts. Filter by sector or by type (future, basis swap, swap, option, crack, CSO, spread), search by key or ticker or description, and click any contract to see its full decomposition — every leg with coefficient, factor code, factor description, unit, and ICE product code where verified.
Click any basis swap and see its two legs explicitly (e.g., TETCO M3 BASIS = +NG.FUT.TETCO_M3, −NG.FUT.HH) — the same decomposition the engine applies when you put the position in your portfolio.
Under the hood
Architecture and verification.
The engine and its browser counterpart share their interface: 108 factors, 107 contracts, eight contract structures (OUTRIGHT, STRIP, CAL_SPREAD, OPTION, CSO, plus basis, cracks, and spreads). Each contract maps to a weighted sum of factors; positions expand through the structure handler into dated monthly legs scaled by the contract's unit conventions.
- Power MW→MWh. A NERC- and EU-aware calendar counts on-peak / off-peak / base hours per delivery month — verified against independent sources (PJM peak July'26 = 368h, Christmas-Friday correctly drops a peak day, peak + off-peak ties to total).
- Options. Black-76 delta for bullet options on positive forwards;
delta_overridefor non-standard structures including CSOs. - Strips and spreads. Calendar strips (
CAL27,2026Q3,WIN26, custom ranges) expand to monthly legs; calendar spreads net the front and back tenors. - Cracks. 3:2:1, 5:3:2, and other refining cracks decompose into their crude / gasoline / distillate constituents with industry-standard ratios.
Parity testing. The Python reference engine and the JavaScript browser engine are checked cell-for-cell — 32/32 (factor, month) cells match exactly on the full reference portfolio. Phase 1 tests: 24/24. Phase 2 tests: 23/23. The dashboard is not a separate, drift-prone reimplementation; it shares the same logic that's checked against the source.
Limitations & caveats
What this dashboard is not — read before drawing conclusions.
This is a research and education tool. It is not investment advice, not a trading system, and not a settlement-grade risk system. Concretely:
- The seed portfolios are illustrative, not real positions. They exist to demonstrate the decomposition and to give you something to drive the UI with on first load.
- $-PnL requires user-provided marks. There is no live ICE/EEX/NYMEX price feed wired in — pasted marks are the source of truth for any P&L number you see.
- Some ICE product codes are flagged unverified. In the Contract Reference tab, a small number of contracts show an UNVERIFIED chip — those are best-effort mappings I've been unable to confirm against ICE's product master. Treat the verified-flagged codes as load-bearing; treat the unverified ones as placeholders.
- Black-76 assumes positive forwards. Calendar spread options (CSO) and basis options where the underlying can go negative require a normal/Bachelier model — currently those positions use
delta_overrideas a workaround. Don't rely on the Black-76 delta for those structures. - Power calendars cover US (5×16) and EU (5×12 peak / 7×24 base) conventions. Other regional conventions (UK 7-day with bank-holiday handling, Nordic, Iberia variants) need explicit configuration.
- Crack ratios use industry-standard conversion factors. 3:2:1, 5:3:2, etc. follow USGC convention. Verify against your firm's spec before applying to a real book.
- Persistence is browser-local only. Portfolios and preferences are saved in
localStorage— no cloud sync, no server backup. Clearing site data deletes your portfolios. Don't use this as a system of record. - Scenario shocks are deterministic factor moves, not Monte-Carlo. The Risk panel applies named factor-level shocks and reports the linear P&L impact; it doesn't propagate correlated tails or run distributional VaR.
- Margin and clearing logic is out of scope. The dashboard returns exposures and P&L; it does not compute SPAN, VaR-based margin, or ICE's actual margin algorithm. Don't use these outputs to anticipate margin calls.
On deck
What's next.
The roadmap that keeps this useful as it grows:
- Live market data integration. Replace the snapshot/mark-input flow with a feed-driven mark layer. The integration shape is already in place — the previous version shipped a CSV-based snapshot loader; this just plugs in real data when there's a feed contract.
- Verified ICE product codes. Close the gap on the unverified-flag set against ICE's product master.
- Normal-model option pricing. Replace the Black-76 /
delta_overrideworkaround with a proper Bachelier model for CSOs and basis options. - Server-side persistence (optional). A save-portfolio endpoint with auth, so portfolios survive a browser clear and can be shared across devices.
- Additional regional conventions. UK power with bank-holiday handling, Nordic system price, Iberia, Japan JEPX.
- Export. One-click PDF / Excel of any tab's state so analyses can be circulated outside the browser.
Artifacts & downloads
- Dashboard Feature Guide (PDF — 10 pp, dark theme, illustrated)
- ICE reference table (CSV)
- ICE reference table (MD)
- Full project (zip — Python engine, specs, tests)
Daniel Kaufman · Kinetic Alpha. Code and methodology are shared for research and education. No warranty is made as to fitness for any particular use; not investment advice; not a trading system. Contact for collaboration: dkaufmanrisk@gmail.com.