Metadata-Version: 2.4
Name: sigma2
Version: 0.0.16a14
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pyranges>=0.0.68
Requires-Dist: tqdm>=4.60.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: appdirs>=1.4.0
Requires-Dist: h5py>=3.0
Requires-Dist: joblib>=1.0
Requires-Dist: scikit-learn>=1.4,<1.8
Requires-Dist: tabulate>=0.8
Requires-Dist: pysam>=0.19
Requires-Dist: matplotlib>=3.5
Requires-Dist: seaborn>=0.12
Requires-Dist: kneed>=0.8
Requires-Dist: psutil>=5.8
Requires-Dist: shap>=0.41
Requires-Dist: diptest>=0.10
Requires-Dist: ipython>=8.0 ; extra == 'notebook'
Requires-Dist: pybedtools>=0.9 ; extra == 'panel'
Provides-Extra: notebook
Provides-Extra: panel
License-File: LICENSE
Summary: Mutational signature analysis for low statistics SNV data
Keywords: bioinformatics,genomics,mutational-signatures,cancer
Author-email: Jan P Hummel <jan_hummel@hms.harvard.edu>, Doga C Gülhan <dgulhan@mgh.harvard.edu>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://www.sigscape.org/docs#sigma2
Project-URL: Homepage, https://www.sigscape.org/packages/sigma2
Project-URL: Repository, https://github.com/sigscape/SigMA2

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](#models).

SigMA2 is the successor to [SigMA](https://www.sigscape.org/packages/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:

```bash
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:

```python
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):

| tumour type | signature | platforms |
| ----------- | --------- | --------- |
| breast      | SBS3, SBS8, SBS18, APOBEC | `fo`, `msk`, `op`, `seqcap`, `tcga_mc3` |
| lung        | SBS4, APOBEC | `fo`, `msk`, `op`, `seqcap`, `tcga_mc3` |
| lung        | SBS3, SBS18 | `fo`, `op`, `seqcap`, `tcga_mc3` |
| prostate (`prost`) | SBS3 | `seqcap`, `tcga_mc3` |
| prostate (`prost`) | SBS18 | `seqcap` |
| skin        | SBS7 | `fo`, `msk`, `op`, `seqcap`, `tcga_mc3` |
| colorectal (`crc`) | SBS18, APOBEC | `fo`, `msk`, `op`, `seqcap`, `tcga_mc3` |
| colorectal (`crc`) | SBS8 | `seqcap`, `tcga_mc3` |

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:

```python
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:

```python
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.

```python
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:

| Column | Meaning |
|---|---|
| `HRD_mva` | the score |
| `pass_mva` | HRD or HRD-low |
| `pass_mva_strict` | HRD |
| `confidence` | high / low / negative |

`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`):

| Tumours (biallelic) | SigMA SBS3 | Best single input | CSI-HRD |
|---|---|---|---|
| All 12 types (288) | 0.58 | 0.87 | 0.90 |
| Breast (72) | 0.63 | 0.87 | 0.88 |
| Ovary (85) | 0.60 | 0.82 | 0.83 |
| Prostate (76) | 0.57 | 0.78 | 0.81 |

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:

```python
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:

```bash
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:

```bash
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](https://gnomad.broadinstitute.org/downloads) 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](https://github.com/sigscape/SigMA2/tree/master/examples)
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:

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

## Documentation & Further Information
Find more [here](https://www.sigscape.org/packages/sigma2)

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

