gbcms

Complete orientation-aware counting system for genomic variants

Features

• 🚀 High Performance: Rust-powered core engine with multi-threading
• 🧬 Complete Variant Support: SNP, MNP, insertion, deletion, and complex variants (DelIns, SNP+Indel)
• 🧪 WFA + PairHMM Phase 3: Pangenomic fast-path WFA alignment with PairHMM fallback for complex multi-allelic classification
• 📊 Orientation-Aware: Forward and reverse strand analysis with fragment counting
• 📏 mFSD (Mutant Fragment Size Distribution): Per-allele cfDNA fragment size profiling with KS test and log-likelihood ratio
• 🔬 Statistical Analysis: Fisher's exact test for strand bias (read-level and fragment-level)
• 📁 Flexible I/O: BAM and CRAM input; VCF and MAF variant input/output formats, converted as vcf2maf / maf2vcf do
• 🎯 Quality Filters: 8 configurable read and quality filtering options with heuristic BAQ
• 🧬 RNA Mode: Transcriptome-aware counting with strandedness, splice detection, and A-to-I editing
• 🔗 UMI Support: Molecule-level deduplication with UMI-aware fragment grouping
• 🔬 Per-Molecule Observations: Export which molecule carried which allele at each variant — the layer beneath the counts — enabling read-backed phasing and allelic imbalance
• 🔧 Normalize Command: Standalone variant normalization (left-align + REF validation) without counting
• 🔁 Convert Command: VCF ↔ MAF conversion with vcf2maf / maf2vcf coordinates, without counting

Installation

Quick install:

pip install gbcms

From source (requires Rust):

git clone https://github.com/msk-access/gbcms.git
cd gbcms
pip install .

Docker:

docker pull ghcr.io/msk-access/gbcms:X.Y.Z  # Replace X.Y.Z with latest from PyPI

💡 Find the latest version on PyPI or GHCR.

📖 Full documentation: https://msk-access.github.io/gbcms/

Usage

gbcms can be used in two ways:

🔧 Option 1: Standalone CLI (1-10 samples)

Best for: Quick analysis, local processing, direct control

gbcms dna \
    --variants variants.vcf \
    --bam sample1.bam \
    --fasta reference.fa \
    --output-dir results/

Output: results/sample1.vcf

Learn more:

• 📘 CLI Quick Start
• 📖 CLI Reference — DNA
• 📖 CLI Reference — RNA
• 📖 CLI Reference — Normalize
• 📖 CLI Reference — Convert

🔄 Option 2: Nextflow Workflow (10+ samples, HPC)

Best for: Many samples, HPC clusters (SLURM), reproducible pipelines

nextflow run nextflow/main.nf \
    --input samplesheet.csv \
    --variants variants.vcf \
    --fasta reference.fa \
    --mode dna \
    -profile slurm

Features:

• ✅ Automatic parallelization across samples
• ✅ SLURM/HPC integration
• ✅ Container support (Docker/Singularity)
• ✅ Resume failed runs

Learn more:

• 🔄 Nextflow Workflow Guide
• 📋 Usage Patterns Comparison

Which Should I Use?

Quick Examples

CLI: DNA Single Sample

gbcms dna \
    --variants variants.vcf \
    --bam tumor.bam \
    --fasta hg19.fa \
    --output-dir results/ \
    --threads 4

CLI: RNA-seq

gbcms rna \
    --variants variants.vcf \
    --bam rna_sample:aligned.bam \
    --fasta hg19.fa \
    --rna-editing-db TABLE1_hg38.txt.gz \
    --output-dir results/

CLI: Normalize Variants

gbcms normalize \
    --variants variants.vcf \
    --fasta hg19.fa \
    --output results/normalized.tsv

CLI: Convert VCF ↔ MAF

gbcms convert --variants variants.vcf --output variants.maf
gbcms convert --variants variants.maf --fasta hg19.fa --output variants.vcf

CLI: Multiple Samples (Sequential)

gbcms dna \
    --variants variants.vcf \
    --bam-list samples.txt \
    --fasta hg19.fa \
    --output-dir results/

Nextflow: Many Samples (Parallel)

# samplesheet.csv:
# sample,bam,bai
# tumor1,/path/to/tumor1.bam,
# tumor2,/path/to/tumor2.bam,

nextflow run nextflow/main.nf \
    --input samplesheet.csv \
    --variants variants.vcf \
    --fasta hg19.fa \
    --mode dna \
    --outdir results \
    -profile slurm

Documentation

📚 Full Documentation: https://msk-access.github.io/gbcms/

Quick Links:

• Installation
• CLI Quick Start
• Nextflow Workflow
• CLI Reference — DNA
• CLI Reference — RNA
• CLI Reference — Normalize
• Input Formats
• Output Formats
• Architecture

Contributing

See CONTRIBUTING.md for development guidelines.

To contribute to documentation, see the gh-pages branch.

Citation

If you use gbcms in your research, please cite:

Shah, R. et al. (2026). gbcms: A high-performance orientation-aware genotype counting system for genomic variants. Available at: https://github.com/msk-access/gbcms

BibTeX:

@software{gbcms,
  author       = {Shah, Ronak and contributors},
  title        = {gbcms: A high-performance orientation-aware genotype counting system for genomic variants},
  year         = {2026},
  url          = {https://github.com/msk-access/gbcms},
  note         = {GitHub repository}
}

License

AGPL-3.0 - see LICENSE for details.

Support

• 🐛 Issues: https://github.com/msk-access/gbcms/issues
• 💬 Discussions: https://github.com/msk-access/gbcms/discussions