[codex] Add precipitation anomaly diagnostics lab

.github/dependabot.yml

@@ -8,6 +8,11 @@ updates:
       - "examples/**"
       - "tests/fixtures/**"
 
+  - package-ecosystem: "pip"
+    directory: "/projects/precipitation-anomaly-diagnostics"
+    schedule:
+      interval: "weekly"
+
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/precipitation-anomaly-diagnostics-ci.yml

@@ -0,0 +1,53 @@
+name: precipitation-anomaly-diagnostics-ci
+run-name: precipitation anomaly diagnostics ci / ${{ github.event_name }} / ${{ github.ref_name }}
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - ".github/workflows/precipitation-anomaly-diagnostics-ci.yml"
+      - "projects/precipitation-anomaly-diagnostics/**"
+  pull_request:
+    paths:
+      - ".github/workflows/precipitation-anomaly-diagnostics-ci.yml"
+      - "projects/precipitation-anomaly-diagnostics/**"
+
+permissions: {}
+
+env:
+  PRECIPITATION_DIAGNOSTICS_PYTHON_VERSION: "3.11"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: projects/precipitation-anomaly-diagnostics
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PRECIPITATION_DIAGNOSTICS_PYTHON_VERSION }}
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install project
+        run: python -m pip install -e .[dev]
+
+      - name: Run tests
+        run: python -m pytest
+
+      - name: Compile modules and scripts
+        run: python -m compileall src scripts
+
+      - name: CLI help smoke tests
+        run: |
+          python scripts/run_preprocessing.py --help
+          python scripts/run_eof_analysis.py --help
+          python scripts/run_composite_analysis.py --help

README.md

@@ -13,9 +13,17 @@ can optionally record PyPI provenance and OpenSSF Scorecard evidence.
 
 For a fast reviewer overview, start with the [`sbom-diff-and-risk` reviewer
 brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md).
-
-## Why This Repository Exists
-
+
+## Additional Project
+
+[`projects/precipitation-anomaly-diagnostics`](projects/precipitation-anomaly-diagnostics/README.md)
+is a public-safe climate diagnostics mini-lab. It demonstrates a reproducible
+workflow for precipitation anomaly preprocessing, EOF analysis, representative
+year selection, circulation composites, and reviewer-friendly scientific
+interpretation.
+
+## Why This Repository Exists
+
 Scientific and security-oriented engineering often needs small, inspectable
 tools that make evidence easier to review. This repository collects projects
 that emphasize:
@@ -39,13 +47,31 @@ Deterministic SBOM/dependency diffing, JSON/Markdown/SARIF output, local policy
 checks, policy decision explainability, optional provenance and Scorecard
 evidence.
 
-Useful entry points:
-
+Useful entry points:
+
 - [`sbom-diff-and-risk` README](tools/sbom-diff-and-risk/README.md)
 - [Reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md)
 - [Reviewer evidence pack](tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md)
 - [v0.9.0 release notes][release-notes-v090]
 - [Examples](tools/sbom-diff-and-risk/examples/)
+
+Project:
+[`precipitation-anomaly-diagnostics`](projects/precipitation-anomaly-diagnostics/README.md)
+
+Status:
+Public-safe mini-lab.
+
+What to review:
+Sanitized climate-diagnostics workflow, small derived example artifacts,
+methodology notes, data policy, and synthetic-data tests.
+
+Useful entry points:
+
+- [`precipitation-anomaly-diagnostics` README](projects/precipitation-anomaly-diagnostics/README.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)
+- [Example report](projects/precipitation-anomaly-diagnostics/reports/example-report.md)
 
 ## Verification and Release Evidence
 

projects/precipitation-anomaly-diagnostics/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local configs and outputs
+configs/local*.yaml
+data/
+raw/
+intermediate/
+outputs/
+tmp/
+scratch/
+
+# Large climate data
+*.nc
+*.nc4
+*.grib
+*.grb
+*.hdf
+*.h5
+*.zarr/
+
+# Private / course artifacts
+*.doc
+*.docx
+*.ppt
+*.pptx
+*.pdf
+*.rar
+*.zip
+*.7z
+
+# Secrets and local environment
+.env
+.env.*
+*.key
+*.pem
+*.p12
+*token*
+*secret*
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

projects/precipitation-anomaly-diagnostics/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stacknil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

projects/precipitation-anomaly-diagnostics/README.md

