005_Write_Your_Own_Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://www.hydroffice.org/epom/\"><img src=\"images/000_000_epom_logo.png\" alt=\"ePOM\" title=\"Open ePOM home page\" align=\"center\" width=\"12%\" alt=\"Python logo\\\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://piazza.com/class/js5dnu0q39n6qe\"><img src=\"images/help.png\" alt=\"ePOM\" title=\"Ask questions on Piazza.com\" align=\"right\" width=\"10%\" alt=\"Piazza.com\\\"></a>\n",
    "# Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have met (and used) several of the many [built-in functions](https://docs.python.org/3.6/library/functions.html) that are shipped with Python: [`print()`](000_Welcome_on_Board.ipynb#What-is-a-Code-cell?), [`type()`](001_Variables_and_Types.ipynb#Dynamic-Nature-of-a-Variable-Type), [`len()`](002_Lists_of_Variables.ipynb#Creation-of-a-List:-Approach-#1), [`dir()`](002_Lists_of_Variables.ipynb#List's-Methods)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function provides a mechanism to represent many lines of code targeting a specific task with a single statement."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A **function** is a named sequence of statements."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A function **encapsulates** a task. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The variables created inside a function are **local variables**. They are not usable (**visible**) outside of the function where they are created."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This allows you to use variable names in your code without having to worry about whether the same names may be used inside some of the functions that you are using."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "Once created, a function can be used multiple times, each time that the function task is required (**code reusability**)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since reusing a function does not require to rewrite its internal code, creating functions helps to reduce duplicated code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a Function: Function Declaration and Definition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create your own function:\n",
    "\n",
    "1. Select a **meaningful** name for the function.\n",
    "2. Put the selected name after the `def` keyword, followed by curved parentheses and ending with a `:`\n",
    "3. Indent the code that has to be executed (the **body** of the function)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A meaningful function name reduces (and sometimes even removes) the need to [add comments in your code](003_Conditional_Execution.ipynb#Add-Comments-to-the-Code). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_temp_list():\n",
    "    temp_list = [23.0, 19.2, 18.5, 21.3, 20.4]\n",
    "    print(temp_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you execute the above **Code** cell, nothing is printed. No worries, this is correct! We have **only** declared the function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now use (**call**) the declared function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print_temp_list()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A function has to be first declared using the `def` keyword, then it can be executed multiple times. To execute a function we **call** it by typing its name followed by brackets: e.g., `my_function()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Modify the code to call a function that prints the number of elements in the `sal_list`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "def print_len_sal_list():\n",
    "    sal_list = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]  # water salinity in PSU\n",
    "    len_sal_list = len(sal_list)\n",
    "    print(\"Nr. of elements: \" + str(len_sal_list))\n",
    "    \n",
    "print_len_sal_list()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sal_list = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding Parameters to a Function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is very common to **pass** one or more values to a function, so that operations can be performed on those values."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "**Parameters** are used to define the values that can be passed into a function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "When a function is called, the values passed to fulfill its parameters are called **arguments**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will modify the code example above to introduce the use of a parameter. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We first add the `sal_list` parameter so that you can pass *any* salinity list to the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_len_sal_list(sal_list):\n",
    "    len_sal_list = len(sal_list)\n",
    "    print(\"Nr. of elements: \" + str(len_sal_list))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `sal_list` parameter identifies the local variable name for the value passed to the function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now create a `salinity_values` variable and pass it to the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_len_sal_list(sal_list):\n",
    "    len_sal_list = len(sal_list)\n",
    "    print(\"Nr. of elements: \" + str(len_sal_list))\n",
    "\n",
    "salinity_values = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]\n",
    "\n",
    "# call the 'print_len_sal_list' function with the 'salinity_values' variable to fulfill the 'sal_list' parameter\n",
    "print_len_sal_list(salinity_values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "In the above code, the name of the `sal_list` parameter differs from the name of the `salinity_values` variable that was passed to the `print_len_sal_list` function. This makes the code **more readable**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "To make the above concept more explicit, we may also explicitly assign (**named parameter**) `salinity_values` to the `sal_list` parameter (i.e., `print_len_sal_list(sal_list=salinity_values)`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_len_sal_list(sal_list):\n",
    "    len_sal_list = len(sal_list)\n",
    "    print(\"Nr. of elements: \" + str(len_sal_list))\n",
    "\n",
    "salinity_values = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]\n",
    "print_len_sal_list(sal_list=salinity_values)  # we are now explicitly assigning the named parameter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will now create a function that takes three parameters (`sal_min` and `sal_max` in addition to `sal_list`). \n",
    "\n",
    "The following `print_filtered_sal_list()` function only prints the values within the range defined by `sal_min` and `sal_max`: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_filtered_sal_list(sal_list, sal_min, sal_max):\n",
    "    \n",
    "    for sal_value in sal_list:  # we loop through all the values in the `sal_list`\n",
    "        \n",
    "        if (sal_value > sal_min) and (sal_value < sal_max): # we apply a condition using relational and logical operators\n",
    "            print(str(sal_value))  # we print the salinity value only when the above condition is valid\n",
    "\n",
    "salinity_values = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]\n",
    "salinity_min = 33.0  # PSU\n",
    "salinity_max = 34.0  # PSU\n",
    "print_filtered_sal_list(salinity_values, salinity_min, salinity_max) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generalizing the Use of a Function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Given the task performed in the function body (i.e., printing the number of elements) in the above **Code** cells, the same **function** will work with any type of list. \n",
    "\n",
    "Let us try to **generalize** the above `print_len_sal_list()` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_len_list(a_list):  # the `sal` is removed from the function name, the parameter is now generically named `a_list`\n",
    "    len_a_list = len(a_list)\n",
    "    print(\"Nr. of elements: \" + str(len_a_list))\n",
    "\n",
    "sal_list = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]\n",
    "print_len_list(sal_list)  # we first use the `print_len_list` to print the length of a list of salinity values\n",
    "\n",
    "temp_list = [23.0, 19.2, 18.5, 21.3, 20.4]\n",
    "print_len_list(temp_list)  # we now use the same function to print the lenght of a list of temperature values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It worked! The `print_len_list()` now prints the number of elements, independently from the content of the list that is passed to the function. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The creation of your own **functions** reduces the code repetition in your programs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Returning a Value from a Function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, a function provides back (**returns**) a special Python object: [`None`](https://docs.python.org/3.6/c-api/none.html?highlight=none#the-none-object)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "`None` denotes lack of value."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Thus, if we assign the result of our previous `print_len_list()` function to a variable, its type will be `NoneType`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_len_list(a_list):\n",
    "    len_a_list = len(a_list)\n",
    "    print(\"Nr. of elements: \" + str(len_a_list))\n",
    "    \n",
    "temp_list = [23.0, 19.2, 18.5, 21.3, 20.4]\n",
    "result = print_len_list(temp_list)  # the function returns the default `None`\n",
    "type(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will now use the `return` mechanism (`return` is [a Python keyword](001_Variables_and_Types.ipynb#Python-Variable-Naming)) to provide back something potentially useful: the number of elements. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def len_list(a_list):\n",
    "    len_a_list = len(a_list)\n",
    "    return len_a_list\n",
    "    \n",
    "temp_list = [23.0, 19.2, 18.5, 21.3, 20.4]\n",
    "nr_of_elements = len_list(temp_list)  # the function returns the number of elements in the list\n",
    "print(\"The number of elements is: \" + str(nr_of_elements))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the following notebooks, you will get some practice in writing functions that return useful values."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Functions and Their Local Variables"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As [previously stated](005_Write_Your_Own_Functions.ipynb#Functions), the **local variables** of a function are only **visible** inside the function where they are created. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code below was *specifically* written to highlight some of the implications of this concept:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define a function that calculates the flattening using the semi-major and semi-minor axes.\n",
    "# The function has a local variable named 'flattening'.\n",
    "def calc_flattening(a, b):\n",
    "    flattening = (a - b) / a\n",
    "    return flattening\n",
    "    \n",
    "# A global variable holding a textual definition of flattening\n",
    "flattening = \"The measure of compression of a cirle to form an ellipse\"\n",
    "\n",
    "# Numeric values of the semi-major and semi-minor axes of an ellipse representing the shape of the Earth\n",
    "semi_major = 6378137.0  # meters\n",
    "semi_minor = 6356752.314245  # meters\n",
    "\n",
    "# Print the definition of flattening\n",
    "print(\"The textbook definition of flattening is: \" + flattening)\n",
    "\n",
    "# Call the previously defined function\n",
    "print(\"The flattening of the Earth is: \" + str(calc_flattening(semi_major, semi_minor)))\n",
    "      \n",
    "# Re-print the definition of flattening \n",
    "# The use of the 'flattening' variable inside the function does NOT affect the value of the global 'flattening' variable!\n",
    "print(\"The textbook definition of flattening is still: \" + flattening)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example above defines and calls a `calc_flattening` function that calculates the [flattening](https://en.wikipedia.org/wiki/Flattening) of an ellipse."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code has two variables with the same name:\n",
    "\n",
    "* The **local** `flattening` variable within the `calc_flattening` function.\n",
    "* The **global** `flattening` variable that is used to store a textual definition of the [flattening](https://en.wikipedia.org/wiki/Flattening) of an ellipse.\n",
    "\n",
    "These two variables do not affect each other. They are in a different **namespace**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Anatomy of a Function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook has introduced a number of terms that are specific to functions!\n",
    "\n",
    "To review some of these terms, we start by first creating code that defines and uses a very simple function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(a, b):\n",
    "    total = a + b\n",
    "    return total\n",
    "\n",
    "val0 = 23\n",
    "val1 = 4\n",
    "\n",
    "result = add(val0, val1)\n",
    "\n",
    "print(\"The sum is: \" + str(result))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following image visually identifies some of the function-specific terms related to the above code:\n",
    "\n",
    "![Function Terminology](images/005_500_function_terminology.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You now know **how to write your own functions!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The combined mechanism to pass variables to a function (using [parameters](#Adding-Parameters-to-a-Function)) and to [return a value](http://localhost:8888/notebooks/python_basics/005_Write_Your_Own_Functions.ipynb#Returning-value-of-a-function) after its execution is a powerful mechanism to reduce code repetition and to better organize your programs. \n",
    "\n",
    "We will end this notebook with an exercise that will give you a bit of more freedom on how to implement the code. Feel free to experiment with some of the notions that you have just learned. The provided solution is just one of the possible way to achieve the task!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Write a `filtered_float_list` function that takes a `list` of `float` values and returns only the values within a specific range. The validity range has to be specified using two parameters. Finally, print the returned filtered list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "def filtered_float_list(float_list, float_min, float_max):\n",
    "    \n",
    "    filtered_list = list()  # we created an empty list to store the filtered values\n",
    "    \n",
    "    for float_value in float_list:  # we loop through all the values in the passed list\n",
    "        \n",
    "        if (float_value > float_min) and (float_value < float_max): # condition using relational and logical operators\n",
    "            filtered_list.append(float_value)\n",
    "    \n",
    "    return filtered_list  # we need to return the filtered list so that it can be used for further analysis\n",
    "\n",
    "salinity_values = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]\n",
    "salinity_min = 33.0  # min range in PSU\n",
    "salinity_max = 34.0  # max range in PSU\n",
    "filtered_values = filtered_float_list(salinity_values, salinity_min, salinity_max)\n",
    "print(str(filtered_values))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "salinity_values = [32.6, 33.3, 34.8, 32.4, 34.3, 33.7, 32.3]\n",
    "salinity_min = 33.0  # min range in PSU\n",
    "salinity_max = 34.0  # max range in PSU"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px; padding-top:10px;\" src=\"images/refs.png\">\n",
    "\n",
    "## Useful References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [The official Python 3.6 documentation](https://docs.python.org/3.6/index.html)\n",
    "  * [Built-in functions](https://docs.python.org/3.6/library/functions.html)\n",
    "  * [None](https://docs.python.org/3.6/c-api/none.html?highlight=none#the-none-object)\n",
    "* [Flattening](https://en.wikipedia.org/wiki/Flattening)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"5%\" style=\"padding-right:10px;\" src=\"images/email.png\">\n",
    "\n",
    "*For issues or suggestions related to this notebook, write to: epom@ccom.unh.edu*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "[< Loops](004_Loops.ipynb) | [Contents](index.ipynb) | [Read and Write Text Files >](006_Read_and_Write_Text_Files.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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}