From 906b02102d9539ee5f9f9adc29386036fec6fba9 Mon Sep 17 00:00:00 2001
From: Tejas <tejasdahiya0007@gmail.com>
Date: Wed, 8 Jul 2026 06:59:02 -0500
Subject: [PATCH] Add ILAMB scorecard generation script and hosting note

Add make_scorecard.sh, a wrapper that runs ilamb-run against a window model
root to produce the ILAMB HTML scorecard, and a README section documenting
how to generate and serve it. The scorecard uses the clean model roots so it
lists PEcAn against the individual CMIP6 and TRENDY models and the ensemble
means, rather than the 100 individual PEcAn members used for spread analysis.
---
 CHANGELOG.md                                  |  1 +
 modules/benchmark/inst/ilamb/README.md        | 18 ++++++
 .../benchmark/inst/ilamb/make_scorecard.sh    | 60 +++++++++++++++++++
 3 files changed, 79 insertions(+)
 create mode 100755 modules/benchmark/inst/ilamb/make_scorecard.sh

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 <window> [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_<window>.
+#   build_dir   Optional. Output directory for the HTML scorecard.
+#               Default: ilamb_scorecard_<window>.
+#
+# 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 <window> [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."