Doc: AMR strategic and commercial crude stock data dictionary
Status: Fixed analytical edition
Owner: American Mineral Registry
Last verified: 2026-11-14
Depends on: pinned three-series EIA input, source definitions and analysis.py

All physical quantities with thousand_barrels suffix are reported in thousand barrels. Divide by 1000 for million barrels. These are month-end inventory snapshots, not averages or gross flows. The complete common fixed panel is January 2005 through December 2025,252 levels and251changes. January through August2026 is a separate observed module. EIA excludes lease stocks from January2005; the SPR category may include non-USstocks under storage agreements.

Run python3 analysis.py, then python3 figures.py in the extracted lane folder. Both use only the standard library, perform no network requests and do not modify source files. Calculations are exact integer differences or Decimal ratios before display rounding. Negative changes are declines in positive stocks, not negative physical stocks.

## comparison-snapshots.csv

2complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| month | Reference month YYYY-MM, measuring its closing stock. Excel’s date label identifies the month; period-end measurement follows EIA definitions. |
| commercial_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| commercial_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| observation | Observation, as defined by the complete matching source panel. |
| commercial_source | Original EIA producer series URL for this stock category. |
| spr_source | Original EIA producer series URL for this stock category. |
| total_source | Original EIA producer series URL for this stock category. |

## consecutive-month-stock-changes.csv

251complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| month | Reference month YYYY-MM, measuring its closing stock. Excel’s date label identifies the month; period-end measurement follows EIA definitions. |
| previous_month | Explicit endpoint or fixed-panel boundary, YYYY-MM. |
| commercial_change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_direction | Sign of reported endpoint difference: rising, falling or unchanged. Equal reported stocks do not prove no gross receipts/deliveries. |
| commercial_direction | Sign of reported endpoint difference: rising, falling or unchanged. Equal reported stocks do not prove no gross receipts/deliveries. |
| spr_current_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| commercial_current_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| commercial_previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_current_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |

## december-year-end-stocks.csv

21complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| month | Reference month YYYY-MM, measuring its closing stock. Excel’s date label identifies the month; period-end measurement follows EIA definitions. |
| commercial_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| commercial_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| observation | Observation, as defined by the complete matching source panel. |
| commercial_source | Original EIA producer series URL for this stock category. |
| spr_source | Original EIA producer series URL for this stock category. |
| total_source | Original EIA producer series URL for this stock category. |

## fixed-panel-summary.csv

3complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| series | spr, commercial (excluding SPR), or total crude stock, retaining exact producer definitions. |
| fixed_first_month | Explicit endpoint or fixed-panel boundary, YYYY-MM. |
| fixed_last_month | Explicit endpoint or fixed-panel boundary, YYYY-MM. |
| first_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| last_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| minimum_month | Minimum month, as defined by the complete matching source panel. |
| minimum_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| maximum_month | Maximum month, as defined by the complete matching source panel. |
| maximum_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| source_url | Original EIA producer series URL for this stock category. |

## joint-stock-direction-frequencies.csv

9complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| spr_direction | Sign of reported endpoint difference: rising, falling or unchanged. Equal reported stocks do not prove no gross receipts/deliveries. |
| commercial_direction | Sign of reported endpoint difference: rising, falling or unchanged. Equal reported stocks do not prove no gross receipts/deliveries. |
| observed_months | All tied month identifiers, semicolon separated. A direction-count field instead counts matched observations as named. |
| matched_comparisons | All251consecutive monthly comparisons in the fixed panel, including unchanged observations. |
| share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |

## largest-monthly-stock-changes.csv

30complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| series | spr, commercial (excluding SPR), or total crude stock, retaining exact producer definitions. |
| direction | Largest increase or largest decrease, a rank based on the sign and size of the matched stock difference. |
| rank | Order within the five largest increases or five largest decreases of the named stock series; ties ordered by month. |
| month | Reference month YYYY-MM, measuring its closing stock. Excel’s date label identifies the month; period-end measurement follows EIA definitions. |
| previous_month | Explicit endpoint or fixed-panel boundary, YYYY-MM. |
| change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| current_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| source_url | Original EIA producer series URL for this stock category. |

## latest-observed-versus-december.csv

3complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| series | spr, commercial (excluding SPR), or total crude stock, retaining exact producer definitions. |
| previous_month | Explicit endpoint or fixed-panel boundary, YYYY-MM. |
| latest_month | Explicit endpoint or fixed-panel boundary, YYYY-MM. |
| previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| latest_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| change_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| source_url | Original EIA producer series URL for this stock category. |

## matched-december-annual-changes.csv

20complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| year | Calendar year. Annual changes compare its December with the prior December, never sums of inventory snapshots. |
| prior_year | Calendar year. Annual changes compare its December with the prior December, never sums of inventory snapshots. |
| spr_previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_current_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_change_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| commercial_previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| commercial_current_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| commercial_change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| commercial_change_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| total_previous_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_current_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_change_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_change_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |

## monthly-stocks-2005-2025.csv

252complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| month | Reference month YYYY-MM, measuring its closing stock. Excel’s date label identifies the month; period-end measurement follows EIA definitions. |
| commercial_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| commercial_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| observation | Observation, as defined by the complete matching source panel. |
| commercial_source | Original EIA producer series URL for this stock category. |
| spr_source | Original EIA producer series URL for this stock category. |
| total_source | Original EIA producer series URL for this stock category. |

## recent-observed-months-2026.csv

8complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| month | Reference month YYYY-MM, measuring its closing stock. Excel’s date label identifies the month; period-end measurement follows EIA definitions. |
| commercial_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| total_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| spr_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| commercial_share_percent | Percentage of matched total stock for composition; current versus named prior stock for growth; counted comparisons divided by251for direction shares. Calculated before rounding. |
| observation | Observation, as defined by the complete matching source panel. |
| commercial_source | Original EIA producer series URL for this stock category. |
| spr_source | Original EIA producer series URL for this stock category. |
| total_source | Original EIA producer series URL for this stock category. |

## within-year-month-end-extremes.csv

63complete rows. Source-defined boundaries remain attached.

| Field | Definition |
| --- | --- |
| year | Calendar year. Annual changes compare its December with the prior December, never sums of inventory snapshots. |
| series | spr, commercial (excluding SPR), or total crude stock, retaining exact producer definitions. |
| minimum_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| minimum_months | All tied month identifiers, semicolon separated. A direction-count field instead counts matched observations as named. |
| maximum_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| maximum_months | All tied month identifiers, semicolon separated. A direction-count field instead counts matched observations as named. |
| december_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| within_year_range_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| december_minus_minimum_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| maximum_minus_december_thousand_barrels | Source level or arithmetic difference indicated by the field name, in thousand barrels. Minimum/maximum are month-end extrema, not daily records. |
| source_url | Original EIA producer series URL for this stock category. |

## Source inputs and qualifications

sources/stock-matched-input.csv contains all260common months from the three pinned original EIA XLS files, not inferred missing history. The source-cell trace retains sheet and row coordinates. Raw SPR history beginsOctober1977but only the commonJanuary2005onward window enters this comparison. No source missingness becomes a financial or physical zero. The fixed-panel extrema, signs and rankings exclude the separate2026module.

Stock shares divide SPR or excluding-SPR inventory by total inventory for the same month. Monthly changes subtract the immediately preceding included month; annual changes use matched December endpoints. All component bridges reconcile exactly at the reported thousand-barrel precision. A contribution to a net change is not a share of physical stock or a causal policy effect.

AMR calculations and original figures: CC BY 4.0. Retain original EIA/DOE attribution and applicable source terms.
