diff --git a/.gitignore b/.gitignore index a160f49..7151b19 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ __pycache__/ *.py[cod] .pytest_cache/ +*.egg-info/ diff --git a/README.md b/README.md index 0a93a4f..6497021 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,7 @@ This mini-lab is a supporting scientific-data project and is not part of the Useful entry points: - [`precipitation-anomaly-diagnostics` README](projects/precipitation-anomaly-diagnostics/README.md) +- [Reviewer path](projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md) - [Data policy](projects/precipitation-anomaly-diagnostics/docs/data-policy.md) - [Methodology](projects/precipitation-anomaly-diagnostics/docs/methodology.md) - [Inference framework](projects/precipitation-anomaly-diagnostics/docs/inference-framework.md) @@ -114,6 +115,7 @@ the `sbom-diff-and-risk` release surface. Useful entry points: - [`precipitation-anomaly-diagnostics-lab` README](projects/precipitation-anomaly-diagnostics-lab/README.md) +- [Reviewer path](projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md) - [Calculation methods](projects/precipitation-anomaly-diagnostics-lab/docs/calculation-methods.md) - [Inference analysis](projects/precipitation-anomaly-diagnostics-lab/docs/inference-analysis.md) - [Synthetic inference report](projects/precipitation-anomaly-diagnostics-lab/examples/synthetic-inference-report.md) diff --git a/docs/reviewer-brief.md b/docs/reviewer-brief.md index 248dc6c..f6c0931 100644 --- a/docs/reviewer-brief.md +++ b/docs/reviewer-brief.md @@ -35,8 +35,8 @@ workflows, but they are not part of the `sbom-diff-and-risk` release surface. | Project | Role | Start here | | --- | --- | --- | -| `precipitation-anomaly-diagnostics` | Compact reviewer-facing mini-lab | [README](../projects/precipitation-anomaly-diagnostics/README.md) | -| `precipitation-anomaly-diagnostics-lab` | Extended climate diagnostics lab | [README](../projects/precipitation-anomaly-diagnostics-lab/README.md) | +| `precipitation-anomaly-diagnostics` | Compact reviewer-facing mini-lab | [Reviewer path](../projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md) | +| `precipitation-anomaly-diagnostics-lab` | Extended climate diagnostics lab | [Reviewer path](../projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md) | | `python-weather-diagnostics-toolkit` | Reusable weather-field diagnostics toolkit | [Reviewer path](../projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md) | ## Reviewer evidence diff --git a/projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md b/projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md new file mode 100644 index 0000000..e3031ea --- /dev/null +++ b/projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md @@ -0,0 +1,108 @@ +# Reviewer path + +This reviewer path is the ordered route for reading the extended precipitation +diagnostics lab. It keeps the lab reviewable as supporting scientific-computing +evidence without presenting it as the repository's flagship release surface. + +## 30-second orientation + +Read the project [README](../README.md) first. Confirm this is a public-safe +extended diagnostics lab, not a course archive, not a raw-data mirror, and not +an operational forecast system. + +Check the first screen for the project role: + +- extended precipitation diagnostics lab variant +- supporting scientific-data project inside `scientific-computing-toolkit` +- not part of the `sbom-diff-and-risk` release surface +- not a separate meteorology portfolio + +## 5-minute workflow review + +Inspect: + +- [`docs/data-policy.md`](data-policy.md) +- [`docs/methodology.md`](methodology.md) +- [`docs/calculation-methods.md`](calculation-methods.md) +- [`docs/inference-analysis.md`](inference-analysis.md) +- [`examples/synthetic-inference-report.md`](../examples/synthetic-inference-report.md) + +This pass should answer whether the lab explains its configurable diagnostics, +synthetic demonstration assets, and inference boundaries without requiring raw +climate datasets or private local materials. + +## 15-minute reproducibility review + +The command files covered by this pass are +[`scripts/run_precipitation_anomalies.py`](../scripts/run_precipitation_anomalies.py), +[`scripts/run_eof.py`](../scripts/run_eof.py), +[`scripts/run_composite_circulation.py`](../scripts/run_composite_circulation.py), +[`scripts/run_index_correlations.py`](../scripts/run_index_correlations.py), +[`scripts/run_lag_diagnostics.py`](../scripts/run_lag_diagnostics.py), +[`scripts/run_mca.py`](../scripts/run_mca.py), +[`scripts/run_regression.py`](../scripts/run_regression.py), and +[`scripts/run_trend_diagnostics.py`](../scripts/run_trend_diagnostics.py). + +Run: + +```bash +python -m pip install -e . +python -m unittest discover -s tests +python scripts/run_precipitation_anomalies.py --help +python scripts/run_eof.py --help +python scripts/run_composite_circulation.py --help +python scripts/run_index_correlations.py --help +python scripts/run_lag_diagnostics.py --help +python scripts/run_mca.py --help +python scripts/run_regression.py --help +python scripts/run_trend_diagnostics.py --help +``` + +Then inspect the synthetic demonstration path: + +The generator is +[`examples/generate_synthetic_demo_assets.py`](../examples/generate_synthetic_demo_assets.py). + +```bash +python examples/generate_synthetic_demo_assets.py +``` + +Expected result: + +- tests pass with synthetic fixtures +- CLI help surfaces are available without local dataset paths +- committed demonstration figures remain clearly synthetic +- generated outputs stay outside the committed source tree unless explicitly + intended as example artifacts + +## Boundaries + +Read: + +- [`docs/data-policy.md`](data-policy.md) +- [`SANITIZATION_REPORT.md`](../SANITIZATION_REPORT.md) +- [`docs/reproducibility.md`](reproducibility.md) + +This project is a supporting extended lab for scientific-computing review. It +does not claim causal attribution, forecast skill, field-significant map +testing, production readiness, or public redistribution of raw climate data. + +## Technical deep-dive route + +For a deeper review, read the project in this order: + +1. [`src/climate_diagnostics/config.py`](../src/climate_diagnostics/config.py) + for typed configuration boundaries. +2. [`src/climate_diagnostics/io.py`](../src/climate_diagnostics/io.py) for + dataset loading and derived-output path handling. +3. [`src/climate_diagnostics/grids.py`](../src/climate_diagnostics/grids.py) + for anomaly, climatology, EOF, and composite helpers. +4. [`src/climate_diagnostics/statistics.py`](../src/climate_diagnostics/statistics.py) + for correlation, regression, trend, lag, and MCA helpers. +5. [`src/climate_diagnostics/plotting.py`](../src/climate_diagnostics/plotting.py) + for reviewer-visible synthetic charts. +6. [`docs/calculation-methods.md`](calculation-methods.md) for formulas and + interpretation constraints. + +This route should make the lab reviewable as a public-safe diagnostics workflow +rather than as a claim about an operational climate product. diff --git a/projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md b/projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md index 51a3440..58f0c96 100644 --- a/projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md +++ b/projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md @@ -4,7 +4,9 @@ This reviewer path is a lightweight guide for reading the compact precipitation ## 30-second orientation -Read the project README first. Confirm this is a sanitized scientific-computing mini-lab, not a course archive and not an operational forecast system. +Read the project [README](../README.md) first. Confirm this is a sanitized +scientific-computing mini-lab, not a course archive and not an operational +forecast system. Check the first screen for the project role: @@ -45,4 +47,4 @@ Read: - [`docs/data-policy.md`](data-policy.md) - [`PUBLICATION_BOUNDARIES.md`](../PUBLICATION_BOUNDARIES.md) -The project should be read as a reproducible spatiotemporal diagnostics module: it demonstrates data-policy discipline, analysis structure, and reviewer-friendly interpretation while keeping raw datasets, institutional course artifacts, personal identifiers, and local machine details out of the public repository. \ No newline at end of file +The project should be read as a reproducible spatiotemporal diagnostics module: it demonstrates data-policy discipline, analysis structure, and reviewer-friendly interpretation while keeping raw datasets, institutional course artifacts, personal identifiers, and local machine details out of the public repository. diff --git a/projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md b/projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md index 5622a36..e32eb44 100644 --- a/projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md +++ b/projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md @@ -2,9 +2,9 @@ ## 30-second orientation -Read the README first. Confirm this is a sanitized Python weather-diagnostics -mini-lab, not a course archive, not a raw-data mirror, and not an operational -forecast system. +Read the project [README](../README.md) first. Confirm this is a sanitized +Python weather-diagnostics mini-lab, not a course archive, not a raw-data +mirror, and not an operational forecast system. Check the first screen for the project role: diff --git a/scripts/validate-reviewer-routes.py b/scripts/validate-reviewer-routes.py index f19c14b..2755e5d 100644 --- a/scripts/validate-reviewer-routes.py +++ b/scripts/validate-reviewer-routes.py @@ -12,6 +12,9 @@ Path("README.md"), Path("docs/reviewer-brief.md"), Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"), + Path("projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md"), + Path("projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md"), + Path("projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md"), ) REQUIRED_LINK_TARGETS = { @@ -19,12 +22,16 @@ "docs/reviewer-brief.md", "tools/sbom-diff-and-risk/docs/reviewer-path.md", "tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md", + "projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md", + "projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md", "projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md", }, Path("docs/reviewer-brief.md"): { "README.md", "tools/sbom-diff-and-risk/docs/reviewer-path.md", "tools/sbom-diff-and-risk/docs/example-artifact-regeneration.md", + "projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md", + "projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md", "projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md", }, Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"): { @@ -36,6 +43,54 @@ "tools/sbom-diff-and-risk/examples/sample-policy.json", "tools/sbom-diff-and-risk/examples/sample-sarif.sarif", }, + Path("projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md"): { + "projects/precipitation-anomaly-diagnostics/README.md", + "projects/precipitation-anomaly-diagnostics/docs/data-policy.md", + "projects/precipitation-anomaly-diagnostics/docs/inference-framework.md", + "projects/precipitation-anomaly-diagnostics/docs/methodology.md", + "projects/precipitation-anomaly-diagnostics/examples/sample_metadata.json", + "projects/precipitation-anomaly-diagnostics/PUBLICATION_BOUNDARIES.md", + "projects/precipitation-anomaly-diagnostics/reports/example-report.md", + }, + Path("projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md"): { + "projects/precipitation-anomaly-diagnostics-lab/README.md", + "projects/precipitation-anomaly-diagnostics-lab/docs/calculation-methods.md", + "projects/precipitation-anomaly-diagnostics-lab/docs/data-policy.md", + "projects/precipitation-anomaly-diagnostics-lab/docs/inference-analysis.md", + "projects/precipitation-anomaly-diagnostics-lab/docs/methodology.md", + "projects/precipitation-anomaly-diagnostics-lab/docs/reproducibility.md", + "projects/precipitation-anomaly-diagnostics-lab/examples/synthetic-inference-report.md", + "projects/precipitation-anomaly-diagnostics-lab/examples/generate_synthetic_demo_assets.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_composite_circulation.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_eof.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_index_correlations.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_lag_diagnostics.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_mca.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_precipitation_anomalies.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_regression.py", + "projects/precipitation-anomaly-diagnostics-lab/scripts/run_trend_diagnostics.py", + "projects/precipitation-anomaly-diagnostics-lab/src/climate_diagnostics/config.py", + "projects/precipitation-anomaly-diagnostics-lab/src/climate_diagnostics/grids.py", + "projects/precipitation-anomaly-diagnostics-lab/src/climate_diagnostics/io.py", + "projects/precipitation-anomaly-diagnostics-lab/src/climate_diagnostics/plotting.py", + "projects/precipitation-anomaly-diagnostics-lab/src/climate_diagnostics/statistics.py", + "projects/precipitation-anomaly-diagnostics-lab/SANITIZATION_REPORT.md", + }, + Path("projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md"): { + "projects/python-weather-diagnostics-toolkit/README.md", + "projects/python-weather-diagnostics-toolkit/docs/calculation-methods.md", + "projects/python-weather-diagnostics-toolkit/docs/climate-statistical-diagnostics.md", + "projects/python-weather-diagnostics-toolkit/docs/data-policy.md", + "projects/python-weather-diagnostics-toolkit/docs/diagnostic-analysis.md", + "projects/python-weather-diagnostics-toolkit/docs/focused-case-abstraction.md", + "projects/python-weather-diagnostics-toolkit/docs/methodology.md", + "projects/python-weather-diagnostics-toolkit/docs/source-to-public-mapping.md", + "projects/python-weather-diagnostics-toolkit/docs/station-precipitation-workflows.md", + "projects/python-weather-diagnostics-toolkit/examples/sample_metadata.json", + "projects/python-weather-diagnostics-toolkit/examples/synthetic-weather-diagnostics-report.md", + "projects/python-weather-diagnostics-toolkit/PUBLICATION_BOUNDARIES.md", + "projects/python-weather-diagnostics-toolkit/SANITIZATION_REPORT.md", + }, } REQUIRED_TEXT = { @@ -56,10 +111,31 @@ "not current repository reputation", "It does not decide whether a dependency is safe.", ), + Path("projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md"): ( + "supporting scientific-data project inside `scientific-computing-toolkit`", + "not part of the `sbom-diff-and-risk` release surface", + "not a separate meteorology portfolio", + "This review does not require raw climate datasets.", + ), + Path("projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md"): ( + "supporting scientific-data project inside `scientific-computing-toolkit`", + "not part of the `sbom-diff-and-risk` release surface", + "not a separate meteorology portfolio", + "without requiring raw climate datasets or private local materials", + "does not claim causal attribution", + ), + Path("projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md"): ( + "supporting atmospheric diagnostics module", + "not part of the `sbom-diff-and-risk` release surface", + "not a separate meteorology portfolio", + "not a public redistribution of raw weather data or course material", + ), } REQUIRED_REVIEWER_PATHS = ( Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"), + Path("projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md"), + Path("projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md"), Path("projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md"), )