augment.bage_mod: Extract Data and Modeled Values

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

Extract Data and Modeled 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 modeled values.

Usage

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

Arguments

x	Object of class "bage_mod", typically created with mod_pois(), mod_binom(), or mod_norm().
rows	Results are returned only for these rows of data. A logical vector, an index vector, or a logical expression evaluated within data. Optional
quiet	Whether to suppress messages. Default is FALSE.
...	Unused. Included for generic consistency only.

Details

The rows argument can be used to obtain results for a subset within data. This is faster, and uses less memory, than generating results for the whole dataset and then subsetting.

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 modeled 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 modeled values are draws from the joint prior distribution. In other words, the modeled 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

• dispersion() Extract values for dispersion

• 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

set.seed(0)

## 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

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

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

## results for females only
mod |>
  augment(rows = sex == "Female")

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

## fitting model and calling 'augument'A
## 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 Feb. 22, 2026, 5:07 p.m.