🔥 fhiry — FHIR to Pandas DataFrame for Data Analytics, AI, and ML

FHIRy is a Python package that simplifies health data analytics and machine learning by converting FHIR bundles or NDJSON files from bulk data export into pandas DataFrames. These DataFrames can be used directly with ML libraries such as TensorFlow and PyTorch. FHIRy also supports FHIR server search and FHIR tables on BigQuery.

---

✨ Features

• Flatten FHIR Bundles/NDJSON to DataFrames for analytics and ML
• Import from FHIR Server via FHIR Search API
• Query FHIR Data on Google BigQuery
• LLM-based Natural Language Queries (see examples/llm_example.py)
• Flexible Filtering and Column Selection

---

🔧 Quick Start

Installation

Stable release:

pip install fhiry

Latest development version:

pip install git+https://github.com/dermatologist/fhiry.git

LLM support:

pip install fhiry[llm]

---

Usage

1. Import FHIR Bundles (JSON) from Folder

import fhiry.parallel as fp
df = fp.process('/path/to/fhir/resources')
print(df.info())

Example dataset: Synthea Notebook: notebooks/synthea.ipynb

---

2. Import NDJSON from Folder

import fhiry.parallel as fp
df = fp.ndjson('/path/to/fhir/ndjson/files')
print(df.info())

Example dataset: SMART Bulk Data Server Notebook: notebooks/ndjson.ipynb

---

3. Import FHIR Search Results

Fetch resources from a FHIR server using the FHIR Search API:

from fhiry.fhirsearch import Fhirsearch

fs = Fhirsearch(fhir_base_url="http://fhir-server:8080/fhir")
params = {"code": "http://snomed.info/sct|39065001"}
df = fs.search(resource_type="Condition", search_parameters=params)
print(df.info())

See fhir-search.md for details.

---

4. Import from Google BigQuery FHIR Dataset

from fhiry.bqsearch import BQsearch
bqs = BQsearch()
df = bqs.search("SELECT * FROM `bigquery-public-data.fhir_synthea.patient` LIMIT 20")

---

🚀 5. LLM-based Natural Language Queries

FHIRy supports natural language queries over FHIR bundles/NDJSON using llama-index:

pip install fhiry[llm]

See usage: examples/llm_example.py

---

🚀 6. Convert FHIR Bundles/Resources to Text for LLMs

Convert a FHIR Bundle or resource to a textual representation for LLMs:

from fhiry import FlattenFhir
import json

bundle = json.load(open('bundle.json'))
flatten_fhir = FlattenFhir(bundle)
print(flatten_fhir.flattened)

---

Filters and Column Selection

You can pass a config JSON to any constructor to remove or rename columns:

df = fp.process('/path/to/fhir/resources', config_json='{ "REMOVE": ["resource.text.div"], "RENAME": { "resource.id": "id" } }')
fs = Fhirsearch(fhir_base_url="http://fhir-server:8080/fhir", config_json='{ "REMOVE": ["resource.text.div"], "RENAME": { "resource.id": "id" } }')
bqs = BQsearch('{ "REMOVE": ["resource.text.div"], "RENAME": { "resource.id": "id" } }')

See df.columns for available columns. Example columns:

patientId
fullUrl
resource.resourceType
resource.id
resource.name
resource.telecom
resource.gender
...

---

Command Line Interface (CLI)

See CLI examples:

fhiry --help

---

Documentation

Full documentation: https://dermatologist.github.io/fhiry/

---

Contributing

We welcome contributions! See CONTRIBUTING.md.

---

Give Us a Star ⭐️

If you find this project useful, please give us a star to help others discover it.

---

Contributors

• Bell Eapen
• Markus Mandalka
• PRs welcome! See CONTRIBUTING.md