Doc: AMR heating research data dictionary
Status: Fixed source edition
Owner: American Mineral Registry
Last verified:2026-11-14
Depends on: pinned primary inputs, analysis.py and source validation

Run python3 analysis.py --lane heating from the extracted reproduction bundle. Python standard library only. Source files are read without modification or network refresh.

All percentages are calculated before display rounding. Empty essential inputs fail the calculation. Unreported cases are excluded, never assigned zero. Source estimates remain estimates.

## heating-and-nonheating.csv

30 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| fuel | Home’s main heating fuel; other uses of the same fuel are included. |
| region | Producer geographic category; U.S. average is not an unweighted regional mean. |
| winter | November through March season crossing years; latest2026-27 is forecast, preceding values producer estimates in November2026vintage. |
| total_expenditure_usd | Nominal USD for the specified household, season and case.  |
| heating_expenditure_usd | Nominal USD for the specified household, season and case.  |
| nonheating_expenditure_usd | Nominal USD for the specified household, season and case.  |
| heating_share_percent | Percentage, numerator and denominator identified by heating share percent. Changes vs2025-26use the prior winter; changes vsbase use the current base forecast. |
| nonheating_share_percent | Percentage, numerator and denominator identified by nonheating share percent. Changes vs2025-26use the prior winter; changes vsbase use the current base forecast. |
| source_cells | Exact original worksheet and cell span; raw source-cell download retains the cached value. |
| source_url | Original primary producer URL. |

## heating-degree-days.csv

40 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| region | Producer geographic category; U.S. average is not an unweighted regional mean. |
| winter | November through March season crossing years; latest2026-27 is forecast, preceding values producer estimates in November2026vintage. |
| case | Producer base, warmer or colder weather scenario, not a probability interval. |
| heating_degree_days | Source seasonal population-weighted heating degree days below65Fbase; forecast weather cases remain separate. |
| source_url | Original primary producer URL. |

## main-heating-fuel-households.csv

180 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| region | Producer geographic category; U.S. average is not an unweighted regional mean. |
| winter | November through March season crossing years; latest2026-27 is forecast, preceding values producer estimates in November2026vintage. |
| main_heating_fuel | One of all six producer household categories; oil includes kerosene. |
| households_thousands | Household counts in thousands, not single households; complete six-category denominator for shares. |
| share_percent | Percentage with the table’s stated denominator. |
| all_fuels_total_thousands | Household counts in thousands, not single households; complete six-category denominator for shares. |
| source_url | Original primary producer URL. |

## monthly-household-expenditures.csv

150 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| fuel | Home’s main heating fuel; other uses of the same fuel are included. |
| region | Producer geographic category; U.S. average is not an unweighted regional mean. |
| winter | November through March season crossing years; latest2026-27 is forecast, preceding values producer estimates in November2026vintage. |
| month | Month name inside the labeled winter; January toMarchbelong toitsendingcalendaryear. |
| quantity | Physical quantity associated with the stated unit. |
| quantity_unit | Mcf=1000cubicfeet, gallons, or kWh. |
| heating_quantity | Physical quantity allocated by source to heating or other uses, in quantity_unit. |
| nonheating_quantity | Physical quantity allocated by source to heating or other uses, in quantity_unit. |
| unit_price_usd | Dollars per physical quantity unit; source electricity cents divided by100. |
| expenditure_usd | Nominal dollars per modeled household for this main fuel, not all household energy. |
| heating_expenditure_usd | Nominal USD for the specified household, season and case.  |
| nonheating_expenditure_usd | Nominal USD for the specified household, season and case.  |
| source_cells | Exact original worksheet and cell span; raw source-cell download retains the cached value. |
| source_url | Original primary producer URL. |

## price-quantity-decomposition.csv

15 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| fuel | Home’s main heating fuel; other uses of the same fuel are included. |
| region | Producer geographic category; U.S. average is not an unweighted regional mean. |
| previous_expenditure_usd | Nominal USD for the specified household, season and case.  |
| base_expenditure_usd | Nominal USD for the specified household, season and case.  |
| change_usd | Nominal USD for the specified household, season and case.  |
| price_component_usd | Nominal USD for the specified household, season and case. Exact old-baseline accounting component, not causal attribution. |
| quantity_component_usd | Nominal USD for the specified household, season and case. Exact old-baseline accounting component, not causal attribution. |
| interaction_usd | Nominal USD for the specified household, season and case. Exact old-baseline accounting component, not causal attribution. |
| price_change_percent | Percentage, numerator and denominator identified by price change percent. Changes vs2025-26use the prior winter; changes vsbase use the current base forecast. |
| quantity_change_percent | Percentage, numerator and denominator identified by quantity change percent. Changes vs2025-26use the prior winter; changes vsbase use the current base forecast. |
| source_url | Original primary producer URL. |

## seasonal-household-expenditures.csv

90 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| fuel | Home’s main heating fuel; other uses of the same fuel are included. |
| region | Producer geographic category; U.S. average is not an unweighted regional mean. |
| winter | November through March season crossing years; latest2026-27 is forecast, preceding values producer estimates in November2026vintage. |
| status | Original estimate or forecast status. |
| quantity | Physical quantity associated with the stated unit. |
| quantity_unit | Mcf=1000cubicfeet, gallons, or kWh. |
| unit_price_usd | Dollars per physical quantity unit; source electricity cents divided by100. |
| expenditure_usd | Nominal dollars per modeled household for this main fuel, not all household energy. |
| source_cells | Exact original worksheet and cell span; raw source-cell download retains the cached value. |
| source_url | Original primary producer URL. |

## used-workbook-cells.csv

1720 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| sheet | Original nominal workbook sheet name. |
| cell | Original spreadsheet cell coordinate in the named sheet. |
| cached_value | Unmodified numerical string stored in the producer XLSX XML, without formula recalculation. |
| source_url | Original primary producer URL. |

## weather-scenarios.csv

45 complete rows. Fields below retain their declared source population and units.

| Field | Definition |
| --- | --- |
| fuel | Home’s main heating fuel; other uses of the same fuel are included. |
| region | Producer geographic category; U.S. average is not an unweighted regional mean. |
| winter | November through March season crossing years; latest2026-27 is forecast, preceding values producer estimates in November2026vintage. |
| case | Producer base, warmer or colder weather scenario, not a probability interval. |
| quantity | Physical quantity associated with the stated unit. |
| quantity_unit | Mcf=1000cubicfeet, gallons, or kWh. |
| unit_price_usd | Dollars per physical quantity unit; source electricity cents divided by100. |
| expenditure_usd | Nominal dollars per modeled household for this main fuel, not all household energy. |
| change_vs_2025_26_percent | Percentage, numerator and denominator identified by change vs 2025 26 percent. Changes vs2025-26use the prior winter; changes vsbase use the current base forecast. |
| change_vs_base_percent | Percentage, numerator and denominator identified by change vs base percent. Changes vs2025-26use the prior winter; changes vsbase use the current base forecast. |
| source_cells | Exact original worksheet and cell span; raw source-cell download retains the cached value. |
| source_url | Original primary producer URL. |

## Scope and reuse

Household expenditure is modeled main-fuel spending, including non-heating uses of that fuel. It is not equipment-switching savings, a household bill distribution, a hardship measure or mineral royalty income. Source electricity cents/kWh are converted to USD/kWh. The price component uses the old quantity; the quantity component uses the old price; the interaction is the product of both changes. Only nominal Seasonal/Monthly sheets are used; broken legacy Real sheets are excluded.

AMR calculations and original charts: CC BY4.0. Preserve original producer attribution and applicable source terms.
