Atmospheric Science Research

Reference files — read on demand, not upfront:

File	Contents	When to read
plot-standards.md	Colormap tables, vector specs, projections, figure sizing, quick reject checklist	MUST read before writing ANY plot code
review.md	RR loop procedure, quick fix recipes, sanity checks	MUST read before starting ANY RR loop
readme-template.md	Chinese README template	MUST read after RR reaches PASS

Before Writing Code

MANDATORY — inspect inputs and directory structure BEFORE writing a single line of code. Shell probes ONLY — do NOT write Python preview scripts:

• NetCDF: ncdump -h file.nc
• GRIB: cdo sinfon file.grib

You MUST confirm: variables, dimensions, coordinates, units, time coverage, spatial region, and missing-data conventions. Writing code without this confirmation is FORBIDDEN — it leads to silent errors and wasted compute.

If multiple valid interpretations exist (e.g., "annual mean" could be calendar-year or DJF-anchored; "anomaly" needs a reference period), you MUST ask the user. NEVER silently pick one — wrong assumptions invalidate entire pipelines. When asking the user, it is best to provide them with multiple options.

Core Standards

ZERO TOLERANCE — violating ANY of these rules produces misleading or unpublishable output. Every rule below is a hard constraint, not a suggestion.

1. import cmaps + explicit levels — NO EXCEPTIONS. Domain-specific colormaps carry scientific meaning. NEVER use jet, rainbow, viridis, or any generic matplotlib colormap. These lack the perceptual structure needed for scientific communication and WILL be rejected.

2. NO full titles, NO stamps — EVER. NEVER call suptitle() or add source/data stamps to figures. Use ONLY ax.set_title("(a) Brief subtitle", loc="left") for panel labels — centered or descriptive-only titles are FORBIDDEN. A figure with a centered title or stamp is an immediate REVISE.

3. ALWAYS open and inspect the rendered PNG — NEVER review code alone. Code that looks correct can render with overlapping labels, clipped elements, or wrong colors. You MUST open the actual PNG with the Read tool in EVERY RR iteration. Skipping this step is the single most common source of defects.

4. Reuse existing project layout — do NOT reorganize. Existing directories reflect the user's decisions. ONLY create data_processed/ + figN/ when NO structure exists. Restructuring without explicit permission is FORBIDDEN.

5. Separate compute from plot — ALWAYS. Atmospheric computations (regridding, EOF, climatology) are expensive. NEVER mix compute and plot in the same script. Compute saves to disk; plot reads from disk. No exceptions.

6. NO environment setup — EVER. All packages are pre-installed. NEVER run pip install, conda install, import checks, or version probes. These waste time and clutter output.

Workflow

Understand the data FIRST (variables, dims, coords, units), THEN execute. Pick initial contour levels from domain knowledge — refine visually in RR, NEVER by profiling data ranges in code.

Execute

ALWAYS split into compute + plot — no monolithic scripts. Use subagents when available — agree on output path and variable names FIRST; plot waits if compute fails. Fix and re-run on failure; entering RR with broken outputs wastes iterations and is unacceptable.

Compute

