Metadata-Version: 2.4
Name: longitudinal-emr
Version: 0.1.1
Summary: Build auditable longitudinal patient timelines from tabular EMR data
Author: Gururajan G
License: Apache-2.0
Project-URL: Homepage, https://github.com/gururajang/longitudinal-emr
Project-URL: Repository, https://github.com/gururajang/longitudinal-emr
Project-URL: Issues, https://github.com/gururajang/longitudinal-emr/issues
Keywords: EMR,healthcare,longitudinal,patient-journey,clinical-data
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: plotly>=5.18
Requires-Dist: pyarrow>=14.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# longitudinal-emr

Build auditable longitudinal patient timelines from tabular EMR data.

`longitudinal-emr` converts heterogeneous EMR extracts (patients, encounters,
diagnoses, labs, medications) into a canonical long-format event table, then
constructs per-patient chronological timelines, care episodes, leakage-safe
lookback/outcome windows, and trajectory features suitable for descriptive
analysis, multi-state modelling, and ML pipelines.

## Why

EMR data usually arrives as separate tables with inconsistent naming and
granularity. Analysts need a single ordered view of what happened to a
patient over time, alongside safeguards that prevent future information
from leaking into features used to predict past or present outcomes.

## Key features

- Configuration-driven mapping layer (YAML) so source column names and file
  layouts can vary by hospital or extract without touching package code
- Canonical `events_long` schema validated with Pydantic
- Automated data-quality report (missing dates, admission/discharge order,
  duplicate events, unmapped codes)
- Per-patient timeline construction
- Encounter/episode grouping
- Leakage-safe index-date, lookback-window, and outcome-window utilities
- Core trajectory features: utilisation, lab recency/trend, condition
  burden, medication changes
- Interactive Plotly patient-timeline visualisation
- CSV/Parquet export
- Synthetic EMR data generator for safe local development

## Installation

```bash
pip install longitudinal-emr
```

For local development:

```bash
git clone https://github.com/gururajang/longitudinal-emr.git
cd longitudinal-emr
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
```

## Quick start (synthetic data)

```bash
python examples/run_demo.py
```

This generates a synthetic diabetes/COPD patient cohort, builds the
canonical event table, runs the data-quality report, constructs timelines
and features, and writes an interactive HTML timeline plus CSV/Parquet
exports to `examples/output/`.

## Quick start (your own data via mapping.yml)

```python
from longitudinal_emr import dataset_from_mapping

dataset = dataset_from_mapping("mapping.yml", data_dir="./deidentified_extract")
events = dataset.to_events()
```

See `examples/mapping.yml` for the template mapping source columns and
filenames to the canonical schema.

## Project layout

```text
src/longitudinal_emr/
  schemas/      canonical event + validation models
  ingest/       CSV/Parquet/mapping-driven loaders
  transform/    standardisation, deduplication, temporal utilities
  timeline/     timeline + episode builders, window utilities
  features/     utilisation, labs, medications, trajectory features
  visualize/    interactive Plotly timeline
  synthetic/    synthetic EMR data generator
```

## Data privacy

This repository ships only synthetic example data. Never commit real
patient-level EMR extracts, internal code lists, or de-identified hospital
data to this public repository.

## License

Apache License 2.0. See `LICENSE`.
