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 (ldSketch). Must already have been passed through summaryStatsQc (the pipeline rejects inputs whose getQcInfo() is empty).

  • 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 FineMappingResult 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,
  mafCutoff = 0,
  macCutoff = 0,
  imissCutoff = 1,
  pipCutoffToSkip = 0,
  absZCutoffToSkip = 0,
  bfCutoffToSkip = 0,
  logBfCutoffToSkip = 0,
  alleleFlip = TRUE,
  ...
)

# S4 method for class 'QtlSumStats'
colocboostPipeline(
  qtlData,
  gwasSumStats = NULL,
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  focalTrait = NULL,
  xqtlColoc = TRUE,
  jointGwas = FALSE,
  separateGwas = FALSE,
  alleleFlip = TRUE,
  mafCutoff = 0,
  macCutoff = 0,
  imissCutoff = 1,
  ...
)

# 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,
  mafCutoff = 0,
  macCutoff = 0,
  imissCutoff = 1,
  pipCutoffToSkip = 0,
  absZCutoffToSkip = 0,
  bfCutoffToSkip = 0,
  logBfCutoffToSkip = 0,
  alleleFlip = TRUE,
  ...
)

# S4 method for class 'ANY'
colocboostPipeline(qtlData, gwasSumStats = NULL, ...)

Arguments

qtlData

One of QtlDataset, QtlSumStats, or MultiStudyQtlDataset.

gwasSumStats

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

...

Additional arguments forwarded to colocboost (e.g., M, L, output_level).

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 getResidualizedGenotypes / getPhenotypes for the variant-window selection).

region

Optional single-range GRanges describing the analysis window. Mutually exclusive with traitId (see the QtlDataset accessors).

cisWindow

Optional cis window in basepairs; required with traitId, optional with 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.

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.

mafCutoff, macCutoff, imissCutoff

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

pipCutoffToSkip

Individual-level pre-filter (ports the legacy pip_cutoff_to_skip_ind). Scalar (applied to every context) or a context-named numeric vector. For each context, every outcome is fit with a single-effect SuSiE (L = 1) and dropped unless some variant's PIP exceeds the cutoff; a context with no surviving outcome is skipped. 0 (default) disables it; a negative value uses 3 / n_variants. (Summary-statistic skipping is handled upstream by summaryStatsQc's own pipCutoffToSkip.)

absZCutoffToSkip, bfCutoffToSkip, logBfCutoffToSkip

Alternative individual-level pre-filter metrics used in place of pipCutoffToSkip: drop an outcome unless its maximum marginal |z| (absZCutoffToSkip), or its maximum per-variant single-effect Bayes factor (bfCutoffToSkip) / log Bayes factor (logBfCutoffToSkip) from the L = 1 fit, exceeds the cutoff. Scalars, each defaulting to 0 (off). Exactly one screening metric may be enabled: setting any of these requires pipCutoffToSkip = 0.

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.

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 getColocPairs (also available as as.data.frame), getColocVariants or getColocBoostOutcomes; timings are on getComputingTime and the region-wide marginal probabilities on getRegionVcp.

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 getGenotypes() / getResidualizedGenotypes(). The pipeline does not run a separate individual-level QC pass.

  • mafCutoff / macCutoff / imissCutoff act at ANALYSIS time on the sumstat sides, measured against the LD reference panel: a variant whose panel genotypes fall below the cutoffs is dropped before the LD matrix is built. They apply to a QtlSumStats QTL side and to a GwasSumStats GWAS side (so they still bite when the QTL side is individual-level). Defaults (0, 0, 1) filter nothing. Unlike summaryStatsQc(imputeOpts = ...), which only bounds what RAISS will impute, these discard observed variants.

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

Analysis variants

  • xqtlColoc (default TRUE): run a colocboost model over the QTL contexts only (individual-level inputs).

  • 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)