Package {ZINB.GP}

Title:	Bayesian Zero-Inflated Negative Binomial Gaussian Process Models
Version:	1.0.0
Description:	Fits Bayesian zero-inflated negative binomial regression models with Gaussian process random effects for spatial, temporal, or spatiotemporal count data. Provides Markov chain Monte Carlo sampling, configurable random effects in the zero-inflation and count components, and posterior predictive draws. Implements a full GP version of the methods described by He and Huang (2024) <doi:10.1016/j.jspi.2023.106098>.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
URL:	https://github.com/KingJMS1/GP_ZINB_R, https://kingjms1.github.io/GP_ZINB_R/
BugReports:	https://github.com/KingJMS1/GP_ZINB_R/issues
Imports:	BayesLogit, LaplacesDemon, MASS, Matrix, msm, mvtnorm, stats
Suggests:	coda, knitr, posterior, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-09-04 15:46:22 UTC; 1king
Author:	Mahlon Scott [aut], Qing He [aut], Hsin-Hsiung Huang [aut, cre, cph]
Maintainer:	Hsin-Hsiung Huang <hsin.huang@ucf.edu>
Repository:	CRAN
Date/Publication:	2026-09-14 15:40:10 UTC

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

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

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

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

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

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

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

Value

A list containing posterior MCMC draws.

Draw a GP at New Levels Conditional on a Stored Draw

Description

Draw a GP at New Levels Conditional on a Stored Draw

Usage

draw_conditional_gp(effect, distance, length_scale, sigma, noise_ratio, kern)

Arguments

Value

A numeric draw at the new levels.

Draw a Zero-Inflated Negative-Binomial Response

Description

Generates one posterior predictive count for each pair of at-risk and count linear predictors using the parameterization fitted by ZINB_GP().

Usage

draw_zinb_response(eta_at_risk, eta_count, r)

Arguments

Value

A non-negative integer vector with one predictive count per linear predictor pair.

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

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

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

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

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

Value

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

Mark Model Output as a ZINB-GP Fit

Description

Mark Model Output as a ZINB-GP Fit

Usage

new_zinb_gp_fit(output)

Arguments

Value

The output with its model class attached.

Mix a Matrix with Identity Noise

Description

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

Usage

noise_mix(A, noise_ratio)

Arguments

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

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

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

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

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

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.

Validate a GP Design and Distance Matrix

Description

Checks that a baseline-coded GP design is aligned with the observations and that its distance matrix contains one additional row and column for the omitted baseline level.

Usage

validate_gp_design(V, D, n_observations, design_name, distance_name)

Arguments

Value

TRUE, invisibly, when the design and distance matrix are valid. Otherwise, the function stops with an input-specific error message.

Validate Spatial Coordinate Alignment

Description

Confirms that the full coordinate matrix, the baseline-coded spatial design, and the spatial distance matrix describe the same number of spatial levels.

Usage

validate_spatial_coordinates(coords, Vs, Ds)

Arguments

Value

TRUE, invisibly, when the spatial inputs are aligned. Otherwise, the function stops with an input-specific error message.

Validate ZINB Model Inputs

Description

Checks the fixed-effect design, count response, and MCMC controls shared by the branch-specific ZINB-GP samplers.

Usage

validate_zinb_inputs(X, y, nsim, burn, thin)

Arguments

Value

TRUE, invisibly, when all inputs are valid. Otherwise, the function stops with an input-specific error message.

Conditional At-Risk Probability for an Observed Zero

Description

Computes the conditional probability that an observation belongs to the negative-binomial, or at-risk, component given that its observed count is zero. The calculation is performed on the log-odds scale for numerical stability.

Usage

zero_at_risk_probability(pi, q, r)

Arguments

Value

A numeric vector or matrix with the same shape as pi and q, containing probabilities between zero and one.