Generate One-At-a-Time (OAT) input design for sensitivity analysis — generate_OAT_SA

Creates an input design matrix for sensitivity analysis where non-parameter inputs (met, IC, soil, etc.) are held constant while parameters vary one-at-a-time across quantiles. This differs from ensemble design, where all inputs vary together.

Usage

generate_OAT_SA_design(settings, samples = NULL)

Arguments

settings: PEcAn settings object. See details for required elements.
samples: Optional pre-computed parameter samples (a list containing at least sa.samples, as returned by get_parameter_samples). When supplied these are used directly; when NULL (default) they are sampled in memory.

Value

A list with design_matrix, a data.frame with one row per SA run: the param column holds sequential run indices, every input column is held at 1, and sa_pft, sa_trait and sa_quantile say what each run is. The first row is the median run, with those three NA, NA and "50"; every row after moves one trait of one PFT to one of its quantiles. Also X, the same matrix under its older name, and samples, the parameter bundle used.

Details

## Settings requirements

This function directly uses:

settings$pfts - List of PFTs (extracts posterior.files)
settings$ensemble$samplingspace - Input types to include in design
settings$sensitivity.analysis$quantiles - SA quantiles, when sampling here rather than reusing a supplied bundle

When samples = NULL, load_pft_posteriors additionally uses settings$database$bety and settings$host$name for the optional posterior lookup.

## OAT design logic For sensitivity analysis, we must isolate the effect of each parameter by holding all other inputs constant. The param column contains sequential indices (1, 2, 3, ...), and sa_pft, sa_trait and sa_quantile say what each run is: the first holds every parameter at its median, and each one after moves a single trait to one of its quantiles. All other columns (met, ic, soil, etc.) are set to 1, meaning the first input file is always used.

## Where the samples come from Parameter samples are drawn in memory via load_pft_posteriors and get_parameter_samples (mirroring generate_joint_ensemble_design), or reused when a samples bundle is supplied. Nothing is read from or written to samples.Rdata. The design is built from the quantile-based sa.samples in that bundle.

Author

Akash B V, Om Kapale

Examples

if (FALSE) { # \dontrun{
# Generate the SA design, sampling parameters in memory
sa_design <- generate_OAT_SA_design(settings)

# View the design matrix
print(sa_design$design_matrix)
#   param met ic soil
# 1     1   1  1    1   # Median run
# 2     2   1  1    1   # trait1 @ q=2.3%
# 3     3   1  1    1   # trait1 @ q=15.9%
# 4     4   1  1    1   # trait1 @ q=84.1%
# ...

# Reuse an established set of samples instead of drawing new ones
sa_design <- generate_OAT_SA_design(settings, samples = samples)
} # }