Metadata-Version: 2.4
Name: omop-alchemy
Version: 0.2.2
Summary: SQLAlchemy-based models, validation, and utilities for the OHDSI OMOP Common Data Model
Author-email: Georgie Kennedy <georgie.kennedy@unsw.edu.au>
License: Apache-2.0
Project-URL: Homepage, https://github.com/AustralianCancerDataNetwork/OMOP_Alchemy
Project-URL: Repository, https://github.com/AustralianCancerDataNetwork/OMOP_Alchemy
Project-URL: Issues, https://github.com/AustralianCancerDataNetwork/OMOP_Alchemy/issues
Keywords: OMOP,OHDSI,clinical-data,health-informatics,sqlalchemy,ETL,real-world-evidence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sqlalchemy>=2.0.45
Requires-Dist: pandas>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
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: rich>=13.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# OMOP Alchemy

**OMOP Alchemy** provides a canonical, typed, SQLAlchemy-first representation of the
[OHDSI OMOP Common Data Model (CDM)](https://ohdsi.github.io/CommonDataModel/).

It is designed to support **research-ready analytics, validation, and exploration**
of OMOP data using modern Python tooling, without imposing ETL conventions or
execution-time side effects.

---

## Design goals

OMOP Alchemy is intentionally:

- **Declarative**  
  Defines tables, columns, relationships, and constraints 

- **SQLAlchemy-native**  
  Built for SQLAlchemy 2.x ORM usage

- **Safe to import anywhere**  
  No implicit engine creation, no global state, no environment assumptions.

- **Typed and inspectable**  
  Models are fully typed and introspectable for validation, tooling, and IDE support.

- **Backend-agnostic**  
  Designed to work across PostgreSQL, SQLite, and other SQLAlchemy-supported databases.

---

## What this package does *not* do

OMOP Alchemy deliberately avoids:

- Enforcing ETL conventions or data pipelines
- Auto-creating databases or loading vocabularies
- Imposing analytics frameworks or dashboards
- Making assumptions about deployment environments

These concerns are intentionally left to downstream tooling.

---

## Core features

- SQLAlchemy ORM models for OMOP CDM tables
- Explicit foreign key and relationship definitions
- Read-only *View* classes for safe navigation and analytics
- Domain validation helpers for OMOP concept integrity
- CSV loading utilities for controlled ingestion and testing
- Lightweight schema and model validation against CDM specs

---

## Example (concept navigation)

```python
from omop_alchemy.model.vocabulary import ConceptView

concept = session.get(ConceptView, 320128)  # Lung cancer
concept.domain.domain_id        # "Condition"
concept.vocabulary.vocabulary_id  # "SNOMED"
concept.is_standard             # True
```

---

## Status

This project is currently beta.

The API is stabilising, but some modules may change as real-world use cases expand. Feedback and issues are welcome.

### Some additional background

This work builds on earlier research and tooling presented at the 2023 OHDSI APAC Symposium
> see [background paper](https://github.com/AustralianCancerDataNetwork/OMOP_Alchemy/blob/main/notebooks/ORMforResearchReadyData_APAC2023.pdf).
