fit.bugs.env: Fit a spatial, Bayesian, plateau envelope model via MCMC in...

In MarkJBrewer/plateau: Fit plateau climate envelopes in species distribution models for presence/absence data

Description

fit.bugs.env fits a spatial GLM with plateau envelope on the climate covariates via MCMC in WinBUGS.

Usage

fit.bugs.env(data, y, x.clim, x.nonclim = NULL, x.factor = NULL,
  car.sigma = 0.1, num, adj, u, prior.ax, prior.beta, prior.beta0.difference,
  constrain.beta, initial.pars.input, informative.priors = list(beta = FALSE,
  beta0 = FALSE, ax = FALSE), burnin = 5000, post.burnin = 1000,
  chains = 2, thin = 1, working.directory = NULL, silent = TRUE,
  bugs.directory = "C:/Program Files (x86)/WinBUGS14/",
  WinBUGS.debug = FALSE, WinBUGS.code = NULL,
  WinBUGS.code.location = NULL, no.starting.value = NULL,
  estimate.p = FALSE, estimate.u = FALSE, u.clique.start, u.clique.end,
  adj.clique.start, adj.clique.end, clique, clique.i)

Arguments

data	The data frame (with n rows) containing all the variables for analysis.
y	A string denoting the binary response variable (taking values 0 or 1 for absence and presence respectively); must correspond to a column name in the data frame specied at data.
x.clim	A vector (length p) of strings denoting which columns in the supplied data frame correspond to the climate covariates; must correspond to column names in the data frame specied at data.
x.nonclim	A vector (length p2) of strings denoting which columns in the supplied data frame correspond to the non-climate covariates; must correspond to column names in the data frame specied at data.
x.factor	A vector (length p3) of strings denoting which columns in the supplied data frame correspond to the non-climate factors; must correspond to column names in the data frame specied at data.
car.sigma	Standard deviation of the WinBUGS car.normal process; needs to be a constant in the case of a binary response.
num	A vector (length n) of the numbers of neighbours of each cell, in order (but see later comment on cliques).
adj	A vector of adjacencies, length 2*number of neighbourhood pairs.
u	Vector of spatial random effects to be supplied as data, of length n; mostly NAs, meaning the u's should be estimated in car.normal, but you may wish to fix some values (e.g. to 0 for disconnected cells). If u is missing and there is only one "clique" (i.e. connected neighbourhood) then u will be created as a vector of NAs of the right length. u should be specified otherwise; this is deliberate. The next four inputs are used to set identifiability constraints on the modelling.
prior.ax	A list of up to two p-vector objects, mean and var, containing the means and variances of (informative) priors for the apex x co-ordinates ax; if either mean or var are omitted, the means and variances are set to 0.5 and 1 respectively.
prior.beta	A list of two p by 2 matrix objects, mean and var, containing the means and variances of (informative) priors for the slopes beta; if omitted, the means and variances are set to 100 and 10000 respectively.
prior.beta0.difference	A list of two scalar objects, mean and var, containing the mean and variance for the log-difference between the apex az and plateau level beta0; if omitted, the mean and variance are set to 1 and 10 respectively.
constrain.beta	A p by 2 matrix of logicals in order to indicate which beta parameters should be constrained to not vary too much from its pair - set at most only one of these to TRUE in each row. A value of TRUE in column 1 suggests that there are not enough data to estimate the "up" (left-hand) part of the envelope, and in column 2 correspondingly for the "down" (right-hand) part of the envelope. If initial.pars.input is not set, the code will work out which betas should be constrained.
initial.pars.input	Vector of length 2p+p+2+p(p-1)/2 containing starting values for each parameter; if missing, the code works out its own starting value. If x.factor is non-null, there will be a total of the number of total levels across all the factors minus p3 extra parameters.
informative.priors	List of logical scalars for which informative priors should be used (from: beta, beta0, ax); this option uses the function generate.initial.values to generate the means, and is an alternative to specifying the priors yourself using prior.ax above etc. Default has all options set to FALSE.
burnin	Scalar specifying the number of "burn-in" iterations to be discarded (default 5000).
post.burnin	Scalar specifying the number of subsequent iterations to be retained (default 1000).
chains	Scalar, number of parallel chains to run (default 2).
thin	Scalar, the thinning to apply to the MCMC iterations (default 1).
working.directory	String containing the location of the WinBUGS code file; default NULL, in which case a temporary folder is used.
silent	Logical flag denoting whether the function runs silently or not. Default is TRUE. The final inputs are optional and will be ignored otherwise. Specifically, you have the option of setting up more than one car.normal in case you have disconnected subsets of your neighbourhood structure. The vectors num, adj and u are still used, and are then composed of NClique parts; the start/end vectors below are used to draw out the relevant data for each clique. Note that if using separate cliques, num will have length n as before, but the order of corresponding cells will be different (not just 1 to n); instead, num specifies the numbers of neighbours in each cell in clique 1 (in the same order as in the data set), and then the numbers of neighbours of cells in clique 2, and so on, until the final clique. Vectors adj and u are structured similarly. The start and end points of each clique are specified using the following inputs:
bugs.directory	String containing location of WinBUGS installation; default "C:/Program Files (x86)/WinBUGS14/" is for Windows 64-bit machines.
WinBUGS.debug	Logical flag as to whether to close WinBUGS after running (default FALSE implies WinBUGS is closed).
WinBUGS.code	You can supply your own code file, especially useful if you want to use informative priors for external information. The default value is NULL, and the code file must be in the folder as specified by WinBUGS.code.location. The effect of a NULL value that the function write.bugs.model is called, and the WinBUGS code file is generated automatically.
WinBUGS.code.location	If WinBUGS.code is not NULL then this folder is examined for the code file specified. The default value is NULL, whereby the code looks for the file in the current directory.
no.starting.value	A list of strings denoting the objects we should not initialise, usually because we set them or calculate them in a bespoke WinBUGS code file. These objects will be set to NA by this function; to use, create objects such as list("beta[2,2]","ax[1]") for example.
estimate.p	Logical flag specifying whether or not to retain samples for the posterior probabilities of presence for each cell, default FALSE; be aware using TRUE can result in slow interaction between R and WinBUGS.
estimate.u	Logical flag specifying whether or not to retain samples for the spatial random effects of presence for each cell, default FALSE; be aware using TRUE can result in slow interaction between R and WinBUGS.
u.clique.start	Vector of length NClique; where each clique starts in u (and num) [Note NClique is determined in the code as the length of this input vector]
u.clique.end	Vector of length NClique; where each clique ends in u (and num).
adj.clique.start	Where each clique starts in adj.
adj.clique.end	Where each clique ends in adj.
clique	Vector to say which clique each observation is in, length n.
clique.i	Vector to say which element each observation is of its clique, length n. If none of these six are supplied, they will be set in the code to enable a "standard" (single clique) analysis.

