API Reference¶
This section documents the core authoring primitives used to define OMOP CDM models in OMOP Alchemy.
These APIs are intentionally low-level, explicit, and composable. They are designed for model authors, not end-users or analysts.
If you are:
- defining new OMOP CDM tables or views
- extending the model surface
- encoding structural or semantic conventions
- building derived or analytical layers
…this is the layer you will work with most directly.
| Section | Purpose |
|---|---|
| Base tables | Core base classes and inheritance structure |
| Columns | Reusable column helpers and FK patterns |
| Mixins | Structural mixins encoding OMOP table semantics |
| Typing | Protocols for static typing and semantic contracts |
The APIs documented here follow a few consistent principles:
-
No hidden behavior
Nothing creates engines, sessions, or tables implicitly. -
Declarative first
Structure and intent should be visible directly on the model class. -
Structural, not analytical
These tools encode what a table is, not how it is used. -
Safe to import anywhere
All modules are import-safe and side-effect free.
This makes the API suitable for: - schema inspection - validation tooling - static analysis - documentation generation - interactive exploration
Architecture¶
Layered architecture specification is described in Architecture
Base table infrastructure¶
At the core of OMOP Alchemy is a small number of base classes that define what it means to be a CDM table.
These classes integrate with lower-level infrastructure (i.e.
orm-loader) but remain OMOP-specific.
Column helpers¶
OMOP CDM tables repeat a number of column patterns: concept foreign keys, nullable vs required fields, source attribution, etc.
Column helpers provide named, intention-revealing shortcuts for these patterns.
Structural mixins¶
Many OMOP tables share structural semantics:
- person-scoped records
- dated events
- value-typed observations
- unit concepts
- health system attribution
Mixins encode these patterns once, and make them reusable and inspectable.
Typing and semantic contracts¶
OMOP Alchemy makes heavy use of Python typing to express semantic expectations:
- “this object has a concept_id”
- “this table participates in domain validation”
- “this is a clinical event”
These protocols support: - static type checking - IDE assistance - tooling and validation layers
Relationship to other layers¶
This API layer sits above generic ORM infrastructure and below analytical or validation tooling.
| Layer | Responsibility |
|---|---|
| Database | Physical storage, constraints |
| orm-loader | Generic table loading, serialization |
| OMOP Alchemy API | OMOP-specific structure & semantics |
| Validation | Domain and semantic checks |
| Analytics | Queries, cohorts, exploration |