Calculate Coheterogeneity with Full-Gradient (or Custom-Weight) Standard Errors

Computes pairwise coheterogeneity correlations across multiple outcome traits using the bias-corrected moment estimator for instrument-borrowing Mendelian randomization.

Usage

coheterogeneity_Q(
  BetaXG,
  BetaYG_matrix = NULL,
  seBetaXG,
  seBetaYG_matrix = NULL,
  BetaIV_matrix = NULL,
  seBetaIV_matrix = NULL,
  ldsc_intercepts = NULL,
  SNP_keep = NULL,
  use_ldsc = TRUE,
  weights = NULL,
  grad_rel_step = 0.001,
  alpha = 0.05,
  eps = 1e-12,
  bx_min = 1e-06,
  F_min = 0,
  min_K_pair = 50,
  return_diagnostics = FALSE
)

Arguments

BetaXG: Numeric vector of SNP-exposure associations.
BetaYG_matrix: Matrix of SNP-outcome associations, rows = SNPs, columns = traits. Optional if BetaIV_matrix is provided.
seBetaXG: Numeric vector of standard errors for BetaXG.
seBetaYG_matrix: Matrix of standard errors for BetaYG_matrix. Optional if seBetaIV_matrix is provided.
BetaIV_matrix: Matrix of ratio estimates (BetaYG / BetaXG), rows = SNPs, columns = traits. Used to reconstruct BetaYG_matrix when needed.
seBetaIV_matrix: Matrix of standard errors for BetaIV_matrix. Used to reconstruct seBetaYG_matrix when needed.
ldsc_intercepts: Optional matrix of LDSC intercepts used for pairwise outcome covariance adjustment.
SNP_keep: Optional logical or integer index vector specifying the SNPs to retain.
use_ldsc: Logical; if TRUE, use ldsc_intercepts when supplied.
weights: Optional numeric vector of non-negative, user-chosen per-SNP weights (length equal to BetaXG). When supplied, these fixed weights replace the default inverse-variance weights and the standard error is the closed-form fixed-weight SE. When NULL (the default), inverse-variance weights are used and the full-gradient SE is returned.
grad_rel_step: Numeric; relative finite-difference step used by the full-gradient numerical SE (default weighting only), expressed as a multiple of each association's standard error.
alpha: Significance level retained in the returned guard settings.
eps: Small positive constant used for numerical stabilization.
bx_min: Minimum absolute exposure effect size allowed.
F_min: Minimum first-stage F statistic threshold, where F = (BetaXG / seBetaXG)^2.
min_K_pair: Minimum number of valid SNPs required for a trait pair.
return_diagnostics: Logical; if TRUE, include a diagnostics list.

Value

A list containing:

rho: Pairwise coheterogeneity correlation matrix.
se: Pairwise standard error matrix for rho: the full-gradient delta-method SE with the default inverse-variance weights, or the fixed-weight closed-form SE when weights is supplied.
z_statistic: Pairwise z-statistic matrix.
wald_statistic: Pairwise Wald statistic matrix.
p_value: Pairwise p-value matrix.
K: Matrix of valid SNP counts per trait pair.
flag: Matrix of per-pair diagnostic flags.
method: Method label for the estimator.
guards: List of guardrail settings used in the analysis.
diagnostics: Optional detailed diagnostics by trait pair.

Details

By default the estimator uses data-dependent inverse-variance precision weights, and the reported standard error is the exact first-order delta-method (full-gradient) SE of Theorem 1: the estimator is differentiated through all of its data dependence, including the weights \(\hat w_k\).

A user who wishes to weight the instruments differently can supply their own per-SNP weights through weights. These are treated as fixed (they are constants chosen by the user, not estimated from the data), so the reported standard error is the closed-form fixed-weight SE — which is the exact delta-method SE for fixed weights, because there is no weight-estimation term to propagate.