Skip to contents

Specify a Binomial Model

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

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

Usage

mod_binom(formula, data, size)

Arguments

formula

An R formula, specifying the outcome and predictors.

data

A data frame containing the outcome and predictor variables, and the number of trials.

size

Name of the variable giving the number of trials, or a formula.

Value

An object of class bage_mod.

Details

The model is hierarchical. The probabilities in the binomial 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.)

Mathematical details

The likelihood is

$$y_i \sim \text{binomial}(\gamma_i; w_i)$$

where

  • \(y_i\) is a count, such of number of births, for some combination \(i\) of classifying variables, such as age, sex, and region;

  • \(\gamma_i\) is a probability of 'success'; and

  • \(w_i\) is the number of trials.

The probabilities \(\gamma_i\) are assumed to be drawn a beta distribution

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

where

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

  • \(\xi\) governs dispersion (ie variance.)

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

$$\text{logit} \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.

The prior for \(\xi\) is described in set_disp().

Specifying size

The size argument can take two forms:

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

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

See also

Examples

mod <- mod_binom(oneperson ~ age:region + age:year,
                 data = nzl_households,
                 size = total)

## use formula to specify size
mod <- mod_binom(ncases ~ agegp + tobgp + alcgp,
                 data = esoph,
                 size = ~ ncases + ncontrols)