Extract Values for Hyper-Parameters

Extract values for hyper-parameters from a model object. Hyper-parameters include

main effects and interactions,
dispersion,
trends, seasonal effects, errors,
SVD, spline, and covariate coefficients,
standard deviations, correlation coefficients.

Usage

# S3 method for class 'bage_mod'
components(object, quiet = FALSE, original_scale = FALSE, ...)

Arguments

object: Object of class "bage_mod", typically created with mod_pois(), mod_binom(), or mod_norm().
quiet: Whether to suppress messages. Default is FALSE.
original_scale: Whether values for "effect", "trend", "season", "error" and "disp" components from a normal model are on the original scale or the transformed scale. Default is FALSE.
...: Unused. Included for generic consistency only.

Value

A tibble with four columns columns:

The return value contains the following columns:

term Model term that the hyper-parameter belongs to.
component Component within term.
level Element within component .
.fitted An rvec containing draws from the posterior distribution.

Fitted vs unfitted models

components() is typically called on a fitted model. In this case, the values returned are draws from the joint posterior distribution for the hyper-parameters in the model.

components() can, however, be called on an unfitted model. In this case, the values returned are draws from the joint prior distribution. In other words, the values incorporate model priors, and any exposure, size, or weights argument, but not observed outcomes.

Scaling and Normal models

Internally, models created with mod_norm() are fitted using transformed versions of the outcome and weights variables. By default, when components() is used with these models, it returns values for .fitted that are based on the transformed versions. To instead obtain values for "effect", "trend", "season", "error" and "disp" that are based on the untransformed versions, set original_scale to TRUE.

Examples

## specify model
mod <- mod_pois(injuries ~ age + sex + year,
                data = nzl_injuries,
                exposure = popn)

## extract prior distribution
## of hyper-parameters
mod |>
  components()
#> ℹ Model not fitted, so values drawn straight from prior distribution.
#> # A tibble: 37 × 4
#>    term        component level                   .fitted
#>    <chr>       <chr>     <chr>              <rdbl<1000>>
#>  1 (Intercept) effect    (Intercept) -0.0032 (-2.1, 1.9)
#>  2 age         effect    0-4           0.087 (-1.9, 2.1)
#>  3 age         effect    5-9            0.11 (-2.6, 2.9)
#>  4 age         effect    10-14         0.061 (-3.3, 3.4)
#>  5 age         effect    15-19           0.031 (-3.8, 4)
#>  6 age         effect    20-24         0.058 (-4.3, 4.7)
#>  7 age         effect    25-29         0.049 (-5.4, 5.4)
#>  8 age         effect    30-34            0.11 (-5.6, 6)
#>  9 age         effect    35-39           0.036 (-6.8, 6)
#> 10 age         effect    40-44         -0.0093 (-7, 7.2)
#> # ℹ 27 more rows

## fit model
mod <- mod |>
  fit()
#> Building log-posterior function...
#> Finding maximum...
#> Drawing values for hyper-parameters...

## extract posterior distribution
## of hyper-parameters
mod |>
  components()
#> # A tibble: 37 × 4
#>    term        component level                    .fitted
#>    <chr>       <chr>     <chr>               <rdbl<1000>>
#>  1 (Intercept) effect    (Intercept)   -2.5 (-4.2, -0.82)
#>  2 age         effect    0-4           -2.5 (-4.1, -0.88)
#>  3 age         effect    5-9            -3.8 (-5.4, -2.2)
#>  4 age         effect    10-14            -3.3 (-5, -1.7)
#>  5 age         effect    15-19        -1.6 (-3.2, -0.015)
#>  6 age         effect    20-24          -1.4 (-3.1, 0.14)
#>  7 age         effect    25-29       -1.6 (-3.2, -0.0072)
#>  8 age         effect    30-34         -1.7 (-3.4, -0.12)
#>  9 age         effect    35-39        -1.7 (-3.4, -0.093)
#> 10 age         effect    40-44         -1.7 (-3.4, -0.12)
#> # ℹ 27 more rows

## fit normal model
mod <- mod_norm(value ~ age * diag + year,
                data = nld_expenditure,
                weights = 1) |>
  fit()
#> Building log-posterior function...
#> Finding maximum...
#> Drawing values for hyper-parameters...

## dispersion (= standard deviation in normal model)
## on the transformed scale
mod |>
  components() |>
  subset(component == "disp")
#> ℹ Values for `.fitted` are on a transformed scale. See the documentation for `mod_norm()` and `components()` for details.
#> # A tibble: 1 × 4
#>   term  component level           .fitted
#>   <chr> <chr>     <chr>      <rdbl<1000>>
#> 1 disp  disp      disp  0.32 (0.31, 0.34)

## disperson on the original scale
mod |>
  components(original_scale = TRUE) |>
  subset(component == "disp")
#> # A tibble: 1 × 4
#>   term  component level        .fitted
#>   <chr> <chr>     <chr>   <rdbl<1000>>
#> 1 disp  disp      disp  164 (157, 171)