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

A release ships a prebuilt wheel for every CPython from 3.10 on Linux x86_64 (glibc 2.28+: RHEL 8 and newer) and on Apple silicon Macs (macOS 11+), and the source distribution. On Intel Macs and older Linux, pip builds the source, which needs a Rust toolchain and a C compiler. The exact platform matrix and build prerequisites are on the Installation page.

From source (Rust toolchain + C compiler):

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?

Scenario	Recommendation
1-10 samples, local machine	CLI
10+ samples, HPC cluster	Nextflow
Quick ad-hoc analysis	CLI
Production pipeline	Nextflow
Need auto-parallelization	Nextflow
Full manual control	CLI

---

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: QC summary of finished outputs

gbcms summarize results/*.maf                                   # the block a run logs
gbcms summarize --format multiqc --output-dir qc/ results/*.maf # MultiQC custom content

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/

This is the beginning of the README. Read the rest at the original. Read the full README ↗