Make your first FHIR client in R – within one hour!

R on FHIR

R on FHIR is the latest addition to our FHIR tool suite. It is available on The Comprehensive R Archive Network (CRAN). R on FHIR is, as you can tell from the name, an R package that supports R users with fetching data from FHIR servers. It provides simple, but powerful tools to perform read, version read and search interactions on FHIR servers and fetch the resulting resources in an R friendly format.

R on FHIR consists of two classes called fhirClient and searchParams, just like our .NET API. The fhirClient provides functions to perform read and search operations and to use the FHIR paging mechanism to navigate around a series of paged result Bundles. The searchParams class provides a set of fluent calls to allow you to easily construct more complex queries. The searchParams class falls outside the scope of this blog, but you can read the documentation on R on FHIR to learn more about how to use this class. The documentation also includes some examples for both classes.

Step 0 – Install R (and RStudio)

Before we start, we need to make sure we have R with preferably RStudio installed, on our machine. See the links below. For this blog I used R version 3.2 (higher versions will also work, lower I think too, but I did not test that) and RStudio version 1.0.153.

Step 1 – Install and load R on FHIR

FHIR up (first and last pun, I promise) your RGui or RStudio and execute the following statement in your console:

# This will install R on FHIR from The Comprehensive R Archive Network.
> install.packages("RonFHIR")

Step 2 – Create a new R script

In this blog we are going to write a function which returns an overview of a population based on a postal code. Go to File > New File > R Script or hit Ctrl+Shift+N in RStudio and for RGUI File > New script. Now that we have an empty script we can start writing our function called ‘getAreaInfo’ with the postal code as our parameter. On the first line of our function we create an instance of a fhirClient. Your script should look like this:

Step 3 –Searching Patients on a FHIR server

Now that we initialized a client we can start performing a search operation on a server. The most basic search is the fhirClient’s $search. It searches all resources of a specific type based on zero or more criteria. The $search function will return a Bundle as a list containing the found ResourceEntries as a data.frame. Normally, any FHIR server will limit the number of search results returned. To obtain all results we can use $continue which uses the FHIR paging mechanism to navigate around a series of paged result Bundles. In our script below we used the $search and $continue functions to find all Patients living within the given postal code and return how the genders are distributed.

Now that our function is complete we can call it from our console, but first we have to tell R to source our code. This can be done with Code > Source or Ctrl+Shift+S in RStudio and File > Source R code… in RGUI. Now we can run our ‘getAreaInfo’ function in our R console.

> getAreaInfo(3999)
genders
female male
1 574

Congratulations! You just created your first function using a FHIR client in R to track the gender distribution in a given postal area.

Finally

This blog only showed a quick example of how you can use R on FHIR. For more details and examples you can always consult the documentation. Feel free to give feedback and join the R on FHIR development at our GitHub page.

We are planning to do a birds of a feather session during the HL7 FHIR DevDays here in Amsterdam. Hope to see you there.