Doc: Residential electricity bills data dictionary
Status: Complete current source edition
Owner: Rene
Last verified: 2026-11-15
Depends on: pinned EIA annual historical and Table 5 Aworkbooks, analysis.py

year is the annual observation year. state is the two-letter producer geography; US is the national total, never a ranked state. state-names.json gives the full source names, with U.S. Totalmatching the older Table 5 A. The complete panel has all 50 states, DC and US for every year 2010 through 2025.

The Total Electric Industry worksheet residential columns are C=revenue in thousand nominal USD, D=electricity sales inMWh, E=customer account count, F=published price in cents/kWh. source_sheet and source_row retain original provenance; combine the row number and column letter for an exact cell. No other sector or provider worksheet is added, preventing double counting across reporting types.

monthly_bill_usd=revenue_thousand_usd*1000/accounts/12. monthly_use_kwh=sales_mwh*1000/accounts/12. effective_price_cents_kwh=revenue_thousand_usd/sales_mwh*100. published_price_cents_kwh preserves the source’s rounded display price. Derived fields use Decimal arithmetic and round to six decimals on export. Nominal dollars are not inflation adjusted. These are account averages, not household medians, tariff quotes or bills in a particular month.

bill_rank, price_rank, usage_rank each compare the same 51 state/DC rows in 2025, highest value first. Rank=1+count(other_values>this_value), so exact ties share a rank. The U.S. rank fields explicitly say Not ranked, U.S. total, rather than representing missing inputs. Ordering is checked against full precision source calculations. bill_vs_us_usd=statebill-USbill. bill_vs_us_pct=(statebill/USbill-1)*100.

bill_change_usd=bill2025-bill2024. bill_change_pct=(bill2025/bill2024-1)*100. price_component_usd=(P 2025-P 2024)*(Q 2024+Q 2025)/200; usage_component_usd=(Q 2025-Q 2024)*(P 2024+P 2025)/200. P uses cents/kWh, Q uses kWh/account/month. The identity is symmetric accounting, not a causal model. rounding_residual_usd preserves the difference between bill change and the two unrounded midpoint components computed from six decimal input fields, then rounds that residual to six decimals. Summing separately rounded exported components can add another one millionth of a dollar difference. Small residuals remain visible.

national-total-reconciliation compares sum of 51 state/DCvalues with the source’s separate U.S. total for accounts, sales MWhand revenue thousandUSD. sum_minus_us retains every signed difference. Do not combine residuals across units or replace the national total with a state sum.

prior-table 5 a-vintage-audit retains older source state names, customers, monthlykWh, price and bill, plus exact Table 5 Asource_row. current_minus_prior_usd is the signed difference between the current historical calculation for 2024 and the older producer published bill. The prior workbook’s OOXML representation may include binary floating artifacts; public bill differences are reported only to meaningful stated precision.
