{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Cookbook for pydna\n",
    "\n",
    "Björn Johansson\n",
    "CBMA\n",
    "University of Minho\n",
    "Braga\n",
    "Portugal\n",
    "\n",
    "![logo](logo.png \"logo\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##What is pydna?\n",
    "\n",
    "Pydna is a python package that provides functions and data types to deal with double stranded DNA. It depends on Biopython (a python bioinformatics package), networkx (a graph theory package) and numpy (a mathematics package).\n",
    "\n",
    "##What does Python dna provide?\n",
    "\n",
    "Python dna provide classes and functions for molecular biology using python. Notably, PCR, cut and paste cloning (sub-cloning) and homologous recombination between linear DNA fragments are supported. Most functionality is implemented as methods for the double stranded DNA sequence record classes “Dseq” and \"Dseqrecord\", which are a subclasses of the Biopython Seq and SeqRecord classes, respectively.\n",
    "\n",
    "Pydna was designed to semantically imitate how sub-cloning experiments are typically documented in scientific literature. One use case for pydna is to create executable documentation for a sub-cloning experiment. The pydna code unambiguously describe the experiment, and can be executed to yield the sequence of the of the resulting DNA molecule(s) and all intermediary steps.  Pydna code describing a sub cloning is reasonably compact and also meant to be easily readable.\n",
    "\n",
    "Typical usage at the command line could look like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-9)\n",
       "GGATCCAAA\n",
       "CCTAGGTTT"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pydna\n",
    "seq = pydna.Dseq(\"GGATCCAAA\",\"TTTGGATCC\", ovhg=0)\n",
    "seq"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example above shows an example usage of the Dseq class which is a double stranded version of the Biopython seq class. This is the main pydna data type along with the Dseqrecord class which is a double stranded version of the Biopython SeqRecord class.\n",
    "\n",
    "The Dseq object was initialized using two strings and a value for the stagger (ovhg) between the DNA strands in the 5' (left) extremity. This is of course not a practical way of creating a Dseq object in most cases, but there are other more practical methods as we will see further on.\n",
    "\n",
    "The Dseq object comes with a cut method that takes one or more restriction enzymes as arguments. A list is returned with the fragments produced in the digestion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from Bio.Restriction import BamHI\n",
    "a,b = seq.cut(BamHI)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-5)\n",
       "G\n",
       "CCTAG"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-8)\n",
       "GATCCAAA\n",
       "    GTTT"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The fragments a and b formed in the example above can be religated together by the addition operator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-9)\n",
       "GGATCCAAA\n",
       "CCTAGGTTT"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "a+b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-13)\n",
       "GATCCAAAG\n",
       "    GTTTCCTAG"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "b+a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-17)\n",
       "GATCCAAAGGATCCAAA\n",
       "    GTTTCCTAGGTTT"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "b+a+b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Dseq objects keep track of the structure of the DNA ends and only allow ligation of compatible fragments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "sticky ends not compatible!",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m\n\u001b[1;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-12-0ecf0fe711d0>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[1;32m----> 1\u001b[1;33m \u001b[0mb\u001b[0m\u001b[1;33m+\u001b[0m\u001b[0ma\u001b[0m\u001b[1;33m+\u001b[0m\u001b[0ma\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;32m/home/bjorn/Dropbox/python_packages/pydna/pydna/dsdna.pyc\u001b[0m in \u001b[0;36m__add__\u001b[1;34m(self, other)\u001b[0m\n\u001b[0;32m    831\u001b[0m             \u001b[0manswer\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mcopy\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mcopy\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    832\u001b[0m         \u001b[1;32melse\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m--> 833\u001b[1;33m             \u001b[1;32mraise\u001b[0m \u001b[0mTypeError\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m\"sticky ends not compatible!\"\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    834\u001b[0m         \u001b[1;32mreturn\u001b[0m \u001b[0manswer\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    835\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;31mTypeError\u001b[0m: sticky ends not compatible!"
     ]
    }
   ],
   "source": [
    "b+a+a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two examples are given in this tutorial (Example 1 and 2). The data files that are referred to in this document can be found in the folder “cookbook_files” that was downloaded together with this file. Alternatively, the examples can be solved on-line using pydna live."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# pydna live"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python 2.7.3 with pydna and Biopython are avaliable for testing interactively online at http://pydna-shell.appspot.com/."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<iframe src=http://pydna-shell.appspot.com width=800 height=350></iframe>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.display import HTML\n",
    "HTML('<iframe src=http://pydna-shell.appspot.com width=800 height=350></iframe>')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Biopython package is not completely supported by pydna live since pydna live runs on the google app engine, which currently does not permit C-extensions. However, all functionality needed for pydna is provided.\n",
    "\n",
    "All files referred to in this cookbook are provided in the sub directory “cookbook_files”. This means that you can execute the statements given here directly as they are written by copy and paste (leaving out the prompt “>>>”). \n",
    "\n",
    "If you perform these examples on your own system, you have to adjust file paths when reading and writing files."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Example 1: Sub cloning by restriction digestion and ligation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The construction of the vector YEp24PGK_XK is described on page 4250 in the publication below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<iframe src=http://www.ncbi.nlm.nih.gov/pmc/articles/PMC93154 width=800 height=300></iframe>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "HTML('<iframe src=http://www.ncbi.nlm.nih.gov/pmc/articles/PMC93154 width=800 height=300></iframe>')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Briefly, the XKS1 gene from Saccharomyces cerevisiae is amplified by PCR using two primers called primer1 and primer3. The primers add restriction sites for BamHI to the ends of the  XKS1 gene. The gene is digested with BamHI and ligated to the YEp24PGK plasmid that has previously been digested with BglII which cut the plasmid in one location. The two enzymes are compatible so fragments cut with either enzyme can be ligated together. Fig 1 shows an image outlining the strategy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
