Nucleotide Transformer v3
Collection
10 items • Updated
Request access to the NTv3 models
One approval grants access to every gated NTv3 model. Requests are reviewed manually.
The NTv3 weights are released under the InstaDeep Open Model Licence for non-commercial use only, and its terms also cover the models' outputs. For commercial use, contact legal@instadeep.com.
Log in or Sign Up to review the conditions and access this model content.
NTv3 Tracks
Predicts functional genomic tracks at single-base resolution, conditioned on species: gene expression, histone marks, transcription-factor binding and chromatin accessibility, from DNA sequence alone.
Built on the NTv3_pretrained
backbone and post-trained on 16,262 tracks across 15 species, then finetuned on a mix
of input lengths so it can be used from 16 kb to 1 Mb. Because one set of learned
representations serves every species and assay, what the model learns about sequence
function carries across them rather than being relearned for each.
Architecture
The NTv3 U-Net trunk — a convolutional encoder, a transformer tower at 1/128 resolution, a deconvolutional decoder back to base resolution — with species-conditioned prediction heads on top. Species conditioning is applied through FiLM modulation inside the trunk and at the head, so the same backbone produces different tracks for different species.
| Parameters | 711,256,680 |
| Resolution | 1 bp |
| Input length | 16,384 to 1,048,576 bp |
| Vocabulary | 16 tokens (soft-masked) |
| Species | 15 |
| Output channels | 7,362 |
| Precision | float32 |
Usage
import json
import torch
from huggingface_hub import hf_hub_download
from transformers import AutoModel, AutoTokenizer
repo = "InstaDeepAI/NTv3_tracks"
model = AutoModel.from_pretrained(repo, trust_remote_code=True).eval()
tokenizer = AutoTokenizer.from_pretrained(repo, trust_remote_code=True)
metadata = json.load(open(hf_hub_download(repo, "track_metadata.json")))
# The input length must be a multiple of 128; see "Input length" below.
sequence = "ACGT" * 4_096
batch = tokenizer([sequence], return_tensors="pt", add_special_tokens=False)
species = [torch.tensor([metadata["species_vocabulary"]["human"]])]
with torch.no_grad():
out = model(**batch, conditions_tokens=species)
out.bigwig_tracks_logits.shape # (1, 6144, 7362)
A 1 Mb forward pass needs a GPU with about 32 GB of memory or more; move the model
and the batch to it with .to("cuda").
Outputs are reachable both as attributes (out.bigwig_tracks_logits) and as keys
(out["bigwig_tracks_logits"]). An attention_mask is accepted and ignored: the
model derives its own mask from the pad token.
trust_remote_code=True is required. The modelling code is not in this repository:
config.json resolves it from InstaDeepAI/NTv3_pretrained, which therefore has to be
reachable as well.
Outputs
| Key | Shape | What it is |
|---|---|---|
bigwig_tracks_logits |
(batch, length × 0.375, 7362) |
Predicted track signal, one channel per track |
embedding |
(batch, length, 1024) |
Decoder output, one vector per base |
logits |
(batch, length, 16) |
Masked-token prediction |
species_logits |
(batch, 21) |
Auxiliary head from training. Not a usable species classifier: it predicts the mask token on real sequence. |
The region interface
For a genomic region rather than a bare sequence, the pipeline fetches the window, conditions on the species and labels the output:
from transformers import pipeline
predictor = pipeline("ntv3-tracks", model="InstaDeepAI/NTv3_tracks",
trust_remote_code=True)
out = predictor({"chrom": "chr11", "start": 5_219_320, "end": 5_235_704,
"species": "human"})
out.tracks.shape # (6144, 7362) positions x tracks
out.coordinates # (5224440, 5230584) what the predictions span
out.track("kai1") # one track's signal, by id
out.coordinates is narrower than the window you asked for, because the model
predicts its centre. Pass {"seq": ...} instead of coordinates for an assembly
UCSC does not host.
Reading the predictions
The output does not cover the whole window. It covers the central 37.5%. A 1 Mb input yields predictions for the central 393,216 bp. The edges are consumed as context. Tile your windows with overlap if you need continuous coverage.
Channel i is track i of that species' list. track_metadata.json holds
bigwigs_per_file_assembly, mapping each assembly to its ordered track ids. That order
is fixed and cannot be recovered from the weights, which is why it ships as a file:
track_ids = metadata["bigwigs_per_file_assembly"]["hg38"]
signal = out["bigwig_tracks_logits"][0, :, 0] # track_ids[0]
Species have different numbers of tracks and the head is padded to the widest one, so
only the first len(track_ids) channels are meaningful for a given species. The rest is
padding.
The species id comes from the same file. metadata["species_vocabulary"] maps each
species name to its id. Passing the wrong id gives you another species' tracks, silently.
Track lists are keyed by assembly, not by species, so
metadata["species_to_assembly"] gives the link:
assembly = metadata["species_to_assembly"]["human"] # "hg38"
track_ids = metadata["bigwigs_per_file_assembly"][assembly]
The predictions are in the scaled space the model was trained on, not in signal
units. Each track was divided by its genome-wide mean, RNA-seq tracks were then raised
to the power 0.75, and values above 10 were soft-clipped. The per-track means and the
RNA-seq flags ship in track_metadata.json, in the same order as the track ids, so the
predictions can be converted back to signal units:
import numpy as np
def to_signal(predictions, assembly, track_ids):
"""Converts predictions for these tracks, (..., len(track_ids)), to signal units."""
all_ids = metadata["bigwigs_per_file_assembly"][assembly]
index = [all_ids.index(track_id) for track_id in track_ids]
mean = np.array(metadata["track_means_per_file_assembly"][assembly])[index]
rna_seq = np.array(metadata["rna_seq_per_file_assembly"][assembly])[index]
x = np.where(predictions > 10, (predictions + 10) ** 2 / 40, predictions)
x = np.where(rna_seq, x ** (1 / 0.75), x)
return x * mean
Input length
The model was finetuned from
NTv3_tracks_1mb on inputs of
16, 32, 65, 131, 262 and 524 kb and 1 Mb. It matches that model at 1 Mb and stays
accurate on the shorter inputs, where the 1 Mb model does not. Accuracy is still
highest at 1 Mb, where the model sees the most context. Lengths between
the trained ones, and lengths outside 16 kb to 1 Mb, were not evaluated.
Pearson correlation between predicted and measured tracks (log1p-transformed, 1 bp) on held-out test regions of the 15 species, by input length. Right: the change per species.
Input requirements
Length must be a multiple of 128, the total downsampling factor of the trunk. Use one of the trained lengths above where you can.
Pass soft-masked sequence as it is. This model reads a 16-symbol alphabet: A C G T N and their lowercase counterparts a c g t n. Lowercase is not a formatting detail —
it is the RepeatMasker soft-masking convention, marking bases inside repeats, and the
model was trained with it. Most reference assemblies are distributed soft-masked, so
this is the natural input; upper-casing first throws the signal away. Note that
NTv3_pretrained uses the 11-symbol uppercase alphabet instead, so the two tokenizers
are not interchangeable.
Characters outside the vocabulary become <unk> and the sequence keeps its length.
Intended use
Predicting functional track signal from sequence for the species the model covers; comparing predicted signal between alleles or between designed sequences; and as a backbone for fine-tuning on your own track data.
Out of scope
Not a clinical or diagnostic tool. Predicted signal is a model output, not a measurement, and should not stand in for an experiment where the experiment is what matters.
Species outside the 15 it was trained on are out of distribution. The model will still return numbers for them, and those numbers carry no validated meaning.
Limitations
Predictions are conditioned on species and sequence only. There is no input for cell type, tissue, developmental stage or treatment beyond what the track panel itself encodes, so the model cannot be steered to a condition that is not already a track.
Accuracy varies substantially across assays, across species and across genomic regions. The panel is not balanced: some species contribute many more tracks than others, and performance follows that. Treat a single channel's output as weaker evidence than an aggregate.
The 37.5% crop is not a tunable inference setting. It is the geometry the model was trained with, and changing it changes what the outputs mean.
Related models
| Model | For |
|---|---|
NTv3_tracks_1mb |
The 1 Mb specialist this model was finetuned from; the NTv3 paper's main results use it |
NTv3_pretrained |
Embeddings, masked-token prediction, fine-tuning |
NTv3_annot_{mammals,plants,insects} |
Ab initio gene annotation, one model per clade |
Licence
Released under the InstaDeep Open Model Licence. The licence restricts output as well as weights, so predicted tracks carry the same terms. Read it before building on the model commercially.
Citation
Citation to be added on publication.
- Downloads last month
- 147