Metadata-Version: 2.4
Name: DeepMutSim
Version: 1.1.0
Summary: Enumerate all possible SNVs for MANE transcripts using HGVS nomenclature.
Author-email: Liu Sun <sunliu@yxnu.edu.cn>, Jian Yang <yangjian@yxnu.edu.cn>
License-Expression: MIT
Project-URL: Homepage, https://github.com/liu-sun/DeepMutSim
Project-URL: Issues, https://github.com/liu-sun/DeepMutSim/issues
Project-URL: Repository, https://github.com/liu-sun/DeepMutSim
Keywords: bioinformatics,hgvs,variant,mane,ncbi,entrez,mutation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: license-file

# DeepMutSim

Generate all possible single nucleotide variants (SNVs) for MANE transcripts
using [HGVS nomenclature][hgvs].  DeepMutSim queries NCBI Entrez to fetch the
MANE Select / MANE Plus Clinical transcript for any human gene and enumerates
every possible substitution — coding, UTR, splice sites, and protein-level.

[hgvs]: https://varnomen.hgvs.org/

## Features

| Function | Output | Description |
|---|---|---|
| `cds(gene)` | `list[tuple]` | All CDS SNVs with protein consequence (1-letter & 3-letter) |
| `missense(gene)` | `list[tuple]` | Missense variants (codon substitutions that change the amino acid) |
| `codon_sub(gene)` | `list[str]` | All codon substitutions (silent + missense, incl. multi-base `delins`) |
| `aa_sub(gene)` | `list[tuple]` | All single amino-acid substitutions |
| `utr5(gene)` | `list[str]` | All 5' UTR SNVs (negative HGVS numbering) |
| `utr3(gene)` | `list[str]` | All 3' UTR SNVs (`c.*` numbering) |
| `splice_site(gene)` | `list[str]` | Canonical splice donor/acceptor ±1, ±2 variants |

## Installation

```bash
pip install deepmutsim
```

DeepMutSim requires Python ≥3.8 and [Biopython][biopython].

[biopython]: https://biopython.org/

## Configuration

Two environment variables are **mandatory** for NCBI Entrez access:

| Variable | Required | Description |
|---|---|---|
| `EMAIL` | Yes | Your email address (NCBI policy) |
| `API_KEY` | Recommended | NCBI API key — raises the rate limit from 3 to 10 req/s |

[Obtain an API key][ncbi-key] from your NCBI account settings.

[ncbi-key]: https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/

**Linux / macOS:**

```bash
export EMAIL="your.email@example.com"
export API_KEY="your_api_key_here"
```

**Windows (PowerShell):**

```powershell
$env:EMAIL = "your.email@example.com"
$env:API_KEY = "your_api_key_here"
```

## Quick start

```python
import deepmutsim

# All CDS single-nucleotide variants
variants = deepmutsim.cds("INS")
# [('NM_000207.3:c.1A>G', 'NP_000198.1:p.(M1?)', 'NP_000198.1:p.(Met1?)'), ...]

# All missense variants
missense = deepmutsim.missense("TP53")

# All 5' UTR SNVs
utr5_vars = deepmutsim.utr5("BRCA1")

# All canonical splice site variants
splice = deepmutsim.splice_site("CFTR")
```

## API reference

### Query helpers

- **`nm(gene)`** — Fetch the MANE nucleotide record (GenBank).
- **`np(gene)`** — Fetch the MANE protein record (FASTA).
- **`nc(gene)`** — Fetch the primary assembly RefSeq accession.

### CDS variants

- **`cds(gene)`** → `list[tuple[str, str, str]]`
  Every possible single-nucleotide substitution across the coding sequence.
  Each entry is `(c.HGVS, p.HGVS_1letter, p.HGVS_3letter)`.  The initiator
  methionine is always reported as `M1?` / `Met1?`.

- **`missense(gene)`** → `list[tuple[str, str, str]]`
  Codon substitutions that change the encoded amino acid.  Includes multi-base
  changes (reported as `delins`).  Same tuple format as `cds()`.

- **`codon_sub(gene)`** → `list[str]`
  All possible codon substitutions (silent + missense).  Single-base changes
  use `X>Y` notation; multi-base changes use `delins`.

### UTR variants

- **`utr5(gene)`** → `list[str]`
  All SNVs in the 5' untranslated region.  Positions use negative HGVS
  numbering (`c.-59`, `c.-58`, …, `c.-1`).

- **`utr3(gene)`** → `list[str]`
  All SNVs in the 3' untranslated region.  Positions use `c.*` numbering
  (`c.*1`, `c.*2`, …).

### Splice site variants

- **`splice_site(gene)`** → `list[str]`
  Canonical donor (+1, +2) and acceptor (−2, −1) positions of every intron
  within the CDS boundaries.  Prefixed with the genomic RefSeq accession.

### Protein-level variants

- **`aa_sub(gene)`** → `list[tuple[str, str]]`
  All single amino-acid substitutions.  Each entry is
  `(p.HGVS_1letter, p.HGVS_3letter)`.  The initiator methionine is reported
  as `M1?` / `Met1?`.

## Development

```bash
# Editable install with test dependencies
pip install -e ".[test]"

# Run tests (no network required — 38 tests)
pytest tests/ -v

# Run tests with coverage
pytest --cov=deepmutsim --cov-report=term-missing

# Build a distribution
python -m build
```

## License

MIT — see [LICENSE](LICENSE).
