README.md

metadata

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 through auto_map, so loading requires trust_remote_code=True.

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/; 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
Cataglyphis hispanica	87.8	63.9	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
Danaus plexippus	89.4	65.7	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
Nymphalis io (syn. Aglais io)	89.2	66.0	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
Tribolium castaneum	80.6	53.1	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
Zerene cesonia	85.1	61.3	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 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 Space: 03a trains a plant annotation model from NTv3-tracks, 03b decodes per-base predictions into gene models, and 03c 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 decodes the logits into gene models (GFF3) with it, and the NTv3-annotate pipeline (Home tab of the ntv3 Space) annotates a genome FASTA end to end.

Licence

Released under the InstaDeep Open Model Licence. 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.