exercise_0.Rmd

---
title: "FHIR for Research - Exercise 0: Getting Started (R version)"
output:
  html_document:
    df_print: paged
---

## Learning Objectives

The objective for this exercise is **to introduce you to the basic mechanisms for working with FHIR.**

For this exercise, we will walk you through the following steps:

- Establish a connection to the client server.
- Format and submit a query to the server.
- Process response data from the FHIR server.
- View the resulting data to confirm that we successfully pulled data from the remote server.

We will use the `fhircrackr` library to handle querying from a FHIR server and converting the response into an R data frame.

Let's get our environment set up:

```{r setup}
library(fhircrackr)
```

## Step 1: Query the FHIR Server

First let's connect to our FHIR server for data retrieval.

Generally speaking the pattern for a RESTful GET query appended to a URL will take the form of:

```
VERB [url]/[Resource] {?parameter=[value]}
```

See <http://hl7.org/fhir/R4/http.html> for more details.

Let's attempt to do a sample load from our example FHIR server by requesting [Patient resources](https://www.hl7.org/fhir/patient.html) for the available patients.

In this case, we want to modify the general pattern with:

- `VERB` is `GET`
- `[url] = https://api.logicahealth.org/researchonfhir/open/`
- `[Resource] = Patient`

```{r}
fhir_server <- "https://api.logicahealth.org/researchonfhir/open/"
request <- fhir_url(url = fhir_server, resource = "Patient")
patient_bundle <- fhir_search(request = request, max_bundles = 1, verbose = 1)
patient_bundle
```

If the above request works, you should see a preview of the first few lines of XML representing the FHIR resources from `patient_bundle` above.

## Step 2: Convert response from server into a data frame

The `fhircrackr` library uses the `fhir_table_description()` function to translate the hierarchical XML resource returned by the FHIR server into a tabular format (i.e., a data frame) that works with typical analysis approaches in R.

This function creates a definition mapping parts of the XML representation of the resource onto columns in the data frame that will be generated. The XML elements are identified using [XPath](https://en.wikipedia.org/wiki/XPath), a query language for XML.

```{r}
table_desc_patient <- fhir_table_description(
    resource = "Patient",

    cols = c(
            id           = "id",
            given_name    = "name/given",
            family_name   = "name/family",
            gender        = "gender",
            birthday      = "birthDate",
            birthTime     = "extension[@url=\"http://hl7.org/fhir/StructureDefinition/patient-birthTime\"]/valueDateTime"
        )

)
```

Many of the XPath queries you will use wil be straight-forward, like `id` and `name/given`. In some cases, you may need to construct more complex queries like the one to extract `birthTime` from the `patient-birthTime` extension in the FHIR resource instance. You can use a tool like [this XPath tester](https://extendsclass.com/xpath-tester.html) to help generate XPaths, but be careful about pasting sensitive data into websites like this (our synthetic example data is not sensitive). For more information on XPath, see [this guide](https://www.w3schools.com/xml/xpath_intro.asp).

Once the table description is created, we can create a data frame:

```{r}
df_patient <- fhir_crack(bundles = patient_bundle, design = table_desc_patient, verbose = 0)
df_patient
```

You should see the name, gender, birthday and birth time for 50 patients.