Metadata-Version: 2.4
Name: m6aformer
Version: 0.1.2
Summary: Deep learning toolkit for m6A site prediction (CNN + lightweight Transformer).
Author: Zhixin Niu
Maintainer: Zhixin Niu
License-Expression: MIT
Project-URL: Homepage, https://github.com/zhixinniu/M6AFormer
Project-URL: Documentation, https://github.com/zhixinniu/M6AFormer#readme
Project-URL: Repository, https://github.com/zhixinniu/M6AFormer
Project-URL: Issues, https://github.com/zhixinniu/M6AFormer/issues
Project-URL: Changelog, https://github.com/zhixinniu/M6AFormer/blob/main/CHANGELOG.md
Keywords: m6A,N6-methyladenosine,RNA modification,epitranscriptomics,deep learning,transformer,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: torch>=2.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.65
Requires-Dist: requests>=2.28
Provides-Extra: web
Requires-Dist: fastapi>=0.100; extra == "web"
Requires-Dist: uvicorn[standard]>=0.23; extra == "web"
Requires-Dist: jinja2>=3.1; extra == "web"
Requires-Dist: python-multipart>=0.0.6; extra == "web"
Requires-Dist: matplotlib>=3.6; extra == "web"
Provides-Extra: eval
Requires-Dist: scikit-learn>=1.1; extra == "eval"
Requires-Dist: matplotlib>=3.6; extra == "eval"
Provides-Extra: train
Requires-Dist: scikit-learn>=1.1; extra == "train"
Requires-Dist: matplotlib>=3.6; extra == "train"
Requires-Dist: seaborn>=0.12; extra == "train"
Requires-Dist: jupyter>=1.0; extra == "train"
Requires-Dist: ipykernel>=6.20; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: fastapi>=0.100; extra == "dev"
Requires-Dist: python-multipart>=0.0.6; extra == "dev"
Requires-Dist: matplotlib>=3.6; extra == "dev"
Provides-Extra: all
Requires-Dist: m6aformer[eval,web]; extra == "all"
Dynamic: license-file

# M6AFormer

> Deep learning toolkit for transcriptome-wide N6-methyladenosine (m6A) site
> prediction, built on a hybrid CNN + lightweight Transformer architecture.

[![PyPI](https://img.shields.io/pypi/v/m6aformer.svg?v=2)](https://pypi.org/project/m6aformer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

---

## Highlights

- **One model, multiple variants.** Four pretrained checkpoints covering both
  201 bp and 801 bp windows, with random and DRACH-filtered negative sampling
  strategies.
- **Three ways to use it.** A clean Python API, a `m6aformer` CLI, and an
  optional local web UI, all driven by the same core `M6AFormer` class.
- **Frozen, audited thresholds.** Each checkpoint ships with a decision
  threshold selected on inner-validation F1 (overridable at predict time).
- **Reproducible.** MIT licensed, fully open-source; bundled weights are
  shipped inside the wheel.

## Pretrained models

| Name        | Architecture       | Window | Negatives | Default |
|-------------|--------------------|--------|-----------|---------|
| `all_801`   | CNN + Transformer  | 801 bp | random    | yes     |
| `all_201`   | CNN + Transformer  | 201 bp | random    |         |
| `drach_801` | CNN + Transformer  | 801 bp | DRACH     |         |
| `drach_201` | CNN + Transformer  | 201 bp | DRACH     |         |

Each model ships with a frozen decision threshold selected on inner-validation
F1, recorded in its `threshold.json`. Users can override the threshold at
prediction time.

## Installation

```bash
# Basic (CPU/GPU inference + CLI)
pip install m6aformer

# With local web UI
pip install "m6aformer[web]"

# Development install (from a clone)
git clone https://github.com/zhixinniu/M6AFormer.git
cd M6AFormer
pip install -e ".[dev,web]"
```

> **PyTorch is intentionally pinned only as `torch>=2.0`.** Install the
> CUDA-matching wheel from <https://pytorch.org/get-started/locally/> first
> if you want GPU support.

## Quickstart

### Python

```python
from m6aformer import M6AFormer

model = M6AFormer.from_pretrained("all_801")           # default checkpoint
df = model.predict_fasta("genome.fa", motif="DRACH")   # scan all DRACH As
# df columns: chrom, position, strand, motif_5mer, prob, label, ...
```

### CLI

```bash
# List all bundled pretrained checkpoints
m6aformer list-models

# Score a FASTA file (auto-finds candidate adenosines)
m6aformer predict --input genome.fa --output sites.tsv --model all_801

# Score one or more inline sequences (no file needed)
m6aformer predict --seq ACGT...A...ACGT --strand + --model all_801
```

### Local web UI

The `[web]` extra installs FastAPI + uvicorn and registers the `serve`
subcommand. The bundled single-page UI exposes the same prediction
pipeline as the CLI.

```bash
pip install "m6aformer[web]"
m6aformer serve                       # http://127.0.0.1:8000
```

For remote use over SSH (recommended over `--host 0.0.0.0`):

```bash
# On your laptop, forward the port and keep the server bound to localhost:
ssh -L 8000:localhost:8000 user@server
# Then open http://localhost:8000 in your browser.
```

## Repository layout

```
M6AFormer/
├── src/m6aformer/      # the pip package (only this ships in the wheel)
├── training/           # training scripts (GitHub only, import m6aformer)
├── data_prep/          # dataset preparation scripts (GitHub only)
├── examples/           # runnable usage examples
├── tests/              # unit + integration tests
├── docs/               # documentation source
```

See [`training/README.md`](training/README.md) for how to retrain from
scratch, and [`data_prep/README.md`](data_prep/README.md) for the dataset
construction pipeline.

## Citation

If you use M6AFormer in your research, please cite the project. A
machine-readable citation is provided in [`CITATION.cff`](CITATION.cff).

## License

[MIT](LICENSE) © 2026 Zhixin Niu.
