Package 'ZINB.GP'

gp_param_bounds

Description

Finds reasonable upper/lower bounds on gp parameters ensuring matrices remain pd invertible

Usage

gp_param_bounds(Ds, Dt, kernel, tolerance = 1e-10)

Arguments

Ds	Spatial distance matrix
Dt	Temporal distance matrix
kernel	Kernel function accepting a distance matrix and a length scale.
tolerance	Numerical tolerance used to assess matrix invertibility.

Value

A list containing the upper bounds ltmax and lsmax for the temporal and spatial length scales, respectively.

---

Squared Exponential Kernel

Description

Creates the kernel matrix exp(-dist / ls^2).

Usage

kernel(dist, ls)

Arguments

dist	Numeric distance matrix.
ls	Positive length scale.

Value

A numeric kernel matrix with the same dimensions as dist.

Examples

distances <- as.matrix(stats::dist(c(0, 1, 3)))
kernel(distances, ls = 2)

---

Build Inputs for Prediction at New GP Coordinates

Description

Creates the augmented distance matrices needed for Gaussian-process conditioning and indicator matrices mapping prediction observations to unique new spatial and temporal levels. The first observed level in each dimension is the baseline omitted by ZINB_GP() and is therefore excluded from the augmented distance matrix.

Usage

make_prediction_inputs(
  coords = NULL,
  time_coords = NULL,
  coords_new = NULL,
  time_coords_new = NULL
)

Arguments

coords	Observed spatial coordinate matrix, including the baseline as its first row. Use NULL for a temporal-only model.
time_coords	Observed temporal coordinate matrix, including the baseline as its first row. A numeric vector is treated as a one-column matrix. Use NULL for a spatial-only model.
coords_new	Spatial coordinates for the prediction observations, with one row per row of the new fixed-effect design matrix. Repeated rows share one predicted spatial random effect.
time_coords_new	Temporal coordinates for the prediction observations, with one row per row of the new fixed-effect design matrix. A numeric vector is treated as a one-column matrix. Repeated rows share one predicted temporal random effect.

Value

A list containing Ds_new, Dt_new, Vs_new, and Vt_new. Each non-NULL distance matrix covers the observed nonbaseline levels followed by the unique new levels. Each design matrix has one row per prediction observation and one column per unique new level.

Examples

observed_space <- rbind(c(0, 0), c(1000, 0), c(0, 1000))
observed_time <- c(0, 100)
new_space <- rbind(c(500, 500), c(500, 500), c(750, 250))
new_time <- c(150, 200, 150)
prediction_inputs <- make_prediction_inputs(
  coords = observed_space,
  time_coords = observed_time,
  coords_new = new_space,
  time_coords_new = new_time
)
prediction_inputs$Vs_new
prediction_inputs$Vt_new

---

make_y_Vs_Vt

Description

Create y, along with spatial and temporal design matrices from an observation matrix.

Usage

make_y_Vs_Vt(obs_matrix)

Arguments

obs_matrix

s by t matrix, where s is the number of locations, t is the number of times, each entry of the matrix is a nonnegative integer.

Value

A list with the following elements:

y

The observation matrix flattened in column-major order.

Vs

Spatial design matrix mapping observations to locations.

Vt

Temporal design matrix mapping observations to times.

Examples

counts <- matrix(c(0, 1, 2, 0, 1, 3), nrow = 2)
design <- make_y_Vs_Vt(counts)
design$y
design$Vs
design$Vt

---

mvn_sample_svd

Description

Use SVD for precision matrix to sample from multivariate normal distribution

Usage

mvn_sample_svd(P_svd, mu, entropy = NULL, threshold = 1e-12)

Arguments

P_svd	SVD of precision matrix
mu	Mean of MVN to draw from
entropy	Draw from MVN of correct size (can be used to draw all mvns at once for efficiency)
threshold	Singular values at or below this threshold are discarded.

Value

A draw from the multivariate normal distribution with precision matrix represented by P_svd.

---

Mix a Matrix with Identity Noise

Description

