Skip to contents

Generate joint ensemble design for parameter sampling

Source: R/generate_joint_ensemble_design.R
generate_joint_ensemble_design.Rd

Creates a joint ensemble design that maintains parameter correlations across all sites in a multi-site run. This function generates sample indices that are shared across sites to ensure consistent parameter sampling.

Usage

generate_joint_ensemble_design(
  settings,
  ensemble_size,
  samples = NULL,
  sobol = FALSE
)

Arguments

settings

PEcAn settings object. This function directly uses:

  • settings$pfts - List of PFTs (extracts posterior.files)

  • settings$ensemble$samplingspace - Input sampling configuration

  • settings$run$inputs - Input paths for each input type

When samples is not supplied, load_pft_posteriors additionally uses settings$database$bety and settings$host$name for the optional posterior lookup.

ensemble_size

Integer specifying the number of ensemble members. The input_design is generated once for the entire model run. You might want to recycle existing ensemble_samples when splitting larger runs into smaller jobs while keeping the same parameters.

samples

Optional pre-computed parameter samples. When supplied, these are used directly instead of loading posteriors and sampling. When NULL (default), samples are generated in memory via load_pft_posteriors and get_parameter_samples.

sobol

Logical. If TRUE, returns a sensitivity::soboljansen object for Sobol sensitivity analysis.

Value

If sobol = FALSE, a list with design_matrix (the design, one row per run, whose param column indexes the samples), X (the same matrix under its older name, kept so existing callers keep working), and samples (the parameter bundle those indices point into). If sobol = TRUE, a sensitivity::soboljansen() result object carrying the same design_matrix and samples entries, with $X set by sensitivity itself, plus the extra components its index calculations need.

Details

Parameter samples are drawn in memory via load_pft_posteriors and get_parameter_samples, or reused when a samples bundle is supplied. Nothing is read from or written to samples.Rdata.

load_pft_posteriors finds and loads the parameter distributions.

In practice it: - uses pft$posterior.files directly when it is defined (an Rdata file with post.distns or prior.distns), - otherwise figures out an output directory from pft$outdir or, if needed, via pft$posteriorid in the database, - then looks in that directory for post.distns.Rdata, falling back to prior.distns.Rdata, - and, for MCMC posteriors, looks up trait.mcmc*.Rdata linked to the same posteriorid or a trait.mcmc.Rdata file in that directory.

Difference from generate_OAT_SA_design: This function samples inputs randomly or quasi-randomly, while generate_OAT_SA_design holds all non-parameter inputs constant to isolate parameter effects.