• Module Definitions
  • Query BETY
  • Meta Analysis
  • Single Write Config
  • Write Configs
  • Start Runs
  • Read Model output
  • Sensitivity Analysis
  • Variance Decomposition
  • Visualization
• Glossary

Module Definitions¶

In all cases pecan/bash/scriptname.sh calls pecan/rscripts/scriptname.R. These script pairs represent workflow modules.

Query BETY¶

• name: query.bety.R
• Description: extracts prior distributions for specified pfts, and trait data for any species associated with pft
• Parameters:
  • settings file: xml file containing inputs
    • settings$database$bety: database connection information
    • pft$name: name of pft used to link to BETY database pfts table, and to query species from BETY
    • pft$constants: fixed parameter values
• Inputs:
  • from BETY:
    • spstr: string of comma delimited, specie_id values in quotes. Used to query trait data associated with these species. These are the species linked to pft$name by the pfts_species table
    • prior.distns: table of prior distributions. These are used in the meta-analysis. These are queried from the priors table, and are selected by linking the settings pft$name to pfts.name in the database, which is linked to the priors table by the pfts_priors lookup table.
• Outputs:
  • trait.data.Rdata: list 'trait.data', containing one table per trait. Used in Meta Analysis. Tables have columns Y, n, site, trt, ghs, obs.prec, se, and cite. These columns are derived from bety using the query.bety.trait.data function with the following relationships: Y = traits.mean, n = traits.n, site = traits.site_id, trt = traits.treatment_id, ghs = treatments.greenhouse, obs.prec = f(se), se = f(traits.stat, traits.statname), and cite = citation_id. the site, trt, and ghs values in the database have been converted to sequential integers starting at 1. Each row is a separate observation
  • prior.distns.Rdata: Used in Meta Analysis tables of prior distributions for each pft, one row per trait, with columns distn, parama, paramb, and n. distn is the name of one of the probability distributions supported by R (commonly gamma, beta, lognorm, weibull, norm), parama and paramb are the first and second parameters of the distribution.

Meta Analysis¶

• name: meta.analysis.R
• Description: calculates the posterior distribution of for traits for each pft, where there exist species-level data for the given pft x trait combination.
• Parameters:
  • settings file
    • meta.analysis$iter: number of steps in MCMC chain
    • pft$outdir: directory for pft-specific output
    • pft$name: name of pft
• Inputs:
  • trait.data.Rdata: Generated by Query BETY module. Data tables for each trait by species combination
  • prior.distns.Rdata: Generated by Query BETY module. Tables of prior distributions for each pft
• Outputs:
  • <traitname>.model.bug meta-analysis model specification in JAGS (used internally)
  • trait.mcmc.Rdata: To be used by Write Configs. List of raw mcmc output (of class mcmc.list) with one mcmc.list per trait
  • post.distns.Rdata: To be used in data assimilation (not currently implemented). Posterior distributions for each pft/trait combination summarized using standard distributions
  • meta.analysis.log: for human assessment: data, meta-analysis results, MCMC diagnostics (also written to terminal)
  • ma.summaryplots.<site>.<pft><trait>.pdf: for human assessment: diagnostic plots, to check that convergence meets assumptions of MCMC method
  • posteriors.pdf: for human assessment of meta-analysis and data: plots for comparing posterior with data and prior

Single Write Config¶

A single configuration file can be written using the write.config() function, e.g.:

trait.samples <- list(Vcmax = 20, SLA = 20)
settings <- xmlToList(xmlParse('~/test.pecan/settings.xml'))
pft <- settings$pfts[[1]]
outdir <- settings$outdir
run.id <- 'test.run'
write.config.ED(pft, trait.samples, settings, outdir, run.id) 

Write Configs¶

• name: write.configs.R
• Description: writes configuration files used in the model runs. Model specific unit and naming conversions are made using functions found in R/model.specific.R
• Parameters:
  • settings file
    • pft$name
    • pft$outdir
    • settings$ensemble
    • settings$sensitivity.analysis
    • settings$sensitivity.analysis$quantiles
  • <runid> is a function of either quantiles or i=1:n ensemble members
  • ED2IN template (see edin/templateED2IN*)
• Inputs:
  • prior.distns.Rdata (from Meta Analysis)
  • trait.mcmc.Rdata (from Meta Analysis)
• Outputs:
  • ED2INc.<pft><runid> ED2IN file for each run
  • c.<pft><runid> configuration file for each run
• Side Effects:
  • Deletes existing config files prior to writing new ones

Start Runs¶

(works on 1 or more runs)

• name: start.runs.R
• Description: Starts model runs by executing bash/batch.jobs.sh
• Parameters:
  • settings file
    • host$name: machine with model
    • host$rundir: directory where model executable is located
    • settings$pecanDir pecan home directory where bash/batch.jobs.sh resides
• Inputs:
  • ED2INc.<pft><runid> ED2IN file for each run (from Write Configs)
  • c.<pft><runid> configuration file for each run (from Write Configs)
  • batch.jobs.sh: script that starts a run for each ED2IN* file generated in write.configs
• Outputs:
  • ED Model output for each <runid>

Read Model output¶

• works for one or more runs, currently set to only output AGB
• see read.output.R for code used to extract data from ED on cluster

• name: get.model.output.R
• Description
• Parameters:
  • settings file
    • settings$run$host name of model host machine
    • settings$outdir directory in which output should be saved
• Inputs:
  • read.output.R script with functions and code to extract model output (self contained, so it can be executed independently on model host machine)
• Output
  • ensemble.Rdata, to be used, e.g., in Sensitivity Analysis and Visualization modules containing (if produced):
  • sensitivity.Rdata, to be used, e.g., in Sensitivity Analysis and Visualization modules containing (if produced):
    • ensemble.output: results from ensemble runs
    • sa.output: aboveground bioma
• name: get.model.output.R
• Description
• Parameters:
  • settings file
    • settings$run$host name of model host machine
    • settings$outdir directory in which output should be saved
• Inputs:
  • read.output.R script with functions and code to extract model output (self contained, so it can be executed independently on model host machine)
• Output
  • sensitivity.Rdata, to be used, e.g., in Sensitivity Analysis and Visualization modules containing (if produced):
  • ensemble.Rdata, to be used, e.g., in Sensitivity Analysis and Visualization modules containing (if produced):
    • ensemble.output: results from ensemble runs
    • sa.output: aboveground biomass results from sensitivity runsss results from sensitivity runs

Sensitivity Analysis¶

• in the context of modularization, this script is still under development

Variance Decomposition¶

• to be branched from Sensitivity Analysis module

Visualization¶

• under development, will be partially branched from current Sensitivity Analysis module

Glossary¶

• Inputs: data sets that are used, and file paths leading to them
• Parameters: e.g. info set in settings file
• Outputs: data sets that are dropped, and the file paths leading to them