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(
    qtlDatasetExample,
    qtlSumStatsExample,
    gwasSumStatsS4Example,
    multiStudyQtlDatasetExample
)

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(qtlDatasetExample, xqtlColoc = TRUE)
str(res, max.level = 1L)

## Formal class 'ColocBoostResult' [package "pecotmr"] with 9 slots

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(
    qtlDatasetExample,
    gwasSumStats = gwasSumStatsS4Example,
    xqtlColoc = FALSE,
    jointGwas = TRUE
)
names(res2)

## NULL

QTL + GWAS (per-GWAS focal models)

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

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

## NULL

Sumstats-only colocalization

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

resSs <- colocboostPipeline(
    qtlSumStatsExample,
    gwasSumStats = gwasSumStatsS4Example,
    xqtlColoc = FALSE,
    jointGwas = TRUE
)

Multi-study individual-level

resMs <- colocboostPipeline(
    multiStudyQtlDatasetExample,
    gwasSumStats = gwasSumStatsS4Example,
    xqtlColoc = TRUE,
    jointGwas = TRUE
)

Focal trait

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

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

Common parameters

colocboostPipeline(
    qtlData = qtlDatasetExample,
    gwasSumStats = gwasSumStatsS4Example,
    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.

Session info

sessionInfo()

## R version 4.5.3 (2026-03-11)
## Platform: x86_64-conda-linux-gnu
## Running under: Ubuntu 24.04.4 LTS
## 
## Matrix products: default
## BLAS/LAPACK: /home/runner/work/pecotmr/pecotmr/.pixi/envs/default/lib/libopenblasp-r0.3.34.so;  LAPACK version 3.12.0
## 
## locale:
##  [1] LC_CTYPE=C.UTF-8       LC_NUMERIC=C           LC_TIME=C.UTF-8       
##  [4] LC_COLLATE=C.UTF-8     LC_MONETARY=C.UTF-8    LC_MESSAGES=C.UTF-8   
##  [7] LC_PAPER=C.UTF-8       LC_NAME=C              LC_ADDRESS=C          
## [10] LC_TELEPHONE=C         LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C   
## 
## time zone: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] pecotmr_0.7.8
## 
## loaded via a namespace (and not attached):
##   [1] tidyselect_1.2.1            dplyr_1.2.1                
##   [3] farver_2.1.2                Biostrings_2.78.0          
##   [5] S7_0.2.2                    bitops_1.0-9               
##   [7] fastmap_1.2.0               reshape_0.8.10             
##   [9] mathjaxr_2.0-0              digest_0.6.39              
##  [11] lifecycle_1.0.5             survival_3.8-11            
##  [13] magrittr_2.0.5              compiler_4.5.3             
##  [15] rlang_1.3.0                 sass_0.4.10                
##  [17] tools_4.5.3                 yaml_2.3.12                
##  [19] knitr_1.51                  S4Arrays_1.10.1            
##  [21] htmlwidgets_1.6.4           bit_4.6.0                  
##  [23] DelayedArray_0.36.0         plyr_1.8.9                 
##  [25] RColorBrewer_1.1-3          abind_1.4-8                
##  [27] BiocParallel_1.44.0         withr_3.0.3                
##  [29] purrr_1.2.2                 numDeriv_2016.8-1.1        
##  [31] BiocGenerics_0.56.0         desc_1.4.3                 
##  [33] grid_4.5.3                  stats4_4.5.3               
##  [35] susieR_0.16.6               ggplot2_4.0.3              
##  [37] scales_1.4.0                MASS_7.3-66                
##  [39] MultiAssayExperiment_1.36.1 SummarizedExperiment_1.40.0
##  [41] cli_3.6.6                   rmarkdown_2.32             
##  [43] metafor_5.0-1               crayon_1.5.3               
##  [45] ragg_1.5.2                  generics_0.1.4             
##  [47] otel_0.2.0                  RcppParallel_5.1.11-2      
##  [49] tzdb_0.5.0                  BiocBaseUtils_1.12.0       
##  [51] colocboost_1.0.9            cachem_1.1.0               
##  [53] stringr_1.6.0               splines_4.5.3              
##  [55] metadat_1.6-0               parallel_4.5.3             
##  [57] XVector_0.50.0              matrixStats_1.5.0          
##  [59] vctrs_0.7.3                 Matrix_1.7-6               
##  [61] jsonlite_2.0.0              IRanges_2.44.0             
##  [63] hms_1.1.4                   S4Vectors_0.48.0           
##  [65] bit64_4.8.6                 mixsqp_0.3-54              
##  [67] irlba_2.3.7                 archive_1.1.13             
##  [69] systemfonts_1.3.2           tidyr_1.3.2                
##  [71] jquerylib_0.1.4             snpStats_1.60.0            
##  [73] glue_1.8.1                  pkgdown_2.2.1              
##  [75] codetools_0.2-20            stringi_1.8.9              
##  [77] gtable_0.3.6                GenomicRanges_1.62.1       
##  [79] quadprog_1.5-8              tibble_3.3.1               
##  [81] pillar_1.11.1               htmltools_0.5.9            
##  [83] Seqinfo_1.0.0               R6_2.6.1                   
##  [85] zigg_0.0.2                  textshaping_1.0.5          
##  [87] vroom_1.7.1                 evaluate_1.0.5             
##  [89] lattice_0.23-1              Biobase_2.70.0             
##  [91] readr_2.2.0                 tictoc_1.2.1               
##  [93] Rsamtools_2.26.0            Rfast_2.1.5.2              
##  [95] bslib_0.12.0                Rcpp_1.1.2                 
##  [97] SparseArray_1.10.8          nlme_3.1-170               
##  [99] xfun_0.60                   fs_2.1.0                   
## [101] MatrixGenerics_1.22.0       pkgconfig_2.0.3

pecotmr authors

2026-09-04