API workshop #2 - Secondary structure mapping.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 #2\n",
    "\n",
    "This notebook is the second in the training material series, and focuses on getting secondary structure mappings for PDB entries 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": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import re\n",
    "import requests\n",
    "\n",
    "base_url = \"https://www.ebi.ac.uk/pdbe/\"\n",
    "\n",
    "api_base = base_url + \"api/\"\n",
    "\n",
    "secondary_structure_url = api_base + 'pdb/entry/secondary_structure/'"
   ]
  },
  {
   "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 secondary structure mapping for entries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "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) Defining function for extracting secondary structure mapping\n",
    "\n",
    "Next, we will define a function that can be used to retrieve secondary structural element ranges for PDB entries, and extracts this information so that it can be displayed in a user-friendly way.\n",
    "\n",
    "The function will rely on the make_request() function we have defined previously.\n",
    "\n",
    "This new function should either accept a single PDB id, or a list of PDB ids, and make a GET or a POST call to the API accordingly. The data structure then has to be traversed, and the residue ranges of helices and strands have to be recorded. Since the data is in a nested JSON format, (for the sake of not touching on more advanced Python topics) we will use nested for-loops to get to the level of interest.\n",
    "\n",
    "If you are wondering how the complete JSON looks like, follow this link:\n",
    "https://www.ebi.ac.uk/pdbe/api/pdb/entry/secondary_structure/1cbs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_secondary_structure_ranges(pdb_id=None, pdb_list=None):\n",
    "    \"\"\"\n",
    "    This function calls the PDBe API and retrieves the residue\n",
    "    ranges of secondary structural elements in a single PDB entry\n",
    "    or in a list of PDB entries\n",
    "    \n",
    "    :param pdb_id: String,\n",
    "    :param pdb_list: String\n",
    "    :return: None\n",
    "    \"\"\"\n",
    "    # If neither a single PDB id, nor a list was provided,\n",
    "    # exit the function\n",
    "    if not pdb_id and not pdb_list:\n",
    "        print(\"Either provide one PDB id, or a list of ids\")\n",
    "        return None\n",
    "    \n",
    "    if pdb_id:\n",
    "        # If a single PDB id was provided, call the API with GET\n",
    "        data = make_request(secondary_structure_url, \"get\", pdb_id)\n",
    "    else:\n",
    "        # If multiple PDB ids were provided, call the API with POST\n",
    "        # The POST API call expects PDB ids as a comma-separated lise\n",
    "        pdb_list_string = \", \".join(pdb_list)\n",
    "        data = make_request(secondary_structure_url, \"post\", pdb_list_string)\n",
    "        \n",
    "    # When no data is returned by the API, exit the function\n",
    "    if not data:\n",
    "        print(\"No data available\")\n",
    "        return None\n",
    "    \n",
    "    # Loop through all the PDB entries in the retrieved data\n",
    "    for entry_id in data.keys():\n",
    "        entry = data[entry_id]\n",
    "        molecules = entry[\"molecules\"]\n",
    "        \n",
    "        # Loop through all the molecules of a given PDB entry\n",
    "        for i in range(len(molecules)):\n",
    "            chains = molecules[i][\"chains\"]\n",
    "            \n",
    "            # Loop through all the chains of a given molecules\n",
    "            for j in range(len(chains)):\n",
    "                secondary_structure = chains[j][\"secondary_structure\"]\n",
    "                helices = secondary_structure[\"helices\"]\n",
    "                strands = secondary_structure[\"strands\"]\n",
    "                helix_list = []\n",
    "                strand_list = []\n",
    "                \n",
    "                # Loop through all the helices of a given chain\n",
    "                for k in range(len(helices)):\n",
    "                    start = helices[k][\"start\"][\"residue_number\"]\n",
    "                    end = helices[k][\"end\"][\"residue_number\"]\n",
    "                    helix_list.append(\"%s-%s\" % (start, end))\n",
    "                \n",
    "                # Loop through all the strands of a given chain\n",
    "                for l in range(len(strands)):\n",
    "                    start = strands[l][\"start\"][\"residue_number\"]\n",
    "                    end = strands[l][\"end\"][\"residue_number\"]\n",
    "                    strand_list.append(\"%s-%s\" % (start, end))\n",
    "                    \n",
    "                report = \"%s chain %s has \" % (entry_id, chains[j][\"chain_id\"])\n",
    "                if len(helix_list) > 0:\n",
    "                    report += \"helices at residue ranges %s \" % str(helix_list)\n",
    "                else:\n",
    "                    report += \"no helices \"\n",
    "                report += \"and \"\n",
    "                if len(strand_list) > 0:\n",
    "                    report += \"strands at %s\" % str(strand_list)\n",
    "                else:\n",
    "                    \"no strands\"\n",
    "                print(report)\n",
    "                \n",
    "    return None"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's try our new function first with a single PDB entry (1cbs), and then with a list of two entries (2aqa and 2klm)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Example of a single PDB entry\")\n",
    "get_secondary_structure_ranges(pdb_id=\"1cbs\")\n",
    "print()\n",
    "print(\"Example of multiple PDB entries\")\n",
    "get_secondary_structure_ranges(pdb_list=[\"2aqa\", \"2klm\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## This ends the second 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
}