MODEL.md — Home Utilities Cost Estimator

Built: 2026-06-12 on geocoder · Code: /home/krish/gpu-pilot/energy/api/ DB: commute @ 172.26.1.152:5433 (rates/prices from the energy layer, see ../ENERGY.md; home attributes in nj_home_attributes, built by etl_nj_attributes.py)

Product thesis (Krishna): consumer energy calculators ask ~20 questions; almost all of the answer is determined by 4–5 variables that we can pull from public records + MLS. So: derive inputs from data, let users override, always disclose which inputs were assumed vs observed.

1. What the reference tools ask

Efficiency Smart "Electricity Usage Calculator" (efficiencysmart.org/electricity-usage-calculator; page is bot-walled, content reconstructed from its public search snippets + the DOE companion page energy.gov/energysaver/estimating-appliance-and-home-electronic-energy-use): a bottom-up appliance calculator — your electric rate, home details, then per-device wattage × hours/day for HVAC, water heater, fridge, laundry, lighting, electronics; compares standard vs efficient models. Useful as a UX checklist of end uses; useless as a data model (nobody knows their wattages — exactly the 20-question problem we're avoiding).

LBL Home Energy Saver (HES) (homes.lbl.gov/home-energy-saver; engineering docs at sites.google.com/a/lbl.gov/hes-public/; full methodology report LBNL-51938, Mills, "Home Energy Saver: Documentation of Calculation Methodology, Input Data, and Infrastructure") is the reference residential model: DOE-2 hourly simulation for heating/cooling driven by building envelope (floor area, vintage-based insulation defaults, windows, infiltration), HVAC equipment + efficiency, TMY3 weather by zip; water heating driven by occupant count + equipment; appliances/MELs from engineering defaults. Two design facts we copy:

1. Minimum-input mode: HES runs from just zip code + a few home basics, filling everything else from climate-zone/vintage defaults (largely RECS-derived) — validated "accurate, on average, to within 1% of actual energy use, majority of individual estimates within ±25%".
2. End-use decomposition: heating, cooling, water heating, base load are modeled separately, each with its own drivers — not one regression on total bill.

We do not embed DOE-2; we fit the same end-use structure statistically on RECS 2020 microdata, which is itself the dataset HES uses for many defaults.

2. The five dominant variables (and why)

Secondary (kept, but defaulted): home type (apartment −49% gas heat vs detached — shared walls), AC type (room AC −17% cooling kWh), water-heater fuel (NJ conditional prior: P(gas DHW | gas heat) = 0.89).

These five are also precisely the attributes available per-home from MOD-IV + MLS — which is the point.

3. Calibration — EIA RECS 2020 microdata

Source: data/recs2020_public_v7.csv (18,496 households, NWEIGHT national weights, includes per-household end-use disaggregation + HDD65/CDD65 + state). Fit by calibrate_recs.py → auto-generated coefficients.py. All regressions NWEIGHT-weighted; log-models mean-recalibrated so weighted predicted mean == weighted actual mean.

Units: RECS BTU columns are thousand BTU (kBTU). therms = kBTU/100; oil gal = kBTU/138.5; propane gal = kBTU/91.45. Gas-heated homes get +3,630 kBTU/yr "gas other" (cooking/dryer).

Climate: per-state NWEIGHT-weighted mean HDD65/CDD65 from the same microdata (51-state table embedded in coefficients.py; NJ = 4,516 HDD / 1,205 CDD) — self-consistent with the fits. County-level NOAA 1991–2020 normals are a noted refinement (NJ north–south spread is roughly ±10% HDD; sub-state climate is the smallest of the five effects here).

NJ priors (RECS NJ subsample, n=456): heating fuel 75.1% gas / 16.1% electric / 6.8% oil / 1.1% propane (AHS 2023 CBSA 35620 corroborates: 55% piped gas / 21% electric / 19% oil for the NY-NJ metro incl. NYC's oil/steam stock); 96.5% have AC; heat-pump share among electric-heated 18%; water-heater fuel conditional on heating fuel as above.

4. Pricing

5. Fallback ladder (per input, disclosed in sources)

1. User override (request attributes block) — always wins.
2. Resolved home from nj_home_attributes (address exact → zip+street → fuzzy prefix → nearest parcel ≤150 m).
3. Derived default: occupants from beds (RECS lookup); water-heater fuel from NJ conditional prior; heating fuel from the ACS B25040 modal prior (tract → county ladder via acs_fuel_priors, source label acs_b25040_{level}_prior; loaded by load_fuel_priors.py — ACS 2024 5-yr, 3,222 counties national + 11,908 tracts NJ/NY/CT/PA). RECS state modal prior (NJ: natural gas, p=0.75) remains the final fallback for geographies without a loaded prior (label state_modal_prior).
4. State average: sqft = state SF-detached mean (NJ 2,515), occupants = state mean (2.46), vintage = 1980-99 base group, climate = state HDD/CDD.

Confidence: high = sqft + year_built + heating fuel all observed/overridden; medium = sqft + year_built observed, fuel from prior; low = mostly defaults.

6. NJ attribute backbone — nj_home_attributes (2,540,595 homes)

Build notes: MOD-IV = tax_assessments (source nj_modiv, class 2 residential; has year_built + lat/lon but no sqft). Sqft comes from county_assessor_owners joined by reconstructed parcel key (district_block_lot; Bergen-style block/lot and Monmouth-style block.lot decoded) — 1,177,741 parcels — plus CJMLS living_area. CJMLS match rate vs parcels: 68.5% (34,984 of 51,089 unique listing addresses; exact normalized muni+street join, 1 ambiguous collision resolved by haversine).

Heating-fuel regex hit rate: 2.4% (1,506 of 61,609 CJMLS listings mention a recognizable fuel in public_remarks; 1,290 land in the final table). This is the weakest attribute by far — remarks are marketing copy. Stored as observations only (heating_fuel_source = 'remarks_regex', confidence 0.75–0.85); everyone else gets the state modal prior at estimate time. ⇒ ETL ask (flagged for Krishna): the CJMLS RESO feed carries standard Heating/Cooling lookup fields — adding them to the reso_etl mapping would take heating-fuel coverage from 2.4% to near-100% of listings and upgrade those homes from medium to high confidence.

7. Validation (required checks)

vs EIA NJ averages. EIA monthly form 861M: NJ residential ≈ 680–700 kWh/mo (8,160–8,400 kWh/yr) across all homes. RECS 2020 NJ weighted mean = 8,305 kWh ✓. Model default NJ single-family detached home (2,515 sqft) = 9,732 kWh vs RECS NJ SF-detached actual 10,138 kWh (−4.0%) — correctly above the all-homes average. NJ winter gas heating: model gas-heated default home = 777–825 therms/yr vs RECS NJ gas-heated weighted mean 908 therms (includes a prewar-skewed stock; a 1931 build estimates 825 ✓).

PSE&G typical-bill sanity. 2,000 sqft 1976 gas-heated colonial, 3BR, PSE&G dual fuel: 8,806 kWh ≈ 734 kWh/mo (PSE&G's "typical residential electric customer" benchmark is ~650–750 kWh/mo) and 814 therms/yr ⇒ $185.87 electric + $100.96 gas = $286.83/mo — inside PSE&G's published combined typical-bill band (~$270–310 at 2026 rates).

Worked examples (live API responses, 2026-06-12; full JSON in README):

All four inside the NJ single-family $150–450/mo believability band (oil-heated prewar at $490 is the expected exception — that is the oil-heat story, and the savings pitch).

8. Known limitations / next

1. State-mean HDD/CDD (county NOAA normals would sharpen NW-NJ vs shore by ~±10% on heat).
2. ~~Heating-fuel prior is state-level modal~~ Done 2026-06-12: acs_fuel_priors (commute DB) holds ACS B25040 2024 5-yr shares — county for all 3,222 US counties, tract for NJ/NY/CT/PA (11,908). Unknown-fuel homes now take the county modal fuel (tract honored when a tract geoid is supplied; the API has no tract geocoding yet). NJ effect: Sussex is the only county that flips (oil-modal, 48.4% oil vs 20.1% gas — an unknown-fuel 2,200 sqft Sparta home moves $253.81 → $442.96/mo); 156 NJ tracts are not gas-modal, the future tract-geocoding payoff. Nationally 1,661 of 3,222 counties are electric-modal (the South), so this prior is load-bearing for expansion beyond NJ. Pick is still deterministic modal — fuel-mixture expected-cost blending is a v2 option.
3. No equipment efficiency input (a 95 AFUE furnace vs 80 looks identical); RECS fits absorb the stock average. HES-style equipment detail is a v2 user-override field.
4. utility_rates_annual is bundled average revenue ¢/kWh, not marginal tariff blocks; URDB tariff detail exists in utility_tariffs for a finer bill engine later.
5. Coverage outside NJ: model + state climate + state prices work nationwide; per-home resolution is NJ-only until more parcel/MLS states are loaded (GSMLS/NJMLS would complete north Jersey listings).