MutaGene is a Python package for analyzing mutations and mutational processes in cancer. It provides command-line tools that complement the MutaGene website.
Requires Python 3.10+.
Install this source checkout to use the unreleased workflows.
Until the next package release, install this checkout with pip install ".[web]".
pip install mutageneFor the local web interface:
pip install "mutagene[web]"| Command | Description |
|---|---|
mutagene fetch |
Download genomes, cancer datasets, and cohorts from remote sources |
mutagene profile |
Create mutational profiles from samples (MAF/VCF input) |
mutagene rank |
Rank mutations by driver status using expected mutability |
mutagene motif |
Test samples for presence of mutational motifs |
mutagene signature |
Decompose profiles into known mutational signatures |
mutagene serve |
Start local web server for interactive analysis |
Use mutagene <command> --help for detailed usage of each subcommand.
Try the bundled synthetic example without network access:
mutagene demo --output-dir mutagene-demoThe expected result contains 3 samples, 24 mutations, and 96 channels. This small example demonstrates execution, not biological inference.
For real mutation files, use a matching reference assembly:
# Download a genome assembly and the precalculated cohorts
mutagene fetch genome -g hg19
mutagene fetch cohorts
mutagene fetch examples
# Create a mutational profile
mutagene profile -i sample1.maf -g hg19 -o profile.tsv
# List the available cohorts, then rank driver mutations against one
mutagene rank -c
mutagene rank -i sample1.maf -g hg19 --cohort pancancer
# Search for mutational motifs
mutagene motif -i sample1.maf -g hg19 --motif 'C[C>T]G'
# Decompose into COSMIC signatures
mutagene signature -i sample1.maf -g hg19 -s COSMICv2
# Start the web interface
mutagene serveEvery subcommand accepts --params-out FILE to record the parameters of a run,
and --params-in FILE to replay it:
mutagene profile -i sample1.maf -g hg19 -o profile.tsv --params-out run.json
mutagene profile --params-in run.json -o rerun.tsvThe genome assembly must match the coordinates in your input file. Run with -v
to see how many reference alleles disagree with the assembly; a large share
means the wrong one was chosen.
Export one sample per column, then fit the labelled SBS96 count matrix:
mutagene profile -i sample1.maf -g hg19 --per-sample -o matrix.tsv
mutagene signature -i matrix.tsv -f MATRIX -o signatures.tsv --diagnostics-out diagnostics.jsonMatrix fitting needs no reference genome download.
The first column must contain Type and all 96 channel labels.
Remaining columns contain nonnegative integer counts for uniquely named samples.
VCF input supports at most one sample column. Select the tumor sample and retain its variant calls before analysis. MutaGene rejects multisample VCFs instead of pooling their records.
If you use MutaGene, please cite:
Goncearenco A, Rager SL, Li M, Sang Q, Rogozin IB, Panchenko AR. Exploring background mutational processes to decipher cancer genetic heterogeneity. Nucleic Acids Res. 2017; 45(W1):W514-W522. https://doi.org/10.1093/nar/gkx367
For the driver ranking method (mutagene rank):
Brown AL, Li M, Goncearenco A, Panchenko AR. Finding driver mutations in cancer: Elucidating the role of background mutational processes. PLOS Computational Biology 2019; 15(4): e1006981. https://doi.org/10.1371/journal.pcbi.1006981
Install the annotations extra before fetching an indexed AlphaMissense table.
Run mutagene fetch alphamissense -g hg38.
The annotation guide explains mapping requirements and the planned driver-model evaluation.
AlphaMissense annotations preserve existing B-scores and driver labels.
The pipeline examples cover DVC, Nextflow, and Snakemake. The R bridge exchanges labelled SBS96 matrices through the CLI.
--diagnostics-out reports optimizer status, fallback behavior, and background-component weights.
The likelihood guide documents convergence and compatibility changes.
Python, CLI, and web interfaces default to sparse-bic with joint background selection.
Use --method MLE or func="MLE" for full-model likelihood fitting.
The sparse-fitting guide describes subset selection and its limitations.
The release checklist separates source validation from publication.
The research index separates historical reports, current limitations, and artifact availability. The SigProfilerAssignment adapter preserves explicit channel alignment. The application-note draft requires revision before submission.