poisson: Poisson regression or Poisson family

In R4VN: Health Data Analysis and Publication-Ready Reporting

Poisson regression or Poisson family

Description

Fits Poisson regression using formula syntax or compact R4VN syntax. When called without a model, for example poisson() or poisson(link = "identity"), returns the ordinary stats::poisson() family. A binary outcome is also supported; event explicitly identifies the event category and rr = TRUE requests a risk-ratio display. Robust or cluster-robust VCE is generally appropriate for modified-Poisson binary models.

Usage

poisson(
  y, ..., vars = NULL, data = NULL, exposure = NULL, offset = NULL,
  event = NULL, irr = FALSE, rr = FALSE, exp = FALSE, link = "log",
  noconstant = FALSE, vce = c("model", "robust", "cluster"), cluster = NULL,
  weights = NULL, subset = NULL, ref = NULL, vif = FALSE, diagnosis = FALSE,
  level = 0.95, digits = 3, p_digits = 3, show = TRUE, console = FALSE
)

Arguments

y	Formula or count outcome. Omit to obtain the base R Poisson family.
...	Predictors or model terms when y is not a formula.
vars	Optional model terms written as vars(...).
data	Data frame or NULL for active data.
exposure	Optional person-time variable; its logarithm is used as offset.
offset	Optional offset already on the linear-predictor scale.
event	Event value when y is binary. For a 0/1 variable the default event is 1; for a factor, the second level is used unless specified.
irr	Add an incidence-rate-ratio table for count outcomes.
rr	Add a risk-ratio table for binary outcomes.
exp	Display exponentiated coefficients only (IRR for counts, RR for binary outcomes).
link	Link used only in family mode. Accepts "log", "identity", or "sqrt"; the corresponding link functions are also accepted for compatibility with packages such as MASS.
noconstant	Fit without an intercept.
vce	Model-based, HC1 robust, or cluster-robust covariance.
cluster	Cluster variable.
weights	Optional non-negative weights.
subset	Optional logical subset.
ref	Optional named list of factor reference levels.
vif	Show coefficient-level VIFs.
diagnosis	Logical; if TRUE, append Poisson model diagnostics including Pearson/deviance dispersion, goodness-of-fit, residual/influence measures, influential observations, and collinearity diagnostics. Default FALSE.
level	Confidence level.
digits, p_digits	Decimal places.
show	Logical; open the formatted result in the Viewer. Default TRUE.
console	Logical; also print the traditional result in the Console. Default FALSE.

Details

The same compact syntax used by logistic() is supported: c.x, i.x, b2.x, ib2.x, * for main effects plus interaction, and : for interaction only.

Standard Poisson models fitted with model-based VCE can be compared using lrtest(). Quasi-Poisson models do not have an ordinary likelihood and are not supported by lrtest().

Value

If y is omitted, a base-R family object for the Poisson distribution with the requested link is returned for compatibility with modeling functions. Otherwise an object of class r4vn_stat is returned invisibly. Its sections component contains the formatted model summary, coefficient and/or exponentiated-effect tables, goodness-of-fit results, and any requested VIF table. In raw, model is the fitted Poisson glm object, vcov is the covariance matrix, coefficients contains coefficient-level estimates and tests, logLik and null.logLik are model log likelihoods, pearson is the Pearson chi-square statistic, offset stores the offset used by the fitted model, and event, binary, vce, and model.terms describe binary-event handling, covariance estimation, and fitted terms.

See Also

logistic(), lrtest()

Examples

set.seed(2026)
d <- data.frame(
  cases = rpois(200, 2),
  time = runif(200, .5, 4),
  age = rnorm(200, 45, 12),
  sex = factor(sample(c("Female", "Male"), 200, TRUE)),
  treatment = factor(sample(c("No", "Yes"), 200, TRUE))
)

p1 <- poisson(
  cases,
  c.age,
  i.sex,
  i.treatment,
  data = d,
  exposure = time,
  show = FALSE
)

p2 <- poisson(
  cases,
  c.age,
  i.sex*i.treatment,
  data = d,
  exposure = time,
  show = FALSE
)

lrtest(p1, p2, show = FALSE)

# Modified Poisson for a binary outcome
d$event01 <- as.integer(d$cases > 1)
poisson(event01, c.age, i.sex, data = d, event = 1, rr = TRUE, vce = "robust")

# Dispersion, residual, influence, and collinearity diagnostics
poisson(cases, c.age, i.sex, data = d, exposure = time, diagnosis = TRUE, show = FALSE)

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.