sfMsDS {spAbundance} | R Documentation |
Function for Fitting Spatial Factor Multi-Species Hierarchical Distance Sampling Models
Description
Function for fitting spatial factor multi-species hierarchical distance sampling models.
Usage
sfMsDS(abund.formula, det.formula, data, inits, priors,
tuning, cov.model = 'exponential', NNGP = TRUE,
n.neighbors = 15, search.type = 'cb', n.factors,
n.batch, batch.length, accept.rate = 0.43,
family = 'Poisson', transect = 'line', det.func = 'halfnormal',
n.omp.threads = 1, verbose = TRUE, n.report = 100,
n.burn = round(.10 * n.batch * batch.length), n.thin = 1,
n.chains = 1, ...)
Arguments
abund.formula |
a symbolic description of the model to be fit for the abundance portion of the model using R's model syntax. Only right-hand side of formula is specified. See example below. Random intercepts and slopes are allowed using lme4 syntax (Bates et al. 2015). |
det.formula |
a symbolic description of the model to be fit for the detection portion of the model using R's model syntax. Only right-hand side of formula is specified. See example below. Random intercepts and slopes are allowed using lme4 syntax (Bates et al. 2015). |
data |
a list containing data necessary for model fitting.
Valid tags are |
inits |
a list with each tag corresponding to a parameter name.
Valid tags are |
priors |
a list with each tag corresponding to a parameter name.
Valid tags are |
tuning |
a list with each tag corresponding to a parameter name,
whose value defines the initial variance of the adaptive sampler.
Valid tags are |
cov.model |
a quoted keyword that specifies the covariance
function used to model the spatial dependence structure among the
observations. Supported covariance model key words are:
|
NNGP |
if |
n.neighbors |
number of neighbors used in the NNGP. Only used if
|
search.type |
a quoted keyword that specifies the type of nearest
neighbor search algorithm. Supported method key words are: |
n.factors |
the number of factors to use in the latent factor model approach. Typically, the number of factors is set to be small (e.g., 4-5) relative to the total number of species in the community, which will lead to substantial decreases in computation time. However, the value can be anywhere between 1 and N (the number of species in the community). |
n.batch |
the number of MCMC batches in each chain to run for the Adaptive MCMC sampler. See Roberts and Rosenthal (2009) for details. |
batch.length |
the length of each MCMC batch in each chain to run for the Adaptive MCMC sampler. See Roberts and Rosenthal (2009) for details. |
accept.rate |
target acceptance rate for Adaptive MCMC. Default is 0.43. See Roberts and Rosenthal (2009) for details. |
family |
the distribution to use for the latent abundance process. Currently
supports |
transect |
the type of transect. Currently supports line transects ( |
det.func |
the detection model used to describe how detection probability varies
with distance. In other software, this is often referred to as the key function. Currently
supports two functions: half normal ( |
n.omp.threads |
a positive integer indicating the number of threads
to use for SMP parallel processing. The package must be compiled for
OpenMP support. For most Intel-based machines, we recommend setting
|
verbose |
if |
n.report |
the interval to report MCMC progress. |
n.burn |
the number of samples out of the total |
n.thin |
the thinning interval for collection of MCMC samples. The
thinning occurs after the |
n.chains |
the number of chains to run in sequence. |
... |
currently no additional arguments |
Value
An object of class sfMsDS
that is a list comprised of:
beta.comm.samples |
a |
alpha.comm.samples |
a |
tau.sq.beta.samples |
a |
tau.sq.alpha.samples |
a |
beta.samples |
a |
alpha.samples |
a |
kappa.samples |
a |
theta.samples |
a |
lambda.samples |
a |
w.samples |
a three-dimensional array of posterior samples for the latent effects for each spatial factor. Array dimensions correspond to MCMC sample, spatial factor, then site. |
N.samples |
a three-dimensional array of posterior samples for the latent abundance values for each species. Note that these values always represent transect-level abundance, even when an offset is supplied. Array dimensions correspond to MCMC sample, species, then site. |
mu.samples |
a three-dimensional array of posterior samples for
the latent expected abundance values for each species. When an offset
is supplied in the |
sigma.sq.mu.samples |
a |
sigma.sq.p.samples |
a |
beta.star.samples |
a |
alpha.star.samples |
a |
y.rep.samples |
a four-dimensional array of fitted values. Array dimensions correspond to MCMC samples, species, sites, and distance band. |
pi.samples |
a four-dimensional array of cell-specific detection probabilities. Array dimensions correspond to MCMC samples, species, sites, and distance band. |
rhat |
a list of Gelman-Rubin diagnostic values for some of the model parameters. |
ESS |
a list of effective sample sizes for some of the model parameters. |
run.time |
MCMC sampler execution time reported using |
The return object will include additional objects used for subsequent prediction and/or model fit evaluation.
Author(s)
Jeffrey W. Doser doserjef@msu.edu,
Andrew O. Finley finleya@msu.edu
References
Bates, Douglas, Martin Maechler, Ben Bolker, Steve Walker (2015). Fitting Linear Mixed-Effects Models Using lme4. Journal of Statistical Software, 67(1), 1-48. doi:10.18637/jss.v067.i01.
Royle, J. A. (2004). Nâmixture models for estimating population size from spatially replicated counts. Biometrics, 60(1), 108-115.
Datta, A., S. Banerjee, A.O. Finley, and A.E. Gelfand. (2016) Hierarchical Nearest-Neighbor Gaussian process models for large geostatistical datasets. Journal of the American Statistical Association, doi:10.1080/01621459.2015.1044091.
Finley, A.O., A. Datta, B.D. Cook, D.C. Morton, H.E. Andersen, and S. Banerjee. (2019) Efficient algorithms for Bayesian Nearest Neighbor Gaussian Processes. Journal of Computational and Graphical Statistics, doi:10.1080/10618600.2018.1537924.
Sollmann, R., Gardner, B., Williams, K. A., Gilbert, A. T., & Veit, R. R. (2016). A hierarchical distance sampling model to estimate abundance and covariate associations of species and communities. Methods in Ecology and Evolution, 7(5), 529-537.
Examples
set.seed(210)
J.x <- 10
J.y <- 10
J <- J.x * J.y
# Number of distance bins from which to simulate data.
n.bins <- 5
# Length of each bin. This should be of length n.bins
bin.width <- c(.10, .10, .20, .3, .1)
# Number of species
n.sp <- 5
# Community-level abundance coefficients
beta.mean <- c(-1, 0.2, 0.3, -0.2)
p.abund <- length(beta.mean)
tau.sq.beta <- c(0.2, 0.3, 0.5, 0.4)
# Detection coefficients
alpha.mean <- c(-1.0, -0.3)
p.det <- length(alpha.mean)
tau.sq.alpha <- c(0.1, 0.2)
# Detection decay function
det.func <- 'halfnormal'
mu.RE <- list()
p.RE <- list()
# Draw species-level effects from community means.
beta <- matrix(NA, nrow = n.sp, ncol = p.abund)
alpha <- matrix(NA, nrow = n.sp, ncol = p.det)
for (i in 1:p.abund) {
beta[, i] <- rnorm(n.sp, beta.mean[i], sqrt(tau.sq.beta[i]))
}
for (i in 1:p.det) {
alpha[, i] <- rnorm(n.sp, alpha.mean[i], sqrt(tau.sq.alpha[i]))
}
sp <- TRUE
family <- 'Poisson'
kappa <- runif(n.sp, 0.3, 3)
offset <- pi * .8^2
transect <- 'line'
factor.model <- TRUE
n.factors <- 3
phi <- runif(n.factors, 3 / 1, 3 / .2)
cov.model <- 'exponential'
dat <- simMsDS(J.x = J.x, J.y = J.y, n.bins = n.bins, bin.width = bin.width,
n.sp = n.sp, beta = beta, alpha = alpha, det.func = det.func,
mu.RE = mu.RE, p.RE = p.RE, sp = sp, cov.model = cov.model,
sigma.sq = sigma.sq, phi = phi, nu = nu, family = family,
offset = offset, transect = transect, factor.model = factor.model,
n.factors = n.factors)
y <- dat$y
X <- dat$X
X.p <- dat$X.p
coords <- dat$coords
dist.breaks <- dat$dist.breaks
covs <- cbind(X, X.p)
colnames(covs) <- c('int.abund', 'abund.cov.1', 'abund.cov.2', 'abund.cov.3',
'int.det', 'det.cov.1')
data.list <- list(y = y,
covs = covs,
dist.breaks = dist.breaks,
coords = coords,
offset = offset)
# Priors
prior.list <- list(beta.comm.normal = list(mean = 0, var = 10),
alpha.comm.normal = list(mean = 0, var = 10),
kappa.unif = list(0, 100),
phi.unif = list(3 / 1, 3 / .1),
tau.sq.beta.ig = list(a = 0.1, b = 0.1),
tau.sq.alpha.ig = list(a = 0.1, b = 0.1))
# Starting values
inits.list <- list(alpha.comm = 0, beta.comm = 0, beta = 0,
alpha = 0, kappa = 1, phi = 3 / .5)
tuning <- list(beta = 0.1, alpha = 0.1, beta.star = 0.3, alpha.star = 0.1,
kappa = 0.8, lambda = 1, w = 1, phi = 0.8)
n.batch <- 4
batch.length <- 25
n.burn <- 0
n.thin <- 1
n.chains <- 1
out <- sfMsDS(abund.formula = ~ abund.cov.1 + abund.cov.2 + abund.cov.3,
det.formula = ~ det.cov.1,
data = data.list,
n.batch = n.batch,
batch.length = batch.length,
inits = inits.list,
family = 'Poisson',
det.func = 'halfnormal',
transect = transect,
tuning = tuning,
cov.model = 'exponential',
NNGP = TRUE,
n.neighbors = 5,
n.factors = n.factors,
priors = prior.list,
accept.rate = 0.43,
n.omp.threads = 1,
verbose = TRUE,
n.report = 10,
n.burn = n.burn,
n.thin = n.thin,
n.chains = n.chains)
summary(out, level = 'community')