- formula
a symbolic description of the model to be fit
for 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 y, covs, coords, and z.
y is a matrix with sites corresponding to species and columns
corresponding to sites. covs is a list, matrix, or data
frame of covariates used in the model, where each column (or list element)
represents a different covariate. coords is a
\(J \times 2\) matrix of the observation coordinates. Note that
spAbundance assumes coordinates are specified in a projected coordinate system.
For zero-inflated Gaussian models, the tag z is used to specify the
binary component of the model and should have the same dimensions as y.
- inits
a list with each tag corresponding to a parameter name.
Valid tags are beta.comm, beta,
tau.sq.beta, sigma.sq.mu,
phi, lambda, nu, and tau.sq. nu is only specified if
cov.model = "matern", tau.sq is only
specified for Gaussian and zero-inflated Gaussian models,
and sigma.sq.mu is only specified if random effects are included in formula.
The value portion of each tag is
the parameter's initial value. See priors description for definition
of each parameter name. Additionally, the tag fix can be set to TRUE
to fix the starting values across all chains. If fix is not specified
(the default), starting values are varied randomly across chains.
- priors
a list with each tag corresponding to a parameter name.
Valid tags are beta.comm.normal, tau.sq.beta.ig, sigma.sq.mu,
phi.unif, nu.unif, and tau.sq.ig.
Community-level (beta.comm) regression coefficients are assumed to follow a
normal distribution. The hyperparameters of the normal distribution
are passed as a list of length two with the first and second elements
corresponding to the mean and variance of the normal distribution,
which are each specified as vectors of length equal to the number of
coefficients to be estimated or of length one if priors are the same for
all coefficients. If not specified, prior means are set
to 0 and prior variances to 100. Community-level variance parameters
(tau.sq.beta) are
assumed to follow an inverse Gamma distribution. The hyperparameters of
the inverse gamma distribution are passed as a list of length two with
the first and second elements corresponding to the shape and scale parameters,
which are each specified as vectors of length equal to the number of
coefficients to be estimated or a single value if priors are the same for all
parameters. If not specified, prior shape and scale
parameters are set to 0.1. If desired, the species-specific regression coefficients
(beta) can also be estimated indepdendently by specifying the
tag independent.betas = TRUE. If specified, this will not estimate species-specific
coefficients as random effects from a common-community-level distribution, and rather
the values of beta.comm and tau.sq.beta will be fixed at the
specified initial values. This is equivalent to specifying a Gaussian, independent
prior for each of the species-specific effects.
The spatial factor model fits n.factors independent
spatial processes. The spatial decay phi and smoothness nu parameters
for each latent factor and spatially-varying coefficient
are assumed to follow Uniform distributions.
The hyperparameters of the Uniform are passed as a list with two elements,
with both elements being vectors of length equal to the number of spatial factors
times the number of spatially-varying coefficients corresponding to the lower and
upper support, respectively, or as a single value if the same value is assigned
for all factors and spatially-varying coefficients.
The priors for the factor loadings matrix lambda are fixed
following the standard spatial factor model to ensure parameter
identifiability (Christensen and Amemlya 2002). The
upper triangular elements of the n.sp x n.factors matrix
for each spatially-varying coefficient are fixed at 0 and the
diagonal elements are fixed at 1. The lower triangular elements are assigned a
standard normal prior (i.e., mean 0 and variance 1).
sigma.sq.mu are the random
effect variances random effects, respectively, and are assumed to follow an inverse
Gamma distribution. The hyperparameters of the inverse-Gamma distribution
are passed as a list of length two with first and second elements corresponding
to the shape and scale parameters, respectively, which are each specified as
vectors of length equal to the number of random intercepts or of length one
if priors are the same for all random effect variances. tau.sq is the
species-specific residual variance for Gaussian (or zero-inflated Gaussian) models, and it is assigned
an inverse-Gamma prior. The hyperparameters of the inverse-Gamma are passed as a list
of length two, with the first and second element corresponding to the shape and
scale parameters, respectively, which are each specified as vectors of length
equal to the number of species or a single value if priors are the same for all species.
- tuning
a single numeric value representing the initial variance of the
adaptive sampler for phi and nu.
See Roberts and Rosenthal (2009) for details.
- svc.cols
a vector indicating the variables whose effects will be
estimated as spatially-varying coefficients. svc.cols can be an
integer vector with values indicating the order of covariates specified
in the model formula (with 1 being the intercept if specified), or it can
be specified as a character vector with names corresponding to variable
names in occ.covs (for the intercept, use '(Intercept)'). svc.cols
default argument of 1 results in a spatial factor model analogous to
sfMsAbund (assuming an intercept is included in the model).
- 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:
"exponential", "matern", "spherical", and
"gaussian".
- NNGP
if TRUE, model is fit with an NNGP. If FALSE,
a full Gaussian process is used. See Datta et al. (2016) and
Finley et al. (2019) for more information. For spatial factor models, only
NNGP = TRUE is currently supported.
- n.neighbors
number of neighbors used in the NNGP. Only used if
NNGP = TRUE. Datta et al. (2016) showed that 15 neighbors is usually
sufficient, but that as few as 5 neighbors can be adequate for certain data
sets, which can lead to even greater decreases in run time. We recommend
starting with 15 neighbors (the default) and if additional gains in computation
time are desired, subsequently compare the results with a smaller number
of neighbors using WAIC.
- search.type
a quoted keyword that specifies the type of nearest
neighbor search algorithm. Supported method key words are: "cb" and
"brute". The "cb" should generally be much
faster. If locations do not have identical coordinate values on
the axis used for the nearest neighbor ordering then "cb"
and "brute" should produce identical neighbor sets.
However, if there are identical coordinate values on the axis used
for nearest neighbor ordering, then "cb" and "brute"
might produce different, but equally valid, neighbor sets,
e.g., if data are on a grid.
- n.factors
the number of factors to use in the spatial factor
model approach for each spatially-varying coefficient.
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 the number of species in the modeled 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 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 abundance. Currently, spatially-varying
coefficient models are available for family = 'Gaussian' and
family = 'zi-Gaussian'.
- 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 n.omp.threads up to the number of
hyperthreaded cores. Note, n.omp.threads > 1 might not
work on some systems.
- verbose
if TRUE, messages about data preparation,
model specification, and progress of the sampler are printed to the screen.
Otherwise, no messages are printed.
- n.report
the interval to report Metropolis sampler acceptance and
MCMC progress. Note this is specified in terms of batches and not overall
samples for spatial models.
- n.burn
the number of samples out of the total n.samples to
discard as burn-in for each chain. By default, the first 10% of samples is discarded.
- n.thin
the thinning interval for collection of MCMC samples. The
thinning occurs after the n.burn samples are discarded. Default
value is set to 1.
- n.chains
the number of chains to run in sequence.
- ...
currently no additional arguments