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 and one column per input type (the param column holds sequential run indices, every other column is held at 1), 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, ...) matching the SA run order in write.sa.configs. 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)
} # }