NB: Fit Negative Binomial Model with Arbitrary Covariates

In sparsesurv: Forecasting and Early Outbreak Detection for Sparse Count Data

Fit Negative Binomial Model with Arbitrary Covariates

Description

Fits a negative binomial (NB) model using JAGS, with an optional design matrix of covariates and full inprod for mean structure, and can generate posterior predictive counts for new covariate data.

Usage

NB(
  cases,
  pop = NULL,
  casespred = NULL,
  covariates = NULL,
  covariatespred = NULL,
  poppred = NULL,
  beta_init = NULL,
  r_init = NULL,
  beta_prior_mean = 0,
  beta_prior_sd = 10,
  r_prior_shape = 1,
  r_prior_rate = 1,
  n_iter = 1e+05,
  n_burnin = 10000,
  n_chains = 3,
  n_thin = 1,
  save_params = c("beta", "r")
)

Arguments

cases	Vector of observed counts (length N)
pop	Optional vector of population offsets (length N)
casespred	Optional vector of true counts (length M) for prediction performance.
covariates	Optional numeric matrix (N x P) of covariates for the count component.
covariatespred	Optional numeric matrix (M x P) of new covariates for count prediction.
poppred	Optional vector of population offsets (length M) for prediction.
beta_init	Optional list of length n_chains for beta, count coefficients initial values.
r_init	Optional numeric vector of length n_chains for dispersion parameter.
beta_prior_mean	Mean for beta prior (default: 0)
beta_prior_sd	SD for beta prior (default: 10)
r_prior_shape	Shape for r ~ dgamma (default: 1)
r_prior_rate	Rate for r ~ dgamma (default: 1)
n_iter	Total MCMC iterations (default: 100000)
n_burnin	Burn-in iterations (default: 10000)
n_chains	Number of chains (default: 3)
n_thin	Thinning interval (default: 1)
save_params	Character vector of parameters to save (default c("beta","delta","r"))

Value

A list with MCMC summary, samples, DIC, and if prediction data provided: prediction_matrix, prediction_mean, mae, rmse

Examples

# ---- tiny example for users & CRAN (< 5s) ----
set.seed(4)
cases <- rnbinom(80, size = 5, mu = 7)  # toy NB series


# ---- actually fit the model, but only when JAGS is available ----

fit <- NB(
  cases = cases,
  # add pop = ... here if your NB function supports offsets
  beta_prior_mean = 0,
  beta_prior_sd   = 5,
  r_prior_shape   = 2,
  r_prior_rate    = 0.5,
  n_iter   = 400,           # keep fast
  n_burnin = 200,
  n_chains = 1,
  n_thin   = 2
)
print(fit)


# ---- longer user-facing demo (skipped on checks) ----
if (nzchar(Sys.which("jags")) && requireNamespace("R2jags", quietly = TRUE)) {
  x <- sin(2*pi*seq_along(cases)/12)
  fit2 <- NB(
    cases = cases,
    covariates = cbind(x),  # simple seasonal regressor
    beta_prior_mean = 0,
    beta_prior_sd   = 5,
    r_prior_shape   = 2,
    r_prior_rate    = 0.5,
    n_iter   = 1000,
    n_burnin = 100,
    n_chains = 2,
    n_thin   = 2
  )
  print(fit2)
  # if a plot method exists:  # plot(fit2)
}


## Not run: 
# ---- time-consuming / full demo ----
if (nzchar(Sys.which("jags")) && requireNamespace("R2jags", quietly = TRUE)) {
  fit_full <- NB(
    cases = cases,
    covariates = cbind(x),  # simple seasonal regressor
    n_iter   = 100000,
    n_burnin = 10000,
    n_chains = 4,
    n_thin   = 5
  )
  print(fit_full)
}

## End(Not run)

if (interactive()) {
  # e.g., plot(fit)
}

sparsesurv documentation built on Sept. 11, 2025, 9:11 a.m.