Creates noise_ratio * A + (1 - noise_ratio) * I.

Usage

noise_mix(A, noise_ratio)

Arguments

A	Numeric square matrix.
noise_ratio	Numeric mixing ratio between zero and one.

Value

A numeric square matrix with the same dimensions as A.

Examples

correlation <- matrix(c(1, 0.5, 0.5, 1), nrow = 2)
noise_mix(correlation, noise_ratio = 0.8)

---

nullcheck

Description

Returns default if value is null

Usage

nullcheck(value, default)

Arguments

value	Nullable
default	Default value

---

Predict at New Locations and Times

Description

Generates posterior predictive draws at new spatial locations, times, or both. For every retained MCMC iteration, the method draws each active random effect from its GP predictive distribution conditional on the stored fitted random effect, adds it to the corresponding fixed-effect predictor, and draws a zero-inflated negative-binomial response.

Usage

## S3 method for class 'zinb_gp_fit'
predict(
  object,
  X,
  Ds_new = NULL,
  Dt_new = NULL,
  Vs_new = NULL,
  Vt_new = NULL,
  kern = NULL,
  ...
)

Arguments

object	A fitted zinb_gp_fit object returned by ZINB_GP().
X	Fixed-effect design matrix for the prediction observations.
Ds_new	Augmented spatial distance matrix produced by make_prediction_inputs(), or NULL for a temporal-only fit.
Dt_new	Augmented temporal distance matrix produced by make_prediction_inputs(), or NULL for a spatial-only fit.
Vs_new	Spatial design matrix produced by make_prediction_inputs().
Vt_new	Temporal design matrix produced by make_prediction_inputs().
kern	Kernel function used to fit the model. The default is kernel(); supply the fitting kernel again if a custom kernel was used.
...	Unused.

Value

An object of class zinb_gp_prediction containing posterior draws Y_pred, eta_at_risk, and eta_count. Active predicted GP effects are returned under A, B, C, and D, matching the fitted object.

Examples

# Fit a small spatial model, then predict at two new locations.
cells <- expand.grid(spatial = seq_len(4), replicate = seq_len(12))
Vs <- diag(4)[cells$spatial, -1, drop = FALSE]
y <- c(
  0, 0, 0, 0, 15, 1, 0, 0, 6, 0, 0, 0, 1, 6, 0, 0,
  0, 0, 0, 1, 11, 0, 0, 0, 2, 0, 0, 0, 8, 0, 5, 0,
  0, 4, 0, 0, 34, 0, 1, 0, 0, 2, 0, 1, 0, 0, 0, 3
)
X <- cbind("(Intercept)" = 1, x = as.numeric(scale(seq_along(y))))
coords <- rbind(c(0, 0), c(1000, 0), c(0, 1000), c(1000, 1000))

set.seed(1)
fit <- ZINB_GP(
  X = X,
  y = y,
  coords = coords,
  nsim = 5,
  burn = 1,
  thin = 2,
  use_count_gp = TRUE,
  use_inflation_gp = FALSE,
  Vs = Vs,
  Ds = as.matrix(stats::dist(coords))
)

coords_new <- rbind(c(500, 500), c(250, 750))
inputs <- make_prediction_inputs(coords = coords, coords_new = coords_new)
X_new <- cbind("(Intercept)" = 1, x = c(-0.5, 0.5))
predictions <- predict(
  fit,
  X = X_new,
  Ds_new = inputs$Ds_new,
  Vs_new = inputs$Vs_new
)
predictions$Y_pred

---

Numerically stable sigmoid function

Description

Computes the inverse-logit transformation while clipping its output away from zero and one.

Usage

sigmoid(eta)

Arguments

eta	Numeric vector or matrix of linear predictors.

Value

eta transformed to probabilities in ⁠[1e-6, 1 - 1e-6]⁠.

---

solve_svd

Description

Use SVD to solve a linear system Ax=b

Usage

solve_svd(A_svd, b, threshold = 1e-12)

Arguments

A_svd	SVD of A
b	Right-hand-side vector or matrix.
threshold	Singular values at or below this threshold are discarded.

