Skip to contents

Fine-Mapping Pipeline

Source: R/fineMappingPipeline.R
fineMappingPipeline.Rd

S4-dispatched per-region fine-mapping entry point that replaces the deprecated univariateAnalysisPipeline, multivariateAnalysisPipeline, rssAnalysisPipeline, and susieRssPipeline pipelines. Accepts:

  • a QtlDataset for individual-level cohort fits (per-context / per-trait univariate SuSiE; joint multi-trait or multi-context mvSuSiE; joint multi-trait fSuSiE per context);

  • a MultiStudyQtlDataset which recurses through each embedded QtlDataset per study and processes the optional embedded QtlSumStats via the sumstat method;

  • a QtlSumStats for per-trait SuSiE-RSS fits and per-(study, trait) multi-context mvSuSiE-RSS fits;

  • a GwasSumStats for per-(study, LD-block) SuSiE-RSS fine-mapping (used by qtlEnrichmentPipeline downstream).

Method tokens are unified across input classes; auto-dispatch picks the individual-level vs RSS implementation based on the input class. The supported tokens are:

susie

susieR::susie with unmappable_effects = "none" on individual-level input; susieR::susie_rss (same) on RSS.

susieInf

unmappable_effects = "inf" variant of the same.

susieAsh

unmappable_effects = "ash" variant of the same.

ser

Single-effect regression via susieR::susie_ser on summary statistics (z, n); LD-free (no R, no L), so distinct from susie with L = 1. Sumstat input only (QtlSumStats / GwasSumStats, or the sumstat side of a MultiStudyQtlDataset); rejected on individual-level QtlDataset.

mvsusie

mvsusieR::mvsusie on individual- level input (requires multi-trait OR multi-context Y), mvsusieR::mvsusie_rss on sumstat input (requires multi-context within a single (study, trait) group). Errors on GwasSumStats input.

fsusie

fsusieR::susiF joint multi-trait fit per context. Individual-level only; errors on any SumStats input.

mrmash

Always rejected here. mr.mash is a TWAS weight-oriented method and lives in twasWeightsPipeline.

Usage

fineMappingPipeline(data, ...)

# S4 method for class 'QtlDataset'
fineMappingPipeline(
  data,
  methods,
  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,
  addSusieInf = TRUE,
  L = 20L,
  Lgreedy = 5L,
  coverage = 0.95,
  secondaryCoverage = c(0.7, 0.5),
  signalCutoff = 0.025,
  minAbsCorr = 0.8,
  medianAbsCorr = NULL,
  fineMappingResult = NULL,
  cvFolds = 0,
  cvThreads = 1,
  samplePartition = NULL,
  pipCutoffToSkip = 0,
  usePCA = FALSE,
  nPCs = 10L,
  seed = NULL,
  twasWeights = NULL,
  dataDrivenPriorWeightsCutoff = 1e-10,
  naAction = c("drop", "impute"),
  verbose = 1,
  trim = TRUE,
  fullFit = FALSE,
  fullFitAlphaOnly = TRUE,
  includeAllCs = FALSE,
  phenotypeCovariatesToResidualize = NULL,
  genotypeCovariatesToResidualize = NULL,
  residualizePhenotypeCovariates = TRUE,
  residualizeGenotypeCovariates = TRUE,
  ...
)

# S4 method for class 'MultiStudyQtlDataset'
fineMappingPipeline(
  data,
  methods,
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  jointRegions = FALSE,
  jointSpecification = NULL,
  addSusieInf = TRUE,
  coverage = 0.95,
  secondaryCoverage = c(0.7, 0.5),
  signalCutoff = 0.025,
  minAbsCorr = 0.8,
  medianAbsCorr = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  dataDrivenPriorWeightsCutoff = 1e-10,
  cvFolds = 0,
  cvThreads = 1,
  samplePartition = NULL,
  pipCutoffToSkip = 0,
  seed = NULL,
  naAction = c("drop", "impute"),
  verbose = 1,
  trim = TRUE,
  fullFit = FALSE,
  fullFitAlphaOnly = TRUE,
  includeAllCs = FALSE,
  phenotypeCovariatesToResidualize = NULL,
  genotypeCovariatesToResidualize = NULL,
  residualizePhenotypeCovariates = TRUE,
  residualizeGenotypeCovariates = TRUE,
  ...
)

