Climate-Mood-Analysis/docs/reviews/02-annual-avg-temperature.md

Filter 2: Annual avg temperature

Status: In progress: method decided (2026-09-15).

Data key: avgTempF. Calculation: filter-calculations.md §2.

Findings

1. Annual temperature weights months equally. February has the same weight as January or July. If the intended label means an average across all days, monthly normals should instead be weighted by the number of days in each month. Resolved on 2026-09-15: equal weighting is the WMO and NOAA standard for annual normals and is kept; see "Annual avg temperature month weighting" in decisions.md.

Cross-filter findings that affect this filter, in 00-cross-filter.md: 2 and 11 (county aggregation), 12 (Alaska and Hawaii not covered), and 15 (source text cites the station Normals).

Decisions

In decisions.md, all 2026-09-15: Annual avg temperature month weighting, aggregation, completeness, and in Alaska and Hawaii.

Tasks

Adopted definition: the equally weighted mean of the 12 monthly 1991–2020 normals of nClimGrid-Monthly tavg, area-weighted to each county; blank unless all 12 months are present. The per-cell normals follow NCEI's own gridded-normals method, "a simple 30-year average of monthly grids" (Rennie and Palecki, U.S. Monthly Gridded Precipitation and Temperature Climate Normals). Alaska and Hawaii stay blank; see decisions.md.

• Verify the calculation against the source data and the WMO and NOAA normals definitions (2026-09-15).
• Decide month weighting, aggregation, completeness, and Alaska/Hawaii handling (2026-09-15; see decisions.md).
• Rewrite filter-calculations.md §2 with the adopted definition, citing WMO-No. 1203 §4.3.3 and NOAA's 1991–2020 Normals methodology. State that average temperature is (Tmax + Tmin)/2 and that the grid covers the contiguous U.S. only (2026-09-15; the current touched-cell method is kept as "Current method" until the new values are applied).
• Add a continuous-value area-weighted mean to scripts/common/county_zonal_stats.py. It takes an array and transform, because nClimGrid is read from netCDF rather than a rasterio file, and reuses cell_coverage_fractions, the cos(latitude) scaling, and the padded window. NaN cells are excluded.
• Build scripts/build_county_avg_temp_metric.py, writing data/metrics/avg_temp.csv with avgTempF and a valid-month count. The 1991–2020 climatology step is NOAA-specific, so it stays with the NOAA code rather than common/.
• Single-column apply step scripts/apply_avg_temp_metric_to_climate_data.py with --dry-run. Move read_csv_rows (4 identical copies in apply_* scripts) into common/ as part of this step.
• check_climate_data.py: keep the 20–85 °F rule and the Alaska/Hawaii blank allowance until that open decision in decisions.md is made; confirm no new blanks in the contiguous U.S.
• Tests (tests/test_avg_temp_metric.py): partial-cell weights, cos(latitude), NaN exclusion, the 12-month rule, equal month weights, Celsius-to-Fahrenheit conversion and rounding, and the apply step.
• Apply to data/climate-data.csv, run the checker, and compare: the spread of changes, the largest shifts (expected in small, narrow, and coastal counties), and no new blanks among the 3,109 contiguous-U.S. counties.
• Mark finding 2 resolved for this metric in 00-cross-filter.md.
• Correct the avgTempF source text in app.js, which cites the station-based U.S. Climate Normals; describe it as 1991–2020 normals computed from nClimGrid-Monthly and link nClimGrid. The "(Normals)" label stays.
• Correct scripts/county_data_sources.md: Source 2 says the build reads monthly normals files, but it reads the nClimGrid monthly series and averages 1991–2020. Update the avgTempF definition line to match.
• Add the area-weighted avgTempF to the §7 guardrail on rerunning build_county_climate_data.py in pipeline-plan.md.