diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ec7cc4560..c43612861b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ For more information about this file see also [Keep a Changelog](http://keepacha ## Unreleased ### Added +- Added `make_scorecard.sh` and documentation to `inst/ilamb/` in PEcAn.benchmark for generating and serving the ILAMB HTML scorecard. - New function `PEcAn.utils::netcdf2df()` flattens all dims and vars of a netCDF into a dataframe, with units attached as an attribute. - New package `PEcAn.RothC` runs the RothC soil carbon model. diff --git a/modules/benchmark/inst/ilamb/README.md b/modules/benchmark/inst/ilamb/README.md index 37f79202e0..8df6e5478f 100644 --- a/modules/benchmark/inst/ilamb/README.md +++ b/modules/benchmark/inst/ilamb/README.md @@ -296,3 +296,21 @@ 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. + +## Generating the scorecard + +ILAMB produces an interactive HTML scorecard alongside the numeric scores. To +generate it for a window, run `make_scorecard.sh` against that window's model +root (built by the pipeline above): + +```bash +export ILAMB_ROOT=/path/to/ILAMB_ROOT +./make_scorecard.sh 2012_2014 +./make_scorecard.sh 2015_2023 +``` + +Each run writes a self-contained static site (`index.html` plus assets) to a +build directory, which can be served directly by copying it under a web +server's document root. The scorecard uses the clean model roots, so it lists +PEcAn alongside the individual CMIP6 and TRENDY models and the ensemble means, +rather than the 100 individual PEcAn members used for the spread analysis. diff --git a/modules/benchmark/inst/ilamb/make_scorecard.sh b/modules/benchmark/inst/ilamb/make_scorecard.sh new file mode 100755 index 0000000000..1879ac73ef --- /dev/null +++ b/modules/benchmark/inst/ilamb/make_scorecard.sh @@ -0,0 +1,60 @@ +#!/bin/bash +# +# Generate the ILAMB HTML scorecard for a PEcAn benchmarking window. +# +# Runs ilamb-run against a window's model root (PEcAn, the individual CMIP6 +# and TRENDY models, and the ensemble means) to produce the interactive HTML +# scorecard ILAMB writes to the build directory. This is the public-facing +# comparison view; it uses the clean model roots (no individual PEcAn members), +# so the scorecard lists PEcAn alongside the models rather than 100 member rows. +# +# Prerequisites: +# - ILAMB installed and on PATH (ilamb-run). +# - ILAMB_ROOT set, with the benchmark datasets under $ILAMB_ROOT/DATA. +# - The window model root already built (see build_window_ensembles.py), +# e.g. ilamb_models_2012_2014 / ilamb_models_2015_2023. +# +# Usage: +# ./make_scorecard.sh [model_root] [build_dir] +# +# window Required. A label for the run, e.g. 2012_2014 or 2015_2023. +# model_root Optional. Directory of model entities to score. +# Default: ilamb_models_. +# build_dir Optional. Output directory for the HTML scorecard. +# Default: ilamb_scorecard_. +# +# Example: +# export ILAMB_ROOT=/path/to/ILAMB_ROOT +# ./make_scorecard.sh 2012_2014 +# ./make_scorecard.sh 2015_2023 +# +# The generated build directory (index.html plus assets) is a self-contained +# static site that can be served directly, for example by copying it under a +# web server's document root. + +set -euo pipefail + +WINDOW="${1:?usage: make_scorecard.sh [model_root] [build_dir]}" +MODEL_ROOT="${2:-ilamb_models_${WINDOW}}" +BUILD_DIR="${3:-ilamb_scorecard_${WINDOW}}" +CONFIG="$(dirname "$0")/pecan_ilamb.cfg" + +if [ -z "${ILAMB_ROOT:-}" ]; then + echo "ERROR: ILAMB_ROOT is not set." >&2 + exit 1 +fi +if [ ! -d "$MODEL_ROOT" ]; then + echo "ERROR: model root '$MODEL_ROOT' not found. Build it first." >&2 + exit 1 +fi + +echo "Generating scorecard for window '$WINDOW'" +echo " model root: $MODEL_ROOT" +echo " build dir: $BUILD_DIR" + +ilamb-run --config "$CONFIG" \ + --model_root "$MODEL_ROOT" \ + --build_dir "$BUILD_DIR" \ + --regions global + +echo "Done. Open $BUILD_DIR/index.html, or serve $BUILD_DIR as a static site."