FHIR Python Analysis and Conversion Kit (PACK)

FHIRPACK (FHIR Python Analysis Conversion Kit) is a general purpose package that simplifies the access, analysis and representation of FHIR and EHR data. FHIRPACK was designed and developed at Institute for Artificial Intelligence in Medicine (IKIM) and the Database Systems Research Group of the University of Heidelberg (HDDBS).

About this Project

A brief description of this repository and the background of this project.

Philosophy

  • Minimalistic yet feature rich
  • CLI and API feature parity
  • Workflow friendliness
  • Extensible and flexible yet sane by default
  • Every data-manipulation step is an ETL step
  • Pandas DataFrames as primary user-facing data format

Structure

putup lib-fhirpack -p fhirpack -n 'fhirpack' -d 'A minimalistic Python package that simplifies crawling, correlating and representing FHIR resources related to individual patients or cohorts thereof.' --markdown --gitlab

.
├── AUTHORS.md
├── CHANGELOG.md
├── CONTRIBUTING.rst
├── dist (generated during build time)
├── docs (generated during build time)
├── execution.log
├── LICENSE.txt
├── logo.png
├── MANIFEST.in
├── Pipfile
├── Pipfile.lock
├── pyproject.toml
├── README.md
├── setup.cfg
├── setup.py
├── src
│   ├── fhirpack
│   └── fhirpack.egg-info
├── tests
│   ├── conftest.py
│   ├── __init__.py
│   ├── __pycache__
│   ├── test_cli.py
│   ├── test_pack.py
│   └── test_utils.py
└── tox.ini

Contributing

Describe how to contribute.

Issues

Describe how to open issues, who to assign them to, what goes where, etc.

Merge Requests

Describe how to open MRs, who to assign them to, what goes where, etc.

Architecture

Describe the architecture of the project and add an architecture diagram.

Stack

Describe the stack components in detail

Dependencies

For more information, see our Pipfile

Development

Setup

Clone this repository

git clone ssh://[email protected]:2222/main/lib-fhirpack.git

Install your virtual environment

pip install pipenv python-dotenv tox pipenv-setup
pipenv install --dev

Verify you can run the tests and build FHIR PACK via tox

tox -e; tox -e build; tox -e clean

Verify you can run the tests and execute FHIR PACK via your virtual environment

pipenv run pytest --mypkg fhirpack

pipenv run ptw --runner "pytest --testmon"

In some cases, tox can have problems installing dependencies, you can recreate the environment used by tox (under ./tox) by using tox --recreate -e py3096

Dependencies

This project only relies on pyenv or asdf, pipenv, pipenv-setup, python-dotenv, pytest, pytest-watch, pytest-picked, pytest-testmon, bump2version and tox for development, testing, building and publishing

Tool Rationale
pyenv or asdf managing multiple python versions
pipenv managing virtual environments and seemless environment setup
tox one single tool for testing, packaging and publishing
pytest running unit tests
pytest-picked running only unit tests of code that has been changed
pytest-watch run unit tests continuously
python-dotenv use .env variables within tox.ini seemlesly
pipenv-setup automatically populate Python’s setup.py requirements
bump2version simple version management

Jupyter Notebook

You can use Jupyter, JupyterLab or VSCode’s Jupyter Plugin to use and improve usage.py and samples.py. However, keep in mind to not upload notebook outputs as they bloat the files and are irrelevant to the reader. To prevent that, execute echo -e '[filter "strip-notebook-output"]\n\tclean = jupyter nbconvert --ClearOutputPreprocessor.enabled=True --to=notebook --stdin --stdout --log-level=ERROR' >> .git/config within the repository. That line defines a clean for Jupyter notebooks that git can then use for all .ipynb files as described in .gitattributes

VS Code

tox -e clean

Testing

pipenv run pytest tests

ptw --runner "pytest --testmon"

tox

pipenv run pytest -s --use-running-containers --docker-compose-no-build --pyargs fhirpack tests

ptw -- -s --use-running-containers --docker-compose-no-build --pyargs fhirpack tests -m 'not reqdocker'

Releasing

bumpversion --allow-dirty patch ; cat VERSION

https://peps.python.org/pep-0440/

tox -e build

tox -e publish

Usage

CLI

The CLI can be invoked by using python -m fhirpack.cli or fp.

> fp --help                                
Usage: fp [OPTIONS]

  The pack for your FHIR server.

Options:
  --version               Show the version and exit.
  -s, --source TEXT       URL of the FHIR server or path to json files.
  -e, --environment TEXT  Path to Dotenv file containing configurations.
  -d, --destination TEXT  Location of the output.
  -o, --operation TEXT    Operations to retrieve data.
  -p, --params TEXT       Provide additional search parameters.
  -v, --verbose           Print results in verbose format.
  -h, --help              Show this message and exit.

CLI usage is analogous to the general fhirpack dataflow.

python shell
pack.getPatients(["1"]) fp -o "getPatients 1"
pack.getPatients(["1", "181", "525"]) fp -o "getPatients 1, 181, 525"
PACK(envFile=".../env.example").getPatients(["1"]) fp -e .env.example -o "getPatients 1"
pack.getPatients(searchParams={}).gatherSimplePaths(["name.family"]) fp -o "getPatients" -p all -o "gatherSimplePaths name.family"
pack.getPatients(searchParams={"family":"Koepp"}) fp -o "getPatients" -p "family = Koepp"

Of note, operations spanning mutliple spaces have to be quoted.

Python with .env File

client=fp.utils.clientFromEnv()
pack= fp.pack.PACK(client)

Python with Manual Client Definition

import fhirpy
client = fhirpy.SyncFHIRClient("http://127.0.0.1:32112/hapi-fhir-jpaserver/fhir/")
pack  = fp.pack.PACK(client)
pack.getPatient('1').to_resource().serialize()

References

List any important or related reading material

Acknowledgements

Acknowledge contributors

GitHub

View Github