# S4 method for class 'QtlSumStats'
fineMappingPipeline(
  data,
  methods,
  contexts = NULL,
  traitId = NULL,
  jointSpecification = NULL,
  addSusieInf = TRUE,
  coverage = 0.95,
  secondaryCoverage = c(0.7, 0.5),
  signalCutoff = 0.025,
  minAbsCorr = 0.8,
  medianAbsCorr = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  dataDrivenPriorWeightsCutoff = 1e-10,
  verbose = 1,
  trim = TRUE,
  fullFit = FALSE,
  fullFitAlphaOnly = TRUE,
  includeAllCs = FALSE,
  serFallback = FALSE,
  rFinite = NULL,
  rMismatch = "none",
  rMismatchMethod = NULL,
  checkPrior = NULL,
  keepFullFit = "fallback",
  ...
)

# S4 method for class 'GwasSumStats'
fineMappingPipeline(
  data,
  methods,
  addSusieInf = TRUE,
  L = 20L,
  Lgreedy = 5L,
  coverage = 0.95,
  secondaryCoverage = c(0.7, 0.5),
  signalCutoff = 0.025,
  minAbsCorr = 0.8,
  medianAbsCorr = NULL,
  fineMappingResult = NULL,
  verbose = 1,
  trim = TRUE,
  fullFit = FALSE,
  fullFitAlphaOnly = TRUE,
  includeAllCs = FALSE,
  serFallback = FALSE,
  rFinite = NULL,
  rMismatch = "none",
  rMismatchMethod = NULL,
  checkPrior = NULL,
  keepFullFit = "fallback",
  ...
)

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

Arguments

data

A QtlDataset, MultiStudyQtlDataset, QtlSumStats, or GwasSumStats.

...

Reserved for future per-method arguments.

methods

Method specification. Accepts either:

  • A character vector of method tokens, e.g. c("susie", "susieInf", "mvsusie") (any subset of c("susie", "susieInf", "susieAsh", "mvsusie", "fsusie"), subject to per-class compatibility).

  • A named list keyed by method token, where each value is a list of per-method kwargs to splice into the underlying fitter, e.g. list(susie = list(L = 1, refine = FALSE), mvsusie = list(max_iter = 500)). Mirrors the convention of twasWeightsPipeline's methods argument. User-supplied kwargs override the capability-table defaults and any base / chained args set by the pipeline (e.g. you can override model_init even when fitting from a susieInf chain).

contexts

Optional character vector of context names. Default NULL (all contexts).

traitId

Optional character vector of trait names to restrict processing to.

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.

jointRegions

For QtlDataset with a multi-range region: FALSE (default) fits each range independently and merges the per-range results into one entry per (study, context, trait, method) — the merged susieFit is a named list of per-region fits and credible-set labels are renumbered to stay unique. TRUE concatenates the ranges' genotypes into one joint fit. Ignored for a single-range / cis (traitId + cisWindow) request.

jointSpecification

Optional joint-fit specification (NULL by default). When NULL, the pipeline runs the implicit multi-context / multi-trait mvSuSiE / fSuSiE branches as before. When non-NULL, the argument is parsed and validated via the joint-spec grammar documented under parseJointSpecification (a character vector of axes, or a list of list(axes, scope) specs); the per-spec axis dispatcher implementation is in progress and a non-NULL value currently errors with an informative message. See the design notes in R/jointSpecification.R for the accepted grammar.

addSusieInf

Logical. When susieInf is in methods alongside susie and/or susieAsh, controls whether the SuSiE-inf fit initialises the chained downstream method(s). Default TRUE.

coverage

Primary credible-set coverage (numeric, length 1). Default 0.95.

secondaryCoverage

Secondary coverages forwarded to postprocessFinemappingFits. Default c(0.7, 0.5).

signalCutoff

PIP cutoff for top-loci selection. Default 0.025.

minAbsCorr

Minimum absolute correlation for credible-set purity. Default 0.8.

medianAbsCorr

Optional median absolute correlation for credible-set purity, routed to susieR::susie_get_cs. A set is kept if it passes either minAbsCorr or medianAbsCorr (OR-logic). Default NULL (off).

fineMappingResult

Optional existing FineMappingResult to use as a resume cache; tuples already present are not refit.

cvFolds

Integer. Number of cross-validation folds. Default 0 (no CV). When > 1, each method is refit on the training samples of every fold and used to predict the held-out samples; the fold partition plus per-fold out-of-fold predictions and metrics are stored on each FineMappingEntry's cvResult slot (see getCvResult). twasWeightsPipeline reuses this partition and feeds these predictions into the SR-TWAS ensemble. Individual-level (QtlDataset / MultiStudyQtlDataset) input only; ignored for sumstat inputs.

