Metadata-Version: 2.4
Name: onco-scoop
Version: 0.1.0
Summary: Add your description here
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: ipykernel>=7.1.0
Requires-Dist: hemonc-alchemy<1.0,>=0.2.0
Requires-Dist: omop-alchemy<2.0,>=1.1.0
Requires-Dist: omop-graph<3.0,>=2.1.0
Requires-Dist: oa-configurator<2.0.0,>=1.0.0
Requires-Dist: pandas>=3.0.2
Requires-Dist: psycopg-binary>=2.9.11
Requires-Dist: pydantic>=2.12.3
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0.3
Provides-Extra: authoring
Requires-Dist: linkml>=1.9.6; extra == "authoring"
Requires-Dist: linkml-runtime>=1.9.5; extra == "authoring"
Provides-Extra: exploration
Requires-Dist: jupyterlab>=4.4; extra == "exploration"
Requires-Dist: nbclient>=0.10; extra == "exploration"
Requires-Dist: nbconvert>=7.16; extra == "exploration"
Requires-Dist: nbformat>=5.10; extra == "exploration"
Requires-Dist: matplotlib>=3.9; extra == "exploration"
Provides-Extra: dev
Requires-Dist: oa-configurator[dev,postgres]<2.0.0,>=1.0.0; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"

# SCOOP

SCOOP is a Python library designed to generate synthetic oncology patient data conforming to the OMOP Common Data Model (CDM). It provides tools to create realistic patient profiles, including demographics, diagnoses, treatments, and outcomes, facilitating dataset alignment and software development for healthcare analytics without compromising patient privacy.
## Key Features
* HemOnc integration — realistic longitudinal roll-out of systemic therapy regimens.
* Configurable attributes — define demographic, clinical, and molecular distributions via YAML or code.
* CDM compatibility — outputs data natively aligned to OMOP tables and concept identifiers.
* Composable design — easily extend distributions, conditional logic, and transformation rules for new disease domains.

## Principles
The functionality of SCOOP should be considered in four broad phases:
1. **Sampling**: Drawing samples from defined statistical distributions to create individual patient attributes.
2. **Simulation**: Rules-based roll out of patient trajectories based on clinical logic and treatment regimens, aligned to generated attributes.
3. **Synthesis**: Applying defined transformations to the sampled attributes to generate the final patient data
4. **Serialisation**: Converting the generated patient data into a format compatible with the OMOP CDM for storage and analysis.


## Flow

1. a Person object is created with basic attributes (sampled from flat distributions - no dependencies)
2. a Condition object is created for that person, with attributes sampled conditionally based on the Person attributes
3. a Regimen object may optionally be created for that condition x person combination, sampled conditionally based on both Person and Condition attributes
4. exposure events (procedures, drug administration events) are created based on the Regimen object
5. treatment response and outcome events are created based on the Condition and Regimen objects
6. all objects are serialised to OMOP CDM tables

## Start here

Install the project dependencies with [uv](https://docs.astral.sh/uv/):

```bash
uv sync
```

## Choose a guide

- [Documentation home](docs/index.md): find the guide for your task.
- [Treatment schedules](docs/scheduling-rollout.md): understand dates, repeated cycles, optional treatment, and unresolved timing.
- [How treatment matching works](docs/hemonc_grouping_model.md): understand how a treatment decision connects to HemOnc regimen candidates.
- [Create a profile](docs/creating_new_profile.md): add or adapt a disease profile.
- [Validate profile YAML](schema/linkml/README.md): check the canonical authoring files.

## Profiles

Profiles are YAML files under [`scoop/profiles/`](scoop/profiles/). NSCLC is the most complete example of the current graph, treatment registry, intervention catalog, and routed-profile format. See [Create a profile](docs/creating_new_profile.md) before copying or extending one.

## Development

Install development dependencies and run the test suite:

```bash
uv sync --extra dev
uv run pytest -q
```
