Refine project documentation and track metric files

Close gaps found in a review of the documentation:
- Track data/metrics/ and data/metric_sources.json in git so the data
  checker passes on a fresh clone (finding 23; decision logged)
- State the Alaska and Hawaii coverage gap in the README limitations and
  extend finding 12
- File findings 24-26: the data-sources doc lacks gridMET and several
  pipeline commands; wettest/driest month are computed twice; solar GHI
  is written by the extreme-temperature apply step
- Add the stale "fallback values" note to filter 2's tasks

Tidy the document system:
- Add docs/reviews/README.md with the numbering rules and a finding index
- Rename koppen-mixed-display-plan.md to koppen-mixed-display.md and fix
  its stale Puerto Rico and "stage 5" text
- Add the precipitation-month step to the README enrichment list
- Describe the Current method / Previous method pattern in plan section 5
- Add CLAUDE.md with the project guardrails and doc layout

Format filter-calculations.md so it renders on GitHub and in VS Code:
inline math uses $...$, ranges use en dashes, and implementation
references name functions instead of line numbers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-15 17:31:26 -04:00
co-authored by Claude Opus 5
parent e855d583e3
commit 867a07cecb
20 changed files with 3519 additions and 121 deletions
+10 -4
View File
@@ -46,7 +46,7 @@ calendar year. Definitions and time periods are shown in the application's
### Requirements
- A modern web browser
- Python 3
- Python 3 (the data pipeline targets Python 3.11)
- PowerShell for the included convenience script
- An internet connection for Leaflet, map tiles, and hosted fonts
@@ -167,6 +167,7 @@ are:
```powershell
.venv\Scripts\python.exe scripts\build_county_koppen_metric.py
.venv\Scripts\python.exe scripts\apply_koppen_metric_to_climate_data.py
.venv\Scripts\python.exe scripts\apply_precipitation_month_metrics_to_climate_data.py
.venv\Scripts\python.exe scripts\build_county_locally_extreme_data.py --skip-download
.venv\Scripts\python.exe scripts\apply_locally_extreme_metric_to_climate_data.py
.venv\Scripts\python.exe scripts\build_county_diurnal_temperature_range.py
@@ -176,8 +177,9 @@ are:
.venv\Scripts\python.exe scripts\apply_nsrdb_cloud_metric_to_climate_data.py
```
The order matters when rebuilding from scratch: run the Köppen apply step after
the base build, generate the locally extreme comparison and solar summaries
These stages follow the base build, `build_county_climate_data.py`, which must
not be rerun over the live CSV. The order matters when rebuilding from scratch:
run the Köppen and precipitation-month apply steps after the base build, generate the locally extreme comparison and solar summaries
before running their apply step, and summarize gridMET or NSRDB downloads
before merging them. See the data-source document linked above for acquisition
commands, expected artifacts, FIPS handling, and the representative-point and
@@ -193,7 +195,7 @@ After updating the CSV, validate it with:
Run the current automated tests with:
```powershell
python -m unittest discover -s tests
.venv\Scripts\python.exe -m unittest discover -s tests
```
## Planned Mood Analysis
@@ -223,6 +225,10 @@ causes changes in mood.
represent every location inside a county.
- Source datasets use different methods and, in some cases, different time
periods.
- Alaska and Hawaii have values only for the Köppen class and the two solar
metrics. The NOAA and gridMET sources behind the other nine metrics cover the
contiguous U.S. only, so those counties show "No data". Puerto Rico is not
shown.
- Some solar metrics use representative-point values where county polygon
summaries are unavailable.
- The current interface is an exploratory visualization, not a completed