01_Basic_Python_intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Basics\n",
    "## Syntax, Functions, Useful Packages, Reading Error Messages\n",
    "\n",
    "### Before you start\n",
    "We'll be assuming you have:\n",
    "1. Installed Python 3 and Jupyter (steps 1 and 2 of [this guide](https://nbviewer.jupyter.org/github/rses-datascience/DataSurgeries/blob/master/S01_GettingStarted/Getting%20Started%20in%20Python.ipynb)).\n",
    "2. Know the very-basics of Python.\n",
    "\n",
    "If you're unsure on point 2, do  [this 'first steps in python' course](https://www.codecademy.com/en/courses/learn-python/lessons/python-syntax/exercises/welcome). It has 13 steps, and takes about 10 minutes to complete. \n",
    "\n",
    "\n",
    "### Programme:\n",
    "1. Basics of Jupyter: cells, evaluation, note taking.\n",
    "2. Basic structure of Python: variables, types, packages, namespaces.\n",
    "3. Iterating: loops, conditional loops, list comprehension.\n",
    "4. Functions: making code re-usable\n",
    "5. Useful Packages: Python can't actually do that much...\n",
    "6. Breaking stuff: errors, and how to interpret them"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Jupyter Basics\n",
    "\n",
    "### Cells\n",
    "Jupyter is arranged as a series of 'cells'. There are two types of cells - `Markdown` cells for taking notes \n",
    "(like this one), and `code` cells, like the next one. The type of the cell determines what Jupyter does when you 'evaluate' the cell. A `markdown` cell will be rendered as nice text, and a `code` cell will be sent to Python to be run."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is code cell (this is a python comment, so nothing will happen when we evaluate it)\n",
    "\n",
    "# Notice how the number in square brackets on the left increases each time you evaluate the cell?\n",
    "# This allows you to keep track of what *order* the code cells have been run in. This can be important,\n",
    "# as we'll get to later."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Shortcut Keys\n",
    "Jupyter fantastic, fast and flexible... but you won't find this out until you break free of the menu bar at the top, and get to know the shortcut keys. You can see the full list of shortcut keys in the Help menu at the top.\n",
    "\n",
    "The Jupyter Notebook has two different keyboard input modes. 'Edit' mode allows you to type code or text into a cell, and is indicated by a green cell border. Command mode binds the keyboard to notebook level commands and is indicated by a grey cell border with a blue left margin.\n",
    "\n",
    "In **Both Modes**:\n",
    "- <kbd>Ctrl-Enter</kbd>: Evaluate current cell, keep focus on cell\n",
    "- <kbd>Shift-Enter</kbd>: Evaluate current cell, move to next cell\n",
    "- <kbd>Alt-Enter</kbd>: Evaluate current cell, insert new cell underneath\n",
    "\n",
    "In **Command Mode**:\n",
    "- <kbd>Enter</kbd>: Enter **Edit Mode**\n",
    "- <kbd>Up/Down Arrow</kbd>: Move the focus between different cells.\n",
    "- <kbd>p</kbd>: Open **Command Palette**\n",
    "- <kbd>d-d</kbd>: Delete cell\n",
    "- <kbd>a</kbd>: Create new cell above current\n",
    "- <kbd>b</kbd>: Create new cell below current\n",
    "- <kbd>c</kbd>: Copy current cell\n",
    "- <kbd>v</kbd>: Paste copied cell below current\n",
    "\n",
    "In **Edit Mode**:\n",
    "- <kbd>Esc</kbd>: Enter **Command Mode**\n",
    "- <kbd>Tab</kbd>: Auto-complete the current variable/function/parameter.\n",
    "- <kbd>Shift-Tab</kbd>: Bring up the documentation for the current function.\n",
    "- <kbd>Ctrl-/</kbd>: Comment or uncomment a line.\n",
    "\n",
    "### Note Taking\n",
    "One of the best features of Jupyter is the ability to take comprehensive notes alongside your code. Notes are written in the [Markdown](https://daringfireball.net/projects/markdown/) language, which is pleasantly simple and capable. All of this is written in markdown. In the above we've used headings and sub-headings, numbered and bulleted lists, HTML tags (the keyboard symbols above), and included links. \n",
    "\n",
    "As well as all that, you can include images, and write in-line $\\frac{Equations}{1}$, as well as standalone ones using $\\LaTeX$ notation:\n",
    "\n",
    "$$ f(x) = A e^{-\\frac{(x - b)^2}{2c^2}}$$\n",
    "\n",
    "That *should* cover all your note-taking needs.\n",
    "\n",
    "To see what markdown looks like, highlight this cell in **Command Mode**, and press <kbd>Enter</kbd> to enter **Edit Mode**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Python Structure\n",
    "\n",
    "### Variables and types\n",
    "When you're using Jupyter, it starts Python running in the background in a 'Kernel'. Whenever you evaluate a code cell, the code is sent to this Kernal to be run.\n",
    "\n",
    "Just after launch, you can think of the Python running in this kernel as a blank canvas, with almost nothing on it - just Python's 'base' functionality, which is remarkably minimal.\n",
    "\n",
    "Let's create some variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "42\n"
     ]
    }
   ],
   "source": [
    "a = 42\n",
    "print(a)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This creates a named variable that is stored by Python. In storing it, it's entered into what's called the 'namespace': the space where all the names are kept... At a low level, these 'names' store pointers towards parts of your computer's memory where the value associated with that name is stored."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'0x562785f8af20'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# to see the memory-address of the where '42' is stored on your computer.\n",
    "hex(id(a))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In practice you don't need to think about this often...\n",
    "\n",
    "When you create a variable, Python stores the data you give it, and works out what `type` it is. You can find out what `type` a variable is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'int'>\n"
     ]
    }
   ],
   "source": [
    "print(type(a))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `type` of a variable tells Python how to handle the variable when you (for example) want to add it to another variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3 <class 'int'>\n",
      "3.0 <class 'float'>\n",
      "6.0 <class 'float'>\n",
      "ab <class 'str'>\n"
     ]
    }
   ],
   "source": [
    "# add two integers\n",
    "x = 1 + 2\n",
    "print(x, type(x))\n",
    "\n",
    "# add two 'floats'\n",
    "y = 1.0 + 2.0\n",
    "print(y, type(y))\n",
    "\n",
    "# add an int and a float\n",
    "w = x + y\n",
    "print(w, type(w))\n",
    "\n",
    "# add two strings?\n",
    "z = 'a' + 'b'\n",
    "print(z, type(z))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are [a few different built-in data types](https://docs.python.org/3/library/stdtypes.html), which we'll get into a bit more later.\n",
    "\n",
    "Variables can re re-assigned:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "42 <class 'int'>\n",
      "not 42 any more! <class 'str'>\n"
     ]
    }
   ],
   "source": [
    "print(a, type(a))\n",
    "\n",
    "a = 'not 42 any more!'\n",
    "print(a, type(a))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So you have to be careful not to *overwrite* your variables while coding. This is surprisingly easy to do, as code gets longer. Be careful to use unique names for important variables!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Bad:\n",
    "important_variable = 1 + 2 * 3\n",
    "#[... lots of code ...]\n",
    "important_variable = 52.32\n",
    "\n",
    "# Good:\n",
    "variable_A = 1 + 2 * 3\n",
    "# [... lots of code ...]\n",
    "variable_B = 52.32\n",
    "\n",
    "# Always be explicit!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So let's do something useful!\n",
    "\n",
    "In science, we often deal with arrays of data, and apply various numeric operations to them. Let's do that in Python!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "can't multiply sequence by non-int of type 'float'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-7-af82365afd5d>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0mdata\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m[\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m4\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m3\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m4\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m3\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m2\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m56\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m \u001b[0mresult\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mdata\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0;36m4.3\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m: can't multiply sequence by non-int of type 'float'"
     ]
    }
   ],
   "source": [
    "data = [1, 4, 3, 4, 3, 2, 56]\n",
    "result = data * 4.3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nnnnope. The variable `data` is a `list`, which is **not** an array. A `list` can contain anything you like - numbers, string, other lists, and more... - it doesn't contain any information on how Python should treat its contents, so it's completely unsuitable for the type of numerical operations we like to do in science. This is a major difference from other languages like Matlab, where all data are stored as vectors/matrices, and can be treated as such.\n",
    "\n",
    "In Python, the basic data types are *not* designed for science - they're designed for *flexibility*. To manipulate data, we need...\n",
    "\n",
    "### Packages\n",
    "When you first start Python, there are only [a few basic functions](https://docs.python.org/3/library/functions.html#built-in-functions) available. Python can't actually do that much 'out of the box'. This is another key difference from things like Matlab, which pre-load every possible function and the kitchen sink when you start it. This is because Matlab is designed for a single purpose (matrix manipulation), so it makes sense to just load all the functions relating to matrices when you start the program. \n",
    "\n",
    "Python is multi purpose, and is used for everything from running websites to controlling robots and analysing data. Loading *all* possible functions that Python uses would be spectacularly inefficient, so instead Python uses modular 'packages', which contain a heap of functions for a specific purpose.\n",
    "\n",
    "To access these functions, you have to `import` them. For example, you can bring in *all* the functions available in the fantastic [**Nu**meric **Py**thon (numpy)](http://www.numpy.org/) package by running:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now all of numpy's vast capabilities are availabe within the `numpy` command, which you access by using a period (`.`) after `numpy`... for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "numpy.add(1,2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But this is a bit clumsy, right? Why can't we just use `add`, like we do in other (Matlab) languages? We can do this if we want to, and import all of `numpy`'s functions directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from numpy import *\n",
    "\n",
    "add(1, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**BUT WAIT!!** This is a terrible idea... remember that variable called `array` that we made at the start? `numpy` has a function in it called `array`, which has just overwritten our carefully defined variable!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<built-in function array>\n"
     ]
    }
   ],
   "source": [
    "# I create a list called array (very bad idea from the starting point, as a list is a list, and not an array... \n",
    "# but let's do it!)\n",
    "\n",
    "# I create my list called array\n",
    "array = [1, 2, 3, 4]\n",
    "\n",
    "# I need numpy so I import everything\n",
    "from numpy import *\n",
    "\n",
    "# Wait, what is array now?\n",
    "print(array)\n",
    "# no longer [1, 2, 3, 4] :("
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you've imported all of the functions from a big library like `numpy` into your namespace, you risk accidentally over-writing variabiles you've already defined, or over-writing some of `numpy`'s important functions when you define a new variable.\n",
    "\n",
    "### Multiple 'Namespaces'\n",
    "\n",
    "By importing `numpy`, rather than its contents (as we did initially), it loads all of its functions inside a *separate* `numpy` **namespace** - i.e. none of numpy's functions can interfere with variables defined in your 'top level' Python namespace, because they're all trapped *inside* `numpy`.\n",
    "\n",
    "You can make it slightly less clunky, by *renaming* `numpy` during import to make it less arduous to access its functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now all of `numpy`'s functions are available via the `np` prefix instead of `numpy`, which is more convenient to type. You can rename imports anything you like..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as giraffe\n",
    "\n",
    "giraffe.add(1, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But that's a bit silly... \n",
    "\n",
    "`np` has become the conventional name for `numpy` in Python codes... So it's good to use that. Using conventions is a good idea because it makes the code readable by anyone: people will know what `np.array` means, but `giraffe.array` is... less evident!\n",
    "\n",
    "`numpy` is specifically designed for numerical operations on arrays - i.e. what Matlab does, so let's try again..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([  4.3,  17.2,  12.9,  17.2,  12.9,   8.6, 240.8])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data = np.array([1, 4, 3, 4, 3, 2, 56])\n",
    "result = data * 4.3\n",
    "\n",
    "result\n",
    "# it works!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Important**: Always use namespaces. It keeps things organised, and prevent you accidentally breaking/overwriting things."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Useful Packages\n",
    "\n",
    "Anyone can make a package for any purpose, and there are a **lot** out there. [On 15th March there were 132,268](https://pypi.python.org/pypi). How do you find the right one for the job?\n",
    "\n",
    "1. Ask people, or [Google!](http://lmgtfy.com/?q=python+packages+for+data+science) Things like 'python package for...' and then terms that are as specific as possible for your problem. Often you won't get to the package page itself, but to some kind of guide that uses the package. Look at their `import` section to find out what they're using. It's possible you'll find more than one option.\n",
    "2. Find out more - look at the package's home page. If there isn't one, look on the [Python Package Index (PyPi)](https://pypi.python.org/pypi). Is being actively maintained (look at the [last upload date on PyPi](https://pypi.python.org/pypi/numpy/1.14.2), or is it 'dead'? If you've found more than one possible option, it's generally better to go for the one that is better documented and more recently updated.\n",
    "3. Install it! Using `conda` or `pip`, as appropriate.\n",
    "\n",
    "A few highlights for scientific applications:\n",
    "\n",
    "<table>\n",
    "    <tr>\n",
    "        <th><a href=\"https://docs.scipy.org/doc/scipy/reference/\">SciPy</a></th>\n",
    "        <td><strong>Sci</strong>entific <strong>Py</strong>thon. A diverse range of data analysis and manipulation tools, from statistical tests to data fitting and spectral analysis.</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <th><a href=\"http://pandas.pydata.org/\">Pandas</a></th>\n",
    "        <td>A mature 'data frame' library for organising and analysing data. Think spreadsheets but for Python, and with much more advanced data processing capabilities.</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <th><a href=\"http://www.numpy.org/\">NumPy</a></th>\n",
    "        <td><strong>Num</strong>eric <strong>Py</strong>thon. The workhorse for array-based numeric calculations in Python.</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <th><a href=\"http://www.sympy.org/en/index.html\">SymPy</a></th>\n",
    "        <td>Symbolic algebra! Write, manipulate and solve equations.</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <th><a href=\"https://matplotlib.org/\">Matplotlib</a></th>\n",
    "        <td>Publication-ready plots, with a few lines of code.</td>\n",
    "    </tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Iteration\n",
    "\n",
    "If you're coming from Excel (or any other spreadsheet), this is where things start getting interesting.\n",
    "\n",
    "The basics are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "5\n",
      "2\n",
      "wahoo\n"
     ]
    }
   ],
   "source": [
    "for i in [1, 5, 2, 'wahoo']:\n",
    "    print(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python iterates through each of the provided inputs, and does something to them.\n",
    "\n",
    "How might this be useful in practice? Imagine you want to perform a calculation that is *state dependent* - i.e. depends on the value the last time it was calculated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[5, 2.5, 1.25, 0.625, 0.3125, 0.15625, 0.078125, 0.0390625, 0.01953125, 0.009765625]\n"
     ]
    }
   ],
   "source": [
    "# start condition\n",
    "out = [5] # out is a list there\n",
    "\n",
    "# an base 2 exponential decay\n",
    "for i in range(1, 10):\n",
    "    out.append(out[i-1] * 0.5) # we add the result of our calculation to the list\n",
    "    \n",
    "print(out) # printing out"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also do interesting things like nested loops:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 0\n",
      "0 1\n",
      "0 2\n",
      "1 0\n",
      "1 1\n",
      "1 2\n"
     ]
    }
   ],
   "source": [
    "for i in range(2):\n",
    "    for j in range(3):\n",
    "        print(i, j)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And use conditions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "boing\n",
      "boing\n",
      "boing\n",
      "boing\n",
      "boing\n"
     ]
    }
   ],
   "source": [
    "for i in range(50233992):\n",
    "    if i == 5:\n",
    "        break  # stops the loop if condition is met\n",
    "    print('boing')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "twang\n",
      "twang\n",
      "twang\n",
      "twang\n",
      "twang\n"
     ]
    }
   ],
   "source": [
    "# a while loop is similar:\n",
    "# keeps looping until a condition is met\n",
    "i = 0\n",
    "while i < 5:\n",
    "    print('twang')\n",
    "    i += 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Iteration can make repetitive tasks easy - for example applying the same calculation to all rows of a large data table, or [testing the influence of varying a particular parameter in a model](https://nbviewer.jupyter.org/github/rses-datascience/DataSurgeries/blob/master/06_MonteCarlo/06_MonteCarloUncertainty.ipynb).\n",
    "\n",
    "## 5. Functions\n",
    "\n",
    "Often while analysing data you might find yourself copying and pasting code to either modify some aspect of it without breaking the original, or apply it to a different data set. This is where *functions* come in. A function takes inputs, does something to the inputs, and then returns something.\n",
    "\n",
    "Writing functions makes code re-usable.\n",
    "\n",
    "A trivial example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "def my_function(a, b):\n",
    "    return a + b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "17"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_function(5, 12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A more useful example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "def seawater_density(Temp, Sal):\n",
    "    A = (8.24493e-1 - 4.0899e-3 * Temp + 7.6438e-5 * Temp**2 - 8.2467e-7 * Temp**3 + 5.3875e-9 * Temp**4)\n",
    "    B = (-5.72466e-3 + 1.0227e-4 * Temp - 1.6546e-6 * Temp**2)\n",
    "    C = 4.8314e-4\n",
    "    p0 = (999.842594 + 6.793952e-2 * Temp - 9.095290e-3 * Temp**2 + 1.001685e-4 * Temp**3 - 1.120083e-6 * Temp**4 + 6.536336e-9 * Temp**5)\n",
    "    \n",
    "    return p0 + A * Sal + B * Sal**(3/2) + C * Sal"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1022.7681219162893"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seawater_density(25, 35)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is short-term useful, but if you were to return to it in 6 months, there's some important information missing:\n",
    "- Is temperature in C or K?\n",
    "- Where do all the coefficients come from?!\n",
    "\n",
    "Making it use-able: [good practice](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "def seawater_density(Temp=25.0, Sal=35.0):\n",
    "    \"\"\"\n",
    "    Calculate seawater density from Temperature and Salinity.\n",
    "    \n",
    "    Using the formulation of Millero and Poisson (1981,\n",
    "    doi:10.1016/0198-0149(81)90122-9)\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    Temp : float or numpy.ndarray\n",
    "        Temperature in Celcius\n",
    "    Sal : float or numpy.ndarray\n",
    "        Salinity\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    Density of seawater in kg m-3 : float or numpy.ndarray\n",
    "    \"\"\"\n",
    "    A = (8.24493e-1 - \n",
    "         4.0899e-3 * Temp + \n",
    "         7.6438e-5 * Temp**2 - \n",
    "         8.2467e-7 * Temp**3 + \n",
    "         5.3875e-9 * Temp**4)\n",
    "    B = (-5.72466e-3 + \n",
    "         1.0227e-4 * Temp - \n",
    "         1.6546e-6 * Temp**2)\n",
    "    C = 4.8314e-4\n",
    "    p0 = (999.842594 + \n",
    "          6.793952e-2 * Temp - \n",
    "          9.095290e-3 * Temp**2 + \n",
    "          1.001685e-4 * Temp**3 - \n",
    "          1.120083e-6 * Temp**4 + \n",
    "          6.536336e-9 * Temp**5)\n",
    "    \n",
    "    return p0 + A * Sal + B * Sal**(3/2) + C * Sal"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1022.7681219162893"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seawater_density()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now with the nice doc, if in 10 months you don't remember how to use seawater_density(), you can call for help!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function seawater_density in module __main__:\n",
      "\n",
      "seawater_density(Temp=25.0, Sal=35.0)\n",
      "    Calculate seawater density from Temperature and Salinity.\n",
      "    \n",
      "    Using the formulation of Millero and Poisson (1981,\n",
      "    doi:10.1016/0198-0149(81)90122-9)\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    Temp : float or numpy.ndarray\n",
      "        Temperature in Celcius\n",
      "    Sal : float or numpy.ndarray\n",
      "        Salinity\n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    Density of seawater in kg m-3 : float or numpy.ndarray\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(seawater_density)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More generally:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "def my_function(a):\n",
    "    \"\"\"\n",
    "    One-line description of function.\n",
    "    \n",
    "    This whole thing at the start is called a 'docstring'. There's a \n",
    "    standard format to make them immediately readable. No everyeone adheres\n",
    "    to it, but they should.\n",
    "    \n",
    "    The bit between the one line summary and the 'Parameters' (below) can\n",
    "    contain a bit more detail about what it does (if necessary).\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    a : type that a should be for the function to work properly\n",
    "        Information about what this should be.\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    Description of the output : type of the output\n",
    "    \n",
    "    Examples\n",
    "    --------\n",
    "    >>> my_function(5)\n",
    "    5\n",
    "    \"\"\"\n",
    "    result = a  # your code here\n",
    "    return result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function my_function in module __main__:\n",
      "\n",
      "my_function(a)\n",
      "    One-line description of function.\n",
      "    \n",
      "    This whole thing at the start is called a 'docstring'. There's a \n",
      "    standard format to make them immediately readable. No everyeone adheres\n",
      "    to it, but they should.\n",
      "    \n",
      "    The bit between the one line summary and the 'Parameters' (below) can\n",
      "    contain a bit more detail about what it does (if necessary).\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    a : type that a should be for the function to work properly\n",
      "        Information about what this should be.\n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    Description of the output : type of the output\n",
      "    \n",
      "    Examples\n",
      "    --------\n",
      "    >>> my_function(5)\n",
      "    5\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(my_function)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `help` function will work on any function with documentation."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}