STBDwDM {womblR}

MCMC sampler for spatiotemporal boundary detection with dissimilarity metric.

Description

STBDwDM is a Markov chain Monte Carlo (MCMC) sampler for a spatiotemporal boundary detection model using the Bayesian hierarchical framework.

Usage

STBDwDM(
  Y,
  DM,
  W,
  Time,
  Starting = NULL,
  Hypers = NULL,
  Tuning = NULL,
  MCMC = NULL,
  Family = "tobit",
  TemporalStructure = "exponential",
  Distance = "circumference",
  Weights = "continuous",
  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 neigborhood 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, T or Phi containing appropriate objects. Delta must be a 3 dimensional vector, T a 3 x 3 dimensional matrix and Phi 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, T or Phi containing further hyperparameter information. These objects are themselves lists and may be constructed as follows.

Delta is a list with two objects, MuDelta and OmegaDelta. MuDelta represents the mean component of the multivariate normal hyperprior and must be a 3 dimensional vector, while OmegaDelta represents the covariance and must be a 3 x 3 dimensional matrix.

T 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 3 x 3 dimensional positive definite matrix.

Phi is a list with two objects, APhi and BPhi. APhi represents the lower bound for the uniform hyperprior, while BPhi represents the upper bound. The bounds must be specified carefully. For example, if the exponential temporal correlation structure is chosen both bounds must be restricted to be non-negative.

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 Theta2, Theta3 and Phi. Theta2 and Theta3 must be Nu dimensional vectors and Phi 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".

TemporalStructure

Character string indicating the temporal structure of the time observations. Options include: "exponential" and "ar1".

Distance

Character string indicating the distance metric for computing the dissimilarity metric. Options include: "euclidean" and "circumference".

Weights

Character string indicating the type of weight used. Options include: "continuous" and "binary".

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 can be found in the article by Berchuck et al. (2018), "Diagnosing Glaucoma Progression with Visual Field Data Using a Spatiotemporal Boundary Detection Method", <arXiv:1805.11636>.

Value

STBDwDM returns a list containing the following objects

mu

NKeep x Nu matrix of posterior samples for mu. The t-th column contains posterior samples from the the t-th time point.

tau2

NKeep x Nu matrix of posterior samples for tau2. The t-th column contains posterior samples from the the t-th time point.

alpha

NKeep x Nu matrix of posterior samples for alpha. The t-th column contains posterior samples from the the t-th time point.

delta

NKeep x 3 matrix of posterior samples for delta. The columns have names that describe the samples within them.

T

NKeep x 6 matrix of posterior samples for T. The columns have names that describe the samples within them. The row is listed first, e.g., t32 refers to the entry in row 3, column 2.

phi

NKeep x 1 matrix of posterior samples for phi.

metropolis

(2 * Nu + 1) x 2 matrix of metropolis acceptance rates and tuners that result from the pilot adaptation. The first Nu correspond to the Theta2 (i.e. tau2) parameters, the next Nu correspond to the Theta3 (i.e. alpha) parameters and the last row give the phi values.

runtime

A character string giving the runtime of the MCMC sampler.

datobj

A list of data objects that are used in future STBDwDM functions and should be ignored by the user.

dataug

A list of data augmentation objects that are used in future STBDwDM functions and should be ignored by the user.

Author(s)

Samuel I. Berchuck

References

Berchuck et al. (2018), "Diagnosing Glaucoma Progression with Visual Field Data Using a Spatiotemporal Boundary Detection Method", <arXiv:1805.11636>.