feat(data): update US state carbon intensity to EPA eGRID2023

[ArshiaBajaj]

Description

US regional emissions now use EPA eGRID2023 state CO₂eq total output emission rates instead of the eGRID2016 CO₂ rates.

• codecarbon/data/private_infra/2023/usa_emissions.json: new data file, same schema as the 2016 one (emissions in lbs/MWh, regionCode), plus a _source entry naming the eGRID edition and field.
• scripts/update_usa_emissions.py: builds that file from EPA's eGRID workbook (sheets ST23 / US23, fields STC2ERTA / USC2ERTA). --gas co2 switches to CO₂-only rates (STCO2RTA).
• codecarbon/input.py and pyproject.toml: point at, and package, the 2023 file. The 2016 file stays in the repo for history but is no longer shipped, like 2016/canada_energy_mix.json.
• docs/explanation/methodology.md: updated the regional-data table and added a short US paragraph, including how to rerun the script.

No logic in emissions.py changes.

Related Issue

Closes #1451. Part of #947 (process for updating reference data).

Motivation and Context

The 2016 rates overstate emissions for 45 of 51 states (incl. DC), 40 of them by more than 10%. Examples: US average 998.4 → 770.9 lb/MWh, Georgia 1001.8 → 717.4, Illinois 811.3 → 474.4, New Mexico 1572.8 → 773.6. Idaho, Washington and Oregon were understated by more than 10%. Every US user on the offline/default path gets these numbers.

CO₂ vs CO₂eq: I used the CO₂eq rate because CodeCarbon reports kg CO2eq. The gap from CO₂-only is under 2% for every state except Vermont (43.0 vs 52.2). If you'd rather keep CO₂ only, it's a one-flag change: --gas co2.

How Has This Been Tested?

• Built usa_emissions.json with the new script from EPA's official egrid2023_data_rev2.xlsx (rev. 2, June 2025); values match EPA's published Table 3 to within rounding.
• New tests/test_update_usa_emissions.py: JSON format, every state and DC present, a missing state raises, extra regions (PR) are ignored, the packaged file round-trips through the script, and reading an eGRID-layout workbook (skipped when openpyxl isn't installed, since it isn't a project dependency).
• tests/test_emissions.py: updated the Illinois expected value (0.110 → 0.0646 kg for 0.3 kWh) and tightened its precision. Added spot checks against EPA's published table (GA, VT, WV, US) and a test that every state resolves to its own rate through get_private_infra_emissions.
• Checked every row of the data: CO₂ + 28·CH₄ + 265·N₂O equals the published CO₂eq rate to within rounding (≤ 0.13 lb/MWh), using the AR5 GWPs that eGRID uses.
• Ran tests/test_emissions.py and tests/test_update_usa_emissions.py on macOS: 44 passed, 1 skipped. Formatting hooks (autoflake, isort, black, flake8) pass.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

AI Usage Disclosure

• 🟥 AI-vibecoded
• 🟠 AI-generated
• ⭐ AI-assisted
• ♻️ No AI used

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the docs/how-to/contributing.md document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[benoit-cty]

Thanks, that's a great improvement.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.94%. Comparing base (bbf14f1) to head (d78b226).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1452   +/-   ##
=======================================
  Coverage   92.94%   92.94%           
=======================================
  Files          50       50           
  Lines        5440     5440           
=======================================
  Hits         5056     5056           
  Misses        384      384           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ArshiaBajaj]

@benoit-cty thanks for the review! I moved the script to codecarbon/data/private_infra/update_usa_emissions.py and updated the test and docs paths (commit 71061cf). On units: I'll keep lbs/MWh here to match the existing file and open a follow-up PR to switch the US data to gCO2eq/kWh like the China and Nordic files. Ready for another look whenever you have time.