Metadata-Version: 2.5
Name: hemonc-alchemy
Version: 0.1.0
Summary: SQLAlchemy-based models, regeneration tooling, and utilities for the HemOnc.org oncology terminology
Project-URL: Homepage, https://github.com/AustralianCancerDataNetwork/HemOnc_Alchemy
Project-URL: Repository, https://github.com/AustralianCancerDataNetwork/HemOnc_Alchemy
Project-URL: Issues, https://github.com/AustralianCancerDataNetwork/HemOnc_Alchemy/issues
Author-email: Georgie Kennedy <georgina.kennedy@unsw.edu.au>
License: CC-BY-NC-SA-4.0
Keywords: ETL,HemOnc,clinical-data,health-informatics,oncology,real-world-evidence,sqlalchemy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.12
Requires-Dist: oa-configurator<2.0.0,>=1.1.0
Requires-Dist: orm-loader<2.0.0,>=1.1.0
Requires-Dist: pandas>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlalchemy>=2.0.45
Requires-Dist: typer>=0.12
Provides-Extra: author
Requires-Dist: linkml-runtime>=1.9.5; extra == 'author'
Requires-Dist: linkml>=1.9.6; extra == 'author'
Requires-Dist: openpyxl>=3.1.5; extra == 'author'
Requires-Dist: pyyaml>=6.0; extra == 'author'
Provides-Extra: dev
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: linkml-runtime>=1.9.5; extra == 'dev'
Requires-Dist: linkml>=1.9.6; extra == 'dev'
Requires-Dist: mkdocs-material>=9.7.1; extra == 'dev'
Requires-Dist: mkdocs-mermaid2-plugin; extra == 'dev'
Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
Requires-Dist: mkdocstrings-python>=2.0.1; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: oa-configurator[dev,postgres]<2.0.0,>=1.1.0; extra == 'dev'
Requires-Dist: openpyxl>=3.1.5; extra == 'dev'
Requires-Dist: psycopg[binary]>=3.2; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: exploration
Requires-Dist: ipykernel>=6.29; extra == 'exploration'
Requires-Dist: ipython>=8.0; extra == 'exploration'
Requires-Dist: matplotlib>=3.9; extra == 'exploration'
Requires-Dist: psycopg[binary]>=3.2; extra == 'exploration'
Provides-Extra: omop
Requires-Dist: omop-alchemy<2.0.0,>=1.1.0; extra == 'omop'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
Description-Content-Type: text/markdown

# HemOnc Alchemy

HemOnc Alchemy turns an imported [HemOnc.org](https://hemonc.org) terminology database into typed SQLAlchemy models and composable Python queries.

The package sits between source data and an analysis or application:

```text
HemOnc extracts → generated model → toolkit queries and treatment policies → your application
```

The generated model describes the source. The toolkit helps navigate it and makes recurring treatment interpretations explicit. Your application remains responsible for cohort definitions, local protocol policy, OMOP mappings, and presentation.

## Start here

Read the [documentation](docs/index.md), beginning with the [quickstart](docs/getting-started/quickstart.md) if you already have a configured database, or [installation](docs/getting-started/installation.md) and [configuration](docs/getting-started/configuration.md) if you do not.

Before writing analytical joins, read [Understanding the HemOnc model](docs/model/index.md). The important questions are the row grain, the difference between a HemOnc CUI and an OMOP `concept_id`, and whether a latest-version policy is being applied.

## Install

```bash
uv add "hemonc-alchemy[postgres]"
```

For repository development:

```bash
uv sync --extra dev
```

For notebooks and exploratory plots:

```bash
uv sync --extra exploration
```

The optional `omop` extra adds the bridge for resolving HemOnc identifiers against an OMOP vocabulary. Docker, PostgreSQL, pgAdmin, source extracts, and clinical data are not installed by the package.

## Configure and query

```bash
omop-config configure hemonc_alchemy
```

```python
from sqlalchemy.orm import Session

from hemonc_alchemy import create_hemonc_engine, get_hemonc_context

_, database = get_hemonc_context()
engine = create_hemonc_engine(database)

with Session(engine) as session:
    ...
```

The [toolkit guide](docs/toolkit/index.md) explains when to use core model queries, treatment selection, classification, and scheduling. The [local development guide](docs/getting-started/local-development.md) describes the disposable Compose stack.

## Repository layout

```text
hemonc_alchemy/
├── model/       generated entities and hand-written relationships
├── toolkit/     model queries, treatment analytics, schedules, and loading
├── schema/      registry used to generate the model
├── compiler/    model-generation and validation code
└── config.py    database configuration
```

Model generation and source loading are maintainer operations. See [Regenerating the model](docs/maintainers/regeneration.md) before changing generated files.
