Extract fitted correlation pairs

corpairs() returns a long table of fitted correlation pairs from a drmTMB model. The current implementation reports correlations that are already fitted elsewhere: residual bivariate rho12, ordinary univariate group-level mu random-effect correlations, matched univariate and same-response bivariate mu/sigma covariance blocks, matched bivariate mu1/mu2 random-intercept and slope-only covariance blocks, and matched bivariate sigma1/sigma2 random-intercept and slope-only covariance blocks from corpars, plus fitted bivariate phylogenetic, coordinate-spatial, animal-model, and relmat() correlation rows. Full q4 phylogenetic, coordinate-spatial, animal-model, and relmat() blocks report six derived endpoint correlations; block-diagonal q4 fallback fits report the direct mu1/mu2 and sigma1/sigma2 block correlations.

Usage

corpairs(object, ...)

# S3 method for class 'drmTMB'
corpairs(
  object,
  level = NULL,
  group = NULL,
  block = NULL,
  class = NULL,
  conf.int = FALSE,
  conf.level = 0.95,
  method = "profile",
  trace = FALSE,
  ...
)

Arguments

object

A drmTMB fit.

...

Additional arguments passed to TMB::tmbprofile() when conf.int = TRUE.

level

Optional character vector of correlation levels to keep, such as "residual", "group", "phylogenetic", or "spatial".

group

Optional character vector of grouping factors to keep, such as "id". Residual rows have no grouping factor and are removed by this filter.

block

Optional character vector of covariance-block labels to keep, such as "p". Residual rows have no block label and are removed by this filter.

class

Optional character vector of pair classes to keep, such as "residual" or "mean-slope". Location aliases such as "location-location" and "location-scale" are accepted as filters for the current "mean-mean" and "mean-scale" rows.

conf.int

Logical; include profile-likelihood confidence intervals where the correlation target is currently profile-ready. Unsupported derived targets receive an explicit interval status instead of silent missing bounds.

conf.level

Confidence level used when conf.int = TRUE. This is named separately from the level filter to avoid ambiguity with correlation levels such as "phylogenetic".

method

Interval method used when conf.int = TRUE. Only "profile" is currently supported for correlation-pair intervals.

trace

Logical; passed to TMB::tmbprofile() when profile intervals are requested.

Value

A data frame with one row per fitted correlation pair or pair summary. Predictor-dependent rho12 is summarized by its mean, minimum, and maximum over the fitted rows. Rows include conf.status and interval_source so point-only and interval-aware pair tables use the same provenance vocabulary as prediction tables.

Details

Use corpairs() when the question is about correlations among fitted residual, ordinary group-level, phylogenetic, coordinate-spatial, animal-model, or relmat() latent effects. Use rho12() when the only target is the residual correlation curve of a bivariate model.

The table is intentionally more explicit than rho12() or corpars because double-hierarchical, phylogenetic, spatial, animal-model, and lower-level relatedness models can contain several scientifically different correlations. Profile intervals are opt-in and can be slow; filter with level, group, block, or class before requesting conf.int = TRUE on large models. Bootstrap intervals are not a corpairs() route.

Examples

set.seed(1)
n <- 40
x <- rnorm(n)
z1 <- rnorm(n)
z2 <- rnorm(n)
mu1 <- 0.2 + 0.5 * x
mu2 <- -0.1 + 0.4 * x
sigma1 <- exp(-0.2 + 0.15 * z1)
sigma2 <- exp(0.1 - 0.1 * z2)
rho <- 0.35
e1 <- rnorm(n)
e2 <- rho * e1 + sqrt(1 - rho^2) * rnorm(n)
dat <- data.frame(
  y1 = mu1 + sigma1 * e1,
  y2 = mu2 + sigma2 * e2,
  x = x,
  z1 = z1,
  z2 = z2
)
fit <- drmTMB(
  bf(
    mu1 = y1 ~ x,
    mu2 = y2 ~ x,
    sigma1 = ~ z1,
    sigma2 = ~ z2,
    rho12 = ~ 1
  ),
  family = c(gaussian(), gaussian()),
  data = dat
)
pairs <- corpairs(fit)
pairs
#>      level group block from_dpar  to_dpar from_coef to_coef from_response
#> 1 residual  <NA>  <NA>  residual residual      <NA>    <NA>            y1
#>   to_response    class parameter estimate      min      max n_values
#> 1          y2 residual     rho12 0.619665 0.619665 0.619665       40
#>   link_estimate  link_min  link_max modelled   conf.status interval_source
#> 1     0.7244622 0.7244622 0.7244622    FALSE not_requested   not_available
corpairs(fit, level = "residual")
#>      level group block from_dpar  to_dpar from_coef to_coef from_response
#> 1 residual  <NA>  <NA>  residual residual      <NA>    <NA>            y1
#>   to_response    class parameter estimate      min      max n_values
#> 1          y2 residual     rho12 0.619665 0.619665 0.619665       40
#>   link_estimate  link_min  link_max modelled   conf.status interval_source
#> 1     0.7244622 0.7244622 0.7244622    FALSE not_requested   not_available

# Profile intervals are opt-in and can be slow for large models.
# corpairs(fit, level = "residual", conf.int = TRUE)