ENCODE-rE2G and scE2G atlases¶
The E2G atlas binding adds the genes a variant's regulatory element is predicted to regulate, from released
ENCODE-rE2G and scE2G prediction files. You import the files into a SQLite link store once with
altar-e2g-atlas-ingest. A run then looks each variant up in the store through the core variant_gene_links
source. It runs neither pipeline.
| Kind | Link source; a run reads its links with type = "variant_gene_links" |
| Install | altar-e2g-atlas, from a source checkout: pip install -e bindings/e2g-atlas in a clone of the repository (how) |
| Genome builds | hg38 |
| Variant classes | Every class, by overlap |
| Data | Import with altar-e2g-atlas-ingest |
| Validation | Not spot-checked (Validation) |
| Licence | No ENCODE restrictions; cite ENCODE-rE2G, scE2G and ENCODE |
| Upstream | Data, Code, Paper |
When to use it¶
- Use the atlases to ask which genes the regulatory elements a variant overlaps are predicted to regulate, in the biosamples or cell types whose files you import.
- Use them for predictions Open Targets E2G leaves out: ENCODE-rE2G links scored below Open Targets' 0.6 cutoff, and scE2G predictions from single-cell data.
- Choose Open Targets E2G for ENCODE-rE2G links across 1,439 biosamples with no import step:
it reads a published copy in place. Both write the same columns, and
column_prefixputs them side by side. - Choose Genomic regions for the nearest genes. A nearest gene is a distance, not a predicted target.
- A link predicts that an element regulates a gene, not that the variant changes the element. Choose a model, such as ChromBPNet, to ask that.
Add it to a run¶
A run reads the links in two steps. The binding's command imports a prediction file into a SQLite link store.
The core variant_gene_links source then reads that store; a run spec names it, not e2g_atlas.
- Install the binding from a clone of the repository:
pip install -e bindings/e2g-atlas. It is not on PyPI; see Install from a source checkout. Thevariant_gene_linkssource is part of corealtar. -
Download a prediction file and import it. This fills
links.sqlitewith ENCODE's kidney rE2G file,ENCFF229GDZ(3 MB compressed, about 70,000 links): -
Add a
variant_gene_linkssection that names the store, the atlas's link dataset and a release label:
altar sources e2g_atlas names the import command, and altar sources variant_gene_links lists the options. The
run spec reference describes the [sources.<name>] section, and
Annotate variants with evidence walks through a run.
Outputs¶
The variant_gene_links source writes the core variant–gene link columns, the contract
org.kundajelab.altar.annotation.variant-gene-links, the same ones Open Targets E2G writes.
With column_prefix = "re2g", each name starts with re2g_:
| Column | Type | Meaning |
|---|---|---|
re2g_link_top_gene |
str | Ensembl gene ID of the strongest link. |
re2g_link_top_gene_symbol |
str | That gene's symbol. |
re2g_link_top_score |
float | That link's score. |
re2g_link_gene_count |
int | Number of distinct linked genes. |
re2g_link_count |
int | Number of links. |
re2g_link_genes |
list of struct | Every link, strongest first. |
Each re2g_link_genes record holds gene_id, gene_namespace, gene_symbol, score, score_direction,
biosample (the file's CellType), biosample_id, regulatory_element_id, element_type (the element's
class), source_id (encode_re2g or sce2g), source_name, method (ENCODE-rE2G or scE2G),
data_release (the import's --release), record_id, source_record_id and source_dataset.
The score is ENCODE-rE2G's Score or scE2G's E2G.Score.qnorm. The three link_top_* columns are empty when no
link has a usable score. A variant with no overlapping element has no row, so every column is empty in the export;
see Variants a lookup may miss.
The import keeps every other column of the source file in typed records, which E2GAtlasSource returns in Python;
the run spec's columns do not include them.
Configuration¶
The options of the variant_gene_links source, under [sources.<name>.options]:
| Option | Meaning |
|---|---|
sqlite_path |
Required. The SQLite link store altar-e2g-atlas-ingest filled. |
dataset |
Required. The link dataset in the store. Every import goes into { namespace = "org.kundajelab", name = "e2g-atlas", version = "1" }. |
release |
Required. A label for what the store holds; see Release and identity. |
filters |
Which links to keep; see below. |
column_prefix |
Prefix every column, such as re2g for re2g_link_top_score, to sit beside another link source such as Open Targets E2G. |
name |
Rename the source. |
genome_build |
Must be hg38, the default; the importer writes GRCh38 only. |
A dataset the store does not hold stops the run, naming the dataset and the store.
filters takes context_names, context_ids, source_ids, gene_ids, methods, data_releases,
minimum_score and maximum_score. Context names and IDs select their union; the other filters intersect. A
store that holds several imports serves all of them. To read one, filter on its release:
[sources.re2g.options]
sqlite_path = "links.sqlite"
dataset = { namespace = "org.kundajelab", name = "e2g-atlas", version = "1" }
release = "ENCFF229GDZ"
filters = { data_releases = ["ENCFF229GDZ"] }
Inputs¶
- Genome builds: hg38 only. The importer requires GRCh38 and never lifts coordinates over.
- Variant classes: every class. A variant is looked up at the reference span of its minimal representation. An indel's span includes its anchor base.
- Chromosomes: a variant on a chromosome the link store does not name, such as an unplaced contig, has no row.
- Files: ENCODE-rE2G files with the
ENCFF229GDZheader, and scE2G v1.3 multiome output. The importer refuses other schemas (Where it comes from).
Where it comes from¶
- ENCODE-rE2G: the ENCODE portal publishes one file per biosample, in its
thresholded element gene linksBED3+ format, under anENCFF…accession. The importer accepts the header ofENCFF229GDZ. Two accessions that Open Targets ingests,ENCFF094BVFandENCFF269DKY, have other headers, and the importer refuses them. - scE2G: the scE2G repository at tag
v1.3(commit754ce2af985d201cf1a2e3e692aed09d233a16f1) defines the output you produce or obtain. The importer accepts the exact v1.3 multiome prediction header and refuses renamed, reordered, extra or missing columns. ATAC-only output is not supported.
Record each file's accession or tag, URL and checksum when you download it. Altar publishes no copy of either atlas.
Release and identity¶
The source's identity is the org.kundajelab.altar.annotation.variant-gene-links contract, version 1.0.0, with
the release option as its release and hg38 as its build. With filters, the release becomes
<release>+<fingerprint of the filters>. A run records it in its provenance.
The store does not record a release for the source. release is a label that must change whenever the store's
links change.
Each import is identified by its settings and the input file's SHA-256:
- importing the same file with the same settings again does nothing, and the report says
"idempotent": true; - an interrupted import resumes after its last complete batch;
- an incomplete import is hidden from queries;
- a new accession, release tag, checksum or setting adds a release next to the old one rather than replacing it.
Build another release¶
Each import adds one file to the store:
altar-e2g-atlas-ingest --input predictions.tsv.gz --database atlas.sqlite \
--source sce2g --release v1.3 --model multiome_powerlaw_v3 \
--gene-namespace-version 'GENCODE v43' \
--context-name 'T cell cluster 1' --context-id CL:0000084 --context-namespace CL \
--score-threshold 0.177 --threshold-applied \
--threshold-interpretation 'v1.3 multiome_powerlaw_v3 inclusive model cutoff'
| Option | Meaning |
|---|---|
--input, --database |
The prediction file and the SQLite store to import into; required |
--source |
encode_re2g or sce2g; required |
--release |
The file's release: an ENCODE file accession such as ENCFF229GDZ, or the scE2G tag v1.3; required |
--model |
The model that produced the file, from your acquisition record; required. The ENCODE file does not name it |
--context-name |
The biosample. It must equal every row's CellType; a row that differs is rejected |
--context-id, --context-namespace |
An ontology term for the biosample, such as CL:0000084 in CL. --context-id needs --context-name, and --context-namespace needs --context-id |
--gene-namespace-version |
The gene annotation release, such as GENCODE v43 |
--score-threshold, --threshold-applied, --threshold-interpretation |
The model's cutoff, whether the file was already filtered by it, and a note. Altar records them and applies no cutoff |
--source-uri |
Where the file came from |
--expected-sha256 |
Refuse the file unless its SHA-256 matches |
--batch-size |
Rows per committed batch (default 10,000) |
The importer has no --overwrite: imports add to the store. It prints a JSON report with the import ID, the
file's SHA-256, the processed, accepted and rejected row counts, the status and idempotent.
The importer requires GRCh38, Ensembl gene IDs and element IDs whose coordinates match the row. It stores
intervals as 0-based, half-open. It splits a gene version suffix such as .5 from the ID and keeps it. A rejected
row keeps its row number and the reason.
Compute and scale¶
- A lookup runs no model and needs no GPU.
- The
variant_gene_linkssource runs one SQLite query per variant. That suits cohorts of up to some tens of thousands of variants. - For larger cohorts, write the links as a Parquet link dataset and read it, or a BigQuery table loaded from it (Python and extension).
- One ENCODE-rE2G file is small:
ENCFF229GDZis 3 MB compressed and holds about 70,000 links.
Prioritization¶
A spec-declared variant_gene_links source annotates only; it never sets prioritized. Build the source in code
with prioritize_predicate to prioritize on its columns, such as re2g_link_top_score.
What prioritized means explains how rules combine.
Altar applies no global cutoff:
- ENCODE-rE2G's
Scoreis a 0–1 logistic-regression confidence. ENCODE marks these files as thresholded, but neither the file nor its metadata gives the cutoff. Record it from the model's documentation with--score-threshold. - scE2G's
E2G.Score.qnormis quantile-normalized to the model's reference. The v1.3 repository ships inclusive cutoffs per model: 0.173 (multiome megamap v3), 0.177 (multiome power-law v3), 0.187 (scATAC megamap v3) and 0.174 (scATAC power-law v3). - Open Targets keeps ENCODE-rE2G links with a score of at least 0.6 when it ingests them. That is Open Targets' choice, and this importer does not apply it.
Validation¶
Validation label: Not spot-checked. The importer checks each file's header against the published ENCODE-rE2G and
scE2G v1.3 headers, and each row's build, gene ID and element coordinates. It records the file's SHA-256, and
--expected-sha256 refuses a file with another digest. The binding's test fixtures are synthetic rows with the
published headers.
Not validated:
- links looked up in an imported store compared with the rows of the source file for named variants;
- reading a BigQuery table of links on live BigQuery, which is Preview.
Limits¶
- GRCh38 only. The importer never lifts coordinates over.
- ENCODE-rE2G DCC files with the
ENCFF229GDZheader, and scE2G v1.3 multiome output. Other schemas, and scE2G ATAC-only output, are refused. - The upstream files carry no ontology IDs, annotation release, checksum or numeric cutoff. Those come from the import options and are kept apart from the source rows.
- The store records no release for the source: the
releaselabel is yours to change when the links change. - A link is a predicted regulatory relation, not evidence that the variant changes the element's activity.
Cite and licence¶
Cite ENCODE-rE2G for ENCODE files, and scE2G for scE2G output:
@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}
}
@article{sheth2026sce2g,
author = {Sheth, Maya U. and Qiu, Wei-Lin and Ma, X. Rosa and Gschwind, Andreas R. and Jagoda, Evelyn and
Tan, Anthony S. and Galante, James and Ray, Judhajeet and Amgalan, Dulguun and Einarsson, Hj{\"o}rleifur and
Gorissen, Bram L. and Dubocanin, Danilo and McGinnis, Christopher S. and Huang, Jacob and Munson, Glen and
Brand, Kayla and Satpathy, Ansuman T. and Jones, Thouis R. and Steinmetz, Lars M. and Kundaje, Anshul and
Ustun, Berk and Engreitz, Jesse M. and Andersson, Robin},
title = {Mapping enhancer--gene regulatory interactions from single-cell data},
journal = {Nature Genetics},
volume = {58},
number = {8},
pages = {1941--1952},
year = {2026},
doi = {10.1038/s41588-026-02695-8}
}
For ENCODE files, follow citing ENCODE: cite the Consortium's
integrative analysis and its portal papers, acknowledge the ENCODE Consortium and the producing laboratory, and
list the ENCFF… accessions you used.
@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}
}
- ENCODE data: ENCODE's data-use policy places no restrictions on downloading, analysing and publishing released data.
- ENCODE-rE2G code: the ENCODE-rE2G repository has no licence file. The binding neither copies nor runs its code.
- scE2G: the scE2G repository's code is MIT-licensed. That licence does not state terms for prediction tables distributed elsewhere; check the terms of the files you use.
- Binding:
altar-e2g-atlasis MIT-licensed. Its test fixtures are synthetic rows with the published headers, and it ships no atlas data.
Python and extension¶
E2GAtlasSource queries the links in any VariantGeneLinkStore, with the typed ENCODE-rE2G or scE2G features of
each row. AtlasIngestor imports into any store; the Python API also takes expected_sha256 and returns an
ImportReport with RejectedRow values. Altar's InMemoryVariantGeneLinkStore and SqliteVariantGeneLinkStore
serve both; see Variant-to-gene links.
VariantGeneLinkAnnotationSource.from_sqlite builds the run spec's source in code, and takes a
prioritize_predicate. For large cohorts, write the links as a Parquet link dataset with write_link_dataset and
read it with VariantGeneLinkAnnotationSource.from_dataset, or from a BigQuery table loaded from it with
from_bigquery_table. The Parquet link dataset, its writer and from_dataset are provisional. The BigQuery backend
is Preview: tested on the BigQuery emulator and DuckDB; not run against live BigQuery. See Run at warehouse scale on
BigQuery.