Type:	Package
Title:	Spatiotemporal Boundary Detection Model for Areal Unit Data
Version:	1.0.5
Description:	Implements a spatiotemporal boundary detection model with a dissimilarity metric for areal data with inference in a Bayesian setting using Markov chain Monte Carlo (MCMC). The response variable can be modeled as Gaussian (no nugget), probit or Tobit link and spatial correlation is introduced at each time point through a conditional autoregressive (CAR) prior. Temporal correlation is introduced through a hierarchical structure and can be specified as exponential or first-order autoregressive. Full details of the package can be found in the accompanying vignette. Furthermore, the details of the package can be found in "Diagnosing Glaucoma Progression with Visual Field Data Using a Spatiotemporal Boundary Detection Method", by Berchuck et al (2018), <doi:10.48550/arXiv.1805.11636>. The paper is in press at the Journal of the American Statistical Association.
Date:	2022-09-04
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.1
NeedsCompilation:	yes
Depends:	R (≥ 3.0.2)
Imports:	graphics, grDevices, msm (≥ 1.0.0), mvtnorm (≥ 1.0-0), Rcpp (≥ 0.12.9), stats, utils
Suggests:	coda, classInt, knitr, rmarkdown
LinkingTo:	Rcpp, RcppArmadillo (≥ 0.7.500.0.0)
VignetteBuilder:	knitr
Packaged:	2022-09-05 00:34:59 UTC; sib2
Author:	Samuel I. Berchuck [aut, cre]
Maintainer:	Samuel I. Berchuck <sib2@duke.edu>
Repository:	CRAN
Date/Publication:	2022-09-05 06:10:02 UTC

Garway-Heath angles for the HFA-II

Description

These Garway-Heath angles are used as the dissimilarity metric when implementing the boundary detection model for a longitudinal series of visual fields.

Usage

data(GarwayHeath)

Format

A vector with length 54, where each entry represents the angle (in degrees) that the underlying retinal nerve fiber enters the optic nerve head. The measure ranges from 0-360, where 0 is designated at the 9-o’clock position (right eye) and angles are counted counter clockwise. These angles are estimates for the Humphrey Field Analyzer-II (Carl Zeiss Meditec Inc., Dublin, CA). The 26th and 35th entries are missing as they correspond to a natural blind spot.

References

Garway-Heath, et al. (2000). Ophthalmology 107:10:1809–1815. (PubMed)

HFAII Queen Adjacency Matrix

Description

Binary adjacency matrix for the Humphrey Field Analyzer-II (Carl Zeiss Meditec Inc., Dublin, CA)

Usage

data(HFAII_Queen)

Format

This adjacency matrix is formated using queen neighbor criteria, meaning two locations on the visual field are only considered neighbors if they share an edge or corner. The adjacency matrix is a 54 x 54 dimensional binary object with zeros on the diagonal and the column and row sums are equal to the number of neighbors.

HFAII Queen Hemisphere Adjacency Matrix

Description

Binary adjacency matrix for the Humphrey Field Analyzer-II (Carl Zeiss Meditec Inc., Dublin, CA)

Usage

data(HFAII_QueenHF)

Format

This adjacency matrix is formated using queen neighbor criteria, meaning two locations on the visual field are only considered neighbors if they share an edge or corner. An additional criterion is included that locations are not considered neighbors if they fall within different hemispheres on the visual field. The adjacency matrix is a 54 x 54 dimensional binary object with zeros on the diagonal and the column and row sums are equal to the number of neighbors.

HFAII Rook Adjacency Matrix

Description

Binary adjacency matrix for the Humphrey Field Analyzer-II (Carl Zeiss Meditec Inc., Dublin, CA)

Usage

data(HFAII_Rook)

Format

This adjacency matrix is formated using rook neighbor criteria, meaning two locations on the visual field are only considered neighbors if they share an edge. The adjacency matrix is a 54 x 54 dimensional binary object with zeros on the diagonal and the column and row sums are equal to the number of neighbors.

PlotAdjacency

Description

Plots a heat map of the differential light sensitivity on the Humphrey Field Analyzer-II visual field.

Usage

PlotAdjacency(
  Wij,
  Visit = 1,
  stat = "mean",
  main = "Estimated Adjacencies",
  color.scheme = c("Black", "White"),
  edgewidth = 2,
  cornerwidth = 1/4,
  lwd.border = 3,
  color.bs = "gray",
  zlim = c(0, 1),
  legend = TRUE,
  DM = NULL,
  W = NULL
)

