Add model card metadata

1078b52 verified 12 days ago

6.34 kB

	---
	license: other
	library_name: pytorch
	tags:
	- biology
	- rna
	- protein
	- rbp
	- protein-rna-interaction
	- generative-model
	- classification
	datasets:
	- sunlab-ai/ProRiboGen-dataset
	---

	# ProRiboGen — Inference Package

	Inference-only package for a website / API backend. No training or test CSVs.

	ProRiboGen has two modules:

	1. Generation — protein amino-acid sequence → RNA FASTA + motifs (+ optional logos)
	2. Classification — protein + RNA → binding probability `binding_prob ∈ (0, 1)`

	Protein conditioning uses VESM-3B (weights live on your GPU server; not shipped here).

	Package size ≈ 2.8 GB (three checkpoints).

	---

	## Layout

	```
	ProRiboGen_code/
	├── README.md # this file
	├── requirements.txt
	├── configs/
	│ ├── paths.env.example # copy → paths.env and edit VESM paths
	│ ├── sample_fixed80bp.json
	│ └── model.json # classifier backbone / data config
	├── checkpoints/
	│ ├── generator.pt # ~1.2G RNA generation module
	│ ├── backbone.pt # ~1.2G MLM backbone for classification
	│ └── classifier.pt # ~477M binding classifier head + fusion
	├── generator/ # Generation module (sample.py + src/ + tokenizer/)
	├── classifier/ # Classification module (RnaRealismClassifierV3)
	├── protein_encoder/ # AA sequence → VESM H5
	├── motif/ # MEME, HOMER conversion, logo PNGs
	├── api/ # CLI + FastAPI
	├── examples/ # demo protein FASTA
	├── scripts/ # smoke tests
	└── workspace/ # runtime outputs (created on demand)
	```

	### Checkpoint roles

	\| File \| Role \|
	\|------\|------\|
	\| `generator.pt` \| Generation only — MaskGIT+ sampling \|
	\| `backbone.pt` \| Classification — build ESM MLM, then load classifier weights \|
	\| `classifier.pt` \| Classification — binding / realism score \|

	Do not use `backbone.pt` for generation. Do not use `generator.pt` as the classifier backbone (the classifier was trained on the backbone run).

	---

	## Setup (another server)

	### 1. Dependencies

	```bash
	cd ProRiboGen_code
	python3 -m venv .venv && source .venv/bin/activate # optional
	pip install -r requirements.txt
	# Motif discovery needs MEME Suite on PATH (`meme` command).
	# Logos need: pip install logomaker matplotlib pandas
	```

	### 2. Configure VESM

	```bash
	cp configs/paths.env.example configs/paths.env
	# edit configs/paths.env
	```

	Either:

	```bash
	# A) Standard 17-VESM3 tree
	VESM_ROOT=/path/to/17-VESM3
	# expects:
	# $VESM_ROOT/models/base/facebook_esm2_t36_3B_UR50D
	# $VESM_ROOT/models/weights/VESM_3B.pth
	```

	or:

	```bash
	# B) Explicit paths (overrides A)
	VESM_BASE_MODEL_DIR=/path/to/facebook_esm2_t36_3B_UR50D
	VESM_WEIGHTS=/path/to/VESM_3B.pth
	DEVICE=cuda:0
	```

	Checkpoint / tokenizer relative paths in `paths.env` usually need no change.

	### 3. Smoke tests

	```bash
	bash scripts/demo_generate.sh
	bash scripts/demo_score.sh

	# With a real protein FASTA from this package:
	python api/generate_rna_and_motif.py \
	--protein @examples/HS90A_HUMAN_P07900.fasta \
	--num-sequences 32 --length-bp 80

	python api/score_binding.py \
	--protein @examples/HS90A_HUMAN_P07900.fasta \
	--rna AUGCAUGCAUGCAUGCAUGCAUGCAUGCAUGC
	```

	---

	## Module 1 — Generation (RNA + motifs)

	```bash
	python api/generate_rna_and_motif.py \
	--protein "MSKSLYVR..." \
	--p-id DemoRBP \
	--num-sequences 64 \
	--length-bp 80
	```

	Or:

	```bash
	python api/generate_rna_and_motif.py --protein @/path/to/protein.fasta --num-sequences 64
	```

	Outputs under `workspace/job_<p_id>/`:

	\| Path \| Meaning \|
	\|------\|---------\|
	\| `*_vesm3b.h5` \| VESM token embeddings \|
	\| `generated/*.fasta` \| Generated RNA \|
	\| `motifs/*/meme.txt` \| MEME raw output \|
	\| `homer_motif_matrix/*.motif` \| HOMER PWMs \|
	\| `homer_motif_logo/*.png` \| Sequence logos (ACGU colors below) \|

	Skip MEME/logos: `--skip-motif`.

	Logo colors (same as internal `create_motif_logo.ipynb`):

	\| Base \| Hex \|
	\|------\|-----\|
	\| A \| `#65a455` \|
	\| C \| `#2e45a4` \|
	\| G \| `#fda562` \|
	\| U \| `#d54f3f` \|

	Standalone logos:

	```bash
	python motif/plot_homer_logos.py workspace/job_DemoRBP/homer_motif_matrix workspace/job_DemoRBP/homer_motif_logo
	```

	Website tip: use `num_sequences=64–256` for latency; paper-style runs use `2048`.

	---

	## Module 2 — Classification (binding probability)

	```bash
	python api/score_binding.py \
	--protein "MSKSLYVR..." \
	--rna "UGCAUGCGAU..." \
	--p-id DemoRBP
	```

	Example JSON:

	```json
	{
	"p_id": "DemoRBP",
	"rna": "UGCAUGCGAU...",
	"rna_len": 80,
	"logit": 1.23,
	"binding_prob": 0.77
	}
	```

	Default decision threshold: `binding_prob >= 0.5` (same as training eval). Reuse a cached H5 with `--protein-h5` to skip re-encoding.

	---

	## HTTP API

	```bash
	uvicorn api.app:app --host 0.0.0.0 --port 8000
	```

	```bash
	curl http://127.0.0.1:8000/health

	curl -X POST http://127.0.0.1:8000/v1/generate \
	-H 'Content-Type: application/json' \
	-d '{"protein":"MSK...","p_id":"Demo","num_sequences":32,"run_motif":true}'

	curl -X POST http://127.0.0.1:8000/v1/score \
	-H 'Content-Type: application/json' \
	-d '{"protein":"MSK...","rna":"UGCA...","p_id":"Demo"}'
	```

	Frontend only needs these two endpoints; GPU work stays on this service.

	---

	## Pipeline

	```
	AA sequence
	│
	├─ VESM-3B ─► H5 [L, 2560]
	│
	├─ generator.pt (generation) ─► FASTA ─► MEME ─► HOMER ─► PNG logos
	│
	└─ backbone.pt + classifier.pt + RNA ─► binding_prob (classification)
	```

	No pretrained 337-protein H5 is required; each request encodes VESM on the fly.

	---

	## Copy to another machine

	```bash
	rsync -avP ProRiboGen_code/ user@host:/path/ProRiboGen_code/
	# or
	tar -cf ProRiboGen_code.tar ProRiboGen_code
	```

	On the new host: install deps → edit `configs/paths.env` → run the smoke scripts.

	---

	## Hardware / notes

	1. Prefer GPU ≥ 24 GB (VESM-3B + 12-layer ProRiboGen). Encode then generate/score can be split across steps.
	2. Without MEME, use `--skip-motif` (sequences only).
	3. `paths.env` is gitignored; ship `paths.env.example` only.
	4. Python ≥ 3.10 recommended (`list[str]` typing in scripts).