Commodities and energy / Methodology
Commodities and Energy methodology
How the /commodities module is built: what it holds, where every number comes
from, the two anchors verified verbatim against EIA, the units, and every
limitation. It is the price-and-fundamentals view of US energy; the futures
positioning on the same commodities lives on positioning.
Source
Everything on the page is the U.S. Energy Information Administration (EIA),
pulled from the EIA Open Data API v2 (the seriesid compatibility route). EIA
is a US federal statistical agency; its data are US-government works in the
public domain under 17 U.S.C. 105, with no redistribution restriction, so
the series are charted and republished directly. The pull is
scripts/fetch_eia_commodities.py; the build into
data/parquet/eia_commodities.parquet is scripts/build_eia_commodities.py;
the page reads it through src/lib/commodities.ts with fixed SQL (no raw SQL on
the page, no typed number).
Series
Eight EIA series, keyed by a stable internal id used as the series_id column
(so an upstream series-id change never silently renames a column):
| id | EIA series id | what | units | frequency |
|---|---|---|---|---|
| WTI | PET.RWTC.D | Cushing, OK WTI crude spot price, FOB | dollars per barrel | daily |
| BRENT | PET.RBRTE.D | Europe Brent crude spot price, FOB | dollars per barrel | daily |
| HENRYHUB | NG.RNGWHHD.D | Henry Hub natural gas spot price | dollars per MMBtu | daily |
| GASOLINE | PET.EMM_EPM0_PTE_NUS_DPG.W | US retail gasoline, all grades, all formulations | dollars per gallon | weekly |
| DIESEL | PET.EMD_EPD2D_PTE_NUS_DPG.W | US on-highway No. 2 diesel retail price | dollars per gallon | weekly |
| CRUDEPROD | PET.WCRFPUS2.W | US field production of crude oil | thousand barrels per day | weekly |
| CRUDESTOCKS | PET.WCESTUS1.W | US ending stocks of crude oil, excluding the SPR | thousand barrels | weekly |
| GASSTORAGE | NG.NW2_EPG0_SWO_R48_BCF.W | Lower-48 working gas in underground storage | billion cubic feet (Bcf) | weekly |
The two anchors
Two headline prices are stated verbatim and match EIA's own latest print (both recomputed from the same pull the page reads):
- WTI crude spot: $79.20 per barrel, 2026-07-13 (PET.RWTC.D).
- Henry Hub natural gas spot: $2.83 per MMBtu, 2026-07-13 (NG.RNGWHHD.D).
Spot prices move every day, so the exact figure is not frozen into a build
assert (that would break on the next refresh, which is the honest behaviour of a
daily series). Instead the build prints anchor receipts for every headline and
enforces a range guard: the latest value of each series must fall inside a
sane physical band (WTI 10-250 $/bbl, Henry Hub 0.5-30 $/MMBtu, and so on), so a
units or parse disaster (a Bcf read as a price) fails the build rather than
shipping. The anchor pairs above were verified verbatim against EIA at the fetch
that seeded the module (2026-07-19) and are recorded in
data/raw/eia/SOURCE.md.
Definitions and computation
- Spot, not futures. Every price here is a physical spot price (delivery now), not a futures settlement. The Brent-WTI gap is the premium of the waterborne, import-relevant grade over the landlocked Cushing benchmark.
- Year-on-year change is the latest value against the nearest observation on or before the same date one year (365 days) earlier, which works uniformly for the daily and weekly series.
- 52-week range is the high and low over the trailing 365 days through the latest date. It is context, not a headline: a single daily gas-spot print can spike far above the range during extreme cold and revert within days.
- Crude production is field production of crude oil only, not total liquids (which would add natural-gas liquids and refinery gains). Reported in thousand barrels per day; the page shows it in millions.
- Crude stocks exclude the Strategic Petroleum Reserve, so this is the commercial inventory the market trades against, not government reserves.
- Working gas in storage is the Lower-48 total; the winter draw / summer injection sawtooth is the natural-gas storage year, not a data artifact.
- Retail fuels are US average pump prices including taxes: gasoline is the all-grades average, diesel is on-highway No. 2. They lag crude by weeks.
What is deliberately omitted
- Metals and the broad commodity indices. WTI, Brent and Henry Hub have a clean public-domain source in EIA. The metals and cross-commodity benchmarks that would round out a commodities page (S&P GSCI, Bloomberg Commodity Index, LME base metals, COMEX) are proprietary and licence-encumbered; there is no license-clean free spot source for them, so they are omitted honestly rather than shown from a source this platform has no right to redistribute. This matches the site's standing rule (the muni-yield and SIFMA omissions elsewhere in the estate).
- FRED as an independent cross-check. FRED does carry WTI and Brent (DCOILWTICO, DCOILBRENTEU), but those series are the EIA prints republished, so they are not an independent second source for spot energy; citing EIA directly is the better provenance.
Refresh and freshness
scripts/refresh.sh calls refresh_eia_commodities (fetch then build; both
idempotent, fixed filenames overwritten in place). Spot prices update each
business day and the weekly petroleum and gas reports update weekly, so the
series ride the daily tier. The /data catalog and the estate freshness table
carry the module's cadence, verified against EIA's own release calendar.
Limitations
- Weekly production and stock figures are EIA's own weekly estimates from the Weekly Petroleum Status Report; they are revised in the later monthly data.
- The retail fuel prices are national averages; regional prices vary widely.
- Nothing here is a forecast. Every value is a published observation.