Implement industry mecs allocation

[jvendries]

cc: cornerstone-data/methods#90
Closes:

What changed? Why?

Introduces MECS Table 7.7 purchased-kWh shares as the default weighting method for Industrial manufacturing purchasers in the EIA-anchored G/T/D electricity allocation, replacing the previous dollar-bill weighting inside manufacturing. The allocation now splits the Industrial class into two pools: manufacturing sectors (weighted by Table 7.7 kWh) and residual Industrial sectors (weighted by dollar bills). A dollars fallback is preserved for diagnostics and tests that must not load Table 7.7. The table was uploaded to GCS as excel and parquet FBA files.

To support comparison between the new MECS-weighted path and the prior dollar-weighted path, a pre-MECS freeze is introduced under historical/pre_mecs_industrial_weights/output/, capturing EIA G/T/D mixed-units q and N with dollar manufacturing weights. A write_freeze script generates this snapshot, and a compare_to_pre_mecs module compares live MECS output against it (not a CI gate).

A five-slide PPTX comparison deck (diagnostics/deck/) is added to visualize differences across three implementation pairs: current (post-MECS) vs. EIA G/T/D pre-MECS, current vs. original electricity disaggregation, and EIA G/T/D pre-MECS vs. original. Each deck includes class MWh tables, per-step D/N EF tables with same/N/A cell labeling, and two-row histogram panels using frozen archived PNGs where available.

The purchaser_tables module is updated to rename d0_* terminology to class_mwh_targets/class_target_mwh throughout, add a manufacturing_mecs_vs_dollar_frame for dual-run comparison, and expose p_share_from_allocation. EIA MECS Energy extraction is extended to parse Table 7.7 (million kWh) for both 2018 and 2022 survey years, with correct unit assignment distinct from Table 7.2 (money). The 2022 MECS year is added to the raw data extraction script.

Cache reset logic is extended to clear the new mecs_purchased_kwh LRU cache alongside existing electricity caches. Existing tests that exercise the allocation path are wrapped with a dollar_industrial_weights context manager so they do not trigger Table 7.7 loading.

Testing

• New unit tests in test_electricity_gtd_mecs.py cover MECS year mapping, NAICS overlay deduplication, 3-digit suppressed-value imputation, two-pool Industrial MWh identity, dollar-path isolation, zero-bill and zero-residual edge cases, cache mutation safety, and cache reset behavior.
• New unit tests in test_eia_mecs_energy_units.py confirm Table 7.7 produces million kWh units and Table 7.2 continues to produce USD / million btu.
• New unit tests in test_purchaser_tables.py cover p_share_from_allocation, manufacturing_mecs_vs_dollar_frame flags, and the renamed class_mwh_targets_frame.
• New unit tests in test_deck.py cover data helpers, histogram frame construction, frozen panel stacking, table grid generation, and end-to-end PPTX assembly (five slides, at least two media files).
• A freeze-existence test in test_pre_mecs_freeze_exists.py asserts the committed parquet files are present on disk.
• An integration test (pytest.mark.eeio_integration) validates post-overlay NAICS presence in live Table 7.7 data for 2018 and 2022.

[jvendries]

• Implement industry mecs allocation #736 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.