Week11_19_Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to create your own function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions provide a way of packaging code into reusable and easy-to-use components and are a key part of many programming languages including Python.\n",
    "\n",
    "We have already been using functions throughout this course:\n",
    " - in-built functions like `print()` or `len()`\n",
    " - type-specific methods like `list.append()` or `str.split()`\n",
    " - functions from imported modules like `np.cos()` or `random.default_rng().random()`\n",
    " - but also functions that have been defined within your workbooks to simplify our code e.g. `lcg_random()` function from Week 8 or the `inside_ellipse()` function from Week 9."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a similar fashion to other constructs in Python (like `for` loops and `if` statements), functions have a rigid structure. They are composed of some necessary scaffolding and some user defined input.\n",
    "\n",
    "Let us consider the following function called `add_lists`, which would allow us to add the elements of two lists together:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add_lists(x, y):\n",
    "    z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):\n",
    "        z.append(x[i] + y[i])\n",
    "    return z"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining a function\n",
    "\n",
    "To create this function, first we must use the `def` keyword to start a function definition:\n",
    "\n",
    "<pre>\n",
    " ↓\n",
    "<b style=\"color:darkred\">def</b> add_lists(x, y):\n",
    "    z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):\n",
    "        z.append(x[i] + y[i])\n",
    "    return z\n",
    "</pre>\n",
    "\n",
    "Then we specify the name that we want to give the function. Like anything in Python, choose a descriptive name that describes what it does. This is the name which we will use when *calling* the function:\n",
    "\n",
    "<pre>\n",
    "        ↓\n",
    "def <b style=\"color:darkred\">add_lists</b>(x, y):\n",
    "    z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):\n",
    "        z.append(x[i] + y[i])\n",
    "    return z\n",
    "</pre>\n",
    "\n",
    "Function definitions must then be followed by a pair of round brackets. This is a similar syntax to that used when *calling* a function and giving it arguments but here we're just defining it:\n",
    "\n",
    "<pre>\n",
    "             ↓    ↓\n",
    "def add_lists<b style=\"color:darkred\">(</b>x, y<b style=\"color:darkred\">)</b>:\n",
    "    z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):\n",
    "        z.append(x[i] + y[i])\n",
    "    return z\n",
    "</pre>\n",
    "\n",
    "Between those brackets go the names of the parameters we want the function to accept. We can define zero or more parameters. Here we are defining two:\n",
    "\n",
    "<pre>\n",
    "              ↓  ↓\n",
    "def add_lists(<b style=\"color:darkred\">x, y</b>):\n",
    "    z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):\n",
    "        z.append(x[i] + y[i])\n",
    "    return z\n",
    "</pre>\n",
    "\n",
    "Finally, the line is completed with a colon:\n",
    "\n",
    "<pre>\n",
    "                   ↓\n",
    "def add_lists(x, y)<b style=\"color:darkred\">:</b>\n",
    "    z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):\n",
    "        z.append(x[i] + y[i])\n",
    "    return z\n",
    "</pre>\n",
    "\n",
    "Since we've used a colon, we must indent the body of the function as we did with loops and conditional statements:\n",
    "\n",
    "<pre>\n",
    "def add_lists(x, y):\n",
    "    <b style=\"color:darkred\">z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):</b>  ← body of function<b style=\"color:darkred\">\n",
    "        z.append(x[i] + y[i])\n",
    "    return z</b>\n",
    "</pre>\n",
    "\n",
    "Most functions will also want to return data back to the code that called it. You can choose what data is returned using the `return` keyword followed by the data you want to return:\n",
    "\n",
    "<pre>\n",
    "def add_lists(x, y):\n",
    "    z = []\n",
    "    length_x = len(x)\n",
    "    for i in range(length_x):\n",
    "        z.append(x[i] + y[i])\n",
    "    <b style=\"color:darkred\">return</b> z\n",
    "      ↑\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using the function\n",
    "\n",
    "This function can then be *called* (i.e. used) in the same way as any other function: with round brackets `(` `)` and passing the input arguments we want to use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "list1 = [1, 2, 3]\n",
    "list2 = [3, 4, 5]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[4, 6, 8]\n"
     ]
    }
   ],
   "source": [
    "added_list = add_lists(list1,list2)\n",
    "print(added_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quick exercise\n",
    "\n",
    "Use the `add_lists()` function above as a template to create a `multiply_lists()` function. This should multiply the elements of two lists together and return the output as a new list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def multiply_lists(x, y):\n",
    "    ### ADD CODE HERE\n",
    "    return z"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "raises-exeception"
    ]
   },
   "outputs": [],
   "source": [
    "### RUN THIS CELL TO CHECK THE OUTPUT OF YOUR FUNCTION\n",
    "\n",
    "# What output would we expect from this function?\n",
    "multipled_list = multiply_lists(list1, list2)\n",
    "print(multipled_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The next notebook contains details of using a website called [Code Wars](https://www.codewars.com), which you will do within groups in breakout rooms. The challenges within Code Wars will be asking you to write some code within functions. This will generally be the same sort of code you have been writing before but in a function block so feel free to use this workbook as a reference if needed.\n",
    "\n",
    "### [Code Wars challenge](Week11_20_CodeWars.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.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}