Extract fitted correlation pairs — corpairs • drmTMB

corpairs() returns a long table of fitted correlation pairs from a drmTMB model. The first 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 random-intercept covariance blocks, and matched bivariate mu1/mu2 and sigma1/sigma2 random-intercept covariance blocks from corpars, plus the first fitted bivariate phylogenetic mu1/mu2 mean-mean correlation.

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", or "phylogenetic".
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

The table is intentionally more explicit than rho12() or corpars because future double-hierarchical, phylogenetic, spatial, and study-level models will contain several scientifically different correlations.

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
)
corpairs(fit)
#>      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.6196689 0.6196689 0.6196689       40
#>   link_estimate  link_min  link_max modelled   conf.status interval_source
#> 1     0.7244674 0.7244674 0.7244674    FALSE not_requested   not_available