GARMA_NB: Fit Negative Binomial GARMA Model with Prediction

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

Fit Negative Binomial GARMA Model with Prediction

Description

This function fits a generalized autoregressive moving average (GARMA-NB) model for count data using a negative binomial distribution, and optionally generates posterior predictive counts for future covariate inputs.

Usage

GARMA_NB(
  cases,
  pop = NULL,
  covariates = NULL,
  p = 2,
  q = 2,
  c = 1,
  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("r", "beta", "phi", "theta"),
  covariatespred = NULL,
  poppred = NULL,
  casespred = NULL
)

Arguments

cases	Vector of observed counts (length N)
pop	Optional vector of population offsets (length N)
covariates	Optional numeric matrix (N x P) of covariates for the count component.
p	Integer, autoregressive order
q	Integer, moving average order
c	Constant added before log (default 1)
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"))
covariatespred	Optional numeric matrix (M x P) of new covariates for count prediction.
poppred	Optional vector of population offsets (length M) for prediction.
casespred	Optional vector of true counts (length M) for prediction performance.

Value

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

Examples

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



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

fit <- GARMA_NB(
  cases = cases,
  p = 1, q = 1,          #
  beta_prior_mean = 0,
  beta_prior_sd   = 5,
  r_prior_shape   = 2,
  r_prior_rate    = 0.5,
  n_iter   = 100,        # keep fast
  n_burnin = 10,
  n_chains = 1,
  n_thin   = 1
)
print(fit)


# ---- longer user-facing demo (skipped on checks) ----
# add a simple seasonal covariate and slightly higher orders
if (nzchar(Sys.which("jags")) && requireNamespace("R2jags", quietly = TRUE)) {
  x <- sin(2*pi*seq_along(cases)/12)
  fit2 <- GARMA_NB(
    cases = cases,
    p = 2, q = 1,
    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 <- GARMA_NB(
    cases = cases,
    p = 2, q = 2,
    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.