# Materials Monitor, Edition 1: September 2026: data dictionary

Files in this directory hold the record behind the edition. `data.csv` is source-reported data as parsed from the retained files; `series.csv` is the chart window of each series, with the rebased values the comparison chart draws; `measures.csv` is what the edition quotes, including the figures Field Assembly calculated; `numbers.json`, `evidence.json` and `exceptions.json` are the same record as kept in the repository. Values keep the precision they were parsed or computed at; the edition text rounds for display.

Data run: `2026-09-24T122426Z`. Information available as of 24 September 2026. Rows in data.csv: 1660. Rows in series.csv: 736.

License: Field Assembly's tables, calculations and documentation here are CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); cite the edition. Files under `evidence/` are third-party source material and keep their publishers' terms; see /reuse/.

## The measures

Core measures, one per material group. Each is a BLS Producer Price Index commodity series, not seasonally adjusted. An index is not a price and index levels are not comparable across series, because each has its own base period.

| series_id | Material | Measure |
|---|---|---|
| `WPU0811` | Softwood lumber | PPI, softwood lumber |
| `WPU10260314` | Copper | PPI, copper wire and cable |
| `WPU1017` | Steel | PPI, steel mill products |
| `WPU102501` | Aluminum | PPI, aluminum mill shapes |
| `WPU137` | Gypsum products | PPI, gypsum products |
| `WPU1333` | Ready-mix concrete | PPI, ready-mix concrete |

Context measures, each chosen to answer a stated question:

| series_id | Measure | Why it is here |
|---|---|---|
| `WPU1322` | PPI, cement (hydraulic) | Cement is an input to concrete, not another name for it. The two indexes are shown side by side so a reader can see when concrete moved without cement, or the reverse. |
| `WPU13710102` | PPI, gypsum building materials | The narrower index under gypsum products; wallboard is in it, but the index is not the price of any one board product. |
| `wb_copper_usd_mt` | LME copper, World Bank monthly average (USD per metric ton) | Raw copper, so that copper wire and cable can be compared with the metal it is made from. |
| `wb_aluminum_usd_mt` | LME aluminum, World Bank monthly average (USD per metric ton) | Raw aluminum, for the same comparison against mill shapes. |
| `usgs_cement_shipments_us_mt` | USGS: portland and blended cement shipments, U.S. plants (metric tons) | A supply and demand measure behind concrete. Lags the price indexes by several months. |
| `census_starts_total_saar` | Census: housing starts, total, seasonally adjusted annual rate (thousands) | Residential demand context. Not a measure of all construction demand. |

## data.csv

One row per series and period, from the data run named above. Monthly periods are `YYYY-MM`.

| Column | Meaning |
|---|---|
| series_id | Identifier. BLS series codes are used as published (for example `WPU0811`); Field Assembly identifiers are lowercase with underscores and name the source and the measure (for example `usgs_cement_shipments_us_mt`) |
| series_title | Plain description with product coverage, adjustment status and base period |
| period | Observation period, `YYYY-MM` |
| value | Numeric value as parsed. Empty when the source published a non-numeric marker; the marker is kept in `notes` |
| unit | `index (base)` for a PPI series with its base period; `USD per metric ton`; `metric tons`; `thousands of units` |
| observation_type | `CONTEMPORANEOUS_CAPTURE` for the latest period a series held at capture time (the value as first seen); `RETROSPECTIVE_HISTORY` for every earlier period, which is history as the source published it on the capture date and may already include the source's revisions |
| source_id | The source in `sources.json` and on the methodology page |
| source_label | The source's class: OFFICIAL STATISTIC or COMMODITY BENCHMARK, with what the figure is and is not |
| source_url | URL fetched (the final URL after any redirect) |
| captured_at | Retrieval time, UTC, ISO 8601 |
| evidence_path | The retained file, byte for byte, under `evidence/` in this directory |
| sha256 | SHA-256 of that file |
| notes | Preliminary or estimated flags, the source's release label, or its own marker text |

Missing values: an empty `value` cell means the source published no numeric value for that period. No value is imputed, interpolated, carried forward or seasonally adjusted by Field Assembly.

## series.csv

The 5-year chart window of each core and context series, ending at that series' own latest period. `rebased_to_window_start` is filled for the six core series only: value ÷ the series' value in Sep 2021 × 100, rounded to three decimals. The rebasing is a display transformation for the comparison chart; the original index values stay in `value` and in data.csv.

## measures.csv

Every figure in `numbers.json`, flattened to one row per leaf with a dotted key. `kind` says whether the row is a Field Assembly calculation or a value or label carried from a source. Calculations:

- `mom_pct`: (latest − prior month) ÷ prior month × 100, rounded to one decimal.
- `yoy_pct`: (latest − same month a year earlier) ÷ same month a year earlier × 100, one decimal.
- `vs_two_years_pct`: the same against the same month two years earlier.
- `same_month_earlier_years_yoy_pct`: `yoy_pct` computed for the same calendar month in each of the four preceding years.
- `since_prior_december.change_pct`: (latest − December of the prior year) ÷ that December × 100.
- `window_5y`: the series' high and low over the chart window, and `change_from_start_pct` against the first month of the window.
- `ytd` (USGS shipments): the sum of the months of the current year through the latest month, the same months a year earlier, and the percentage change between them. Marked INCOMPLETE when any month is missing.
- `pairs[].yoy_gap_points`: the product's `yoy_pct` minus the raw input's `yoy_pct`, in percentage points. A gap is an observation about two series; it is not a margin, a markup or a cost.

Nothing is averaged across series. There is no composite construction-cost figure in this record.

## Revisions

Each edition quotes what the source published at capture time. BLS marks the most recent four months of a PPI series preliminary and may revise them; USGS marks survey figures estimated and preliminary; Census revises recent starts. A later revision is not applied to an earlier edition. It appears in the next edition's data, and that edition notes it when it changes a previously quoted comparison by 0.5 points or more. Corrections to Field Assembly's own work are a separate matter and are listed at /corrections/.

## Sources in this data run

| source_id | Source | Class | Page |
|---|---|---|---|
| `bls` | U.S. Bureau of Labor Statistics: Producer Price Index commodity series (public API v1) | OFFICIAL STATISTIC (producer price index; not a delivered price) | https://www.bls.gov/ppi/ |
| `worldbank_cmo` | World Bank Commodity Price Data (the Pink Sheet), monthly prices | COMMODITY BENCHMARK (exchange settlement price, monthly average; not a U.S. delivered price) | https://www.worldbank.org/en/research/commodity-markets |
| `usgs_cement_mis` | U.S. Geological Survey, Mineral Industry Surveys: Cement (monthly workbook) | OFFICIAL STATISTIC (survey of producers; shipments in metric tons; preliminary) | https://www.usgs.gov/centers/national-minerals-information-center/cement-statistics-and-information |
| `census_nrc_starts` | U.S. Census Bureau, New Residential Construction: housing units started (time series workbook) | OFFICIAL STATISTIC (survey estimate; residential only) | https://www.census.gov/construction/nrc/data/series.html |

FRED republishes the BLS series; it is not a second source for them and is not fetched.

## evidence/

The retained source files with their HTTP response headers (Set-Cookie redacted at capture), and `capture.json` for each source with URL, time and SHA-256. Under `evidence/anchors/`, when present: the timestamp chain entry that covers these files, its manifest of hashes, and the RFC 3161 tokens. A token attests that the entry hash existed at the stated time; it does not attest that any source's figure was correct.