Lab #5. Encounter 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 #5. FHIR resource Encounter\n",
    "\n",
    "John Thompson finally arrives at the clinical center and has just started his visit with the practitioner Kelly Smith.\n",
    "He told Kelly about his concerns about fever and high blood pressure.\n",
    "So, Kelly checked the current temperature and the blood pressure: 96.8 F and 130/80.\n",
    "Kelly diagnosed hypertension and requested some blood tests to diagnose the cause of the fever.\n",
    "\n",
    "Let’s create an Encounter to track the visit."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1 Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1 Import library"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the beginning we should import the `fhirpy` and `os` libraries.  \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",
    "We 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 related resources"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Before creating `Encounter` resource you need to find the patient - `John Thompson`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient = await client.resources('Patient').search(\n",
    "    # Write code here\n",
    ").first()\n",
    "patient"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Next you need to find the practitioner - `Kelly Smith`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "practitioner = await client.resources('Practitioner').search(\n",
    "    # Write code here\n",
    ").first()\n",
    "practitioner"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The clinical center where our patient has finally arrived is `Hahnemann University Hospital`\n",
    "\n",
    "**Exercise**: Find `Location` resource for the clinical center 'Hahnemann University Hospital'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "location = await client.resources('Location').search(\n",
    "    # Write code here\n",
    ").first()\n",
    "location"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And finally load `Appointment` that scheduled this `Encounter`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "appointment = await client.resources('Appointment').search(actor=patient['id']).first()\n",
    "appointment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3 Encounter Resource"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Encounter](https://www.hl7.org/fhir/encounter.html) is an interaction between a patient and healthcare provider for the purpose of providing healthcare service or assessing the health status of a patient.\n",
    "\n",
    "An `Encounter` encompasses the lifecycle from pre-admission, the actual encounter, admission, stay and discharge. During the encounter the patient may move from practitioner to practitioner and location to location.\n",
    "\n",
    "`Encounter` has a broad scope, so some components may be irrelevant to a specific context, the `class` element is used to distinguish between settings.\n",
    "\n",
    "Different orgranizations may have different level of aggregation for `Encounter`. For example, during hospitalization each single visit of a practitioner may lead to a new instance of `Encounter`, but in other orgranization the whole hospitalization may be defined in terms of a single `Encounter`.  \n",
    "\n",
    "We use `Appointment` for the planning stage. When the appointment is about to start, we create a new `Encounter` and mark `Appointment` object as fulfilled."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1 Load Encounter resources"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's search for existent `Encounter` resources before creating one"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "encounters = await client.resources('Encounter').search(subject=patient['id']).first()\n",
    "encounters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2 Create Condition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Condition](https://www.hl7.org/fhir/condition.html) resource can be used to describe information about illness identified from application of clinical reasoning. It is important to distinguish `Condition` from `Observaion`, we use `Observation` when a symptom contributes to the establishment of a condition. `Condition` on the other hand is about a clinician's assessment and assertion of a particular aspect of a patient's state of healt.\n",
    "\n",
    "Let's create `Condition` for hypertension. Hypertension is encoded as `38341003` in `http://snomed.info/sct` system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "condition = client.resource(\n",
    "    'Condition',\n",
    "    id='condition_for_john_thompson',\n",
    "    code={'coding': [{'system': 'http://snomed.info/sct', 'code': '38341003'}]},\n",
    "    subject=patient\n",
    ")\n",
    "condition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.3 Create Encounter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we've all the information required, we can finally register our `Encounter`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "encounter = client.resource(\n",
    "    'Encounter',\n",
    "    id='encounter_for_john_thompson',\n",
    "    status='in-progress',\n",
    "    subject=patient,\n",
    "    participant=[{\n",
    "        'type': [{\n",
    "            'coding': [{\n",
    "                'system': 'http://hl7.org/fhir/v3/ParticipationType',\n",
    "                'code': 'PPRF'\n",
    "            }]\n",
    "        }],\n",
    "        'individual': practitioner\n",
    "    }],\n",
    "    appointment=appointment,\n",
    "    diagnosis=[{'condition': condition}],\n",
    "    location=[{'location': location, 'status': 'active'}]\n",
    ")\n",
    "encounter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.4 Register symptoms with Observation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can link `Observation` resource to `Encounter` with `Observation.context`.\n",
    "\n",
    "**Exercise**: You need to register the observations:\n",
    "* temperature 96.8 F\n",
    "* blood pressure 130/80\n",
    "\n",
    "and link them to the encounter we've just created."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temperature_observation = client.resource(\n",
    "    'Observation',\n",
    "    id='temperature_observation_for_john_thompson',\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",
    "    },\n",
    "    effectiveDateTime='2018-09-16',\n",
    "    # Write code here\n",
    ")\n",
    "temperature_observation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "blood_pressure_observation = client.resource(\n",
    "    'Observation',\n",
    "    id='blood_pressure_observation_for_john_thompson',\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",
    "    effectiveDateTime='2018-09-16',\n",
    "    # Write code here\n",
    ")\n",
    "blood_pressure_observation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this laboratory work we've discussed:\n",
    "* How to search for `Encounter`\n",
    "* How to create `Condition`\n",
    "* What is the difference between `Condition` and `Observation`\n",
    "* How to create `Encounter`\n",
    "* How to link `Condition` and `Observation` to `Encounter`"
   ]
  },
  {
   "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": 2
}