Skip to content

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_prefix puts 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.

  1. 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. The variant_gene_links source is part of core altar.
  2. Download a prediction file and import it. This fills links.sqlite with ENCODE's kidney rE2G file, ENCFF229GDZ (3 MB compressed, about 70,000 links):

    curl -sSfLO https://www.encodeproject.org/files/ENCFF229GDZ/@@download/ENCFF229GDZ.bed.gz
    altar-e2g-atlas-ingest --input ENCFF229GDZ.bed.gz --database links.sqlite \
      --source encode_re2g --release ENCFF229GDZ --model DNase_only --context-name "right kidney"
    
  3. Add a variant_gene_links section that names the store, the atlas's link dataset and a release label:

    [sources.re2g]
    type = "variant_gene_links"
    
    [sources.re2g.options]
    sqlite_path = "links.sqlite"
    dataset = { namespace = "org.kundajelab", name = "e2g-atlas", version = "1" }
    release = "ENCFF229GDZ"
    column_prefix = "re2g"
    

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 ENCFF229GDZ header, 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 links BED3+ format, under an ENCFF… accession. The importer accepts the header of ENCFF229GDZ. Two accessions that Open Targets ingests, ENCFF094BVF and ENCFF269DKY, have other headers, and the importer refuses them.
  • scE2G: the scE2G repository at tag v1.3 (commit 754ce2af985d201cf1a2e3e692aed09d233a16f1) 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_links source 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: ENCFF229GDZ is 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 Score is 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.qnorm is 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 ENCFF229GDZ header, 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 release label 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-atlas is 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.