Run Bayesian meta-analysis for a single PFT (file-based wrapper)

Thin wrapper around meta_analysis_standalone that reads trait data and priors either directly from in-memory R objects (when trait_data and prior_distns are provided) or from .Rdata files in pft$outdir (the legacy path). Results are always saved back to pft$outdir for scientific provenance and registered in BETYdb.

Usage

run.meta.analysis.pft(
  pft,
  iterations,
  random = TRUE,
  threshold = 1.2,
  dbfiles,
  dbcon,
  use_ghs = TRUE,
  update = FALSE,
  trait_data = NULL,
  prior_distns = NULL,
  return_data = FALSE
)

Arguments

pft: (list) PFT list object, as defined in settings. Must include the following: outdir, name, posteriorid
iterations: (integer) Number of sampler iterations for MCMC analysis
random: (boolean; default = TRUE) Should random effects be used?
threshold: Gelman-Rubin convergence diagnostic (MGPRF) default = 1.2 following Bolker 2008 Ecological Models and Data in R
dbfiles: (character) directory where previous results are found
dbcon: (DBI connection object) BETY database connection object
use_ghs: (boolean; default = TRUE) If TRUE, do not exclude greenhouse data
update: (boolean; default = FALSE) If TRUE, replace existing posteriors with new ones
trait_data: (named list; default = NULL) Optional in-memory trait data with the same structure as the contents of trait.data.Rdata. When non-NULL, must be provided alongside prior_distns and the .Rdata files in pft$outdir are not read.
prior_distns: (data frame; default = NULL) Optional in-memory prior distributions with the same structure as the contents of prior.distns.Rdata. When non-NULL, must be provided alongside trait_data and the .Rdata files in pft$outdir are not read.
return_data: (boolean; default = FALSE) If TRUE, attach trait.mcmc, post.distns, and jagged.data to the returned pft for in-memory chaining. Defaults to FALSE to preserve legacy behavior — attaching these objects to a pft that is embedded in a settings object would inflate the settings and can break serialization.

Value

The pft list with three additional elements attached, or NA if no trait data are available for this PFT. The returned pft list contains:

name: (character) PFT name, e.g. "temperate.deciduous".
outdir: (character) Path to directory where output files are stored (trait data, priors, posteriors, MCMC samples).
posteriorid: (integer) Row ID of the posterior record in BETYdb's posteriors table.
constants: (named list, optional) Trait values to treat as fixed constants, bypassing the meta-analysis.
trait.mcmc: (named list) mcmc.list objects, one per trait.
post.distns: (data frame) Fitted posterior distributions.
jagged.data: (named list) JAGS-formatted data frames.

File-based side effects in pft$outdir are preserved for backward compatibility and scientific provenance.

Details

Input contract: Trait data and priors enter via one of two paths:

In-memory (preferred for new code)

Pass both trait_data and prior_distns as function arguments. Disk loading is skipped entirely. Either both arguments must be provided or both must be NULL — passing only one is an error.

Disk-based (legacy)

When both trait_data and prior_distns are NULL, the function reads:

trait.data.Rdata — Named list of trait data frames produced by get.trait.data.pft.
prior.distns.Rdata — Data frame of prior distributions produced by get.trait.data.pft.

loaded from pft$outdir.

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

trait.mcmc.Rdata: Contains trait.mcmc: a named list of mcmc.list objects (one per trait) with posterior MCMC samples from JAGS. Each element has columns beta.o (overall mean) and optionally sd.o (overall SD).
post.distns.MA.Rdata: Contains post.distns: a data frame with one row per trait and columns distn, parama, paramb, n summarizing the fitted posterior distribution.
post.distns.Rdata: Symlink to post.distns.MA.Rdata.
jagged.data.Rdata: Contains jagged.data: a named list of data frames (one per trait) formatted for use in the JAGS meta-analysis model (see jagify).

These saves are unconditional: calling this wrapper is the provenance opt-in mechanism. Callers that need a purely in-memory analysis with no filesystem side effects should call meta_analysis_standalone directly.

Downstream contract: The files trait.mcmc.Rdata and post.distns.Rdata are expected by PEcAn.uncertainty::get.parameter.samples() (in PEcAn.uncertainty), which loads them to generate ensemble and sensitivity analysis samples. The same objects are now also attached to the returned pft list (see Value below), so callers wired to the modular pipeline can consume them without re-reading the .Rdata files.

Note: The core computation is performed by meta_analysis_standalone, which accepts and returns R objects directly — see its documentation for the pure-function interface.