Skip to content

Pick a flavor

Warning

Preview of the next release (branch beta), not of the version on PyPI. The released version is documented here. To try the preview: pip install --pre dzdomop when a release candidate is out, or install the branch:

pip install "dzdomop @ git+https://github.com/DZD-eV-Diabetes-Research/dzd-omop-cdm-python-models@beta#subdirectory=packages/dzdomop"

Every CDM version (5.3, 5.4, 5.5) comes in four flavors. They describe the same tables and columns. They differ in how you write Python code against them.

Flavor Module You get Extra Pick it when
declarative omopmodel.OMOP_5_4_declarative ORM classes (Person, Concept, ...) on a SQLAlchemy DeclarativeBase none you use the SQLAlchemy ORM. The default choice
dataclasses omopmodel.OMOP_5_4_dataclasses the same classes as Python dataclasses (MappedAsDataclass): generated __init__, __repr__, __eq__ none you want the constructor to require the NOT NULL columns
sqlmodels omopmodel.OMOP_5_4_sqlmodels SQLModel classes, also Pydantic models sqlmodel you use FastAPI or Pydantic, or want model_validate()
tables omopmodel.OMOP_5_4_tables no classes, only Table objects (person, concept, ...) none you write SQLAlchemy Core queries or only need the schema

Swap 5_4 for 5_3 or 5_5 to get another CDM version.

What every module has

Name What it is
metadata the SQLAlchemy MetaData with all tables. omop.metadata.create_all(engine) creates them
Base the base class of all classes in the module (not in tables)
CDM_VERSION the CDM version, e.g. "5.4"
CDM_RELEASE the upstream release the module is generated from, e.g. "v5.5.0" (also for 5.3 and 5.4)
__all__ every public name: the classes (or tables), Base, metadata and the two constants

Each module has its own metadata, so you can import several versions into one process.

tables

The variables are named like the tables. The OMOP table metadata is metadata_table, so it doesn't hide the MetaData object.

from sqlalchemy import create_engine, insert, select

from omopmodel import OMOP_5_4_tables as omop

engine = create_engine("sqlite:///tables.db")
omop.metadata.create_all(engine)

with engine.begin() as conn:
    conn.execute(insert(omop.care_site).values(care_site_id=1, care_site_name="St. Local"))
    print(conn.execute(select(omop.care_site.c.care_site_name)).scalar_one())

Note

Some OMOP tables have no primary key upstream (e.g. death, concept_ancestor). create_all() creates them without one in every flavor, like the official DDL. See the FAQ.

dataclasses

from omopmodel import OMOP_5_4_dataclasses as omop

care_site = omop.CareSite(care_site_id=1, care_site_name="St. Local")
person = omop.Person(
    person_id=1,
    gender_concept_id=8507,
    year_of_birth=1985,
    race_concept_id=0,
    ethnicity_concept_id=0,
)
person.care_site = care_site

print(person.month_of_birth, person.measurements, person.care_site.care_site_name)
None [] St. Local

Constructor rules:

Argument Rule
NOT NULL columns (person_id, year_of_birth, ...) required
nullable columns (month_of_birth, care_site_id, ...) optional, default None
lists (measurements, visit_occurrences, ...) optional, default []
single objects (care_site, gender_concept, death, ...) not accepted. Set them after creating the object, or pass the id (care_site_id=1)

Arguments also work by position (NOT NULL columns first, in table order), but keywords are easier to read.

sqlmodels

Needs pip install "dzdomop[sqlmodel]".

from sqlalchemy import create_engine
from sqlmodel import Session, select

from omopmodel import OMOP_5_4_sqlmodels as omop

engine = create_engine("sqlite:///sqlmodels.db")
omop.metadata.create_all(engine)  # the module's metadata, not SQLModel.metadata

with Session(engine) as session:
    session.add(omop.CareSite(care_site_id=1, care_site_name="St. Local"))
    session.commit()
    print(session.exec(select(omop.CareSite)).one().care_site_name)

Warning

SQLModel.metadata.create_all(engine) creates no OMOP tables, and raises no error. The classes derive from omop.Base (a SQLModel subclass) with its own metadata. Always use omop.metadata. Derive your own tables from omop.Base if they have a foreign key to an OMOP table.

Person(...) doesn't validate anything, like in the other flavors. Use Person.model_validate({...}) for that, see Validation.

Next: Relationships