API workshop #3 - Citations of PDB entries.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "PDBe API Training\n",
    "=========\n",
    "\n",
    "This interactive Python notebook will guide you through various ways of programmatically accessing Protein Data Bank in Europe (PDBe) data using REST API\n",
    "\n",
    "The REST API is a programmatic way to obtain information from the PDB and EMDB. You can access details about:\n",
    "\n",
    "* sample\n",
    "* experiment\n",
    "* models\n",
    "* compounds\n",
    "* cross-references\n",
    "* publications \n",
    "* quality \n",
    "* assemblies \n",
    "* and more...\n",
    "\n",
    "For more information, visit http://www.ebi.ac.uk/pdbe/pdbe-rest-api"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook #3\n",
    "\n",
    "This notebook is the third in the training material series, and focuses on evaluating the impact of PDB entries by counting citations using the REST API of PDBe."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1) Making imports and setting variables\n",
    "\n",
    "First, we import some packages that we will use, and set some variables.\n",
    "\n",
    "Note: Full list of valid URLs is available from http://www.ebi.ac.uk/pdbe/api/doc/"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import re\n",
    "\n",
    "base_url = \"https://www.ebi.ac.uk/pdbe/\"\n",
    "\n",
    "api_base = base_url + \"api/\"\n",
    "\n",
    "citation_url = api_base + 'pdb/entry/related_publications/'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2) Defining request function\n",
    "\n",
    "Let's start with defining a function that can be used to GET a single PDB entry, or POST a comma-separated list of PDB entries.\n",
    "\n",
    "We will use this function to retrieve citations data for entries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def make_request(url, mode, pdb_id):\n",
    "    \"\"\"\n",
    "    This function can make GET and POST requests to\n",
    "    the PDBe API\n",
    "    \n",
    "    :param url: String,\n",
    "    :param mode: String,\n",
    "    :param pdb_id: String\n",
    "    :return: JSON or None\n",
    "    \"\"\"\n",
    "    if mode == \"get\":\n",
    "        response = requests.get(url=url+pdb_id)\n",
    "    elif mode == \"post\":\n",
    "        response = requests.post(url, data=pdb_id)\n",
    "\n",
    "    if response.status_code == 200:\n",
    "        return response.json()\n",
    "    else:\n",
    "        print(\"[No data retrieved - %s] %s\" % (response.status_code, response.text))\n",
    "    \n",
    "    return None"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3) Investigating citations of PDB entries\n",
    "\n",
    "In this exercise, we will try to evaluate the impact of a set of PDB entries based on the number of citations (publications that mention the entry, where the authors are not the same as the PDB depositors)\n",
    "\n",
    "We will use the API call \"related publications\" to do this."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1) Defining a list of PDB entries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdb_list = (\"1cbs\", \"2aqa\", \"3bow\", \"2klm\", \"5tok\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2) Examining an example entry\n",
    "Let's see what the API data would look like for a specific entry.\n",
    "\n",
    "For example the entry \"3bow\" would have information such as this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'3bow': {'appears_without_citation': {'Reviews': [], 'Articles': []},\n",
       "  'cited_by': {'Reviews': [{'title': 'Calpains and cancer: friends or enemies?',\n",
       "     'journal': 'Arch. Biochem. Biophys.',\n",
       "     'citation_type': 'Review',\n",
       "     'year': '2014',\n",
       "     'volume': '564',\n",
       "     'pubmed_id': '25305531',\n",
       "     'authors': 'Moretti D, Del Bello B, Allavena G, Maellaro E.',\n",
       "     'cited_by_count': 12,\n",
       "     'pages': '26-36'}],\n",
       "   'Articles': []},\n",
       "  'uniprot_publications': {'Reviews': [], 'Articles': []}}}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "{\n",
    "    \"3bow\": {\n",
    "        \"appears_without_citation\": {\n",
    "            \"Reviews\": [],\n",
    "            \"Articles\": []\n",
    "        },\n",
    "        \"cited_by\": {\n",
    "            \"Reviews\": [\n",
    "                {\n",
    "                    \"title\": \"Calpains and cancer: friends or enemies?\",\n",
    "                    \"journal\": \"Arch. Biochem. Biophys.\",\n",
    "                    \"citation_type\": \"Review\",\n",
    "                    \"year\": \"2014\",\n",
    "                    \"volume\": \"564\",\n",
    "                    \"pubmed_id\": \"25305531\",\n",
    "                    \"authors\": \"Moretti D, Del Bello B, Allavena G, Maellaro E.\",\n",
    "                    \"cited_by_count\": 12,\n",
    "                    \"pages\": \"26-36\"\n",
    "                }\n",
    "            ],\n",
    "            \"Articles\": []\n",
    "        },\n",
    "        \"uniprot_publications\": {\n",
    "            \"Reviews\": [],\n",
    "            \"Articles\": []\n",
    "        }\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the API call returns a structured JSON object with information on three types of related publications. For our purposes, the most relevant citations will be found in the \"cited_by\" sub-dictionary. For the sake of this exercise, we will argue that the impact of a PDB entry is best quantified by how many times it was cited directly. We will also make a distinction between reviews and articles, as articles are on the frontline of science, and the most impactful developments are published in this type of publications. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.3) Defining a function to calculate the number of review and article citations of PDB entries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calculate_citations(pdb_list):\n",
    "    \"\"\"\n",
    "    This function will calculate the number of review and article\n",
    "    citations for each PDB entry on an id list\n",
    "    \n",
    "    :param pdb_list: List\n",
    "    :return: Dict or None\n",
    "    \"\"\"\n",
    "    \n",
    "    # We will save valid and unique PDB ids\n",
    "    validated_unique_ids = []\n",
    "    citation_counts = {}\n",
    "    \n",
    "    # First, we loop through the PDB list\n",
    "    # and check if the ids match the PDB\n",
    "    # id pattern\n",
    "    for pdb_id in pdb_list:\n",
    "        if not re.match(\"[0-9][A-Za-z][A-Za-z0-9]{2}\", pdb_id):\n",
    "            continue\n",
    "        if pdb_id not in validated_unique_ids:\n",
    "            validated_unique_ids.append(pdb_id)\n",
    "    \n",
    "    # Join the list of PDB ids in a string \n",
    "    # format that the API requires\n",
    "    joined_list = \", \".join(validated_unique_ids)\n",
    "    \n",
    "    # Get the citations data for the list of \n",
    "    # PDB entries\n",
    "    citations_data = make_request(citation_url, \"post\", joined_list)\n",
    "    \n",
    "    if not citations_data:\n",
    "        print(\"No data\")\n",
    "        return None\n",
    "    \n",
    "    for entry_id in citations_data.keys():\n",
    "        number_of_reviews = len(citations_data[entry_id][\"cited_by\"][\"Reviews\"])\n",
    "        number_of_articles = len(citations_data[entry_id][\"cited_by\"][\"Articles\"])\n",
    "        citation_counts[entry_id] = {\"reviews\": number_of_reviews, \"articles\": number_of_articles}\n",
    "    return citation_counts    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have this function, we can call it with the list of PDB entries. We also added a simple function to print the results in a more user-friendly manner."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Getting citation counts:\n",
      "{'2klm': {'reviews': 11, 'articles': 10}, '1cbs': {'reviews': 16, 'articles': 80}, '2aqa': {'reviews': 22, 'articles': 42}, '5tok': {'reviews': 3, 'articles': 1}, '3bow': {'reviews': 25, 'articles': 86}}\n",
      "\n",
      "pdb id\tarticles\treviews\n",
      "2klm\t10\t11\n",
      "1cbs\t80\t16\n",
      "2aqa\t42\t22\n",
      "5tok\t1\t3\n",
      "3bow\t86\t25\n"
     ]
    }
   ],
   "source": [
    "print(\"Getting citation counts:\")\n",
    "counts = calculate_citations(pdb_list)\n",
    "print(counts)\n",
    "print()\n",
    "\n",
    "def print_nicely(counts):\n",
    "    \"\"\"\n",
    "    This function iterates through a count\n",
    "    dictionary and prints the values in a\n",
    "    user-friendly way\n",
    "    \n",
    "    :param counts: Dict,\n",
    "    :return: None\n",
    "    \"\"\"\n",
    "    print(\"pdb id\\tarticles\\treviews\")\n",
    "    for entry_id in counts.keys():\n",
    "        print(\"%s\\t%i\\t%i\" % (entry_id, \n",
    "                              counts[entry_id][\"articles\"],\n",
    "                              counts[entry_id][\"reviews\"]))\n",
    "    return None\n",
    "\n",
    "print_nicely(counts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## This ends the third notebook - please proceed to other notebooks of your interest"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copyright 2018 EMBL - European Bioinformatics Institute\n",
    "\n",
    "Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\n",
    "\n",
    "Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License."
   ]
  }
 ],
 "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.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}