Metadata-Version: 2.4
Name: sigma2
Version: 0.0.13a2
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.0,<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:

| tumour type | signatures                  | platforms                          |
| ----------- | --------------------------- | ---------------------------------- |
| breast      | SBS3, SBS8, SBS18, APOBEC   | `fo`, `msk`, `op`, `seqcap`, `tcga_mc3` |
| skin        | SBS7                        | `fo`, `msk`, `op`, `seqcap`, `tcga_mc3` |

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

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

