PIQITT Contest Demo (Synthetic HL7 v2 → FHIR → PIQI → IRIS)

This repo is a contest-focused, end-to-end demo that:

Generates synthetic HL7 v2 messages (ADT^A01 + ORU^R01)
Converts HL7 v2 → FHIR Bundle
Runs PIQI (data quality) scoring against the FHIR Bundle
Stores the annotated FHIR Bundle + PIQI summary in InterSystems IRIS via a REST service
Browses results in a lightweight Streamlit UI

This project uses synthetic data only (no PHI).

Note: This repo does not require Docker. Run IRIS however you prefer (local install, VM, Docker, etc.).
The only requirement is that the IRIS REST web app is reachable from your machine.

Repo layout

scripts_generate_hl7.py
Generates synthetic HL7 v2 .hl7 files into ./out
scripts/hl7_out_to_piqi.py
Reads .hl7 files from ./out, converts to FHIR, runs PIQI, and writes:
- out/fhir_bundles.ndjson
- out/fhir_bundles_annotated.ndjson
- out/piqi_scores.ndjson
scripts/post_annotated_bundles_to_iris.py
Reads out/fhir_bundles_annotated.ndjson and POSTs bundles to IRIS REST API
scripts/summarize_piqi_scores.py
Summarizes PIQI scores from out/piqi_scores.ndjson
app.py
Streamlit UI to run the pipeline and browse IRIS stored bundles
lib/PIQITT.REST.BundleService.cls
IRIS REST service that persists bundles and exposes:
- POST /bundle
- GET /bundle/{id}
- GET /bundles
- POST /wipe (admin/demo reset)
config/
PIQI evaluator configuration:
- piqi_sam_library.yaml
- profile_clinical_minimal.yaml
- plausibility.yaml

Prerequisites

Python 3.10+
InterSystems IRIS (IRIS for Health Community Edition is fine)
IRIS REST web app configured (example): /csp/piqitt/api
- Dispatch class: PIQITT.REST.BundleService
- Namespace: whichever you compiled the class into (example: DATADEMO)
- Authentication: password (basic auth)

Python setup

Create and activate a virtualenv, then install deps:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Step 1: Generate HL7 v2 Files

python scripts_generate_hl7.py --n 10 --out out --per-encounter

This writes .hl7 files into ./out

Step 2: Convert HL7 to FHIR and Score PIQI

python -m scripts.hl7_out_to_piqi `
  --sam config/piqi_sam_library.yaml `
  --profile config/profile_clinical_minimal.yaml `
  --plausibility config/plausibility.yaml

Outputs written under ./out:

fhir_bundles.ndjson
fhir_bundles_annotated.ndjson
piqi_scores.ndjson

Step 3: Summarize PIQI scores

python -m scripts.summarize_piqi_scores

Step 4: Post annotated bundles to IRIS

python -m scripts.post_annotated_bundles_to_iris `
  --base http://localhost:30000/csp/piqitt/api `
  --user _SYSTEM `
  --password demo `
  --limit 5

Verify

curl.exe -u _SYSTEM:demo http://localhost:30000/csp/piqitt/api/bundles

Step 5: Run the Streamlit UI

streamlit run app.py

In the UI you can:

generate HL7
convert + PIQI score
post bundles to IRIS
browse stored bundles + view full JSON
wipe IRIS demo data (POST /wipe)

piqitt-contest