SigMA2 - Mutational Signature Analysis in Python

SigMA2 detects mutational signatures and homologous-recombination deficiency (HRD) in tumours with few single nucleotide variants (SNVs): hybrid-capture panels, whole exomes and whole genomes. Trained classifiers ship with the package: install it, point it at your mutations, and say which question you are asking.

SigMA2 is the successor to SigMA; the original SigMA (v1) classifiers are included too, so earlier analyses stay reproducible.

Choose a classifier

Signatures and HRD go through sg2.run(), where the soi ("signature of interest") argument picks the classifier; mismatch-repair deficiency and POLE through sg2.predict_mmrd_ppd():

Ask for HRD rather than SBS3 when the decision is about HR deficiency. On real MSK-IMPACT panels CSI-HRD finds 63 % of biallelic BRCA1/2 breast tumours at a 10 % false-positive rate, SigMA2 SBS3 33 % (see HRD).

Installation

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

pip install --pre sigma2

Python 3.9 or newer. One dependency, sorted-nearest, compiles during install, so a C toolchain is needed (build-essential on Debian/Ubuntu, base-devel on Arch, the Xcode command line tools on macOS, the Microsoft C++ Build Tools on Windows). On Windows, FASTA files must be plain text (not bgzip-compressed).

Quickstart

import sigma2 as sg2

# Signature 3 on MSK-IMPACT breast panels
sbs3 = sg2.run(input="panels.maf", ref_genome="hg19", tumor_type="breast", seq_type="msk", soi="SBS3")

# HRD on the same panels, with their copy-number segments
hrd = sg2.run(input="panels.maf", ref_genome="hg19", tumor_type="breast", seq_type="msk", soi="HRD",
              segments="panels.seg")

hrd.df[["HRD_mva", "hrd_call", "confidence"]]

input is a MAF, a VCF (or a directory of them), or a 96-channel SNV matrix (CSV or DataFrame). seq_type is the sequencing platform:

See what is installed

sg2.describe()                          # every classifier per tumour type and platform, with its status
sg2.models(tumor_type="breast")         # "breast/SBS3/msk", "breast/HRD/msk", "breast/MMRD/msk", ...
sg2.model("breast/HRD/msk")             # load one
sg2.verify_model("breast/HRD/msk")      # integrity check (SHA-256 fingerprint)

describe() shows one table per tumour type, headed by its SNV floor (samples with fewer SNVs are not scored by any classifier). Rows are classifiers (signatures, HRD and MMRD/POLE alike), columns are platforms:

breast  ·  SNV floor 5
        fo    msk    op    seqcap    tcga_mc3    wgs
------  ----  -----  ----  --------  ----------  -----
APOBEC  ●     ●      ●     ●         ●           ●
SBS18   ●     ●      ●     ●         ●           ●
SBS3    ●     ●      ●     ●         ●           ●
SBS8    ●     ●      ●     ●         ●           ●
HRD     ●     ●      ●     ●         ●           —
MMRD    ●     ●      ●     ●         ●           —

● released · ◐ released, weak evidence: a positive call raises the odds little · ▲ experimental: only its ranking holds, and run() refuses it without force=True · — none. Weak and experimental cells add the positive likelihood ratio (LR+) of a call. Tumour types whose tables would be identical share one. The original SigMA (v1) classifiers, which model="legacy" loads, are listed separately.

models(), model() and verify_model() take every kind by the same name, tumour/classifier/platform: "breast/SBS3/msk", "breast/HRD/msk", "breast/MMRD/msk".

Bundled classifiers (the GEL-trained signature classifiers also have wgs reference models; the PCAWG-trained ones list wgs where it passed the release gate):

Mutational signatures

model="auto" (the default) picks the classifier for your tumour type, signature and platform; names are matched in any case ("Breast", "MSK", "sbs3").

• SNV floor. Tumours with fewer SNVs than the floor the classifier was trained at (on its model card, snv_cutoff) are not scored. snv_ctf= overrides it.
• Catalog. Leave catalog= out: the classifier's own is used. Passing another one warns that the scores are not the validated ones; one that lacks the signature of interest is refused.
• Platform. Pass seq_type=. seq_type="auto" picks the platform whose training cohort's median SNV count is closest to your cohort's, and says which it picked. Panels of similar size (msk, fo, op) cannot be told apart that way.
• Your own classifier: run(model=sg2.model("breast/SBS3/msk", root_dir="shared_store")).

Output. <soi>_mva is the score. pass_mva is a call at the cutoff for a 10 % false-positive rate and pass_mva_strict at 1 %. confidence is high (past 1 %), low (past 10 % only) or negative.

Experimental classifiers. Some combinations ship as experimental: lung SBS3 and SBS18 on msk, most prostate panel cells, and colorectal SBS8 on fo, msk and op. Their ranking is usable but their calls are not, so run() refuses them unless you pass force=True.

What a classifier calls is set by its training labels, recorded on its model card (label_curation).

• The breast SBS3 classifiers on msk and tcga_mc3 call strong SBS3 only. They are not intended to call weak SBS3.
• The colorectal SBS18 classifiers call the summed SBS18 + SBS36 process.

