Add downscaling-error diagnostic (OOB RMSE vs ensemble spread)

[Tejas7007]

Description

Adds a small diagnostic that compares the downscaling model's own predictive error against the spread of the SDA ensemble, at the assimilation sites, in each variable's own units.

Each SDA ensemble member is downscaled to a 1 km grid by its own random forest. This reads the saved per-member forests and reports, per variable and year, the between-member spread (standard deviation across members, averaged over sites), the downscaling out-of-bag RMSE (averaged over members), and their ratio. When the OOB RMSE exceeds the spread, the members agree with each other more tightly than the downscaling is actually accurate, so the downscaled maps carry error the ensemble spread does not represent. This complements the ensemble-calibration and regional diagnostics already in this directory.

Contents (in modules/benchmark/inst/ilamb/calibration/):

• downscaling_error.R computes the OOB RMSE, the between-member spread, and the ratio from the saved per-member randomForest objects. Paths are parameterized (--model-dir, --variables, --year); the defaults are illustrative.
• test_downscaling_error.R builds small synthetic randomForest objects and checks the extraction, the ratio, and the error paths.
• README_downscaling_error.md documents the inputs, how to run it, and the language choice.

Note on language: the other diagnostics in this directory are Python; this one is R because the downscaling models are R randomForest objects saved in .Rdata, which R reads natively.

Motivation and Context

The ensemble-calibration work showed the ensemble is overconfident relative to independent benchmarks. One contributing mechanism is the downscaling step: the random forest emulator shares structure across members, so the members can agree closely while all being similarly off from truth. This diagnostic makes that quantitative by putting the downscaling's own error next to the between-member spread.

Review Time Estimate

• Immediately
• Within one week
• When possible

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• My name is in the list of CITATION.cff
• I agree that PEcAn Project may distribute my contribution under any or all of
  • the same license as the existing code,
  • and/or the BSD 3-clause license.
• I have updated the CHANGELOG.md.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[ankurdesai]

look good - math makes sense to me