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:
@@ -50,8 +50,6 @@ run after it.
|
||||
6. `summarize_county_gridmet_humidity.py` → `apply_gridmet_humidity_metric_to_climate_data.py`
|
||||
7. `apply_nsrdb_cloud_metric_to_climate_data.py`
|
||||
|
||||
The README's enrichment list starts at step 2 and omits steps 1 and 3.
|
||||
|
||||
### Problems
|
||||
|
||||
1. **Rerunning a step can destroy data.** The base build writes 12 columns,
|
||||
@@ -66,7 +64,8 @@ The README's enrichment list starts at step 2 and omits steps 1 and 3.
|
||||
2. **Order is implicit.** The sequence lives in the README, in
|
||||
`scripts/county_data_sources.md`, and in each script's assumptions.
|
||||
3. **Column ownership is unclear.** GHI is finalized by the extreme-temperature
|
||||
apply script; wettest/driest month are computed in two places.
|
||||
apply script; wettest/driest month are computed in two places. See findings
|
||||
25 and 26 in [reviews/00-cross-filter.md](reviews/00-cross-filter.md).
|
||||
4. **County aggregation is inconsistent.** See finding 11 in
|
||||
[reviews/00-cross-filter.md](reviews/00-cross-filter.md).
|
||||
5. **No single entry point or final check.** A new user must piece together
|
||||
@@ -160,20 +159,24 @@ For each filter:
|
||||
filter's review file under `docs/reviews/`.
|
||||
2. Decide any rule or method changes with the project owner, and record them in
|
||||
`decisions.md`.
|
||||
3. Record the adopted definition in `filter-calculations.md`.
|
||||
3. Record the adopted definition in `filter-calculations.md`. Until the new
|
||||
values are applied, keep the old definition below it under "Current
|
||||
method".
|
||||
4. Implement the calculation, writing `data/metrics/<metric>.csv`.
|
||||
5. Add a single-column apply step for the current CSV.
|
||||
6. Update the rules in `check_climate_data.py`.
|
||||
7. Add or update unit tests.
|
||||
8. Apply to the CSV, run `check_climate_data.py`, and compare changed counties
|
||||
against expectations.
|
||||
against expectations. Then rename "Current method" to "Previous method" in
|
||||
`filter-calculations.md`, as §1 does.
|
||||
9. Update the app if the value set or display changes.
|
||||
|
||||
## 6. Filter tracker
|
||||
|
||||
Each filter's findings, decisions, and tasks are in its review file. Findings
|
||||
that affect more than one filter are in
|
||||
[00-cross-filter.md](reviews/00-cross-filter.md).
|
||||
[00-cross-filter.md](reviews/00-cross-filter.md), and
|
||||
[reviews/README.md](reviews/README.md) indexes every finding number.
|
||||
|
||||
| # | Filter | Status | Review |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
Reference in New Issue
Block a user