DLPacker.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import urllib\n",
    "from dlpacker import DLPacker\n",
    "\n",
    "# the lines below hides neverending warnings from biopython\n",
    "import warnings\n",
    "from Bio.PDB.PDBExceptions import PDBConstructionWarning\n",
    "warnings.simplefilter('ignore', PDBConstructionWarning)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p>For everythig in this notebook to work, make sure you have <b>dlpacker</b> installed (see the main README.md file for instructions). On the first run the package will try to unzip the weights supplied with the code.</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p><b>The code cell below just loads PDB file from RCSB to serve as an example. Feel free to replace this with your PDB structure:</b></p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('4p0d.pdb', <http.client.HTTPMessage at 0x7fa52c9c69a0>)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pdb = '4p0d'\n",
    "# this line loads an example PDB structure from RCSB\n",
    "urllib.request.urlretrieve('http://files.rcsb.org/download/' + pdb + '.pdb', pdb + '.pdb')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p><b>Basic usage example</b></p>\n",
    "<p>Reconstructing a whole protein structure only takes two lines of code as shown below.</p>\n",
    "<p>You only need a PDB structure to work with. The structure may or may not contain side chains, existing side chains will be ignored anyway. Just make sure the backbone is present.</p>\n",
    "<p>As described in the paper, there are three order options:<br/>1. <b>sequence</b> - the simplest strategy that restores all the residues from N- to C-terminus. The fastest of three, but with slighly worse preformance than the other two.<br/>2. <b>natoms</b> - Slightly slower, but better strategy that sorts residues by the number ot backbone atoms around them and restores side chains in the most crowded microenvironments first. Roughly corresponds to first restoring side chains in the protein’s interior and then gradually moving to its exterior.<br/>3. <b>score</b> - the best performing strategy, but also the slowest one - takes twice as much time as the other two and is a two-stage process. First, predictions are made for each amino acid (without actually restoring the side chains) and then residues are sorted by their prediction score,normalized by the number of atoms in a side chain. Side chains are then restored in the second pass.</p>\n",
    "<p>The average performance difference between the three is not that significant, so choose wisely.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Missing backbone atoms: residue (35, 'A', 'LYS')\n",
      "Skipping residue: (35, 'A', 'LYS')\n",
      "Working on residue: 469 (513, 'A', 'LEU') (506, 'A', 'THR')\n",
      "Writing output file...\n",
      "Done!\n",
      "CPU times: user 40.7 s, sys: 1.42 s, total: 42.1 s\n",
      "Wall time: 41.6 s\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "dlp = DLPacker(pdb + '.pdb')\n",
    "dlp.reconstruct_protein(order = 'sequence', output_filename = pdb + '_repacked.pdb')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p><b>Mutation example #1</b></p>\n",
    "<p>Just a bit more complicated usage example. The code below introduces mutations into the original PDB structure and then repacks it. It takes an (unsuccessful) attempt at building a salt bridge inside the structure.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Mutated (155, 'A', 'LEU') to ARG!\n",
      "Mutated (144, 'A', 'LEU') to ASP!\n",
      "Sorting residues...\n",
      "Working on residue: 469 (473, 'A', 'ASN')\n",
      "Writing output file...\n",
      "Done!\n",
      "CPU times: user 44 s, sys: 848 ms, total: 44.9 s\n",
      "Wall time: 44.4 s\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "dlp = DLPacker(pdb + '.pdb')\n",
    "dlp.mutate_sequence((155, 'A', 'LEU'), 'ARG')\n",
    "dlp.mutate_sequence((144, 'A', 'LEU'), 'ASP')\n",
    "dlp.reconstruct_protein(order = 'natoms', output_filename = pdb + '_mutated.pdb')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p><b>Mutation example #2</b></p>\n",
    "<p>The code below introduces mutations into the original PDB structure and then repacks only a <b>part</b> of the PDB structure. For this purpose we introduced a helper method `get_targets` that takes as input the amino acid we just mutated and assembles a list of its neighbours that lie within specified radius:</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Mutated (72, 'A', 'PHE') to TRP!\n",
      "List of residues targeted for remodelling:\n",
      " [(59, 'A', 'GLU'), (123, 'A', 'GLY'), (58, 'A', 'GLY'), (60, 'A', 'GLY'), (155, 'A', 'LEU'), (167, 'A', 'LEU'), (145, 'A', 'LEU'), (147, 'A', 'ALA'), (126, 'A', 'VAL'), (148, 'A', 'SER'), (61, 'A', 'VAL'), (73, 'A', 'LYS'), (158, 'A', 'LYS'), (105, 'A', 'PHE'), (71, 'A', 'ASN'), (72, 'A', 'TRP'), (57, 'A', 'ILE'), (70, 'A', 'ILE'), (82, 'A', 'GLU'), (62, 'A', 'TYR'), (124, 'A', 'ALA'), (156, 'A', 'VAL'), (157, 'A', 'THR'), (153, 'A', 'GLY'), (56, 'A', 'LYS'), (149, 'A', 'TYR'), (154, 'A', 'ASN'), (127, 'A', 'TYR'), (74, 'A', 'TYR'), (80, 'A', 'LEU'), (69, 'A', 'PHE'), (75, 'A', 'ALA'), (125, 'A', 'SER'), (146, 'A', 'ALA'), (150, 'A', 'ASN')]\n",
      "CPU times: user 464 ms, sys: 354 ms, total: 818 ms\n",
      "Wall time: 812 ms\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "dlp = DLPacker(pdb + '.pdb')\n",
    "dlp.mutate_sequence((72, 'A', 'PHE'), 'TRP')\n",
    "targets = dlp.get_targets(target = (72, 'A', 'TRP'), radius = 10)\n",
    "print('List of residues targeted for remodelling:\\n', targets)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p>The line below calls a function called `reconstruct_region` that takes a list of residues to remodel as an additional argument:</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Working on residue: 34 (167, 'A', 'LEU')\n",
      "Writing output file...\n",
      "Done!\n"
     ]
    }
   ],
   "source": [
    "dlp.reconstruct_region(targets = targets, order = 'sequence', output_filename = pdb + '_region.pdb')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p><b>Mutation example #3</b></p>\n",
    "<p>Sometimes you might need to just mutate a single residue (e.g. on the surface) without remodelling any other parts of the protein. The code below does just this:</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Mutated (156, 'A', 'VAL') to TYR!\n",
      "CPU times: user 472 ms, sys: 254 ms, total: 726 ms\n",
      "Wall time: 725 ms\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "dlp = DLPacker(pdb + '.pdb')\n",
    "dlp.mutate_residue((156, 'A', 'VAL'), 'TYR')\n",
    "dlp.save_structure(pdb + '_single.pdb')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p>Note the difference between method `mutate_sequence` above and `mutate_residue` here: the first one literally just changes the sequence and nothing else, while the second one mutates the sequence and does side chain restoration for the target residue.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.12 64-bit",
   "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.10.12"
  },
  "vscode": {
   "interpreter": {
    "hash": "916dbcbb3f70747c44a77c7bcd40155683ae19c65e1c03b4aa3499c5328201f1"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}