Compute fSuSiE feature-level TWAS weights

Collapses a functional SuSiE (fsusieR::susiF) fit back to a variants x features weight matrix usable for TWAS prediction of each molecular feature. fSuSiE fits the regression in the wavelet domain, storing per-SNP posterior-mean wavelet effects fitted_wc[[l]] (nSNP x n_wac) and inclusion probabilities alpha[[l]]. Because the inverse wavelet transform wr() is linear, the posterior-mean prediction pushes through to a per-SNP, per-feature weight matrix: $$W[j, f] = \sum_l alpha[[l]][j] \cdot \mathrm{wr}\!\left(fitted\_wc[[l]][j, ] / csd\_X[j]\right)[f].$$ This is the exact analog of coef.susie for scalar SuSiE (all SNPs, alpha-weighted), which spreads weight across the credible set — more robust for out-of-sample TWAS than fSuSiE's in-sample lead-SNP summary (update_cal_indf).

Usage

fsusieWeights(
  fsusieFit = NULL,
  X = NULL,
  Y = NULL,
  variantIds = NULL,
  featureNames = NULL,
  retainFit = FALSE
)

Arguments

fsusieFit

A fitted fsusieR::susiF object. Must retain fitted_wc, alpha, csd_X, n_wac, and outing_grid (i.e. an untrimmed fit). Required.

X, Y

Accepted for call-compatibility with the multivariate weight-method dispatch in learnTwasWeights, which invokes every method as fn(X = ., Y = ., ...). fSuSiE is a functional method that cannot be refit from a bare (X, Y) pair (it needs feature positions and the wavelet model), so these are ignored: a fitted fsusieFit is always required.

variantIds

Optional character vector of variant IDs (length = number of SNPs in the fit) for the matrix row names. Defaults to names(fsusieFit$csd_X) / names(fsusieFit$pip).

featureNames

Optional character vector of feature (outcome) names for the matrix column names. Defaults to the fit's outing_grid.

retainFit

If TRUE, stores the fit as an attribute on the result.

Value

A numeric matrix of variant (rows) by feature (columns) weights.

Details

The reconstruction uses the raw posterior wavelet coefficients fitted_wc, so it is independent of the post_processing mode ("smash"/"TI"/"HMM"/"none") — that smoothing only denoises the alpha-collapsed display curve fitted_func, never the per-SNP predictive coefficients. The $D/$C coefficient layout and wavelet basis mirror out_prep.susiF, so the feature-domain output matches fSuSiE's own conventions.