Skip to content

orfdata

orfdata builds the protein reference for a species: the proteins annotated in a PyEnsembl genome, plus open reading frames (ORFs) that ribosome-profiling studies found translated outside those annotations. Each added ORF stays bound to its PyEnsembl transcript, with its source, category and evidence. Viral proteomes can be added explicitly, but only for a species that is a recorded host of the virus.

Install

Use Python 3.11 or later. Install orfdata and one PyEnsembl annotation:

python -m pip install orfdata
pyensembl install --release 115 --species human
orfdata setup --species human --catalogs all  # For ncORF presets and "all"

The second command downloads and indexes Ensembl 115 for human GRCh38. The third builds human's optional Ribo-seq ORF catalogues from their pinned sources and downloads the assembly chains and the GDC viral collection (--collections none skips it). Opening ORFdata resources never downloads them implicitly; use the explicit commands under orfdata data or the corresponding PyEnsembl command when data is missing.

The base install includes PyEnsembl, the spreadsheet source readers and PyArrow exports. The canine-extraction extra (pip install 'orfdata[canine-extraction]') adds APSW, needed only to extract the original canine vendor database; released dataset queries and rebuilds from normalized sources do not need it.

Viral support is part of the base install; only the data is downloaded. Get the human GDC viral references — genomes, coding transcripts and proteins, as three named layers — with orfdata download viral --species human. Use orfdata data list to see every known resource and orfdata data status to see what is local. To annotate variants in viral transcripts or noncanonical ORFs with varcode, isovar, topiary or vaxrank, see Downstream tools.

Build a human proteome

from pyensembl import EnsemblRelease
from orfdata import ReferenceTranscriptome

genome = EnsemblRelease(115, species="human")
transcriptome = ReferenceTranscriptome.from_genome(genome)
reference = transcriptome.proteome()  # Reference CDS proteins only.
proteome = transcriptome.proteome(nc_orf_sources="ms")
proteome.write_fasta("human-e115.fasta")
print(proteome.summary()["protein_sources"], len(proteome.excluded))

{'reference_cds': 245535, 'nc_orf': 2181} 5

proteome() takes every reference CDS protein in the Ensembl 115 annotation. Use isoforms="longest" for one reference protein per gene, selected by length. nc_orf_sources="ms" adds the bundled human ORFs that have supporting mass-spectrometry (MS) peptides: 2,181 of the 2,186 are encoded by an Ensembl 115 transcript, which must contain the ORF's exact spliced coding path. The other 5 are listed in proteome.excluded with the reason. Each entry lists every transcript encoding it. Building this human proteome takes under a minute, and proteome.save(path) keeps it as a checksummed snapshot.

The same proteome from the command line:

orfdata proteome --species human --release 115 --nc-orf-sources ms --output human-e115.fasta

Choose ncORF sources

nc_orf_sources= Selects ORFs with Human ORFs Encoded in Ensembl 115
"ribosome" or "riboseq" Ribosome profiling across all datasets 69,286 69,162
"ms" Any supporting MS peptide 2,186 2,181
"immunopeptidomics" Peptides eluted from MHC (in human, HLA) molecules 1,881 1,879
"proteomics" Peptides from digested cellular proteins 73 72
"all" Every compatible dataset 69,286 69,162

Use nc_orf_sources="bundled" for the bundled dataset alone, or a list of names such as ["bundled", "ncorf-mammals-human"] for a subset. Evidence presets and "all" require all compatible datasets; install human's optional datasets once with orfdata setup --species human --catalogs all. Missing resources produce installation instructions. The defaults still add no ncORFs. RibORF source catalogues include valid 1–4-residue ORFs. Apply a downstream policy explicitly with min_protein_length=5, or CLI --min-protein-length 5, when a peptide-search reference should omit them.

Most MS support in the bundled human catalogue comes from immunopeptidomics. A presented peptide shows that the ORF was translated; it does not establish a stable protein. See building a reference proteome for stricter filters and what each level means.

Look up the ORFs on a transcript

Continue in the same Python session:

from orfdata import extra_orfs

orfs = extra_orfs(genome)
for orf in orfs.for_transcript(genome.transcript_by_id("ENST00000304842")):  # TPST1
    print(orf.model.orf_id, orf.model.orf_type, orf.protein_sequence)
    print(orf.evidence.has_evidence("ms"))

c7riboseqorf56 uORF MPSRRRGGSSLIPDVGYLSEVDCPWPEHFPKIILSKISV
True

extra_orfs(genome) places every catalogue ORF on every transcript of this genome that carries its exact coding path; without evidence=, it includes every catalogue ORF. Each result is a TranscriptORF: the source ORF, its evidence and the original PyEnsembl transcript, with start and end slicing the transcript sequence. One RNA can have several ORFs, even when Ensembl annotates it as noncoding; the transcript's biotype and annotated protein are unchanged. Add include_annotated=True to list the annotated CDSs on that transcript alongside them.

Species

Species Annotated proteins Noncanonical ORFs
Human From PyEnsembl; T2T-CHM13 from a pinned Ensembl annotation 7,264 GRCh38 ORFs, bundled; lifted to GRCh37, NCBI36 and T2T-CHM13. 69,286 with the optional Ribo-seq catalogues of Chang et al. and Yang et al. (nc_orf_sources="all")
Mouse From PyEnsembl 60,707 ORFs on GRCm39: Ribo-seq ORFs of Chang et al. and Yang et al., and 2,976 MS-supported ones (OpenProt 2.2), built locally with orfdata setup --species mouse; lifted to GRCm38 and NCBIM37
Zebrafish From PyEnsembl 15,491 GRCz11 Ribo-seq ORFs of Yang et al., built locally
C. elegans From PyEnsembl 4,035 WBcel235 Ribo-seq ORFs of Yang et al., built locally
Budding yeast From PyEnsembl 1,369 R64-1-1 Ribo-seq ORFs of Yang et al., built locally; 171 lie on Ensembl's transcripts
Dog From PyEnsembl None: no public dog Ribo-seq or ncORF MS exists

Other assemblies use a catalogue lifted to them once orfdata chains download has fetched the chain files (with --accept-terms for UCSC's non-commercial mouse chains); see every assembly of a species. with_nc_orfs() raises for a species without a catalogue, or whose catalogue or chains aren't installed yet, rather than returning an annotated-only proteome. Human ORF evidence is never transferred to another species. The same API also serves RNA, ribosome and protein measurements for human, mouse, dog and yeast; see released data and gaps.

Next steps