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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: omop-constructs
-Version: 0.4.1
+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>

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

@@ -1,6 +1,6 @@
 [project]
 name = "omop-constructs"
-version = "0.4.1"
+version = "0.4.2"
 description = "For building complex constructs on top of the omop-alchemy library."
 readme = "README.md"
 authors = [

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.1 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/episodes/consult_window_mv.py

@@ -15,6 +15,13 @@ 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"
@@ -30,6 +37,7 @@ class ConsultWindowMV(MaterializedViewMixin, Base):
     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
     )

{omop_constructs-0.4.1 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/episodes/consult_window_query.py

@@ -1,3 +1,11 @@
+"""
+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
 
@@ -13,6 +21,9 @@ 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),
@@ -24,6 +35,7 @@ episode_of_care = (
         Episode.person_id,
         Episode.episode_id,
         Episode.episode_start_date,
+        Episode.episode_concept_id,
     )
     .where(
         Episode.episode_concept_id
@@ -141,6 +153,7 @@ specialist_trajectory = (
         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,
@@ -183,6 +196,7 @@ consult_window = (
         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,

{omop_constructs-0.4.1 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/events/dx_linked_visit_mv.py

@@ -11,6 +11,9 @@ 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)
@@ -40,6 +43,12 @@ class ConditionEpisodeVisitCols:
 
 @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"

{omop_constructs-0.4.1 → omop_constructs-0.4.2}/src/omop_constructs/alchemy/events/visit_queries.py

@@ -1,3 +1,11 @@
+"""
+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
 

{omop_constructs-0.4.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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: ...