Skip to contents

Convert priors / MCMC samples to parameter sample chains

Source: R/get.parameter.samples.R
get.parameter.samples.Rd

Loads posterior distributions and MCMC chain results from disk, generates parameter samples for ensemble and sensitivity analysis runs, and optionally saves results to samples.Rdata. This is the backward-compatible wrapper that delegates computation to get_parameter_samples.

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