Value

The SVD-based solution to A %*% x = b.

---

update_ls_sigma_noise

Description

Update kernel parameters for a GP

Usage

update_ls_sigma_noise(
  ls,
  sigma,
  noise_ratio,
  gpdraw,
  K,
  D,
  lsPrior,
  sigmaPrior,
  noisePrior,
  kern
)

Arguments

ls	Current length scale
sigma	Current sigma
noise_ratio	Current noise ratio
gpdraw	Last draw from the gp with these parameters
K	Current kernel matrix
D	Distance matrix
lsPrior	prior information for length scale, needs mh_sd, max, a, b
sigmaPrior	prior information for sigma, needs a, b
noisePrior	prior information for noise_ratio, needs mh_sd, a, b
kern	Kernel function accepting a distance matrix and a length scale.

Value

A list with the following elements:

ls

Updated length scale.

sigma

Updated GP scale.

noise_ratio

Updated kernel-to-noise mixing ratio.

K

Updated kernel matrix.

K_inv

Inverse of the updated kernel matrix.

---

ZINB_GP

Description

Fits the zero-inflated negative-binomial Gaussian-process model described in doi:10.1016/j.jspi.2023.106098. The supplied spatial and temporal design and distance matrices determine which Gaussian processes are included.

Usage

ZINB_GP(
  X,
  y,
  coords,
  nsim = 5000,
  burn = 1000,
  use_count_gp = TRUE,
  use_inflation_gp = FALSE,
  thin = 1,
  kern = NULL,
  save_ypred = FALSE,
  print_iter = 100,
  print_progress = FALSE,
  Vs = NULL,
  Vt = NULL,
  Ds = NULL,
  Dt = NULL,
  ltPrior = NULL,
  lsPrior = NULL,
  sigmaPrior = NULL,
  noisePrior = NULL,
  mh_sd_r = NULL
)

Arguments

X	Fixed-effect design matrix with one row per observation.
y	Non-negative integer count response.
coords	Spatial coordinate matrix with one row per full spatial level, including the baseline level omitted from Vs.
nsim	Total number of MCMC iterations; must exceed burn.
burn	Number of burn-in iterations.
use_count_gp	Whether to include GP random effects in the count component.
use_inflation_gp	Whether to include GP random effects in the zero-inflation component.
thin	Store every thin-th iteration after burn-in.
kern	Kernel function accepting a distance matrix and length scale.
save_ypred	Whether to save posterior predictive draws.
print_iter	Report progress every print_iter iterations when print_progress is TRUE.
print_progress	Whether to report MCMC progress via message(); these reports can be silenced with suppressMessages().
Vs	Spatial random-effect design matrix with one row per observation and the baseline spatial column omitted.
Vt	Temporal random-effect design matrix with one row per observation and the baseline temporal column omitted.
Ds	Spatial distance matrix for all spatial levels, including the baseline; its diagonal must be zero.
Dt	Temporal distance matrix for all temporal levels, including the baseline; its diagonal must be zero.
ltPrior	List with max, mh_sd, a, and b for temporal length-scale prior and proposal controls.
lsPrior	List with max, mh_sd, a, and b for spatial length-scale prior and proposal controls.
sigmaPrior	List with a and b inverse-gamma prior parameters for GP scales.
noisePrior	List with a, b, and mh_sd for the GP noise-ratio prior and proposal.
mh_sd_r	Proposal standard deviation for the negative-binomial dispersion parameter.

Details

At least one spatial or temporal GP must be active in the count or zero-inflation component. Models with no active GP are outside this entry point and signal an error that points to standard GLM software instead.

Value

A list containing posterior MCMC draws:

Alpha

Fixed-effect coefficients for the zero-inflation component.

Beta

Fixed-effect coefficients for the count component.

A, B

Spatial and temporal random effects for the zero-inflation component.

C, D

Spatial and temporal random effects for the count component.

L1t, L2t

Temporal GP length scales for the zero-inflation and count components.

Sigma1t, Sigma2t

