Document restructuring and the beginnings of Filter 2 changes

Split the pipeline documentation by purpose so each fact has one home:
- docs/pipeline-plan.md keeps the plan, checklist, tracker, and guardrails
- docs/decisions.md holds open decisions and the dated decision log
- docs/reviews/ holds findings and tasks: one file per filter, plus
  00-cross-filter.md for findings that span filters
- scripts/common/README.md holds the shared-helper rules (formerly Phase 2)
- filter-calculations.md now describes calculations only

Filed findings 12-22 from a consistency audit of the app, docs, and scripts.

Filter 1 (Köppen-Geiger): use "Köppen" with the umlaut in all prose, labels,
docstrings, help text, and checker messages (finding 21), and correct the
base build's "majority" docstring (finding 22).

Filter 2 (annual avg temperature): record the adopted definition in
filter-calculations.md §2: equally weighted 1991-2020 monthly normals, per
WMO-No. 1203 and NOAA's 2020 methodology; area-weighted county means; blank
unless all 12 months exist. Code changes for this filter are still pending.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-15 16:13:11 -04:00
co-authored by Claude Opus 5
parent a9e722791d
commit e855d583e3
27 changed files with 807 additions and 242 deletions
+41
View File
@@ -0,0 +1,41 @@
# Filter 11: Solar GHI
**Status:** Not started.
**Data key:** `meanDailyGlobalHorizontalRadiationKwhM2Day`. Calculation:
[filter-calculations.md](../filter-calculations.md) §11.
## Findings
**9. The GHI formula assumes hourly, 365-day input.** It is correct for the
current 60-minute, `leap_day=false` requests. If the request interval changes,
the energy sum needs an interval-hours multiplier; leap-day handling would
also need to change the divisor.
**19. The data-sources doc recommends a GHI raster the pipeline does not use.**
Source 4 in `scripts/county_data_sources.md` says county means should come
from a gridded annual GHI raster passed with `--solar-ghi-raster`. The app
values come from NSRDB polygon archive summaries, with representative points
as fallback, applied by `apply_locally_extreme_metric_to_climate_data.py`.
**20. The base build labels any solar CSV as representative-point.** In
`build_county_climate_data.py`, the `--solar-ghi-csv` help text calls it a
representative-point fallback, and the per-row `source` tag is always
`solar-ghi-representative-point`, but the documented build command passes
`data/nrel/county_polygon_ghi_summary.csv`. The apply step later replaces both
the value and the tag, so only the base build's output is mislabeled.
Known issue to review: finalized by the extreme-temperature apply script.
Cross-filter findings that affect this filter, in
[00-cross-filter.md](00-cross-filter.md): 11 (inconsistent aggregation) and
16 (the app's NSRDB source link no longer resolves).
## Decisions
None yet.
## Tasks
Not started; follow the per-filter review checklist in
[pipeline-plan.md](../pipeline-plan.md) §5.