Commodities and Energy methodology

How the /commodities module is built: what it holds, where every number comes from, how World Bank Pink Sheet variants and units are identified, how overlaps remain separate, the EIA anchors, and every limitation. CFTC futures positioning in WTI crude is on positioning.

Source

The broad commodity selector comes from the World Bank Commodity Markets Pink Sheet under CC BY 4.0. The application reads wb_pinksheet.parquet through src/lib/commodities.ts. The narrower US energy block comes from 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).

World Bank Pink Sheet definitions

The Pink Sheet selector requires a frequency and a variant. The application classifies every selected series as price or index from its unit first. The index_nominal and index_real rows have NULL units in today's parquet, so those two variants provide the classification only when the unit is NULL. One named-series exception then prevents a semantic error: any index whose commodity name contains MUV or Deflator is labelled "deflator, nominal (used to construct constant-dollar prices)", regardless of the sheet variant. The workbook's MUV series is the nominal manufactures-unit-value deflator, not a real-price index.

• Nominal observations (price_nominal) are prices when the unit is currency per quantity and indices when the unit ends in =100.
• Real observations (price_real) use the same unit rule; real prices are in constant 2010 US dollars, while index units retain their published basis.
• Nominal index (index_nominal) has reference basis 2010=100.
• Real index (index_real) has reference basis 2010=100.

The workbook supplies the 2010 reference year. Null units under index_nominal and index_real are indices and display the documented 2010=100 basis. A unit ending in =100 is also an index even when stored under a price_* variant. Everything with a currency-per-quantity unit is a price. The application renders the selected row's unit rather than looking it up in a commodity map. Published indices do not offer the chart's derived Index transform, so their native reference basis cannot be mistaken for a rebase to the first observation.

The stated opening view is monthly nominal price for Crude oil, Brent. Missing or invalid URL fields are disclosed beside the controls. If a valid variant and frequency are not available together, the resolver preserves the valid variant and selects a frequency that actually exists. A stale commodity resolves to Crude oil, Brent when that commodity exists on the slice, otherwise to the first alphabetical commodity on the validated slice.

Where a nominal monthly Pink Sheet price overlaps WTI, Brent, or Henry Hub, the two sources remain separate lines. EIA daily observations are averaged within months with at least 80% of weekdays observed; otherwise the EIA point is NULL. Annual comparisons require all twelve months to meet that rule; otherwise the annual EIA point is NULL. These EIA monthly and annual values are aggregates computed by this application, as are the common-period gap statistics; they are not observations published in that form by EIA or the World Bank. No splice or source substitution is performed.

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):

The two anchors

Two headline prices were checked digit-for-digit against EIA at the fetch that seeded this module (2026-07-19). They are that fetch's print, not the current one: spot prices move every day, and the page always renders the latest observation in the parquet.

• 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 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

• Proprietary commodity benchmarks. S&P GSCI, Bloomberg Commodity Index, LME benchmarks, and COMEX data are proprietary and licence-encumbered. The license-clean World Bank series are shown instead; proprietary series are omitted rather than republished without permission. 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.
• Pink Sheet nominal prices, real prices, nominal indices, and real indices are not interchangeable. Changing the selector changes the measured quantity.
• Pink Sheet and EIA observations can diverge because their source definitions and publication processes differ. The overlap chart is a comparison, not a merged canonical series.
• Nothing here is a forecast. Source-series values are published observations; displayed EIA monthly and annual comparison values and gap statistics are computed by this application using the rules above.