ColocBoost multi-trait colocalization pipeline (S4)

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,
  pipCutoffToSkip = 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,
  ...
)

# 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,
  pipCutoffToSkip = 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.
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.)
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 list with elements xqtl_coloc, joint_gwas, separate_gwas, and computing_time.

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.
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.