Temporal GP scale parameters.

L1s, L2s

Spatial GP length scales for the zero-inflation and count components.

Sigma1s, Sigma2s

Spatial GP scale parameters.

R

Negative-binomial dispersion parameter.

at_risk

Latent at-risk indicator draws, included when save_ypred is TRUE.

Y_pred

Posterior predictive count draws, included when save_ypred is TRUE.

Examples

# A small synthetic spatial example.
cells <- expand.grid(spatial = seq_len(4), replicate = seq_len(12))
Vs <- diag(4)[cells$spatial, -1, drop = FALSE]
y <- c(
  0, 0, 0, 0, 15, 1, 0, 0, 6, 0, 0, 0, 1, 6, 0, 0,
  0, 0, 0, 1, 11, 0, 0, 0, 2, 0, 0, 0, 8, 0, 5, 0,
  0, 4, 0, 0, 34, 0, 1, 0, 0, 2, 0, 1, 0, 0, 0, 3
)
X <- cbind("(Intercept)" = 1, x = as.numeric(scale(seq_along(y))))
coords <- rbind(c(0, 0), c(1000, 0), c(0, 1000), c(1000, 1000))

set.seed(1)
fit <- ZINB_GP(
  X = X,
  y = y,
  coords = coords,
  nsim = 5,
  burn = 1,
  thin = 2,
  use_count_gp = TRUE,
  use_inflation_gp = FALSE,
  Vs = Vs,
  Ds = as.matrix(stats::dist(coords))
)
names(fit)

---

ZINB_GP_count

Description

Run the ZINB GP model with GP random effects only in the count part.

Usage

ZINB_GP_count(
  X,
  y,
  coords,
  Vs,
  Vt,
  Ds,
  Dt,
  nsim,
  burn,
  thin = 1,
  save_ypred = FALSE,
  print_iter = 100,
  print_progress = FALSE,
  ltPrior = NULL,
  lsPrior = NULL,
  sigmaPrior = NULL,
  noisePrior = NULL,
  mh_sd_r = NULL,
  kern = NULL
)

Arguments

X	Fixed-effect design matrix with one row per observation.
y	Non-negative integer count response.
coords	Spatial coordinate matrix with one row per full spatial level, including the baseline level omitted from Vs.
Vs	Spatial random-effect design matrix with one row per observation.
Vt	Temporal random-effect design matrix with one row per observation.
Ds	Spatial distance matrix; its diagonal must be zero.
Dt	Temporal distance matrix; its diagonal must be zero.
nsim	Total number of MCMC iterations; must exceed burn.
burn	Number of burn-in iterations.
thin	Store every thin-th iteration after burn-in.
save_ypred	Whether to save posterior predictive draws.
print_iter	Print progress every print_iter iterations.
print_progress	Whether to print MCMC progress.
ltPrior	List with max, mh_sd, a, and b for temporal length-scale prior and proposal controls.
lsPrior	List with max, mh_sd, a, and b for spatial length-scale prior and proposal controls.
sigmaPrior	List with a and b inverse-gamma prior parameters for GP scales.
noisePrior	List with a, b, and mh_sd for the GP noise-ratio prior and proposal.
mh_sd_r	Proposal standard deviation for the negative-binomial dispersion parameter.
kern	Kernel function accepting a distance matrix and length scale.

Value

A list containing posterior MCMC draws for the count GP, fixed effects, and the negative-binomial dispersion parameter.

---

ZINB_GP_inflation

Description

Run the ZINB GP model with GP random effects only in the inflation component

Usage

ZINB_GP_inflation(
  X,
  y,
  coords,
  Vs,
  Vt,
  Ds,
  Dt,
  nsim,
  burn,
  thin = 1,
  save_ypred = FALSE,
  print_iter = 100,
  print_progress = FALSE,
  ltPrior = NULL,
  lsPrior = NULL,
  sigmaPrior = NULL,
  noisePrior = NULL,
  mh_sd_r = NULL,
  kern = NULL
)

Arguments

