Skip to content

Downloading a vocabulary from Athena

Rule chains in a Rabbit-in-a-Hat file that use VocabMap, VocabSourceId, or UsagiMap need a copy of the OMOP vocabulary loaded on the destination side. Vocabularies come from Athena, OHDSI's vocabulary download portal.

Rook IT can't distribute the vocabulary itself — every constituent vocabulary (UMLS, SNOMED CT, CPT-4, LOINC, RxNorm, …) has its own licence and Athena's account flow is where those terms get accepted. What we can do is tell you exactly which vocabularies your RiaH needs, and provide scripts that take it from there.

Step 1 — find out which vocabularies your RiaH needs

From the unpacked engine bundle:

./bin/check-vocabs.sh

Sample output for the bundled Synthmas RiaH:

OMOP vocabularies referenced by the RiaH:
  ✗  CVX                  MISSING — re-download from Athena with this vocab selected
  ✗  LOINC                MISSING — re-download from Athena with this vocab selected
  ✗  RxNorm               MISSING — re-download from Athena with this vocab selected
  ✗  SNOMED               MISSING — re-download from Athena with this vocab selected

Usagi files referenced by the RiaH:
  ✓  specialities.csv
  ✗  values-observation.csv  MISSING
  ...

The script scans every rule chain in your hat file for VocabMap, VocabSourceId, and UsagiMap references, and tells you which vocabularies (by Athena's short name) and which Usagi files the rules will look up at run time. Re-run it after each setup-vocab.sh to confirm the vocab you downloaded actually covers what the RiaH needs.

Step 2 — download from Athena

  1. Open https://athena.ohdsi.org/ and create an account if you don't have one (free, but required — Athena needs an account to enforce the constituent vocabulary licences).
  2. Click Download in the top navigation.
  3. Select the vocabularies the previous step listed (e.g. SNOMED, RxNorm, LOINC, CVX for the bundled Synthmas demo). Athena's UI organises them roughly by Standard / Classification / Non-standard; the search box at the top filters quickly.
  4. Click Download at the bottom of the selection list.
  5. Athena prompts you to accept the terms for each licensed vocabulary in your selection (UMLS, SNOMED, CPT-4, …). Accept only those you have rights to use.
  6. Athena queues the export and emails you a zip when it's ready — typically within a few minutes. The file is named like vocabulary_download_v5_<timestamp>.zip.

CPT-4 and other licensed code sets

If you selected CPT-4 (or another licensed-with-API code set), the download zip contains placeholders rather than real concept rows. See Troubleshooting → Athena zips with licensed code sets for the unpacking script process. You'll need a UMLS API key.

Step 3 — install the vocabulary

For a CSV CDM target (the Free-tier default):

./bin/setup-vocab.sh ~/Downloads/vocabulary_download_v5_*.zip

The script unpacks the CSV files into etc/etl-engine.d/cdm-out/, skipping any non-CSV artefacts (Athena's unpacking scripts, READMEs, etc.). The engine reads the vocab tables in place when it runs.

For an RDBMS CDM target (Paid tier), use the automation.pre.populate vocabulary setting in etl.conf instead — see automation.

Step 4 — verify

./bin/check-vocabs.sh

You should now see ✓ marks against every referenced vocabulary:

OMOP vocabularies referenced by the RiaH:
  ✓  CVX                  present
  ✓  LOINC                present
  ✓  RxNorm               present
  ✓  SNOMED               present

If anything is still ✗, re-download from Athena with the missing vocab selected, and re-run setup-vocab.sh.

Usagi files

The check script also lists Usagi files your RiaH expects. These are domain-specific source-string → concept-id mapping CSVs that you build yourself with the OHDSI Usagi tool — they aren't distributed either by Rook IT or by Athena.

If your RiaH references a Usagi file that doesn't exist yet:

  1. Open Usagi (free, separate download from Athena).
  2. Feed it the distinct source values you want to map, plus a vocabulary to map against.
  3. Curate the suggested mappings.
  4. Export to CSV, drop the file into etc/etl-engine.d/usagi/, named to match the UsagiMap("…") reference in the RiaH.
  5. Re-run ./bin/check-vocabs.sh to confirm all references resolve.

What the engine does without vocabulary

If you skip the vocabulary download entirely, the engine still runs — the vocab-lookup rules just leave their concept fields NULL (or fail the row, depending on whether you've supplied a default). The rest of the CDM populates normally. So a quick smoke test of the engine against Synthmas works without ever opening Athena; the vocabulary step is what turns a structural transformation into a clinically-meaningful one.