API workshop #4 - Ramachandran and side-chain outlier residues.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 #4\n",
    "\n",
    "This notebook is the fourth in the training material series, and focuses on investigating Ramachandran and side-chain outliers 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 requests\n",
    "import re\n",
    "\n",
    "base_url = \"https://www.ebi.ac.uk/pdbe/\"\n",
    "\n",
    "api_base = base_url + \"api/\"\n",
    "\n",
    "outlier_data_url = api_base + 'validation/protein-ramachandran-sidechain-outliers/entry/'"
   ]
  },
  {
   "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) Investigating ourlier residues\n",
    "\n",
    "We will use one of the validation data calls of the PDBe API to get information on the Ramachandran and side-chain outliers of various models in a PDB entry.\n",
    "\n",
    "For this exercise, we will look at the NMR entry \"2aqa\". Generally, the JSON data will have the following basic structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "example = {\n",
    "    \"2aqa\": {\n",
    "        \"ramachandran_outliers\": [],\n",
    "        \"sidechain_outliers\": []\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The lists will contain dictionaries which give residue-level information. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "example = {\n",
    "    \"model_id\": 2,\n",
    "    \"entity_id\": 1,\n",
    "    \"residue_number\": 47,\n",
    "    \"author_residue_number\": 48,\n",
    "    \"chain_id\": \"A\",\n",
    "    \"author_insertion_code\": \"\",\n",
    "    \"alt_code\": \"\",\n",
    "    \"struct_asym_id\": \"A\"\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1) Listing the number of outliers per model\n",
    "\n",
    "The entry \"2aqa\" has multiple models, and it may be of interest to see if any of the models has relatively more outliers than the rest.\n",
    "\n",
    "First, we will list the number of outlier residues per models using the functions below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Ramachandran outliers:\n",
      "Model 2 has 1 Ramachandran outliers\n",
      "Model 3 has 1 Ramachandran outliers\n",
      "Model 5 has 1 Ramachandran outliers\n",
      "Model 6 has 1 Ramachandran outliers\n",
      "Model 7 has 1 Ramachandran outliers\n",
      "Model 8 has 1 Ramachandran outliers\n",
      "Model 9 has 1 Ramachandran outliers\n",
      "Model 11 has 1 Ramachandran outliers\n",
      "Model 12 has 1 Ramachandran outliers\n",
      "Model 13 has 1 Ramachandran outliers\n",
      "Model 15 has 1 Ramachandran outliers\n",
      "Model 16 has 1 Ramachandran outliers\n",
      "Model 19 has 1 Ramachandran outliers\n",
      "\n",
      "Side-chain outliers:\n",
      "Model 1 has 4 Side-chain outliers\n",
      "Model 2 has 6 Side-chain outliers\n",
      "Model 3 has 8 Side-chain outliers\n",
      "Model 4 has 6 Side-chain outliers\n",
      "Model 5 has 6 Side-chain outliers\n",
      "Model 6 has 4 Side-chain outliers\n",
      "Model 7 has 9 Side-chain outliers\n",
      "Model 8 has 4 Side-chain outliers\n",
      "Model 9 has 5 Side-chain outliers\n",
      "Model 10 has 4 Side-chain outliers\n",
      "Model 11 has 8 Side-chain outliers\n",
      "Model 12 has 4 Side-chain outliers\n",
      "Model 13 has 5 Side-chain outliers\n",
      "Model 14 has 5 Side-chain outliers\n",
      "Model 15 has 4 Side-chain outliers\n",
      "Model 16 has 6 Side-chain outliers\n",
      "Model 17 has 7 Side-chain outliers\n",
      "Model 18 has 2 Side-chain outliers\n",
      "Model 19 has 7 Side-chain outliers\n",
      "Model 20 has 4 Side-chain outliers\n"
     ]
    }
   ],
   "source": [
    "def get_outlier_data(pdb_id):\n",
    "    \"\"\"\n",
    "    This function will GET the outlier data from\n",
    "    the PDBe API using the make_request() function\n",
    "    \n",
    "    :param pdb_id: String\n",
    "    :return: JSON\n",
    "    \"\"\"\n",
    "    # Check if the provided PDB id is valid\n",
    "    # There is no point in making an API call\n",
    "    # with bad PDB ids\n",
    "    if not re.match(\"[0-9][A-Za-z][A-Za-z0-9]{2}\", pdb_id):\n",
    "        print(\"Invalid PDB id\")\n",
    "        return None\n",
    "    \n",
    "    # GET the outlier data\n",
    "    outlier_data = make_request(outlier_data_url, \"get\", pdb_id)\n",
    "    \n",
    "    # Check if there is data\n",
    "    if not outlier_data:\n",
    "        print(\"No data found\")\n",
    "        return None\n",
    "    \n",
    "    return outlier_data\n",
    "    \n",
    "def list_number_of_outliers_per_model(pdb_id):\n",
    "    \"\"\"\n",
    "    This function calls get_outlier_data() and\n",
    "    then list the number of Ramachandran and\n",
    "    side-chain outliers per model in the PDB entry\n",
    "    \n",
    "    :param pdb_id: String,\n",
    "    :return: None\n",
    "    \"\"\"\n",
    "    # We will collect the number of outlier \n",
    "    # residues per model\n",
    "    outliers = {\"ramachandran_outliers\": {}, \"sidechain_outliers\": {}}\n",
    "    \n",
    "    # Getting outlier data\n",
    "    outlier_data = get_outlier_data(pdb_id)\n",
    "    \n",
    "    # If there is no data, return None\n",
    "    if not outlier_data:\n",
    "        return None\n",
    "    \n",
    "    # Iterate through both Ramachandran and\n",
    "    # side-chain outliers\n",
    "    for key in outliers.keys():\n",
    "        for i in range(len(outlier_data[pdb_id][key])):\n",
    "            # Grab the model id\n",
    "            model_id = outlier_data[pdb_id][key][i][\"model_id\"]\n",
    "            # If the model id was not observed before, add to\n",
    "            # the outliers dictionary with the corresponding\n",
    "            # outlier type, otherwise increase the count by one\n",
    "            if model_id not in outliers[key].keys():\n",
    "                outliers[key][model_id] = 1\n",
    "            else:\n",
    "                outliers[key][model_id] += 1\n",
    "\n",
    "    print(\"Ramachandran outliers:\")\n",
    "    for model in outliers[\"ramachandran_outliers\"].keys():\n",
    "        print(\"Model %i has %i Ramachandran outliers\" % (model, \n",
    "                                                         outliers[\"ramachandran_outliers\"][model]))\n",
    "    print()\n",
    "    print(\"Side-chain outliers:\")\n",
    "    for model in outliers[\"sidechain_outliers\"].keys():\n",
    "        print(\"Model %i has %i Side-chain outliers\" % (model, \n",
    "                                                       outliers[\"sidechain_outliers\"][model]))\n",
    "\n",
    "list_number_of_outliers_per_model(\"2aqa\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2) Listing all outlier residues of a model\n",
    "\n",
    "Next, we will write a function that lists out which are the outlier residues within a specific model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Listing outlier residues for Model #7 of PDB entry 2aqa:\n",
      "Residue 14 in chain A of entity 1 is a Ramachandran outlier\n",
      "Residue 3 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 22 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 27 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 30 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 39 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 42 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 44 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 46 in chain A of entity 1 is a side-chain outlier\n",
      "Residue 57 in chain A of entity 1 is a side-chain outlier\n"
     ]
    }
   ],
   "source": [
    "def list_outlier_residues_of_model(pdb_id, model_id):\n",
    "    \"\"\"\n",
    "    This function calls get_outlier_data()\n",
    "    and lists all outlier residues of a \n",
    "    specific model\n",
    "    \n",
    "    :param pdb_id: String,\n",
    "    :param model_id: Integer,\n",
    "    :return: None\n",
    "    \"\"\"\n",
    "    \n",
    "    outlier_data = get_outlier_data(pdb_id)\n",
    "    \n",
    "    # If there is no data, return None\n",
    "    if not outlier_data:\n",
    "        return None\n",
    "    \n",
    "    # Iterate thourgh the outlier types\n",
    "    for outlier_type in outlier_data[pdb_id].keys():\n",
    "        # Loop through all the residue-level outlier information\n",
    "        for i in range(len(outlier_data[pdb_id][outlier_type])):\n",
    "            outlier_information = outlier_data[pdb_id][outlier_type][i]\n",
    "            # Only process outlier information that corresponds to\n",
    "            # the model id of interest\n",
    "            if outlier_information[\"model_id\"] != model_id:\n",
    "                continue\n",
    "                \n",
    "            # Set outlier type labels\n",
    "            if outlier_type == \"ramachandran_outliers\":\n",
    "                label = \"Ramachandran\"\n",
    "            else:\n",
    "                label = \"side-chain\"\n",
    "                \n",
    "            residue = outlier_information[\"residue_number\"]\n",
    "            chain = outlier_information[\"chain_id\"]\n",
    "            entity = outlier_information[\"entity_id\"]\n",
    "            print (\"Residue %i in chain %s of entity %i is a %s outlier\" % (residue,\n",
    "                                                                            chain,\n",
    "                                                                            entity,\n",
    "                                                                            label))\n",
    "\n",
    "print(\"Listing outlier residues for Model #7 of PDB entry 2aqa:\")\n",
    "list_outlier_residues_of_model(\"2aqa\", 7)\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## This ends the fourth 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
}