omop-constructs 0.2.0__tar.gz → 0.2.2__tar.gz

{omop_constructs-0.2.0 → omop_constructs-0.2.2}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.3
 Name: omop-constructs
-Version: 0.2.0
+Version: 0.2.2
 Summary: For building complex constructs on top of the omop-alchemy library.
 Author: Georgie Kennedy
 Author-email: Georgie Kennedy <georgina.kennedy@unsw.edu.au>
-Requires-Dist: omop-alchemy==0.5.11
-Requires-Dist: omop-semantics==0.1.8
+Requires-Dist: omop-alchemy>=0.5.12
+Requires-Dist: omop-semantics>=0.1.8
+Requires-Dist: psycopg2-binary>=2.9.11
 Requires-Dist: sqlalchemy>=2.0.45
 Requires-Dist: urllib3>=2.6.3
 Requires-Python: >=3.12

{omop_constructs-0.2.0 → omop_constructs-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omop-constructs"
-version = "0.2.0"
+version = "0.2.2"
 description = "For building complex constructs on top of the omop-alchemy library."
 readme = "README.md"
 authors = [
@@ -8,10 +8,11 @@ authors = [
 ]
 requires-python = ">=3.12"
 dependencies = [
-    "omop-alchemy==0.5.11",
-    "omop-semantics==0.1.8",
+    "omop-alchemy>=0.5.12",
+    "omop-semantics>=0.1.8",
+    "psycopg2-binary>=2.9.11",
     "sqlalchemy>=2.0.45",
-    "urllib3>=2.6.3"
+    "urllib3>=2.6.3",
 ]
 
 [project.scripts]
@@ -19,4 +20,4 @@ omop-constructs = "omop_constructs.cli:main"
 
 [build-system]
 requires = ["uv_build>=0.9.2,<0.10.0"]
-build-backend = "uv_build"
+build-backend = "uv_build"

omop_constructs-0.2.2/src/omop_constructs/alchemy/episodes/condition_episode_mv.py

@@ -0,0 +1,65 @@
+import sqlalchemy as sa
+from orm_loader.helpers import Base
+from .episode_joins import overarching_disease_episode
+from ...core.materialized import MaterializedViewMixin
+from ...core.constructs import register_construct
+
+class OverarchingDiseaseEpisodeCols:
+    __table_args__ = {"extend_existing": True}
+
+    disease_episode_id = sa.Column(sa.Integer, primary_key=True)
+    person_id = sa.Column(sa.Integer)
+
+    disease_episode_concept_id = sa.Column(sa.Integer)
+    disease_episode_label = sa.Column(sa.String)
+
+    disease_episode_start_date = sa.Column(sa.Date)
+    disease_episode_end_date = sa.Column(sa.Date)
+
+    extent_episode_id = sa.Column(sa.Integer)
+    extent_episode_concept_id = sa.Column(sa.Integer)
+    extent_episode_label = sa.Column(sa.String)
+
+    extent_start_date = sa.Column(sa.Date)
+    extent_end_date = sa.Column(sa.Date)
+
+@register_construct
+class OverarchingDiseaseEpisodeMV(
+    OverarchingDiseaseEpisodeCols,
+    MaterializedViewMixin,
+    Base,
+):
+    """
+    Materialized view representing overarching disease episodes
+    with optional child disease-extent episodes.
+
+    One row per (episode_of_care, disease_extent_episode?) pair.
+    """
+
+    __mv_name__ = "overarching_disease_episode_mv"
+    __mv_select__ = overarching_disease_episode.select()
+    __mv_index__ = "disease_episode_id"
+    __deps__ = ()
+    __tablename__ = __mv_name__
+
+    def __repr__(self) -> str:
+        if self.has_extent:
+            return (
+                f"<OverarchingDiseaseEpisode "
+                f"{self.disease_episode_id} -> extent {self.extent_episode_id}>"
+            )
+        return f"<OverarchingDiseaseEpisode {self.disease_episode_id}>"
+    
+    @property
+    def has_extent(self) -> bool:
+        return self.extent_episode_id is not None
+
+    @property
+    def disease_interval(self):
+        return (self.disease_episode_start_date, self.disease_episode_end_date)
+
+    @property
+    def extent_interval(self):
+        if self.extent_episode_id is None:
+            return None
+        return (self.extent_start_date, self.extent_end_date)

omop_constructs-0.2.2/src/omop_constructs/alchemy/episodes/episode_factories.py

@@ -0,0 +1,98 @@
+import sqlalchemy as sa
+import sqlalchemy.orm as so
+from typing import Iterable
+from omop_alchemy.cdm.model import (
+    Condition_Occurrence,
+    Episode,
+    Concept,
+    Episode_Event
+)
+from omop_semantics.runtime.default_valuesets import runtime
+
+episode_concept = so.aliased(Concept, name="episode_concept")
+
+def get_episode_query(
+    episode_concept_ids: Iterable[int],
+    name: str = "episode_construct",
+) -> sa.Subquery:
+    """
+    Base query for Episode-derived constructs.
+    Guarantees at most 1 row per episode_id.
+    """
+    return (
+        sa.select(
+            Episode.episode_id,
+            Episode.person_id,
+            Episode.episode_start_date,
+            Episode.episode_start_datetime,
+            Episode.episode_end_date,
+            Episode.episode_end_datetime,
+            Episode.episode_concept_id,
+            episode_concept.concept_name.label("episode_label"),
+            Episode.episode_object_concept_id,
+            Episode.episode_type_concept_id,
+            Episode.episode_parent_id,
+        )
+        .join(
+            episode_concept,
+            episode_concept.concept_id == Episode.episode_concept_id,
+            isouter=True,
+        )
+        .where(Episode.episode_concept_id.in_(list(episode_concept_ids)))
+        .subquery(name=name)
+    )
+
+def require_condition_anchor(
+    episode_subq: sa.Subquery,
+    name: str | None = None,
+) -> sa.Subquery:
+    """
+    Filters an Episode subquery to only episodes with at least one
+    linked Condition_Occurrence via Episode_Event.
+    """
+    exists_condition = sa.exists().where(
+        sa.and_(
+            Episode_Event.episode_id == episode_subq.c.episode_id,
+            Episode_Event.episode_event_field_concept_id
+            == runtime.modifiers.modifier_fields.condition_occurrence_id,
+            Condition_Occurrence.condition_occurrence_id == Episode_Event.event_id,
+        )
+    )
+    return (
+        sa.select(*episode_subq.c)
+        .where(exists_condition)
+        .subquery(name=name or episode_subq.name)
+    )
+
+
+def get_episode_hierarchy_query(
+    parent_episode_subq: sa.Subquery,
+    child_episode_subq: sa.Subquery,
+    name: str = "episode_optional_children",
+) -> sa.Subquery:
+    """
+    Expands an episode subquery to optionally include child episodes.
+    """
+
+    return (
+        sa.select(
+            parent_episode_subq.c.episode_id.label("parent_episode_id"),
+            parent_episode_subq.c.person_id.label("person_id"),
+            parent_episode_subq.c.episode_concept_id.label("parent_episode_concept_id"),
+            parent_episode_subq.c.episode_label.label("parent_episode_label"),
+            parent_episode_subq.c.episode_start_date.label("parent_start_date"),
+            parent_episode_subq.c.episode_end_date.label("parent_end_date"),
+
+            child_episode_subq.c.episode_id.label("child_episode_id"),
+            child_episode_subq.c.episode_concept_id.label("child_episode_concept_id"),
+            child_episode_subq.c.episode_label.label("child_episode_label"),
+            child_episode_subq.c.episode_start_date.label("child_start_date"),
+            child_episode_subq.c.episode_end_date.label("child_end_date"),
+        )
+        .join(
+            child_episode_subq,
+            child_episode_subq.c.episode_parent_id == parent_episode_subq.c.episode_id,
+            isouter=True,  
+        )
+        .subquery(name=name)        
+    )

omop_constructs-0.2.2/src/omop_constructs/alchemy/episodes/episode_joins.py

@@ -0,0 +1,22 @@
+from .episode_factories import require_condition_anchor, get_episode_query, get_episode_hierarchy_query
+from omop_semantics.runtime.default_valuesets import runtime
+
+episode_of_care_select = require_condition_anchor(
+    get_episode_query(
+        [runtime.episodes.disease_episode_types.episode_of_care],  # type: ignore
+        name="episode_of_care"
+    )
+)
+
+disease_extent_select = require_condition_anchor(
+    get_episode_query(
+        [runtime.episodes.disease_episode_types.metastatic, runtime.episodes.disease_episode_types.disease_progression],  # type: ignore
+        name="disease_extent"
+    )
+)   
+
+overarching_disease_episode = get_episode_hierarchy_query(
+    episode_of_care_select,
+    disease_extent_select,
+    name="overarching_disease_episode",
+)

{omop_constructs-0.2.0 → omop_constructs-0.2.2}/src/omop_constructs/alchemy/modifiers/modifier_joins.py

@@ -35,4 +35,9 @@ size_select = earliest_modifier(
 grade_select = earliest_modifier(
     get_direct_modifier_query(list(registry['tumor_grade'].all_concepts), name="tumor_grade"),
     name="tumor_grade_earliest"
+)
+
+mets_select = earliest_modifier(
+    get_direct_modifier_query(list(registry['metastatic_disease'].all_concepts), name="metastatic_disease"),
+    name="metastatic_disease_earliest"
 )

{omop_constructs-0.2.0 → omop_constructs-0.2.2}/src/omop_constructs/alchemy/modifiers/modifier_mappers.py

@@ -8,6 +8,7 @@ from .modifier_joins import (
     laterality_select,
     size_select,
     grade_select,
+    mets_select
 )
 from ...core.materialized import MaterializedViewMixin
 from ...core.constructs import register_construct
@@ -102,37 +103,12 @@ class LateralityModifierMV(MeasModCols, MaterializedViewMixin, Base):
     __mv_index__ = "measurement_event_id"
     __deps__ = ()
     __tablename__ = __mv_name__
-    value_as_concept_id = sa.Column(sa.Integer)
-
-# class TStage(StageColumns, Base):
-#     __table__ = t_stage_select
-#     __tablename__ = 't_stage'
-
-# class NStage(StageColumns, Base):
-#     __table__ = n_stage_select
-#     __tablename__ = 'n_stage'
-    
-# class MStage(StageColumns, Base):
-#     __table__ = m_stage_select
-#     __tablename__ = 'm_stage'
-
-# class GroupStage(StageColumns, Base):
-#     __table__ = group_stage_select
-#     __tablename__ = 'group_stage'
-    
-# class SizeModifier(MeasModCols, Base):
-#     __table__ = size_select
-#     __tablename__ = 'size_modifier'
-#     value_as_number = size_select.c.value_as_number
-#     unit_concept_id = size_select.c.unit_concept_id
-    
-# class GradeModifier(MeasModCols, Base):
-#     __table__ = grade_select
-#     __tablename__ = 'grade_modifier'
-#     measurement_concept_id = grade_select.c.measurement_concept_id
-
-# class LatModifier(MeasModCols, Base):
-#     __table__ = laterality_select
-#     __tablename__ = 'laterality_modifier'
-#     value_as_concept_id = laterality_select.c.value_as_concept_id
 
+@register_construct
+class MetastaticDiseaseModifierMV(MeasModCols, MaterializedViewMixin, Base):
+    __mv_name__ = "metastatic_disease_modifier_mv"
+    __mv_select__ = mets_select.select()
+    __mv_index__ = "measurement_event_id"
+    __deps__ = ()
+    __tablename__ = __mv_name__
+    value_as_concept_id = sa.Column(sa.Integer)

omop_constructs-0.2.2/src/omop_constructs/core/registry.py

@@ -0,0 +1,274 @@
+
+from dataclasses import dataclass
+from typing import Iterable, Iterator, Type
+import sqlalchemy as sa
+import json
+from datetime import datetime
+from .plan import ConstructNode, topo_sort
+from ..typing import SupportsMaterializedView
+
+@dataclass(frozen=True)
+class ConstructPlanItem:
+    name: str
+    kind: str
+    deps: tuple[str, ...]
+
+
+def materialized_view_exists(bind, name: str, schema: str = "public") -> bool:
+    sql = sa.text("""
+        SELECT EXISTS (
+            SELECT 1
+            FROM pg_matviews
+            WHERE schemaname = :schema
+              AND matviewname = :name
+        )
+    """)
+    return bool(bind.execute(sql, {"schema": schema, "name": name}).scalar())
+
+class ConstructRegistry:
+    """
+    Registry of materialized views / constructs.
+
+    Handles creation, refresh, and teardown in a controlled way.
+    """
+    _constructs: dict[str, Type[SupportsMaterializedView]]
+
+    def __init__(self, constructs: Iterable[type[SupportsMaterializedView]]):
+        self._constructs = {c.__mv_name__: c for c in constructs}
+        
+    def __iter__(self) -> Iterator[type[SupportsMaterializedView]]:
+        return iter(self._constructs.values())
+
+    def get(self, name: str) -> type[SupportsMaterializedView]:
+        return self._constructs[name]
+
+    def plan(self) -> tuple[ConstructPlanItem, ...]:
+        nodes = [
+            ConstructNode(name=k, deps=v.__deps__, kind=getattr(v.__construct__, "kind", "materialized_view"))
+            for k, v in self._constructs.items()
+        ]
+        ordered = topo_sort(nodes)
+        return tuple(ConstructPlanItem(n.name, n.kind, n.deps) for n in ordered)
+    
+    def create_all(self, bind, *, with_data: bool = True):
+        for item in self.plan():
+            cls = self._constructs[item.name]
+            cls.create_mv(bind, with_data=with_data)
+
+    def refresh_all(self, bind, *, concurrently: bool = False) -> None:
+        for item in self.plan():
+            self._constructs[item.name].refresh_mv(bind, concurrently=concurrently)
+
+    def drop_all(self, bind, *, cascade: bool = False) -> None:
+        # drop reverse order
+        for item in reversed(self.plan()):
+            self._constructs[item.name].drop_mv(bind, cascade=cascade)
+
+    def create_missing(self, bind, *, with_data: bool = True, schema: str = "public") -> list[str]:
+        """
+        Create only materialized views that do not yet exist.
+
+        Returns a list of MV names that were created.
+        """
+        created: list[str] = []
+
+        for item in self.plan():
+            cls = self._constructs[item.name]
+
+            exists = materialized_view_exists(bind, cls.__mv_name__, schema=schema)
+            if exists:
+                continue
+
+            cls.create_mv(bind, with_data=with_data)
+            created.append(cls.__mv_name__)
+
+        return created
+
+    def refresh_existing(self, bind, *, concurrently: bool = False, schema: str = "public") -> list[str]:
+        """
+        Refresh only materialized views that already exist.
+        """
+        refreshed: list[str] = []
+
+        for item in self.plan():
+            cls = self._constructs[item.name]
+            if materialized_view_exists(bind, cls.__mv_name__, schema=schema):
+                cls.refresh_mv(bind, concurrently=concurrently)
+                refreshed.append(cls.__mv_name__)
+
+        return refreshed
+
+
+    def explain(self, bind, *, schema: str = "public", with_counts: bool = True) -> str:
+        """
+        For each materialized view in the registry, show the SQL definition and whether it exists in the database.
+        If with_counts is True, also attempt to query the row count for existing MVs.
+        """
+        lines = ["<ConstructRegistry explain>"]
+
+        for item in self.plan():
+            cls = self._constructs[item.name]
+
+            sql = str(cls.__mv_select__.compile(bind, compile_kwargs={"literal_binds": True}))
+            sql_kb = round(len(sql) / 1024, 1)
+
+            exists = materialized_view_exists(bind, cls.__mv_name__, schema=schema)
+
+            row_info = ""
+            if with_counts and exists:
+                try:
+                    count = bind.execute(
+                        sa.text(f"SELECT count(*) FROM {schema}.{cls.__mv_name__}")
+                    ).scalar()
+                    row_info = f", rows={count:,}"
+                except Exception as e:
+                    row_info = f", rows=<?> ({e.__class__.__name__})"
+
+            lines.append(
+                f"  - {cls.__mv_name__:25s}  sql≈{sql_kb:6.1f} KB, exists={exists}{row_info}"
+            )
+
+        return "\n".join(lines)
+
+    def validate(self, bind, *, schema: str = "public") -> str:
+        """
+        Check to see if each materialized view exists, and if so whether its schema matches 
+        the mapper definition.
+        """
+        lines = ["<ConstructRegistry validate>"]
+
+        for item in self.plan():
+            cls = self._constructs[item.name]
+            name = cls.__mv_name__
+
+            exists = materialized_view_exists(bind, name, schema=schema)
+            if not exists:
+                lines.append(f"  ✗ {name}: MV does not exist")
+                continue
+
+            cols = bind.execute(sa.text(f"""
+                SELECT column_name
+                FROM information_schema.columns
+                WHERE table_schema = :schema
+                AND table_name = :name
+                ORDER BY ordinal_position
+            """), {"schema": schema, "name": name}).scalars().all()
+
+            orm_cols = {
+                k for k, v in vars(cls).items()
+                if hasattr(v, "property") or hasattr(v, "type")
+            }
+
+            missing = sorted(set(orm_cols) - set(cols))
+            extra = sorted(set(cols) - set(orm_cols))
+
+            if not missing and not extra:
+                lines.append(f"  ✓ {name}: schema OK")
+            else:
+                lines.append(f"  ⚠ {name}: schema mismatch")
+                if missing:
+                    lines.append(f"      - missing in MV: {missing}")
+                if extra:
+                    lines.append(f"      - extra in MV:   {extra}")
+
+        return "\n".join(lines)
+
+
+    def build_plan_json(self) -> dict:
+        """
+        Dumps plan information as JSON-serializable dict, e.g. for API responses or logging.
+        """
+        items = self.plan()
+
+        return {
+            "generated_at": datetime.utcnow().isoformat(),
+            "constructs": [
+                {
+                    "name": item.name,
+                    "kind": item.kind,
+                    "deps": list(item.deps),
+                }
+                for item in items
+            ],
+        }
+
+    def status(self, bind, *, schema: str = "public") -> str:
+        """
+        Which each MV exists or not, in dependency order.
+        """
+        lines = ["<ConstructRegistry status>"]
+        for item in self.plan():
+            name = item.name
+            exists = materialized_view_exists(bind, name, schema=schema)
+            flag = "✓" if exists else "✗"
+            lines.append(f"  {flag} {name}")
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:
+        try:
+            items = self.plan()
+        except Exception:
+            # fallback if deps are broken / incomplete during import time
+            names = sorted(self._constructs.keys())
+            body = ", ".join(names)
+            return f"<ConstructRegistry [{body}]>"
+
+        body = ", ".join(item.name for item in items)
+        return f"<ConstructRegistry [{body}]>"
+    
+
+    def describe(self, full: bool = False) -> str:
+        try:
+            items = self.plan()
+        except Exception:
+            return f"<ConstructRegistry (invalid dependency graph) n={len(self._constructs)}>"
+
+        lines = ["<ConstructRegistry>"]
+        for item in items:
+            deps = ", ".join(item.deps) if item.deps else "—"
+            lines.append(f"  - {item.name:25s}  kind={item.kind:18s} deps=[{deps}]")
+
+            if full:
+                cls = self._constructs[item.name]
+                sql = str(cls.__mv_select__)
+                lines.append(f"      sql_length={len(sql):,} chars")
+
+        return "\n".join(lines)
+    
+
+    def ascii_dag(self) -> str:
+        """
+        Render a simple ASCII dependency graph of the construct registry.
+        """
+
+        try:
+            items = self.plan()
+        except Exception as e:
+            return f"<ConstructRegistry DAG unavailable: {e}>"
+
+        # adjacency: parent -> children
+        children: dict[str, list[str]] = {name: [] for name in self._constructs}
+        for name, cls in self._constructs.items():
+            for dep in cls.__deps__:
+                if dep in children:
+                    children[dep].append(name)
+
+        roots = [name for name, cls in self._constructs.items() if not cls.__deps__]
+
+        lines: list[str] = []
+
+        def walk(node: str, prefix: str = "", is_last: bool = True):
+            connector = "└─ " if is_last else "├─ "
+            lines.append(prefix + connector + node)
+
+            kids = children.get(node, [])
+            for i, child in enumerate(kids):
+                last = i == len(kids) - 1
+                next_prefix = prefix + ("   " if is_last else "│  ")
+                walk(child, next_prefix, last)
+
+        for i, root in enumerate(roots):
+            last_root = i == len(roots) - 1
+            walk(root, "", last_root)
+
+        return "\n".join(lines)

omop_constructs-0.2.0/src/omop_constructs/core/registry.py

@@ -1,115 +0,0 @@
-from typing import Iterable, Iterator, Type
-from .materialized import MaterializedViewMixin
-from .plan import ConstructNode, topo_sort
-from ..typing import SupportsMaterializedView
-from dataclasses import dataclass
-
-@dataclass(frozen=True)
-class ConstructPlanItem:
-    name: str
-    kind: str
-    deps: tuple[str, ...]
-
-class ConstructRegistry:
-    """
-    Registry of materialized views / constructs.
-
-    Handles creation, refresh, and teardown in a controlled way.
-    """
-    _constructs: dict[str, Type[SupportsMaterializedView]]
-
-    def __init__(self, constructs: Iterable[type[SupportsMaterializedView]]):
-        self._constructs = {c.__mv_name__: c for c in constructs}
-        
-    def __iter__(self) -> Iterator[type[SupportsMaterializedView]]:
-        return iter(self._constructs.values())
-
-    def get(self, name: str) -> type[SupportsMaterializedView]:
-        return self._constructs[name]
-
-    def plan(self) -> tuple[ConstructPlanItem, ...]:
-        nodes = [
-            ConstructNode(name=k, deps=v.__deps__, kind=getattr(v.__construct__, "kind", "materialized_view"))
-            for k, v in self._constructs.items()
-        ]
-        ordered = topo_sort(nodes)
-        return tuple(ConstructPlanItem(n.name, n.kind, n.deps) for n in ordered)
-    
-    def create_all(self, bind, *, with_data: bool = True):
-        for item in self.plan():
-            cls = self._constructs[item.name]
-            cls.create_mv(bind, with_data=with_data)
-
-    def refresh_all(self, bind, *, concurrently: bool = False) -> None:
-        for item in self.plan():
-            self._constructs[item.name].refresh_mv(bind, concurrently=concurrently)
-
-    def drop_all(self, bind, *, cascade: bool = False) -> None:
-        # drop reverse order
-        for item in reversed(self.plan()):
-            self._constructs[item.name].drop_mv(bind, cascade=cascade)
-
-
-    def __repr__(self) -> str:
-        try:
-            items = self.plan()
-        except Exception:
-            # fallback if deps are broken / incomplete during import time
-            names = sorted(self._constructs.keys())
-            body = ", ".join(names)
-            return f"<ConstructRegistry [{body}]>"
-
-        body = ", ".join(item.name for item in items)
-        return f"<ConstructRegistry [{body}]>"
-    
-
-    def describe(self) -> str:
-        try:
-            items = self.plan()
-        except Exception:
-            return f"<ConstructRegistry (invalid dependency graph) n={len(self._constructs)}>"
-
-        lines = ["<ConstructRegistry>"]
-        for item in items:
-            deps = ", ".join(item.deps) if item.deps else "—"
-            lines.append(f"  - {item.name:25s}  kind={item.kind:18s} deps=[{deps}]")
-
-        return "\n".join(lines)
-    
-
-    def ascii_dag(self) -> str:
-        """
-        Render a simple ASCII dependency graph of the construct registry.
-        """
-
-        try:
-            items = self.plan()
-        except Exception as e:
-            return f"<ConstructRegistry DAG unavailable: {e}>"
-
-        # adjacency: parent -> children
-        children: dict[str, list[str]] = {name: [] for name in self._constructs}
-        for name, cls in self._constructs.items():
-            for dep in cls.__deps__:
-                if dep in children:
-                    children[dep].append(name)
-
-        roots = [name for name, cls in self._constructs.items() if not cls.__deps__]
-
-        lines: list[str] = []
-
-        def walk(node: str, prefix: str = "", is_last: bool = True):
-            connector = "└─ " if is_last else "├─ "
-            lines.append(prefix + connector + node)
-
-            kids = children.get(node, [])
-            for i, child in enumerate(kids):
-                last = i == len(kids) - 1
-                next_prefix = prefix + ("   " if is_last else "│  ")
-                walk(child, next_prefix, last)
-
-        for i, root in enumerate(roots):
-            last_root = i == len(roots) - 1
-            walk(root, "", last_root)
-
-        return "\n".join(lines)