Document config fields and benchmark customization (review feedback for #4038)

Add inline documentation to pecan_ilamb.cfg explaining every confrontation
field (variable, weight at both levels, mass_weighting, skip flags, units),
and a Customizing the benchmark section to the README covering how to update
or add models, add benchmark datasets, and adjust scoring weights. Addresses
review feedback on the PR.

Author: Tejas7007

modules/benchmark/inst/ilamb/README.md

@@ -254,3 +254,45 @@ figure.
 - TRENDY: Global Carbon Budget 2024, public download index.
 - Benchmarks: Xu & Saatchi 2021 (biomass), GIMMS LAI4g (leaf area index),
   HWSD2 (soil carbon).
+
+## Customizing the benchmark
+
+The benchmark is designed to stay usable as models and datasets evolve. Three
+common changes: updating or adding models, adding benchmark datasets, and
+adjusting the scoring weights. The per-field meaning of every configuration
+option is documented inline in `pecan_ilamb.cfg`.
+
+### Updating or adding a model
+
+Each model is just a directory under the model root (for example
+`ilamb_models_2012_2014/`), containing `cVeg.nc`, `cSoil.nc`, and `lai.nc` on
+the analysis grid. ILAMB scores every model directory it finds there, so:
+
+- To add a model, place its directory (with the three variable files, regridded
+  to the analysis grid) under the model root and re-run `ilamb-run`.
+- To update a model to a newer version (for example a new CMIP6 or TRENDY
+  release), regenerate its files with the relevant build script and overwrite
+  that model's directory. The build scripts take the source and output paths as
+  arguments, so pointing them at a new data release does not require code edits.
+
+The ensemble means (CMIP6, TRENDY, PEcAn) are rebuilt from the individual
+members by `build_window_ensembles.py`, so re-run it after changing the set of
+member models so the means reflect the new set.
+
+### Adding a benchmark dataset
+
+Benchmarks are defined in `pecan_ilamb.cfg`. To add one for an existing
+variable, copy the dataset block under the relevant `[h2: ...]` variable, rename
+it, and point its `source` at the new benchmark netCDF (placed under
+`ILAMB_ROOT/DATA/...`). When more than one benchmark is listed under a variable,
+their `weight` values set how they combine. To score a new variable entirely,
+add a new `[h2: ...]` block and make sure the model files contain that variable.
+
+### Adjusting weights
+
+Scoring weights live in `pecan_ilamb.cfg` at two levels: the `weight` on each
+`[h2: ...]` variable sets how much that variable counts toward the overall
+score relative to the other variables, and the `weight` on each dataset block
+sets how much that dataset counts within its variable. Both are relative
+weights, not percentages. See the inline comments in the config for the full
+per-field reference.

modules/benchmark/inst/ilamb/pecan_ilamb.cfg

@@ -8,6 +8,58 @@
 #  - LAI: GIMMS_LAI4g (1982-2020). Direct lai comparison.
 #  - Soil carbon: HWSD2 (time-invariant). PEcAn TotSoilCarb is 0-200cm vs
 #    benchmark shallower; PEcAn reads higher. Flagged for review.
+#
+# ---------------------------------------------------------------------------
+# How this file is structured (ILAMB confrontation config)
+# ---------------------------------------------------------------------------
+# [h1: ...]   A top-level section header that groups variables on the
+#             scorecard. Purely organizational; "bgcolor" sets its row color.
+#
+# [h2: ...]   A variable to be scored (one carbon-cycle quantity). Its fields:
+#   variable        The ILAMB/CMOR variable name ILAMB looks for in the
+#                   benchmark file (e.g. "lai", "cSoil"). For "biomass" the
+#                   model files store "cVeg", so alternate_vars maps it.
+#   alternate_vars  Other variable name(s) to accept from the model files if
+#                   "variable" is not found (here: model cVeg -> biomass).
+#   weight          How much this variable counts toward the overall score,
+#                   RELATIVE to the other [h2] variables. These are relative
+#                   weights, not percentages: Biomass 5, LAI 3, Soil 5 means
+#                   biomass and soil each count 5/13 and LAI 3/13 of the total.
+#                   Raise a variable's weight to make it matter more overall.
+#   mass_weighting  If True, spatial errors are weighted by the magnitude of
+#                   the field, so high-carbon regions count more than near-zero
+#                   ones. Standard for carbon pools.
+#   cmap            Colormap for this variable's plots (cosmetic only).
+#
+# [BenchmarkName]   An observational dataset to compare against, listed
+#             directly under its [h2] variable. Its fields:
+#   source          Path to the benchmark netCDF, relative to ILAMB_ROOT
+#                   (set via the ILAMB_ROOT environment variable). This is the
+#                   observation the models are scored against.
+#   weight          How much THIS dataset counts within its variable, relative
+#                   to any other benchmark datasets listed under the same [h2].
+#                   With a single dataset per variable (as here) its value only
+#                   matters if you add a second benchmark for that variable.
+#   table_unit      Unit shown in the summary score tables (e.g. "Pg").
+#   plot_unit       Unit used in the map plots (e.g. "kg m-2").
+#   space_mean      If True, report a spatial mean; if False, report a spatial
+#                   integral/sum. False suits total-pool comparisons.
+#   skip_rmse       Skip the RMSE component of the score. Used where an
+#                   absolute-value RMSE is not meaningful for this comparison
+#                   (e.g. pool-definition mismatches noted above).
+#   skip_cycle      Skip the seasonal-cycle score component. Used for LAI here
+#                   because the benchmark and model sampling differ seasonally.
+#
+# ---------------------------------------------------------------------------
+# To ADD A NEW BENCHMARK for an existing variable: copy a [BenchmarkName]
+# block under the relevant [h2], rename it, and point "source" at the new
+# netCDF (placed under ILAMB_ROOT/DATA/...). Multiple benchmarks under one
+# [h2] are combined using their "weight" values.
+#
+# To ADD A NEW VARIABLE: add a new [h2: ...] block with its "variable" name
+# and at least one [BenchmarkName] dataset beneath it, then make sure the
+# model files contain that variable (see build scripts and README).
+# ---------------------------------------------------------------------------
 
 [h1: Ecosystem and Carbon Cycle]
 bgcolor = "#ECFFE6"