X	Fixed-effect design matrix with one row per observation.
y	Non-negative integer count response.
coords	Spatial coordinate matrix with one row per full spatial level, including the baseline level omitted from Vs.
Vs	Spatial random-effect design matrix with one row per observation.
Vt	Temporal random-effect design matrix with one row per observation.
Ds	Spatial distance matrix; its diagonal must be zero.
Dt	Temporal distance matrix; its diagonal must be zero.
nsim	Total number of MCMC iterations; must exceed burn.
burn	Number of burn-in iterations.
thin	Store every thin-th iteration after burn-in.
save_ypred	Whether to save posterior predictive draws.
print_iter	Print progress every print_iter iterations.
print_progress	Whether to print MCMC progress.
ltPrior	List with max, mh_sd, a, and b for temporal length-scale prior and proposal controls.
lsPrior	List with max, mh_sd, a, and b for spatial length-scale prior and proposal controls.
sigmaPrior	List with a and b inverse-gamma prior parameters for GP scales.
noisePrior	List with a, b, and mh_sd for the GP noise-ratio prior and proposal.
mh_sd_r	Proposal standard deviation for the negative-binomial dispersion parameter.
kern	Kernel function accepting a distance matrix and length scale.

Value

A list containing posterior MCMC draws for the zero-inflation GP, fixed effects, and the negative-binomial dispersion parameter.

---

ZINB_GP_orig

Description

Fits the spatial-temporal zero-inflated negative-binomial Gaussian-process model described in doi:10.1016/j.jspi.2023.106098.

Usage

ZINB_GP_orig(
  X,
  y,
  coords,
  Vs,
  Vt,
  Ds,
  Dt,
  nsim,
  burn,
  thin = 1,
  save_ypred = FALSE,
  print_iter = 100,
  print_progress = FALSE,
  ltPrior = NULL,
  lsPrior = NULL,
  sigmaPrior = NULL,
  noisePrior = NULL,
  mh_sd_r = NULL,
  kern = NULL
)

Arguments

X	Fixed-effect design matrix with one row per observation.
y	Non-negative integer count response.
coords	Spatial coordinate matrix with one row per full spatial level, including the baseline level omitted from Vs.
Vs	Spatial random-effect design matrix with one row per observation.
Vt	Temporal random-effect design matrix with one row per observation.
Ds	Spatial distance matrix; its diagonal must be zero.
Dt	Temporal distance matrix; its diagonal must be zero.
nsim	Total number of MCMC iterations; must exceed burn.
burn	Number of burn-in iterations.
thin	Store every thin-th iteration after burn-in.
save_ypred	Whether to save posterior predictive draws.
print_iter	Print progress every print_iter iterations.
print_progress	Whether to print MCMC progress.
ltPrior	List with max, mh_sd, a, and b for temporal length-scale prior and proposal controls.
lsPrior	List with max, mh_sd, a, and b for spatial length-scale prior and proposal controls.
sigmaPrior	List with a and b inverse-gamma prior parameters for GP scales.
noisePrior	List with a, b, and mh_sd for the GP noise-ratio prior and proposal.
mh_sd_r	Proposal standard deviation for the negative-binomial dispersion parameter.
kern	Kernel function accepting a distance matrix and length scale.

Value

A list containing posterior MCMC draws, including fixed-effect coefficients, spatial and temporal random effects, their GP parameters, the negative-binomial dispersion parameter, and optional predictive draws.

---

ZINB_GP_spatial

Description

Fit a zero-inflated negative-binomial model with spatial Gaussian-process random effects in both the zero-inflation and count components.

Usage

ZINB_GP_spatial(
  X,
  y,
  Vs,
  Ds,
  nsim,
  burn,
  thin = 1,
  save_ypred = FALSE,
  print_iter = 100,
  print_progress = FALSE,
  lsPrior = NULL,
  sigmaPrior = NULL,
  noisePrior = NULL,
  mh_sd_r = NULL,
  kern = NULL
)

Arguments

