RiboSignal / README.md
emalek's picture
Model card: correct input scope, mamba4 CPU support, training data
5e8342a verified
|
Raw History Blame Contribute Delete
4.72 kB
---
license: mit
library_name: pytorch
tags:
- biology
- genomics
- ribosome-profiling
- ribo-seq
- translation
- orf-prediction
- rna
pipeline_tag: other
---
# Ribo-seq signal model: per-nucleotide ribosome profiling from sequence and RNA-seq
Predicts a **per-nucleotide ribosome P-site profile** for a transcript from its sequence and
matched RNA-seq coverage. It takes any transcript, coding or non-coding, up to 10,000 nt, the
longest in training. No ribosome-profiling experiment is required at inference.
The predicted profile can be fed to an ORF caller in place of real Ribo-seq, which is how it is
evaluated here and what it is for: calling translated ORFs, including upstream and non-canonical
ones, in samples where no Ribo-seq exists.
Two checkpoints are released. They differ **only** in the sequence mixer; body, heads, inputs,
training data and ORF track are identical.
| checkpoint | mixer | params | device | profile r, 3-seed mean (range) |
|---|---|--:|---|--:|
| `mamba4_best.pt` **(primary)** | dilated CNN + 4 bidirectional Mamba blocks | 7,521,026 | GPU; CPU through the repository's pure-PyTorch reference | **0.6799** (0.6753-0.6851) |
| `attn_best.pt` | dilated CNN + 2 transformer layers | 5,071,106 | CPU or GPU | 0.6595 (0.6585-0.6603) |
Profile r is the median per-transcript Pearson correlation on raw counts over 70,883 held-out
transcripts, averaged across three training seeds. The released checkpoints are the seed-0 runs:
0.6851 for mamba4 and 0.6585 for attn, the values in `<arch>_test_metrics.json`.
## Inputs
Ten channels per nucleotide:
| channels | content |
|---|---|
| 4 | one-hot A/C/G/T of the transcript |
| 5 | ORF-candidate track: frame 0/1/2 occupancy, start context, stop |
| 1 | RNA-seq coverage, depth-normalised |
Two output heads: a per-nucleotide profile (a distribution summing to 1) and a per-transcript
count.
## What must match training
The inputs are built from your own transcripts and RNA-seq with the repository's pack builder;
the tutorial at <https://ribosignal.readthedocs.io> does this for chromosome 22. Two settings must
match what the checkpoints were trained on:
- the ORF-candidate track is built with `--mode ext --kozak none`. Both released models are
`--kozak none` models; feeding them a heuristic-Kozak track is a mistake that has already
happened once in this project.
- transcripts longer than 10,000 nt are left out. None was in training, and attention memory
grows with the square of the length.
Reproducing the held-out metrics above additionally needs the training universe (84,472
transcripts), which is not published here.
## Loading
```python
import torch, json
cfg = json.load(open("mamba4_config.json"))
sd = torch.load("mamba4_best.pt", map_location="cpu") # plain state_dict
```
`model.py` is the model definition. With the copy here, `mamba4_best.pt` requires `mamba_ssm`
and a CUDA device. The repository's `scripts/model.py` falls back to a pure-PyTorch reference
(`scripts/mamba_ref.py`) where `mamba_ssm` is absent, so mamba4 also runs on CPU, more slowly.
`attn_best.pt` has no such requirement.
## Training
- Human tissue data from Chothani et al.: Ribo-seq from GEO **GSE182371**, RNA-seq from
**GSE182372** (SuperSeries GSE182377).
- Leave-one-tissue-out: held out Hepatocytes; trained on Fibroblast, VSMC, ES, Fat, HA_EC, HCAEC,
HUVEC. Brain dropped. 42,000 train / 8,400 val / 70,883 test transcripts.
- Training universe: 84,472 transcripts, protein-coding (74,704) and lncRNA (9,768), up to
10,000 nt. Other biotypes can be run but were not seen in training.
- Unique-mapper alignments for both assays (`--outFilterMultimapNmax 1`); rRNA, tRNA, miRNA and
mitochondrial loci removed before P-site calling. Mitochondrial protein-coding genes excluded
throughout.
- 256 channels, 10 blocks, dropout 0.1, 16,000 nt budget, `count_weight` 0.1, `input_mode: both`.
- Checkpoint selected on validation `pearson_median`.
## License
**MIT.** Free for any use including commercial, with no attribution requirement beyond keeping the
copyright notice. Full text in `LICENSE`.
The weights and `model.py` are covered. The **training data are not**: they are third-party public
datasets (GEO GSE182371 and GSE182372) under their own terms, and this licence makes no claim
about them.
## Code
<https://github.com/ericmalekos/ribosignal>
`model.py` here is an earlier copy of that repository's `scripts/model.py`; the repository version
adds the CPU fallback for mamba4. The pack builder, prediction, ORF-calling and scoring pipeline
live there.
## Citation
Manuscript in preparation. Until then cite this repository and
<https://github.com/ericmalekos/ribosignal>.