Multi-trait colocalization with ColocBoost

Overview

colocboostPipeline() runs the colocboost multi-trait variable-selection model on QTL data — optionally with one or more GWAS studies layered on top. It accepts inputs from the QTL input classes:

QTL input	What it is
`QtlDataset`	Single-study, individual-level: per-context residualized X/Y are extracted from the dataset
`QtlSumStats`	QTL summary statistics with a shared LD reference (must be QC’d)
`MultiStudyQtlDataset`	One or more individual-level studies + optional embedded `QtlSumStats`

GWAS input (optional) is always a GwasSumStats, passed as the separate gwasSumStats argument. colocboostPipeline() does not accept a FineMappingResult for either side — colocboost runs its own variable selection.

library(pecotmr)

Bundled inputs

data(qtl_dataset_example,
     qtl_sumstats_example,
     gwas_sumstats_s4_example,
     multi_study_qtl_dataset_example)

Three analysis variants

ColocBoost can run three different model flavours in one call.

Flag	Default	What
`xqtlColoc`	TRUE	QTL-only colocboost across the QTL contexts.
`jointGwas`	FALSE	Single non-focal colocboost model that stacks all QTL contexts/studies with every supplied GWAS study.
`separateGwas`	FALSE	One focal colocboost model per GWAS study (the GWAS is the focal outcome).

xQTL-only colocalization

The default call runs colocboost over the contexts in the QTL data with no GWAS layer.

res <- colocboostPipeline(qtl_dataset_example, xqtlColoc = TRUE)
str(res, max.level = 1L)

## List of 4
##  $ xqtl_coloc    :List of 5
##   ..- attr(*, "class")= chr "colocboost"
##  $ joint_gwas    : NULL
##  $ separate_gwas : NULL
##  $ computing_time:List of 1

The result is a named list with four entries:

xqtl_coloc — output of the QTL-only run (NULL when xqtlColoc = FALSE)
joint_gwas — output of the joint QTL+GWAS run (NULL when jointGwas = FALSE)
separate_gwas — list of per-GWAS focal runs (empty when separateGwas = FALSE)
computing_time — per-variant timing record

QTL + GWAS (joint model)

res2 <- colocboostPipeline(
  qtl_dataset_example,
  gwasSumStats = gwas_sumstats_s4_example,
  xqtlColoc    = FALSE,
  jointGwas    = TRUE)
names(res2)

## [1] "xqtl_coloc"     "joint_gwas"     "separate_gwas"  "computing_time"

QTL + GWAS (per-GWAS focal models)

When you want one colocboost run per GWAS trait, with that trait as the focal outcome:

res3 <- colocboostPipeline(
  qtl_dataset_example,
  gwasSumStats = gwas_sumstats_s4_example,
  xqtlColoc    = FALSE,
  separateGwas = TRUE)
names(res3$separate_gwas)

## [1] "trait1"

Sumstats-only colocalization

A QtlSumStats input goes through the same dispatch with no individual-level data needed; the LD comes from the ldSketch GenotypeHandle carried on the collection.

resSs <- colocboostPipeline(
  qtl_sumstats_example,
  gwasSumStats = gwas_sumstats_s4_example,
  xqtlColoc    = FALSE,
  jointGwas    = TRUE)

Multi-study individual-level

resMs <- colocboostPipeline(
  multi_study_qtl_dataset_example,
  gwasSumStats = gwas_sumstats_s4_example,
  xqtlColoc    = TRUE,
  jointGwas    = TRUE)

Focal trait

focalTrait makes the xQTL-only run treat one specific trait as the focal outcome:

colocboostPipeline(
  qtl_dataset_example,
  xqtlColoc  = TRUE,
  focalTrait = "ENSG_example")

Common parameters

colocboostPipeline(
  qtlData      = qtl_dataset_example,
  gwasSumStats = gwas_sumstats_s4_example,
  contexts     = "brain",
  traitId      = "ENSG_example",
  region       = NULL,            # alternative to traitId+cisWindow
  cisWindow    = 5e5,             # required with traitId
  focalTrait   = NULL,
  xqtlColoc    = TRUE,
  jointGwas    = FALSE,
  separateGwas = FALSE,
  # Forward to colocboost::colocboost
  M            = 10,
  L            = 5,
  output_level = 1L)

Trait / context / region restrictions are pre-construction concerns on the QtlDataset (keepSamples, keepVariants, the per-context SummarizedExperiment row selection); the pipeline parameters above are the per-call refinements.

QC requirements

Individual-level (QtlDataset / MultiStudyQtlDataset): 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 pass.
Summary statistics (QtlSumStats / GwasSumStats): all variant filters, panel harmonization, LD-mismatch detection, and RAISS imputation live in summaryStatsQc(). The pipeline rejects inputs whose getQcInfo() is empty.

pecotmr authors

2026-07-21