Skip to contents

Adjust a functional response for covariate effects

Source: R/adjust_covariates.R
mf_adjust_for_covariates.Rd

Returns Y_adjusted = Y - Z %*% fitted_func where fitted_func is a K x T matrix of per-position covariate effects fit by one of two methods:

Usage

mf_adjust_for_covariates(
  Y,
  Z,
  X = NULL,
  method = c("wavelet_eb", "ols"),
  wavelet_basis_order = 10L,
  wavelet_family = "DaubLeAsymm",
  max_iter = 50L,
  tol = 0.001,
  null_prior_weight = 10,
  init_pi0_w = 1,
  control_mixsqp = list(verbose = FALSE, eps = 1e-06, numiter.em = 4L),
  grid_mult = sqrt(2),
  wavelet_magnitude_cutoff = 0
)

Arguments

Y

n x T numeric matrix; the functional response. T must be a power of two for method = "wavelet_eb".

Z

n x K numeric matrix; covariates to adjust away.

X

optional n x p numeric matrix; the genotype matrix to FWL-residualize. Default NULL.

method

"wavelet_eb" (default) or "ols".

wavelet_basis_order

integer, selects the wavelet basis member within wavelet_family (number of vanishing moments for Daubechies families). Forwarded to wavethresh::wd's filter.number. Default 10L.

wavelet_family

character, the family argument to wd. Default "DaubExPhase".

max_iter

integer, maximum outer iterations for the wavelet-EB path. Default 50.

tol

numeric, convergence tolerance on the per-scale prior weights ||pi - pi_prev|| / log(K) < tol. Default 1e-3.

null_prior_weight

numeric, penalty on the null component (passed through to the EB prior init). Default 10.

init_pi0_w

numeric, starting null-component mass for mixsqp. Default 1.

control_mixsqp

optional named list of mixsqp control args. Default list(verbose = FALSE, eps = 1e-6, numiter.em = 4L).

grid_mult

numeric, multiplier for the ash mixture grid. Default sqrt(2).

wavelet_magnitude_cutoff

non-negative numeric. Wavelet columns whose median(|column|) is at or below this cutoff are zeroed and treated as uninformative (Bhat = 0, Shat = 1) at every outer iteration. Default 0.

Value

A named list with:

Y_adjusted

n x T matrix, the residualized response.

X_adjusted

n x p matrix when X was supplied, else NULL.

fitted_func

K x T matrix of fitted covariate effects.

sigma2

numeric, residual variance estimate.

niter

integer, number of outer iterations (wavelet-EB only).

converged

logical, convergence status (wavelet-EB only).

method

character, the method used.

Details

  • "wavelet_eb" (default): wavelet-domain empirical-Bayes regression with a per-scale mixture-of-normals prior. Suitable when the covariate effects are smooth functions of position.

  • "ols": closed-form Frisch-Waugh-Lovell residualization. The no-shrinkage limit of the wavelet-EB path; suitable when the covariate effects can vary arbitrarily across positions.

When X is supplied, the function also returns X_adjusted = (I - Z (Z'Z)^{-1} Z') X to handle covariate- genotype correlation. Upstream covariate-adjustment workflows typically do not residualize X; the option is provided for downstream fine-mapping users who need it.

References

Manuscript: methods/online_method.tex eq:wavelet_residualization (covariate adjustment in the wavelet domain).