Open Targets E2G¶
The opentargets_e2g source adds the genes a variant's regulatory element is predicted to regulate, from the
Open Targets Platform's enhancer_to_gene dataset. Those are ENCODE-rE2G
predictions across 1,439 ENCODE biosamples, which Open Targets keeps at score ≥ 0.6. The source is a lookup in a
released dataset and runs no model.
| Kind | Annotation source; type = "opentargets_e2g" |
| Install | pip install altar-opentargets-e2g (PyPI) |
| Genome builds | hg38 |
| Variant classes | Every class, by overlap, on chr1–22 and X |
| Data | Published: release 26.09 on hg38, read in place. gcs (default): gs://kundajelab-altar/opentargets-e2g/enhancer-to-gene-26.09; hf: hf://datasets/altar-genomics/opentargets-e2g-26.09. Copy it with altar pull opentargets_e2g --to PATH_OR_URI, or --bigquery PROJECT.DATASET.TABLE. Build your own with altar-opentargets-e2g-build |
| Validation | Matches upstream on spot checks (Validation) |
| Licence | CC0 1.0 data; cite Open Targets and ENCODE |
| Upstream | Data, Paper, Documentation |
When to use it¶
- Use Open Targets E2G to ask which genes the regulatory elements a variant overlaps are predicted to regulate, and in which ENCODE biosamples. It reads a published copy in place, with no download.
- Choose the ENCODE-rE2G and scE2G atlases for links Open Targets leaves out: ENCODE-rE2G links
scored below 0.6, or scE2G predictions from single-cell data. You import those files into a link store yourself.
Both sources write the same columns, and
column_prefixputs them side by side. - Choose Genomic regions for the nearest genes and the variant's gene region. A nearest gene is a distance, not a predicted target.
- Choose a model, such as ChromBPNet or Cherimoya, to ask whether the variant changes the element's activity. A link predicts that an element regulates a gene, not that the variant matters.
- The source serves hg38 only (Limits).
Add it to a run¶
- Install the binding:
pip install altar-opentargets-e2g. - Add the section above to the run spec. It reads the published copy in place, with no download and no credentials.
altar sources opentargets_e2g lists the columns, the options and the published copy. The
run spec reference describes the [sources.<name>] section, and
Annotate variants with evidence walks through a run.
Tutorial 3: put model scores beside evidence reads the genes linked to
five variants in a notebook.
Outputs¶
| Column | Type | Meaning |
|---|---|---|
link_top_gene |
str | The Ensembl gene ID of the strongest link. |
link_top_gene_symbol |
str | The gene symbol of that link. Open Targets gives no symbols, so it is empty. |
link_top_score |
float | The ENCODE-rE2G score of that link. |
link_gene_count |
int | The number of distinct linked genes. |
link_count |
int | The number of links. |
link_genes |
list of struct (gene_id, gene_namespace, gene_symbol, score, score_direction, biosample, biosample_id, regulatory_element_id, element_type, source_id, source_name, method, data_release, record_id, source_record_id, source_dataset) |
Every link, strongest first. |
The columns are Altar's variant–gene link contract, org.kundajelab.altar.annotation.variant-gene-links. Every
link whose regulatory element overlaps the variant counts. With column_prefix = "ot", each name starts with ot_,
such as ot_link_top_score.
Each link_genes record has the link's gene (gene_id, gene_namespace, gene_symbol), its score and
score_direction, its biosample and biosample_id, its element (regulatory_element_id, element_type) and
its provenance (source_id, source_name, method, data_release, record_id, source_record_id,
source_dataset). source_record_id is Open Targets' intervalId.
A variant that overlaps no link gets no link columns. That is not evidence that it regulates nothing: Open Targets keeps only links scored 0.6 or more.
An augmented VCF written from a run's export carries these columns as ALTAR1_OT_E2G_* INFO fields; see
Write an augmented VCF.
Configuration¶
| Option | Set in | Type | Default | Meaning |
|---|---|---|---|---|
dataset |
[sources.opentargets_e2g.options] |
path | not set | your own copy, as a path or URI, such as one altar pull made or one altar-opentargets-e2g-build wrote (default: the published copy) |
table |
[sources.opentargets_e2g.options] |
text | not set | your own BigQuery table, project.dataset.table, such as one altar pull --bigquery loaded |
release |
[sources.opentargets_e2g.options] |
text | not set | the release a table holds, given only with table (default: the published release) |
genome_build |
[sources.opentargets_e2g.options] |
text | not set | the genome build of the data, checked against it when given |
filters |
[sources.opentargets_e2g.options] |
table with keys context_ids, context_names, source_ids, gene_ids, methods, data_releases, minimum_score, maximum_score |
not set | which links to keep, by biosample, gene, source, method, release or score |
column_prefix |
[sources.opentargets_e2g.options] |
text | not set | a prefix for every column, such as ot for ot_link_top_score, to sit beside another link source |
name |
[sources.opentargets_e2g.options] |
text | not set | the source's name in the run (default: opentargets_e2g, or <column_prefix>_opentargets_e2g) |
prioritize_predicate |
Only in code | not set | a rule on the source's columns that sets prioritized |
|
storage_options |
[sources.opentargets_e2g.options] |
table | not set | fsspec settings for reading the files, such as credentials |
connection |
[sources.opentargets_e2g] |
not set | connection = "<name>": the [connections.<name>] section to read the data through | |
location |
[sources.opentargets_e2g.options] |
one of "gcs", "hf" |
"gcs" |
where to read the published copy from |
Every option is optional. With none, the source reads the published copy from gcs.
location = "hf"reads the Hugging Face mirror, which needspip install "altar[hf]"(Where it comes from).datasetnames your own link dataset, as a path or a URI. It may hold another release built withaltar-opentargets-e2g-build.tablenames your own BigQuery table,project.dataset.table, read through agcpconnection. It is Preview: tested on the BigQuery emulator and DuckDB; not run against live BigQuery.releaseis given withtableonly. The default is26.09.genome_build, when given, must behg38.storage_optionsis not allowed withconnection.connection = "<name>", set in[sources.opentargets_e2g]itself, names the[connections.<name>]section to read through.
filters keeps only some links. Its keys are context_names (biosample names, such as ["liver"]),
context_ids, gene_ids, source_ids, methods, data_releases, minimum_score and maximum_score. The
identifier filters are lists of strings. Filters change the source's identity
(Release and identity). This keeps kidney and liver links and prefixes the columns:
[sources.e2g]
type = "opentargets_e2g"
[sources.e2g.options]
filters = { context_names = ["right kidney", "liver"] }
column_prefix = "ot"
column_prefix prefixes every column, such as ot for ot_link_top_score, so the source can sit beside another
link source. name renames the source.
An unknown option, filter or location stops the run with an error that lists the valid ones.
Inputs¶
- Genome builds: hg38 only. Open Targets publishes the data on GRCh38 only. A run on another build stops before it reads the cohort, whichever copy the source reads, and the error names the source.
- Variant classes: every class. A variant is looked up at the reference span of its minimal representation, and every link whose element overlaps that span counts. An indel's span includes its anchor base.
- Chromosomes: links are on chr1–22 and X. A variant elsewhere has no link columns.
Where it comes from¶
The Kundaje lab builds Open Targets release 26.09 (enhancer_to_gene, 2026-09-24, on GRCh38) with
altar-opentargets-e2g-build. It publishes the output in a public-read bucket, with a byte-for-byte mirror on
Hugging Face (dataset card). The card above
lists both locations. It holds 48,806,245 links in 23 files, 2.70 GB, partitioned by chromosome and sorted by
start position. altar-opentargets-e2g depends on altar[gcs], so the default location needs no other install.
location = "hf" reads the mirror, which needs pip install "altar[hf]". Hugging Face limits anonymous
requests, so a large cohort read from hf can stall; see
Hugging Face rate limits.
To keep your own copy:
altar pull opentargets_e2g --to gs://my-bucket/opentargets-e2g-26.09
altar pull opentargets_e2g --bigquery my-project.reference.opentargets_e2g_26_09 --project my-project
The first copies the Parquet files and checks that every file records the release. The second loads them into a
BigQuery table clustered on chromosome, start, since a link is found by interval overlap, and labels the table with
its release. altar pull --bigquery is Preview: tested against a fake BigQuery client only; not run against live
BigQuery. Name the copy with dataset, or the table with table and a gcp connection.
Choose where data is read from covers the published copy, your own copy, BigQuery
tables, altar pull and connections for every source.
Release and identity¶
An Open Targets release is named YY.MM, such as 26.09; the Platform publishes about one a quarter. The source
reads release 26.03 and later.
The source's identity is the contract (version 1.0.0), the release and hg38. Filters change which links a
variant has, so with filters the identity's release is 26.09+<fingerprint>. The published copy, a pulled copy,
a table loaded from it, and a copy you build from the same release declare the same identity. Where the data is
read from is not part of it.
Build another release¶
altar-opentargets-e2g-build reads every Parquet file of one release and writes the link dataset to a local
directory:
pip install "altar-opentargets-e2g[build]"
altar-opentargets-e2g-build \
--input https://ftp.ebi.ac.uk/pub/databases/opentargets/platform/26.09/output/enhancer_to_gene/ \
--release 26.09 --output /scratch/opentargets-e2g-26.09
--input takes files or directories, local or behind a URI; the build extra adds https://. The EBI FTP site
slows above a few parallel connections, so downloading the files first and passing their directory is faster.
The builder:
- refuses a file from before release 26.03, whose coordinates were 32-bit and which lacks
biosampleFromSourceIdandqualityControls, and a row scored below 0.6; - maps each file in its own process (
--workers, by default the CPU count); - drops a row that repeats an
intervalIdonly when the whole upstream row is identical, and stops when two rows with oneintervalIddiffer. 26.09 has 2,246 identical repeats; - writes one row per link, partitioned by chromosome (1–22, X), sorted by start, in 32,000-row groups, with the
release,
hg38and the dataset in every file's metadata; - writes only into an empty or absent
--output.--overwritereplaces a previous link dataset there.
--temp-directory sets where scratch files go, and --input-storage-option passes a non-secret fsspec option
for remote inputs. --output is a local directory; copy it to a bucket yourself. Name the output with dataset.
Compute and scale¶
- A lookup runs no model and needs no GPU.
- The published copy is 48,806,245 links in 23 files, 2.70 GB, partitioned by chromosome and sorted by start in 32,000-row groups. Reading it bills you nothing.
- Hugging Face limits anonymous requests, so read a large cohort from
gcsor from your own copy. - A BigQuery table is queried in place, one query per 10,000 variants. A query over scattered variants reads most of the table whatever the cohort's size: about 12 GB billed for a handful of variants and 15 GB for 10,000 on 26.09, at on-demand pricing.
Prioritization¶
None from a run spec. Built in code, OpenTargetsE2GAnnotationSource.from_options(prioritize_predicate=...)
gates prioritized on a rule you give, such as Ge(Col("link_top_score"), Lit(0.8)).
What prioritized means explains how rules combine.
Validation¶
Validation label: Matches upstream on spot checks. When the published copy was built, its links plus the 2,246 identical repeats the builder dropped were checked against the 48,808,491 rows of Open Targets' files. Variants looked up in the published copy and in Open Targets' files had the same links.
Not validated:
- a release you build yourself;
- reading a BigQuery table (
table) or loading one (altar pull --bigquery) on live BigQuery, both Preview.
Limits¶
- Open Targets publishes the data on GRCh38 only, so the source serves hg38.
- Links are on chr1–22 and X. A variant elsewhere has no link columns.
- Open Targets keeps links scored 0.6 or more, so a weaker prediction is not in the data.
- Open Targets gives no gene symbols, so
link_top_gene_symbolis empty. - A link says that ENCODE-rE2G predicts an element regulates a gene in a biosample. It is not a measured effect of the variant.
Cite and licence¶
Open Targets Platform data is released under CC0 1.0. See Open Targets: citation. Cite the Platform:
@article{buniello2025opentargets,
author = {Buniello, Annalisa and Suveges, Daniel and Cruz-Castillo, Carlos and Llinares, Manuel Bernal and
Cornu, Helena and Lopez, Irene and Tsukanov, Kirill and Rold{\'a}n-Romero, Juan Mar{\'i}a and Mehta, Chintan and
Fumis, Luca and McNeill, Graham and Hayhurst, James D and Martinez Osorio, Ricardo Esteban and
Barkhordari, Ehsan and Ferrer, Javier and Carmona, Miguel and Uniyal, Prashant and Falaguera, Maria J and
Rusina, Polina and Smit, Ines and Schwartzentruber, Jeremy and Alegbe, Tobi and Ho, Vivien W and
Considine, Daniel and Ge, Xiangyu and Szyszkowski, Szymon and Tsepilov, Yakov and Ghoussaini, Maya and
Dunham, Ian and Hulcoop, David G and McDonagh, Ellen M and Ochoa, David},
title = {Open Targets Platform: facilitating therapeutic hypotheses building in drug discovery},
journal = {Nucleic Acids Research},
volume = {53},
number = {D1},
pages = {D1467--D1475},
year = {2025},
doi = {10.1093/nar/gkae1128}
}
Cite ENCODE-rE2G, the model behind the links:
@article{gschwind2026encodere2g,
author = {Gschwind, Andreas R. and Mualim, Kristy S. and Karbalayghareh, Alireza and Sheth, Maya U. and
Dey, Kushal K. and Jagoda, Evelyn and Nurtdinov, Ramil N. and Xi, Wang and Tan, Anthony S. and Galante, James
and Jones, Hank and Ma, X. Rosa and Yao, David and Amgalan, Dulguun and Ray, Judhajeet and Munger, Chad J. and
Nasser, Joseph and Avsec, {\v{Z}}iga and James, Benjamin T. and Shamim, Muhammad S. and Durand, Neva C. and
Rao, Suhas S. P. and Mahajan, Ragini and Doughty, Benjamin R. and Andreeva, Kalina and Ulirsch, Jacob C. and
Fan, Kaili and Perez, Elizabeth M. and Nguyen, Tri C. and Kelley, David R. and Finucane, Hilary K. and
Moore, Jill E. and Weng, Zhiping and Kellis, Manolis and Bassik, Michael C. and Ustun, Berk and Price, Alkes L.
and Beer, Michael A. and Guig{\'o}, Roderic and Stamatoyannopoulos, John A. and Lieberman Aiden, Erez and
Greenleaf, William J. and Leslie, Christina S. and Steinmetz, Lars M. and Kundaje, Anshul and Engreitz, Jesse M.},
title = {An encyclopedia of human enhancer--gene regulatory interactions},
journal = {Nature},
volume = {657},
number = {8130},
pages = {179--190},
year = {2026},
doi = {10.1038/s41586-026-10781-4}
}
The links are ENCODE data. ENCODE's citation guidance asks you
to cite its integrative analysis and its portal papers, to acknowledge the consortium, and to give the accessions
of the prediction files (ENCFF…) you rely on. Open Targets names each row's file in its studyId column; a
link's source_record_id is the row's intervalId, which finds it there.
@article{encode2012integrated,
author = {{ENCODE Project Consortium}},
title = {An integrated encyclopedia of {DNA} elements in the human genome},
journal = {Nature},
volume = {489},
number = {7414},
pages = {57--74},
year = {2012},
doi = {10.1038/nature11247}
}
@article{luo2020encodeportal,
author = {Luo, Yunhai and Hitz, Benjamin C. and Gabdank, Idan and Hilton, Jason A. and Kagda, Meenakshi S. and
Lam, Bonita and Myers, Zachary and Sud, Paul and Jou, Jennifer and Lin, Khine and Baymuradov, Ulugbek K. and
Graham, Keenan and Litton, Casey and Miyasato, Stuart R. and Strattan, J. Seth and Jolanki, Otto and
Lee, Jin-Wook and Tanaka, Forrest Y. and Adenekan, Philip and O'Neill, Emma and Cherry, J. Michael},
title = {New developments on the {Encyclopedia of DNA Elements} ({ENCODE}) data portal},
journal = {Nucleic Acids Research},
volume = {48},
number = {D1},
pages = {D882--D889},
year = {2020},
doi = {10.1093/nar/gkz1062}
}
@article{kagda2025encodeportal,
author = {Kagda, Meenakshi S. and Lam, Bonita and Litton, Casey and Small, Corinn and Sloan, Cricket A. and
Spragins, Emma and Tanaka, Forrest and Whaling, Ian and Gabdank, Idan and Youngworth, Ingrid and
Strattan, J. Seth and Hilton, Jason and Jou, Jennifer and Au, Jessica and Lee, Jin-Wook and
Andreeva, Kalina and Graham, Keenan and Lin, Khine and Simison, Matt and Jolanki, Otto and Sud, Paul and
Assis, Pedro and Adenekan, Philip and Miyasato, Stuart and Zhong, Weiwei and Luo, Yunhai and
Myers, Zachary and Cherry, J. Michael and Hitz, Benjamin C.},
title = {Data navigation on the {ENCODE} portal},
journal = {Nature Communications},
volume = {16},
pages = {9592},
year = {2025},
doi = {10.1038/s41467-025-64343-9}
}
- Data: Open Targets Platform data, CC0 1.0.
- Binding:
altar-opentargets-e2gis MIT-licensed. It ships no data.
Python and extension¶
OpenTargetsE2GAnnotationSource.from_options() builds the same source as a run spec, with the same options as
keywords. Look up evidence shows a lookup from Python.
The binding also registers OpenTargetsE2GSource, a variant–gene link source. It pages each link with its full
record, including distances, component scores and quality controls, from any link store that
OpenTargetsE2GImporter filled. Both shapes map an upstream row the same way, so a link has the same gene,
score, biosample and provenance in either. See
Add an annotation source for link sources and stores.
A table source runs its own queries, so a BigQuery store does not read it in its own SQL.
Run at warehouse scale on BigQuery covers sources at warehouse scale.