Lab #1. Introduction to FHIR resources.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 #1. Introduction to FHIR resources\n",
    "\n",
    "Meet John Thompson. He is a 36 year old (date of birth is *08-02-1982*) man from *Philadelphia*. He is thinking of visiting our clinical center because of some health problems. John calls our center and asks if he can visit us."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let’s check if he has visited our center before."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1 Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1 Import libraries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the beginning we should import libraries `fhirpy` and `os`.  \n",
    "Also we import `pprint` helper function from local `utils.py` file. We'll use `pprint` for 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 initiate `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 data from the FHIR server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1 Load list of patients"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Patient` resource covers data about patients and animals involved in a wide range of health-related activities, including:\n",
    "\n",
    "* Theurapeutic activities\n",
    "* Psychiatric care\n",
    "* Social services\n",
    "* Pregnancy care\n",
    "* Nursing and assisted living\n",
    "* Dietary services\n",
    "* Tracking of personal health and exercise data\n",
    "\n",
    "The data in the Resource cover the \"who\" information about the patient: its attributes are focused on the demographic information necessary to support the administrative, financial and logistic procedures. A `Patient` record is generally created and maintained by each organization providing care for a patient.\n",
    "\n",
    "Let's try to fetch all patients in the database using `resources` method.  \n",
    "This method returns a 'lazy object' (an instance of `FHIRSearchSet`), which provides some helpful methods for building queries. The most important method which we are going to use is `fetch_all`. Using it, we can execute built queries and load all records suitable for our query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patients = await client.resources('Patient').fetch_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We built a simple query without any filters and sortings. Executing this query we load all patient records which are represented as dict-like object (an instance of `FHIRResource`).\n",
    "\n",
    "Let's try to display the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patients"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see from the output above, we have a lot of patient resources with different IDs.  \n",
    "To get more details, we can get some fields using `get` and `get_by_path` methods.  \n",
    "\n",
    "`get(field_name)` method receives field name as the first argument.  \n",
    "`get_by_path(path)` method receives path as string (`'name.0.given.0'`) or as a list (`['name', 0, 'given', 0]`)  \n",
    "\n",
    "Let's try to iterate over `patients` list and display their ids and full name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for patient in patients:\n",
    "    print('{0} {1} {2}'.format(\n",
    "        patient.get('id'), \n",
    "        patient.get_by_path('name.0.family'),\n",
    "        patient.get_by_path('name.0.given.0')))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2 Sorting results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also, we can sort the result, for example, by name using `sort` method.  \n",
    "Please, pay attention, that `sort` receives multiple parameters and all possible parameters described in the [official FHIR specification](https://www.hl7.org/fhir/patient.html#search)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patients = await client.resources('Patient').sort('name').fetch_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can display the result and see what changed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for patient in patients:\n",
    "    print('{0} {1} {2}'.format(\n",
    "        patient.get('id'), \n",
    "        patient.get_by_path('name.0.family'),\n",
    "        patient.get_by_path('name.0.given.0')))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, the list is very long and it may be too difficult to find the particular patient especially if we have thousands of entries.  \n",
    "To minimize the result, FHIR API provides special search tools.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.3 Search through patients' resources"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Patient` resource has many search parameters. You can read more about them in the [official FHIR specification](https://www.hl7.org/fhir/patient.html#search).  \n",
    "\n",
    "\n",
    "\n",
    "For searching we should use `search` method on a search set. If we want to find, for example, all patients with the first name `John` and the last name `Thompson` we should use intersection search, passing list of values, for example, `search(name=['John', 'Thompson'])`. This is known as an AND search parameter.  \n",
    "If we wanted to find all patients with name `John` or `Carl`, we would use `search(name='John,Carl')`. This is known as an OR search parameter.\n",
    "\n",
    "\n",
    "Let's try to search for a patient by a parameter `name`.  \n",
    "This param is used for searching by string fields in the patient's name, including family, given, prefix, suffix, and/or text.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patients = await client.resources('Patient').search(name=['John', 'Thompson']).fetch_all()\n",
    "patients"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We found nothing. Maybe his record has a typo in the name. Now let's try to search by other parameters, for example, \n",
    "by birth date. The search parameter has name `birthdate` according to the [FHIR specification](https://www.hl7.org/fhir/patient.html#search).  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patients = await client.resources('Patient').search(birthdate='1982-08-02').fetch_all()\n",
    "patients"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also, we can try to find all patients who were born in `Philadelphia`. For this purpose we should use `address` search param."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patients = await client.resources('Patient').search(address='Philadelphia').fetch_all()\n",
    "patients"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, we didn’t find our client in the system, so, we should create a record for him. But before we do that, let's learn more about how different fields should be stored."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3 Patient resource structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's try to load one patient resource and understand this structure.  \n",
    "We don't need to load all patient's records because they have a similar structure, so we can load only one record using `first` method on the search set.  \n",
    "This method returns only one resource representation (an instance of `FHIRResource`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient = await client.resources('Patient').first()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you know, FHIRResource is a dict-like object. It means, we can display some fields from the resource using an access by key."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient['id']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's see how the patient name looks.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1 Name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The name is represented using `HumanName` type. \n",
    "\n",
    "Names might be changed and people may have different names in different contexts. So, a patient name is always represented as a list even if the patient has only one name. \n",
    "\n",
    "The most popular fields in this structure are:\n",
    "* given - given names, not only first name (e.g. John). It should be a list of names, even if the person has only one.\n",
    "* family - family name (e.g. Tompson)\n",
    "* use - in which context this name applies\n",
    "* text - text representation of the full name (e.g. John Tompson)\n",
    "\n",
    "\n",
    "More information you can find more information in the [FHIR specification](https://www.hl7.org/fhir/datatypes.html#humanname). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(patient['name'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2 Address"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The address type may be used to convey addresses for use in delivering mail as well as for visiting locations which might not be valid for mail delivery. There are a variety of address formats defined around the world.\n",
    "\n",
    "More information you can find in the [FHIR specification](https://www.hl7.org/fhir/datatypes.html#address). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(patient['address'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.3 Contact information"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Contact information is stored in `telecom` field. This fields contains details for all kinds of technology-mediated contact points for a person, including telephone, email, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(patient['telecom'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4 Editing patient resource"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Patient` resource can include different fields, which are described in the [official FHIR specification](https://www.hl7.org/fhir/patient.html#resource). \n",
    "Now we are familiar with some of them: `name`, `address` and `telecom`. Let's create a new record for the patient."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.1 Create a new patient record"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can create a new instance of resource using `resource` method. This method creates a new resource representation in the memory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient = client.resource('Patient')\n",
    "patient"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This line doesn't save the patient to the database. So, we can change any attributes of resource before it will be really saved."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient['name'] = [\n",
    "    {\n",
    "        'given': ['John'],\n",
    "        'family': 'Thompson',\n",
    "        'use': 'official',\n",
    "        'prefix': ['Mr.'],\n",
    "    }\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also we can specify date of birth, using `birthDate` field. We should pass a date in format `year-month-day`. Let's do it by yourself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient['birthDate'] = ''  # Write code here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To save the resource, we should use `save` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await patient.save()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This line doesn't return anything in case of success but mutates the patient resource. Now, the `patient` has an additional meta information and unique ID.  \n",
    "We can look at this information using attributes `id` and `meta`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient['id']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient['meta']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.2 Edit a patient record"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we should update the patient’s details.  \n",
    "Let's edit the  address - the new one is `1818 Market St,apartment 100, Philadelphia, PA 19103`\n",
    "\n",
    "You need to fill in the address by yourself using fields from [FHIR specification](https://www.hl7.org/fhir/datatypes.html#address). \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient['address'] = [\n",
    "    {\n",
    "        # Write code here\n",
    "    }\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And set the new telephone number: `(215) 352-3801`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patient['telecom'] = [\n",
    "    {\n",
    "        # Write code here\n",
    "    }\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And finally, save the changes to the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await patient.save()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5 Check laboratory results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we need to make sure that we have our patient record in the database.  \n",
    "\n",
    "Let's try to search for the patient again. For this operation we should use the same query as we did it before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "patients = await client.resources('Patient').search(name=['John', 'Thompson']).fetch_all()\n",
    "pprint(patients)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you followed the instructions, you should have the following fields in the output:\n",
    "\n",
    "* id\n",
    "* resourceType\n",
    "* birthDate\n",
    "* name\n",
    "* telecom\n",
    "* address"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6 Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From this laboratory work we learned how to:\n",
    "* load patients from the FHIR server\n",
    "* search by different fields\n",
    "* sort the results\n",
    "* display different resorce's attributes\n",
    "* create patient record\n",
    "* edit patient record\n",
    "\n"
   ]
  },
  {
   "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
}