spatial.occupancy: Fit a spatial occupancy model using Gibbs sampling
In stocc: Fit a Spatial Occupancy Model via Gibbs Sampling

Description Usage Arguments Details Value Author(s)

View source: R/spatial.occupancy.R

This function fits a spatial occupancy model where the true occupancy is a function of a spatial process. An efficient Gibbs sampling algorithm is used by formulating the detection and occupancy process models with a probit model instead of the traditional logit based model.

spatial.occupancy(
  detection.model,
  occupancy.model,
  spatial.model,
  so.data,
  prior,
  control,
  initial.values = NULL
)

`detection.model`	A formula object describing the detection portion of the occupancy model. The variables described by the detection model are located in the `visit` data frame of the `so.data`.
`occupancy.model`	A formula object describing the fixed effects portion of the spatial occupancy process. The variables described by the occupancy model are located in the `site` data frame of an `so.data` object.
`spatial.model`	A named list object describing the spatial component of the occupancy process. Currently the only possible models are ICAR, restricted spatial regression, process convolution models, and no spatial model (i.e., eta = 0). Thus, `spatial.model=list(model="icar", threshold= )`, `spatial.model=list(model="rsr", threshold=, moran.cut=)`, `spatial.model=list(model="proc.conv", knots=)`, and `spatial.model=list(model="none")` are the only forms that are accepted at present. The `threshold` component is used the create neighborhoods in the ICAR and RSR models. All sites within distance `threshold` of site i are considered neighbors of site i. The `moran.cut` component is the cut-off for selecting the spatial harmonics used in the restricted spatial regression model. The value must be between 1 and N and implies that the eigen vectors associated with the largest `moan.cut` eigen values are used for the basis functions. The item `knots` are xy locations of the discrete process convolution knots.
`so.data`	An `so.data` object containing the observed occupancies, detection covariates, site covariates, and site coordinates. This is created via the `make.so.data`
`prior`	A named list that provides the parameter values for the prior distributions. At the current time the elements of the list must contain `a.tau` and `b.tau` which are the parameters for the gamma prior on the spatial process parameter in the occupancy model. Other elements may include `Q.b` and `mu.b` which are the tolerance and mean for the beta vector (detection parameters). Also `Q.g` and `mu.g` which are the prior parameters for the occupancy model. If the Q.b and Q.g are left out, the default is Q.b = 0 and Q.g = 0 (i.e., flat priors). If mu.b and mu.g are left out, the default is zero vectors.
`control`	A named list with the control parameters for the MCMC. The elements of the list must include: (1) `burnin` is the number of iterations of burnin, (2) `iter` is the total number of iterations retained for the MCMC sample, and (3) `thin` is the thining rate of the chain. The real number of MCMC iterations is equal to `iter*thin` of which `iter - burnin` are retained for posterior summary.
`initial.values`	A named list that can include any or all of the following vectors or scalers (1) `beta`, a vector of initial values for the detection parameters, (2) `gamma`, a vector or initial values for the occupancy model, and (3) `tau`, an initial value for the spatial precision parameter.

A Gibbs sampler is run to draw an MCMC sample of the spatial occupancy parameters beta (detection parameters), gamma (the occupancy parameters), psi (the model occupancy generating process), and the realized occupancy.

A list with the following elements:

`beta`	An object of class `mcmc`. The detection model parameters.
`gamma`	An object of class `mcmc`. The occupancy model parameters.
`psi`	An object of class `mcmc`. The occupancy generating process
`real.occ`	An object of class `mcmc`. The realized occupancy at the time of the survey
`tau`	An object of class `mcmc`. The variance parameter for the spatial model
`occupancy.df`	A data frame with the spatial coordinates, site id, and posterior mean and variance of psi, eta, and real.occ
`D.m`	The posterior predictive loss criterion of Gelfand and Ghosh (1998; Biometrika 85:1-11) for model selection. The criterion is a combination of a goodness-of-fit measure, G.m, and a complexity measure, P.m, similar information criteria such as AIC and BIC. D.m = G.m + P.m. Lower values of D.m imply lower expected loss in predicting new data with the posterior model parameters.
`G.m`	The goodness-of-fit portion of D.m
`P.m`	The model complexity component of D.m
`detection.model`	The detection model call.
`occupancy.model`	The occupancy model call.
`model`	A character version of the joint occupancy and detection model call. This is useful for saving results.