Interactions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Interaction API\n",
    "\n",
    "In this section, we will continue investigating the use of an API published by the National Library of Medicine.  The techniques will be very similar to the spell checker example in the APIRequest notebook, though the data is more elaborate and more challenging to parse.\n",
    "\n",
    "We will be querying drug interactions through teh InteractionAPI.  This api accepts an rxcui for a particular drug and provides information about the known interactions with other medications.  \n",
    "\n",
    "To read more about this API, you can follow the link at\n",
    "\n",
    "https://rxnav.nlm.nih.gov/InteractionAPIs.html\n",
    "\n",
    "For an overview of the metadata related to this api, you can use the appendix at\n",
    "\n",
    "https://www.nlm.nih.gov/research/umls/rxnorm/docs/2015/appendix5.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start by loading the required libraries, making a connection to a URI, and converting the JSON response to a python dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "url = 'https://rxnav.nlm.nih.gov/REST/interaction/interaction.json?rxcui=153165'\n",
    "resp = requests.get(url)\n",
    "data = resp.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "this cell is commented out because of the amount of data.  To follow along, you can uncomment and run to look at the raw JSON from the URI.  Alternatively, just take a look at the URI directly in your brower.  You may want to install a plug-in to make viewing easier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This data structure is more elaborate and nested than the spell checker, combining lists and dictionaries.  \n",
    "\n",
    "Suppose you wanted to use this API to extract a list of drugs with a known interaction?  Do do this, you'll need to parse the JSON document to get specifically at the data fields you need.  There are various techniques to do this, so you often don't need to write this by hand.  However, there will be times when you need to apply very specific logic to a JSON tree, so we will investigate how to do this by directly accessing elements of a tree with Python.  \n",
    "\n",
    "To directly access the names of the drugs with interactions, we will need to follow\n",
    "\n",
    "interactionTypeGroup -> interactionType -> interactionPair -> minConceptItem.\n",
    "\n",
    "Some of these are nested dictionaries, and some are lists, so we may need to use different syntax to access them.\n",
    "\n",
    "To get the top level keys for this dictionary, you can use the python keys syntax.  Remember, a JSON document is very similar to a dictionary, and once loaded, you can use all the dict methods available in Python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['nlmDisclaimer', 'userInput', 'interactionTypeGroup'])"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Becase we are dealing with **keys**, we can use dictionary syntax.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "interactionTypeGroup = data['interactionTypeGroup']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "list"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(interactionTypeGroup)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have a key that maps to a list.  Let's check the length."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(interactionTypeGroup)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There's only one item in this list, but we can't assume that will always be the case.  If you want to parse a JSON tree, or a nested dictionary, make sure you iterate over every item in a list, even if in every case so far, you've only seen a single value.  \n",
    "\n",
    "We're dealing with a list here, so instead of using a lookup value in a dictionary (which is not ordered), we can access by positional index for a list, which is ordered."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "interactionTypeGroup = interactionTypeGroup[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(interactionTypeGroup)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The top level dictionary contained a list.  This list, in turn, contains dictionaries.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['sourceDisclaimer', 'sourceName', 'interactionType'])"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "interactionTypeGroup.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using this technique, let's continue to descend this tree until we get to the data we need."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "interactionType = interactionTypeGroup['interactionType']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "list"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(interactionType)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(interactionType)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "interactionType = interactionType[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['minConceptItem', 'interactionPair', 'comment'])"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "interactionType.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "interactionPair = interactionType['interactionPair']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "#interactionPair"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "368"
      ]
     },
     "execution_count": 46,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(interactionPair)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To avoid ambiguity between terms, let's pluralize this to remember we're dealing with a list.  The naming makes no different to Python, of course, but we (and others) have to read this code!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "interactionPairs = interactionPair"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'description': 'The serum concentration of Atorvastatin can be increased when it is combined with Lepirudin.',\n",
       " 'interactionConcept': [{'minConceptItem': {'name': 'atorvastatin',\n",
       "    'rxcui': '83367',\n",
       "    'tty': 'IN'},\n",
       "   'sourceConceptItem': {'id': 'DB01076',\n",
       "    'name': 'Atorvastatin',\n",
       "    'url': 'http://www.drugbank.ca/drugs/DB01076#interactions'}},\n",
       "  {'minConceptItem': {'name': 'lepirudin', 'rxcui': '237057', 'tty': 'IN'},\n",
       "   'sourceConceptItem': {'id': 'DB00001',\n",
       "    'name': 'Lepirudin',\n",
       "    'url': 'http://www.drugbank.ca/drugs/DB00001#interactions'}}],\n",
       " 'severity': 'N/A'}"
      ]
     },
     "execution_count": 48,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "interactionPair[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(interactionPair[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['interactionConcept', 'severity', 'description'])"
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "interactionPair[0].keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We don't have to assign an intermediary variable if we don't need one - we can grab the key value from the first element of the array.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "interactionConcept = interactionPair[0]['interactionConcept']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'minConceptItem': {'name': 'atorvastatin', 'rxcui': '83367', 'tty': 'IN'},\n",
       "  'sourceConceptItem': {'id': 'DB01076',\n",
       "   'name': 'Atorvastatin',\n",
       "   'url': 'http://www.drugbank.ca/drugs/DB01076#interactions'}},\n",
       " {'minConceptItem': {'name': 'lepirudin', 'rxcui': '237057', 'tty': 'IN'},\n",
       "  'sourceConceptItem': {'id': 'DB00001',\n",
       "   'name': 'Lepirudin',\n",
       "   'url': 'http://www.drugbank.ca/drugs/DB00001#interactions'}}]"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "interactionConcept"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 53,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(interactionConcept)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Look back at your original tree - the first element of the list is the name of the drug we're researching.  The second element is the name of the drug with an interaction.  To build our list, we'll grab that one.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "minConceptItem = interactionConcept[1]['minConceptItem']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'lepirudin', 'rxcui': '237057', 'tty': 'IN'}"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "minConceptItem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we arrive at a the data we need!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "name = minConceptItem['name']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'lepirudin'"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Exercise\n",
    "\n",
    "We obtained the name for a single interaction in this section.  How would you parse this tree to obtain a list of all interactions from this web service?  \n",
    "\n",
    "There are always multiple ways to do things in a programming language.  In the next section, InteractionList.ipynb, we'll review one way to do this.  But before you take a look, give this a try and see how your solution compares.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "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.5.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}