feat: support ResStock and multifamily building handling

[nllong]

Summary

Adds support for NREL's residential building stock dataset, ResStock, alongside the existing ComStock support, and handles ResStock's representation of multifamily buildings.

Stacked on #31 (measure/package comparison) — this targets that branch, not main, so it will show that PR's diff too until it merges.

Background: where ResStock lives, and multifamily handling

ResStock is hosted on the same OEDI data lake as ComStock (nrel-pds-building-stock/end-use-load-profiles-for-us-building-stock/{year}/resstock_*), but differs in a few important ways I confirmed by inspecting the bucket directly:

• Metadata partitioning: only by state (state=DE/DE_upgrade0.parquet), not state+county like ComStock.
• Building types: residential housing categories, not commercial (Single-Family Detached, Multi-Family with 5+ Units, etc.), stored in in.geometry_building_type_recs.
• County format: in.county_name has no state prefix ("Kent County", not "DE, Kent County").
• Measure crosswalk: an Excel file (measure_name_crosswalk_res_{year}_{release}.xlsx), not csv.
• Releases: only resstock_amy2018_release_1 has been remastered into the current, consistent 2025 layout so far — the newer resstock_amy2018_release_2 still lives at its original (differently-structured) 2024 path, so it isn't supported yet.

Multifamily buildings: ResStock simulates individual dwelling units, not whole buildings — a "Multi-Family with 5+ Units" metadata row is one apartment unit, not the building. There's no shared "building id" tying units back to a real building; each is an independently sampled, weighted record. Relevant columns: in.geometry_building_number_units_mf (units in that unit's building), in.geometry_building_horizontal_location_mf/in.geometry_building_level_mf (the unit's position, affecting heat transfer with neighbors), and weight/in.units_represented (population scaling).

What changed

• Extracted BuildingStockProcessor (building_stock_processor.py): a shared base class with the S3 listing/downloading, list_upgrades(), and process_building_time_series() logic that's identical between ComStock and ResStock (same bucket, same timeseries layout, same upgrades_lookup.json convention). ComStockProcessor now subclasses it, unchanged behaviorally — all existing tests pass without modification.
• Added ResStockProcessor (resstock_processor.py):
  • SUPPORTED_RELEASES = {"release_1": ...} (only the one confirmed-working layout, for now).
  • RESSTOCK_BUILDING_TYPES — the 5 valid in.geometry_building_type_recs values, validated in the constructor.
  • State-only partitioned process_metadata()/process_metadata_for_upgrades() (simpler than ComStock's, no county sub-listing needed).
  • county_name filtering without the state prefix, get_measure_crosswalk()/find_upgrade_id() adapted to the xlsx format.
• Added openpyxl dependency (to read the xlsx crosswalk).
• Tests: tests/test_resstock_processor.py mirrors the ComStock test suite — release/building-type validation, mocked default-upgrades behavior, and integration tests for metadata download/filtering (including both multifamily categories and county-name-without-prefix), caching, list_upgrades, get_measure_crosswalk, find_upgrade_id, process_metadata_for_upgrades, and time series downloads.
• README: new "ResStockProcessor Class" section covering the differences from ComStock and a "Handling Multifamily Buildings" walkthrough.

from pathlib import Path
from resstock_processor import ResStockProcessor

processor = ResStockProcessor(
    state="DE", county_name="All", building_type="Multi-Family with 5+ Units", upgrade="0",
    base_dir=Path("./datasets/resstock"),
)
multifamily_units_df = processor.process_metadata(save_dir=processor.base_dir)
multifamily_units_df["weight"].sum()  # weighted total real housing units this sample represents

Validation

• uv run pytest tests/ -m unit ✅ (16 passed — release/building-type validation, mocked behaviors, for both ComStock and ResStock)
• uv run pytest tests/ -m integration ✅ (27 passed, ~1 min — full ComStock suite unchanged + new ResStock metadata/multifamily/crosswalk/timeseries tests for Delaware)
• uv run mypy ✅ (6 source files)
• uv run pre-commit run --all-files ✅
• Manual smoke tests confirming metadata download, multifamily filtering, find_upgrade_id, and time series downloads all work end-to-end against the live OEDI bucket