
Bayesian spatially-temporally varying coefficients generalized linear model using predictive stacking
Source:R/stvcGLMstack.R
stvcGLMstack.Rd
Fits Bayesian spatial-temporal generalized linear model with spatially-temporally varying coefficients on a collection of candidate models constructed based on some candidate values of some model parameters specified by the user and subsequently combines inference by stacking predictive densities. See Pan, Zhang, Bradley, and Banerjee (2024) for more details.
Usage
stvcGLMstack(
formula,
data = parent.frame(),
family,
sp_coords,
time_coords,
cor.fn,
process.type,
priors,
candidate.models,
n.samples,
loopd.controls,
parallel = FALSE,
solver = "ECOS",
verbose = TRUE,
...
)
Arguments
- formula
a symbolic description of the regression model to be fit. Variables in parenthesis are assigned spatially-temporally varying coefficients. See examples.
- data
an optional data frame containing the variables in the model. If not found in
data
, the variables are taken fromenvironment(formula)
, typically the environment from whichstvcGLMstack
is called.- family
Specifies the distribution of the response as a member of the exponential family. Supported options are
'poisson'
,'binomial'
and'binary'
.- sp_coords
an \(n \times 2\) matrix of the observation spatial coordinates in \(\mathbb{R}^2\) (e.g., easting and northing).
- time_coords
an \(n \times 1\) matrix of the observation temporal coordinates in \(\mathcal{T} \subseteq [0, \infty)\).
- cor.fn
a quoted keyword that specifies the correlation function used to model the spatial-temporal dependence structure among the observations. Supported covariance model key words are:
'gneiting-decay'
(Gneiting and Guttorp 2010). See below for details.- process.type
a quoted keyword specifying the model for the spatial-temporal process. Supported keywords are
'independent'
which indicates independent processes for each varying coefficients characterized by different process parameters,independent.shared
implies independent processes for the varying coefficients that shares common process parameters, andmultivariate
implies correlated processes for the varying coefficients modeled by a multivariate Gaussian process with an inverse-Wishart prior on the correlation matrix. The input forsptParams
andpriors
must be given accordingly.- priors
(optional) a list with each tag corresponding to a hyperparameter name and containing hyperprior details. Valid tags include
V.beta
,nu.beta
,nu.z
,sigmaSq.xi
andIW.scale
. Values ofnu.beta
andnu.z
must be at least 2.1. If not supplied, uses defaults.- candidate.models
an object of class
candidateModels
containing a list of candidate models for stacking. SeecandidateModels()
for details.- n.samples
number of samples to be drawn from the posterior distribution.
- loopd.controls
a list with details on how leave-one-out predictive densities (LOO-PD) are to be calculated. Valid tags include
method
,CV.K
andnMC
. The tagmethod
can be either'exact'
or'CV'
. If sample size is more than 100, then the default is'CV'
withCV.K
equal to its default value 10 (Gelman et al. 2024). The tagnMC
decides how many Monte Carlo samples will be used to evaluate the leave-one-out predictive densities, which must be at least 500 (default).- parallel
logical. If
parallel=FALSE
, the parallelization plan, if set up by the user, is ignored. Ifparallel=TRUE
, the function inherits the parallelization plan that is set by the user via the functionfuture::plan()
only. Depending on the parallel backend available, users may choose their own plan. More details are available at https://cran.R-project.org/package=future.- solver
(optional) Specifies the name of the solver that will be used to obtain optimal stacking weights for each candidate model. Default is
'ECOS'
. Users can use other solvers supported by the CVXR-package package.- verbose
logical. If
TRUE
, prints model-specific optimal stacking weights.- ...
currently no additional argument.
Value
An object of class stvcGLMstack
, which is a list including the
following tags -
samples
a list of length equal to total number of candidate models with each entry corresponding to a list of length 3, containing posterior samples of fixed effects (
beta
), spatial effects (z
), and fine scale variationxi
for that model.loopd
a list of length equal to total number of candidate models with each entry containing leave-one-out predictive densities under that particular model.
n.models
number of candidate models that are fit.
candidate.models
a list of length
n_model
rows with each entry containing details of the model parameters.stacking.weights
a numeric vector of length equal to the number of candidate models storing the optimal stacking weights.
run.time
a
proc_time
object with runtime details.solver.status
solver status as returned by the optimization routine.
This object can be further used to recover posterior samples of the scale
parameters in the model, and subsequrently, to make predictions at new
locations or times using the function posteriorPredict()
.
Examples
data("sim_stvcPoisson")
dat <- sim_stvcPoisson[1:100, ]
# create list of candidate models (multivariate)
mod.list2 <- candidateModels(list(phi_s = list(1, 2, 3),
phi_t = list(1, 2, 4),
boundary = c(0.5, 0.75)), "cartesian")
# fit a spatial-temporal varying coefficient model using predictive stacking
mod1 <- stvcGLMstack(y ~ x1 + (x1), data = dat, family = "poisson",
sp_coords = as.matrix(dat[, c("s1", "s2")]),
time_coords = as.matrix(dat[, "t_coords"]),
cor.fn = "gneiting-decay",
process.type = "multivariate",
candidate.models = mod.list2,
loopd.controls = list(method = "CV", CV.K = 10, nMC = 500),
n.samples = 500)
#>
#> STACKING WEIGHTS:
#>
#> | phi_s | phi_t | boundary | weight |
#> +----------+-------+-------+----------+--------+
#> | Model 1 | 1| 1| 0.50| 0.000 |
#> | Model 2 | 2| 1| 0.50| 0.000 |
#> | Model 3 | 3| 1| 0.50| 0.181 |
#> | Model 4 | 1| 2| 0.50| 0.000 |
#> | Model 5 | 2| 2| 0.50| 0.026 |
#> | Model 6 | 3| 2| 0.50| 0.000 |
#> | Model 7 | 1| 4| 0.50| 0.000 |
#> | Model 8 | 2| 4| 0.50| 0.000 |
#> | Model 9 | 3| 4| 0.50| 0.793 |
#> | Model 10 | 1| 1| 0.75| 0.000 |
#> | Model 11 | 2| 1| 0.75| 0.000 |
#> | Model 12 | 3| 1| 0.75| 0.000 |
#> | Model 13 | 1| 2| 0.75| 0.000 |
#> | Model 14 | 2| 2| 0.75| 0.000 |
#> | Model 15 | 3| 2| 0.75| 0.000 |
#> | Model 16 | 1| 4| 0.75| 0.000 |
#> | Model 17 | 2| 4| 0.75| 0.000 |
#> | Model 18 | 3| 4| 0.75| 0.000 |
#> +----------+-------+-------+----------+--------+
#>