Genes

Gene identity is the least interesting part of a result and the easiest place to lose one. A symbol is a name humans gave a gene; names are changed, retired and occasionally reused for something else. An Ensembl stable identifier is not.

So: the identifier is primary, and the symbol travels beside it. A result file's gene axis is indexed by Ensembl stable gene identifier, and the symbol is a column next to it.

Part	Contract
Format	h5ad
Gene axis index	ensembl_gene_id
Gene axis columns	feature_name, hgnc_id, biotype, measured_in_training, n_train_datasets, model_token
Extra matrices	bulk_calibrated, image_only
Provenance keys	model, input_spec, job

Identifiers are stored unversioned — ENSG00000141510, not ENSG00000141510.16 — so a table carrying one version joins the same gene as a reference carrying another.

The table is the pin

One versioned table maps every symbol the model can predict to an identifier. It is built from the HGNC complete set and one pinned Ensembl release, and it is committed with the checksum of each source file it was built from — because a table rebuilt from "the current release" is a different table, and a result you cannot re-map is a result you cannot compare.

Fact	Value
Symbols on the axis	19,338
Ensembl release	116
Built from sources fetched	2026-09-05

Source	sha256 of the file it was built from
hgnc_complete_set	6f43d6ff43aa9fdfa5fb2f20a20a7cace66e6e02e2a0dcf19d9b726e2e248d20
ensembl_gtf_116	ed992f0eac7197d9627bda618f8f831ba355c95bd5d0796af785387d462828b6

How each symbol was resolved

Most symbols match the current HGNC symbol directly. The rest are exactly the cases that make symbol-keyed data quietly wrong, and every one of them is recorded rather than resolved on the fly:

Resolved by	Symbols	Meaning
symbol	19,166	the current HGNC symbol matched directly
prev_symbol	103	the name is a previous HGNC symbol for the gene
ensembl_name	65	no HGNC match; a gene of that name in the pinned Ensembl release
curated	3	resolved by hand, with the reason recorded on the row
alias_symbol	1	the name is a recorded HGNC alias

Nothing is dropped

A symbol the model predicts always keeps its row, even when no identifier could be sourced for it. A missing row would be an absence you had to notice; a row with an empty identifier is one you can see.

Symbol	Why it has no identifier
IQCA1	no HGNC record and no gene named IQCA1 in Ensembl 116; the model predicts it, so the row stays and the id is unknown
IQCD	no HGNC record and no gene named IQCD in Ensembl 116; the model predicts it, so the row stays and the id is unknown

4 further symbols carry an identifier from HGNC that the pinned Ensembl release no longer lists: PAXX, PRY, PRY2, SMIM2. They keep their row and their identifier.

Asking for particular genes

You may name the genes you want back, as identifiers or as symbols. Symbols are resolved through this table, so a previous symbol or a recorded alias works. Two failures are reported rather than guessed at:

• a name that is not in the table at all — gene_unknown;
• a name that resolves to more than one gene — gene_ambiguous.

Send the identifier when you know it. It is the one form that cannot be ambiguous.

Predicted is not measured

The gene axis carries columns saying whether each gene was measured in the training data and in how many datasets. A gene the model never saw measured still has a column in the output, because the output axis is fixed — and it is marked, because a prediction for a gene with no training signal is not the same kind of number as one with it.