Athena and Usagi¶
Two tools, one workflow. Athena is where you get the vocabularies and look concepts up. Usagi is where you build mappings for the codes the vocabularies do not cover.
Athena¶
Athena is the OHDSI vocabulary service. It does two jobs.
It serves the vocabulary download. You select which vocabularies you need, and it packages CSV files for loading into your OMOP CDM's vocabulary tables. Some vocabularies require you to hold your own license, notably CPT4, and Athena handles that with a post-download step rather than distributing licensed content.
It is a browsable lookup. For any code you can find the concept, its domain, its standard status, its class, its validity dates, its synonyms, its relationships, and its position in the hierarchy.
Reading an Athena page¶
When you look up a concept, five things answer most questions:
| Field | The question it answers |
|---|---|
| Domain | Which table does this belong in |
| Standard concept | Can this go in a _concept_id column |
| Vocabulary | Which terminology is this from |
| Concept class | How granular is it |
| Validity and invalid reason | Is this still current |
Then look at relationships. Maps to is the translation. Maps to value appears for codes that carry a result rather than a finding and tells you the value concept. Concept replaced by appears on deprecated concepts.
A practical habit¶
When you start a project, look up twenty of your highest-volume source codes by hand before writing any transformation code. Not to build the mapping, but to develop a feel for how your source's coding practice interacts with the vocabularies. You will find surprises, and finding them in week one is much cheaper than finding them in integration testing.
For R. Alvarez's bundle, that exercise would surface the family history routing immediately, which is the kind of discovery that changes a pipeline design rather than patching it.
Vocabulary versions¶
The vocabulary is versioned and it changes. Concepts get added, deprecated, and remapped.
Three rules that prevent a lot of pain:
Record your version. CDM_SOURCE has a field for vocabulary version. Fill it in. An instance whose vocabulary version is unknown cannot be reliably compared to another instance or reproduced later.
Treat an upgrade as a remapping event. Upgrading the vocabulary can change what a source code maps to. If you upgrade without re-running the mapping, your instance contains a mixture of old and new mappings with no marker. Plan upgrades as a full remap, and diff the results.
Use the same version across a network study. If you are participating in a multi-site study, the coordinating center will usually specify a vocabulary version. Different versions across sites reintroduce exactly the incomparability the OMOP CDM exists to eliminate.
Usagi¶
Usagi is a desktop application for building mappings from source codes to standard concepts. It exists because the automated Maps to path covers the standard vocabularies and not your institution's local codes, and local codes are where the hard work is.
How it works¶
You give Usagi a file of source codes with descriptions and frequencies. It uses term similarity to propose candidate standard concepts for each. You review each proposal and accept, reject, or replace it. The output is a mapping file you load into SOURCE_TO_CONCEPT_MAP.
The important thing about Usagi is that it is a review tool, not an automation tool. The proposals are a starting point that a human with clinical knowledge evaluates. A mapping accepted without review is worse than no mapping, because it creates confident wrong answers rather than visible gaps.
Ordering the work¶
Include frequency counts in your input file and work in descending frequency order. Local code sets follow a steep distribution: a small number of codes account for most of the volume. Mapping the top fifty codes usually moves your unmapped rate more than mapping the next five hundred.
Then stop and reassess. The long tail is often local administrative codes, retired codes with no current use, and one-off entries. Some of that tail should be mapped and much of it should not, and the judgment about which is which is clinical rather than technical.
Who should do it¶
Not the ETL engineer alone. A mapping decision like "this local nursing frailty scale corresponds to this standard frailty concept" is a clinical judgment with research consequences. The workable pattern is that the engineer prepares the candidates and manages the tooling, and a clinician or clinical informaticist reviews and signs off, with the reasoning recorded.
For rare disease work in particular, involve someone who knows the condition. The vocabulary coverage for rare conditions is genuinely uneven, and someone who knows the clinical area will spot both a wrong mapping and a missing one that a general reviewer will not.
Recording the reasoning¶
For each non-trivial local mapping, record four things somewhere durable:
- The source code and its local meaning, in words
- The standard concept chosen and why
- What was considered and rejected
- A confidence marker: close equivalent, approximate, or best available
That fourth item earns its keep. An analyst who knows a mapping is approximate can decide whether it is fit for their question. An analyst who cannot tell approximate from exact will treat everything as exact.
The other tools you will meet¶
Brief orientation, because these names come up constantly and nobody explains them.
| Tool | What it is for |
|---|---|
| White Rabbit | Scans a source database and produces a profile of its tables, fields, and value distributions. Useful for a relational source; less so for FHIR NDJSON, though it can profile staged tables |
| Rabbit in a Hat | Reads a White Rabbit scan and lets you draw the source-to-OMOP CDM mapping visually, producing an ETL specification document |
| Data Quality Dashboard | Runs a large library of systematic quality checks against a loaded OMOP CDM instance and reports pass and fail by check |
| Achilles | Characterizes an OMOP CDM instance, producing descriptive statistics and distributions used for both quality review and data set description |
| ATLAS | Web application for building concept sets, defining cohorts, and running characterization and estimation studies |
| HADES | The R package suite implementing OHDSI analytical methods against an OMOP CDM |
For a FHIR to OMOP project specifically, the ones you will use most are Athena and Usagi during build, and Data Quality Dashboard and Achilles during validation.
Where this quietly breaks¶
Accepting Usagi proposals in bulk. The similarity scoring is a heuristic on term text. It confidently proposes wrong matches for codes with similar wording and different meaning. Review every accepted mapping.
Mapping to non-standard concepts. Usagi can be configured to propose them. Check the standard status of what you accept.
Losing the mapping file. SOURCE_TO_CONCEPT_MAP in the database is the runtime artifact. The reviewed source file, with reasoning, is the durable record. Version-control it alongside your ETL code.
Never revisiting. Vocabularies improve. A code with no standard concept in 2024 may have one now. Re-run the unmapped list against a fresh vocabulary periodically and recover what you can.
Next¶
- Patient to PERSON, where the table-by-table work begins