Implement unit conversion

[jvendries]

cc:
Closes: cornerstone-data/methods#86

What changed? Why?

Introduces mixed-unit (MWh) electricity emission factors for sector 221110 (generation), gated behind a new implement_electricity_mixed_units config flag. When enabled, the generation sector's output column in A, q, and B is converted from USD to MWh using eGRID net generation as the physical anchor and EIA Table 2.4 class-differentiated retail prices to compute per-column row scaling factors (c_row). This allows emission factors for the generation sector to be expressed in CO₂e/MWh rather than CO₂e/USD.

Key additions:

• electricity_disaggregation.py: Core conversion functions — electricity_output_factor, electricity_class_row_factors, apply_electricity_unit_conversion_to_A/q/B — and the GENERATION_SECTOR constant.
• electricity_end_use_mapping.py: Production home for the Cornerstone commodity → EPA end-use mapping and EIA Table 2.4 price loader, promoted from the analysis module. classify_industry_end_use now returns a (end_use, rule) tuple and iterates over CORNERSTONE_COMMODITIES_ELEC instead of CORNERSTONE_INDUSTRIES_ELEC.
• cornerstone_disagg_pipeline.py: electricity_mixed_units_enabled, electricity_conversion_factors, build_electricity_mixed_units_aq/b, and compute_mixed_unit_ef_vectors (non-cached, used for Track B class-vs-uniform comparison).
• derived_cornerstone.py: Cached derives derive_cornerstone_Aq_mixed_units, derive_cornerstone_B_mixed_units, and derive_cornerstone_y_nab_mixed_units.
• model_objects.py and cache_reset.py: get_A, get_Adom, get_B, get_D, get_q route through mixed-unit derives when the gate is on.
• diagnostics_helpers.py: apply_mixed_units_ef_diff_exemptions and apply_mixed_units_bly_diff_exemptions NaN out the 221110 percent-diff columns when units are incommensurate with the monetary baseline. New build_mixed_vs_monetary_comparison_df and sectors_for_mixed_vs_monetary_tab helpers populate a mixed_vs_monetary_221110 diagnostics tab.
• calculate_ef_diagnostics.py and calculate_national_accounting_balance_diagnostics.py: Route to mixed derives under the gate; write the new comparison tab; add a note column on BLy vs E_orig when drift is expected due to unit change.
• analysis/electricity/class_prices/: Track B analysis comparing class-priced vs uniform-price mixed EF vectors, with a CLI that writes CSV and markdown output.
• analysis/electricity/d_86/: Three-path toy analysis (Methods INFRA-001: Create diagnostics module eeio_diagnostics.py #86) demonstrating that applying mixed-unit conversion directly to scaled A/q (PR4 path) produces numerically identical results to rebuilding V/U/Y flow tables and rederiving A. Includes toy_tables, toy_scaling, toy_dom_imp, toy_paths, mixed_flow_conversion, write_report, and a pre-generated report.
• New config files: test_usa_config_waste_disagg_electricity_mixed_units.yaml and 2025_usa_cornerstone_v0_2_electricity_mixed_units.yaml. USAConfig validates that implement_electricity_mixed_units requires implement_electricity_disaggregation.

The d_85 analysis modules are refactored to re-export from the new production homes rather than defining their own copies of table_2_4_prices_cents_kwh, classify_industry_end_use, and build_end_use_map.

Testing

• Unit tests in test_electricity_mixed_units.py cover output factor validation, class row factor monotonicity, uniform-price similarity transform, end-use map coverage, gate-off no-op behavior, MWh anchor, y_nab consistency, D scalar bridge, and the non-cached compute_mixed_unit_ef_vectors path.
• test_toy_paths.py verifies that Section 2 (flow-level mixed) and Section 3 (direct matrix mixed) produce identical Atot and q, that output identities pass, and that BLy is dimensionally consistent.
• test_mixed_vs_monetary_diagnostics.py covers sectors_for_mixed_vs_monetary_tab and build_mixed_vs_monetary_comparison_df column structure and values.
• test_usa_config.py adds parsing and validation tests for implement_electricity_mixed_units.
• test_calculate_national_accounting_balance.py adds tests confirming mixed derives are called under the gate and that the note column and exemption_reason column appear in the correct output tabs.
• test_end_use_mapping.py updated to reflect the new (end_use, rule) return type and CORNERSTONE_COMMODITIES_ELEC coverage.

[jvendries]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Implement unit conversion #492 👈 (View in Graphite)
• Implement changes from resolutions from discussion #85 #490
• implement analysis for decisions 3, 5, and 7 in dicussion #85 #481
• Implement print to excel for PR3 #463
• Implement 221100 split #462
• main

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