omop-constructs

omop-constructs is a small library for building reusable, composable analytical constructs on top of OMOP CDM using SQLAlchemy.

It sits “above” low-level OMOP table models (from omop-alchemy) and semantic definitions (from omop-semantics), and provides a way to package up common query patterns, mappings, and derived views into reusable units.

In practice, this means you can define things like:

tumour staging logic (T/N/M, group stage),
clinical modifiers (grade, laterality, size),
condition + modifier joins,
episode-linked phenotypes,
reusable materialized views or query fragments,

and then reuse them consistently across:

analytics code,
cohort definitions,
ETL / feature engineering,
dashboards and reports.

What problem does this solve?

When working with OMOP in real research settings, you often end up re-implementing the same patterns:

joining measurements or observations back to conditions,
resolving multiple staging systems (clinical vs pathological),
preferring “best available” records (earliest, latest, ranked),
materialising complex derived tables for performance,
wiring together multiple OMOP tables into analysis-ready shapes.

These patterns are:

non-trivial SQL,
project-specific but reusable,
and easy to drift or fork across notebooks, pipelines, and services.

omop-constructs gives you a place to define these patterns once, as explicit, testable Python objects built on SQLAlchemy, and then reuse them anywhere you use OMOP.

Think of it as a library of semantic query building blocks for OMOP.

Relationship to other libraries

omop-alchemy
Provides the canonical, typed SQLAlchemy models for OMOP CDM tables.
omop-semantics
Defines which concepts, groups, and roles mean what in your domain (e.g. staging, modifiers).
omop-constructs
Uses both of the above to build higher-level analytical constructs, such as:
- derived views,
- reusable joins,
- staged phenotype tables,
- canonical query fragments.

In short:

omop-alchemy defines the schema
omop-semantics defines the meaning
omop-constructs defines the reusable analytical shapes

Core ideas

Composable query building blocks
Encapsulate common SQL patterns as reusable Python objects.
SQLAlchemy-first
Constructs are normal SQLAlchemy select() expressions, subqueries, and ORM-mapped views.
Reusable analytical units
Package complex mappings (e.g. staging logic) once and reuse them across contexts.
Materialized view support
Support for defining derived tables and materialized views for performance and stability.
Semantics-aware
Integrates with omop-semantics concept registries and lookups, rather than hard-coding concept IDs.

Example use case (high level)

A typical construct might:

take OMOP Measurement rows representing staging concepts,
classify them into T, N, M, and group stage using semantic lookups,
rank multiple records per condition to select the “best” stage,
expose the result as a materialized view that can be joined back to Condition_Occurrence.

This allows downstream code to work with a clean, analysis-ready table like:

“conditions with resolved TNM stage and modifiers”

without re-implementing the logic every time.

Typical workflow

Define semantic lookups
Use omop-semantics to define which concepts represent staging, grading, laterality, etc.
Build constructs
Use SQLAlchemy and omop-alchemy models to define reusable queries and derived views.
Materialize or compose
Optionally materialize complex constructs into views or tables for performance.
Reuse everywhere
Import the same construct into analytics notebooks, ETL jobs, or services.

Configuration and CLI

omop-constructs uses oa-configurator for runtime logging and CDM resource resolution.

omop-config init
omop-config configure omop_alchemy
omop-config configure omop_constructs

omop-config configure omop_constructs validates that a shared cdm_db resource is available and can record a package-specific default_resource override when omop-constructs should use a different CDM resource than omop-alchemy.

The package CLI exposes operational helpers such as registry schema export:

omop-constructs schema-snapshot tests/artifacts/construct_registry_schema.csv

When should you use this?

Use omop-constructs if you:

repeatedly write and share complex OMOP joins and mappings,
need consistent, reusable phenotype or feature definitions,
want complex logic to live in one place that is versionable and extensible,
are building analytics pipelines or research platforms on OMOP,
care about making your analytical layer explicit and testable.

Design goals

Declarative, explicit constructs
SQLAlchemy-native
No hidden execution or side effects
Easy to test in isolation
Compatible with materialized views and derived tables
SQLAlchemy query definitions are portable across backends
Materialized view lifecycle management targets PostgreSQL

Metadata

Release files for omop-constructs 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for omop-constructs 0.9.0
File	Size	Uploaded
omop_constructs-0.9.0.tar.gz	272.8 kB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for omop-constructs 0.9.0
File	Interpreter	ABI	Platform	Reset
omop_constructs-0.9.0-py3-none-any.whl 101.0 kB Oct 9, 2026	Python 3	none	any	Details

Total release size: 373.9 kB

Release files / omop_constructs-0.9.0.tar.gz

Download URL	omop_constructs-0.9.0.tar.gz
Size	272.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`7929765eb37cae115120195dc099efb998b8ce7e3a6001e969fb61dcf1cf73ec`
BLAKE2b-256 checksum How to use checksums	`2154f3c6d6a49f18ecc51201a8398e1df8d621ed81e5b86bab656cdb8f0d3e2c`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AustralianCancerDataNetwork/omop-constructs
Publishing commit: github.com/AustralianCancerDataNetwork/omop-constructs/tree/d3902581f9c9b767f4069671d41b07738e65b7a2

Workflow

Publishing configuration: github.com/AustralianCancerDataNetwork/omop-constructs/blob/d3902581f9c9b767f4069671d41b07738e65b7a2/.github/workflows/publish.yml
Publishing logs: github.com/AustralianCancerDataNetwork/omop-constructs/actions/runs/37922923433/attempts/1

Artifact

Subject: omop_constructs-0.9.0.tar.gz
SHA-256 checksum: 7929765eb37cae115120195dc099efb998b8ce7e3a6001e969fb61dcf1cf73ec Verifying attestations

Release files / omop_constructs-0.9.0-py3-none-any.whl

Download URL	omop_constructs-0.9.0-py3-none-any.whl
Size	101.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f29626f0f60fc0226c1b7411ceb3bd18df4910cf65044661a3062c183de99b57`
BLAKE2b-256 checksum How to use checksums	`784b815d1431af35050385759cdf4288edbce5ceb9fe768be8647ad87abdc370`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AustralianCancerDataNetwork/omop-constructs
Publishing commit: github.com/AustralianCancerDataNetwork/omop-constructs/tree/d3902581f9c9b767f4069671d41b07738e65b7a2

Workflow

Publishing configuration: github.com/AustralianCancerDataNetwork/omop-constructs/blob/d3902581f9c9b767f4069671d41b07738e65b7a2/.github/workflows/publish.yml
Publishing logs: github.com/AustralianCancerDataNetwork/omop-constructs/actions/runs/37922923433/attempts/1

Artifact

Subject: omop_constructs-0.9.0-py3-none-any.whl
SHA-256 checksum: f29626f0f60fc0226c1b7411ceb3bd18df4910cf65044661a3062c183de99b57 Verifying attestations