How chb/py-umls works
1. This repository is a small Python 3 toolkit for working with medical vocabularies from UMLS, SNOMED CT, and RxNorm. Its core model is: download official terminology releases, import them into a local SQLite 3 database, then query them through lightweight Python lookup classes.
2. The main user-facing entry points are the three scripts umls.py, snomed.py, and rxnorm.py. According to the README, each can be run directly from the shell, prompts the user to install the relevant data, and then demonstrates a simple code-to-meaning lookup.
3. The data layer is local and file-based rather than network-service based. The repository assumes each terminology is stored in a SQLite database created from the official source files. The sqlite.py module is likely the shared database access layer, while csvimporter.py appears to support bulk import of source CSV/flat files into SQLite tables.
4. The import/download workflow is split out from lookup logic. In the file tree, databases/rxnorm.sh and databases/umls.sh are shell scripts for acquiring and preparing the vocabulary datasets, while rxnorm_download.py and rxnorm_link_run.py/rxnorm_link_run.sh look like helper scripts for fetching or transforming RxNorm-specific inputs and building derived link data.
5. Each vocabulary has its own module boundary: umls.py, snomed.py, and rxnorm.py. The README says each exposes an XYLookup class, so the architecture is centered on per-terminology lookup objects with a common usage pattern, even if the underlying schemas differ.
6. There are also specialized RxNorm utilities beyond simple lookup. rxnorm_graph.py, rxnorm_link.py, and graphable.py suggest support for traversing or rendering RxNorm relationships as a graph, likely to support use cases where understanding drug ingredient/brand/relationship chains matters more than flat code lookup.
7. The repository includes tests for at least SNOMED and RxNorm: snomed_tests.py and rxnorm_tests.py. That implies the architecture is organized around validating terminology-specific database setup and lookup behavior rather than a single generic test suite.
8. Documentation is generated with Sphinx. The docs/ folder contains conf.py, index.rst, and py-umls.rst, so the project has a conventional documentation subsystem separate from runtime code. This is useful for understanding public API usage, but it is not part of the runtime data flow.
9. The external dependency boundary is important: UMLS requires a license and data download from official sources, and the repo is designed to consume those local releases rather than calling an external API at runtime. So the main runtime dependency is SQLite and locally installed terminology datasets, not a remote service.
10. Architecturally, this is best drawn as three layers: source terminology files from external vendors, an import/build layer that normalizes them into SQLite, and a lookup/utilities layer that exposes code-to-meaning queries and RxNorm graph/link helpers to downstream Python projects. The repository is intended to be embedded as a submodule or imported package in another application, not deployed as a standalone server.
Main entry points: sqlite.py SQLite layer · rxnorm.py RxNorm lookup · snomed.py SNOMED lookup · py-umls.rst API docs
Components 21
Source terminologies
External terminology releases consumed as local files.
- UMLS files · Official UMLS release files used as the local source for imports.
- SNOMED CT files · Official SNOMED CT release files used as the local source for imports.
- RxNorm files · Official RxNorm release files and derived inputs used by the toolkit.
Import and build
Scripts and helpers that download, normalize, and load terminology data into SQLite.
- UMLS setup · Shell entrypoint for acquiring and preparing UMLS data.
databases/umls.sh - RxNorm setup · Shell entrypoint for acquiring and preparing RxNorm data.
databases/rxnorm.sh - RxNorm download · Downloads or stages RxNorm inputs before database creation.
rxnorm_download.py - CSV importer · Bulk importer for source flat files into SQLite tables.
csvimporter.py - SQLite layer · Shared local database access and query helpers.
sqlite.py - RxNorm links · Builds derived RxNorm relationship/link structures.
rxnorm_link.py - Link runner · Command-line runner for the RxNorm link-building pipeline.
rxnorm_link_run.py
Lookup API
User-facing Python modules for querying terminology codes and relationships.
- UMLS lookup · User-facing UMLS lookup class and shell entrypoint.
umls.py - SNOMED lookup · User-facing SNOMED CT lookup class and shell entrypoint.
snomed.py - RxNorm lookup · User-facing RxNorm lookup class and shell entrypoint.
rxnorm.py - LOINC lookup · Additional terminology lookup module following the same local-database pattern.
loinc.py - RxNorm graph · Traversal and graph-oriented utilities for RxNorm relationships.
rxnorm_graph.py - Graphable mixin · Shared abstraction for turning terminology relationships into graph-friendly structures.
graphable.py - Package init · Top-level package entry for importing the toolkit.
__init__.py
Support
Tests and documentation around the public API.
- SNOMED tests · Behavior tests for SNOMED import and lookup flows.
snomed_tests.py - RxNorm tests · Behavior tests for RxNorm import, lookup, and link behavior.
rxnorm_tests.py - Docs index · Sphinx documentation entry point and API overview.
docs/index.rst - API docs · Generated reference page for the public Python API.
docs/py-umls.rst
Connections 26
- UMLS files → UMLS setup: prepare · UMLS releases are staged and prepared by the setup script.
- SNOMED CT files → SNOMED lookup: import · SNOMED source files are loaded into the local database used by the lookup API.
- RxNorm files → RxNorm download: fetch · RxNorm source inputs are downloaded or staged first.
- RxNorm files → RxNorm setup: prepare · RxNorm setup script coordinates local preparation of the data release.
- UMLS setup → CSV importer: load · UMLS preparation uses the CSV/flat-file importer.
- RxNorm setup → CSV importer: load · RxNorm preparation uses the CSV/flat-file importer.
- RxNorm download → CSV importer: input · Downloaded RxNorm inputs feed the import pipeline.
- CSV importer → SQLite layer: write · Importer normalizes source files into SQLite tables.
- SQLite layer → UMLS lookup: query · UMLS lookup reads from the shared SQLite database layer.
- SQLite layer → SNOMED lookup: query · SNOMED lookup reads from the shared SQLite database layer.
- SQLite layer → RxNorm lookup: query · RxNorm lookup reads from the shared SQLite database layer.
- SQLite layer → LOINC lookup: query · LOINC lookup follows the same local database access pattern.
- RxNorm lookup → RxNorm links: relationships · RxNorm lookup exposes relationship data used for graph/link building.
- RxNorm links → RxNorm graph: build graph · Derived RxNorm links are shaped into graph traversal structures.
- Graphable mixin → RxNorm graph: supports · Graph-oriented helpers provide a shared abstraction for relationship traversal.
- Link runner → RxNorm links: run · Command-line runner executes the link-building pipeline.
- Package init → UMLS lookup: export · Package root exposes the terminology APIs for importers.
- Package init → SNOMED lookup: export · Package root exposes the terminology APIs for importers.
- Package init → RxNorm lookup: export · Package root exposes the terminology APIs for importers.
- SNOMED tests → SNOMED lookup: validate · Tests exercise SNOMED lookup behavior and database setup.
- RxNorm tests → RxNorm lookup: validate · Tests exercise RxNorm lookup behavior and derived relationship handling.
- RxNorm tests → RxNorm graph: validate · Tests also cover RxNorm graph-related utilities.
- Docs index → API docs: includes · Documentation index points to the public API reference.
- API docs → UMLS lookup: documents · API docs describe the UMLS lookup entrypoint.
- API docs → SNOMED lookup: documents · API docs describe the SNOMED lookup entrypoint.
- API docs → RxNorm lookup: documents · API docs describe the RxNorm lookup entrypoint.