Skip to contents

Specify a Poisson Model

Source: R/bage_mod-constructors.R
mod_pois.Rd

Specify a model where the outcome is drawn from a Poisson distribution.

Usage

mod_pois(formula, data, exposure)

Arguments

formula

An R formula, specifying the outcome and predictors.

data

A data frame containing outcome, predictor, and, optionally, exposure variables.

exposure

Name of the exposure variable, or a 1, or a formula. See below for details.

Value

An object of class bage_mod_pois.

Details

The model is hierarchical. The rates in the Poisson distribution are described by a prior model formed from dimensions such as age, sex, and time. The terms for these dimension themselves have models, as described in priors. These priors all have defaults, which depend on the type of term (eg an intercept, an age main effect, or an age-time interaction.)

Specifying exposure

The exposure argument can take three forms:

  • the name of a variable in data, with or without quote marks, eg "population" or population;

  • the number 1, in which case a pure "counts" model with no exposure, is produced; or

  • a formula, which is evaluated with data as its environment (see below for example).

Mathematical details

The likelihood is

$$y_i \sim \text{Poisson}(\gamma_i w_i)$$

where

  • subscript \(i\) identifies some combination of the classifying variables, such as age, sex, and time;

  • \(y_i\) is an outcome, such as deaths;

  • \(\gamma_i\) is rates; and

  • \(w_i\) is exposure.

In some applications, there is no obvious population at risk. In these cases, exposure \(w_i\) can be set to 1 for all \(i\).

The rates \(\gamma_i\) are assumed to be drawn a gamma distribution

$$y_i \sim \text{Gamma}(\xi^{-1}, (\xi \mu_i)^{-1})$$

where

  • \(\mu_i\) is the expected value for \(\gamma_i\); and

  • \(\xi\) governs dispersion (i.e. variation), with lower values implying less dispersion.

Expected value \(\mu_i\) equals, on the log scale, the sum of terms formed from classifying variables,

$$\log \mu_i = \sum_{m=0}^{M} \beta_{j_i^m}^{(m)}$$

where

  • \(\beta^{0}\) is an intercept;

  • \(\beta^{(m)}\), \(m = 1, \dots, M\), is a main effect or interaction; and

  • \(j_i^m\) is the element of \(\beta^{(m)}\) associated with cell \(i\).

The \(\beta^{(m)}\) are given priors, as described in priors.

\(\xi\) has an exponential prior with mean 1. Non-default values for the mean can be specified with set_disp().

The model for \(\mu_i\) can also include covariates, as described in set_covariates().

See also

Examples

## specify a model with exposure
mod <- mod_pois(injuries ~ age:sex + ethnicity + year,
                data = nzl_injuries,
                exposure = popn)

## specify a model without exposure
mod <- mod_pois(injuries ~ age:sex + ethnicity + year,
                data = nzl_injuries,
                exposure = 1)

## use a formula to specify exposure
mod <- mod_pois(injuries ~ age:sex + ethnicity + year,
                data = nzl_injuries,
                exposure = ~ pmax(popn, 1))