bioepic-data/ecosim-agent / .agents/skills/ecosim-plant-trait-sanity-check
ecosim-plant-trait-sanity-check
VerifiedRead-only validation of EcoSIM plant_trait.*.desc values for the first grid, including all plant-class identities and their evidence coverage, C3/C4 physiology, active protein allocation and root hydraulics. Use for trait evaluation and run-readiness checks. Never edit or replace the `.desc` file.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.7 KB |
| agents/openai.yaml | config | 314 B |
| references/class_information_validation.md | markdown | 7.3 KB |
| references/evidence_coverage.md | markdown | 4.5 KB |
| references/pft_case_notes.md | markdown | 5.6 KB |
| references/sanity_rules.md | markdown | 23.6 KB |
| references/web_evidence.md | markdown | 11.0 KB |
| scripts/check_plant_trait_desc.py | script | 72.5 KB |
| scripts/plant_class_validation.py | script | 13.5 KB |
| scripts/site_vegetation.py | script | 18.2 KB |
| scripts/trait_corrections.py | script | 10.5 KB |
| tests/test_annual_phenology.py | script | 2.2 KB |
| tests/test_class_information.py | script | 9.5 KB |
| tests/test_physiological_parameterization.py | script | 12.9 KB |
| tests/test_root_conduit_hydraulics.py | script | 8.7 KB |
| tests/test_site_vegetation.py | script | 5.4 KB |
| tests/test_soybean_angle_default.py | script | 1.8 KB |
| tests/test_trait_corrections.py | script | 7.0 KB |
scripts/trait_corrections.py
View on GitHub#!/usr/bin/env python3
"""Plan and apply literature-backed corrections for plant-trait sanity-check findings.
Corrections are written to a PFT-parameter NetCDF through ParEditor
(ecosim-pftpar-editor); plant_trait.*.desc files are never edited.
Severe findings are every ERROR, every value outside a web-evidence range, and
every categorical identity mismatch. The model-formulation-sensitive Jmax:Vcmax
diagnostic and other warnings are reported, not corrected.
Every numeric correction comes from a literature range in the web-evidence JSON
(``numeric_ranges``, plus ``derived_ranges`` for constraints such as Rubisco
specificity that combine several parameters); the range's source, URL,
evidence level, and conversion note are copied into the correction record.
A severe finding without such a range is left unresolved rather than given an
invented value. Rules:
- SLA1: 0.25 x the typical value (midpoint of the literature range).
- Other numeric parameters: the midpoint ("medium value") of the literature range.
- Rubisco kinetics (VCMX/VOMX/XKCO2/XKO2): keep VCMX, XKCO2, and XKO2 and set
VOMX so VCMX*XKO2/(VOMX*XKCO2) equals the midpoint of the literature
RUBISCO_SPECIFICITY range.
- Categorical identity (IEBTYP, ISNTYP, ...): the EcoSIM enum code the checker
expects (ElmIDMod), with the categorical web evidence as supporting source.
- CHL for C3 trees without a literature range: the user default 0.12, recorded
as evidence level "user-default" (C3 Jmax scales with ETMX*CHL, so the
resulting protein-normalized Jmax:Vcmax is recorded too).
"""
from __future__ import annotations
import contextlib
import os
import re
import sys
from pathlib import Path
from typing import Any, Dict, Iterator, List, Optional, Tuple
SLA_TYPICAL_FRACTION = 0.25
RULE_TOLERANCE = 0.01
SPECIFICITY_KEY = "RUBISCO_SPECIFICITY"
RUBISCO_PARAMETER = "VCMX/VOMX/XKCO2/XKO2"
# User rule (2026-10-12): C3 trees without a usable literature CHL get CHL = 0.12.
C3_TREE_PFTS = ("ndlf", "ndld", "bdlf", "bdln", "bdlw", "bspr", "dfir", "jpin", "lpin", "tasp", "woak")
C3_TREE_CHL_DEFAULT = 0.12
IC3_PHOTO = 3 # ElmIDMod ic3_photo
EXPECTED_CODE = re.compile(r"is expected to use .*\((\d+)\); found")
PROJECT_ROOT = Path(__file__).resolve().parents[4]
def is_c3_tree(pft: str, values: Dict[str, float]) -> bool:
ictyp = values.get("ICTYP")
return pft[:4] in C3_TREE_PFTS and ictyp is not None and int(round(ictyp)) == IC3_PHOTO
def jmax_to_vcmax(values: Dict[str, float], chl: float) -> Optional[float]:
"""Protein-normalized C3 Jmax:Vcmax, ETMX*CHL/(3.5*VCMX*RUBP), as in StomatesMod.F90."""
if all(values.get(k) for k in ("ETMX", "VCMX", "RUBP")):
return values["ETMX"] * chl / (3.5 * values["VCMX"] * values["RUBP"])
return None
def is_severe(finding: Dict[str, Any]) -> bool:
message = finding.get("message", "")
if finding.get("severity") == "ERROR":
return True
return (
"outside web-evidence range" in message
or EXPECTED_CODE.search(message) is not None
or "does not contain web-evidence expectation" in message
)
def plant_evidence(evidence: Dict[str, Any], pft: str) -> Dict[str, Any]:
for plant in evidence.get("plants", []):
if plant.get("pft_code") == pft:
return plant
return {}
def literature_ranges(plant: Dict[str, Any]) -> Dict[str, Dict[str, Any]]:
ranges = {}
for key in ("numeric_ranges", "derived_ranges"):
for entry in plant.get(key, []):
ranges[entry["variable"]] = entry
return ranges
def literature_target(variable: str, entry: Dict[str, Any]) -> Tuple[float, str]:
typical = (float(entry["min"]) + float(entry["max"])) / 2.0
if variable == "SLA1":
return SLA_TYPICAL_FRACTION * typical, f"{SLA_TYPICAL_FRACTION} x typical {typical:.4g} (literature midpoint)"
return typical, f"midpoint of literature range [{entry['min']}, {entry['max']}]"
def citation(entry: Optional[Dict[str, Any]]) -> Dict[str, Any]:
if not entry:
return {}
keys = ("source", "url", "evidence_level", "conversion_note", "unit")
return {key: entry[key] for key in keys if key in entry}
def plan_corrections(
report: Dict[str, Any], evidence: Dict[str, Any], current: Dict[str, Dict[str, float]]
) -> Dict[str, Any]:
"""Return {corrections, unresolved, satisfied_by_rule} for the report's findings.
``current`` maps pft code -> {parameter: current value in the PFT file}.
"""
corrections: Dict[Tuple[str, str], Dict[str, Any]] = {}
unresolved: List[Dict[str, Any]] = []
satisfied: List[Dict[str, Any]] = []
severe = [f for f in report.get("findings", []) if is_severe(f)]
# Categorical codes first, so web-evidence label mismatches they resolve are not unresolved.
for finding in severe:
match = EXPECTED_CODE.search(finding["message"])
if not match:
continue
pft, variable = finding["pft_code"], finding["parameter"]
categorical = next(
(c for c in plant_evidence(evidence, pft).get("categorical_expectations", []) if c["variable"] == variable),
None,
)
corrections[(pft, variable)] = {
"pft": pft, "variable": variable, "old": current.get(pft, {}).get(variable), "new": int(match.group(1)),
"rule": "EcoSIM enum code expected by the checker (ElmIDMod)",
"evidence": citation(categorical) or {"source": "ElmIDMod enum via plant-trait checker"},
}
for finding in severe:
pft, variable, message = finding["pft_code"], finding["parameter"], finding["message"]
values = current.get(pft, {})
ranges = literature_ranges(plant_evidence(evidence, pft))
if EXPECTED_CODE.search(message):
continue
if "does not contain web-evidence expectation" in message:
if (pft, variable) not in corrections:
unresolved.append({"finding": message, "pft": pft, "variable": variable,
"reason": "no EcoSIM enum code identified for this category"})
continue
if variable == RUBISCO_PARAMETER:
entry = ranges.get(SPECIFICITY_KEY)
if entry is None:
unresolved.append({"finding": message, "pft": pft, "variable": variable,
"reason": f"no literature {SPECIFICITY_KEY} range in web evidence"})
continue
if not all(key in values for key in ("VCMX", "XKO2", "XKCO2")):
unresolved.append({"finding": message, "pft": pft, "variable": variable,
"reason": "VCMX, XKO2, or XKCO2 not readable from the PFT parameter file"})
continue
target, rule = literature_target(SPECIFICITY_KEY, entry)
vomx = values["VCMX"] * values["XKO2"] / (target * values["XKCO2"])
corrections[(pft, "VOMX")] = {
"pft": pft, "variable": "VOMX", "old": values.get("VOMX"), "new": vomx,
"rule": f"VOMX so VCMX*XKO2/(VOMX*XKCO2) = {target:.4g} ({rule}); VCMX, XKCO2, XKO2 kept",
"evidence": citation(entry),
}
continue
entry = ranges.get(variable)
if entry is None and variable == "CHL" and is_c3_tree(pft, values):
ratio_old = jmax_to_vcmax(values, values["CHL"]) if values.get("CHL") else None
ratio_new = jmax_to_vcmax(values, C3_TREE_CHL_DEFAULT)
corrections[(pft, "CHL")] = {
"pft": pft, "variable": "CHL", "old": values.get("CHL"), "new": C3_TREE_CHL_DEFAULT,
"rule": "user default for C3 trees without a usable literature value"
+ (f"; Jmax:Vcmax {ratio_old:.2f} -> {ratio_new:.2f} (ETMX unchanged)"
if ratio_old is not None and ratio_new is not None else ""),
"evidence": {"source": "user default (2026-10-12): C3 trees use CHL = 0.12 when the literature search "
"finds no usable light-harvesting fraction; not literature-backed",
"evidence_level": "user-default"},
}
continue
if entry is None:
unresolved.append({"finding": message, "pft": pft, "variable": variable,
"reason": "no literature-backed range for this parameter in web evidence"})
continue
target, rule = literature_target(variable, entry)
old = values.get(variable)
if variable == "SLA1" and old is not None and abs(old - target) <= RULE_TOLERANCE * target:
satisfied.append({"pft": pft, "variable": variable, "value": old, "rule": rule})
continue
corrections[(pft, variable)] = {
"pft": pft, "variable": variable, "old": old, "new": target, "rule": rule, "evidence": citation(entry),
}
return {"corrections": list(corrections.values()), "unresolved": unresolved, "satisfied_by_rule": satisfied}
def read_pft_values(pftpar_file: Path, pft: str, variables: List[str]) -> Dict[str, float]:
from netCDF4 import Dataset
with Dataset(str(pftpar_file)) as dataset:
codes = ["".join(c.decode() if isinstance(c, bytes) else c for c in row).strip()
for row in dataset.variables["pfts"][:].filled(b" ")]
index = codes.index(pft)
return {v: float(dataset.variables[v][index]) for v in variables if v in dataset.variables}
@contextlib.contextmanager
def working_directory(path: Path) -> Iterator[None]:
previous = os.getcwd()
os.chdir(path)
try:
yield
finally:
os.chdir(previous)
def apply_corrections(pftpar_file: Path, corrections: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""Write corrections with ParEditor (its JSONL change log lands beside the file) and read them back."""
sys.path.insert(0, str(PROJECT_ROOT / "applications" / "notebooks"))
from scripts.ParamEditor import ParEditor
pftpar_file = Path(pftpar_file).resolve()
by_pft: Dict[str, Dict[str, Any]] = {}
for item in corrections:
by_pft.setdefault(item["pft"], {})[item["variable"]] = item["new"]
with working_directory(pftpar_file.parent), contextlib.redirect_stdout(open(os.devnull, "w")):
editor = ParEditor(pftparfile=str(pftpar_file))
for pft, pars in by_pft.items():
editor.PlantParamModify(pft, pars, iscale=False, verbose=False)
applied = []
for item in corrections:
readback = read_pft_values(pftpar_file, item["pft"], [item["variable"]]).get(item["variable"])
applied.append({**item, "readback": readback})
return applied
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |