Metadata-Version: 2.3
Name: oa-cohorts
Version: 0.4.0
Summary: Serialisation utilities for OMOP CDM cohorts and CQI builder
Author: Georgie Kennedy
Author-email: Georgie Kennedy <georgina.kennedy@unsw.edu.au>
Requires-Dist: omop-constructs>=0.3.24
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Requires-Dist: ipython>=8.0 ; extra == 'dev'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: mkdocs-material>=9.7.1 ; extra == 'dev'
Requires-Dist: mkdocstrings-python>=2.0.1 ; extra == 'dev'
Requires-Dist: mkdocs>=1.6.1 ; extra == 'dev'
Requires-Dist: mkdocs-mermaid2-plugin ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: myst-parser ; extra == 'docs'
Requires-Python: >=3.12
Provides-Extra: dev
Provides-Extra: docs
Description-Content-Type: text/markdown

# OA Cohorts – Reporting & Cohort Execution Engine

This package provides the core machinery for defining, executing, and inspecting cohort-based reports over OMOP-style clinical data. It’s designed to support building real-world evidence reports from composable clinical rules, measures, cohorts, and indicators, with both programmatic APIs and lightweight HTML rendering for debugging and exploration.

The framework implemented here supports configuration-driven clinical quality indicators over OMOP-harmonised data, with explicit support for disease and treatment episodes, temporality, and combinatorial logic. Measures can be defined in terms of diagnoses, treatments, procedures, observations, measurements, and demographics, and composed into clinically interpretable cohorts and indicators. 

This enables the same indicator definitions to support bulk benchmarking, trend analysis over time, and patient-level drill-down, without rewriting query logic for each use case. In practice, this provides a bridge between formal indicator specifications and the operational reality of multidisciplinary care.

At a high level, the system lets you:

* Define query rules (exact, hierarchical, scalar thresholds, phenotypes, etc.)
* Combine rules into subqueries
* Build measures from subqueries (including composite measures with AND/OR/EXCEPT logic)
* Group measures into dash cohorts and cohort definitions
* Define indicators (numerator/denominator pairs)
* Assemble everything into a report
* Execute the report against a database session and materialise results as in-memory member sets
* Inspect SQL, executability, and structure via HTML renderers (handy in notebooks)

This is intentionally object-centric: once a report is executed, downstream payloads are assembled from the resolved cohort and indicator member sets, with report-level demography fetched only for the in-scope cohort person_ids.

## What’s here (roughly)

* `Report / ReportCohortMap`: Top-level report definition, linking cohorts and indicators.
* `DashCohort / DashCohortDef`: User-facing cohort groupings backed by executable measures.
* `Measure / MeasureSQLCompiler / MeasureExecutor`: The core executable units. Measures compile to SQL, execute against a session, and materialise member sets with dating and episode context.
* `Indicator`: Numerator/denominator semantics over measures, with temporal constraints.
* `QueryRule (+ subclasses)`: The rule DSL: exact matches, hierarchies, exclusions, scalar thresholds, phenotypes, substring matches, etc.
* `HTMLRenderable mixins`: Lightweight visualisation of structure, SQL previews, and executability for debugging and exploration.

## Execution model 

```python
report.execute(session)
report.assert_executed()

rows = report.members(executor)    # all cohort members
indicators = report.indicators     # output rows are built per denominator member within the report cohort
```

### Status

This is a working internal engine under active development. APIs may shift.

## Docker

The repo includes a lightweight CLI container under `docker/docker-compose.yaml` that joins the external `cava-network` and expects an `ENGINE` SQLAlchemy URL.

Example:

```bash
cd docker
docker compose up -d oa-cohorts
docker compose exec oa-cohorts oa-cohorts --help
docker compose exec oa-cohorts oa-cohorts import-config /app/dash_config
```

The database host in `ENGINE` should be reachable on `cava-network`, for example `postgresql+psycopg2://user:password@postgres:5432/dbname`.
