key: hgnc
name: HGNC gene symbols
description: Approved HUGO Gene Nomenclature Committee gene symbols.
# Gene symbols have no strict shape, so pattern mode is only a loose token check
# using ASCII classes so R and Python agree. Existence is checked in cache mode
# against the approved-symbol snapshot; a withdrawn or previous symbol resolves
# to its approved successor through the snapshot's retired-map sidecar.
pattern: "[A-Za-z0-9][A-Za-z0-9._@-]*"
example: 'TP53'
species_aware: false
version_aware: true
# Cache mode reads the bundled approved-symbol snapshot. biobouncer.pull() refreshes
# it from a dated HGNC "complete set" archive through the hgnc_tsv builder; the
# version is the archive's release date.
default_version: '2026-07-07'
cache:
  builder: hgnc_tsv
  tsv_url: "https://storage.googleapis.com/public-download-files/hgnc/archive/archive/monthly/tsv/hgnc_complete_set_{version}.txt"
# Remote mode checks live existence against the genenames.org REST service. Only
# an approved symbol counts as existing; a previous or withdrawn symbol is absent
# remotely, and cache mode carries the successor map for suggestions.
remote:
  resolver: genenames
# In cache mode, a well-formed symbol that is neither approved nor a known
# In cache mode, a well-formed symbol that is neither approved nor a known
# previous symbol falls back to the nearest approved symbol within this edit
# distance, so a typo like TP52 suggests TP53.
#
# case_insensitive measures that distance between lowercase forms, so a
# difference in case costs no edits and tp53 suggests TP53. A symbol has no
# single case convention, so this cannot be a normalize rule: 263 of the 45019
# approved symbols are not all-uppercase (C9orf72), and folding case would
# corrupt them. The suggestion is always the snapshot's own spelling, so both
# c9orf72 and C9ORF72 suggest C9orf72.
#
# Without it, case silently consumes the edit budget and the suggestion is wrong
# rather than merely absent: tp53 lands 2 edits from both TP53 and CD53, and the
# tie-break picks the wrong gene, while brca1 is 4 edits from BRCA1 and out of
# reach entirely. Lowercase symbols are common in real data, so this is the
# normal case, not an edge case.
suggest:
  case_insensitive: true
  fuzzy:
    max_distance: 2
provenance:
  pattern_source: hgnc
  homepage: https://www.genenames.org
