Skip to contents

ColocBoost multi-trait colocalization pipeline (S4)

Source: R/colocboostPipeline.R
colocboostPipeline.Rd

Protocol-level multi-trait colocalization analysis using colocboost. Dispatches on the QTL input type:

  • QtlDataset – single-study, individual-level multi-context data. Per-context residualized X / Y are extracted from the dataset (filtering knobs on the constructor apply lazily inside the accessors).

  • QtlSumStats – summary-statistic-only QTL data with a shared LD reference (ldReference). Must already have been passed through summaryStatsQc (the pipeline rejects inputs whose qcInfo() is empty). Every analysis variant is available on this input, including xqtlColoc, which colocalizes the QTL studies against each other with no GWAS involved.

  • MultiStudyQtlDataset – a mixture of one or more individual-level QtlDataset studies and an optional QtlSumStats collection.

GWAS is optional and always passed separately as a GwasSumStats object (must also be QC'd).

colocboostPipeline does not accept a fine-mapping result for either side; colocboost has its own variable-selection algorithm.

Usage

colocboostPipeline(qtlData, gwasSumStats = NULL, ...)

# S4 method for class 'QtlDataset'
colocboostPipeline(
  qtlData,
  gwasSumStats = NULL,
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  focalTrait = NULL,
  xqtlColoc = TRUE,
  jointGwas = FALSE,
  separateGwas = FALSE,
  samples = NULL,
  panelFilterParam = PanelFilterParam(),
  signalScreenParam = SignalScreenParam(),
  alleleFlip = TRUE,
  residualizationParam = ResidualizationParam(),
  methodArgs = ColocboostOptions()
)

# S4 method for class 'QtlSumStats'
colocboostPipeline(
  qtlData,
  gwasSumStats = NULL,
  contexts = NULL,
  traitId = NULL,
  focalTrait = NULL,
  xqtlColoc = TRUE,
  jointGwas = FALSE,
  separateGwas = FALSE,
  alleleFlip = TRUE,
  panelFilterParam = PanelFilterParam(),
  methodArgs = ColocboostOptions()
)

# S4 method for class 'MultiStudyQtlDataset'
colocboostPipeline(
  qtlData,
  gwasSumStats = NULL,
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  focalTrait = NULL,
  xqtlColoc = TRUE,
  jointGwas = FALSE,
  separateGwas = FALSE,
  samples = NULL,
  panelFilterParam = PanelFilterParam(),
  signalScreenParam = SignalScreenParam(),
  alleleFlip = TRUE,
  residualizationParam = ResidualizationParam(),
  methodArgs = ColocboostOptions()
)

Arguments

qtlData

One of QtlDataset, QtlSumStats, or MultiStudyQtlDataset.

gwasSumStats

Optional GwasSumStats with the GWAS studies to colocalize against. NULL to skip GWAS colocalization.

...

Required by the generic; the methods take no further arguments.

contexts

Optional character vector of context names to restrict the individual-level / QtlSumStats QTL analysis to. When NULL (default), every context present is used.

traitId

Optional character vector of trait identifiers to restrict the analysis to. When supplied with an individual-level QtlDataset input, cisWindow is required (passed to residualizedGenotypes / molecularTraits for the variant-window selection).

region

Optional single-range GRanges describing the analysis window. Mutually exclusive with traitId (see the QtlDataset accessors). Individual-level input only: summary statistics carry no genotypes to window, so the QtlSumStats method does not take it — matching fineMappingPipeline and twasWeightsPipeline.

cisWindow

Optional cis window in basepairs; required with traitId, optional with region. Individual-level input only, as for region.

focalTrait

Optional trait name; when supplied and present in the assembled outcome list, the colocboost xQTL-only run uses it as the focal outcome. Only xqtlColoc reads it: jointGwas is non-focal by construction and separateGwas always makes the GWAS study focal.

xqtlColoc, jointGwas, separateGwas

Logical flags selecting which colocboost variants to run.

samples

Optional character vector of sample IDs to restrict the analysis to; NULL (default) uses all samples.

panelFilterParam

Analysis-time filters applied to the summary-statistic sides against the LD reference panel, built with PanelFilterParam: a variant whose panel genotypes fall below its cutoffs is dropped before the LD matrix is built. The defaults filter nothing. See the Details section for how these relate to the individual-level cutoffs recorded on a QtlDataset.

signalScreenParam

Individual-level pre-filter (ports the legacy pip_cutoff_to_skip_ind), built with SignalScreenParam. For each context every outcome is fit with a single-effect SuSiE (L = 1) and dropped unless the chosen metric exceeds its cutoff; a context with no surviving outcome is skipped:

  • pip — the maximum PIP. A negative cutoff uses 3 / n_variants. Uniquely here it may also be a context-named numeric vector rather than a scalar, applying a different cutoff per context.

  • absZ — the maximum marginal |z|.

  • bf / logBf — the maximum per-variant Bayes factor or log Bayes factor from the L = 1 fit.

Only one metric may be enabled, which SignalScreenParam enforces when you build it. Unset (the default) screens nothing. Summary-statistic skipping is handled upstream by summaryStatsQc.

alleleFlip

Logical, default TRUE. When TRUE, harmonize variants across the individual X, sumstats, and LD by (chrom, pos) with ref/alt swaps recognized (flipping z / residualized dosage / LD to a shared coding); when FALSE, match on exact alleles only (names-only), so a ref/alt swap is treated as a distinct variant.

residualizationParam

Covariate residualization settings for individual-level input, built with ResidualizationParam. Reaches both residualizedGenotypes and residualizedPhenotypes, so it governs what is regressed out of each side and — through scaleResiduals — whether the columns are scaled to unit variance. Previously absent, which left this pipeline on the dataset's own settings with no per-call say, unlike fineMappingPipeline and twasWeightsPipeline. Ignored on QtlSumStats input, which has nothing to residualize.

methodArgs

Additional arguments forwarded to colocboost::colocboost, built with ColocboostOptions. Names are checked against that function's formals, so a misspelled option errors instead of being dropped inside the run. The data slots the pipeline assembles itself (X, Y, sumstat, LD, X_ref, focal_outcome_idx) are refused.

Value

A ColocBoostResult: one element per confidence set (CoS) across every analysis that ran, holding that set's member variants with their vcp. The analysis column marks which run each set came from (xqtl_coloc, joint_gwas or separate_gwas), and gwasStudy distinguishes the per-study separate_gwas runs. Outcome-specific (uncolocalized) sets are included with isColocalized = FALSE.

Project it with colocPairs (also available as as.data.frame), colocVariants or colocBoostOutcomes; timings are on computingTime and the region-wide marginal probabilities on regionVcp.

QC contract

  • Individual-level QC (MAF / MAC / X-variance / per-sample missingness, sample / variant restrictions) lives on the QtlDataset constructor and is applied lazily inside genotypes() / residualizedGenotypes(). The pipeline does not run a separate individual-level QC pass.

  • panelFilterParam acts at ANALYSIS time on the sumstat sides, measured against the LD reference panel: a variant whose panel genotypes fall below its cutoffs is dropped before the LD matrix is built. It applies to a QtlSumStats QTL side and to a GwasSumStats GWAS side (so it still bites when the QTL side is individual-level). Its defaults filter nothing. Unlike summaryStatsQc(raissParam = ...), which only bounds what RAISS will impute, these discard observed variants.

  • All summary-statistic QC (variant filters, harmonization against the ldReference, LD-mismatch detection, RAISS imputation, etc.) lives in summaryStatsQc. The pipeline rejects any QtlSumStats or GwasSumStats where length(qcInfo(x)) == 0L.

Analysis variants

  • xqtlColoc (default TRUE): run a colocboost model over the QTL outcomes only, excluding gwasSumStats. Works for either data form – the individual-level contexts, the summary-level QTL studies, or both together when a MultiStudyQtlDataset carries a mixture. This is the only variant that honors focalTrait.

  • jointGwas (default FALSE): run a non-focal colocboost model that combines all QTL contexts/studies with the supplied gwasSumStats studies.

  • separateGwas (default FALSE): run one focal colocboost model per GWAS study, where the GWAS is the focal outcome.

Examples

data(qtlDatasetExample)
colocboostPipeline(qtlDatasetExample, xqtlColoc = TRUE)
#> ====== Performing xQTL-only ColocBoost on 1 contexts. =====
#> Validating input data.
#> Starting gradient boosting algorithm.
#> Gradient boosting for outcome 1 converged after 27 iterations!
#> Performing inference on colocalization events.
#> No colocalization results in this region!
#> No uncolocalized results in this region!
#> ColocBoostResult with 0 confidence set(s)