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.

Indels, MMR deficiency and HRD

Indel features

From a VCF or MAF, SigMA2 keeps the indels next to the SNV matrix (Samples(...).indels). Six counts per sample come from them (sigma2.indel_features):

• nins / ndel: all insertions and deletions;
• nmsi_ins / nmsi_del: insertions and deletions in a microsatellite (repeat) locus;
• mmej: deletions of at least 5 bp with at least 2 bp of microhomology at the breakpoint;
• nhej: deletions of at least 5 bp without that microhomology.

VCF-style records (with an anchor base) and MAF-style records (-) give the same counts. The repeat loci in the data directory are hg19; on hg38 the two nmsi_* counts need beds= in that build.

These features are added to the input whenever something reads them: hrd=True, predict_mmrd_ppd(), or an explicit indels=. Plain msi=True adds SNV-based steps only and leaves the input as it was. MMR-deficiency/POLE calls therefore run straight from a MAF:

mmrd = sg2.predict_mmrd_ppd(input="cohort.maf", ref_genome="hg19", tumor_type="uterus",
                            seq_type="tcga_mc3", soi="SBS3", model="legacy",
                            catalog="cosmic_v2_inhouse", mva=False)

HRD: the CSI-HRD classifier

HRD is a classifier like any other: ask for soi="HRD". The classifier is CSI-HRD (Gulhan et al., bioRxiv 10.1101/2025.10.13.681986). It combines three kinds of evidence:

• the SigMA Signature 3 score, likelihood and exposure;
• the mmej and nhej deletion counts;
• copy-number instability.

out = sg2.run(input="panels.maf", ref_genome="hg19", tumor_type="breast", seq_type="msk",
              soi="HRD", segments="panels.seg")
out.df[["HRD_mva", "pass_mva", "pass_mva_strict", "confidence", "hrd_call"]]

Output. The answer comes in SigMA's own columns:

hrd_call gives HRD, HRD-low, HRP, or MMRD/POLE for hypermutated tumours, which are set aside first. HRD means both the pan-cancer and the tumour-type score exceed 0.5, and HRP that neither does. The Signature 3 run behind it stays in the output as SBS3_mva, SBS3_pass_mva, ….

Managing models. HRD models are listed, loaded and checked like the signature classifiers: sg2.models(soi="HRD"), sg2.model("breast/HRD/msk"), sg2.verify_model(...) and sg2.describe(). hrd=True adds the same columns to a run for another soi.

Copy number. The model variant follows what segments= holds:

• Allele-specific (ASCAT, FACETS): the genomic instability score gis (HRD-LOH + TAI + LST), as in the preprint.
• Log-ratio (a panel's .seg file, e.g. MSK-IMPACT): total-copy-number instability. That is fga (the fraction of the genome with |log ratio| ≥ 0.2) and lst_lr (large-scale transitions).
• Neither: a model trained without copy number.

You can also pass gis=, or give gis / fga / lst_lr columns in the input.

Shipped models:

• msk (MSK-IMPACT): trained on 28,834 real MSK-IMPACT 50K panels and on TCGA exomes reduced to MSK-IMPACT panels. The TCGA exomes carry complete truth, including germline carriers. Allele-specific segments are read on the IMPACT gene grid the model stores, as MSK's gene-level FACETS calls are.
• tcga_mc3 (TCGA exomes).
• seqcap, fo (FoundationOne), op (OncoPanel): trained on TCGA exomes reduced to each footprint. Out of fold they reach AUC 0.95–0.96 against biallelic BRCA1/2; SigMA's Sig3 reaches 0.83 on seqcap.

Each has a pan-cancer model and tumour-type models. With allele-specific copy number they use the three GIS components (HRD-LOH, TAI, LST) rather than their sum.

Benchmark. Real MSK-IMPACT 50K panels, biallelic BRCA1/2, scored out of fold; AUC (examples/hrd_msk/csi/msk50k_pancan.py):

At a 10 % false-positive rate, CSI-HRD finds 63 % of biallelic breast tumours; SigMA SBS3 finds 33 %. On TCGA exomes, out of fold, it reaches 0.95, against 0.82 for SigMA's Sig3 score alone.

To train a model for another assay or cohort, build the feature table and give biallelic BRCA1/2 status per tumour:

F = sg2.hrd_features(input="cohort.maf", tumor_type="breast", seq_type="my_assay",
                     segments="segments.tsv", ref_genome="hg19")
F["brca"] = brca_biallelic                       # bool per sample
sg2.tune_hrd(F, labels="brca", seq_type="my_assay")   # saved; then run(..., seq_type="my_assay", soi="HRD")

The same from the shell:

sigma2 hrd score --input panels.maf --tumor-type breast --seq-type msk --segments panels.seg -o hrd.tsv
sigma2 hrd features | sigma2 hrd tune | sigma2 hrd gis | sigma2 hrd models

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.