PRForm

Predict programmed ribosomal frameshift (PRF) sites in Viral genomes.

prform is a deep-learning tool that scores every nucleotide in viral genome sequence for the probability that a -1 or +1 frameshift event occurs there. Predictions come from a 1D residual network with a 10 kb receptive field.

The model was trained on NCBI ~50,000 deduplicated viral genomes (as of Feb 2026). Trained model checkpoint and calibrator are bundled with the package and ready to run.

Install

From PyPI:

pip install prform

From bioconda:

conda install -c bioconda prform

From source (development):

git clone https://github.com/khoa-yelo/PRForm.git
cd PRForm/prform_pkg
pip install -e .[dev]

Usage

prform predict input.fasta --outdir results/

(equivalent: python -m prform predict ... — useful when ~/.local/bin isn't on your PATH.)

Writes two files into results/:

• predictions.csv — one row per FASTA record: the top-k predicted peak positions with their calibrated PRF probability and frameshift type (-1 PRF, +1 PRF, or no frameshift detected).
• predictions.h5 — full per-nucleotide calibrated probability tracks.

predictions.h5 layout:

records/
    accession_id     (R,) str
    length           (R,) int
    top{k}_pos       (R,) int      # k = 1..top_k, 1-based; -1 if no peak
    top{k}_prob      (R,) float32
    top{k}_type      (R,) int8     # -1 PRF, +1 PRF, or 0 = no frameshift detected
per_nucleotide/
    {accession_id}/                # one group per FASTA record
        no_PRF_prob      (L,) float32
        minus1_PRF_prob  (L,) float32
        plus1_PRF_prob   (L,) float32

With --both-strands each orientation gets its own block — fwd_/rev_ column and dataset prefixes, and fwd/rev per-nucleotide subgroups — see Scoring both strands.

Read a record's per-nucleotide tracks in Python:

import h5py
with h5py.File("results/predictions.h5") as f:
    for acc in f["records/accession_id"].asstr()[:]:
        g = f[f"per_nucleotide/{acc}"]
        minus1 = g["minus1_PRF_prob"][:]
        plus1  = g["plus1_PRF_prob"][:]
        prf_track = minus1 + plus1

Scoring both strands

PRForm is a directional detector: it only sees a frameshift in the orientation it is given. A PRF encoded on the minus strand of your input is invisible on a forward-only pass. Pass --both-strands to score each record in both orientations:

prform predict genomes.fasta --outdir results/ --both-strands

Both orientations are reported. The peaks and tracks are duplicated into a forward block and a reverse block:

predictions.csv
    accession_id, length,
    fwd_top{k}_pos, fwd_top{k}_prob, fwd_top{k}_type,
    rev_top{k}_pos, rev_top{k}_prob, rev_top{k}_type

predictions.h5
    records/                       # same fwd_/rev_ prefixes as the CSV
        accession_id, length,
        fwd_top{k}_{pos,prob,type}, rev_top{k}_{pos,prob,type}
    per_nucleotide/
        {accession_id}/
            fwd/  no_PRF_prob, minus1_PRF_prob, plus1_PRF_prob   (L,) each
            rev/  no_PRF_prob, minus1_PRF_prob, plus1_PRF_prob   (L,) each

The reverse block is mirrored back into forward-genome coordinates, so both blocks index the same nucleotide: fwd_top1_pos, rev_top1_pos and index i of either track all refer to position i+1 of the sequence as you supplied it. Class channels are not swapped — a -1 PRF read on the reverse complement stays in minus1_PRF_prob, because the shift direction is defined relative to the strand being read.

Test the install

prform ships with small FASTA fixtures (one folder per labeled frameshift class) so you can verify the install end-to-end without any external data. Copy them into your working directory:

prform download-examples ./prform_examples

Layout after download:

prform_examples/
    plus1_PRF/    influenza_pax.fasta
    minus1_PRF/   coronavirus_khosta2.fasta, phage_tyson.fasta
    no_PRF/       monkeypox, ledantevirus, nanovirus, ourmiavirus, orbivirus

Run predict on each class:

# +1 PRF: peak should land near the labeled site
prform predict prform_examples/plus1_PRF/influenza_pax.fasta \
    --outdir prform_test/plus1

# -1 PRF: peak should land near the labeled site
prform predict prform_examples/minus1_PRF/coronavirus_khosta2.fasta \
    --outdir prform_test/minus1

# no PRF: no frameshift should be called
prform predict prform_examples/no_PRF/nanovirus.fasta \
    --outdir prform_test/no_prf

cat prform_test/plus1/predictions.csv
cat prform_test/minus1/predictions.csv
cat prform_test/no_prf/predictions.csv

Expected behavior:

fixture	labeled site	what to look for
plus1_PRF/influenza_pax.fasta	+1 PRF @ pos 582	top1_pos within a few nt of 582, top1_type == 1
minus1_PRF/coronavirus_khosta2.fasta	-1 PRF @ pos 13248	top1_pos near 13248, top1_type == -1
minus1_PRF/phage_tyson.fasta	-1 PRF @ pos 10279	top1_pos near 10279, top1_type == -1
no_PRF/*.fasta	none	top1_type == 0 (no frameshift called)

Each labeled-positive FASTA header carries the labeled site for easy comparison.

Python API

from prform import PRFormPredictor

predictor = PRFormPredictor()                      # loads bundled weights
results = predictor.predict_fasta("input.fasta")   # list of dicts
# or
results = predictor.predict_sequences([("rec1", "ACGT" * 1000)])
# score both orientations, keep the better strand per record
results = predictor.predict_fasta("input.fasta", both_strands=True)

Each result entry has accession_id, length, strand, cal_probs_3 (3, L) and a top list of peak summaries (pos, prob, type) — all from the winning strand. With both_strands=True, rec["fwd"] and rec["rev"] each hold that orientation's own cal_probs_3 and top, both in forward-genome coordinates; otherwise they are None.

Hardware

CPU works. GPU is faster — prform automatically uses CUDA when available. For long sequences (>1 Mb total input) a GPU is recommended.

License

MIT