Fit two margins and construct a frozen-margin association in one call

biv_associate() is the convenience front end for the reviewed Arc 6 frozen-margin route. It fits two univariate margins to the supplied data and then calls associate_pairs() without refitting either margin. It is one R call, but it is not a jointly fitted bivariate model: stage 2 treats the fitted marginal parameters as fixed and estimates only the latent-normal association eta.

Usage

biv_associate(
  formula_1,
  formula_2,
  family,
  data,
  kernel = latent_normal(),
  association = ~1,
  control_1 = list(),
  control_2 = list()
)

Arguments

formula_1, formula_2

Univariate drm_formula objects for the first and second response margins.

family

A two-element list of marginal family objects.

data

A data frame containing both responses and every predictor used by either margin.

kernel

Association kernel. Arc 6 accepts only latent_normal().

association

Association formula. Most Arc 6 pair classes accept only ~ 1, which estimates one constant association parameter. The beta Bernoulli x ordinary-NB2 route accepts an intercept-bearing fixed-effect model-matrix formula, including multiple predictors, factors, interactions, and explicit transformations. Alpha-scale standard errors and Wald intervals are available for every admitted association formula when its fit-specific Godambe covariance diagnostics pass.

control_1, control_2

Optional control lists passed to the corresponding marginal drmTMB() fits.

Value

A drm_pair_association object that retains frozen snapshots of both fitted margins. association() returns the point estimate unless the numerical diagnostic is boundary-unresolved; a near-boundary status remains flagged. Admitted routes have alpha-scale vcov() and confint() methods when the fit-specific Godambe covariance succeeds. Intercept-only routes also have bounded eta intervals; predict.drm_pair_association() returns eta-scale standard errors and pointwise confidence intervals. No profile is available.

Details

The two formulas must be univariate bf() or drm_formula() objects, and family must be a two-element list. The supplied data must already be the same complete paired analysis data for both margins. If the two marginal fits retain different rows, the constructor fails rather than silently comparing different individuals.

Examples

set.seed(20260725)
dat <- data.frame(x = rnorm(80))
z_continuous <- rnorm(80)
z_binary <- 0.35 * z_continuous + sqrt(1 - 0.35^2) * rnorm(80)
dat$trait_continuous <- 0.2 + 0.5 * dat$x + z_continuous
dat$trait_binary <- as.integer(z_binary > qnorm(0.4))

assoc <- biv_associate(
  bf(mu = trait_continuous ~ x, sigma = ~ 1),
  bf(mu = trait_binary ~ x),
  family = list(gaussian(), binomial()), data = dat
)
association(assoc)
#>          kernel                  estimand       eta   status boundary
#> 1 latent_normal latent-normal association 0.3331496 interior    FALSE
sqrt(diag(vcov(assoc)))
#> Warning: Association uncertainty is interval-feasible; coverage is not yet calibrated
#> for this route.
#> ℹ The two-stage Godambe covariance passed fit-specific diagnostics. Treat the
#>   Wald interval as experimental until a route-specific coverage campaign is
#>   completed.
#>     alpha 
#> 0.1382374 
confint(assoc)
#> Warning: Association uncertainty is interval-feasible; coverage is not yet calibrated
#> for this route.
#> ℹ The two-stage Godambe covariance passed fit-specific diagnostics. Treat the
#>   Wald interval as experimental until a route-specific coverage campaign is
#>   completed.
#>            2.5 %    97.5 %
#> alpha 0.07542699 0.6173075
confint(assoc, type = "eta")
#> Warning: Association uncertainty is interval-feasible; coverage is not yet calibrated
#> for this route.
#> ℹ The two-stage Godambe covariance passed fit-specific diagnostics. Treat the
#>   Wald interval as experimental until a route-specific coverage campaign is
#>   completed.
#>         2.5 %  97.5 %
#> eta 0.0752842 0.54925