TWAS Weights Pipeline

S4-dispatched per-region pipeline for learning TWAS prediction weights. Accepts:

a QtlDataset for individual-level cohort fits;
a QtlSumStats for per-trait RSS fits;
a GwasSumStats for per-LD-block PRS-CS-style fits from GWAS summary statistics.

Usage

twasWeightsPipeline(data, ...)

# S4 method for class 'QtlDataset'
twasWeightsPipeline(
  data,
  methods = "default",
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  mafCutoff = NULL,
  macCutoff = NULL,
  xvarCutoff = NULL,
  imissCutoff = NULL,
  keepIndel = NULL,
  keepSamples = NULL,
  keepVariants = NULL,
  jointRegions = FALSE,
  jointSpecification = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  mashPrior = NULL,
  cvFolds = 5,
  samplePartition = NULL,
  fitFullData = TRUE,
  maxCvVariants = -1,
  cvThreads = 1,
  cvWeightMethods = NULL,
  ensemble = TRUE,
  ensembleR2Threshold = 0.01,
  ensembleSolver = "quadprog",
  ensembleAlpha = 1,
  estimatePi = TRUE,
  retainFit = TRUE,
  retainFitDetail = c("slim", "full"),
  phenotypeCovariatesToResidualize = NULL,
  genotypeCovariatesToResidualize = NULL,
  residualizePhenotypeCovariates = TRUE,
  residualizeGenotypeCovariates = TRUE,
  dataType = NULL,
  naAction = c("drop", "impute"),
  verbose = 1,
  seed = NULL,
  ...
)

# S4 method for class 'QtlSumStats'
twasWeightsPipeline(
  data,
  methods = NULL,
  contexts = NULL,
  traitId = NULL,
  jointSpecification = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  retainFit = TRUE,
  retainFitDetail = c("slim", "full"),
  dataType = NULL,
  verbose = 1L,
  mafCutoff = 0,
  macCutoff = 0,
  imissCutoff = 1,
  ...
)

# S4 method for class 'MultiStudyQtlDataset'
twasWeightsPipeline(
  data,
  methods = "default",
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  jointRegions = FALSE,
  jointSpecification = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  retainFit = TRUE,
  retainFitDetail = c("slim", "full"),
  naAction = c("drop", "impute"),
  verbose = 1,
  phenotypeCovariatesToResidualize = NULL,
  genotypeCovariatesToResidualize = NULL,
  residualizePhenotypeCovariates = TRUE,
  residualizeGenotypeCovariates = TRUE,
  seed = NULL,
  ...
)

# S4 method for class 'ANY'
twasWeightsPipeline(data, ...)

Arguments

data: A QtlDataset, MultiStudyQtlDataset, or QtlSumStats. The MultiStudyQtlDataset method iterates the embedded individual-level QtlDataset entries and the optional embedded QtlSumStats, then rbinds the results.
...: Reserved for method-specific arguments.
methods: A character vector of short method names, a preset string ("default" or "fast_default"), or a named list of <method>_weights = args entries. For QtlSumStats / GwasSumStats inputs the default switches to the RSS preset (c("susieRss", "susieInfRss", "lassosumRss", "prsCs", "sdpr")).
contexts: Optional character vector of contexts to restrict processing to (QtlDataset / QtlSumStats inputs). Default NULL (use all contexts).
traitId: Optional character vector of trait identifiers to restrict processing to (QtlDataset / QtlSumStats inputs). Default NULL.
region: Optional variant window for QtlDataset trait selection: a GRanges, a "chr:start-end" string, or a one-row data.frame with chrom/start/end. Mutually exclusive with traitId.
cisWindow: For QtlDataset: cis-window (bp) around each trait's genomic position when extracting variants. Required when traitId is supplied. Mutually exclusive with region.
mafCutoff, macCutoff, xvarCutoff, imissCutoff: For QtlDataset: optional per-call genotype-filter overrides. Each replaces the corresponding construct-time QtlDataset slot for this call only (applied to a validated copy); NULL (default) leaves the stored value in place. Variant QC is a property of the data, so these are applied identically here and in fineMappingPipeline – there is deliberately no TWAS-specific variant filter.
keepIndel, keepSamples, keepVariants: As above: per-call QtlDataset genotype-filter overrides.
jointRegions: For QtlDataset with a multi-range region: FALSE (default) learns weights for each range independently and concatenates them into one entry per (study, context, trait, method); the per-region fits are kept as a named list and per-region CV is recorded as a flat cvResult data frame (one row per region). TRUE concatenates the ranges' genotypes into one joint fit. Ignored for a single-range / cis request.
jointSpecification: Optional joint-fit specification (NULL by default). When NULL, the pipeline runs the implicit multi-trait / multi-context mr.mash branches as before. When non-NULL, the argument is parsed and validated via the joint-spec grammar documented under parseJointSpecification; the per-spec axis dispatcher implementation is in progress and a non-NULL value currently errors with an informative message.
fineMappingResult: Optional FineMappingResult. When supplied, its SuSiE / SuSiE-inf / SuSiE-ash trimmed fits for the matching (study, context, trait) tuples are injected into learnTwasWeights via fittedModels so SuSiE-family weight methods reuse the prior fit instead of refitting.
twasWeights: Optional TwasWeights resume cache. For each requested (study, context, trait, method) tuple already present in this collection, the cached TwasWeightsRow is copied through and the corresponding weight fit is skipped. Only the un-cached method subset is fit; the cached and fresh entries are concatenated in the returned collection. Per-tuple matching mirrors the fineMappingResult cache in fineMappingPipeline. Multivariate dispatch (mvsusie, mr.mash) is unaffected because those methods produce one fit jointly across multiple (context, trait) columns.
mashPrior: Optional MashPrior (or coercible) supplying data-driven prior matrices for mr.mash weight methods; NULL to skip.
cvFolds: Integer. Cross-validation folds. Default 5. Set to 0 to skip CV (and ensemble).
samplePartition: Optional pre-defined CV partition data.frame.
fitFullData: Logical. If TRUE, fit final weights on the full data after cross-validation. Default TRUE.
maxCvVariants: Maximum number of variants for CV. Default -1 (no limit).
cvThreads: Threads for CV parallelism. Default 1.
cvWeightMethods: Optional override of methods used for CV.
ensemble: Logical. Compute SR-TWAS ensemble weights. Default TRUE.
ensembleR2Threshold: Minimum CV R-squared for ensemble inclusion. Default 0.01.
ensembleSolver: Solver for ensemble stacking. Default "quadprog".
ensembleAlpha: Elastic-net mixing parameter (only when ensembleSolver = "glmnet"). Default 1.
estimatePi: If TRUE, estimate spike-and-slab sparsity from mr.ash before BGLR / qgg spike-and-slab methods that consume it.
retainFit: Logical. Retain the fitted-model object on each entry. Default FALSE.
retainFitDetail: Character. Level of fit detail to retain: "slim" (default) or "full".
phenotypeCovariatesToResidualize, genotypeCovariatesToResidualize: Character vector (or NULL) of covariate column names to residualize against. Forwarded to getResidualizedPhenotypes / getResidualizedGenotypes for QtlDataset / MultiStudyQtlDataset input. Default NULL (use all available covariates). Ignored for sumstat inputs.
residualizePhenotypeCovariates: Logical (length 1). When TRUE (default) residualize against the phenotype-side covariates listed in phenotypeCovariatesToResidualize; set FALSE to disable.
residualizeGenotypeCovariates: Logical (length 1). When TRUE (default) residualize against the genotype-side covariates listed in genotypeCovariatesToResidualize; set FALSE to disable.
dataType: Optional data-type label recorded on every TwasWeightsRow$dataType (e.g. "expression").
naAction: Character. How to handle missing values in the extracted data.
verbose: Verbosity (0 silent, 1 default, 2 includes external package messages).
seed: Integer or NULL. When supplied (QtlDataset path), seeds both the main-process RNG and the parallel method-fitting / cross-validation RNG (BiocParallel RNGseed) for reproducibility under multi-threading. The main-process seed is scoped to the call, so the session RNG is left as it was found. NULL (default) does not seed at all, so an outer set.seed() still governs the main-process draws.

