Python/Python_Lesson_06.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "wjZKXZ9dXJUr"
   },
   "source": [
    "<a name=\"top\"></a>\n",
    "\n",
    "# Introduction to Python Programming for Bioinformatics. Lesson 6\n",
    "\n",
    "<details>\n",
    "<summary>\n",
    "About this notebook\n",
    "</summary>\n",
    "\n",
    "This notebook was originally written by [Marc Cohen](https://github.com/mco-gh), an engineer at Google. The original source can be found on [Marc's short link service](https://mco.fyi/), and starts with [Python lesson 0](https://mco.fyi/py0), and I encourage you to work through that notebook if you find some details missing here.\n",
    "\n",
    "Rob Edwards edited the notebook, adapted it for bioinformatics, using some simple geneticy examples, condensed it into a single notebook, and rearranged some of the lessons, so if some of it does not make sense, it is Rob's fault!\n",
    "\n",
    "It is intended as a hands-on companion to an in-person course, and if you would like Rob to teach this course (or one of the other courses) don't hesitate to get in touch with him.\n",
    "\n",
    "</details>\n",
    "<details>\n",
    "<summary>\n",
    "Using this notebook\n",
    "</summary>\n",
    "\n",
    "You can download the original version of this notebook from [GitHub](https://linsalrob.github.io/ComputationalGenomicsManual/Python/Python_Lesson_06.ipynb) and from [Rob's Google Drive]()\n",
    "\n",
    "**You should make your own copy of this notebook by selecting File->Save a copy in Drive from the menu bar above, and then you can edit the code and run it as your own**\n",
    "\n",
    "There are several lessons, and you can do them in any order. I've tried to organise them in the order I think most appropriate, but you may disagree!\n",
    "</details>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "_Km_oeNBXJUy"
   },
   "source": [
    "# Lesson Links\n",
    "<a name=\"lessons\"></a>\n",
    "\n",
    "* [Lesson 6 - Functions](#Lesson-6---Functions)\n",
    "  * [Defining Functions](#Defining-Functions)\n",
    "  * [Docstrings](#Docstrings)\n",
    "  * [Return Values](#Return-Values)\n",
    "\n",
    "Previous Lesson: [Local](Python_Lesson_05.ipynb) | [GitHub](https://linsalrob.github.io/ComputationalGenomicsManual/Python/Python_Lesson_05.ipynb) | [Google Colab](https://colab.research.google.com/drive/1VmGd4AAb1fBKOjmemYIKnPgu58xGE5so)\n",
    "\n",
    "Next Lesson: [Local](Python_Lesson_07.ipynb) | [GitHub](https://linsalrob.github.io/ComputationalGenomicsManual/Python/Python_Lesson_07.ipynb) | [Google Colab](https://colab.research.google.com/drive/1Uq9ysM5TxMsiS9vElA53Ihl63ONOYDTA)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "t0HB4x7zSarK"
   },
   "source": [
    "# Lesson 6 - Functions\n",
    "\n",
    "## Functions are flexible software building blocks\n",
    "\n",
    "* So far, we’ve been writing small programs.\n",
    "* Things get much more complicated when we write large programs, especially with multiple authors.\n",
    "* Ideally, we'd like to build software like snapping lego pieces together.\n",
    "* What would that buy us?\n",
    "  * abstraction\n",
    "  * reuse\n",
    "  * modularity\n",
    "  * maintainability\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Q1AThwoeWq-_"
   },
   "source": [
    "### Abstraction - You don't need to do everything\n",
    "\n",
    "* When building a house, you don't do everything yourself.\n",
    "  * You hire an architect, a carpenter, an electrician, a roofer, a plumber, a mason.\n",
    "  * You might hire a contractor to hire and manage all those people.\n",
    "* In our programs we delegate tasks to certain functions, like `print()`, so that we don't have to worry about all the details.\n",
    "  * It's a bit like hiring an electrician so that we don't have to worry about the details of electrical wiring in our house (or getting blown up!)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "kRSeTwXFW7DM"
   },
   "source": [
    "### Reuse - Don't Reinvent the Wheel\n",
    "\n",
    "* it's OK to reuse other people's work\n",
    "  * it's not stealing\n",
    "  * it makes you more efficient and more productive\n",
    "* Very few people build a house from scratch\n",
    "  * so don't try to build programs from scratch\n",
    "* Most of the software we produce is called `open source software` which means\n",
    "  * you can look at the source\n",
    "  * you can change the source\n",
    "  * you can do more complex things with it\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "5tT_kiFjYIpb"
   },
   "source": [
    "#### Reuse Example\n",
    "You can count the number of bases in a DNA sequence the hard way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "executionInfo": {
     "elapsed": 29,
     "status": "ok",
     "timestamp": 1718613809134,
     "user": {
      "displayName": "Rob Edwards",
      "userId": "17780279723170493443"
     },
     "user_tz": -570
    },
    "id": "uubqVKszFLoK",
    "outputId": "2c6b00ce-1abf-427a-9f5a-2bd3935ecec0"
   },
   "outputs": [],
   "source": [
    "sequence = \"ATGCATAGCTAGCATCAGACTGATGCATCGACTGATCGACTGT\"\n",
    "bases = 0\n",
    "valid_bases = [\"A\", \"T\", \"G\", \"C\"]\n",
    "for i in sequence:\n",
    "    if i in valid_bases:\n",
    "        bases += 1\n",
    "\n",
    "print(f\"There are {bases} bases in {sequence}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "a804f1uCFemA"
   },
   "source": [
    "Or the easy way, by calling a method..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "executionInfo": {
     "elapsed": 23,
     "status": "ok",
     "timestamp": 1718613809134,
     "user": {
      "displayName": "Rob Edwards",
      "userId": "17780279723170493443"
     },
     "user_tz": -570
    },
    "id": "aXu9iH9kFkXM",
    "outputId": "46cfa1b1-b2a6-48ff-a993-75d4125aaca9"
   },
   "outputs": [],
   "source": [
    "sequence = \"ATGCATAGCTAGCATCAGACTGATGCATCGACTGATCGACTGT\"\n",
    "print(f\"There are {len(sequence)} bases in {sequence}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ZjlWbakQFhz2"
   },
   "source": [
    "Which would you rather use? Which is more reliable?\n",
    "* The first approach is great for learning.\n",
    "* The second approach is great for getting real work done.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "PGbEhmEAYXxv"
   },
   "source": [
    "### Modularity - Divide and Conquer\n",
    "* So far, our programs have been monoliths - one  continous sequence of Python statements.\n",
    "* Real programs are often much bigger than the ones we've written.\n",
    "  * Google's software repository has billions of lines of source code ([Why Google Stores Billions of Lines of Code in a Single Repository](https://cacm.acm.org/magazines/2016/7/204032-why-google-stores-billions-of-lines-of-code-in-a-single-repository/fulltext))\n",
    "  * No one person can write a program that big.\n",
    "  * Large programs are built by teams.\n",
    "  * In order to build large, complex programs, we need the ability to divide program logic into manageable pieces.\n",
    "* We call this modularity - dividing software into pieces or modules.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "iBPnZBIdZCCq"
   },
   "source": [
    "### Maintainability - Keeping your code DRY (Don't Repeat Yourself)\n",
    "* Imagine that you need to do roughly the same thing in ten different places so you copy the code to those ten locations.\n",
    "  * What happens when you find a bug or want to improve that piece of code?\n",
    "  * You need to make the change ten times.\n",
    "  * Will you remember to do that?\n",
    "  * If you do remember, will you catch all ten locations?\n",
    "  * Copying code is a **bad thing** - it leads to bugs.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "XsXu3tyfZagC"
   },
   "source": [
    "### Functions solve all of these Problems\n",
    "\n",
    "* Functions give us the ability to:\n",
    "  * Hide low level details (abstraction)\n",
    "  * Share and reuse pieces of functionality (reuse)\n",
    "  * Split programs into manageable pieces (modularity)\n",
    "  * Write one copy of an algorithm and use it anywhere (maintainability)\n",
    "* We've already used several functions\n",
    "  * `print()`, `input()`, `int()`, `len()`, `range()`, etc.\n",
    "* Now let's see how to define our own functions.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "xjZpdnvMycJM"
   },
   "source": [
    "## Defining Functions\n",
    "\n",
    "* example:\n",
    "```\n",
    "def function_name(arg1, arg2):\n",
    "    '''This is a docstring.'''  # optional but a good idea\n",
    "    statement1\n",
    "    statement2\n",
    "    ...\n",
    "```\n",
    "* Not surprisingly, we define the scope of the function body using indentation (just like how we define blocks for if statements, for loops, etc.).\n",
    "* This is a bit like an assignment statement in that it assigns a block of code (the function body) to the function name.\n",
    "  * Function names have the same rules as variable names.\n",
    "  * This only defines a function - it doesn't execute it.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "executionInfo": {
     "elapsed": 393,
     "status": "ok",
     "timestamp": 1719454811823,
     "user": {
      "displayName": "Rob Edwards",
      "userId": "17780279723170493443"
     },
     "user_tz": -570
    },
    "id": "5Hlbe-sYaJp8",
    "outputId": "8f571ffc-21d7-46b2-d448-aa1c14c6669a"
   },
   "outputs": [],
   "source": [
    "def next_base():\n",
    "  '''\n",
    "     This function generates a DNA sequence base.\n",
    "     It's how Illumina sequencing works.\n",
    "  '''\n",
    "  bases = [\"A\", \"G\", \"T\", \"C\"]\n",
    "  print(bases[0])\n",
    "\n",
    "next_base()\n",
    "next_base()\n",
    "next_base()\n",
    "print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "5o2mco2220b1"
   },
   "source": [
    "### Docstrings\n",
    "* string defined immediately after the def line\n",
    "* usually triple quoted since it may be multi-line\n",
    "* not required but a good way to document your functions\n",
    "* IDEs use the docstring to make your life easier\n",
    "* automates output of `help(function)`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "bRhweVvt3CVf"
   },
   "source": [
    "### Example Function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "executionInfo": {
     "elapsed": 359,
     "status": "ok",
     "timestamp": 1719459489512,
     "user": {
      "displayName": "Rob Edwards",
      "userId": "17780279723170493443"
     },
     "user_tz": -570
    },
    "id": "xbJeh1p5QCvy"
   },
   "outputs": [],
   "source": [
    "# Reverse complement a DNA sequence\n",
    "# Here's an example function definition...\n",
    "def reverse_complement(dna):\n",
    "    \"\"\"\n",
    "    Reverse complement a DNA sequence\n",
    "    :param dna: The DNA sequence\n",
    "    :type dna: str\n",
    "    :return: The reverse complement of the DNA sequence\n",
    "    :rtype: str\n",
    "    \"\"\"\n",
    "    complements = str.maketrans('acgtrymkbdhvACGTRYMKBDHV', 'tgcayrkmvhdbTGCAYRKMVHDB')\n",
    "    rcseq = dna.translate(complements)[::-1]\n",
    "    return rcseq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "executionInfo": {
     "elapsed": 357,
     "status": "ok",
     "timestamp": 1719455175839,
     "user": {
      "displayName": "Rob Edwards",
      "userId": "17780279723170493443"
     },
     "user_tz": -570
    },
    "id": "-QC40fS6P6eW",
    "outputId": "811ce209-ea5b-402f-af8e-3500673cb4ad"
   },
   "outputs": [],
   "source": [
    "# Get help about this function...\n",
    "help(reverse_complement)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 35
    },
    "executionInfo": {
     "elapsed": 361,
     "status": "ok",
     "timestamp": 1719459495265,
     "user": {
      "displayName": "Rob Edwards",
      "userId": "17780279723170493443"
     },
     "user_tz": -570
    },
    "id": "JQ3S4ickQSHo",
    "outputId": "87699e43-8af1-4538-bbc9-1f91025b512e"
   },
   "outputs": [],
   "source": [
    "# And here's how we would call this function...\n",
    "sequence = \"ATCGATCGCATAGCTACGACTAGCTACGACTGACT\"\n",
    "reverse_complement(sequence)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "3aRAKCjF44YD"
   },
   "source": [
    "### Passing Values to a Function\n",
    "\n",
    "* The variables we define in a function to take on the values passed by the caller are called parameters.\n",
    "* In this code, `a`, `b` and `c` are parameters:\n",
    "```\n",
    "def sum(a, b, c):\n",
    "    return a + b + c\n",
    "```\n",
    "* The values supplied by the caller when calling a function are called arguments.\n",
    "* In this code, `1`, `2`, and `3` are arguments:\n",
    "```\n",
    "sum(1, 2, 3)\n",
    "```\n",
    "\n",
    "So in our example above, the `function` `rc()` has one parameter (`dna`) and the code to run it passes one argument (`sequence`).\n",
    "\n",
    "Don't get hung up on this, most people use argument and parameter interchangeably.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "RxZNVXjg5hyP"
   },
   "source": [
    "### Passing Arguments\n",
    "* Functions can define any number of parameters, including zero.\n",
    "* Multiple parameters are separated by commas, like this...\n",
    "```\n",
    "def product(a, b, c):\n",
    "    return a * b * c\n",
    "```\n",
    "* If you pass the wrong number of arguments, you'll hear about it:\n",
    "```\n",
    "product(1, 2)\n",
    "...\n",
    "TypeError: product() takes exactly 3 positional argument (2 given)\n",
    "...\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "kNuuRlHm5x51"
   },
   "source": [
    "## Return Values\n",
    "\n",
    "Instead of printing the result, we can also have the function return a result to the caller so that the caller can print it or use it in a calculation.\n",
    "\n",
    "For example, our `reverse_complement()` function returns the reverse complement of the sequence. We can store that in a new variable and do things with it.\n",
    "\n",
    "```\n",
    "sequence = \"ATGCATCGCATCGATCAGCTACGACTCGACTCGAT\"\n",
    "reverse_complement = reverse_complement(sequence)\n",
    "# do something with reverse_complement\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "1faLXr5p6BVU"
   },
   "source": [
    "* Functions return a value to the caller via the `return` statement.\n",
    "* The `return` statement causes two things to happen...\n",
    "  * the function ends and control is returned to the caller\n",
    "  * the returned value is passed back to the caller\n",
    "* You can have as many return statements as you like (including zero).\n",
    "* If the caller wants to do something with a returned value, it needs to save it or use it in an expression...\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "a290fc13"
   },
   "source": [
    "[Return to the lesson listing](#lessons)\n",
    "\n",
    "[Return to the top of the notebook](#top)"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "provenance": [
    {
     "file_id": "15KAyGvriQwRoXQa3t70jmi3XumKBxDRi",
     "timestamp": 1718237753735
    }
   ]
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}