docs/notebooks/PCR.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to Perform a Polymerase Chain Reaction (PCR)\n",
    "\n",
    "> Visit the full library documentation [here](https://bjornfjohansson.github.io/pydna/)\n",
    "\n",
    "This page walks you through how to perform a PCR, and design PCR primers, using `pydna`. A PCR amplifies a specific stretch of DNA defined by the primers, and it is critical to ensure primer binding specificity and appropriate primer melting temperature (tm) through careful design. `pydna` provides tools for quick modelling of PCR to check for correct PCR products, and methods for calculating tm and primer design, as performed in other popular web servcies (e.g Primer3Plus). \n",
    "\n",
    "## Modelling PCR with Known Primers\n",
    "\n",
    "To perform PCR, `pydna` provides the `anneal` class and the `pcr` method to quickly generate expected primer products, on a `Dseqrecord` object. The `pcr` method needs only the forward and reverse primers, and the sequence. The primers must be passed from the 5' to the 3' end, following biological convention. More information on `Dseqrecord` and importing DNA sequences can be found in the other guide pages. \n",
    "  \n",
    "The following example uses a 300+ bp custom sample circular DNA, containing an example gene that we would like to clone. 18 bp forward and reverse primers have been provided. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a target=\"_blank\" href=\"https://colab.research.google.com/github/BjornFJohansson/pydna/blob/dev_bjorn/docs/notebooks/PCR.ipynb\">\n",
    "  <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",
    "</a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install pydna (only when running on Colab)\n",
    "import sys\n",
    "if 'google.colab' in sys.modules:\n",
    "    %%capture\n",
    "    # Install the current development version of pydna (comment to install pip version)\n",
    "    !pip install git+https://github.com/BjornFJohansson/pydna@dev_bjorn\n",
    "    # Install pip version instead (uncomment to install)\n",
    "    # !pip install pydna\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LOCUS       45bp_PCR_prod             45 bp    DNA     linear   UNK 01-JAN-1980\n",
       "DEFINITION  pcr_product_description_description.\n",
       "ACCESSION   45bp\n",
       "VERSION     45bp\n",
       "KEYWORDS    .\n",
       "SOURCE      .\n",
       "  ORGANISM  .\n",
       "            .\n",
       "FEATURES             Location/Qualifiers\n",
       "     gene            1..45\n",
       "                     /label=\"example_gene\"\n",
       "     primer_bind     1..18\n",
       "                     /label=\"name\"\n",
       "                     /PCR_conditions=\"primer sequence:ATTCCTGCAGAGTACATC\"\n",
       "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
       "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
       "     primer_bind     complement(28..45)\n",
       "                     /label=\"name\"\n",
       "                     /PCR_conditions=\"primer sequence:ACCATCCGAAGATATCTT\"\n",
       "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
       "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
       "ORIGIN\n",
       "        1 attcctgcag agtacatcaa ttctatgaag atatcttcgg atggt\n",
       "//"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from pydna.amplify import pcr\n",
    "from pydna.dseqrecord import Dseqrecord\n",
    "from pydna.parsers import parse\n",
    "\n",
    "#Importing GenBank file containing sample sequence \n",
    "path = \"./sample_seq.gb\"\n",
    "record = parse(path)[0]\n",
    "\n",
    "#Defining forward and reverse primers\n",
    "fwd_primer = \"ATTCCTGCAGAGTACATC\"\n",
    "rvs_primer = \"ACCATCCGAAGATATCTT\"\n",
    "\n",
    "#Performing PCR\n",
    "pcr_product = pcr(fwd_primer, rvs_primer, record)\n",
    "\n",
    "#Printing results\n",
    "pcr_product.format(\"gb\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `pcr` method then returns a `Amplicon` class object (to model a PCR product), a subclass of `Dseqrecord` with some extra methods (e.g `.figure`. See \"Other ways of visualising the PCR products\" section below). All the features inside the PCR product has been retained. Note how the example gene has been retained as a feature in `pcr_product`. In addition, two new features have been added to the record to indicate the forward and reverse primer binding regions.\n",
    "\n",
    "`pydna` also allows modelling for PCR with extra bases on the 5' end of primers. This functionality is useful for modelling molecular cloning with multiple steps, where you might want to add different restriction sites to PCR products and ensure that the right sequences have been replicated.\n",
    "\n",
    "For instance, to make sure that I can add a HindIII restriction site (AAGCTT) at the end of my `example_gene` without accidental hybridisation with other parts of the circular sequence, I can perform PCR in the `pydna` package like so."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LOCUS       57bp_PCR_prod             57 bp    DNA     linear   UNK 01-JAN-1980\n",
       "DEFINITION  pcr_product_description_description.\n",
       "ACCESSION   57bp\n",
       "VERSION     57bp\n",
       "KEYWORDS    .\n",
       "SOURCE      .\n",
       "  ORGANISM  .\n",
       "            .\n",
       "FEATURES             Location/Qualifiers\n",
       "     primer_bind     1..21\n",
       "                     /label=\"name\"\n",
       "                     /PCR_conditions=\"primer sequence:AAGCTTATTCCTGCAGAGTACATC\"\n",
       "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
       "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
       "     gene            4..48\n",
       "                     /label=\"example_gene\"\n",
       "     primer_bind     complement(31..48)\n",
       "                     /label=\"name\"\n",
       "                     /PCR_conditions=\"primer sequence:AAGCTTACCATCCGAAGATATCTT\"\n",
       "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
       "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
       "ORIGIN\n",
       "        1 aagcttattc ctgcagagta catcaattct atgaagatat cttcggatgg taagctt\n",
       "//"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fwd_primer = \"AAGCTTATTCCTGCAGAGTACATC\"\n",
    "rvs_primer = \"AAGCTTACCATCCGAAGATATCTT\"\n",
    "\n",
    "#Performing PCR\n",
    "pcr_product_HindIII = pcr(fwd_primer, rvs_primer, record)\n",
    "\n",
    "#Printing results\n",
    "pcr_product_HindIII.format(\"gb\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more information on restriction digests and ligation, please refer to the Restriction and Ligation page.  \n",
    "\n",
    "## Other ways of visualising the PCR products \n",
    "\n",
    "In addition to the normal `print` function and the `.format()` method (More information can be found in Dseq and Importing_Seqs pages, respectively), pcr products can also be visualized in other ways.\n",
    "\n",
    "We can check the sequence of the pcr products alone using the `.seq` attribute on a PCR product:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ATTCCTGCAGAGTACATCAATTCTATGAAGATATCTTCGGATGGT\n"
     ]
    }
   ],
   "source": [
    "print(pcr_product.seq)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also visualize the pcr products as a figure, using the `.figure` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5ATTCCTGCAGAGTACATC...AAGATATCTTCGGATGGT3\n",
      "                      ||||||||||||||||||\n",
      "                     3TTCTATAGAAGCCTACCA5\n",
      "5ATTCCTGCAGAGTACATC3\n",
      " ||||||||||||||||||\n",
      "3TAAGGACGTCTCATGTAG...TTCTATAGAAGCCTACCA5\n"
     ]
    }
   ],
   "source": [
    "print(pcr_product.figure())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Designing Primers and Calculating Tm in pydna\n",
    "\n",
    "`pydna` also provides the `primer_design` method to design primer sequences based on the desired pcr product and the template sequence's melting temperature (Tm). The `primer_design` method can be imported from the `pydna.design` module, and needs the user to supply the PCR template sequence (as a `Dseqrecord` object) and the Tm. The template sequence should be given as the first parameter, and the Tm give through the `target_tm=` argument, as demonstrated below. If you have no specific Tm in mind, the method uses the default Tm of 55 degrees celcius.\n",
    "\n",
    "Note that in the following example below, I used zero-based indexing on the `Dseqrecord` to find the sequence of my example gene, of which I would like to clone via PCR. Please refer to the `Dseq` page for more information on how to index a sequence. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "LOCUS       example_gene              45 bp    DNA     linear   UNK 01-JAN-1980\n",
      "DEFINITION  pcr_product_f45 example_gene_r45 example_gene.\n",
      "ACCESSION   example_gene\n",
      "VERSION     example_gene\n",
      "KEYWORDS    .\n",
      "SOURCE      .\n",
      "  ORGANISM  .\n",
      "            .\n",
      "FEATURES             Location/Qualifiers\n",
      "     gene            1..45\n",
      "                     /label=\"example_gene\"\n",
      "     primer_bind     1..16\n",
      "                     /label=\"f45\"\n",
      "                     /PCR_conditions=\"primer sequence:ATTCCTGCAGAGTACA\"\n",
      "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
      "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
      "     primer_bind     complement(29..45)\n",
      "                     /label=\"r45\"\n",
      "                     /PCR_conditions=\"primer sequence:ACCATCCGAAGATATCT\"\n",
      "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
      "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
      "ORIGIN\n",
      "        1 attcctgcag agtacatcaa ttctatgaag atatcttcgg atggt\n",
      "//\n"
     ]
    }
   ],
   "source": [
    "from pydna.design import primer_design\n",
    "\n",
    "#Designing the primers\n",
    "primers = primer_design(record[6:51], target_tm=50.0)\n",
    "\n",
    "#Printing the output\n",
    "print(primers.format(\"gb\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The formula for primer design in `pydna` is based on the Tm formula from Rychlik et al (1990), found [here](http://www.ncbi.nlm.nih.gov/pubmed/2243783). Additional information on calculating Tm can be found in the \"Calculating Tm\" section below.\n",
    "\n",
    "The forward and reverse primer sequences are printed in the features list of the `Amplicon` object. Note how the feature representing the example gene is retained, as appropriate.  \n",
    "\n",
    "If you already have a forward / reverse primer, `primer_design` also allows this information to be taken as arguments. `fp` specifies the forward primer, `rp` specifies the reverse primers. `fp` and `rp` can be should be given as `Primer` class objects, which should be imported from `pydna` too.  \n",
    "\n",
    "For instance, if I already have a forward primer containing an EcoRI restriction site, and I aim to to generate a reverse primer of a similar Tm, I can apply the following code:  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "LOCUS       example_gene              51 bp    DNA     linear   UNK 01-JAN-1980\n",
      "DEFINITION  pcr_product_forward_primer example_gene_r45 example_gene.\n",
      "ACCESSION   example_gene\n",
      "VERSION     example_gene\n",
      "KEYWORDS    .\n",
      "SOURCE      .\n",
      "  ORGANISM  .\n",
      "            .\n",
      "FEATURES             Location/Qualifiers\n",
      "     gene            1..45\n",
      "                     /label=\"example_gene\"\n",
      "     primer_bind     1..19\n",
      "                     /label=\"f45\"\n",
      "                     /PCR_conditions=\"primer sequence:GAATTCATTCCTGCAGAGTACATCA\"\n",
      "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
      "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
      "     primer_bind     complement(26..45)\n",
      "                     /label=\"r45\"\n",
      "                     /PCR_conditions=\"primer sequence:ACCATCCGAAGATATCTTCA\"\n",
      "                     /ApEinfo_fwdcolor=\"#baffa3\"\n",
      "                     /ApEinfo_revcolor=\"#ffbaba\"\n",
      "ORIGIN\n",
      "        1 gaattcattc ctgcagagta catcaattct atgaagatat cttcggatgg t\n",
      "//\n"
     ]
    }
   ],
   "source": [
    "from pydna.primer import Primer\n",
    "\n",
    "forward_primer = Primer(\"GAATTCATTCCTGCAGAGTACATCA\", id=\"forward_primer\")\n",
    "\n",
    "primers_sixfive = primer_design(record[6:51], fp = forward_primer)\n",
    "\n",
    "print(primers_sixfive.format(\"gb\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Calculating Tm\n",
    "\n",
    "`pydna` comes with some functions to calculate Tms. The default function `tm_default` used is the previously mentioned one by Rychlik et al (1990), which takes a string as input. Another function derive from the Tm calculation adapted for primers using polymerases with a DNA binding domain (e.g Phusion polymerase). The default values for Tm calculation, including primer concentration, buffer strengths, and more, can also be modified through arguments in the `tm_default` method. Please refer to the `pydna.tm` module docstring for more information. An example is provided with a pair of primers; the temperature is given in degrees celcius."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "55.901005046706075\n",
      "55.841913263215304\n"
     ]
    }
   ],
   "source": [
    "from pydna.tm import tm_default\n",
    "\n",
    "# Example Tm calculation for a pair of primers\n",
    "primer_f = \"ATTCCTGCAGAGTACATCA\"\n",
    "primer_r = \"ACCATCCGAAGATATCTTCA\"\n",
    "tm_f = tm_default(primer_f)\n",
    "tm_r = tm_default(primer_r)\n",
    "\n",
    "print(tm_f)\n",
    "print(tm_r)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.12.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}