gcamland: gcamland: A stand-alone implementation of the GCAM land...
In JGCRI/gcamland: GCAM Land Allocation Module

Description Usage Bayesian Inference

The gcamland package replicates the land allocation decisions made in GCAM (https:://github.com/jgcri/gcam-core). The equations are documented in Wise et al. (2014). gcamland takes in prices and agricultural productivity growth and calculates land allocation. The model can operate in either hindcast (1975-2015) or future mode (2010-2100), running either single simulations or large ensembles.

Basic Usage

To run an individual scenario, first generate a structure to hold the scenario parameters. The scenario structure can be passed directly to the main model function. Then the model can be run with the run_model function.

1 2	sceninfo <- ScenarioInfo(aExpectationType = "Perfect", aScenarioType = "Hindcast", aScenarioName = "Perfect_Hindcast", aFileName = "Perfect_Hindcast") rslt <- run_model(sceninfo)

The results will be returned as a data frame. If the aVerbose argument is set to TRUE, the results also written as a series of rds (compressed R binaries that can be loaded with readRDS function) and csv files in the directory specified.

Running Ensembles

The run_ensemble_bayes function function will generate and run a collection of scenarios with varying parameters. The parameters are sampled quasi-randomly using a Sobol sequence. The arguments to run_ensemble_bayes are the number of samples (for each expectation model, so 3 times that many will actually be run), output directory, and (optionally) scenario type.

Ensembles can (and probably should) be run in parallel using the doParallel package. To do this, just specify the number of cores to use in the parallel calculation, and doParallel will take care of the rest.

1 2	registerDoParallel(cores=6) ensemble_scenarios <- run_ensemble_bayes(1000, './ensemble-output')

The return value from run_ensemble_bayes is a list of ScenarioInfo structures for the scenarios that were run.

For very large ensembles ensembles you will probably want to run them in parallel on a cluster. There is an example batch script (for the SLURM cluster resource manager) in scripts/jobrun.zsh. You will want to customize the output directory and number of iterations to your needs, then submit it with sbatch. For example, to run 10 batches, each with 960 samples for each of the three models, submit this batch request:

1	sbatch --array=0-9 jobrun.zsh

There are several functions to support Bayesian inference on the ensemble results. The run_bayes function compares the model outputs to the historical data and computes posterior probability densities for the samples. The results of run_bayes are stored in the ScenarioInfo structures. You can use the grand_table_bayes function to reorganize these results into a table for more convenient analysis.

Other Bayesian analysis functions include:

MAP_bayes: Maximum a posteriori parameter estimate.
EV: Expectation value for parameters.
HPDI: Highest Posterior Density Interval (a type of confidence interval for parameters)
waic: Widely Applicable Information Criterion (WAIC), an estimate of a model's out of sample performance.