Vocabulary¶

OMOP mappings (VocabMap("SNOMED") etc.) resolve source codes against the OMOP Athena vocabulary tables. You need to download those once and upload the zip to the orchestrator.

What the bundle must contain¶

The Synthmas mappings exercise these vocabularies:

Vocabulary	Used by
SNOMED	conditions, procedures, allergies, devices
LOINC	observations (clinical step), measurements
RxNorm	drug_exposure
CVX	drug_exposure (immunizations)

You can include more (LOINC Component Hierarchy, ATC, etc.) without hurting — the engine indexes the whole vocab on load and unused entries just sit there.

Required tables inside the Athena zip:

CONCEPT.csv
CONCEPT_RELATIONSHIP.csv
CONCEPT_ANCESTOR.csv
CONCEPT_SYNONYM.csv
CONCEPT_CLASS.csv
VOCABULARY.csv
RELATIONSHIP.csv
DOMAIN.csv
DRUG_STRENGTH.csv

These are exactly the file set the engine's vocabulary_loader expects (filename prefix vocabulary_download_v5_*.zip).

How to download¶

Create an account on https://athena.ohdsi.org/.
Download → tick the vocabularies above → start the download.
Athena emails you when the bundle is ready (usually within an hour).
Click the email link, save the resulting .zip (typically named vocabulary_download_v5_<date>_<id>.zip).

Total uncompressed size: ~3.3 GB; compressed ~600 MB. The orchestrator keeps it as a single blob and never re-extracts at runtime.

Upload¶

In the UI: Pipelines → Synthmas → Configure → Vocabulary → upload the zip. Give it a version string (the Athena release date works: v5_2026-01-15). The orchestrator computes a content hash and won't re-extract if the same content is uploaded again.

Notes:

The vocab is pipeline-scoped — once uploaded, every env using this pipeline shares it. Switch vocab by uploading a new version; envs see the change on their next pre-automation run.
Loading time into the postgres CDM is ~10 minutes for the full Athena bundle on a modest box; the CSV CDM path doesn't load into a database — it serves the vocab files directly from disk.

→ Next: Source data.