• Save intermediates to data_processed/*.nc — MUST include units and long_name attributes. Missing attributes = incomplete output.
• Use fast tools — Use faster, more efficient Python packages such as cdo, along with optimized algorithms like vectorized operations. Avoid slow loops and inefficient methods.
• Memory & dask — MANDATORY rules:
  • ALWAYS open data with dask backing: xr.open_dataset(..., chunks="auto") / xr.open_mfdataset(..., chunks="auto"). NEVER omit chunks — loading entire datasets into RAM causes OOM on large reanalysis/model outputs.
  • NEVER rechunk. Do NOT call .rechunk() — it is expensive, triggers unnecessary data movement, and chunks="auto" already produces optimal chunk sizes for most workflows.
  • Lazy first, compute late. Build the full computation graph (selections, arithmetic, reductions) BEFORE calling .compute() or .load(). NEVER insert .load() / .compute() / .values mid-pipeline — each one forces full materialization and defeats dask's lazy evaluation.
  • NEVER use .values. It forces the entire dask array into RAM as a NumPy array, causing OOM. Use .item() for scalars, .to_numpy() on tiny already-reduced results only if absolutely necessary, or keep data as xarray/dask objects throughout.
  • Save with dask: use ds.to_netcdf(..., compute=True) — dask writes chunks sequentially without loading everything into RAM.
  • Close datasets: call ds.close() after processing is complete, or use with xr.open_dataset(...) as ds: context managers. Unclosed file handles leak memory across long scripts.
  • gc.collect() after large intermediate drops: if you delete a large intermediate variable (del big_array), follow with gc.collect() to actually release the memory.

Plot — MUST read plot-standards.md first

Read from saved intermediates, NEVER from raw data. Detailed specs (panel labels, colorbar, vectors, stippling, borders, export) are in plot-standards.md — do NOT duplicate here.

• Colormap: import cmaps + discrete levels. Absolute fields → sequential; anomaly/difference → diverging, symmetric, center 0. Comparable panels MUST share colormap and level range — mismatched scales between panels is an immediate REVISE.

  Quick lookup (full table in plot-standards.md):

  Variable	Absolute	Anomaly / Difference
  Temperature	temp_19lev, hotcolr_19lev	temp_diff_18lev, BlueWhiteOrangeRed
  Precipitation	precip_11lev, precip3_16lev	precip_diff_12lev, CBR_drywet
  SST	temp_19lev, cmocean_thermal	GHRSST_anomaly, MPL_sstanom
  Geopotential	BlAqGrYeOrRe, BlAqGrYeOrReVi200	—
  SLP	MPL_YlOrRd, BlAqGrYeOrRe	—
  Generic	BlAqGrYeOrReVi200, MPL_YlOrRd	BlueWhiteOrangeRed, BlWhRe

• Tibetan Plateau masking: For ≤ 850 hPa low-level fields (wind, geopotential height, etc.) whose domain covers the Tibetan Plateau, MUST mask Tibet with grey fill (facecolor="lightgrey") using ~/code/data/map/Tibet/Tibet.shp. Apply automatically — do NOT ask the user. See plot-standards.md § "Tibetan Plateau Masking".

• Layout code is NEVER correct on first render — figsize, subplot arrangement, colorbar size, and element positions are starting-point guesses. You MUST verify proportions in the rendered PNG and refine iteratively in RR. See "Layout Anti-patterns" in plot-standards.md.

Patch (figure-only fix)

1. Read existing code. Identify the MINIMUM change needed — nothing more.
2. Patch ONLY affected code — NO directory restructuring, NO compute rewrite.
3. Re-render affected figures ONLY.

RR — Review & Revision Loop

MANDATORY: Load review.md and plot-standards.md BEFORE starting. Follow EVERY check listed there — skipping any check is FORBIDDEN.

Loop until PASS or BLOCKED. Max 10 iterations per figure. NEVER declare PASS without opening and inspecting the PNG.

Each iteration — this sequence is MANDATORY, do NOT skip or reorder:

1. Open PNG with Read tool
2. Check layout proportions FIRST (colorbar sizing, element crowding, subplot spacing)
3. Check against Core Standards + quick reject checklist — every item
4. Verify physical plausibility (values, units, sign conventions, spatial patterns)
5. Classify: REVISE / BLOCKED / PASS

Same defect after 2 fixes → STOP patching. Recheck data, coords, units, dtypes from scratch — the root cause is upstream.

Layout parameters in code are NEVER correct on first render — the rendered PNG is the ONLY ground truth. NEVER trust code-level parameters over what you see in the image.

Documentation — ONLY after RR reaches PASS

MUST load readme-template.md first. Write or update a Chinese README.md:

• New project → full README.
• Later modifications → append to「版本更新」, update affected sections ONLY.

ONLY produce README.md — creating any other documentation file is FORBIDDEN.

Data Handling — Common Traps

These are NOT optional checks — each one has caused silent data corruption in real projects:

• Missing values: ALWAYS verify NaN handling (skipna=True or nanmean). Unhandled NaN = wrong results.
• Multi-file datasets: MUST verify time continuity and variable consistency BEFORE merging. NEVER blindly concatenate. Use xr.open_mfdataset(..., chunks="auto") — NEVER chunks omitted.
• Pressure-level data: MUST check vertical coordinate ordering (ascending vs descending). Wrong ordering = inverted profiles.
• Memory overflow: NEVER load full datasets without chunks="auto". NEVER use .values — it forces full materialization. Do NOT rechunk. Build lazy computation graphs first, .compute() only at the end.
• Existing code: ALWAYS preserve original style when modifying. Do NOT refactor code you did not write.
• Web search: use ONLY after local docs and domain knowledge fail — not as a first resort.