Hi everyone,
I’d like to introduce the Custom Vocabulary Browser , a small open-source tool that grew out of our work in the OHDSI GIS Working Group.
The idea was inspired by discussions with Dr. Andrew Williams, whose contribution to this work we remember with gratitude. Those discussions, in the context of the GIS toolchain, highlighted a practical need: when a project introduces OMOP-compatible concepts that are maintained outside the standard Athena distribution, there should still be a simple, transparent way to find, inspect, review, and understand those concepts, while preserving stable, persistent identifiers that can be referenced consistently across datasets, analyses, and tools.
Although GIS was the original use case, the problem is much broader. Custom concepts may represent local instruments, research-specific measurements or observations, source-system extensions, provisional vocabulary content, or other concepts that are not yet - and may never be - distributed through Athena. The browser therefore has no GIS-specific dependency and can be used with any compatible custom vocabulary.
What does it do?
The browser provides an Athena-inspired interface for custom OMOP concepts. You can search by:
concept_idconcept_codeconcept_namesynonyms
The search is not just a literal string lookup. Text is normalized before matching, and the browser supports exact, prefix, token, and bounded fuzzy matching for names and synonyms, while IDs and codes remain deterministic exact/structured searches. Results use deterministic ranking and can be filtered by vocabulary, domain, concept class, standard concept status, and validity.
Opening a concept allows you to inspect its core OMOP attributes together with:
- synonyms
- incoming and outgoing relationships
- relationships to standard concepts outside the loaded package
- source/package/file provenance
- ancestors and descendants when hierarchy data are available (TBD).
How does it work?
It is deliberately lightweight: the browser is a static web application and does not require an application server or database.
A vocabulary can currently be loaded in three ways:
- from the vocabulary snapshot bundled with the browser
- directly from a compatible public GitHub repository
- from a local folder containing OMOP-compatible CSV files
For local files, the data are processed entirely in browser memory and are not uploaded anywhere.
At minimum, a package contains the familiar OMOP structures for concepts, synonyms, and relationships (concept_delta.csv , concept_synonym_delta.csv , and concept_relationship_delta.csv ). Additional tables can provide hierarchy and vocabulary metadata. This means the browser is not tied to one custom vocabulary or one project - another compatible vocabulary package can simply be loaded and explored.
Current status
The browser is already functional and available here:
Browser: Custom Vocabulary Browser
Repository: GitHub - p-talapova/CustomVocabularyBrowser · GitHub
This is still an early version, with several enhancements planned, including a more refined UI, improved visualization and navigation of concept ancestry, support for larger vocabulary packages, richer metadata presentation, and cross-vocabulary search across multiple custom vocabularies at once. Feedback and use cases from the community would be very welcome and will help determine where development should go next.
The repository currently lives under my personal GitHub account. Since the tool was developed for the OHDSI ecosystem and is intended to support any OHDSI project working with custom concepts , I am also asking for permission to transfer the existing repository into the OHDSI GitHub organization . A repository transfer, rather than recreating the project, would preserve its Git history and project metadata while giving it a more appropriate community home.
I’d be particularly interested to hear from anyone already maintaining custom OMOP concepts: what would you want to see in a browser like this?