readjust=True re-derives a model's cutoffs for the SNV depth of the cohort you score, as SigMA did.

SigMA v1. model="legacy" runs the original SigMA classifiers (Signature 3 only), for reproducing earlier analyses:

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

Homologous-recombination deficiency (HRD)

soi="HRD" runs CSI-HRD (Gulhan et al., bioRxiv 10.1101/2025.10.13.681986). It combines three kinds of evidence:

• SigMA's Signature 3 score, likelihood and exposure;
• deletions of at least 5 bp with microhomology (mmej) and without (nhej);
• copy-number instability.

CSI stands for copy number, single-base substitutions and indels. Each tumour gets a pan-cancer score and a tumour-type score. The call combines them:

HRD_mva is the mean of the two scores; hrd_score_pan and hrd_score_type are the parts. The Signature 3 run behind it stays in the output as SBS3_*.

What you pass.

• Mutations. A VCF or MAF, so SigMA2 can count the deletions. With a matrix input, add mmej and nhej columns, or pass indels=.
• Copy number, optional but strongly recommended. Pass segments=; SigMA2 picks the model variant from what the file holds:
  • Allele-specific segments (ASCAT, FACETS): the three parts of the genomic instability score (GIS) -- loss-of-heterozygosity regions (HRD-LOH), telomeric allelic imbalance (TAI) and large-scale state transitions (LST). On msk they are read on the IMPACT gene grid, as MSK's gene-level calls are.
  • Log-ratio segments (a panel .seg): fga (fraction of the genome with |log ratio| ≥ 0.2) and lst_lr (large-scale transitions).
  • None: a model without copy number, which is weaker.
• hrd_loh / tai / lst or fga / lst_lr columns in a matrix input are used as given. A GIS sum alone is not enough for the allele-specific variant; SigMA2 warns and falls back.

What run() refuses, before computing anything:

• seq_type="auto", or a platform without an HRD model;
• a tumour type that platform's model never saw;
• hrd=False, mva=False and readjust=True, which do not apply to HRD.

Platforms and tumour types: see See what is installed.

How it performs. Real MSK-IMPACT 50K panels, biallelic BRCA1/2 truth, scored out of fold; AUC:

On TCGA exomes, out of fold, CSI-HRD reaches 0.95, against 0.82 for SigMA's Sig3 score.

There is no public real-panel truth for seqcap, fo and op. Their models are trained and tested on TCGA exomes reduced to each footprint and reach 0.95–0.96. describe() shows each tumour type's cross-validated AUC, so weak ones are visible. For example, colorectal on msk has an AUC of 0.48: only 5 biallelic tumours.

hrd=True adds the HRD columns to a run for another soi. An HRD run costs about a second per tumour on one worker, most of it the MMRD/POLE step; on a large cohort pass mxw= (workers) or mxw="max".

Mismatch-repair deficiency and POLE

mmrd = sg2.predict_mmrd_ppd(input="cohort.maf", ref_genome="hg19", tumor_type="uterus", seq_type="msk")
mmrd.df[["MMRD_category", "MMRD_prob", "POLE_prob", "MMRP_prob"]]

MMRD_category is MMRD, POLE (a POLE exonuclease-domain mutator) or MMRP, one call per tumour: the most probable class, held to at most a 1% false-positive rate; tumours below the SNV floor are "Unclassified". SigMA2 has a classifier for msk, fo, op, seqcap and tcga_mc3; model="legacy" runs SigMA v1's (msk, tcga_mc3). Both read the same features; SigMA2's are retrained on larger truth sets:

POLE truth: a pathogenic exonuclease-domain hotspot (P286R, S297F, F367S, V411L, L424I, P436R, M444K, A456P, S459F) in a microsatellite-stable tumour. Out of fold, against SigMA v1 on the same tumours, sensitivity at 1% FPR on real MSK-IMPACT panels: MMRD 0.997 vs 0.994, POLE 0.993 vs 0.855. Tumours called MSI-high whose input holds no microsatellite indel are left out of these comparisons for both classifiers. The call itself, out of fold on all five platforms: MMRD at sensitivity 0.96-0.99 and false-positive rate 0.03-0.17%, POLE at 0.90-0.98 and 0.03-0.04%.

It reads the indel counts SigMA2 takes from a VCF or MAF (sigma2.indel_features):

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

Train your own

• Signature classifier: the Add workflow annotates, clusters and simulates your cohort, then tunes a classifier you pass back as model=. See the example notebooks.

  a = sg2.Add(input=mutations, exposures=exposures, tumor_type="breast", seq_type=["msk"], soi=["SBS3"])
  a.annotate(); a.cluster(); a.simulate(); models = a.tune(output_dir="...")
  

• HRD classifier: for another assay or cohort, build the feature table and give biallelic BRCA1/2 status per tumour. Add does not train HRD; HRD is a classifier, not a signature.

  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")   # then run(..., seq_type="my_assay", soi="HRD")
  

From the shell: sigma2 hrd score | features | tune | gis | 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.

Example notebooks

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.