python_fm_2.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Working with Python: functions and modules\n",
    "\n",
    "## Session 2: Functions\n",
    "\n",
    "- [Function definition syntax](#Function-definition-syntax)\n",
    "- [Exercise 2.1](#Exercise-2.1)\n",
    "- [Return value](#Return-value)\n",
    "- [Exercise 2.2](#Exercise-2.2)\n",
    "- [Function arguments](#Function-arguments)\n",
    "- [Variable scope](#Variable-scope)\n",
    "- [Exercise 2.3](#Exercise-2.3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Function basics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have already seen a number of functions built into python that let us do useful things to strings, collections and numbers etc. For example **`print()`** or **`len()`** which is passed some kind of sequence object and returns the length of the sequence.\n",
    "\n",
    "This is the general form of a function; it takes some input _arguments_ and returns some output based on the supplied arguments.\n",
    "\n",
    "The arguments to a function, if any, are supplied in parentheses and the result of the function _call_ is the result of evaluating the function.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = abs(-3.0)\n",
    "print(x)\n",
    "\n",
    "l = len(\"ACGGTGTCAA\")\n",
    "print(l)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As well as using python's built in functions, you can write your own. Functions are a nice way to **encapsulate some code that you want to reuse** elsewhere in your program, rather than repeating the same bit of code multiple times. They also provide a way to name some coherent block of code and allow you to structure a complex program."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Function definition syntax"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions are defined in Python using the **`def` keyword** followed by the name of the function. If your function takes some arguments (input data) then you can name these in parentheses after the function name. If your function does not take any arguments you still need some empty parentheses. Here we define a simple function named `sayHello` that prints a line of text to the screen:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def sayHello():\n",
    "    print('Hello world!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the code block for the function (just a single print line in this case) is indented relative to the `def`. The above definition just decalares the function in an abstract way and nothing will be printed when the definition is made. To actually use a function you need to invoke it (call it) by using its name and a pair of round parentheses:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sayHello() # Call the function to print 'Hello world'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If required, a function may be written so it accepts input. Here we specify a variable called `name` in the brackets of the function definition and this variable is then used by the function. Although the input variable is referred to inside the function the variable does not represent any particular value. It only takes a value if the function is actually used in context."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def sayHello(name):\n",
    "    print('Hello', name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we call (invoke) this function we specify a specific value for the input. Here we pass in the value `User`, so the name variable takes that value and uses it to print a message, as defined in the function. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sayHello('User')  # Prints 'Hello User'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we call the function again with a different input value we naturally get a different message. Here we also illustrate that the input value can also be passed-in as a variable (text in this case)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "text = 'Mary'\n",
    "sayHello(text)     # Prints 'Hello Mary'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function may also generate output that is passed back or returned to the program at the point at which the function was called. For example here we define a function to do a simple calculation of the square of input (`x`) to create an output (`y`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def square(x):\n",
    "  y = x*x\n",
    "  return y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the `return` statement is reached the operation of the function will end, and anything on the return line will be passed back as output. Here we call the function on an input number and catch the output value as result. Notice how the names of the variables used inside the function definition are separate from any variable names we may choose to use when calling the function.\n",
    "  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "number = 7\n",
    "result = square(number) # Call the square() function which returns a result\n",
    "print(result)           # Prints: 49"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function `square` can be used from now on anywhere in your program as many times as required on any (numeric) input values we like."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(square(1.2e-3))   # Prints: 1.4399999999999998e-06"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function can accept multiple input values, otherwise known as arguments. These are separated by commas inside the brackets of the function definition. Here we define a function that takes two arguments and performs a calculation on both, before sending back the result.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calcFunc(x, y):\n",
    "  z = x*x + y*y\n",
    "  return z\n",
    "\n",
    "\n",
    "result = calcFunc(1.414, 2.0)\n",
    "print(result)  #  5.999396"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that this function does not check that x and y are valid forms of input. For the function to work properly we assume they are numbers. Depending on how this function is going to be used, appropriate checks could be added."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions can be arbitrarily long and can peform very complex operations. However, to make a function reusable, it is often better to assign it a single responsibility and a descriptive name.\n",
    "Let's define now a function to calculate the [Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance) between two vectors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calcDistance(vec1, vec2):    \n",
    "    dist = 0\n",
    "    for i in range(len(vec1)):\n",
    "        delta = vec1[i] - vec2[i]\n",
    "        dist += delta*delta\n",
    "    dist = dist**(1/2) # square-root\n",
    "    return dist"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the record, the [prefered way to calcule a square-root](https://docs.python.org/3/library/math.html#math.sqrt) is by using the built-in function `sqrt()` from the `math` library:\n",
    "```python\n",
    "import math\n",
    "math.sqrt(x)\n",
    "```\n",
    "\n",
    "Let's experiment a little with our function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w1 = ( 23.1, 17.8, -5.6 )\n",
    "w2 = ( 8.4, 15.9, 7.7 )\n",
    "calcDistance( w1, w2 )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the function is general and handles any two vectors (irrespective of their representation) as long as their dimensions are compatible:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "calcDistance( ( 1, 2 ), ( 3, 4 ) ) # dimension: 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "calcDistance( [ 1, 2 ], [ 3, 4 ] ) # vectors represented as lists"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "calcDistance( ( 1, 2 ), [ 3, 4 ] ) # mixed representation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 2.1\n",
    "\n",
    "- a. Calculate the mean\n",
    "    - Write a function that takes 2 numerical arguments and returns their mean. Test your function on some examples.\n",
    "    - Write another function that takes a list of numbers and returns the mean of all the numbers in the list.\n",
    "- b. Write a function that takes a single DNA sequence as an argument and estimates the molecular weight of this sequence. Test your function using some example sequences. The following table gives the weight of each (single-stranded) nucleotide in g/mol:\n",
    "\n",
    "<table>\n",
    "    <tr><th>DNA Residue</th><th>Weight</th></tr>\n",
    "    <tr><td>A</td><td>331</td></tr>\n",
    "    <tr><td>C</td><td>307</td></tr>\n",
    "    <tr><td>G</td><td>347</td></tr>\n",
    "    <tr><td>T</td><td>306</td></tr>\n",
    "</table>\n",
    "\n",
    "\n",
    "- c. If the sequence passed contains base `N`, use the mean weight of the other bases as the weight of base `N`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Return value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There can be more than one `return` statement in a function, although typically there is only one, at the bottom. Consider the following function to get some text to say whether a number is positive or negative. It has three return statements: the first two return statements pass back text strings but the last, which would be reached if the input value were zero, has no explicit return value and thus passes back the Python `None` object. Any function code after this final return is ignored. \n",
    "The `return` keyword immediately exits the function, and no more of the code in that function will be run once the function has returned (as program flow will be returned to the call site)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def getSign(value):\n",
    "    \n",
    "    if value > 0:\n",
    "        return \"Positive\"\n",
    "    \n",
    "    elif value < 0:\n",
    "        return \"Negative\"\n",
    "    \n",
    "    return # implicit 'None'\n",
    "\n",
    "    print(\"Hello world\") # execution does not reach this line\n",
    "    \n",
    "print(\"getSign( 33.6 ):\", getSign( 33.6 ))\n",
    "print(\"getSign( -7 ):\", getSign( -7 ))\n",
    "print(\"getSign( 0 ):\", getSign( 0 ))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All of the examples of functions so far have returned only single values, however it is possible to pass back more than one value via the `return` statement. In the following example we define a function that takes two arguments and passes back three values. The return values are really passed back inside a single tuple, which can be caught as a single collection of values. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def myFunction(value1, value2):\n",
    "    \n",
    "    total = value1 + value2\n",
    "    difference = value1 - value2\n",
    "    product = value1 * value2\n",
    "    \n",
    "    return total, difference, product\n",
    "\n",
    "values = myFunction( 3, 7 )  # Grab output as a whole tuple\n",
    "print(\"Results as a tuple:\", values)\n",
    "\n",
    "x, y, z = myFunction( 3, 7 ) # Unpack tuple to grab individual values\n",
    "print(\"x:\", x)\n",
    "print(\"y:\", y)\n",
    "print(\"z:\", z)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 2.2\n",
    "\n",
    "a. Write a function that counts the number of each base found in a DNA sequence. Return the result as a tuple of 4 numbers representing the counts of each base `A`, `C`, `G` and `T`.\n",
    "\n",
    "b. Write a function to return the reverse-complement of a nucleotide sequence."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Function arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Mandatory arguments\n",
    "\n",
    "The arguments we have passed to functions so far have all been _mandatory_, if we do not supply them or if supply the wrong number of arguments python will throw an error also called an exception:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def square(number):\n",
    "    # one mandatory argument\n",
    "    y = number*number\n",
    "    return y"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "square(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Mandatory arguments are assumed to come in the same order as the arguments in the function definition**, but you can also opt to specify the arguments using the argument names as _keywords_, supplying the values corresponding to each keyword with a `=` sign."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "square(number=3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def repeat(seq, n):\n",
    "    # two mandatory arguments\n",
    "    result = ''\n",
    "    for i in range(0,n):\n",
    "        result += seq\n",
    "    return result\n",
    "\n",
    "print(repeat(\"CTA\", 3))\n",
    "print(repeat(n=4, seq=\"GTT\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert-warning\">**NOTE** Unnamed (positional) arguments must come before named arguments, even if they look to be in the right order.</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(repeat(seq=\"CTA\", n=3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Arguments with default values\n",
    "Sometimes it is useful to give some arguments a default value that the caller can override, but which will be used if the caller does not supply a value for this argument. We can do this by assigning some value to the named argument with the `=` operator in the function definition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def runSimulation(nsteps=1000):\n",
    "    print(\"Running simulation for\", nsteps, \"steps\")\n",
    "\n",
    "runSimulation(500)\n",
    "runSimulation()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert-warning\">**CAVEAT**: default arguments are defined once and keep their state between calls. This can be a problem for *mutable* objects:</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def myFunction(parameters=[]):\n",
    "    parameters.append( 100 )\n",
    "    print(parameters)\n",
    "    \n",
    "myFunction()\n",
    "myFunction()\n",
    "myFunction()\n",
    "myFunction([])\n",
    "myFunction([])\n",
    "myFunction([])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... or avoid modifying *mutable* default arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def myFunction(parameters):\n",
    "    # one mandatory argument without default value\n",
    "    parameters.append( 100 )\n",
    "    print(parameters)\n",
    "    \n",
    "my_list = []\n",
    "myFunction(my_list)\n",
    "myFunction(my_list)\n",
    "myFunction(my_list)\n",
    "my_new_list = []\n",
    "myFunction(my_new_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Position of mandatory arguments\n",
    "Arrange function arguments so that *mandatory* arguments come first:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def runSimulation(initialTemperature, nsteps=1000):\n",
    "    # one mandatory argument followed by one with default value\n",
    "    print(\"Running simulation starting at\", initialTemperature, \"K and doing\", nsteps, \"steps\")\n",
    "    \n",
    "runSimulation(300, 500)\n",
    "runSimulation(300)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before, no positional argument can appear after a keyword argument, and all required arguments must still be provided."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "runSimulation( nsteps=100, initialTemperature=300 )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "runSimulation( initialTemperature=300 )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "runSimulation( nsteps=100 ) # Error: missing required argument 'initialTemperature'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "runSimulation( nsteps=100, 300 ) # Error: positional argument follows keyword argument"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keyword names must naturally match to those declared:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "runSimulation( initialTemperature=300, numSteps=100 ) # Error: unexpected keyword argument 'numSteps'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Function cannot be defined with mandatory arguments after default ones."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def badFunction(nsteps=1000, initialTemperature):\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Variable scope"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Every variable in python has a _scope_ in which it is defined. Variables defined at the outermost level are known as _globals_ (although typically only for the current module). In contrast, variables defined within a function are local, and cannot be accessed from the outside."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def mathFunction(x, y):\n",
    "    math_func_result = ( x + y ) * ( x - y )\n",
    "    return math_func_result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "answer = mathFunction( 4, 7 )\n",
    "print(answer)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "answer = mathFunction( 4, 7 )\n",
    "print(math_func_result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we have two variables with the same name but they do have different scopes, one local to the function and the other one global, therefore they are different."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def increase(value):\n",
    "    value += 1\n",
    "    print(value)\n",
    "    \n",
    "value = 4\n",
    "increase(value)\n",
    "print(value)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Generally, variables defined in an outer scope are also visible in functions, but you should be careful manipulating them as this can lead to confusing code and python will actually raise an error if you try to change the value of a global variable inside a function. Instead it is a good idea to avoid using global variables and, for example, to pass any necessary variables as parameters to your functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "counter = 4\n",
    "def increment(): \n",
    "    counter += 1\n",
    "    return counter\n",
    "\n",
    "print(counter)\n",
    "print(increment())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use a local variable instead"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def increment(): \n",
    "    counter = 4\n",
    "    counter += 1\n",
    "    return counter\n",
    "\n",
    "print(increment())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or pass any necessary variables as parameters to your functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def increment(counter): \n",
    "    counter += 1\n",
    "    return counter\n",
    "\n",
    "print(increment(4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 2.3\n",
    "\n",
    "Extend your solution to the previous exercise estimating the weight of a DNA sequence so that it can also calculate the weight of an RNA sequence, use an optional argument to specify the molecule type, but default to DNA. The weights of RNA residues are:\n",
    "\n",
    "<table>\n",
    "    <tr><th>RNA Residue</th><th>Weight</th></tr>\n",
    "    <tr><td>A</td><td>347</td></tr>\n",
    "    <tr><td>C</td><td>323</td></tr>\n",
    "    <tr><td>G</td><td>363</td></tr>\n",
    "    <tr><td>U</td><td>324</td></tr>\n",
    "</table>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next session\n",
    "\n",
    "Go to our next notebook: [python_functions_and_modules_3](python_fm_3.ipynb)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}