MuTopia — Mutational Topography Inference and Analysis¶

MuTopia is a Python toolkit for studying how mutational signatures vary across the genome. It learns topographic models that jointly explain which mutational processes are active in a genome and how local genomic context (chromatin state, replication timing, transcription level, DNA sequence composition, …) shapes process’s mutation rate profiles.

Build G-Tensors

Integrate any combination of genomic feature tracks (bigWig, BED, bedGraph) with mutation calls into a spatially-indexed G-Tensor — the core data structure behind every MuTopia analysis.

Tutorial 1: Building G-Tensors

Train Models

Decompose mutation counts into topographically-resolved components with expressive, nonlinear rate models. Tune hyperparameters automatically with Optuna.

Tutorial 3: Tuning and training models

Annotate Data

Apply a trained model to any VCF — including panel and exome data - to learn which topographic processes are driving mutagenes. Go a step further and annotate each mutation with its most likely generating process.

Tutorial 5: Annotating VCFs with a Pre-Trained Model

Five minutes to MuTopia¶

The fastest way to get started is to:

Pull the docker.
Download a pre-trained model from our Zenodo repository.
Apply it to your mutation data. The annotate-vcf command infers which topographical mutational processes are active in your sample and annotates each mutation with its most likely generating process.

docker pull allenlynch/mutopia:latest

TUMOR_TYPE="Liver-HCC"
FASTA="path/to/hg38.fasta"

ZENODO="https://zenodo.org/records/18803136/files"
MODEL=${TUMOR_TYPE}.model.pkl
DATA=${TUMOR_TYPE}.nc
wget ${ZENODO}/${MODEL}
wget ${ZENODO}/${DATA}
wget ${ZENODO}/${DATA}.regions.bed

VCF=CHC197.sample.hg38.vcf.gz
wget -O ${VCF} https://github.com/sigscape/MuTopia/releases/download/v1.0.5/CHC197.sample.hg38.vcf.gz

topo-model setup ${MODEL} ${DATA} ${TUMOR_TYPE}.setup.nc -@ 4

mutopia-sbs annotate-vcf ${MODEL} ${TUMOR_TYPE}.setup.nc ${VCF} --no-pass-only --no-cluster -fa ${FASTA} -w VAF -o annotated.vcf

MuTopia can do a lot more than just data annotation. Check out the tutorials for walkthroughs on data munging, model training, and mutational topography analysis!