bioepic-data/ecosim-agent / .agents/skills/ecosim-pftpar-editor
ecosim-pftpar-editor
VerifiedEdit EcoSIM PFT-parameter NetCDF files such as ecosim_pftpar_20260303.nc with the ParEditor class from applications/notebooks/scripts/ParamEditor.py. Use when asked to modify, scale, copy, compare, or delete PFT parameter records for a plant functional type (six-character pfts code such as gr3s43 or ndlf34), update microbe parameter NetCDF values, or maintain the JSONL change log that records past parameter changes. Never modify plant_trait.*.desc files; they are read-only references.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.6 KB |
SKILL.md
View on GitHub---
name: ecosim-pftpar-editor
description: Edit EcoSIM PFT-parameter NetCDF files such as ecosim_pftpar_20260303.nc with the ParEditor class from applications/notebooks/scripts/ParamEditor.py. Use when asked to modify, scale, copy, compare, or delete PFT parameter records for a plant functional type (six-character pfts code such as gr3s43 or ndlf34), update microbe parameter NetCDF values, or maintain the JSONL change log that records past parameter changes. Never modify plant_trait.*.desc files; they are read-only references.
---
# EcoSIM PFT Parameter Editor (ParamEditor.py)
Use this skill to edit EcoSIM `ecosim_pftpar_*.nc` PFT-parameter NetCDF files
with the bundled `ParEditor` class. The canonical tool is
`applications/notebooks/scripts/ParamEditor.py`; treat it as the source of
truth. Do not reimplement NetCDF editing when this skill applies.
## File boundary
Treat every `plant_trait.*.desc` file as read-only, including when the request is
phrased as editing plant trait parameters. Use a `.desc` file only for inspection
or validation. Apply requested parameter changes to the corresponding
`ecosim_pftpar_*.nc` file with `ParamEditor.py`. Never patch, overwrite, or emit a
replacement `.desc` file.
## Locate the target file
1. PFT-parameter NetCDF files usually live in EcoSIM run folders, for example
`~/work/github/ecosim_workspace/<case>/input_data/ecosim_pftpar_YYYYMMDD.nc`.
Search the user-supplied run folder first, then `ecosim_workspace/*/input_data/`,
then the repository (`data/`, `templates/`).
2. If the user gives only a date such as `20260303`, match
`ecosim_pftpar_<date>.nc`. If several run folders contain it, ask which case
to edit, or edit all cases only when explicitly requested.
3. Templates exist as `.cdl` text; do not edit `.cdl` files with this skill.
## Environment and import pattern
Use the repository NetCDF-capable environment and import `ParamEditor` as a
package module (it does `from . import stringTools` internally, so it must be
imported as `scripts.ParamEditor` with `applications/notebooks` on `sys.path`):
```python
# run with .venv-cmip6/bin/python from the repo root, or set cwd accordingly
import sys
sys.path.insert(0, 'applications/notebooks')
from scripts.ParamEditor import ParEditor
```
If `.venv-cmip6/bin/python` is unavailable, use any Python that can
`import netCDF4`.
## Core API
| Method | Purpose |
| --- | --- |
| `ParEditor(pftparfile=path)` | Bind the editor to a PFT-parameter file. Optional `micparfile=` binds a microbe-parameter file. The change-log stem is the first dot-token of the file basename (for `ecosim_pftpar_20260303.nc` it is `ecosim_pftpar_20260303`); records are appended to `<stem>.jsonl` **in the current working directory**. |
| `reset(sure=True)` | Delete the recorded `.jsonl` change-log files. Call only when the user wants to clear history. |
| `PlantParamModify(pft, pars, iscale=False, verbose=True)` | Set parameters for one PFT. `pars` is a dict `{varname: value}` using exact NetCDF variable names such as `VCMX`, `ETMX`, `RRAD1M`. With `iscale=False` the value replaces the current value; with `iscale=True` the value multiplies the current value (a factor of 1.0 leaves it unchanged). |
| `CopyPlantPft(pft_from, pft_to)` | Copy all parameters from one PFT to another. If `pft_to` does not exist it is appended to the unlimited `npfts` dimension as a new record. |
| `PlantParCompare(pft1, pft2)` | Print parameters that differ between two PFTs. Use before copying to confirm the archetype. |
| `delete_pft_records(input_file, output_file, names_to_delete)` | Write a **new** NetCDF with the listed `pfts` codes removed; the input file is not modified. |
| `MicrobeParamModify(pars, iscale=False, verbose=True)` | Modify variables in the microbe-parameter file for all records (`variable[:]`). |
## Workflow
For a run/check/correct loop on an existing case, use
[ecosim-trait-correction-short-run](../ecosim-trait-correction-short-run/SKILL.md).
It defaults to five-day simulations and validates model-generated trait output.
1. List available PFT codes and locate the record before editing:
```python
from netCDF4 import Dataset
def pft_codes(pftparfile):
with Dataset(pftparfile) as nc:
return ["".join(c.decode('utf-8') if isinstance(c, bytes) else c
for c in row).strip()
for row in nc.variables['pfts'][:].filled(" ")]
print(pft_codes(pftparfile))
```
Use the exact six-character code. If the user names a plant, map it to a
`pfts` code and confirm the match (for example, ponderosa pine as `ndlf34`).
2. Back up before any in-place edit, because `PlantParamModify` and
`CopyPlantPft` open the file in `r+` mode and save immediately:
```bash
mkdir -p result/pftpar_editor
cp /path/to/ecosim_pftpar_20260303.nc result/pftpar_editor/ecosim_pftpar_20260303_backup_$(date +%Y%m%d_%H%M%S).nc
```
3. Read the pre-edit values, apply changes, and read back the post-edit values
in one session:
```python
from netCDF4 import Dataset
parEditor = ParEditor(pftparfile=pftparfile)
pft = 'ndlf34'
def pft_index(pftparfile, pft):
with Dataset(pftparfile) as nc:
codes = ["".join(c.decode('utf-8') if isinstance(c, bytes) else c
for c in row).strip()
for row in nc.variables['pfts'][:].filled(" ")]
return codes.index(pft)
def show(names):
with Dataset(pftparfile) as nc:
i = pft_index(pftparfile, pft)
for n in names:
print(n, nc.variables[n][i])
show(['VCMX', 'ETMX', 'RSRR']) # before
# absolute replacement
parEditor.PlantParamModify(pft, {'VCMX': 35.0, 'ETMX': 500.0}, iscale=False, verbose=True)
# multiplicative scaling (factor)
parEditor.PlantParamModify(pft, {'RSRR': 1.10}, iscale=True, verbose=True)
show(['VCMX', 'ETMX', 'RSRR']) # after
```
4. To create a new PFT from an archetype, compare first, then copy and adjust:
```python
parEditor.PlantParCompare('ndlf34', 'ndlf32')
parEditor.CopyPlantPft('ndlf34', 'ndlf36')
parEditor.PlantParamModify('ndlf36', {'VCMX': 40.0}, verbose=True)
```
5. To remove PFTs, always write to a new file (default under `result/`), never
overwrite the run-folder input in place:
```python
parEditor.delete_pft_records(input_file, 'result/pftpar_editor/ecosim_pftpar_pruned.nc',
['gr3s32', 'maiz31'])
```
6. Verify and report:
- Re-open the file and print the edited variables for the target PFT.
- Report the change-log path (for example `./ecosim_pftpar_20260303.jsonl`
in the working directory) and its latest records.
- Report the backup file path under `result/pftpar_editor/`.
- Warn that other run folders keep their own copy of
`ecosim_pftpar_<date>.nc`; propagate the same edit to other cases only on
request.
## Contract and cautions
- Never fabricate variable names: read them from the file first. A wrong name
raises `KeyError` from `nc_file.variables[parnm]`; stop and list the
available variables instead of guessing.
- `PlantParamModify` writes values with broadcasting; scalars are safe for
`npfts`-leading variables.
- The `pfts` variable is a character array `(npfts, nchars1=10)`; strip
padding when matching codes.
- Keep the JSONL change log; it is the audit trail of every modify call
(`{'pft':..., 'parvarnames':[...], 'parvals':[...]}`).
- Only call `reset()` when the user explicitly asks to clear history, because
it deletes the `.jsonl` files.
- Do not use regex or text editing on NetCDF; edit variables directly through
`netCDF4` as ParamEditor.py does.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |