🔥 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.