> For the complete documentation index, see [llms.txt](https://docs.mithrl.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mithrl.com/guides/gene-symbol-resolution.md).

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

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

```graphql
query {
  schemaSummary {
    buildPin
    geneSymbolAuthority { name version }
    geneAccessionVintage { name version }
  }
}
```

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