Arguments

Details

PlotAdjacency is used in the application of glaucoma progression to plot the posterior mean and standard deviation neighborhood adjacencies across the visual field.

Author(s)

Samuel I. Berchuck

Examples

###Define blind spot locations on the HFA-II
blind_spot <- c(26, 35)

###Load visual field adjacency matrix
W <- HFAII_Queen[ -blind_spot, -blind_spot]

###Load Garway-Heath angles for dissimiliarity metric
DM <- GarwayHeath[-blind_spot] #Uses Garway-Heath angles object "GarwayHeath"

###Adjacency plots
PlotAdjacency(W = W, DM = DM, zlim = c(0, 180), Visit = NA,
              main = "Garway-Heath dissimilarity metric\n across the visual field")

PlotSensitivity

Description

Plots a heat map of the differential light sensitivity on the Humphrey Field Analyzer-II visual field.

Usage

PlotSensitivity(
  Y = Y,
  main = "Sensitivity Estimate (dB) at each \nlocation on visual field",
  legend.lab = "DLS (dB)",
  zlim = c(10, 35),
  bins = 200,
  border = TRUE,
  legend = TRUE,
  color = c("yellow", "orange", "red"),
  col.bs = "grey",
  legend.round = 0,
  legend.vals = 5
)

Arguments

Details

PlotSensitivity is used in the application of glaucoma progression to plot a variable across the visual field in the form of a heat map.

Author(s)

Samuel I. Berchuck

Examples

data(VFSeries)
PlotSensitivity(Y = VFSeries$DLS[VFSeries$Visit == 1],
                  main = "Sensitivity estimate (dB) at each \n location on visual field",
                  legend.lab = "DLS (dB)",
                  zlim = c(10, 35),
                  bins = 250)

PlotVfTimeSeries

Description

Plots a time series at each location of the Humphrey Field Analyzer-II visual field .

Usage

PlotVfTimeSeries(
  Y,
  Location,
  Time,
  main = "Visual field sensitivity time series \n at each location",
  xlab = "Time from first visit (days)",
  ylab = "Sensitivity (dB)",
  line.col = "red",
  line.reg = TRUE,
  line.type = 1
)

Arguments

Details

PlotVfTimeSeries is used in the application of glaucoma progression. In each cell is the observed DLS at each location over visits, with the red line representing a linear regression trend.

Author(s)

Samuel I. Berchuck

Examples

data(VFSeries)
PlotVfTimeSeries(Y = VFSeries$DLS,
                  Location = VFSeries$Location,
                  Time = VFSeries$Time,
                  main = "Visual field sensitivity time series \n at each location",
                  xlab = "Days from baseline visit",
                  ylab = "Differential light sensitivity (dB)")

PosteriorAdj

Description

Calculates the posterior mean and standard deviation for the neighborhood adjacencies from the STBDwDM model.

Usage

PosteriorAdj(object)

Arguments

Details

The function PosteriorAdj calculates the posterior mean and standard deviation of the neighborhood adjacencies for each pairwise location. The neighborhood structure used to do this comes from Berchuck et al. 2017.

Value

PosteriorAdj returns a matrix containing the following columns.

i

Location i (i.e. which row/column on the adjacency matrix W).

j

Location j (i.e. which row/column on the adjacency matrix W).

DM

The dissimilarity metric between locations i and j.

meant

The posterior mean of the neighborhood adjacency between location i and j at time t, t = 1, ... , Nu.

sdt

The posterior mean of the neighborhood adjacency between location i and j at time t, t = 1, ... , Nu.

Author(s)

Samuel I. Berchuck

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

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>.

Visual field series for one patient.

Description

A dataset containing 9 visual field series from a patient of the Vein Pulsation Study Trial in Glaucoma and the Lions Eye Institute trial registry, Perth, Western Australia.

Usage

data(VFSeries)

Format

A data frame with 486 rows and 4 variables:

Visit

The visual field test visit number, (1, 2, ... , 9).

DLS

The observed outcome variable, differential light sensitivity (DLS).

Time

The time of the visual field test (in days from baseline).

Location

The location on the visual field of a Humphrey Field Analyzer-II (Carl Zeiss Meditec Inc., Dublin, CA) (1, 2, ... , 54).

