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 fine-mapping result 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 ldReference 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 genotypes() / residualizedGenotypes(). 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 qcInfo() is empty.

Session info

sessionInfo()

## R version 4.5.3 (2026-03-11)
## Platform: x86_64-conda-linux-gnu
## Running under: Ubuntu 24.04.5 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.9.3
## 
## loaded via a namespace (and not attached):
##   [1] DBI_1.3.0                   bitops_1.1-0               
##   [3] httr2_1.3.0                 rlang_1.3.0                
##   [5] magrittr_2.0.5              otel_0.2.0                 
##   [7] matrixStats_1.5.0           susieR_0.16.6              
##   [9] compiler_4.5.3              RSQLite_3.53.3             
##  [11] systemfonts_1.3.2           vctrs_0.7.3                
##  [13] colocboost_1.0.9            quadprog_1.5-8             
##  [15] stringr_1.6.0               pkgconfig_2.0.3            
##  [17] crayon_1.5.3                fastmap_1.2.0              
##  [19] dbplyr_2.6.0                backports_1.5.1            
##  [21] XVector_0.50.0              Rsamtools_2.26.0           
##  [23] rmarkdown_2.32              tzdb_0.5.0                 
##  [25] ragg_1.5.2                  purrr_1.2.2                
##  [27] bit_4.6.0                   xfun_0.61                  
##  [29] Rfast_2.1.5.2               MultiAssayExperiment_1.36.2
##  [31] cachem_1.1.0                jsonlite_2.0.0             
##  [33] blob_1.3.0                  DelayedArray_0.36.1        
##  [35] reshape_0.8.10              tictoc_1.2.1               
##  [37] BiocParallel_1.44.0         irlba_2.4.1                
##  [39] parallel_4.5.3              R6_2.6.1                   
##  [41] bslib_0.12.0                stringi_1.8.9              
##  [43] RColorBrewer_1.1-3          GenomicRanges_1.62.1       
##  [45] jquerylib_0.1.4             numDeriv_2016.8-1.1        
##  [47] Rcpp_1.1.2                  Seqinfo_1.0.0              
##  [49] SummarizedExperiment_1.40.0 knitr_1.52                 
##  [51] readr_2.2.0                 IRanges_2.44.0             
##  [53] BiocBaseUtils_1.12.0        Matrix_1.7-6               
##  [55] tidyselect_1.2.1            abind_1.4-8                
##  [57] yaml_2.3.12                 codetools_0.2-20           
##  [59] curl_8.0.0                  metafor_5.0-1              
##  [61] lattice_0.23-1              tibble_3.3.1               
##  [63] plyr_1.8.9                  withr_3.0.3                
##  [65] Biobase_2.70.0              S7_0.2.2                   
##  [67] evaluate_1.0.5              archive_1.1.13             
##  [69] desc_1.4.3                  RcppParallel_5.1.11-2      
##  [71] BiocFileCache_3.0.0         Biostrings_2.78.0          
##  [73] filelock_1.0.3              pillar_1.11.1              
##  [75] MatrixGenerics_1.22.0       metadat_1.6-0              
##  [77] checkmate_2.3.3             stats4_4.5.3               
##  [79] generics_0.1.4              vroom_1.7.1                
##  [81] mathjaxr_2.0-0              S4Vectors_0.48.1           
##  [83] hms_1.1.4                   ggplot2_4.0.3              
##  [85] scales_1.4.0                glue_1.8.1                 
##  [87] tools_4.5.3                 robustbase_0.99-7          
##  [89] fs_2.1.0                    grid_4.5.3                 
##  [91] PlinkMatrix_1.0.0           tidyr_1.3.2                
##  [93] nlme_3.1-170                cli_3.6.6                  
##  [95] zigg_0.0.2                  textshaping_1.0.5          
##  [97] mixsqp_0.3-54               S4Arrays_1.10.1            
##  [99] dplyr_1.2.1                 gtable_0.3.6               
## [101] DEoptimR_1.2-1              sass_0.4.10                
## [103] digest_0.6.39               BiocGenerics_0.56.0        
## [105] SparseArray_1.10.10         htmlwidgets_1.6.4          
## [107] farver_2.1.2                memoise_2.0.1              
## [109] htmltools_0.5.9             pkgdown_2.2.1              
## [111] lifecycle_1.0.5             bit64_4.8.6                
## [113] MASS_7.3-66

pecotmr authors

2026-10-22