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

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

1. Generates synthetic HL7 v2 messages (ADT^A01 + ORU^R01)
2. Converts HL7 v2 → FHIR Bundle
3. Runs PIQI (data quality) scoring against the FHIR Bundle
4. Stores the annotated FHIR Bundle + PIQI summary in InterSystems IRIS via a REST service
5. 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)