For the complete documentation index, see llms.txt. This page is also available as Markdown.

Resolving gene symbols

Gene symbols are not stable identifiers. They get renamed between releases of the underlying gene vocabularies, and some are retired outright. A gene expression matrix built against one release therefore carries symbols that a knowledge graph built from a different release does not recognize, and a lookup that returns nothing cannot on its own tell you whether the symbol was retired upstream or the gene is missing from the graph.

Join on Ensembl gene ids where you can. An id such as ENSEMBL:ENSG00000113161 is stable across releases, so it sidesteps the problem entirely. This is the recommended key for any symbol-keyed dataset, and it is the only approach that recovers rows whose symbols are retired.

What to expect from a symbol-keyed dataset

A human RNA-seq differential expression table of 20,774 symbols, built against a gene vocabulary several years older than the graph's, resolves like this against build v1-20260909-0cc51a-academic:

outcome
symbols
share

matched a gene by name

15,115

72.76%

matched by name or synonym

16,542

79.63%

did not match

4,232

20.37%

Around 80% is the ceiling for that dataset. Matching is case-insensitive and literal: there is no fuzzy, phonetic, or semantic fallback. Roughly 1,400 of the matches come through a synonym rather than the display name, which is how an older-but-still-current symbol resolves.

Those figures describe one dataset against one build, so treat them as the shape of the problem rather than a number to plan against. Your own resolution rate depends on which vocabulary release your data was built against.

Retired clone-style names never resolve

Most of the failures above are clone-based display names: RP11-44N21.4, AC009133.15, CTD-2369P2.8, GS1-393G12.14, RP5-1029K10.2. Earlier GENCODE releases used names of this shape for unnamed long non-coding RNAs and antisense transcripts, and later releases replaced them with stable LINC and -AS1 symbols. The clone names are gone from the upstream vocabularies, so no release of the graph carries them and no symbol conversion recovers them.

The genes themselves are almost always present under their current symbols. Reach them by their Ensembl gene ids. If a clone name is all you have, map it through the GENCODE release that minted it to get an Ensembl gene id, then query on that.

Reading the build's releases

Two different releases matter, and the build reports both.

mithrl schema --sources

The output carries notes of the form gene symbols from babel:2025sep1 and gene accessions from ensembl:113. Over the GraphQL API the same facts are:

geneSymbolAuthority is the one to read when you key on gene symbols. Most genes in the graph carry an NCBI gene id and take their display symbol from that release.

geneAccessionVintage is the Ensembl release behind the graph's ENSEMBL:ENSG... ids. It describes the accessions and does not predict display names.

Converting your symbols to match geneSymbolAuthority raises your resolution rate, but it is not a complete fix and it can cost you rows: some genes are known to the graph under a symbol that a straight conversion would replace with one the graph does not carry. Where a row matters, resolve it to an Ensembl gene id and join on that.

Last updated

Was this helpful?