cvThreads

Integer. Number of parallel workers for the cross-validation fold refits (passed to the shared CV engine's numThreads). Default 1 (serial); -1 uses all cores. Only consulted when cvFolds > 1.

samplePartition

Optional pre-defined CV partition data.frame with columns Sample and Fold. When supplied (and cvFolds > 1), every method reuses this exact partition; otherwise a fresh partition is generated per (study, context, trait).

pipCutoffToSkip

Numeric (length 1). Individual-level single-effect (SER) pre-screen applied to each residualized (X, y) block before a full fit: a susie model with L = 1 is fit and the block is skipped when no PIP exceeds the cutoff (no potentially significant variant). The summary-statistics analog lives in summaryStatsQc(). 0 (default) disables the screen; a negative value uses the adaptive 3 / nVariants threshold.

usePCA

Logical (length 1). QtlDataset only. When TRUE (default FALSE), each multi-trait context's PCA-reduced phenotype is fine-mapped with univariate SuSiE on its top principal components (ports the legacy fsusie.R susie_on_top_pc). Each PC becomes a pseudo-trait row keyed trait = "topPC\{i\}", method = "susie". Single-trait contexts have no PCA and are skipped.

nPCs

Integer (length 1). QtlDataset only. Caps the number of top principal components fine-mapped per context when usePCA = TRUE (default 10). The effective count is min(nPCs, usable traits).

seed

Optional integer. When non-NULL, set.seed(seed) is called once at the start of the call for reproducible fits. Default NULL (no seeding).

verbose

Verbosity (0 silent, 1 default). Default 1.

trim

Logical (length 1). When TRUE (default) the susieFit slot on each output FineMappingEntry carries a trimmed view of the SuSiE fit (the minimal subset needed by downstream pipelines). When FALSE the full untrimmed susie() return is retained so accessors like getSusieFit() and non-default-coverage queries through getCs() can read the full posterior matrices (lbf_variable, mu, mu2, V). The per-variant topLoci table is always fully populated regardless of trim.

fullFit

Logical (length 1, default FALSE). Master switch for per-credible-set variant-level export in topLoci. When FALSE, only the always-on within_cs_pip scalar column is added (each variant's alpha in its assigned primary-coverage credible set; NA when not in a set). When TRUE, wide per-CS columns are added, one set of columns per credible set (labelled cs<k>).

fullFitAlphaOnly

Logical (length 1, default TRUE). No-op when fullFit=FALSE. When TRUE, only alpha is widened (within_cs_pip_cs<k>). When FALSE, all four per-effect matrices are widened: within_cs_pip_cs<k> (alpha), cs_logbf_cs<k> (lbf_variable), cs_effect_cs<k> (mu, unscaled) and cs_effect_var_cs<k> (posterior variance, unscaled).

includeAllCs

Logical (length 1, default FALSE). No-op when fullFit=FALSE. When FALSE, only effects that produced a passing (purity/coverage-filtered) credible set are widened. When TRUE, every effect L is widened (including filtered-out ones, labelled L<k> instead of cs<k>).

phenotypeCovariatesToResidualize

Character vector (or NULL) of phenotype-covariate names to residualize against. NULL (default) uses every available phenotype covariate. Only meaningful when the input is a QtlDataset / MultiStudyQtlDataset (ignored for sumstat inputs).

genotypeCovariatesToResidualize

Character vector (or NULL) of genotype-covariate column names to residualize against. NULL uses every available genotype covariate.

residualizePhenotypeCovariates

Logical (length 1). When TRUE (default) residualize against the phenotype-side covariates listed in phenotypeCovariatesToResidualize. Set FALSE to disable phenotype-covariate residualization entirely. The marginal univariate effects stored on each FineMappingEntry obey the same residualization choice as the SuSiE fit itself — they are computed against the same residualized X / Y.

residualizeGenotypeCovariates

Logical (length 1). When TRUE (default) residualize against the genotype-side covariates listed in genotypeCovariatesToResidualize. Set FALSE to disable.

serFallback

Logical (length 1, default FALSE). QtlSumStats / GwasSumStats (summary-statistics SuSiE-RSS paths) only. When TRUE, after each standard multi-effect SuSiE-RSS fit (susie / susieAsh) the pipeline reads susieR's finite-sample R diagnostics and, if fit$R_finite_diagnostics$R_reliability_flag is TRUE, reports the single-effect (ser_model) result for that region instead of the multi-effect fit. Defaults FALSE so existing callers are unchanged. See keepFullFit for retaining the multi-effect fit.

rFinite

QtlSumStats / GwasSumStats only. Finite-sample size for susieR's R_finite correction, forwarded to susieR::susie_rss(). NULL (default) uses susieR's default, except when a finite/EB mode is active (serFallback=TRUE or rMismatch != "none") and rFinite is NULL, in which case it defaults to the LD-panel sample size getNSamples(ldSketch).

rMismatch

QtlSumStats / GwasSumStats only. LD-mismatch mode forwarded to susieR::susie_rss() as R_mismatch (e.g. "eb" for empirical Bayes). Default "none" (susieR's default).

rMismatchMethod

QtlSumStats / GwasSumStats only. Optional R_mismatch_method forwarded to susieR::susie_rss() when non-NULL.

checkPrior

QtlSumStats / GwasSumStats only. Optional check_prior forwarded to susieR::susie_rss() when non-NULL.

keepFullFit

QtlSumStats / GwasSumStats only. Controls retention of the pre-fallback multi-effect SuSiE-RSS fit when serFallback=TRUE: "fallback" (default) keeps it only for regions that fell back to SER; "all" keeps it for every region; "none" keeps none. The retained fit and the decision are stored on the entry's SuSiE fit and read via getSusieFit(res)$multiEffectFit, getSusieFit(res)$R_reliability_flag, and getSusieFit(res)$serFallbackUsed.

ldBlocks

For GwasSumStats input only: an LdBlocks object describing the LD-block partition. The pipeline performs SuSiE-RSS fine-mapping per (study, ldBlock). Required for the GwasSumStats method.

Value

A FineMappingResult collection keyed by (study, context, trait, method). The ldSketch slot is set automatically: NULL for individual-level (QtlDataset / all-individual-level MultiStudyQtlDataset) fits, the input's ldSketch for RSS-derived fits.

Chained initialisation

When susieInf is requested alongside susie and/or susieAsh and addSusieInf = TRUE (default), the SuSiE-inf fit is computed first and used as initialisation for the SuSiE / SuSiE-ash fits, mirroring the legacy univariateAnalysisPipeline / susieRssPipeline chained init behaviour. SuSiE-inf is dropped from the final result when the caller did not explicitly request it (only used as init).

QC contract

All QtlSumStats and GwasSumStats inputs must have been QC'd via summaryStatsQc; the pipeline errors on inputs where length(getQcInfo(x)) == 0L. summaryStatsQc also drops variants absent from the ldSketch, so by the time per-entry processing runs every variant is guaranteed to be present in the LD panel and a local LD matrix can be built with extractBlockGenotypes + computeLd("sample").

Optional resume cache

Supplying fineMappingResult of an existing FineMappingResult skips re-fitting any (study, context, trait, method) tuple that already has a matching row; cached entries are merged with the newly-fit entries in the returned collection.

Intentional behaviours dropped from the pre-stub pipelines

The four pre-stub pipelines (univariateAnalysisPipeline / multivariateAnalysisPipeline / rssAnalysisPipeline / susieRssPipeline) carried several behaviours that are deliberately not ported here:

  • TWAS weights computation (twasWeights = TRUE path): lives in twasWeightsPipeline now.

  • Filtering knobs (mafCutoff, imissCutoff, xvarCutoff, ldReferenceMetaFile): individual- level QC lives on the QtlDataset constructor; sumstat QC lives in summaryStatsQc(). No filtering happens inside this pipeline.

  • Diagnostic re-analysis paths (singleEffect / bayesianConditionalRegression reanalysis on the RSS path): these are not exposed as dedicated method tokens. Callers who want a single-effect fit can request it via per-method kwargs, e.g. methods = list(susie = list(L = 1)) (see the methods parameter).

  • loadRssData and explicit ldReferenceMetaFile arguments: the new QtlSumStats / GwasSumStats carry the (already-QC'd) sumstats and ldSketch directly.

  • Verbose methodName suffixing (e.g. "susie_rss_NO_QC", "susie_rss_SLALOM_RAISS_imputed"): the method column on the returned FineMappingResult carries the bare token ("susie", "susieInf", "mvsusie", ...) only. QC provenance is recorded on the sumstats' qcInfo.