Value

A TwasWeights collection keyed by (study, context, trait, method). The ldSketch slot is NULL for individual-level fits and equals the input's ldSketch for RSS-derived fits.

Details

Method-restriction rules (enforced):

mr.mash, mvsusie follow the multi-trait / multi-context rules of the fine-mapping mvsusie family (require at least two traits OR at least two contexts).
RSS-only methods (PRS-CS, lassosumRss, SDPR, all *Rss variants) are rejected on QtlDataset input.
Individual-level-only methods (BGLR and CRAN-stable qgg: bayes_a/b/c/l/n/r, b_lasso, dpr_*) are rejected on QtlSumStats / GwasSumStats input.

Both QtlSumStats and GwasSumStats inputs must have been QC'd via summaryStatsQc first; otherwise an error is raised pointing at that function.

The returned TwasWeights collection's ldSketch slot is set automatically: NULL for individual-level fits, the input's ldSketch for RSS-derived fits.

Optionally a FineMappingResult may be supplied as a source of pre-fit SuSiE / SuSiE-inf / SuSiE-ash objects; their trimmedFit payloads are passed through to learnTwasWeights / the RSS sub-pipelines via the fittedModels slot, avoiding a re-fit.

When the supplied FineMappingResult was produced with cross-validation (fineMappingPipeline(..., cvFolds > 1)), each matching (study, context, trait) entry's cvResult is reused: its fold partition becomes the CV partition (unless samplePartition is given explicitly) and its per-fold out-of-fold predictions/metrics are fed directly into the SR-TWAS ensemble in place of re-fitting those fine-mapping methods here. Non-fine-mapping methods (lasso, enet, ...) are still cross-validated on the same shared partition.

On QtlSumStats input there is no genotype matrix to filter, so mafCutoff / macCutoff / imissCutoff are measured against the LD reference panel instead: a variant whose panel genotypes fall below the cutoffs is dropped before the z-scores and LD matrix are built. The thresholds mean the same thing as on the QtlDataset path (MAC is converted to a MAF equivalent and the stricter of the two applies), so one number carries across input types. Defaults (0, 0, 1) filter nothing.

This discards observed variants, unlike summaryStatsQc(imputeOpts = ...), which only bounds which variants RAISS will impute.

Examples

data(qtlDatasetExample)
twasWeightsPipeline(qtlDatasetExample, methods = "lasso", cisWindow = 1e6)
#>   Fitting lasso ...
#>   Fitting lasso done in 0.2s
#>   CV fold 1/5 ...
#>   CV fold 2/5 ...
#>   CV fold 3/5 ...
#>   CV fold 4/5 ...
#>   CV fold 5/5 ...
#> TwasWeights: 1 entries
#>   1 studies, 1 contexts, 1 traits, 1 methods
#>   LD sketch: NULL (individual-level fit)

Usage

Arguments

Value

Details

Panel filters on the RSS path

Examples