spLM: Function for fitting univariate Bayesian spatial regression models

Description

The function spLM fits Gaussian univariate Bayesian spatial regression models. Given a set of knots, spLM will also fit a predictive process model (see references below).

Usage

spLM(formula, data = parent.frame(), coords, knots, starting, tuning, priors, cov.model, modified.pp = TRUE, amcmc, n.samples,  verbose=TRUE, n.report=100, ...)

Arguments

formula

a symbolic description of the regression model to be fit. See example below.

data

an optional data frame containing the variables in the model. If not found in data, the variables are taken from environment(formula), typically the environment from which spLM is called.

coords

an $n x 2$ matrix of the observation coordinates in $R^2$ (e.g., easting and northing).

knots

either a $m x 2$ matrix of the predictive process knot coordinates in $R^2$ (e.g., easting and northing) or a vector of length two or three with the first and second elements recording the number of columns and rows in the desired knot grid. The third, optional, element sets the offset of the outermost knots from the extent of the coords.

starting

a list with each tag corresponding to a parameter name. Valid tags are beta, sigma.sq, tau.sq, phi, and nu. The value portion of each tag is the parameter's starting value.

tuning

a list with each tag corresponding to a parameter name. Valid tags are sigma.sq, tau.sq, phi, and nu. The value portion of each tag defines the variance of the Metropolis sampler Normal proposal distribution.

priors

a list with each tag corresponding to a parameter name. Valid tags are sigma.sq.ig, tau.sq.ig, phi.unif, nu.unif, beta.norm, and beta.flat. Variance parameters, simga.sq and tau.sq, are assumed to follow an inverse-Gamma distribution, whereas the spatial decay phi and smoothness nu parameters are assumed to follow Uniform distributions. The hyperparameters of the inverse-Gamma are passed as a vector of length two, with the first and second elements corresponding to the shape and scale, respectively. The hyperparameters of the Uniform are also passed as a vector of length two with the first and second elements corresponding to the lower and upper support, respectively. If the regression coefficients, i.e., beta vector, are assumed to follow a multivariate Normal distribution then pass the hyperparameters as a list of length two with the first and second elements corresponding to the mean vector and positive definite covariance matrix, respectively. If beta is assumed flat then no arguments are passed. The default is a flat prior.

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". See below for details.

modified.pp

a logical value indicating if the modified predictive process should be used (see references below for details). Note, if a predictive process model is not used (i.e., knots is not specified) then this argument is ignored.

amcmc

a list with tags n.batch, batch.length, and accept.rate. Specifying this argument invokes an adaptive MCMC sampler, see Roberts and Rosenthal (2007) for an explanation.

n.samples

the number of MCMC iterations. This argument is ignored if amcmc is specified.

verbose

if TRUE, model specification and progress of the sampler is printed to the screen. Otherwise, nothing is printed to the screen.

n.report

the interval to report Metropolis sampler acceptance and MCMC progress.

...

currently no additional arguments.

Value

coords: the $n x 2$ matrix specified by coords.
knot.coords: the $m x 2$ matrix as specified by knots.
p.theta.samples: a coda object of posterior samples for the defined parameters.
acceptance: the Metropolis sampling acceptance percent. Reported at batch.length or n.report intervals for amcmc specified and non-specified, respectively.

Details

Model parameters can be fixed at their starting values by setting their tuning values to zero.

The no nugget model is specified by removing tau.sq from the starting list.

References

Banerjee, S., A.E. Gelfand, A.O. Finley, and H. Sang. (2008) Gaussian Predictive Process Models for Large Spatial Datasets. Journal of the Royal Statistical Society Series B, 70:825--848.

Banerjee, S., Carlin, B.P., and Gelfand, A.E. (2004). Hierarchical modeling and analysis for spatial data. Chapman and Hall/CRC Press, Boca Raton, FL.

Finley, A.O., S. Banerjee, and A.E. Gelfand. (2015) spBayes for large univariate and multivariate point-referenced spatio-temporal data models. Journal of Statistical Software, 63:1--28. http://www.jstatsoft.org/v63/i13. Finley, A.O., H. Sang, S. Banerjee, and A.E. Gelfand. (2009) Improving the performance of predictive process modeling for large datasets. Computational Statistics and Data Analysis, 53:2873--2884. Roberts G.O. and Rosenthal J.S. (2006). Examples of Adaptive MCMC. http://probability.ca/jeff/ftpdir/adaptex.pdf.

Examples

Run this code

