Get trait data from the database for a single PFT

Queries BETYdb for trait observations and prior distributions for a single plant functional type (PFT). Results are saved to files in the PFT output directory (pft$outdir), and also registered in the database as posterior records when write = TRUE.

Usage

get.trait.data.pft(
  pft,
  modeltype,
  dbfiles,
  dbcon,
  trait.names = NULL,
  forceupdate = FALSE,
  write = TRUE,
  return_data = FALSE
)

Arguments

pft

list of settings for the pft whose traits to retrieve. See details.

modeltype

type of model that is used, this is used to distinguish between different pfts with the same name.

dbfiles

location where previous results are found

dbcon

database connection

trait.names

list of trait names to retrieve

forceupdate

set this to true to force an update, auto will check to see if an update is needed.

write

(Logical) If TRUE updated posteriors will be written to BETYdb. Defaults to FALSE.

return_data

(Logical) If TRUE, the returned pft list also includes trait_data and prior_distns as in-memory objects. Defaults to FALSE to preserve legacy behavior — when pft is embedded inside a settings object, attaching these data frames by default would inflate the settings and break serialization.

Value

The updated pft list with posteriorid set to the ID of the (possibly new) posterior record in BETYdb. The posterior ID can be used to locate the output files (trait.data.Rdata, prior.distns.Rdata, etc.) via BETYdb's dbfiles table.

When return_data = TRUE, the returned list also includes trait_data and prior_distns as in-memory objects, so downstream callers can use them without reloading from pft$outdir.

Details

pft should be a list containing at least name and outdir, and optionally posteriorid and constants.

File-based side effects

The following files are written to pft$outdir:

trait.data.Rdata

Named list of trait data frames, one per trait that has observations. Read by run.meta.analysis.pft().

prior.distns.Rdata

Data frame of prior distributions, rows named by trait. Read by run.meta.analysis.pft().

species.csv or cultivars.csv

Data frame of PFT member species or cultivar IDs, depending on PFT type.

trait.data.csv

Flattened CSV of all trait observations, one row per observation, for human inspection.

In addition, each output file is registered in BETYdb via dbfile.insert() and associated with the posterior record whose ID is returned as pft$posteriorid.

Downstream contract

run.meta.analysis.pft() reads trait.data.Rdata and prior.distns.Rdata from pft$outdir at the start of the meta-analysis step. These two files are therefore a required output of this wrapper.

Note: this file-based contract will be removed once run.meta.analysis.pft() is refactored to accept in-memory inputs (GSoC Week 2).

Author

David LeBauer, Shawn Serbin, Rob Kooper