Covariates: Specify covariates in a prior for a main effect or...
In StatisticsNZ/demest: Bayesian Demographic Estimation and Forecasting

Covariates

R Documentation

Specify covariates in a prior for a main effect or interaction.

Description

Most priors for main effects or interactions, such as age effects or age-sex interactions, can include a covariate term. The covariate term is specified using function Covariates.

Usage

Covariates(
  formula = NULL,
  data = NULL,
  infant = FALSE,
  contrastsArg = list(),
  coef = TDist()
)

Arguments

`formula`	A `formula` with response `mean`.
`data`	A data.frame containing covariate data.
`infant`	Logical. Whether to add an 'infant' indicator to the covariates specified by `formula`. Defaults to `FALSE`.
`contrastsArg`	A named list, the elements which are matrices or names of contrasts functions.
`coef`	An object of class `TDist`.

Details

The formula argument is a standard R formula, though with the restriction that the response must be mean. Interactions are specified in the usual way, so that, for instance,

mean ~ age * sex + time

mean ~ age + sex + age:sex + time

mean ~ (age + sex)^2 + time

are all equivalent.

The data argument must include labels for the main effect or interaction being modelled, in addition to the covariate data itself. For example, the data argument for region effect with a formula argument of mean ~ income could be

	region	income
1	A	15000
2	B	22000
3	C	18000

The data argument for region:time interaction with a formula argument of mean ~ income could be

	region	time	income
1	A	2000	15000
2	B	2000	22000
3	C	2000	18000
4	A	2010	17000
5	B	2010	23000
6	C	2010	17000

Any columns in data that are not referred to by the formula argument and that do do not serve as labels for the main effect or interaction are ignored. Similarly, redundant rows are ignored.

When modelling mortality rates with data that include an "infant" age group (ie an age group that includes infants, such as age group "0" or age group "0-4"), it is good practice to include an indicator variable for this age group, since its mortality rates are much higher would be predicted by subsequent age groups. If infant is TRUE, then an infant indicator is set up automatically.

infant = TRUE can only be used when specifying the prior for a main effect for age. If infant is TRUE, then formula and data can also be supplied, but do not have to be.

Internally, covariates are standardized to have mean 0 and standard deviation 0.5, as described in Gelman et al (2014, Section 16.3). Coefficients for the standardized covariates are assumed to be drawn from t distributions centered on 0. These distributions contain scale parameters that determine the degree to which coefficient estimates are shrunk towards 0. The rules for choosing default values for the scale parameters are described in the' documentation for HalfT. Shrinking coefficient' estimates towards 0 protects against over-fitting.

The help for model.matrix contains a discussion of contrasts. With Bayesian models that have informative priors, such as the t priors used by Covariates, all levels of a factor can be included in the model. See below for an example.

Value

An object of class Covariates

References

Gelman, A., Carlin, J.B., Stern, H.S. and Rubin, D.B., 2014. Bayesian Data Analysis. Third Edition. Boca Raton, FL, USA: Chapman & Hall/CRC.

Examples

reg.data <- data.frame(region = LETTERS[1:10],
                       income = c(20, 31, 15, 7, 24, 8, 22, 14, 21, 17),
                       area = rep(c("Urban", "Rural"), each = 5))
Covariates(mean ~ income + area,
           data = reg.data)

## override the default settings
Covariates(mean ~ income + area,
           data = reg.data,
           coef = TDist(scale = 0.25))

## override the default 'treatment' contrast
contrasts.arg <- list(area = diag(2))
Covariates(mean ~ income + area,
           data = reg.data,
           contrastsArg = contrasts.arg)

## covariate data for an age:sex interaction
agesex.data <- data.frame(age = rep(c("0-14", "15-29", "30+"),
                                    times = 2),
                          sex = rep(c("Female", "Male"),
                                    each = 3),
                          weight = c(78, 94, 83, 84, 62, 75))
Covariates(mean ~ weight,
           data = agesex.data)

## 'infant' indicator
Covariates(infant = TRUE)

StatisticsNZ/demest documentation built on Nov. 2, 2023, 7:56 p.m.