---
title: "Upper level FHIR concepts"
author: "Vincent J. Carey, stvjc at channing.harvard.edu"
date: "`r format(Sys.time(), '%B %d, %Y')`"
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Upper level FHIR concepts}
  %\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)
})
})
```

# Introduction

The purpose of this vignette is to explore
relationships between concepts underlying
FHIR foundational concepts and
aspects of implementation 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.

# Some comments from hl7.org/fhir Executive Summary

The following are verbatim from the [executive summary](http://hl7.org/fhir/summary.html)
on Oct 5 2022.  The FHIR system is said to provide

- A strong focus on implementation: fast and easy to implement (multiple developers have had simple interfaces working in a single day)
- Multiple implementation libraries, many examples available to kick-start development
- Specification is free for use with no restrictions
- Interoperability out-of-the-box: base resources can be used as is, but can also be adapted as needed - which happens a lot - for local requirements using Profiles, Extensions, Terminologies and more
- Evolutionary development path from HL7 Version 2 and CDA: standards can co-exist and leverage each other
- Strong foundation in Web standards: XML, JSON, HTTP, OAuth, etc.
- Support for RESTful architectures, seamless exchange of information using messages or documents, and service-based architectures
- Concise and easily understood specifications
- A human-readable serialization format for ease of use by developers
- Ontology-based analysis with formal mapping for correctness (under development)

End of quotation.

# FHIR JSON documents in BiocFHIR

The file located at `dir(system.file("json", package="BiocFHIR"), full=TRUE)`
is a single JSON document produced in the Synthea project of the MITRE
Corporation.  It is an extract from a zip file provided at the [Synthea web site](https://synthea.mitre.org/downloads).  Usage notes include:

> 'Data hosted within SyntheticMass has been generated by SyntheaTM, an open-source patient population simulation made available by The MITRE Corporation.

> The data is free from cost, privacy, and security restrictions. It can be used without restriction for a variety of secondary uses in academia, research, industry, and government.

> Please cite SyntheaTM or SyntheticMass as:

> Jason Walonoski, Mark Kramer, Joseph Nichols, Andre Quina, Chris Moesel, Dylan Hall, Carlton Duffett, Kudakwashe Dube, Thomas Gallagher, Scott McLachlan, Synthea: An approach, method, and software mechanism for generating synthetic patients and the synthetic electronic health care record, Journal of the American Medical Informatics Association, Volume 25, Issue 3, March 2018, Pages 230–238, https://doi.org/10.1093/jamia/ocx079'")

A collection of 50 documents, randomly sampled from over 1100 provides at Synthea,
is available using the command `BiocFHIR::make_test_json_set()`; the documents will
be written to a temporary folder.

# Examining sample data

```{r takepeek}
peek = jsonlite::fromJSON(dir(system.file("json", package="BiocFHIR"), full=TRUE))
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))
```

There are many concepts covered in `peek$entry$resource`, but in this
document, most of them will have no content.

It is significant to note that the `resourceType` has value "Bundle".  The
meaning of this term is provided at [http://hl7.org/fhir/bundle.html](http://hl7.org/fhir/bundle.html).

Drilling down a bit further, we see that the 301 records
collected in this Bundle have resource types indicative of a clinical focus.
```{r lkcli}
table(peek$entry$resource$resourceType)
```
More details on these types
can be examined at [http://hl7.org/fhir/clinicalsummary-module.html](http://hl7.org/fhir/clinicalsummary-module.html).

# Session information

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