bage (version 0.10.2)

mod_binom: Specify a Binomial Model

Description

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

Usage

mod_binom(formula, data, size)

Value

An object of class bage_mod.

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.

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). This option has been deprecated, because it makes forecasting and measurement error models more complicated.

Mathematical details

The likelihood is

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

where

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

• \(y_i\) is a count, such of number of births, 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.

\(\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().

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.)

See Also

• mod_pois() Specify Poisson model

• mod_norm() Specify normal model

• set_prior() Specify non-default prior for term

• set_disp() Specify non-default prior for dispersion

• fit() Fit a model

• augment() Extract values for probabilities, together with original data

• components() Extract values for hyper-parameters

• forecast() Forecast parameters and outcomes

• report_sim() Check model using simulation study

• replicate_data() Check model using replicate data

• Mathematical Details Detailed descriptions of models

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)
## but formulas are now deprecrated, and the
## recommended approach is to transform
## the input data outside the model:
esoph$total <- esoph$ncases + esoph$ncontrols
mod <- mod_binom(ncases ~ agegp + tobgp + alcgp,
                 data = esoph,
                 size = total)