Metadata-Version: 2.4
Name: orfdata
Version: 0.27.1
Summary: Reference proteomes with evidence-backed noncanonical ORFs on PyEnsembl genomes
Author: OpenVax
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pyensembl
Requires-Dist: pyensembl>=2.27.2; extra == "pyensembl"
Provides-Extra: build-data
Requires-Dist: openpyxl>=3.1; extra == "build-data"
Provides-Extra: data
Requires-Dist: datacache<2,>=1.25.1; extra == "data"
Provides-Extra: columnar
Requires-Dist: pyarrow>=14; extra == "columnar"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: openpyxl>=3.1; extra == "dev"
Requires-Dist: pyensembl>=2.27.2; extra == "dev"
Requires-Dist: datacache<2,>=1.25.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Dynamic: license-file

[![Tests](https://github.com/openvax/orfdata/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/orfdata/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/orfdata.svg)](https://pypi.org/project/orfdata/)

# orfdata

orfdata builds the protein reference for a species: the proteins annotated in
a [PyEnsembl](https://github.com/openvax/pyensembl) genome, plus open reading
frames (ORFs) that ribosome-profiling studies found translated outside those
annotations. These include upstream and downstream ORFs, ORFs in other reading
frames of a coding sequence, and ORFs on RNAs annotated as noncoding. Each added
ORF stays bound to its PyEnsembl transcript, with its source, category and
evidence.

## Installation

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

```sh
python -m pip install 'orfdata[pyensembl]'
pyensembl install --release 115 --species human
```

## Example

```python
from pyensembl import EnsemblRelease
from orfdata import Proteome

genome = EnsemblRelease(115, species="human")
proteome = Proteome.from_genome(genome).with_extra_orfs(evidence="ms")
proteome.write_fasta("human-e115.fasta")
print(proteome.summary()["kinds"], len(proteome.excluded))
```

```text
{'annotated': 245535, 'extra_orf': 2181} 5
```

This takes every protein in the Ensembl 115 annotation and adds the 2,181
bundled human ORFs that have supporting mass-spectrometry peptides and are
encoded by an Ensembl 115 transcript. Each entry lists every transcript encoding
it; the other 5 selected ORFs are listed in `proteome.excluded` with the
reason. Use `evidence="ribosome"` for all 7,239 encoded ribosome-profiling ORFs,
or a rule such as `RiboSeq(min_studies=2) & MS()` to set Ribo-seq and MS
stringency separately (1,293 encoded ORFs).
`proteome.save(path)` writes a checksummed snapshot that `Proteome.load` reads
offline. From the command line:

```sh
orfdata proteome --species human --release 115 --output human-e115.fasta
```

A translated ORF or a detected peptide does not by itself establish a stable,
functional protein. Most MS support in the bundled catalogue comes from
peptides presented by HLA molecules.

## Species

The bundled noncanonical ORF catalogue is human GRCh38. Mouse ORFs come from
OpenProt 2.2: `orfdata catalogs build openprot-mouse` builds that catalogue
from OpenProt's own files. After `orfdata chains download` (add
`--accept-terms` for UCSC's non-commercial mouse chains), older assemblies
(GRCh37, NCBI36, GRCm38, NCBIM37) use these catalogues lifted to them. Dog and yeast proteomes contain their
PyEnsembl-annotated proteins. `load_catalog(species=...)` and
`with_extra_orfs()` pick the catalogue for a species and raise when none is
available or built.
Human evidence is never transferred to another species. Viral proteomes can be added with
`with_viral(...)`, but only to a proteome for one of the virus's recorded hosts.
orfdata also provides [RNA, ribosome and protein measurements](https://openvax.github.io/orfdata/measurements/)
for human, mouse, dog and yeast.

## Measurement datasets

RNA, ribosome and protein measurements are separate, downloadable datasets with
the same species-scoped API. Install the `data` extra, then download and query
one:

```sh
pip install 'orfdata[data]'
orfdata datasets list
orfdata datasets download ingolia-yeast-rna-ribo
```

| Guide | Species | Measurements |
| --- | --- | --- |
| [Protein abundance](https://openvax.github.io/orfdata/pfizer-protein/) | Human, mouse, dog | TMT protein groups (Oziolor et al.) |
| [RNA abundance](https://openvax.github.io/orfdata/pfizer-rna/) | Dog, mouse | Native gene counts (Oziolor et al.) |
| [Matched human tissues](https://openvax.github.io/orfdata/human-tissue/) | Human | RNA and protein from adjacent cryosections (Wang et al.) |
| [Yeast protein and RNA](https://openvax.github.io/orfdata/copy-yeast/) | Budding yeast | Calibrated protein and RNA abundance (CoPY) |
| [Yeast RNA and ribosome occupancy](https://openvax.github.io/orfdata/ingolia-yeast/) | Budding yeast | Source regions, including UTR and ncRNA labels (Ingolia et al.) |

Gene RNA and canonical protein measurements do not establish noncanonical ORF
abundance. See [released data and gaps](https://openvax.github.io/orfdata/coverage/).

## Documentation

The [documentation](https://openvax.github.io/orfdata/) covers:

| Task | Guide |
| --- | --- |
| Build a proteome: evidence levels, exclusions, contigs, viral proteins | [Build a reference proteome](https://openvax.github.io/orfdata/proteome/) |
| ORF classes, evidence definitions, Varcode and Isovar integration | [ORFs and evidence](https://openvax.github.io/orfdata/reference/) |
| Species and reference identity, mitochondrial genetic codes | [Species, references and genetic codes](https://openvax.github.io/orfdata/species/) |
| Versioned ORF catalogues managed through DataCache | [Optional ORF catalogues](https://openvax.github.io/orfdata/catalogs/) |
| Quantitative datasets and what has been released | [Measurements](https://openvax.github.io/orfdata/measurements/), [released data and gaps](https://openvax.github.io/orfdata/coverage/) |

The [data roadmap](https://github.com/openvax/orfdata/issues/3) tracks further
species and sources. Every PR includes a version bump, lint and tests;
maintainers publish with `./deploy.sh` from clean `main`.

## License

Apache 2.0. Downloadable datasets keep their sources' own terms and
attribution, recorded in each release manifest.
