spCP: MCMC sampler for spatially varying change point model.
In spCP: Spatially Varying Change Points

spCP	R Documentation

MCMC sampler for spatially varying change point model.

Description

spCP is a Markov chain Monte Carlo (MCMC) sampler for a spatially varying change point model with spatially varying slopes, intercepts, and unique variances at each spatial-temporal location. The model is implemented using a Bayesian hierarchical framework.

Usage

spCP(
  Y,
  DM,
  W,
  Time,
  Starting = NULL,
  Hypers = NULL,
  Tuning = NULL,
  MCMC = NULL,
  Family = "tobit",
  Weights = "continuous",
  Distance = "circumference",
  Rho = 0.99,
  ScaleY = 10,
  ScaleDM = 100,
  Seed = 54
)

Arguments

`Y`	An `N` dimensional vector containing the observed outcome data. Here, `N = M * Nu`, where `M` represents the number of spatial locations and `Nu` the number of temporal visits. The observations in `Y` must be first ordered spatially and then temporally, meaning the first `M` observations in `Y` should come from the initial time point.
`DM`	An `M` dimensional vector containing a dissimilarity metric for each spatial location. The order of the spatial locations must match the order from `Y`.
`W`	An `M x M` dimensional binary adjacency matrix for dictating the spatial neighborhood structure.
`Time`	A `Nu` dimensional vector containing the observed time points for each vector of outcomes in increasing order.
`Starting`	Either `NULL` or a `list` containing starting values to be specified for the MCMC sampler. If `NULL` is not chosen then none, some or all of the starting values may be specified. When `NULL` is chosen then default starting values are automatically generated. Otherwise a `list` must be provided with names `Delta`, `Alpha` or `Sigma` containing appropriate objects. `Delta` must be a `5` dimensional vector, `Sigma` a `5 x 5` dimensional matrix and `Alpha` a scalar.
`Hypers`	Either `NULL` or a `list` containing hyperparameter values to be specified for the MCMC sampler. If `NULL` is not chosen then none, some or all of the hyperparameter values may be specified. When `NULL` is chosen then default hyperparameter values are automatically generated. These default hyperparameters are described in detail in (Berchuck et al.). Otherwise a `list` must be provided with names `Delta`, `Sigma` or `Alpha` containing further hyperparameter information. These objects are themselves `lists` and may be constructed as follows. `Delta` is a `list` with one object, `Kappa2`. `Kappa2` represents the prior variance and must be a scalar. `Sigma` is a `list` with two objects, `Xi` and `Psi`. `Xi` represents the degrees of freedom parameter for the inverse-Wishart hyperprior and must be a real number scalar, while `Psi` represents the scale matrix and must be a `5 x 5` dimensional positive definite matrix. `Alpha` is a `list` with two objects, `AAlpha` and `BAlpha`. `AAlpha` represents the lower bound for the uniform hyperprior, while `BAlpha` represents the upper bound. The bounds must be specified carefully.
`Tuning`	Either `NULL` or a `list` containing tuning values to be specified for the MCMC Metropolis steps. If `NULL` is not chosen then all of the tuning values must be specified. When `NULL` is chosen then default tuning values are automatically generated to `1`. Otherwise a `list` must be provided with names `Lambda0Vec`, `Lambda1Vec`, `EtaVec` and `Alpha`. `Lambda0Vec`, `Lambda1Vec`, and `EtaVec` must be `M` dimensional vectors and `Alpha` a scalar. Each containing tuning variances for their corresponding Metropolis updates.
`MCMC`	Either `NULL` or a `list` containing input values to be used for implementing the MCMC sampler. If `NULL` is not chosen then all of the MCMC input values must be specified. `NBurn`: The number of sampler scans included in the burn-in phase. (default = `10,000`) `NSims`: The number of post-burn-in scans for which to perform the sampler. (default = `100,000`) `NThin`: Value such that during the post-burn-in phase, only every `NThin`-th scan is recorded for use in posterior inference (For return values we define, NKeep = NSims / NThin (default = `10`). `NPilot`: The number of times during the burn-in phase that pilot adaptation is performed (default = `20`)
`Family`	Character string indicating the distribution of the observed data. Options include: `"normal"`, `"probit"`, `"tobit"`.
`Weights`	Character string indicating the type of weight used. Options include: `"continuous"` and `"binary"`.
`Distance`	Character string indicating the distance metric for computing the dissimilarity metric. Options include: `"euclidean"` and `"circumference"`.
`Rho`	A scalar in `(0,1)` that dictates the magnitude of local spatial sharing. By default it is fixed at `0.99` as suggested by Lee and Mitchell (2012).
`ScaleY`	A positive scalar used for scaling the observed data, `Y`. This is used to aid numerically for MCMC convergence, as scaling large observations often stabilizes chains. By default it is fixed at `10`.
`ScaleDM`	A positive scalar used for scaling the dissimilarity metric distances, `DM`. This is used to aid numerically for MCMC convergence. as scaling spatial distances is often used for improved MCMC convergence. By default it is fixed at `100`.
`Seed`	An integer value used to set the seed for the random number generator (default = 54).

Details

Details of the underlying statistical model proposed by proposed by Berchuck et al. 2018. are forthcoming.

Value

spCP returns a list containing the following objects

beta0: NKeep x M matrix of posterior samples for beta0. The s-th column contains posterior samples from the the s-th location.
beta1: NKeep x M matrix of posterior samples for beta1. The s-th column contains posterior samples from the the s-th location.
lambda0: NKeep x M matrix of posterior samples for lambda0. The s-th column contains posterior samples from the the s-th location.
lambda1: NKeep x M matrix of posterior samples for lambda1. The s-th column contains posterior samples from the the s-th location.
eta: NKeep x M matrix of posterior samples for eta. The s-th column contains posterior samples from the the s-th location.
theta: NKeep x M matrix of posterior samples for theta. The s-th column contains posterior samples from the the s-th location.
delta: NKeep x 5 matrix of posterior samples for delta. The columns have names that describe the samples within them.
sigma: NKeep x 15 matrix of posterior samples for Sigma. The columns have names that describe the samples within them. The row is listed first, e.g., Sigma32 refers to the entry in row 3, column 2.
alpha: NKeep x 1 matrix of posterior samples for Alpha.
metropolis: (3 * M + 1) x 3 matrix of metropolis acceptance rates, updated tuners, and original tuners that result from the pilot adaptation. The first M correspond to the Lambda0Vec parameters, the next M correspond to the Lambda1Vec, the next M correspond to the EtaVec parameters and the last row give the Alpha values.
runtime: A character string giving the runtime of the MCMC sampler.
datobj: A list of data objects that are used in future spCP functions and should be ignored by the user.
dataug: A list of data augmentation objects that are used in future spCP functions and should be ignored by the user.