---
title: "Linking information between FHIR resources"
author: "Vincent J. Carey, stvjc at channing.harvard.edu"
date: "`r format(Sys.time(), '%B %d, %Y')`"
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Linking information between FHIR resources}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document:
    highlight: pygments
    number_sections: yes
    theme: united
    toc: yes
---

```{r setup,results="hide",echo=FALSE}
suppressPackageStartupMessages({
suppressMessages({
library(BiocFHIR)
library(DT)
library(jsonlite)
library(graph)
library(igraph)
})
})
```

# Introduction

The purpose of this vignette is to provide
details on how FHIR documents are
transformed to graphs in BiocFHIR.

This text uses R commands that will work for an R (version 4.2 or greater) in which
BiocFHIR (version 0.0.14 or greater) has been installed.  The source codes are
always available at [github](https://github.com/vjcitn/BiocFHIR) and may
be available for installation by other means.

# Examining sample data, again

In the "Upper level FHIR concepts" vignette, we used the
following code to get a peek at the information
structure in a single document representing a Bundle
associated with a patient.

```{r takepeek}
tfile = dir(system.file("json", package="BiocFHIR"), full=TRUE)
peek = jsonlite::fromJSON(tfile)
names(peek)
peek$resourceType
names(peek$entry)
length(names(peek$entry$resource))
class(peek$entry$resource)
dim(peek$entry$resource)
head(names(peek$entry$resource))
```

We perform a first stage of transformation with `process_fhir_bundle`:
```{r txpeek}
bu = process_fhir_bundle(tfile)
bu
```

# A graph relating patients to conditions

```{r lkg1}
data(allin)
g = make_condition_graph(allin)
g
names(g)
```

We made a new S3 class to hold the graph with some convenient metadata.
Ultimately that metadata should be bound into the graph itself as nodeData
and edgeData components.

Because basic identifying information is decomposed into components
in FHIR, we have a utility to acquire the patient name for a given bundle.

```{r lkn}
getHumanName(allin[[1]]$Patient)
```

The edges emanating from the node corresponding to this patient are conditions that have
been recorded.  Edges are retrieved using the `edgeL` method.

```{r lke}
library(graph)
nodes(g$graph)[edgeL(g$graph)[["Ankunding277D'Amore443"]]$edges]
```

# Adding procedures to the graph

We have been unable so far to see how procedures
can be linked directly to conditions, except by
association with a given patient.  We
add the procedure information as follows:

```{r showa}
g = add_procedures(g, allin)
g
```

Data on additional resources can be added using
the methods of `add_procedures`.  This
will be carried out in future
releases.

# Interactive visualization of the graph

A visNetwork widget can be produced directly
from a list of ingested bundles.  This display can
be zoomed and dragged.  Procedures are green, patients
are blue, conditions are red.

```{r morep}
display_proccond_igraph( build_proccond_igraph( allin ))
```

# Conclusions

This collection of vignettes shows some approaches to
working with FHIR R4 JSON using R.  It is very likely that
a new collection of bundles obtained from a different source
would not be properly ingested or transformed by the code
present in this version of BiocFHIR.  Future extensions of
the package will employ direct analysis of JSON structures
to identify data values and relationships, that should be more
adaptable to diverse collections of documents.

Relationships among resources may be represented in many
different ways.  This survey of the resources in the synthea
bundles is surely limited, perhaps even with respect to the
information available in the bundles.  FHIR experts are invited
to identify gaps in this implementation.  We anticipate
considerable additional work needed to deal with other contexts
such as research studies.

# Session information

```{r lksess}
sessionInfo()
```