Value

A list object as returned by the bugs() function in R2WinBUGS; see the help file for that function for further details.

The list is augmented by the response y and the climate variables x.clim, primarily to aid the plotting functions, and by the vector which.beta, of length p, which contains 1's and 2's to signify which set of beta parameters to use; see the description of beta below.

The variables in WinBUGS are (i indexes the climate variable):

beta[which.beta[i],i,1/2]

which.beta (see above) specifies which of two sets of beta parameters to use. There are two betas in order to facilitate constraining either the beta[i,1] (up-slope) or beta[i,2] (down-slope) is to be constrained to be close to its opposite. If beta[i,2] is constrained, we'll use the first set (i.e. which.beta[i]==1) as this models beta[i,1] directly and the multiplicative difference between that and beta[i,2]; if beta[i,1] is constrained (which.beta[i]==2) then we model beta[i,2] directly.

ax

The x-coordinate of the apex for each climate variable.

beta0

Scalar suggesting where the top-slicing should be applied.

az

Scalar coordinate on the logit scale of the response axis apex.

gamma

(Upper triangle) matrix of pairwise interaction parameters between the climate variables; these are constrained relative to the betas in order not to break the geometric formula for a cone.

MarkJBrewer/plateau documentation built on May 7, 2019, 3:35 p.m.