| --- |
| library_name: transformers |
| tags: |
| - genomics |
| - dna |
| - gene-annotation |
| - ntv3 |
| - long-range |
| license: other |
| license_name: instadeep-open-model-licence |
| license_link: https://huggingface.co/InstaDeepAI/NTv3_annot_insects/blob/main/MODEL-LICENSE.md |
| language: |
| - code |
| extra_gated_heading: Request access to the NTv3 models |
| extra_gated_description: >- |
| One approval grants access to every gated NTv3 model. Requests are reviewed |
| manually. |
| extra_gated_prompt: >- |
| The NTv3 weights are released under the |
| [InstaDeep Open Model Licence](https://huggingface.co/InstaDeepAI/NTv3_annot_insects/blob/main/MODEL-LICENSE.md) for non-commercial use only, and its terms |
| also cover the models' outputs. For commercial use, contact legal@instadeep.com. |
| extra_gated_fields: |
| Full name: text |
| Affiliation: text |
| Institutional email: text |
| Organisation type: |
| type: select |
| options: |
| - University |
| - Public research institute |
| - Non-profit |
| - Hospital |
| - Company |
| - Other |
| Country: country |
| Intended use: text |
| I will use NTv3 and its outputs for non-commercial purposes only, under the InstaDeep Open Model Licence: checkbox |
| extra_gated_button_content: Request access |
| --- |
| |
| # NTv3 Annotate — insects |
|
|
| NTv3 gene-annotation model for insect genomes: 703M parameters, predicting one of 15 |
| gene-structure classes at every base of a 1 Mb window. Modelling code is not in this |
| repository: `config.json` resolves it from |
| [`InstaDeepAI/NTv3_pretrained`](https://huggingface.co/InstaDeepAI/NTv3_pretrained) |
| through `auto_map`, so loading requires `trust_remote_code=True`. |
|
|
| > [!WARNING] |
| > **Use 1,048,576 bp windows only.** This model was trained only on 1 Mb windows. |
| > Shorter windows run without error, but annotation quality drops as the window gets |
| > shorter. Tile long sequences with 1 Mb windows, keeping the central 75% of each, and |
| > pad sequences shorter than 1 Mb with `N` up to 1,048,576 bp. The scores below were |
| > measured this way. |
|
|
| ## Test-species annotations |
|
|
| Whole-genome predictions on the 10 held-out test species are in |
| [`annot_results/`](annot_results/); its README gives provenance and scoring. |
|
|
| | species | CDS F1 | gene F1 | GFF3 | |
| |---|---:|---:|---| |
| | *Bombyx mori* | 85.2 | 56.5 | [`annot_results/ntv3_bombyx_mori_GCF_030269925.1.gff3.gz`](annot_results/ntv3_bombyx_mori_GCF_030269925.1.gff3.gz) | |
| | *Cataglyphis hispanica* | 87.8 | 63.9 | [`annot_results/ntv3_cataglyphis_hispanica_GCF_021464435.1.gff3.gz`](annot_results/ntv3_cataglyphis_hispanica_GCF_021464435.1.gff3.gz) | |
| | *Colias croceus* | 88.1 | 62.6 | [`annot_results/ntv3_colias_croceus_GCF_905220415.1.gff3.gz`](annot_results/ntv3_colias_croceus_GCF_905220415.1.gff3.gz) | |
| | *Danaus plexippus* | 89.4 | 65.7 | [`annot_results/ntv3_danaus_plexippus_GCF_018135715.1.gff3.gz`](annot_results/ntv3_danaus_plexippus_GCF_018135715.1.gff3.gz) | |
| | *Leptidea sinapis* | 82.0 | 55.0 | [`annot_results/ntv3_leptidea_sinapis_GCF_905404315.1.gff3.gz`](annot_results/ntv3_leptidea_sinapis_GCF_905404315.1.gff3.gz) | |
| | *Nymphalis io* (syn. *Aglais io*) | 89.2 | 66.0 | [`annot_results/ntv3_nymphalis_io_GCF_905147045.1.gff3.gz`](annot_results/ntv3_nymphalis_io_GCF_905147045.1.gff3.gz) | |
| | *Osmia bicornis* | 86.3 | 58.7 | [`annot_results/ntv3_osmia_bicornis_GCF_907164935.1.gff3.gz`](annot_results/ntv3_osmia_bicornis_GCF_907164935.1.gff3.gz) | |
| | *Tribolium castaneum* | 80.6 | 53.1 | [`annot_results/ntv3_tribolium_castaneum_GCF_031307605.1.gff3.gz`](annot_results/ntv3_tribolium_castaneum_GCF_031307605.1.gff3.gz) | |
| | *Vanessa cardui* | 88.8 | 64.4 | [`annot_results/ntv3_vanessa_cardui_GCF_905220365.1.gff3.gz`](annot_results/ntv3_vanessa_cardui_GCF_905220365.1.gff3.gz) | |
| | *Zerene cesonia* | 85.1 | 61.3 | [`annot_results/ntv3_zerene_cesonia_GCF_012273895.1.gff3.gz`](annot_results/ntv3_zerene_cesonia_GCF_012273895.1.gff3.gz) | |
|
|
| ## Data and notebooks |
|
|
| - **Benchmark data.** The test species' soft-masked genomes and reference |
| annotations are in |
| [`InstaDeepAI/NTv3_annot_dataset`](https://huggingface.co/datasets/InstaDeepAI/NTv3_annot_dataset) under |
| `insects/test_species/`: the longest-isoform reference the scores above use |
| (`reference_longest_isoform.gff3.gz`) and every annotated isoform |
| (`reference_all_isoforms.gff3.gz`). |
| - **Notebooks** in the [`ntv3`](https://huggingface.co/spaces/InstaDeepAI/ntv3) Space: |
| [03a](https://huggingface.co/spaces/InstaDeepAI/ntv3/blob/main/notebooks_tutorials/03a_genome_annotation_training.ipynb) trains a plant annotation |
| model from NTv3-tracks, |
| [03b](https://huggingface.co/spaces/InstaDeepAI/ntv3/blob/main/notebooks_tutorials/03b_genome_annotation_decoding.ipynb) decodes per-base predictions |
| into gene models, and |
| [03c](https://huggingface.co/spaces/InstaDeepAI/ntv3/blob/main/notebooks_tutorials/03c_genome_annotation_evaluation.ipynb) scores a GFF3 against a |
| reference the way the benchmark does. |
|
|
| ## Model information |
|
|
| - **Soft-masked input.** The tokenizer has 16 tokens: `A C G T N`, their lowercase |
| (repeat-masked) forms, and special tokens. Lowercase bases carry their own token ids, |
| so feed a soft-masked assembly (e.g. NCBI `_genomic.fna`, Ensembl `dna_sm`) for best |
| results. An uppercase-only sequence runs without error but loses the repeat signal. |
| `AutoTokenizer.from_pretrained(..., trust_remote_code=True)` loads it. |
| - **Window.** 1,048,576 bp windows, keeping the central 0.75 of each |
| (`ntv3.keep_target_center_fraction`, 0.75 by default in `config.json`). Keep both |
| values: other settings give a plausible but wrong annotation, not an error. |
| Pad sequences shorter than 1 Mb with `N`. |
| - **No species conditioning.** Pass an empty list: `conditions_tokens=[]`. |
| - **Precision.** Weights are fp32. For bf16, use `torch.autocast(device_type="cuda", |
| dtype=torch.bfloat16)`; casting the model itself (`torch_dtype="bfloat16"`, |
| `model.to(torch.bfloat16)`) fails. |
| - **Decoding.** The model outputs per-base class logits, not genes. `config.json` |
| holds the decoding HMM under `annotation` (states, transitions, splice-motif rules). |
| Notebook [03b](https://huggingface.co/spaces/InstaDeepAI/ntv3/blob/main/notebooks_tutorials/03b_genome_annotation_decoding.ipynb) decodes the logits into |
| gene models (GFF3) with it, and the NTv3-annotate pipeline (Home tab of the |
| [`ntv3`](https://huggingface.co/spaces/InstaDeepAI/ntv3) Space) annotates a genome FASTA end to end. |
|
|
| ## Licence |
|
|
| Released under the [InstaDeep Open Model Licence](https://huggingface.co/InstaDeepAI/NTv3_annot_insects/blob/main/MODEL-LICENSE.md). The licence restricts **output** as |
| well as weights, so predicted annotations carry the same terms. Read it before building |
| on the model commercially. |
|
|
| ## Citation |
|
|
| Citation to be added on publication. |
|
|
