Add the access-request form (#7)

9188406 2 days ago

10.6 kB

---
library_name: transformers
tags:
  - genomics
  - dna
  - biology
  - ntv3
  - long-range
  - functional-genomics
license: other
license_name: instadeep-open-model-licence
license_link: https://huggingface.co/InstaDeepAI/NTv3_tracks_1mb/blob/main/MODEL-LICENSE.md
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_tracks_1mb/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 Tracks — 1 Mb

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`](https://huggingface.co/InstaDeepAI/NTv3_pretrained)
backbone and post-trained on 16,262 tracks across 15 species. 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.

This is the 1 Mb specialist, the model behind the main results of the NTv3 paper.

> [!WARNING]
> **Use 1,048,576 bp inputs only.** This is the 1 Mb specialist: it was trained only on
> 1 Mb windows. Shorter inputs run without error, but prediction quality drops as the
> input gets shorter. For shorter sequences, use
> [`NTv3_tracks`](https://huggingface.co/InstaDeepAI/NTv3_tracks), which was trained on
> a range of lengths.

## 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 | 1,048,576 bp (trained length) |
| Vocabulary | 16 tokens (soft-masked) |
| Species | 15 |
| Output channels | 7,362 |
| Precision | float32 |

## Usage

```python
import json
import torch
from huggingface_hub import hf_hub_download
from transformers import AutoModel, AutoTokenizer
repo = "InstaDeepAI/NTv3_tracks_1mb"
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")))
# Inputs must be 1,048,576 bp, the length the model was trained on.
sequence = "ACGT" * 262_144
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, 393216, 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:

```python
from transformers import pipeline
predictor = pipeline("ntv3-tracks", model="InstaDeepAI/NTv3_tracks_1mb",
                     trust_remote_code=True)
out = predictor({"chrom": "chr11", "start": 4_703_224, "end": 5_751_800,
                 "species": "human"})
out.tracks.shape      # (393216, 7362)  positions x tracks
out.coordinates       # (5030904, 5424120)  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:

```python
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:

```python
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:

```python
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 requirements

**Length must be 1,048,576 bp**, the length the model was trained on. Other multiples
of 128 run, but give less accurate predictions.

**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.

The model was trained at a single input length (1 Mb). Like the 37.5% crop, this is
part of the geometry it learned, not a free inference setting.

## Related models

| Model | For |
| --- | --- |
| [`NTv3_tracks`](https://huggingface.co/InstaDeepAI/NTv3_tracks) | The same tracks, from inputs of 16 kb to 1 Mb |
| [`NTv3_pretrained`](https://huggingface.co/InstaDeepAI/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](https://huggingface.co/InstaDeepAI/NTv3_tracks_1mb/blob/main/MODEL-LICENSE.md). 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.

	---
	library_name: transformers
	tags:
	- genomics
	- dna
	- biology
	- ntv3
	- long-range
	- functional-genomics
	license: other
	license_name: instadeep-open-model-licence
	license_link: https://huggingface.co/InstaDeepAI/NTv3_tracks_1mb/blob/main/MODEL-LICENSE.md
	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_tracks_1mb/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 Tracks — 1 Mb

	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`](https://huggingface.co/InstaDeepAI/NTv3_pretrained)
	backbone and post-trained on 16,262 tracks across 15 species. 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.

	This is the 1 Mb specialist, the model behind the main results of the NTv3 paper.

	> [!WARNING]
	> Use 1,048,576 bp inputs only. This is the 1 Mb specialist: it was trained only on
	> 1 Mb windows. Shorter inputs run without error, but prediction quality drops as the
	> input gets shorter. For shorter sequences, use
	> [`NTv3_tracks`](https://huggingface.co/InstaDeepAI/NTv3_tracks), which was trained on
	> a range of lengths.

	## 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 \| 1,048,576 bp (trained length) \|
	\| Vocabulary \| 16 tokens (soft-masked) \|
	\| Species \| 15 \|
	\| Output channels \| 7,362 \|
	\| Precision \| float32 \|

	## Usage

	```python
	import json

	import torch
	from huggingface_hub import hf_hub_download
	from transformers import AutoModel, AutoTokenizer

	repo = "InstaDeepAI/NTv3_tracks_1mb"
	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")))

	# Inputs must be 1,048,576 bp, the length the model was trained on.
	sequence = "ACGT" * 262_144

	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, 393216, 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:

	```python
	from transformers import pipeline

	predictor = pipeline("ntv3-tracks", model="InstaDeepAI/NTv3_tracks_1mb",
	trust_remote_code=True)

	out = predictor({"chrom": "chr11", "start": 4_703_224, "end": 5_751_800,
	"species": "human"})

	out.tracks.shape # (393216, 7362) positions x tracks
	out.coordinates # (5030904, 5424120) 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:

	```python
	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:

	```python
	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:

	```python
	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 requirements

	Length must be 1,048,576 bp, the length the model was trained on. Other multiples
	of 128 run, but give less accurate predictions.

	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.

	The model was trained at a single input length (1 Mb). Like the 37.5% crop, this is
	part of the geometry it learned, not a free inference setting.

	## Related models

	\| Model \| For \|
	\| --- \| --- \|
	\| [`NTv3_tracks`](https://huggingface.co/InstaDeepAI/NTv3_tracks) \| The same tracks, from inputs of 16 kb to 1 Mb \|
	\| [`NTv3_pretrained`](https://huggingface.co/InstaDeepAI/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](https://huggingface.co/InstaDeepAI/NTv3_tracks_1mb/blob/main/MODEL-LICENSE.md). 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.