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.4.tar.gz (40.2 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.4-py3-none-any.whl (72.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: omop_constructs-0.5.4.tar.gz
  • Upload date:
  • Size: 40.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for omop_constructs-0.5.4.tar.gz
Algorithm Hash digest
SHA256 cc33e42d3bbbd5be583f3dba35ee9f772e145ff2b003238bcf3b660a4260d34e
MD5 18ec09ed984c42f8e341ad886b4c207f
BLAKE2b-256 45f1f88fd4770007a27164b87c05159895ee8cd3f946b242e70d9a69899ca3f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for omop_constructs-0.5.4.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.4-py3-none-any.whl.

File metadata

File hashes

Hashes for omop_constructs-0.5.4-py3-none-any.whl
Algorithm Hash digest
SHA256 ed88e8d16c9bf7eeb77d10c7fca525e85d6c295182b31afb07c6a794edaaf526
MD5 d75684bbc13ba152586d4dec628ceb13
BLAKE2b-256 7326dc402f703a62330309804bbf847e2021703b8da916737e67ed972bdaf63e

See more details on using hashes here.

Provenance

The following attestation bundles were made for omop_constructs-0.5.4-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

This release

0.5.4 This release

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

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