SigMA2 - Mutational Signature Analysis in Python

SigMA2 detects mutational signatures in samples with few single nucleotide variants (SNVs), where conventional signature analysis tools are unreliable. It supports hybrid capture panels, whole-exome, and whole-genome sequencing (WGS) data.

Trained classifiers ship with the package. You do not need to train anything to run an analysis — install, point SigMA2 at your data, and it uses the classifier matching your tumour type, signature and sequencing platform. See Models.

SigMA2 is the successor to SigMA. The original SigMA (v1) classifiers are also included, reimplemented in Python, so earlier analyses remain reproducible.

Installation

SigMA2 is currently an alpha pre-release, so --pre is required:

pip install --pre sigma2

Requires Python 3.9 or newer.

One dependency, sorted-nearest, is source-only on every Python version and is compiled during install, so a working C toolchain is needed (build-essential on Debian/Ubuntu, base-devel on Arch, Xcode command line tools on macOS).

Models

Both the SigMA2 classifiers and the original SigMA (v1) classifiers are bundled in the package. Nothing is downloaded, and no R installation is required.

Default: the SigMA2 classifiers

This is the normal way to use SigMA2. model="auto" is the default, so it can be left out entirely — SigMA2 selects the classifier matching your tumour type, signature of interest and sequencing platform:

import sigma2 as sg2

result = sg2.run(input="...", tumor_type="breast", soi="SBS3", seq_type="msk")

Bundled classifiers (released; every tumour type also has wgs reference models):

Other combinations ship as experimental models: lung SBS3 and SBS18 on msk, most prostate panel cells, and colorectal SBS8 on fo, msk and op (real MSK-IMPACT colorectal panels carry about a third of the SBS8 the simulated training panels do). sg2.run() does not load them unless asked (force=True), and their scores are not validated for calls.

What a classifier calls is set by its training labels, recorded on its model card (label_curation). The breast SBS3 classifiers are trained on strict labels on msk and tcga_mc3: positives are the GEL tumours whose whole-genome SBS3 is strong (band 100); the weak band, with an SBS3 fraction of 9 to 36% and mostly dominated by the flat SBS5, was left out as not judgeable on a panel. These two are not intended to call weak SBS3. The breast SBS3 classifiers on fo, op and seqcap still count the weak band as positive. The colorectal SBS18 classifiers are trained on the summed SBS18 + SBS36 exposure: the whole-genome refit splits one reactive-oxygen C>A process between the two near-identical signatures, so they call that process, not SBS18 alone.

run(readjust=True) re-derives a model's cutoffs for the SNV-depth distribution of the cohort being scored, as SigMA did (see the changelog for 0.0.16-alpha.12 and its limits).

Legacy: the SigMA v1 classifiers

Select the original classifiers with model="legacy", for reproducing earlier SigMA analyses:

result = sg2.run(input="...", model="legacy", soi="SBS3",
                 tumor_type="breast", seq_type="msk")

model="legacy" supports soi="SBS3" only, since v1 shipped Signature 3 classifiers exclusively.

Training your own

Only needed for a combination not listed above. The Add workflow annotates, clusters and simulates your cohort, then tunes a classifier you pass back as model=. See the example notebooks.

Reference data

The package ships everything a run needs in the way of models: the data store, the classifiers, and the panel definitions. Bulk reference data (~835 MB) is downloaded on demand instead:

sigma2 data list          # what exists and what is installed
sigma2 data fetch --all   # download everything
sigma2 data verify        # re-check checksums
sigma2 info               # versions, data directory, disk usage

Files land in a per-user data directory; set $SIGMA2_DATA_DIR to override it, which is the usual choice on a cluster where one pre-seeded copy is shared.

Reference genomes are separate and larger (~3 GB each): sigma2 data genome hg19.

Two things are deliberately not distributed, because they are not ours to redistribute: reference genomes, fetched from UCSC by the command above, and gnomAD germline VCFs, which you supply yourself. Obtain the latter from gnomAD and point SigMA2 at your own copy.

Access note. Until the accompanying paper is published, the bulk data lives in a private repository. sigma2 data fetch therefore needs GitHub credentials with access to it — either run gh auth login, or set SIGMA2_GITHUB_TOKEN. Without access the fetch fails with a 404; the code itself is fully functional, and any data you already hold can be used by pointing $SIGMA2_DATA_DIR at it. Please contact the authors (below) to request access.

Quick Start

Work through the example notebooks in numerical order to get started with SigMA2 and its built-in functions.

They are not included in the installed package; clone the repository to run them locally:

git clone https://github.com/sigscape/SigMA2.git
jupyter notebook SigMA2/examples

Documentation & Further Information

Find more here

Contact

Requests for use of the Software for or on behalf of for-profit entities or for any commercial purposes, please contact:

Office of Technology Development Harvard University Smith Campus Center, Suite 727E 1350 Massachusetts Avenue Cambridge, MA 02138 USA Telephone: (617) 495-3067 E-mail: otd@harvard.edu

Citation

Citation pending. The manuscript describing SigMA2 is in preparation; this section will be updated with the reference once the preprint is available.

If you use SigMA2 in your work in the meantime, please contact the authors for the citation to use.

Copyright (c) 2019-2026 - President and Fellows of Harvard College. All rights reserved.