EIA Updates

Scout’s residential and commercial baseline energy use is anchored to the U.S. Energy Information Administration (EIA) Annual Energy Outlook (AEO). When Scout is updated to a new AEO release, we use a small helper script to compare Scout’s internal microsegment totals against the official AEO tables.

The script lives in scout/AEO_update_helpers/baseline_comparison.py. At a high level it:

  • loads Scout’s processed AEO microsegments file (mseg_res_com_cz.json),

  • aggregates energy use by building class, fuel type, and end use,

  • queries the EIA AEO API for the matching time-series,

  • compares Scout vs. EIA year-by-year, and

  • prints summary tables showing any large differences.

Running the EIA update check

  1. Create a local `.env` file (not committed to git) in the project root (the same folder as pyproject.toml) with your EIA API key:

    EIA_API_KEY=YOUR_REAL_KEY_HERE

    You can request a free key from EIA at https://www.eia.gov/opendata/register.php.

  2. Install Scout and its dependencies into a virtual environment (see Installation Guide).

  3. From the project root, run the helper script, for example:

    python -m scout.AEO_update_helpers.baseline_comparison --year 2025

    Use --verbose to see the underlying API calls and any combinations where data are missing.

The output includes per-combination comparisons and simple roll-up tables by building class and fuel type. These reports make it easier to confirm that Scout’s baseline matches the chosen AEO reference.