Metadata-Version: 2.4
Name: usdm4_fhir
Version: 0.11.0
Summary: A python package for importing and exporting the CDISC TransCelerate USDM, version 4, using FHIR
Author: D Iberson-Hurst
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: usdm4>=0.22.0
Requires-Dist: d4k_ms_base>=0.3.0
Requires-Dist: fhir.resources==7.1.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: python-dotenv; extra == "test"
Dynamic: license-file

# USDM4 FHIR

A Python package for converting between [CDISC](https://www.cdisc.org/) TransCelerate Unified Study Data Model (USDM), version 4, and [HL7 FHIR](https://www.hl7.org/fhir/) M11 message bundles.

Supports export (USDM to FHIR) and import (FHIR to USDM) for multiple FHIR profile versions, including PRISM2 and PRISM3 message formats, as well as a Madrid export variant.

## Features

- **Export** USDM4 study definitions to FHIR M11 Bundle JSON (PRISM2, PRISM3, Madrid)
- **Import** FHIR M11 Bundle JSON back to USDM4 study definitions (PRISM2, PRISM3)
- **Schedule of Activities** export to FHIR
- **Round-trip fidelity** testing between USDM and FHIR representations
- Built on [fhir.resources](https://pypi.org/project/fhir.resources/) (Pydantic-based FHIR R5 models)

## Installation

```bash
pip install usdm4_fhir
```

## Quick Start

### Export: USDM to FHIR

```python
from usdm4_fhir.m11.export.export_prism3 import ExportPRISM3

exporter = ExportPRISM3(study, extra)
fhir_bundle_json = exporter.to_message()
```

### Import: FHIR to USDM

```python
from usdm4_fhir.m11.import_.import_prism3 import ImportPRISM3

importer = ImportPRISM3()
wrapper = await importer.from_message("path/to/fhir_bundle.json")
study = wrapper.study
```

## Dependencies

- [usdm4](https://pypi.org/project/usdm4/) (>=0.18.0) -- USDM4 API model and assembler
- [fhir.resources](https://pypi.org/project/fhir.resources/) (==7.1.0) -- FHIR R5 resource models
- [d4k_ms_base](https://pypi.org/project/d4k-ms-base/) (>=0.3.0) -- shared microservice base

## Development

### Setup

```bash
git clone https://github.com/data4knowledge/usdm4_fhir.git
cd usdm4_fhir
python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
```

### Commands

```bash
ruff format          # Format code
ruff check           # Lint
pytest               # Run tests
```

### Build and Publish

```bash
python3 -m build --sdist --wheel
twine upload dist/*
```

## Project Structure

```
src/usdm4_fhir/
  factory/        FHIR resource factories (ResearchStudy, PlanDefinition, etc.)
  m11/
    export/       USDM to FHIR export (PRISM2, PRISM3, Madrid)
    import_/      FHIR to USDM import (PRISM2, PRISM3)
    utility/      Shared utilities (address service, HTML parsing, tag references)
  soa/
    export/       Schedule of Activities FHIR export
  utility/        Data store
tests/            Integration test suite with round-trip verification
```

## License

This project is licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE) for details.
