Skip to main content

fhir-query

Leveraging FHIR GraphDefinition for Data Traversals and Local Analysis


Overview

This project leverages FHIR GraphDefinition objects to define and execute graph-based traversals across multiple interconnected FHIR resource graphs. The data retrieved is written to a local SQLite database for persistence and later transformed into analyst-friendly dataframes for analysis using tools like Python’s pandas library.


Motivation

FHIR Search provides a robust querying framework but comes with significant limitations:

  1. Deep Chaining Limits:
    Chaining searches (e.g., Patient -> Observation -> Encounter -> Procedure) often hits server depth limitations.

  2. Inefficient Query Execution:
    Searching deeply related resources requires multiple chained requests, leading to performance issues and unnecessary round trips.

  3. Lack of Explicit Traversals:
    Relationships in FHIR are implicit in references (e.g., Observation.subject pointing to Patient). This implicit structure requires manual composition of queries, which is prone to errors.

By using FHIR GraphDefinition, we declaratively define resource relationships and efficiently retrieve data. Once retrieved, the data is stored locally and can be transformed into dataframes for advanced analysis.


Key Features

  • GraphDefinition-Driven Traversals: Use GraphDefinition objects to define explicit relationships between resources and automate traversal logic.
  • Local SQLite Storage: Persist the retrieved FHIR data in a local SQLite database for querying and offline analysis.
  • Analyst-Friendly Dataframes: Convert stored FHIR resources into pandas dataframes for ease of use in analytical workflows.
  • Reusable Graph Definitions: Maintain a library of GraphDefinition YAML files that can be reused across different workflows and projects.

Architecture

Components

  1. GraphDefinition Library

  2. Traversal Engine

    • Reads a GraphDefinition and iteratively queries the FHIR server using RESTful _include and _revinclude operations for efficiency.
    • Stores the retrieved resources in a SQLite database in JSON format for flexibility.
  3. SQLite Data Storage

    • Table Schema: see fhir_query.ResourceDB
  4. Analyst-Friendly DataFrames TODO

    • Transforms FHIR data from SQLite into pandas dataframes for easier analysis.
    • Data can be filtered, aggregated, or visualized to meet analytical use cases.

Workflow

  1. Load a GraphDefinition

    • Define a GraphDefinition object (e.g., study-to-documents) to specify the traversal path.
  2. Execute Traversal

    • Use the Traversal Engine to query the FHIR server based on the GraphDefinition.
    • Follow each link and include related resources efficiently using _include or _revinclude.
  3. Store Data Locally

    • Write the retrieved resources to the SQLite database with their resource types and full JSON representation.
  4. Transform to DataFrames TODO

    • Retrieve specific resource types or relationships from the SQLite database.
    • Convert the JSON data into structured pandas dataframes for analysis.

Usage

To use the fq command, you need to provide the necessary options. Below is an example of how to use the command:

fq --help
Usage: fq [OPTIONS] COMMAND [ARGS]...

  FHIR-Aggregator utilities.

Commands:
  ls          List all the installed GraphDefinitions.
  run         Run GraphDefinition queries.
  results     Work with the results of a GraphDefinition query.
  vocabulary  FHIR-Aggregator's key Resources and CodeSystems.

Examples:

Metadata

Release files for fhir-aggregator-client 0.1.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fhir-aggregator-client 0.1.9
File Size Uploaded Provenance Actions
fhir_aggregator_client-0.1.9.tar.gz 28.9 kB Without provenance Details for fhir_aggregator_client-0.1.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fhir-aggregator-client 0.1.9
File Interpreter ABI Platform Actions
fhir_aggregator_client-0.1.9-py3-none-any.whl Python 3 none any Details for fhir_aggregator_client-0.1.9-py3-none-any.whl

Total release size: 56.7 kB

Release files / fhir_aggregator_client-0.1.9.tar.gz

Download URL fhir_aggregator_client-0.1.9.tar.gz
Size 28.9 kB
Tags Source
SHA-256 checksum
How to use checksums
41a753f160b24bb90c6466faaec062ac3c075b929aeae6ab4f3d16a184c65316
BLAKE2b-256 checksum
How to use checksums
c8c3839057625c6d4568d22971b6d297d4b8aef3e6c7a2a6260781813a86805f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.0.0 CPython/3.12.1

Release files / fhir_aggregator_client-0.1.9-py3-none-any.whl

Download URL fhir_aggregator_client-0.1.9-py3-none-any.whl
Size 27.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
47f9f6f90ad1fd493bf5709884a8bc174d4e9bb30ac05f7c3e21c445fdd601e3
BLAKE2b-256 checksum
How to use checksums
93892a7b5be56eceec647df3e63c205e753e504d31fde8d75124e905de9487f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.0.0 CPython/3.12.1

Security for fhir-aggregator-client 0.1.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page