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

  1. Define semantic lookups
    Use omop-semantics to define which concepts represent staging, grading, laterality, etc.

  2. Build constructs
    Use SQLAlchemy and omop-alchemy models to define reusable queries and derived views.

  3. Materialize or compose
    Optionally materialize complex constructs into views or tables for performance.

  4. 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

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.7.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for gkennos from gravatar.com gkennos

Credits

Author: Georgie Kennedy

Requires

Python >=3.12

Provides Extra

dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

omop_constructs-0.5.1.tar.gz (40.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

omop_constructs-0.5.1-py3-none-any.whl (73.0 kB view details)

Uploaded Python 3

File details

Details for the file omop_constructs-0.5.1.tar.gz.

File metadata

  • Download URL: omop_constructs-0.5.1.tar.gz
  • Upload date:
  • Size: 40.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for omop_constructs-0.5.1.tar.gz
Algorithm Hash digest
SHA256 e44c27c9aebfab488aeae688944a44ae9c90ae025302c42e9c0e02eac455b12e
MD5 7610d83347c638f120f99c7a910f87aa
BLAKE2b-256 7cc25cea1c4347dd2905d989c49acec9e40625ca0fc6b61bb56fac693702036c

See more details on using hashes here.

Provenance

The following attestation bundles were made for omop_constructs-0.5.1.tar.gz:

Publisher: py_pi.yml on AustralianCancerDataNetwork/omop-constructs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file omop_constructs-0.5.1-py3-none-any.whl.

File metadata

  • Download URL: omop_constructs-0.5.1-py3-none-any.whl
  • Upload date:
  • Size: 73.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for omop_constructs-0.5.1-py3-none-any.whl
Algorithm Hash digest
SHA256 3f1e6a93314d7a31a6cf64c5ff00e0aa57fe1cca054ec86419154fb65c6ed3f1
MD5 d493e44e3e374431425a80b4bcbb899a
BLAKE2b-256 075990074f3fa36825ee991b5ebb7942743c81926c6cab8efe248fb4aba6c78f

See more details on using hashes here.

Provenance

The following attestation bundles were made for omop_constructs-0.5.1-py3-none-any.whl:

Publisher: py_pi.yml on AustralianCancerDataNetwork/omop-constructs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.7.0

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

This release

0.5.1 This release

2 files

0.5.0

2 files

0.4.10

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.24

2 files

0.3.23

2 files

0.3.22

2 files

0.3.21

2 files

0.3.20

2 files

0.3.19

2 files

0.3.18

2 files

0.3.17

2 files

0.3.16

2 files

0.3.15

2 files

0.3.14

2 files

0.3.13

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.17

2 files

0.2.16

2 files

0.2.15

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page