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-3.12. The upper bound comes from a transitive dependency (pyranges -> ncls), which publishes no wheels for 3.13 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:

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.