Lab #2. Observation FHIR resource.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table width=\"100%\" border=\"0\">\n",
    "<tr>\n",
    "<td width=\"50%\" bgcolor=\"#FFF\" border=\"1\">\n",
    "<a href=\"https://www.health-samurai.io/\">\n",
    "<img src=\"images/health-samurai.png\" alt=\"Health Samurai\" align=\"left\" />\n",
    "</a>\n",
    "</td>\n",
    "<td width=\"50%\" bgcolor=\"#FFF\">\n",
    "<a href=\"http://beda.software/\">\n",
    "<img src=\"images/beda-software.png\" alt=\"Beda.Software\" align=\"right\" />\n",
    "</a>\n",
    "</td>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Laboratory work #2. Observation FHIR resource\n",
    "\n",
    "A clinical coordinator  asked John about his complaints to clarify how we can help.\n",
    "John explained, he doesn't feel well this week. It’s related to the temperature and high blood pressure.  This started to happen on Monday (10-20-2018)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1 Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1 Import library"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the beginning we need to import libraries `fhirpy` and `os`.  \n",
    "Also, we import `pprint` helper function from local `utils.py` file. We'll use `pprint` to display some structures."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import fhirpy\n",
    "\n",
    "from utils import pprint"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.2 Create an instance of connection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To load data from FHIR server we should instantiate `FHIRClient` class from `fhirpy` package.  \n",
    "Let's pass `url` and `authorization` arguments from environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "client = fhirpy.AsyncFHIRClient(\n",
    "    url=os.environ['BOX_URL'] + '/fhir', \n",
    "    authorization=os.environ['BOX_AUTHORIZATION'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we are able to operate with FHIR resources using `client`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2 Load data from the FHIR server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1 Load list of observations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Observation](https://www.hl7.org/fhir/observation.html) is a central element in healthcare, used to support a diagnosis, monitor progress, determine baselines and patterns and even capture demographic characteristics. Most observations are simple name/value pair assertions with some metadata, but some observations group other observations together logically, or even are multi-component observations.\n",
    "\n",
    "Usage of [Observation](https://www.hl7.org/fhir/observation.html) resource includes:\n",
    "\n",
    "* Vital signs such as body weight, blood pressure, and temperature\n",
    "* Laboratory Data like blood glucose, or an estimated GFR\n",
    "* Imaging results like bone density or fetal measurements\n",
    "* Devices Measurements such as EKG data or Pulse Oximetry data\n",
    "* Clinical assessment tools such as APGAR or a Glasgow Coma Score\n",
    "* Personal characteristics: such as eye-color\n",
    "* Social histories like tobacco use, family support, or cognitive status\n",
    "* Core characteristics like pregnancy status, or a death assertion\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "observations = await client.resources('Observation').limit(10).fetch()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This line fetched a portion of data in size of 10 from the server. You can see the result of its execution.  \n",
    "It is a list containing resource representations for a `Observation`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "observations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can display all data from the `Observation`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(observations[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3 Create Observation record"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two patient's claims:  \n",
    "* On Monday his temperature was 96.8 F and the blood pressure was 140/90.\n",
    "* On Tuesday his temperature was 100.4 F and the blood pressure was 120/80.\n",
    "\n",
    "The category of our claims is defined by the `category` field of the `Observation`. This field is of type [CodeableConcept](https://www.hl7.org/fhir/datatypes.html#CodeableConcept). \n",
    "\n",
    "[CodeableConcept](https://www.hl7.org/fhir/datatypes.html#CodeableConcept) consists of a terminology (`coding` field of type [Coding](https://www.hl7.org/fhir/datatypes.html#Coding)). We are going to use it in our formal description  \n",
    "and a plain text problem explanation (`text` field of type [string](https://www.hl7.org/fhir/datatypes.html#string)). When none of the `coding` elements are marked as `userSelected`,  \n",
    "the `text` (if present) is the preferred source of meaning.\n",
    "\n",
    "Within [Coding](https://www.hl7.org/fhir/datatypes.html#Coding) we can refer to a particular `system` and `code`.\n",
    "\n",
    "`Observation` defines its `category.coding` in terms of [observation-category](https://www.hl7.org/fhir/valueset-observation-category.html), so this is our `category.coding.system`.\n",
    "\n",
    "[observation-category](https://www.hl7.org/fhir/valueset-observation-category.html) contains multiple concepts, you can read up on them in the official FHIR specification.  \n",
    "Patient's claims contain information about the body temperature and the blood pressure, so we choose `vital-signs` as the `category.coding.code`.\n",
    "\n",
    "From [vital-signs structure definition](https://www.hl7.org/fhir/vitalsigns.html) we can verify our `category` value (that we've figured out above) and find out what the `code` value is.\n",
    "\n",
    "`Observation.category`:\n",
    "* `coding.system` - `http://hl7.org/fhir/observation-category`\n",
    "* `coding.code` - `vital-signs`\n",
    "\n",
    "So we were right with our `category` configuration. Now let's find out the `code` value.\n",
    "\n",
    "`Observation.code`:\n",
    "* `coding.system` - `http://loinc.org`\n",
    "* `coding.code` - one of the [allowed vital sign result types](https://www.hl7.org/fhir/valueset-observation-vitalsignresult.html), in our case it is `8310-5` for body temperature, `8480-6` for systolic blood pressure and `8462-4` for diastolic blood pressure."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we clarified `Observation` `category` and `code`. Let's create an `Observation` object.\n",
    "\n",
    "Before we do that, please read a small note about `Observation` [status](https://www.hl7.org/fhir/valueset-observation-status.html) field: it is used to specify what the current status of an observation is.  \n",
    "There are multiple values defined in the [FHIR specification]((https://www.hl7.org/fhir/valueset-observation-status.html)), some of them are:\n",
    "* `registered` - The existence of the observation is registered, but there is no result yet available.\n",
    "* `preliminary` - This is an initial or interim observation: data may be incomplete or unverified.\n",
    "* `final` - The observation is complete."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "observation = client.resource(\n",
    "    'Observation',\n",
    "    status='preliminary',\n",
    "    category=[{\n",
    "        'coding': [{\n",
    "            'system': 'http://hl7.org/fhir/observation-category',\n",
    "            'code': 'vital-signs'\n",
    "        }]\n",
    "    }],\n",
    "    code={\n",
    "        'coding': [{\n",
    "            'system': 'http://loinc.org',\n",
    "            'code': '8310-5'\n",
    "        }]\n",
    "    })"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Observation` has a field called `valueQuantity` (of type [Quantity](https://www.hl7.org/fhir/datatypes.html#Quantity)) it contains current results of measurements performed.  \n",
    "According to [vital-signs structure definition](https://www.hl7.org/fhir/vitalsigns.html) for `vital-signs` category this field can be populated with (remember, it is of [Quantity](https://www.hl7.org/fhir/datatypes.html#Quantity) type):\n",
    "* `system` - `http://unitsofmeasure.org`\n",
    "* `value` - represents one numeric value\n",
    "* `code` - UCUM (stands for *The Unified Code for Units of Measure*) unit code from [Vital Signs Units](https://www.hl7.org/fhir/valueset-ucum-vitals-common.html)\n",
    "\n",
    "So, on Monday (10-20-2018) our patient has a temperature of 96.8F let's write it in the observation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "observation['effectiveDateTime'] = '2018-10-20'\n",
    "\n",
    "observation['valueQuantity'] = {\n",
    "    'system': 'http://unitsofmeasure.org',\n",
    "    'value': 96.8,\n",
    "    'code': 'degF'\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We've just created our first `Observation` object. Let's connect the `Observation` to the `Patient` from *Lab 1* before saving to the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient = await client.resources('Patient').search(name=['John', 'Thompson']).first()\n",
    "patient"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Patient` reference is stored in `Observation.subject`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "observation['subject'] = patient.to_reference()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await observation.save()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's figure out what the current observation state is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(observation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: the patient weight is 85 kilograms, please, add this information as an observation using the temperature example above (remember using [vital-signs structure definition](https://www.hl7.org/fhir/vitalsigns.html), [allowed vital sign result types](https://www.hl7.org/fhir/valueset-observation-vitalsignresult.html) and [vital signs units](https://www.hl7.org/fhir/valueset-ucum-vitals-common.html))."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "weight_observation = client.resource(\n",
    "    'Observation',\n",
    "    status='preliminary',\n",
    "    category=[{\n",
    "        'coding': [\n",
    "            # Write code here\n",
    "        ]\n",
    "    }],\n",
    "    code={\n",
    "        'coding': [\n",
    "            # Write code here\n",
    "        ]\n",
    "    },\n",
    "    effectiveDateTime='2018-10-20',\n",
    "    valueQuantity={\n",
    "        # Write code here\n",
    "    },\n",
    "    subject=patient.to_reference()\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(weight_observation)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await weight_observation.save()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's create `Observation` object for the blood pressure.\n",
    "\n",
    "Blood pressure value is built up of two parts: systolic and diastolic, and we have to specify both of them in the same `Observation`. For this purpose there is a special field in `Observation` object called `component`. Each `component` field consists of `code` and `valueQuantity`. For `Observation` with multiple components we have to specify section header code. For blood pressure this code is `55284-4` from `http://loinc.org` system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "blood_pressure_observation = client.resource(\n",
    "    'Observation',\n",
    "    status='preliminary',\n",
    "    category=[{\n",
    "        'coding': [{\n",
    "            'system': 'http://hl7.org/fhir/observation-category',\n",
    "            'code': 'vital-signs'\n",
    "        }]\n",
    "    }],\n",
    "    code={\n",
    "        'coding': [{\n",
    "            'system': 'http://loinc.org',\n",
    "            'code': '55284-4'\n",
    "        }]\n",
    "    },\n",
    "    component=[\n",
    "        {\n",
    "            'code': {\n",
    "                'coding': [{\n",
    "                    'system': 'http://loinc.org',\n",
    "                    'code': '8480-6'\n",
    "                }]\n",
    "            },\n",
    "            'valueQuantity': {\n",
    "                'system': 'http://unitsofmeasure.org',\n",
    "                'value': 140,\n",
    "                'code': 'mmHg'\n",
    "            }\n",
    "        },\n",
    "        {\n",
    "            'code': {\n",
    "                'coding': [{\n",
    "                    'system': 'http://loinc.org',\n",
    "                    'code': '8462-4'\n",
    "                }]\n",
    "            },\n",
    "            'valueQuantity': {\n",
    "                'system': 'http://unitsofmeasure.org',\n",
    "                'value': 90,\n",
    "                'code': 'mmHg'\n",
    "            }\n",
    "        }\n",
    "    ],\n",
    "    effectiveDateTime='2018-10-20',\n",
    "    subject=patient.to_reference()\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await blood_pressure_observation.save()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(blood_pressure_observation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Create observations for Tuesday values of the blood and the pressure using examples given above.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tuesday_temperature_observation = client.resource(\n",
    "    'Observation',\n",
    "    # Write code here\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tuesday_blood_pressure_observaion = client.resource(\n",
    "    'Observation',\n",
    "    # Write code here\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4 Work with related resources"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We've just created our first two observations. Let's see how to make a search. \n",
    "We can use `patient` search parameter to find all the patient's observations.\n",
    "There are multiple [search parameters](https://www.hl7.org/fhir/observation.html#search) defined for `Observation`. With `patient` we can search for observations which belong to the patient we've created before by giving patient's `id` as an argument. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await client.resources('Observation').search(patient=patient['id']).fetch_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, there are multiple observations registered for the patient.\n",
    "\n",
    "To do the reverse search for `Patient` based on a reference in `Observation` we can use [reverse chaining](https://www.hl7.org/fhir/search.html#has) with `_has` search parameter.  \n",
    "`_has` allows to select resources based on the properties of resources which refer to them.\n",
    "\n",
    "For example, query `GET /Patient?_has:Observation:patient:code=8310-5` will search for observations with `code=8310-5` (which is related to the body temperature). From every observation found retrieves a reference to the `Patient` this observation refers to. The patient is then included into the search result. Note that `code` here is not directly applies to `Observation` structure, it is defined as a [search parameter](https://www.hl7.org/fhir/observation.html#search) instead.\n",
    "\n",
    "Let's build the same query with `fhir-py` API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await client.resources('Patient').has('Observation', 'patient', code='8310-5').fetch_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This query returns all of the temperature `Observation`'s we've created before."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From this laboratory work you learned how to:\n",
    "* load observations from the FHIR server \n",
    "* create Observation records\n",
    "* search related resources\n",
    "* display different resorce's attributes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table width=\"100%\" border=\"0\">\n",
    "<tr>\n",
    "<td width=\"50%\" bgcolor=\"#FFF\" border=\"1\">\n",
    "<a href=\"https://www.health-samurai.io/\">\n",
    "<img src=\"images/health-samurai.png\" alt=\"Health Samurai\" align=\"left\" />\n",
    "</a>\n",
    "</td>\n",
    "<td width=\"50%\" bgcolor=\"#FFF\">\n",
    "<a href=\"http://beda.software/\">\n",
    "<img src=\"images/beda-software.png\" alt=\"Beda.Software\" align=\"right\" />\n",
    "</a>\n",
    "</td>\n",
    "</tr>\n",
    "</table>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}