Convert priors / MCMC samples to parameter sample chains

Usage

get.parameter.samples(
  settings,
  ensemble.size = 1,
  posterior.files = rep(NA, length(settings$pfts)),
  ens.sample.method = "uniform",
  save_to_disk = TRUE
)

Arguments

settings: PEcAn settings object
ensemble.size: number of runs in model ensemble
posterior.files: list of filenames to read from
ens.sample.method: one of "halton", "sobol", "torus", "lhc", "uniform"
save_to_disk: logical. If TRUE (default), saves samples.Rdata.

Value

Named list with 5 elements: trait.samples, sa.samples, ensemble.samples, runs.samples, env.samples. Returned invisibly.

Details

Upstream contract (reads from each PFT's outdir):

post.distns.Rdata or prior.distns.Rdata: Posterior (or prior) distribution summaries produced by run.meta.analysis.pft. A data frame with columns distn, parama, paramb, n.
trait.mcmc.Rdata: (Optional) MCMC chain samples from the meta-analysis. Named list of mcmc.list objects, one per trait. If present, samples are drawn from the chains directly; otherwise, independent samples are drawn from post.distns.

File-based side effects (saved to settings$outdir):

samples.Rdata

When save_to_disk = TRUE, bundles 5 objects:

trait.samples — Named list (PFT -> trait -> numeric vector of length iterations). Raw MCMC or prior-sampled values.
sa.samples — Named list (PFT -> matrix[n_quantiles x n_traits]). Quantile-based samples for sensitivity analysis.
ensemble.samples — Named list (PFT -> data frame[ensemble.size x n_traits]). Subsampled parameter sets for ensemble runs.
env.samples — Currently empty list (reserved for environmental samples).
runs.samples — Currently empty list (reserved for run metadata).

Downstream contract: samples.Rdata is loaded by run.write.configs (in PEcAn.workflow) to generate model configuration files. It is also loaded by get.results and run.sensitivity.analysis to retrieve sample metadata for post-processing. This implicit file-based coupling is a refactoring target.

Author

David LeBauer, Shawn Serbin, Istem Fer, Om Kapale