run_model: Run the EcoDiet model

In heloisethero/EcoDiet: Estimating a diet matrix from biotracer and stomach content data

Description

This function runs the EcoDiet model using a Markov chain Monte Carlo approximation through the rjags package to provide an approximated distribution for the variables of interest.

Depending on the nb_iter and nb_adapt entered, this function may take hours, or even days to run. We advise you to first test whether your model is compiling properly with the by-default parameters, as this should take 1-2 min to run depending on your data size.

A message is printed if the model has not converged in the end (if the Gelman-Rubin diagnostic of at least one variable is > 1.1). Other messages or notes may also be printed by the rjags package.

You need to have run the preprocess_data and the write_model functions before using this function, as their outputs are used as the inputs for run_model.

Usage

run_model(
  model_file,
  data,
  inits = NULL,
  nb_iter = 100,
  nb_adapt = 10,
  nb_burnin = floor(nb_iter/2),
  variables_to_save = c("eta", "PI")
)

Arguments

model_file	The file containing the BUGS definition of the EcoDiet model output by the write_model function
data	The preprocessed data list output by the preprocess_data() function
inits	A list containing the initial values of the variables. By default the initialisation values are NULL, which means that the chain initial values are drawns from the prior distributions.
nb_iter	The number of iterations to run. The more iteration, the better are the chances that the model will converge. By default a very small number is used to test if the model is compiling properly.
nb_adapt	The number of adaptation steps to run. The more adaptation steps, the better are the chances that the model will run with good hyperparameters, and thus be faster to converge. By default a very small number is used to test if the model is compiling properly.
nb_burnin	The number of burn in steps to run. Because the chains start at a random initial value, it is good practice to "burn in" the first iterations of the chains so that the variable approximations are not too influenced by the first initial random values. By default we use the same strategy as the rjags package and define the number of iterations to be burnt to be as high as the number of iterations to be kept.
variables_to_save	A vector of variable names defining the variables to output. The number has a big number of variables but by default we only save the variables of interest that are the trophic link probabilities eta and the diet proportions PI. Only these saved variables are used to compute the Gelman-Rubin statistics that indicate whether the model has converged or not.

Value

A matrix containing the variables to store for each predator-prey combination in the columns, and with one MCMC iteration per line.

See Also

preprocess_data to preprocess the data, and write_model to define the model.

Examples

## Not run: 
realistic_biotracer_data <- read.csv(system.file("extdata", "realistic_biotracer_data.csv",
                                               package = "EcoDiet"))
realistic_stomach_data <- read.csv(system.file("extdata", "realistic_stomach_data.csv",
                                             package = "EcoDiet"))

data <- preprocess_data(biotracer_data = realistic_biotracer_data,
                        trophic_discrimination_factor = c(0.8, 3.4),
                        literature_configuration = FALSE,
                        stomach_data = realistic_stomach_data)
                        
model_string <- write_model(literature_configuration = FALSE)

mcmc_output <- run_model(textConnection(model_string), data, nb_adapt = 1e1, nb_iter = 1e2)

## End(Not run)

heloisethero/EcoDiet documentation built on Feb. 12, 2020, 6:08 p.m.