omop-constructs 0.4.0__tar.gz → 0.4.2__tar.gz

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: omop-constructs
-Version: 0.4.0
+Version: 0.4.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.6.1
-Requires-Dist: omop-semantics>=0.1.14
+Requires-Dist: omop-semantics>=0.1.15
 Requires-Dist: psycopg2-binary>=2.9.11
 Requires-Dist: sqlalchemy>=2.0.45
 Requires-Dist: ipython>=9.8.0 ; extra == 'dev'

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omop-constructs"
-version = "0.4.0"
+version = "0.4.2"
 description = "For building complex constructs on top of the omop-alchemy library."
 readme = "README.md"
 authors = [
@@ -9,7 +9,7 @@ authors = [
 requires-python = ">=3.12"
 dependencies = [
     "omop-alchemy>=0.6.1",
-    "omop-semantics>=0.1.14",
+    "omop-semantics>=0.1.15",
     "psycopg2-binary>=2.9.11",
     "sqlalchemy>=2.0.45",
 ]

omop_constructs-0.4.2/src/omop_constructs/alchemy/__init__.py

@@ -0,0 +1,7 @@
+"""
+High-level construct families built on top of ``omop-alchemy`` models.
+
+The subpackages under :mod:`omop_constructs.alchemy` expose the repository's
+active analytical constructs, mostly as ORM-mapped materialized views plus the
+query fragments used to build them.
+"""

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/episodes/__init__.py

@@ -8,6 +8,7 @@ from .fraction_mv import FractionMV
 from .treatment_summary_mv import ConditionTreatmentEpisode
 from .treatment_envelope_mv import TreatmentEnvelopeMV
 from .modality_intent_mv import TreatmentIntentMV, ConditionTreatmentIntentMV
+from .consult_window_mv import ConsultWindowMV
 
 __all__ = [
     "OverarchingDiseaseEpisodeMV",
@@ -24,4 +25,5 @@ __all__ = [
     "TreatmentEnvelopeMV",
     "TreatmentIntentMV",
     "ConditionTreatmentIntentMV",
-]
+    "ConsultWindowMV",
+]

omop_constructs-0.4.2/src/omop_constructs/alchemy/episodes/consult_window_mv.py

@@ -0,0 +1,57 @@
+import sqlalchemy as sa
+import sqlalchemy.orm as so
+from datetime import date
+from typing import Optional
+
+from orm_loader.helpers import Base
+
+from ...core.constructs import register_construct
+from ...core.materialized import MaterializedViewMixin
+from ..events.dx_linked_obs_mv import DxObservationMV
+from ..events.dx_linked_visit_mv import DxRelevantVisitMV
+from .consult_window_query import consult_window
+from .treatment_envelope_mv import TreatmentEnvelopeMV
+
+
+@register_construct
+class ConsultWindowMV(MaterializedViewMixin, Base):
+    """
+    Episode-of-care consult and referral window summary.
+
+    The materialized view exposes the earliest specialist contact and the
+    derived scalar windows currently used downstream for referral timing
+    analysis.
+    """
+    __mv_name__ = "consult_window_mv"
+    __mv_select__ = consult_window.select()
+    __mv_index__ = "episode_id"
+    __deps__ = (
+        DxObservationMV.__mv_name__,
+        DxRelevantVisitMV.__mv_name__,
+        TreatmentEnvelopeMV.__mv_name__,
+    )
+    __tablename__ = __mv_name__
+    __table_args__ = {"extend_existing": True}
+
+    mv_id: so.Mapped[int] = so.mapped_column(primary_key=True)
+    person_id: so.Mapped[int] = so.mapped_column(sa.Integer)
+    episode_id: so.Mapped[int] = so.mapped_column(sa.Integer)
+    episode_start_date: so.Mapped[date] = so.mapped_column(sa.Date)
+    episode_concept_id: so.Mapped[int] = so.mapped_column(sa.Integer)
+    initial_gp_referral: so.Mapped[Optional[date]] = so.mapped_column(
+        sa.Date, nullable=True
+    )
+    first_specialist: so.Mapped[Optional[date]] = so.mapped_column(sa.Date, nullable=True)
+    first_pall_care: so.Mapped[Optional[date]] = so.mapped_column(sa.Date, nullable=True)
+    first_pall_care_or_treatment: so.Mapped[Optional[date]] = so.mapped_column(
+        sa.Date, nullable=True
+    )
+    earliest_treatment: so.Mapped[Optional[date]] = so.mapped_column(
+        sa.Date, nullable=True
+    )
+    referral_to_specialist: so.Mapped[Optional[float]] = so.mapped_column(
+        sa.Float, nullable=True
+    )
+    referral_to_tx: so.Mapped[Optional[float]] = so.mapped_column(
+        sa.Float, nullable=True
+    )

omop_constructs-0.4.2/src/omop_constructs/alchemy/episodes/consult_window_query.py

@@ -0,0 +1,261 @@
+"""
+Episode-level consult and referral window query fragments.
+
+The current implementation combines episode-of-care anchors, diagnosis-linked
+consult observations, ranked specialist visits, and the treatment envelope to
+derive referral-to-specialist and referral-to-treatment windows.
+"""
+
+import sqlalchemy as sa
+from sqlalchemy.sql import ColumnElement
+
+from omop_alchemy.cdm.model import Episode
+from omop_semantics.runtime.default_valuesets import runtime  # type: ignore
+
+from ..events.dx_linked_obs_mv import DxObservationMV
+from ..events.dx_linked_visit_mv import DxRelevantVisitMV
+from .treatment_envelope_mv import TreatmentEnvelopeMV
+
+
+def days_between(
+    end_date: ColumnElement,
+    start_date: ColumnElement,
+) -> ColumnElement:
+    """
+    Return the interval between two date-like expressions in days.
+    """
+    return sa.func.extract(
+        "epoch",
+        sa.cast(end_date, sa.DateTime) - sa.cast(start_date, sa.DateTime),
+    ) / 86400.0
+
+
+episode_of_care = (
+    sa.select(
+        Episode.person_id,
+        Episode.episode_id,
+        Episode.episode_start_date,
+        Episode.episode_concept_id,
+    )
+    .where(
+        Episode.episode_concept_id
+        == runtime.types.disease_episode_types.episode_of_care  # type: ignore[attr-defined]
+    )
+    .subquery(name="episode_of_care")
+)
+
+episode_of_care_obs = (
+    sa.select(*DxObservationMV.__table__.c)
+    .where(
+        DxObservationMV.episode_concept_id
+        == runtime.types.disease_episode_types.episode_of_care  # type: ignore[attr-defined]
+    )
+    .subquery(name="episode_of_care_obs")
+)
+
+first_specialist = (
+    sa.select(
+        episode_of_care_obs.c.person_id,
+        episode_of_care_obs.c.episode_id,
+        sa.func.min(episode_of_care_obs.c.event_date).label("first_specialist_consult"),
+        sa.func.max(episode_of_care_obs.c.event_date).label("last_specialist_consult"),
+    )
+    .where(
+        episode_of_care_obs.c.event_concept_id.in_(
+            [
+                runtime.cancer_procedures.cancer_consult_types.medonc,  # type: ignore[attr-defined]
+                runtime.cancer_procedures.cancer_consult_types.clinonc,  # type: ignore[attr-defined]
+            ]
+        )
+    )
+    .group_by(
+        episode_of_care_obs.c.person_id,
+        episode_of_care_obs.c.episode_id,
+    )
+    .subquery(name="first_specialist")
+)
+
+gp_referral = (
+    sa.select(
+        episode_of_care_obs.c.person_id,
+        episode_of_care_obs.c.episode_id,
+        sa.func.min(episode_of_care_obs.c.event_date).label("initial_gp_referral"),
+    )
+    .where(
+        episode_of_care_obs.c.event_concept_id
+        == runtime.cancer_procedures.cancer_consult_types.oncology_referral  # type: ignore[attr-defined]
+    )
+    .group_by(
+        episode_of_care_obs.c.person_id,
+        episode_of_care_obs.c.episode_id,
+    )
+    .subquery(name="gp_referral")
+)
+
+pall_care_referral = (
+    sa.select(
+        episode_of_care_obs.c.person_id,
+        episode_of_care_obs.c.episode_id,
+        sa.func.min(episode_of_care_obs.c.event_date).label("first_pall_care_referral"),
+    )
+    .where(
+        episode_of_care_obs.c.event_concept_id
+        == runtime.cancer_procedures.cancer_consult_types.pall_care_referral  # type: ignore[attr-defined]
+    )
+    .group_by(
+        episode_of_care_obs.c.person_id,
+        episode_of_care_obs.c.episode_id,
+    )
+    .subquery(name="pall_care_referral")
+)
+
+specialist_visit = (
+    sa.select(
+        DxRelevantVisitMV.person_id,
+        DxRelevantVisitMV.episode_id,
+        sa.func.min(DxRelevantVisitMV.visit_start_date).label("first_specialist_visit"),
+    )
+    .where(
+        DxRelevantVisitMV.provider_specialty_concept_id.in_(
+            [
+                runtime.cancer_procedures.encounter_provider_specialty.radonc,  # type: ignore[attr-defined]
+                runtime.cancer_procedures.encounter_provider_specialty.medonc,  # type: ignore[attr-defined]
+                runtime.cancer_procedures.encounter_provider_specialty.haematologist,  # type: ignore[attr-defined]
+            ]
+        )
+    )
+    .group_by(
+        DxRelevantVisitMV.person_id,
+        DxRelevantVisitMV.episode_id,
+    )
+    .subquery(name="specialist_visit")
+)
+
+pall_care_visit = (
+    sa.select(
+        DxRelevantVisitMV.person_id,
+        DxRelevantVisitMV.episode_id,
+        sa.func.min(DxRelevantVisitMV.visit_start_date).label("first_pall_care_visit"),
+    )
+    .where(
+        DxRelevantVisitMV.provider_specialty_concept_id
+        == runtime.cancer_procedures.encounter_provider_specialty.pall_care  # type: ignore[attr-defined]
+    )
+    .group_by(
+        DxRelevantVisitMV.person_id,
+        DxRelevantVisitMV.episode_id,
+    )
+    .subquery(name="pall_care_visit")
+)
+
+specialist_trajectory = (
+    sa.select(
+        episode_of_care.c.person_id,
+        episode_of_care.c.episode_id,
+        episode_of_care.c.episode_start_date,
+        episode_of_care.c.episode_concept_id,
+        first_specialist.c.first_specialist_consult,
+        first_specialist.c.last_specialist_consult,
+        specialist_visit.c.first_specialist_visit,
+        gp_referral.c.initial_gp_referral,
+        pall_care_referral.c.first_pall_care_referral,
+        pall_care_visit.c.first_pall_care_visit,
+    )
+    .join(
+        first_specialist,
+        first_specialist.c.episode_id == episode_of_care.c.episode_id,
+        isouter=True,
+    )
+    .join(
+        gp_referral,
+        gp_referral.c.episode_id == episode_of_care.c.episode_id,
+        isouter=True,
+    )
+    .join(
+        pall_care_referral,
+        pall_care_referral.c.episode_id == episode_of_care.c.episode_id,
+        isouter=True,
+    )
+    .join(
+        specialist_visit,
+        specialist_visit.c.episode_id == episode_of_care.c.episode_id,
+        isouter=True,
+    )
+    .join(
+        pall_care_visit,
+        pall_care_visit.c.episode_id == episode_of_care.c.episode_id,
+        isouter=True,
+    )
+    .subquery(name="specialist_trajectory")
+)
+
+consult_window = (
+    sa.select(
+        sa.func.row_number().over().label("mv_id"),
+        specialist_trajectory.c.person_id,
+        specialist_trajectory.c.episode_id,
+        specialist_trajectory.c.episode_start_date,
+        specialist_trajectory.c.initial_gp_referral,
+        specialist_trajectory.c.episode_concept_id,
+        sa.func.least(
+            specialist_trajectory.c.first_specialist_consult,
+            specialist_trajectory.c.first_specialist_visit,
+        ).label("first_specialist"),
+        sa.func.least(
+            specialist_trajectory.c.first_pall_care_referral,
+            specialist_trajectory.c.first_pall_care_visit,
+        ).label("first_pall_care"),
+        sa.func.least(
+            specialist_trajectory.c.first_pall_care_referral,
+            specialist_trajectory.c.first_pall_care_visit,
+            TreatmentEnvelopeMV.earliest_treatment,
+        ).label("first_pall_care_or_treatment"),
+        TreatmentEnvelopeMV.earliest_treatment,
+        sa.case(
+            (
+                sa.and_(
+                    specialist_trajectory.c.initial_gp_referral.is_not(None),
+                    sa.func.least(
+                        specialist_trajectory.c.first_specialist_consult,
+                        specialist_trajectory.c.first_specialist_visit,
+                    ).is_not(None),
+                ),
+                days_between(
+                    sa.func.least(
+                        specialist_trajectory.c.first_specialist_consult,
+                        specialist_trajectory.c.first_specialist_visit,
+                    ),
+                    specialist_trajectory.c.initial_gp_referral,
+                ),
+            ),
+            else_=None,
+        ).label("referral_to_specialist"),
+        sa.case(
+            (
+                sa.and_(
+                    specialist_trajectory.c.initial_gp_referral.is_not(None),
+                    sa.func.least(
+                        specialist_trajectory.c.first_pall_care_referral,
+                        specialist_trajectory.c.first_pall_care_visit,
+                        TreatmentEnvelopeMV.earliest_treatment,
+                    ).is_not(None),
+                ),
+                days_between(
+                    sa.func.least(
+                        specialist_trajectory.c.first_pall_care_referral,
+                        specialist_trajectory.c.first_pall_care_visit,
+                        TreatmentEnvelopeMV.earliest_treatment,
+                    ),
+                    specialist_trajectory.c.initial_gp_referral,
+                ),
+            ),
+            else_=None,
+        ).label("referral_to_tx"),
+    )
+    .join(
+        TreatmentEnvelopeMV,
+        TreatmentEnvelopeMV.condition_episode == specialist_trajectory.c.episode_id,
+        isouter=True,
+    )
+    .subquery(name="consult_window")
+)

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/episodes/treatment_summary_mv.py

@@ -4,6 +4,7 @@ from orm_loader.helpers import Base
 from datetime import date
 from typing import Optional
 from .treatment_summary_joins import condition_treatment_join
+from .treatment_envelope_mv import TreatmentEnvelopeMV
 from .course_mv import RTCourseMV
 from .systemic_treatment_mv import SACTRegimenMV
 from ...core.materialized import MaterializedViewMixin
@@ -44,4 +45,4 @@ class ConditionTreatmentEpisode(
     sact_intent_concept_id: so.Mapped[int] = so.mapped_column(sa.Integer)
     sact_intent_concept: so.Mapped[int] = so.mapped_column(sa.Integer)
     exposure_count: so.Mapped[int] = so.mapped_column(sa.Integer)
-    regimen_count: so.Mapped[int] = so.mapped_column(sa.Integer)
+    regimen_count: so.Mapped[int] = so.mapped_column(sa.Integer)

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/events/__init__.py

@@ -18,6 +18,9 @@ from .dx_linked_procedure_mv import (
 from .dx_linked_obs_mv import (
     DxObservationMV,
 )
+from .dx_linked_visit_mv import (
+    DxRelevantVisitMV,
+)
 
 __all__ = [
     "WeightDxMV",
@@ -33,4 +36,5 @@ __all__ = [
     "DxMeasurementMV",
     "DxProcedureMV",
     "DxObservationMV",
-]
+    "DxRelevantVisitMV",
+]

omop_constructs-0.4.2/src/omop_constructs/alchemy/events/dx_linked_visit_mv.py

@@ -0,0 +1,56 @@
+import sqlalchemy as sa
+import sqlalchemy.orm as so
+from datetime import date, datetime
+from typing import Optional
+
+from orm_loader.helpers import Base
+
+from ...core.constructs import register_construct
+from ...core.materialized import MaterializedViewMixin
+from .visit_queries import dx_relevant_visits
+
+
+class ConditionEpisodeVisitCols:
+    """
+    Shared mapped columns for diagnosis-relevant visit materialized views.
+    """
+    __table_args__ = {"extend_existing": True}
+
+    mv_id: so.Mapped[int] = so.mapped_column(primary_key=True)
+
+    person_id: so.Mapped[int] = so.mapped_column(sa.Integer)
+    visit_occurrence_id: so.Mapped[int] = so.mapped_column(sa.Integer)
+    visit_start_date: so.Mapped[date] = so.mapped_column(sa.Date)
+    visit_start_datetime: so.Mapped[Optional[datetime]] = so.mapped_column(
+        sa.DateTime, nullable=True
+    )
+
+    provider_id: so.Mapped[int] = so.mapped_column(sa.Integer)
+    provider_specialty: so.Mapped[Optional[str]] = so.mapped_column(
+        sa.String, nullable=True
+    )
+    provider_specialty_concept_id: so.Mapped[Optional[int]] = so.mapped_column(
+        sa.Integer, nullable=True
+    )
+
+    episode_id: so.Mapped[int] = so.mapped_column(sa.Integer)
+    episode_start_date: so.Mapped[date] = so.mapped_column(sa.Date)
+
+    episode_prior: so.Mapped[int] = so.mapped_column(sa.Integer)
+    diff_days: so.Mapped[float] = so.mapped_column(sa.Float)
+    rank: so.Mapped[int] = so.mapped_column(sa.Integer)
+
+
+@register_construct
+class DxRelevantVisitMV(ConditionEpisodeVisitCols, MaterializedViewMixin, Base):
+    """
+    Provider-specialty visits linked to diagnosis episodes.
+
+    This view uses ranked episode assignment logic tailored to specialist visit
+    analysis rather than the generic event factory time-window attachment path.
+    """
+    __mv_name__ = "dx_visit_mv"
+    __mv_select__ = dx_relevant_visits.select()
+    __mv_index__ = "person_id"
+    __deps__ = ()
+    __tablename__ = __mv_name__

omop_constructs-0.4.2/src/omop_constructs/alchemy/events/visit_queries.py

@@ -0,0 +1,89 @@
+"""
+Query fragments for linking visit occurrences to disease episodes by specialty.
+
+These queries support specialist consult-style measures where visit/provider
+specialty is part of the derivation and generic event-attachment helpers are not
+quite expressive enough.
+"""
+
+import sqlalchemy as sa
+import sqlalchemy.orm as so
+
+from omop_alchemy.cdm.model import Concept, Episode, Provider, Visit_Occurrence
+from omop_semantics.runtime.default_valuesets import runtime  # type: ignore
+
+
+provider_concept = so.aliased(Concept, name="provider_concept")
+
+episode_of_care = (
+    sa.select(
+        Episode.person_id,
+        Episode.episode_id,
+        Episode.episode_start_date,
+    )
+    .where(
+        Episode.episode_concept_id
+        == runtime.types.disease_episode_types.episode_of_care  # type: ignore[attr-defined]
+    )
+    .subquery(name="episode_of_care")
+)
+
+visit_start = sa.func.coalesce(
+    Visit_Occurrence.visit_start_datetime,
+    sa.cast(Visit_Occurrence.visit_start_date, sa.DateTime),
+)
+episode_start = sa.cast(episode_of_care.c.episode_start_date, sa.DateTime)
+
+diff_days = sa.func.extract("epoch", visit_start - episode_start) / 86400.0
+
+episode_start_prior = sa.case(
+    (
+        sa.func.abs(diff_days) < 180,
+        1,
+    ),
+    (
+        visit_start > episode_start,
+        2,
+    ),
+    else_=3,
+)
+
+visits_by_specialty = (
+    sa.select(
+        Visit_Occurrence.person_id,
+        Visit_Occurrence.visit_occurrence_id,
+        Visit_Occurrence.visit_start_date,
+        Visit_Occurrence.visit_start_datetime,
+        Provider.provider_id,
+        provider_concept.concept_name.label("provider_specialty"),
+        provider_concept.concept_id.label("provider_specialty_concept_id"),
+        episode_of_care.c.episode_id,
+        episode_of_care.c.episode_start_date,
+        episode_start_prior.label("episode_prior"),
+        diff_days.label("diff_days"),
+        sa.func.row_number()
+        .over(
+            partition_by=Visit_Occurrence.visit_occurrence_id,
+            order_by=[episode_start_prior, diff_days],
+        )
+        .label("rank"),
+    )
+    .join(episode_of_care, episode_of_care.c.person_id == Visit_Occurrence.person_id)
+    .join(Provider, Visit_Occurrence.provider_id == Provider.provider_id)
+    .join(provider_concept, provider_concept.concept_id == Provider.specialty_concept_id)
+    .subquery(name="visits_by_specialty")
+)
+
+dx_relevant_visits = (
+    sa.select(
+        sa.func.row_number().over().label("mv_id"),
+        *visits_by_specialty.c,
+    )
+    .where(
+        sa.or_(
+            visits_by_specialty.c.episode_prior == 1,
+            visits_by_specialty.c.rank == 1,
+        )
+    )
+    .subquery(name="dx_relevant_visits")
+)

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/modifiers/modifier_joins.py

@@ -1,14 +1,16 @@
+"""
+Resolver-backed query fragments for staging and condition modifier selection.
+
+Importing this module is not a pure no-op. At module import time it resolves the
+configured semantics-backed resolver sets and uses them to build the stage and
+modifier query fragments that feed the modifier materialized views.
+"""
+
 from omop_constructs.semantics import registry
 from omop_alchemy.cdm.model.clinical import Measurement
 from omop_semantics.runtime.default_valuesets import runtime
 from .modifier_factories import get_query_per_stage_type, get_eav_modifier_query, earliest_modifier, get_direct_modifier_query
-"""
-These calls have side effects of building the resolvers and querying the database to 
-cache the required concepts in memory, but this is necessary to create the correct 
-subqueries for staging modifiers. 
 
-TODO: we may want to refactor to separate out the resolver construction from the concept retrieval?
-"""
 t_stage_select = get_query_per_stage_type(registry['tnm_t_stage'].all_concepts, name="t_stage")
 n_stage_select = get_query_per_stage_type(registry['tnm_n_stage'].all_concepts, name="n_stage")
 m_stage_select = get_query_per_stage_type(registry['tnm_m_stage'].all_concepts, name="m_stage")
@@ -50,4 +52,4 @@ all_stage_select = get_direct_modifier_query(
             )
     ),
     name="all_stage_modifiers"
-)
+)

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/core/constructs.py

@@ -9,7 +9,11 @@ _CONSTRUCTS: Dict[str, Type[SupportsMaterializedView]] = {}
 
 def register_construct(cls: T) -> T:
     """
-    Decorator to register a materialized view / construct class.
+    Register a materialized view-backed construct class.
+
+    Registration is import-driven: any module that defines construct classes and
+    imports this decorator will add those classes to the in-process registry as
+    soon as the module is imported.
     """
     name = getattr(cls, "__mv_name__", None)
     if not name:
@@ -24,4 +28,12 @@ def register_construct(cls: T) -> T:
     return cls
 
 def get_construct_registry() -> ConstructRegistry:
-    return ConstructRegistry(_CONSTRUCTS.values())
+    """
+    Return a registry view over all construct classes imported so far.
+
+    Notes
+    -----
+    The returned registry reflects the current Python process. If a construct
+    module has not yet been imported, its classes will not appear here.
+    """
+    return ConstructRegistry(_CONSTRUCTS.values())

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/core/materialized.py

@@ -18,6 +18,9 @@ class MaterializedViewMixin:
 
     @classmethod
     def create_mv(cls, bind, *, with_data: bool = True) -> None:
+        """
+        Create the backing materialized view for this mapped class.
+        """
         ddl = CreateMaterializedView(cls.__mv_name__, cls.__mv_select__, with_data=with_data)
         bind.execute(ddl)
         if cls.__mv_index__ is not None:
@@ -25,6 +28,9 @@ class MaterializedViewMixin:
 
     @classmethod
     def refresh_mv(cls, bind, *, concurrently: bool = False):
+        """
+        Refresh the backing materialized view.
+        """
         suffix = " CONCURRENTLY" if concurrently else ""
         bind.execute(
             sa.text(f"REFRESH MATERIALIZED VIEW{suffix} {cls.__mv_name__}")
@@ -32,11 +38,17 @@ class MaterializedViewMixin:
 
     @classmethod
     def drop_mv(cls, bind, *, cascade: bool = False):
+        """
+        Drop the backing materialized view.
+        """
         ddl = DropMaterializedView(cls.__mv_name__, cascade=cascade)
         bind.execute(ddl)
 
     @classmethod
     def create_index(cls, bind, index_colname: str):
+        """
+        Create the configured helper index for the materialized view if needed.
+        """
         bind.execute(sa.text(
             f"CREATE INDEX IF NOT EXISTS {cls.__mv_name__}_{index_colname}_idx "
             f"ON {cls.__mv_name__} ({index_colname})"

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/core/plan.py

@@ -7,11 +7,20 @@ from .errors import DependencyCycleError
 
 @dataclass(frozen=True)
 class ConstructNode:
+    """
+    Lightweight dependency node used when building construct execution plans.
+    """
     name: str
     deps: tuple[str, ...] = ()
     kind: str = "materialized_view"
 
 def topo_sort(nodes: list[ConstructNode]) -> list[ConstructNode]:
+    """
+    Topologically sort construct nodes by their declared dependencies.
+
+    Dependencies that point outside the provided node set are treated as
+    external and ignored for ordering purposes.
+    """
     by_name = {n.name: n for n in nodes}
     indeg = {n.name: 0 for n in nodes}
     adj = defaultdict(list)

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/core/registry.py

@@ -9,12 +9,18 @@ from ..typing import SupportsMaterializedView
 
 @dataclass(frozen=True)
 class ConstructPlanItem:
+    """
+    Serializable view of a construct's name, kind, and declared dependencies.
+    """
     name: str
     kind: str
     deps: tuple[str, ...]
 
 
 def materialized_view_exists(bind, name: str, schema: str = "public") -> bool:
+    """
+    Check whether a PostgreSQL materialized view already exists.
+    """
     sql = sa.text("""
         SELECT EXISTS (
             SELECT 1
@@ -34,15 +40,24 @@ class ConstructRegistry:
     _constructs: dict[str, Type[SupportsMaterializedView]]
 
     def __init__(self, constructs: Iterable[type[SupportsMaterializedView]]):
+        """
+        Build a registry over an iterable of construct classes.
+        """
         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 a registered construct class by materialized view name.
+        """
         return self._constructs[name]
 
     def plan(self) -> tuple[ConstructPlanItem, ...]:
+        """
+        Return constructs in dependency order.
+        """
         nodes = [
             ConstructNode(name=k, deps=v.__deps__, kind=getattr(v.__construct__, "kind", "materialized_view"))
             for k, v in self._constructs.items()
@@ -51,6 +66,9 @@ class ConstructRegistry:
         return tuple(ConstructPlanItem(n.name, n.kind, n.deps) for n in ordered)
     
     def create_all(self, bind, *, with_data: bool = True):
+        """
+        Create every registered materialized view in dependency order.
+        """
         for item in self.plan():
             cls = self._constructs[item.name]
             cls.create_mv(bind, with_data=with_data)
@@ -60,6 +78,9 @@ class ConstructRegistry:
             self._constructs[item.name].refresh_mv(bind, concurrently=concurrently)
 
     def drop_all(self, bind, *, cascade: bool = False) -> None:
+        """
+        Drop every registered materialized view in reverse dependency order.
+        """
         # drop reverse order
         for item in reversed(self.plan()):
             try:
@@ -221,6 +242,9 @@ class ConstructRegistry:
     
 
     def describe(self, full: bool = False) -> str:
+        """
+        Render a text description of the registry dependency graph.
+        """
         try:
             items = self.plan()
         except Exception:
@@ -274,4 +298,4 @@ class ConstructRegistry:
             last_root = i == len(roots) - 1
             walk(root, "", last_root)
 
-        return "\n".join(lines)
+        return "\n".join(lines)

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/semantics/lookups.py

@@ -14,6 +14,9 @@ from typing import Callable
 # as a pre-processing step
 
 def get_concept_resolver_registry(engine: sa.engine.Engine) -> ConceptResolverRegistry:
+    """
+    Create a resolver registry bound to the supplied SQLAlchemy engine.
+    """
     return ConceptResolverRegistry(engine)
 
 
@@ -25,6 +28,9 @@ def build_parent_resolver(
         corrections: list[Callable] = [],
         unknown_concept_id: int = UNKNOWN["generic"].concept_id
 ) -> ConceptResolver:
+    """
+    Build a resolver from one or more OMOP parent concepts.
+    """
     return make_concept_resolver(
         session,
         name=resolver_name,
@@ -40,9 +46,12 @@ def build_stage_resolver(
         parent_list: list[int], 
         stage_name: str
 ) -> ConceptResolver:
+    """
+    Build a staging resolver with the standard TNM correction pipeline.
+    """
     return build_parent_resolver(
         session,
         resolver_name=f"tnm_{stage_name}_stage",
         parent_list=parent_list,
         corrections=[strip_uicc, make_stage],
-    )
+    )

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/semantics/runtime_lookups.py

@@ -54,16 +54,25 @@ DEFAULT_RESOLVER_BUILDERS = {
 }
 
 def get_registry_engine(env_path: str = __file__):
+    """
+    Build the engine used for runtime resolver lookup.
+
+    If ``ENGINE`` is not already defined in the environment, the function asks
+    ``omop-alchemy`` to load environment configuration relative to ``env_path``.
+    """
     if os.environ.get("ENGINE") is None:
         load_environment(env_path)
     engine_string = get_engine_name()
     return sa.create_engine(engine_string, future=True, echo=False)
 
 def get_runtime_resolvers(engine: sa.Engine) -> ConceptResolverRegistry:
+    """
+    Return a resolver registry populated with the default resolver builders.
+    """
     resolver_registry = get_concept_resolver_registry(engine)
 
     # Register all known resolvers up-front (lazy build)
     for name, builder in DEFAULT_RESOLVER_BUILDERS.items():
         resolver_registry.register(name, builder)
 
-    return resolver_registry
+    return resolver_registry

omop_constructs-0.4.2/src/omop_constructs/services/__init__.py

@@ -0,0 +1,5 @@
+"""
+Small helper services used alongside the construct layer.
+
+These are thin convenience functions rather than registered construct classes.
+"""

{omop_constructs-0.4.0 → omop_constructs-0.4.2}/src/omop_constructs/typing.py

@@ -4,6 +4,9 @@ from .core.plan import ConstructNode, topo_sort
 
 @runtime_checkable
 class SupportsMaterializedView(Protocol):
+    """
+    Protocol for ORM classes backed by materialized view definitions.
+    """
     __mv_name__: str
     __mv_select__: sa.sql.Select
     __deps__: tuple[str, ...]
@@ -19,6 +22,9 @@ class SupportsMaterializedView(Protocol):
 
 @runtime_checkable
 class SupportsConstructRegistry(Protocol):
+    """
+    Protocol for registry-like lifecycle managers.
+    """
     def create_all(self, bind: Any) -> None: ...
     def refresh_all(
         self,
@@ -31,12 +37,15 @@ class SupportsConstructRegistry(Protocol):
 
 @runtime_checkable
 class SupportsSelectable(Protocol):
+    """
+    Protocol for objects that can emit a SQLAlchemy ``Select``.
+    """
     def select(self) -> sa.sql.Select: ...
 
 
 @runtime_checkable
 class SupportsQueryFactory(Protocol):
     """
-    Factory that produces SQLAlchemy Selectables
+    Factory that produces SQLAlchemy ``Select`` objects.
     """
     def build(self) -> sa.sql.Select: ...