OMOP policy¶
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:
Every OMOP-specific choice of the generator is plain data in
omop_policy.py. The generator subclasses in generate.py apply it to
every flavor, so the flavors can't drift apart. Everything else is sqlacodegen's default.
from omop_codegen import omop_policy as policy
print(policy.NO_REVERSE_RELATIONSHIPS)
print(policy.SELF_REFERENCE_REVERSE_RELATIONSHIPS)
print(policy.TABLE_VARIABLE_NAMES)
print(policy.DDL_PATCHES)
for version, keys in policy.CANDIDATE_KEYS.items():
print(version, sorted(keys))
| Setting | Shape | Effect |
|---|---|---|
NO_REVERSE_RELATIONSHIPS |
{target table: frozenset({"source_table.fk_column", ...})} |
No list attributes on the target table, except for the foreign keys listed |
SELF_REFERENCE_REVERSE_RELATIONSHIPS |
bool |
False: no <name>_reverse lists for self-references |
TABLE_VARIABLE_NAMES |
{table: variable name} |
Variable names in the tables flavor |
CANDIDATE_KEYS |
{cdm version: {table: (column, ...)}} |
Primary key on the Python side for tables without one |
DDL_PATCHES |
{cdm version: {ddl part: (sql, ...)}} |
SQL that runs after one part of the official DDL |
After a change: regenerate, then run the tests and review the baseline diff.
Relationships¶
| Kind | Named after | Example |
|---|---|---|
| many-to-one, and the side of a one-to-one that holds the foreign key | the foreign key column without _id |
Person.gender_concept, FactRelationship.domain_concept_1, Death.person |
| one-to-many (list) | the plural of the table that holds the foreign key | Person.visit_occurrences, CareSite.persons |
| the other side of a one-to-one | the table that holds the foreign key | Person.death |
The plural adds es after s, x, ch and sh, otherwise s:
from omop_codegen.generate import pluralize
print(pluralize("person"), pluralize("concept_class")) # persons concept_classes
A name that clashes with another one gets a trailing _, then a number
(ConceptRelationship.relationship_, because relationship is taken). There's no setting
for single names: to rename one relationship, extend generate_relationship_name() in
generate.py.
Drop or keep list attributes. Concept is the target of about 120 foreign keys
(gender_concept_id, unit_concept_id, ...). A list for each one would bury its useful
attributes, so it only gets Concept.concept_classes:
NO_REVERSE_RELATIONSHIPS: dict[str, frozenset[str]] = {
"concept": frozenset({"concept_class.concept_class_concept_id"}), # Concept.concept_classes
}
Add a table with an empty frozenset() to drop all of its lists. A composite foreign key
is written as "table.col_a,col_b". The many-to-one side (Person.gender_concept) is always
generated.
Self-references (visit_occurrence.preceding_visit_occurrence_id, ...) get only the
many-to-one side. Set SELF_REFERENCE_REVERSE_RELATIONSHIPS = True to also get sqlacodegen's
<name>_reverse lists.
Names in the tables flavor¶
The variables are named after the tables (person, visit_occurrence). The OMOP table
metadata would overwrite the module's MetaData object, so TABLE_VARIABLE_NAMES renames
it to metadata_table.
Candidate keys¶
SQLAlchemy's ORM can't map a class without a primary key. Some OMOP tables have none
(death, concept_ancestor, ...). In 5.5, vocabulary has a UNIQUE on a nullable column
instead. Each of them gets a candidate key per CDM version:
from omop_codegen.omop_policy import CANDIDATE_KEYS
from omopmodel.OMOP_5_5_declarative import Death
print(CANDIDATE_KEYS["5.5"]["death"]) # ('person_id',)
print(Death.__mapper_args__) # {'primary_key': ['person_id']}
| What happens | Where |
|---|---|
| The key columns become NOT NULL | every flavor |
| The table gets no primary key, like the official DDL | every flavor |
The class gets __mapper_args__ = {"primary_key": [...]} |
declarative, dataclasses, sqlmodels |
mark_candidate_keys() adds the key as a temporary primary key, so sqlacodegen makes a class
instead of a plain Table. OmopGeneratorMixin.generate_models() removes it again before
rendering.
Every version in CDM_VERSIONS needs an entry in CANDIDATE_KEYS, even an empty one. A
candidate key for a table that already has a primary key stops the run.
DDL patches¶
For upstream bugs that stop the official DDL on Postgres. A patch runs right after one
part: ddl, primary_keys, indices or constraints. @cdmDatabaseSchema becomes the
schema name. Today there is one: the 5.4 DDL has foreign keys to vocabulary, but no
primary key on it.
DDL_PATCHES: dict[str, dict[str, tuple[str, ...]]] = {
"5.4": {
"primary_keys": (
"ALTER TABLE @cdmDatabaseSchema.vocabulary"
" ADD CONSTRAINT xpk_vocabulary PRIMARY KEY (vocabulary_id);",
),
},
}
A patch for an unknown part stops the run with an error. When upstream fixes
the bug, the patch fails loudly (here: multiple primary keys for table "vocabulary"). Then
delete it.
sqlacodegen options¶
The ORM flavors run with two sqlacodegen options
(ORM_OPTIONS in generate.py). The tables flavor gets none.
| Option | Why |
|---|---|
nojoined |
death.person_id is the key of death and a foreign key to person. Without it, Death would be a joined-inheritance subclass of Person. |
nofknames |
Reverse sides are named after the table that holds the foreign key (Person.death), not after the foreign key columns |