Scalar-structured random-effect correlation draws

Reconstructs dense correlation matrices for one scalar-structured formula random-effect block from its compiled metadata and posterior draws. The matrices are derived only when this function is called; fitted objects can otherwise retain the compact scalar correlation coordinate.

random_effects_correlation_draws(random_term, posterior_samples)

Arguments

random_term

compiled random-effect term metadata from a BayesTools_formula_design object.

posterior_samples

posterior sample matrix, data frame, mcmc, or mcmc.list. Samples must contain the compiled internal scalar-correlation coordinate unless it is fixed in random_term metadata. This coordinate is a backend dependency, not the public semantic cor quantity. A one-coefficient block needs no correlation coordinate and accepts a numeric draw-by-zero matrix.

Value

A dense numeric array with dimensions draw x coefficient x coefficient. Coefficient dimension names use the compiled random-effect column names when available.

Details

Supported structures are compound symmetry ("CS" and "HCS"), discrete autoregressive ("AR1" and "HAR"), and continuous-time autoregressive ("CAR"). Correlation coordinates are transformed and checked against the structure-specific support recorded in random_term. "CAR" matrices use the compact ordered time coordinates stored by the formula compiler.

The returned array is dense and therefore requires memory proportional to the number of posterior draws times the squared coefficient count.

See also

prior_random() random_effects_marginal_vcov()

Examples

dat <- data.frame(
  study = factor(rep(c("s1", "s2"), each = 3)),
  time = factor(rep(1:3, 2))
)
generated <- JAGS_formula(
  ~ 1 + ar1(time | study),
  parameter = "mu",
  data = dat,
  prior_list = list(intercept = prior("normal", list(0, 1))),
  prior_random = prior_random(
    sd = prior("point", list(location = 1)),
    cor = prior("normal", list(0, 0.5))
  )
)
random_term <- generated$formula_design$random_effects[[1]]
posterior <- matrix(c(-0.2, 0.4), ncol = 1)
colnames(posterior) <- random_term$correlation$rho_name
random_effects_correlation_draws(random_term, posterior)
#> , , column = time1
#> 
#>       row
#> draw   time1 time2 time3
#>   [1,]     1  -0.2  0.04
#>   [2,]     1   0.4  0.16
#> 
#> , , column = time2
#> 
#>       row
#> draw   time1 time2 time3
#>   [1,]  -0.2     1  -0.2
#>   [2,]   0.4     1   0.4
#> 
#> , , column = time3
#> 
#>       row
#> draw   time1 time2 time3
#>   [1,]  0.04  -0.2     1
#>   [2,]  0.16   0.4     1
#>