docs/cookbook/cookbook.ipynb

{
 "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",
    "<div>\n",
    "<img src=\"logo.png\" width=\"15%\"/>\n",
    "</div>"
   ]
  },
  {
   "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 mostly on Biopython (a python bioinformatics package), networkx (a graph theory package).\n",
    "\n",
    "## What does Pydna provide?\n",
    "\n",
    "Pydna provides 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. \n",
    "\n",
    "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. \n",
    "\n",
    "The advantage of documenting with pydna is that 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",
    "Look [here](https://github.com/BjornFJohansson/pydna-examples) for examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 1: Sub cloning by restriction digestion and ligation\n",
    "\n",
    "The construction of the vector YEp24PGK_XK is described on page 4250 in the publication below:\n",
    "\n",
    "[Johansson et al., “Xylulokinase Overexpression in Two Strains of Saccharomyces cerevisiae Also Expressing Xylose Reductase and Xylitol Dehydrogenase and Its Effect on Fermentation of Xylose and Lignocellulosic Hydrolysate” Applied and Environmental Microb](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC93154/)\n",
    "\n",
    "Briefly, the XKS1 gene from _Saccharomyces cerevisiae_ was amplified by PCR using two primers called primer1 and primer3.\n",
    "\n",
    "The primers add restriction sites for BamHI to the ends of the  XKS1 gene. \n",
    "\n",
    "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. BamHI and BglII are compatible so fragments cut with either enzyme can be ligated together. \n",
    "\n",
    "Fig 1 shows an image outlining the strategy. BamHI is the blue enzyme and BglII is shown in yellow.\n",
    "\n",
    "<div>\n",
    "<img src=\"figure1.png\" width=\"50%\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pydna.genbank import Genbank"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "gb = Genbank(\"myemail@mydomain.com\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "YEp24PGK = gb.nucleotide(\"KC562906.1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The representation of the YEp24PGK object includes a link to the record on Genbank."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href='https://www.ncbi.nlm.nih.gov/nuccore/KC562906.1?from=&to=&strand=1' target='_blank'>KC562906.1</a>"
      ],
      "text/plain": [
       "Gbnk(o9637 KC562906.1)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "YEp24PGK"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(o9637)\n",
       "GAAT..TCAA\n",
       "CTTA..AGTT"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "YEp24PGK.seq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pydna.parsers import parse_primers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "p1, p3 = parse_primers(\n",
    "    '''\n",
    ">primer1\n",
    "GCGGATCCTCTAGAATGGTTTGTTCAGTAATTCAG\n",
    ">primer3\n",
    "AGATCTGGATCCTTAGATGAGAGTCTTTTCCAG'''\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "XKS1 = gb.nucleotide(\"Z72979.1\").rc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href='https://www.ncbi.nlm.nih.gov/nuccore/Z72979.1?from=&to=&strand=2' target='_blank'>Z72979.1</a>"
      ],
      "text/plain": [
       "Gbnk(-3140 Z72979.1)"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "XKS1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-3140)\n",
       "ATGA..AAAA\n",
       "TACT..TTTT"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "XKS1.seq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pydna.amplify import pcr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "PCR_prod = pcr(p1, p3, XKS1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Primer1 and 3 add restriction sites to the PCR product. The stuffer fragments are removed after digestion."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "                    5TGTTCAGTAATTCAG...CTGGAAAAGACTCTCATCTAA3\n",
       "                                       |||||||||||||||||||||\n",
       "                                      3GACCTTTTCTGAGAGTAGATTCCTAGGTCTAGA5\n",
       "5GCGGATCCTCTAGAATGGTTTGTTCAGTAATTCAG3\n",
       "                     |||||||||||||||\n",
       "                    3ACAAGTCATTAAGTC...GACCTTTTCTGAGAGTAGATT5"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "PCR_prod.figure()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "from Bio.Restriction import BamHI, BglII"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "stuffer1, insert, stuffer2 = PCR_prod.cut(BamHI)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Dseqrecord(-7), Dseqrecord(-1819), Dseqrecord(-11))"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "stuffer1, insert, stuffer2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-1819)\n",
       "GATCCTCT..TAAG    \n",
       "    GAGA..ATTCCTAG"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "insert.seq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "YEp24PGK_BglII = YEp24PGK.linearize(BglII)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dseq(-9641)\n",
       "GATCTCCC..AAAA    \n",
       "    AGGG..TTTTCTAG"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "YEp24PGK_BglII.seq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "YEp24PGK_XK = (YEp24PGK_BglII + insert).looped()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "YEp24PGK_XK = YEp24PGK_XK.synced(YEp24PGK)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'t9fs_9UvEuD-Ankyy8XEr1hD5DQ'"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "YEp24PGK_XK.cseguid()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<font face=monospace><a href='YEp24PGK_XK.gb' target='_blank'>YEp24PGK_XK.gb</a></font><br>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "YEp24PGK_XK.write(\"YEp24PGK_XK.gb\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 2: Sub cloning by homologous recombination\n",
    "\n",
    "The construction of the vector pGUP1 is described in the publication:\n",
    "\n",
    "[Régine Bosson, Malika Jaquenoud, and Andreas Conzelmann, “GUP1 of Saccharomyces cerevisiae Encodes an O-acyltransferase Involved in Remodeling of the GPI Anchor,” Molecular Biology of the Cell 17, no. 6 (June 2006): 2636–2645.](https://www.molbiolcell.org/doi/10.1091/mbc.e06-02-0104)\n",
    "\n",
    "Our objective is to replicate the cloning steps using Pydna so that we can have the final sequence of the plasmid.\n",
    "\n",
    "The cloning is described in the paper on page 2637 on the upper left side of the publication:\n",
    "\n",
    "\"The expression vectors harboring GUP1 or GUP1H447A were obtained as follows: the open reading frame of GUP1 was amplified by PCR using plasmid pBH2178 (kind gift from Morten Kielland-Brandt) as a template and using primers  and, underlined sequences being homologous to the target vector pGREG505 (Jansen et al., 2005). The PCR fragment was purified by a PCR purification kit (QIAGEN, Chatsworth, CA) and introduced into pGREG505 by co transfection into yeast cells thus generating pGUP1 (Jansen et al., 2005).\"\n",
    "\n",
    "\n",
    "<div>\n",
    "<img src=\"figure2.png\" width=\"50%\"/>\n",
    "</div>\n",
    "\n",
    "\n",
    "Briefly, two primers (GUP1rec1sens and GUP1rec2AS) were used to amplify the GUP1 gene from _Saccharomyces cerevisiae_ chromosomal DNA using the two primers:\n",
    "\n",
    "    >GUP1rec1sens \n",
    "    gaattcgatatcaagcttatcgataccgatgtcgctgatcagcatcctgtc\n",
    "\n",
    "    >GUP1rec2AS\n",
    "    gacataactaattacatgactcgaggtcgactcagcattttaggtaaattccg\n",
    "\n",
    "Then the vector pGREG505 was digested with the restriction enzyme SalI. This is not mentioned in  Bosson et. al, but they make a reference to Jansen 2005:\n",
    "\n",
    "Jansen G, Wu C, Schade B, Thomas DY, Whiteway M. 2005. Drag&Drop cloning in yeast. Gene, 344: 43–51. \n",
    "\n",
    "Jansen et al describe the pGREG505 vector and that it is digested with SalI before cloning. The SalI digests the vector in two places, so a fragment containing the HIS3 gene is removed.\n",
    "\n",
    "The SalI sites are visible in the plasmid drawing in Fig. 3.\n",
    "\n",
    "<div>\n",
    "<img src=\"pGREG505.png\" width=\"30%\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "GUP1rec1sens, GUP1rec2AS = parse_primers(\n",
    "    '''\n",
    ">GUP1rec1sens\n",
    "gaattcgatatcaagcttatcgataccgatgtcgctgatcagcatcctgtc\n",
    ">GUP1rec2AS\n",
    "gacataactaattacatgactcgaggtcgactcagcattttaggtaaattccg\n",
    "'''\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "GUP1_locus = gb.nucleotide(\"Z72606\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "insert = pcr(GUP1rec1sens, GUP1rec2AS, GUP1_locus)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "                               5tcagcattttaggtaaattccg...gacaggatgctgatcagcgacat3\n",
       "                                                         |||||||||||||||||||||||\n",
       "                                                        3ctgtcctacgactagtcgctgtagccatagctattcgaactatagcttaag5\n",
       "5gacataactaattacatgactcgaggtcgactcagcattttaggtaaattccg3\n",
       "                                ||||||||||||||||||||||\n",
       "                               3agtcgtaaaatccatttaaggc...ctgtcctacgactagtcgctgta5"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "insert.figure()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pydna.readers import read"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "pGREG505 = read(\"pGREG505.gb\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href='pGREG505.gb' target='_blank'>pGREG505.gb</a><br>"
      ],
      "text/plain": [
       "File(pGREG505)(o9465)"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pGREG505"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "from Bio.Restriction import SalI"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [],
   "source": [
    "his3_stuffer, lin_vect = pGREG505.cut(SalI)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Dseqrecord(-8301), Dseqrecord(-1172))"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "lin_vect, his3_stuffer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pydna.assembly import Assembly"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Assembly class implements homologous recombination and make use of the [NetworkX](https://networkx.org) package to find all recombination products."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [],
   "source": [
    "asm = Assembly((lin_vect, insert))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Assembly\n",
       "fragments..: 8301bp 1742bp\n",
       "limit(bp)..: 25\n",
       "G.nodes....: 4\n",
       "algorithm..: common_sub_strings"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "asm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [],
   "source": [
    "candidates = asm.assemble_circular()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The two candidates are equivalent"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [],
   "source": [
    "candidate1, candidate2 = candidates"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 55,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "candidate1.cseguid() == candidate2.cseguid()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [],
   "source": [
    "pGUP1 = candidate1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [],
   "source": [
    "pGUP1 = pGUP1.synced(pGREG505)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'0R8hr15t-psjHVuuTj_JufGxOPg'"
      ]
     },
     "execution_count": 58,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pGUP1.cseguid()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<font face=monospace><a href='pGUP1.gb' target='_blank'>pGUP1.gb</a></font><br>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "pGUP1.write(\"pGUP1.gb\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:bjorn311]",
   "language": "python",
   "name": "conda-env-bjorn311-py"
  },
  "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.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}