session3/notebooks/1_python_functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Organizing Code for Readability and Reusability: Functions\n",
    "\n",
    "Whether you're writing code in a jupyter notebook or in a script, eventually your code will get long enough that it becomes a challenge to keep it understandable and easy to find useful pieces to reuse in other projects.\n",
    "\n",
    "The most common way of organizing code is to break it into into smaller functions. To make a function, you need to tell Python:\n",
    "\n",
    "- The function's name,\n",
    "- The inputs (a.k.a \"arguments\") that the function needs to do its work, and\n",
    "- The output (a.k.a. \"return value\") that the function will give to whatever code that called it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Example**: Create a function called `add` that adds two numbers and returns the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(x, y):   # Define a function name and its arguments x and y\n",
    "    z = x + y    # Make calculations in the function body\n",
    "    return z     # \"Return\" data out of the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = add(5, 3)  # Then the function can be called again, changing the argument values for whatever you want!\n",
    "\n",
    "result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Create a function called `multiply` that multiplies two numbers and returns the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Create a function called `calculate_mean` that takes a list of numbers as input and returns the mean. Please do not use numpy for this :)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Packaging Code into Functions as Refactoring\n",
    "\n",
    "Because writing functions is often done during a refactoring (reorganizing) process in writing code, let's practice refactoring by taking code that already works and changing it into a function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Example**: Make a function out of the code below, so the following line works:\n",
    "```python\n",
    "c = subtract(5, 3)`\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = 10\n",
    "b = 2\n",
    "result = a - b\n",
    "result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def subtract(a, b):\n",
    "    result = a - b\n",
    "    return result\n",
    "\n",
    "c = subtract(5, 3)\n",
    "c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Make a function out of the code below, so the following line works:\n",
    "\n",
    "```python\n",
    "numbers = [1, 2, 3, 4, 5]\n",
    "std = calculate_std(numbers)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mean = calculate_mean(numbers)\n",
    "variance = sum([(x - mean) ** 2 for x in numbers]) / len(numbers)\n",
    "std = variance ** 0.5"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Make a function out of the code below, so the following line works:\n",
    "\n",
    "```python\n",
    "numbers = [1, 2, 3, 4, 5]\n",
    "median = calculate_median(numbers)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "numbers = [3, 1, 4, 2, 5]\n",
    "\n",
    "numbers.sort()\n",
    "n = len(numbers)\n",
    "mid = n // 2\n",
    "if n % 2 == 0:\n",
    "    median = (numbers[mid - 1] + numbers[mid]) / 2\n",
    "else:\n",
    "    median = numbers[mid]\n",
    "\n",
    "median"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Below we have some code to plot a historgram of a numpy array. Can you turn it into a function such that we can use it as `plot_histogram(data, nbins=50)`?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "data = np.random.randn(1000)\n",
    "\n",
    "nbins = 20\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "figure, ax = plt.subplots(ncols=1, nrows=1)\n",
    "ax.hist(data, bins=nbins);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Functions with Optional Arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Example**: Create a function that by default converts a temperature value in Celcius to Fahrenheit, but the user can convert it to Kelvin by specifying the corresponding input argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def convert_celcius(temp, to='fahrenheit'):\n",
    "    if to == 'fahrenheit':\n",
    "        return temp * 9/5 + 32\n",
    "    elif to == 'kelvin':\n",
    "        return temp + 273.15\n",
    "    else:\n",
    "        return \"Unknown scale\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Modify the `plot_histogram()` function such that we can optionally also specify the color of the histogram: `plot_histogram(data, nbins=50, color=\"crimson\")`. Default color should be black."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Create a function, called `compute_stat()`, that by default computes the mean, but when the `kind` argument is specified it can also compute standard deviation or median. Inside this function, make use of the functions you already defined in the previous exercises."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise**: Create a function that by default normalizes the data between 0 and 1, but the user can optionally also specify a lower value and/or and upper value so that the data will be normalized accordingly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Function description (i.e. docstring)\n",
    "\n",
    "When sharing our project with others such that they use the functions we have created, it would be nice to provide some documentation for the function such that the user can just refer to the documentation and get an understanding of how to use it:\n",
    "- what does the function do on a high level?\n",
    "- what is each input argument?\n",
    "- what type should each input argument be?\n",
    "- what does the function return?\n",
    "- what is the type of the variable that the function returns?\n",
    "\n",
    "the description of a function is usually referred to the \"docstring\" which stands for documentation string.\n",
    "\n",
    "If we look at commonly used packages such as Numpy and Pandas pretty much all of the methods they have has an extensive docstring. Let's see some examples:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to see the docstring we can use the `?` after the function name (without the `()`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.max?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.clip?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### How do we create a docstring for our own functions?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While there are several commonly used styles for creating docstrings for functions, the **Google Style** is favored by many for its simplicity and readability. Here is an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(num1, num2):\n",
    "    \"\"\"Adds two numbers and returns the sum.\n",
    "\n",
    "    Args:\n",
    "        num1 (int or float): The first addend.\n",
    "        num2 (int or float): The second addend.\n",
    "\n",
    "    Returns:\n",
    "        int or float: The sum of `num1` and `num2`.\n",
    "    \"\"\"\n",
    "    return num1 + num2\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "add?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "workshop-env",
   "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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}