@@ -0,0 +1,119 @@
+# Precipitation Anomaly Diagnostics Lab
+
+A compact scientific-computing workflow for July precipitation anomaly diagnostics over eastern China.
+
+This mini-lab demonstrates how to turn gridded precipitation and atmospheric circulation fields into reproducible climate diagnostics:
+
+- preprocess monthly precipitation and circulation fields;
+- compute climatology, anomalies, and standardized anomaly indices;
+- apply EOF analysis to identify dominant spatial modes;
+- select representative years from standardized principal components;
+- run circulation composite analysis for positive and negative phases;
+- generate reviewable figures and lightweight Markdown reports.
+
+The repository is designed as a reproducible research mini-lab, not as an operational forecast system.
+
+## Repository Layout
+
+```text
+.
+├─ assets/sanitized-figures/       # derived, metadata-stripped demonstration figures
+├─ configs/example.yaml            # placeholder local data paths and analysis settings
+├─ docs/
+│  ├─ data-policy.md
+│  ├─ inference-framework.md
+│  ├─ methodology.md
+│  └─ reproducibility.md
+├─ examples/
+│  ├─ regional_precipitation_summary_1961_2022.csv
+│  └─ sample_metadata.json
+├─ reports/example-report.md
+├─ scripts/
+│  ├─ run_composite_analysis.py
+│  ├─ run_eof_analysis.py
+│  └─ run_preprocessing.py
+└─ src/climate_diagnostics/
+   ├─ composite.py
+   ├─ config.py
+   ├─ eof.py
+   ├─ plotting.py
+   └─ preprocess.py
+```
+
+## Installation
+
+Use Python 3.10+.
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+```
+
+On Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .
+```
+
+Optional plotting dependencies such as `cartopy` may require platform-specific geospatial libraries. The core numerical workflow uses `numpy`, `pandas`, `xarray`, `scipy`, `matplotlib`, and `pyyaml`.
+
+## Expected Inputs
+
+This repository does not redistribute raw climate datasets. Users should obtain datasets from their original providers and configure local paths in `configs/example.yaml`.
+
+Typical inputs:
+
+- monthly precipitation fields with `time`, `lat`, and `lon` dimensions;
+- atmospheric circulation fields such as `uwnd`, `vwnd`, `hgt`, and `omega`;
+- a target month, region bounds, and reference climatology period.
+
+## Example Usage
+
+```bash
+python scripts/run_preprocessing.py --config configs/example.yaml
+python scripts/run_eof_analysis.py --config configs/example.yaml
+python scripts/run_composite_analysis.py --config configs/example.yaml
+```
+
+The example CSV under `examples/` is a small derived summary table for demonstration only. It is not a raw dataset.
+
+## Demonstration Figures
+
+The `assets/sanitized-figures/` directory contains derived figures suitable for a public project page:
+
+- regional precipitation time series;
+- decadal precipitation and category counts;
+- EOF spatial regression modes;
+- Monte Carlo variance screening;
+- standardized EOF1 principal component;
+- circulation climatology and phase-composite panels.
+
+## Diagnostic Inference
+
+The public version keeps a small amount of scientific interpretation while avoiding institutional or personal context. The key inference pattern is:
+
+```text
+climatology -> anomaly field -> EOF modes -> screened signals -> representative years -> circulation composites -> mechanism hypothesis
+```
+
+The main methodological takeaway is that EOF modes should be treated as diagnostic coordinates, not as final explanations. Physical interpretation is added only after checking variance contribution, Monte Carlo screening, representative-year behavior, and vertically coherent circulation composites.
+
+See `docs/inference-framework.md` for the reusable reasoning framework.
+
+## Limitations
+
+- EOF signs are arbitrary. This project normalizes the first EOF mode so that positive PC values correspond to positive regional precipitation anomalies.
+- Representative-year thresholds are configurable and should be treated as analysis choices, not universal physical constants.
+- Composite diagnostics are descriptive and should be interpreted with physical context and uncertainty checks.
+- The repository does not include raw climate data and cannot be fully reproduced until users provide compatible local datasets.
+
+## Data Policy
+
+Raw gridded climate datasets can be large and may have separate access policies. This repository does not redistribute CN05.1, NCEP/NCAR Reanalysis, or any other raw third-party climate dataset. See `docs/data-policy.md`.
+
+## Public-Safe Scope
+
+This public version is framed as a neutral scientific-computing project. It excludes course documents, institutional templates, personal identifiers, local-machine paths, and raw restricted datasets.

projects/precipitation-anomaly-diagnostics/SANITIZATION_REPORT.md

@@ -0,0 +1,46 @@
+# Sanitization Report
+
+This working-tree report records how the public-safe export was prepared.
+
+## Files Inspected
+
+- root-level source materials;
+- generated figures;
+- generated reports;
+- compressed data and analysis artifacts;
+- public export tree.
+
+## Identifiers Removed or Excluded
+
+- personal names and student identifiers;
+- institution, college, course, and classroom context;
+- team-member and instructor references;
+- local Windows and cloud-sync paths;
+- course templates, slides, and word-processing reports;
+- raw compressed data archives and large climate datasets.
+
+## Public Assets Kept
+
+- reusable Python source modules;
+- neutral documentation;
+- placeholder configuration;
+- small derived CSV summary;
+- derived demonstration figures with neutral filenames.
+
+## Raw Files Excluded
+
+- raw or packaged climate datasets;
+- original course PDFs;
+- original presentation decks;
+- original word-processing reports;
+- compressed working archives.
+
+## Remaining Assumptions
+
+- Included figures are derived scientific outputs and do not contain personal or institutional branding.
+- The public repository should be created from this sanitized export directory, not from the original working folder.
+- Git history should be clean because the export directory is separate from the original materials.
+
+## Recommended Review Path
+
+Publish or review this project from the sanitized subproject directory only. Do not publish the original working directory or raw source materials.

projects/precipitation-anomaly-diagnostics/configs/example.yaml

@@ -0,0 +1,32 @@
+project:
+  name: precipitation-anomaly-diagnostics
+
+paths:
+  precipitation_file: /path/to/monthly_precipitation.nc
+  circulation_dir: /path/to/reanalysis_fields/
+  output_dir: outputs/
+
+variables:
+  precipitation: pre
+  u_wind: uwnd
+  v_wind: vwnd
+  geopotential_height: hgt
+  omega: omega
+
+analysis:
+  month: 7
+  climatology_period: [1961, 2022]
+  region:
+    lon_min: 105.0
+    lon_max: 140.25
+    lat_min: 14.75
+    lat_max: 42.5
+  eof:
+    n_modes: 10
+    typical_year_threshold: 0.9
+    monte_carlo_iterations: 1000
+    monte_carlo_quantile: 0.95
+    random_seed: 2026
+
+notes:
+  raw_data_policy: Raw datasets must be obtained from original providers and are not redistributed by this repository.