augment.bage_mod: Extract Data and Modelled Values

In bage: Bayesian Estimation and Forecasting of Age-Specific Rates

Extract Data and Modelled Values

Description

Extract data and rates, probabilities, or means from a model object. The return value consists of the original data and one or more columns of modelled values.

Usage

## S3 method for class 'bage_mod'
augment(x, quiet = FALSE, ...)

Arguments

x	Object of class "bage_mod", typically created with mod_pois(), mod_binom(), or mod_norm().
quiet	Whether to suppress messages. Default is FALSE.
...	Unused. Included for generic consistency only.

Value

A tibble, with the original data plus one or more of the following columns:

• ⁠.<outcome>⁠ Corrected or extended version of the outcome variable, in applications where the outcome variable has missing values, or a data model is being used.

• .observed 'Direct' estimates of rates or probabilities, ie counts divided by exposure or size (in Poisson and binomial models.)

• .fitted Draws of rates, probabilities, or means.

• .expected Draws of expected values for rates or probabilities (in Poisson that include exposure, or in binomial models.)

Uncertain quantities are represented using rvecs.

Fitted vs unfitted models

augment() is typically called on a fitted model. In this case, the modelled values are draws from the joint posterior distribution for rates, probabilities, or means.

augment() can, however, be called on an unfitted model. In this case, the modelled values are draws from the joint prior distribution. In other words, the modelled values are informed by model priors, and by values for exposure, size, or weights, but not by observed outcomes.

Imputed values for outcome variable

augment() automatically imputes any missing values for the outcome variable. If outcome variable var has one or more NAs, then augment creates a variable .var holding original and imputed values.

Data model for outcome variable

If the overall model includes a data model for the outcome variable var, then augment() creates a new variable .var containing estimates of the true value for the outcome.

See Also

• components() Extract values for hyper-parameters from a model

• tidy() Short summary of a model

• mod_pois() Specify a Poisson model

• mod_binom() Specify a binomial model

• mod_norm() Specify a normal model

• fit() Fit a model

• is_fitted() See if a model has been fitted

• unfit() Reset a model

• datamods Overview of data models implemented in bage

Examples

## specify model
mod <- mod_pois(divorces ~ age + sex + time,
                data = nzl_divorces,
                exposure = population) |>
  set_n_draw(n_draw = 100) ## smaller sample, so 'augment' faster

## draw from the prior distribution
mod |> augment()

## fit model
mod <- mod |>
  fit()

## draw from the posterior distribution
mod |> augment()

## insert a missing value into outcome variable
divorces_missing <- nzl_divorces
divorces_missing$divorces[1] <- NA

## fitting model and calling 'augument'
## creates a new variable called '.divorces'
## holding observed and imputed values
mod_pois(divorces ~ age + sex + time,
         data = divorces_missing,
         exposure = population) |>
  fit() |>
  augment()

## specifying a data model for the
## original data also leads to a new
## variable called '.divorces'
mod_pois(divorces ~ age + sex + time,
         data = nzl_divorces,
         exposure = population) |>
  set_datamod_outcome_rr3() |>
  fit() |>
  augment()

bage documentation built on April 3, 2025, 8:53 p.m.