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

Every question goes through one call, sg2.run(). The soi ("signature of interest") argument picks the classifier:

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).

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, its state and operating points
sg2.models(tumor_type="breast")         # names such as "breast/SBS3/msk", "breast/HRD/msk"
sg2.model("breast/HRD/msk")             # load one
sg2.verify_model("breast/HRD/msk")      # integrity check (SHA-256 fingerprint)

describe() shows two tables:

• Signature classifiers. One row per tumour type, signature and platform, with the SNV floor, the state (● verified, ▲ experimental), and the cutoffs at a false-positive rate (FPR) of 10 % and 1 %.
• HRD classifiers (CSI-HRD). One row per tumour type, one column per platform. Each cell says whether the tumour type has its own model (own) or shares the pooled one (pooled), with that model's cross-validated AUC (area under the ROC curve). A dash means that platform's model never saw the tumour type, and run() refuses it.

Mutational signatures

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

model="auto" (the default) picks the classifier for your tumour type, signature and platform.

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. HRD models exist for msk, tcga_mc3, seqcap, fo and op. describe() lists which tumour types have their own model and which share the pooled one.

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. Weak tumour-type models show in describe() with their cross-validated AUC. 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.

Mismatch-repair deficiency and POLE

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)

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.