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/e-learning_python_for_ocean_mapping/summer2019/om000/home\"><img src=\"images/help.png\" alt=\"ePOM\" title=\"Ask questions on Piazza.com\" align=\"right\" width=\"10%\" alt=\"Piazza.com\\\"></a>\n",
    "# Write Your Own 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": [
    "It is now time to empower you with the capability to create your own function. But what is a function?"
   ]
  },
  {
   "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": [
    "## Function declaration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to create your own function:\n",
    "\n",
    "1. You first need to think of a meaningful name to give to the function. 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). \n",
    "2. You put the selected name after the `def` keyword, followed by curved parentheses and ending with a `:`.\n",
    "3. You indent the body of the function (that is, the code that has to be executed)."
   ]
  },
  {
   "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. We can now 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, than it can be called (i.e., executed) multiple times."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "shown",
    "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": "shown"
   },
   "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 a very common requirement to be able to pass one or more variables to a function so that operations can be performed on those variables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The **parameters** are used to pass the values of selected variables into a function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The **parameters** define the **arguments** that a function can take."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By modifying the previous code example, we will add the `sal_list` parameter to the function in the previous code example. Then, we will call the modified function passing a `salinity_list` variable. "
   ]
  },
  {
   "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(salinity_values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The name of the parameter (i.e., `sal_list`) differs from the name of the variable that was passed to the function (i.e., `salinity_values`). This makes the code **more readable** avoiding any potential confusion in the code reader about which of the lists a statement is applied to."
   ]
  },
  {
   "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 value of a function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, a function 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. It has no methods."
   ]
  },
  {
   "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)\n",
    "type(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will now use the returning mechanism (by means of the `return` keyword) to provide back to the function caller 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)\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": [
    "# Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You now know **how to write your own functions!**\n",
    "\n",
    "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)"
   ]
  },
  {
   "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) | [Dictionaries and Metadata >](006_Dictionaries_and_Metadata.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
}