X	Fixed-effect design matrix with N rows.
y	Non-negative integer count response of length N.
Vs	Sparse or dense spatial random-effect design matrix. It should have N rows and one column per spatial location.
Ds	Spatial distance matrix with one row and column per full spatial level, including the baseline level omitted from Vs. Diagonal entries must be zero.
nsim	Total number of MCMC iterations.
burn	Number of burn-in iterations.
thin	Store every thin-th iteration after burn-in.
save_ypred	Whether to save posterior predictive counts and at-risk draws.
print_iter	Print progress every print_iter iterations.
print_progress	Whether to print MCMC progress.
lsPrior	Prior and proposal controls for spatial GP length scales.
sigmaPrior	Inverse-gamma prior parameters for GP variances.
noisePrior	Beta prior and MH controls for GP noise ratios.
mh_sd_r	Proposal standard deviation for NB dispersion r.
kern	Kernel function accepting a squared-distance matrix and a length scale.

Value

A list containing posterior MCMC draws.

---

ZINB_GP_spatial_count

Description

Fit a zero-inflated negative-binomial model with spatial Gaussian-process random effects in only the count component.

Usage

ZINB_GP_spatial_count(
  X,
  y,
  Vs,
  Ds,
  nsim,
  burn,
  thin = 1,
  save_ypred = FALSE,
  print_iter = 100,
  print_progress = FALSE,
  lsPrior = NULL,
  sigmaPrior = NULL,
  noisePrior = NULL,
  mh_sd_r = NULL,
  kern = NULL
)

Arguments

X	Fixed-effect design matrix with N rows.
y	Non-negative integer count response of length N.
Vs	Sparse or dense spatial random-effect design matrix. It should have N rows and one column per spatial location.
Ds	Spatial distance matrix with one row and column per full spatial level, including the baseline level omitted from Vs. Diagonal entries must be zero.
nsim	Total number of MCMC iterations.
burn	Number of burn-in iterations.
thin	Store every thin-th iteration after burn-in.
save_ypred	Whether to save posterior predictive counts and at-risk draws.
print_iter	Print progress every print_iter iterations.
print_progress	Whether to print MCMC progress.
lsPrior	Prior and proposal controls for spatial GP length scales.
sigmaPrior	Inverse-gamma prior parameters for GP variances.
noisePrior	Beta prior and MH controls for GP noise ratios.
mh_sd_r	Proposal standard deviation for NB dispersion r.
kern	Kernel function accepting a squared-distance matrix and a length scale.

Value

A list containing posterior MCMC draws.

---

ZINB_GP_spatial_inflation

Description

Fit a zero-inflated negative-binomial model with spatial Gaussian-process random effects in only the inflation part.

Usage

ZINB_GP_spatial_inflation(
  X,
  y,
  Vs,
  Ds,
  nsim,
  burn,
  thin = 1,
  save_ypred = FALSE,
  print_iter = 100,
  print_progress = FALSE,
  lsPrior = NULL,
  sigmaPrior = NULL,
  noisePrior = NULL,
  mh_sd_r = NULL,
  kern = NULL
)

Arguments

X	Fixed-effect design matrix with N rows.
y	Non-negative integer count response of length N.
Vs	Sparse or dense spatial random-effect design matrix. It should have N rows and one column per spatial location.
Ds	Spatial distance matrix with one row and column per full spatial level, including the baseline level omitted from Vs. Diagonal entries must be zero.
nsim	Total number of MCMC iterations.
burn	Number of burn-in iterations.
thin	Store every thin-th iteration after burn-in.
save_ypred	Whether to save posterior predictive counts and at-risk draws.
print_iter	Print progress every print_iter iterations.
print_progress	Whether to print MCMC progress.
lsPrior	Prior and proposal controls for spatial GP length scales.
sigmaPrior	Inverse-gamma prior parameters for GP variances.
noisePrior	Beta prior and MH controls for GP noise ratios.
mh_sd_r	Proposal standard deviation for NB dispersion r.
kern	Kernel function accepting a squared-distance matrix and a length scale.

Value

A list containing posterior MCMC draws.

---