ORFannotate

KO | EN

gitlite — search

#python #hacktoberfest #typescript #golang #machine-learning #rust #docker #windows #awesome #cli #pytorch #security #mcp #open-source

(★ 14)

A GTF-native ORF annotation tool for transcriptomes

ORFannotate 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ORFannotate

[![DOI](https://zenodo.org/badge/958608941.svg)](https://doi.org/10.5281/zenodo.16812866)
![GitHub release](https://img.shields.io/github/v/release/egustavsson/ORFannotate)

`ORFannotate` is a Python-based command-line tool for annotating coding open reading frames (ORFs) and translational features directly within transcript annotations. It augments GTF/GFF files with precise CDS features and generates a comprehensive transcript-level summary, including coding classification (CPAT score), Kozak context strength, 5′ and 3′ UTR lengths, splice junction distribution, predicted nonsense-mediated decay (NMD) sensitivity and predicts upstream ORFs (uORFs).

Designed for fast and reproducible transcriptome analysis, `ORFannotate` supports multiple species with pre-trained CPAT models, requires minimal dependencies, and integrates seamlessly into bioinformatics workflows.

---

## Features

`ORFannotate` is designed as a lightweight, GTF-native annotation step that augments transcript models with coding and translational-context information:
- Extract transcript sequences from a GTF/GFF and genome FASTA
- Predict and score ORFs using [`CPAT`](https://cpat.readthedocs.io/en/latest/#introduction)
- Annotate GTF/GFF files with CDS features (only for coding transcripts)
- Identify likely NMD targets (simple heuristic)
- Generate a clean, tab-separated summary of ORF and coding properties, including:
  - ORF/CDS length (nt/aa), coding probability
  - Kozak context and strength classification
  - Exon and UTR junction structure
  - UTR lengths
  - NMD prediction
  - uORF information
- Generate fasta files with transcript, CDS, UTR (5'/3') and protein sequences

---

## Installation

1. Clone the repository:
```
git clone https://github.com/egustavsson/ORFannotate.git
cd ORFannotate
```

2. Create the environment:
```
conda env create -f ORFannotate.conda_env.yml
conda activate ORFannotate
```

> Note: All required tools are installed when creating the environment.

---

## Quick test run

To quickly verify that ORFannotate is installed and functioning, use the minimal test dataset provided in `tests/test_data/`.
See the [Minimal test dataset](tests/test_data/README.md) for details.

---

## Running tests

ORFannotate includes unit tests and config-driven integration tests.

To run the standard test suite:

```bash
pytest
```

To run the full ORFannotate integration test using the toy dataset:

```bash
pytest tests/test_orfannotate.py --run-config tests/run-configs/toy.json
```

## Input

The pipeline requires:

| File           | Format       | Notes                                                                 |
|----------------|--------------|-----------------------------------------------------------------------|
| GTF/GFF file   | `.gtf` or `.gff` | Must contain `transcript` and `exon` features. Transcript IDs should be unique and consistent. |
| Genome FASTA   | `.fa`, `.fasta` | Reference genome matching the GTF. Must have transcript chromosome names matching those in the annotation. |

> [!WARNING]
> Ensure that your GTF includes transcript-level features (not just exons), or the pipeline may skip some records or produce incomplete outputs.

---

## Usage

To see available arguments:
```bash
python ORFannotate.py --help
```
This will print:

```
usage: ORFannotate.py [-h] --gtf GTF --fa FA --outdir OUTDIR [--species {human,mouse,fly,zebrafish}] [--coding-cutoff CODING_CUTOFF]

ORFannotate – predict coding ORFs, annotate GTF, and generate summaries.

required arguments:
  --gtf             Input GTF or GFF file with transcript and exon features
  --fa              Reference genome in FASTA format
  --outdir          Directory to write all outputs

optional arguments:
  --species         Species model to use for CPAT (choices: human, mouse, fly, zebrafish). Default: human
  --coding-cutoff   CPAT probability threshold to classify coding vs noncoding (if not set, default for species is used)
```
To run `ORFannotate`:
```bash
python ORFannotate.py --gtf annotations.gtf --fa genome.fa --outdir output/
```
### CPAT Species Support

`ORFannotate` now supports multiple species using CPAT’s pre-trained models:

| Species    | Hexamer file                  | Logistic model                   | Default cutoff |
|------------|-------------------------------|----------------------------------|----------------|
| Human      | data/Human_Hexamer.tsv        | data/Human_logitModel.RData      | 0.364          |
| Mouse      | data/Mouse_Hexamer.tsv        | data/Mouse_logitModel.RData      | 0.44           |
| Fly        | data/Fly_Hexamer.tsv          | data/Fly_logitModel.RData        | 0.39           |
| Zebrafish  | data/Zebrafish_Hexamer.tsv    | data/Zebrafish_logitModel.RData  | 0.38           |

Use the `--species` argument to select the appropriate model. If `--coding-cutoff` is not specified, the pipeline will use the default cutoff for the selected species.

> [!NOTE]
> ***Training or Updating CPAT Models***
>
> You can train your own CPAT models, either for unsupported species or to update the model for an existing species using improved coding and noncoding transcript sets.
> This requires building a custom hexamer frequency table and logistic regression model.
> 
> Refer to the [CPAT documentation](https://cpat.readthedocs.io/en/latest/#training-a-custom-model) for detailed instructions.

## Configuration
`ORFannotate` includes a configuration file [config.json](data/config.json) defining:
- Paths to CPAT model files for each supported species
- Default CPAT probability cutoffs
- Number of ORFs retained per transcript (top N by CPAT score; default N = 5)
- Minimum length for upstream ORFs (`min_length_uorf`, default: 30 nt)

## Output files
After a successful run, the following files will be saved in `<output_dir>`:

| **File**                      | **Description**                                                                                          |
|-------------------------------|----------------------------------------------------------------------------------------------------------|
| `transcripts.fa`              | FASTA file of full transcript sequences                                                                  |
| `CPAT/cpat.ORF_prob.tsv`      | CPAT output for the top N ORFs per transcript (default: 5)                                               |
| `CPAT/cpat.ORF_prob.best.tsv` | CPAT output for the best ORF per transcript                                                              |
| `CPAT/cpat_debug.tsv`         | Full CPAT-scored ORFs (optional debug output)                                                            |
| `CPAT/CPAT_run_info.log`      | Full CPAT command log                                                                                    |
| `CPAT/CPAT.log`               | CPAT runtime messages                                                                                    |
| `CPAT_uORF/`                  | CPAT outputs for uORF prediction using 5′ UTR sequences                                                  |
| `cds.fa`                      | FASTA of predicted coding sequences for coding transcripts                                               |
| `protein.fa`                  | FASTA of protein sequences translated from predicted CDS                                                 |
| `utr5.fa`                     | FASTA of 5′ UTRs for coding transcripts (if present)                                                     |
| `utr3.fa`                     | FASTA of 3′ UTRs for coding transcripts (if present)                                                     |
| `ORFannotate_annotated.gtf`   | GTF with predicted CDS features added to coding transcripts                                              |
| `uORFannotate_annotated.gtf`  | GTF with predicted uORF features added within 5′ UTR regions                                             |
| `ORFannotate_summary.tsv`     | Final transcript-level summary with ORF, CDS, UTR, uORF, Kozak, NMD, and coding classification features  |
| `ORFannotate.log`             | General pipeline log                                                                                     |

> FASTA files are only generated for transcripts classified as coding. UTRs are only included if valid regions exist upstream or downstream of the predicted ORF.

### Summary Output Fields

The final output summary file `ORFannotate_summary.tsv` contains one row per transcript and includes:

| Column                        | Description |
|-------------------------------|-------------|
| `transcript_id`               | Transcript identifier |
| `gene_id`                     | Associated gene ID |
| `chrom`                       | Chromosome name |
| `strand`                      | `+` or `-` |
| `transcript_start`            | Transcript start position (genomic) |
| `transcript_end`              | Transcript end position (genomic) |
| `has_orf`                     | `TRUE` if an ORF was predicted, `FALSE` otherwise |
| `orf_nt_len`                  | ORF length in nucleotides (only if coding) |
| `orf_aa_len`                  | ORF length in amino acids (only if coding) |
| `coding_prob`                 | CPAT-predicted coding probability |
| `coding_class`                | `coding` or `noncoding` based on cutoff |
| `total_junctions`             | Total number of exon–exon junctions in the transcript |
| `utr5_junctions`              | Number of junctions occurring fully within the 5′ UTR (only for coding) |
| `cds_junctions`               | Number of junctions overlapping or inside the CDS region (only for coding) |
| `utr3_junctions`              | Number of junctions occurring fully within the 3′ UTR (only for coding) |
| `stop_to_last_EJ`             | Distance from stop codon to last exon junction |
| `NMD_sensitive`               | `TRUE` if predicted to undergo NMD, else `FALSE` |
| `kozak_strength`              | `strong`, `moderate`, `weak`, or `NA` (only if coding) |
| `kozak_sequence`              | Kozak sequence around start codon (if available) |
| `utr5_nt_len`                 | 5′ UTR length in nucleotides (only if coding) |
| `utr3_nt_len`                 | 3′ UTR length in nucleotides (only if coding) |
| `has_uORF`                    | `TRUE` if an uORF was predicted, `FALSE` otherwise |
| `coding_prob_best_uORF`       | CPAT-predicted coding probability of the best uORF |
| `length_best_uORF`            | Length of the best retained uORF |
| `nmd_sensitivity_best_uORF`   | Predicted NMD sensitivity associated with the best retained uORF |
| `kozak_strength_best_uORF`    | Kozak context strength of the best retained uORF start codon |
| `kozak_seq_best_uORF`         | Sequence context surrounding the best retained uORF start codon |

---

### Kozak Sequence Scoring

The Kozak consensus sequence plays a role in translation initiation efficiency. For each predicted coding transcript, `ORFannotate` extracts a 10-nucleotide sequence surrounding the start codon (positions −6 to +4) and classifies the Kozak strength:

**Consensus:**
```
gccRccAUGG
      ^^^
```

- R = A or G
- Position −3 (relative to start codon) is most critical
- Position +4 (immediately after AUG) also contributes

**Classification:**

| Position −3 | Position +4 | Strength   |
|-------------|-------------|------------|
| A or G      | G           | **strong** |
| A or G      | not G       | moderate   |
| not A/G     | G           | moderate   |
| not A/G     | not G       | weak       |

If the sequence is too short to evaluate, strength is recorded as `"NA"`.

---

### NMD Prediction
`ORFannotate` predicts nonsense-mediated decay (NMD) susceptibility using a simple and widely accepted heuristic:

>A transcript is considered NMD-sensitive if the stop codon lies more than 50 nucleotides upstream of the last exon–exon junction.

This conservative approach is fast and works well for general transcriptome-level analyses, but may not capture all context-dependent cases.

The following output column is provided in the summary:

NMD_sensitive: "TRUE" if the transcript meets the NMD rule, "FALSE" otherwise.

---

### Upstream Open Reading Frames (uORFs)

ORFannotate identifies upstream open reading frames (uORFs) within the 5′ UTR of transcripts that are classified as coding and have a predicted canonical ORF.

uORFs are defined as CPAT-predicted ORFs that:
- occur entirely upstream of the canonical ORF start site
- exceed the minimum configured ORF length (default: 30 nt / 10 aa)
- have a coding probability above the specified cutoff

The minimum uORF length is configurable per species in [config.json](data/config.json) via the
`min_length_uorf` field.

uORFs are not evaluated for transcripts without a predicted canonical coding ORF.  
If no qualifying uORF is detected, `has_uORF` is reported as `FALSE`, and the uORF-specific fields are reported as `NA`.

For transcripts with a retained uORF, the summary reports the CPAT coding probability, uORF length, predicted NMD sensitivity, Kozak strength, and Kozak sequence for the best retained uORF using the following columns:

- `coding_prob_best_uORF`
- `length_best_uORF`
- `nmd_sensitivity_best_uORF`
- `kozak_strength_best_uORF`
- `kozak_seq_best_uORF`

Selected uORFs are also written to `uORFannotate_annotated.gtf`, where they are added as uORF features within the predicted 5′ UTR regions.

## Directory Structure

```
ORFannotate/
├── ORFannotate.py                 # Main script (entry point)
├── ORFannotate.conda_env.yml      # Conda environment file
├── orfannotate/                   # Modular Python package
│   ├── __init__.py
|   ├── utils.py                   # Shared helper functions
│   ├── transcript_extraction.py
│   ├── orf_prediction.py
│   ├── gtf_annotation.py
│   ├── nmd.py
│   ├── kozak.py
│   ├── orf_filter.py
│   └── summarise.py
|
├── tests/                         # Unit and integration tests (pytest)
│   ├── __init__.py
│   ├── conftest.py                # Adds pytest options, including --run-config
│   ├── run-configs/               # JSON configs for integration test runs
│   ├── test_imports.py
│   ├── test_kozak.py
│   ├── test_nmd.py
│   ├── test_orf_filter.py
│   ├── test_orfannotate.py        # Config-driven integration tests
│   └── test_data/
│       ├── README.md
│       ├── toy.fa
│       └── toy.gtf
│
├── data/                          # CPAT model files (hexamer and logitModel)
│   ├── Human_Hexamer.tsv
│   |── Human_logitModel.RData
│   |── ... # additional species
|   └── config.json                # Config file: species models, cutoffs, ORF limits.
│
├── docs/
│   └── logo.svg
│
├── LICENSE
└── README.md
```
## Citation

If you use `ORFannotate` in your research, please cite:

Sonia García-Ruiz, Hannah Macpherson, Laura Caton, Mina Ryten, Emil K Gustavsson.  
**ORFannotate: reproducible coding sequence annotation of transcriptome assemblies.**  
*Bioinformatics* (2026).  
https://doi.org/10.1093/bioinformatics/btag082

## License
This project is licensed under the GPLv3 License. See [`LICENSE`](LICENSE) for details.

## Acknowledgements
- [CPAT](https://cpat.readthedocs.io/en/latest/)
- [gffutils](https://github.com/daler/gffutils)
- [Biopython](https://biopython.org/)
- [gffread](https://github.com/gpertea/gffread)

ORFannotate

ORFannotate 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

ORFannotate

ORFannotate 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README