Source

https://anzctr.org.au/Trial/Registration/TrialReview.aspx?ACTRN=12608000274370

diagnostics

Description

Calculates diagnostic metrics using output from the STBDwDM model.

Usage

diagnostics(
  obj,
  diags = c("dic", "dinf", "waic"),
  keepDeviance = FALSE,
  keepPPD = FALSE
)

Arguments

Details

To assess model fit, DIC, d-infinity and WAIC are used. DIC is based on the deviance statistic and penalizes for the complexity of a model with an effective number of parameters estimate pD (Spiegelhalter et al 2002). The d-infinity posterior predictive measure is an alternative diagnostic tool to DIC, where d-infinity=P+G. The G term decreases as goodness of fit increases, and P, the penalty term, inflates as the model becomes over-fit, so small values of both of these terms and, thus, small values of d-infinity are desirable (Gelfand and Ghosh 1998). WAIC is invariant to parametrization and is asymptotically equal to Bayesian cross-validation (Watanabe 2010). WAIC = -2 * (lppd - p_waic_2). Where lppd is the log pointwise predictive density and p_waic_2 is the estimated effective number of parameters based on the variance estimator from Vehtari et al. 2016. (p_waic_1 is the mean estimator).

Value

diagnostics returns a list containing the diagnostics requested and possibly the deviance and/or posterior predictive distribution objects.

Author(s)

Samuel I. Berchuck

References

Gelfand, A. E., & Ghosh, S. K. (1998). Model choice: a minimum posterior predictive loss approach. Biometrika, 1-11.

Spiegelhalter, D. J., Best, N. G., Carlin, B. P., & Van Der Linde, A. (2002). Bayesian measures of model complexity and fit. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 64(4), 583-639.

Vehtari, A., Gelman, A., & Gabry, J. (2016). Practical Bayesian model evaluation using leave-one-out cross-validation and WAIC. Statistics and Computing, 1-20.

Watanabe, S. (2010). Asymptotic equivalence of Bayes cross validation and widely applicable information criterion in singular learning theory. Journal of Machine Learning Research, 11(Dec), 3571-3594.

is.PosteriorAdj

Description

is.PosteriorAdj is a general test of an object being interpretable as a PosteriorAdj object.

Usage

is.PosteriorAdj(x)

Arguments

Details

The PosteriorAdj class is defined as the posterior adjacency object that results from the PosteriorAdj function.

is.STBDwDM

Description

is.STBDwDM is a general test of an object being interpretable as a STBDwDM object.

Usage

is.STBDwDM(x)

Arguments

Details

The STBDwDM class is defined as the regression object that results from the STBDwDM regression function.

predict.STBDwDM

Description

Predicts future observations from the STBDwDM model.

Usage

## S3 method for class 'STBDwDM'
predict(object, NewTimes, ...)

Arguments

Details

predict.STBDwDM uses Bayesian krigging to predict vectors at future time points. The function returns the krigged observed outcomes along with the observational level parameters (mu, tau, and alpha).

Value

predict.STBDwDM returns a list containing the following objects.

MuTauAlpha

A list containing three matrices, mu, tau and alpha. Each matrix is dimension NKeep x s, where s is the number of new time points. Each matrix contains posterior samples obtained by Bayesian krigging.

Y

A list containing s posterior predictive distribution matrices. Each matrix is dimension NKeep x s, where s is the number of new time points. Each matrix is obtained through Bayesian krigging.

Author(s)

Samuel I. Berchuck

womblR

Description

This package implements a spatiotemporal boundary detection with a dissimilarity metric for areal data with inference in a Bayesian setting using Markov chain Monte Carlo (MCMC). The response variable can be modeled as Gaussian (no nugget), probit or Tobit link and spatial correlation is introduced at each time point through a conditional autoregressive (CAR) prior. Temporal correlation is introduced through a hierarchical structure and can be specified as exponential or first-order autoregressive. Full details of the the package can be found in the accompanying vignette. Furthermore, the details of the package can be found in "Diagnosing Glaucoma Progression with Visual Field Data Using a Spatiotemporal Boundary Detection Method", by Berchuck et al (2018), <arXiv:1805.11636>. The paper is in press at the Journal of the American Statistical Association.

Author(s)

Samuel I. Berchuck sib2@duke.edu