## Not run: 
# rmvn <- function(n, mu=0, V = matrix(1)){
#   p <- length(mu)
#   if(any(is.na(match(dim(V),p))))
#     stop("Dimension problem!")
#   D <- chol(V)
#   t(matrix(rnorm(n*p), ncol=p)%*%D + rep(mu,rep(n,p)))
# }
# 
# set.seed(1)
# 
# n <- 100
# coords <- cbind(runif(n,0,1), runif(n,0,1))
# X <- as.matrix(cbind(1, rnorm(n)))
# 
# B <- as.matrix(c(1,5))
# p <- length(B)
# 
# sigma.sq <- 2
# tau.sq <- 0.1
# phi <- 3/0.5
# 
# D <- as.matrix(dist(coords))
# R <- exp(-phi*D)
# w <- rmvn(1, rep(0,n), sigma.sq*R)
# y <- rnorm(n, X%*%B + w, sqrt(tau.sq))
# 
# n.samples <- 2000
# 
# starting <- list("phi"=3/0.5, "sigma.sq"=50, "tau.sq"=1)
# 
# tuning <- list("phi"=0.1, "sigma.sq"=0.1, "tau.sq"=0.1)
# 
# priors.1 <- list("beta.Norm"=list(rep(0,p), diag(1000,p)),
#                  "phi.Unif"=c(3/1, 3/0.1), "sigma.sq.IG"=c(2, 2),
#                  "tau.sq.IG"=c(2, 0.1))
# 
# priors.2 <- list("beta.Flat", "phi.Unif"=c(3/1, 3/0.1),
#                  "sigma.sq.IG"=c(2, 2), "tau.sq.IG"=c(2, 0.1))
# 
# cov.model <- "exponential"
# 
# n.report <- 500
# verbose <- TRUE
# 
# m.1 <- spLM(y~X-1, coords=coords, starting=starting,
#             tuning=tuning, priors=priors.1, cov.model=cov.model,
#             n.samples=n.samples, verbose=verbose, n.report=n.report)
# 
# m.2 <- spLM(y~X-1, coords=coords, starting=starting,
#             tuning=tuning, priors=priors.2, cov.model=cov.model,
#             n.samples=n.samples, verbose=verbose, n.report=n.report)
# 
# burn.in <- 0.5*n.samples
# 
# ##recover beta and spatial random effects
# m.1 <- spRecover(m.1, start=burn.in, verbose=FALSE)
# m.2 <- spRecover(m.2, start=burn.in, verbose=FALSE)
# 
# round(summary(m.1$p.theta.recover.samples)$quantiles[,c(3,1,5)],2)
# round(summary(m.2$p.theta.recover.samples)$quantiles[,c(3,1,5)],2)
# 
# round(summary(m.1$p.beta.recover.samples)$quantiles[,c(3,1,5)],2)
# round(summary(m.2$p.beta.recover.samples)$quantiles[,c(3,1,5)],2)
# 
# m.1.w.summary <- summary(mcmc(t(m.1$p.w.recover.samples)))$quantiles[,c(3,1,5)]
# m.2.w.summary <- summary(mcmc(t(m.2$p.w.recover.samples)))$quantiles[,c(3,1,5)]
# 
# plot(w, m.1.w.summary[,1], xlab="Observed w", ylab="Fitted w",
#      xlim=range(w), ylim=range(m.1.w.summary), main="Spatial random effects")
# arrows(w, m.1.w.summary[,1], w, m.1.w.summary[,2], length=0.02, angle=90)
# arrows(w, m.1.w.summary[,1], w, m.1.w.summary[,3], length=0.02, angle=90)
# lines(range(w), range(w))
# 
# points(w, m.2.w.summary[,1], col="blue", pch=19, cex=0.5)
# arrows(w, m.2.w.summary[,1], w, col="blue", m.2.w.summary[,2], length=0.02, angle=90)
# arrows(w, m.2.w.summary[,1], w, col="blue", m.2.w.summary[,3], length=0.02, angle=90)
# 
# ###########################
# ##Predictive process model
# ###########################
# m.1 <- spLM(y~X-1, coords=coords, knots=c(6,6,0.1), starting=starting,
#             tuning=tuning, priors=priors.1, cov.model=cov.model,
#             n.samples=n.samples, verbose=verbose, n.report=n.report)
# 
# m.2 <- spLM(y~X-1, coords=coords, knots=c(6,6,0.1), starting=starting,
#             tuning=tuning, priors=priors.2, cov.model=cov.model,
#             n.samples=n.samples, verbose=verbose, n.report=n.report)
# 
# burn.in <- 0.5*n.samples
# 
# round(summary(window(m.1$p.beta.samples, start=burn.in))$quantiles[,c(3,1,5)],2)
# round(summary(window(m.2$p.beta.samples, start=burn.in))$quantiles[,c(3,1,5)],2)
# 
# round(summary(window(m.1$p.theta.samples, start=burn.in))$quantiles[,c(3,1,5)],2)
# round(summary(window(m.2$p.theta.samples, start=burn.in))$quantiles[,c(3,1,5)],2)
# ## End(Not run)

Run the code above in your browser using DataLab