PythonClassPrimer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center><h1>A Primer on Python Classes</h1>\n",
    "<br>\n",
    "<center><b>Collin Capano</b></center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `inference` module in PyCBC makes heavy use of Python classes in order to manage different samplers and models with a common API. In this tutorial we provide an overview of:\n",
    " * Object oriented programming in Python, including what a `class` is and how to define it.\n",
    " * Class inheritance.\n",
    " * Abstract base classes.\n",
    " * How these are used in PyCBC Inference.\n",
    " \n",
    "In addition, the Appendix provides some more background on common decorators and different ways to define and call functions.\n",
    "\n",
    "### Table of Contents\n",
    "\n",
    " * [I. Brief review of functions](#I.-Brief-review-of-functions)\n",
    " * [II. Namespaces and scope](#II.-Namespaces-and-scope)\n",
    " * [III. Classes](#III.-Classes)\n",
    "   - [The need for classes](#The-need-for-classes)\n",
    "   - [Defining classes](#Defining-classes)\n",
    "   - [What's the deal with `self`?](#What's-the-deal-with-self?)\n",
    "   - [The `__init__` method](#The-__init__-method)\n",
    " * [IV. Class inheritance](#IV.-Class-inheritance)\n",
    "   - [Using `super`](#Using-super)\n",
    "   - [Multiple inheritance](#Multiple-inheritance)\n",
    " * [V. Abstract Base Classes](#V.-Abstract-Base-Classes)\n",
    " * [VI. Usage in `pycbc.inference`](#VI.-Usage-in-pycbc.inference)\n",
    " * [Further reading](#Further-reading)\n",
    " * [Appendix](#Appendix)\n",
    "   - [A. Decorators](#A.-Decorators)\n",
    "   - [B. More on functions](#B.-More-on-functions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Prerequisites"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import print_function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## I. Brief review of functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we start up a Python environment, we have all of Python's built-in functions and operators available to us, such as `import`, `for`, `if`, etc. With the `=` operator we can define variables, which we can then modify using other operators, such as `+`, `-`, etc. For example, let's define a float called `a` and set it to some initial value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = 1.234"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now carry out various operations with `a`, e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Add one to a: 2.234\n",
      "Square a: 1.522756\n"
     ]
    }
   ],
   "source": [
    "print('Add one to a:', a + 1)\n",
    "print('Square a:', a**2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Say we wanted to find the [floor](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions) of `a`. We could do that with the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The floor of a is:\n",
      "1\n"
     ]
    }
   ],
   "source": [
    "print('The floor of a is:')\n",
    "if a > 0:\n",
    "    print(int(a))\n",
    "else:\n",
    "    print(int(a-1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now introduce two other variables, `b` and `c`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "b = -3.14\n",
    "c = 7.2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Say we also want the floor of these. To do that, we could copy and paste the code above twice, once for `b` and once for `c`. However, repeating code is generally a bad idea. First, it makes your code long and tedious to read. Second, what if you want to modify it later, or you find there's a bug? Now you'd have to go and fix every repetition of it, which can easily lead to more bugs. This rule of thumb is so important, it's worth a call out:\n",
    "<br>\n",
    "<br>\n",
    "<center><div class=\"alert alert-block alert-info\">\n",
    "    <b><big>Do not repeat code.</big></b>\n",
    "    <br>\n",
    "    <small>(Unless you really need to.)</small>\n",
    "</div></center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead, we can define a function, and put our code in there:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def floor(x):\n",
    "    if x > 0:\n",
    "        x = int(x)\n",
    "    else:\n",
    "        x = int(x-1)\n",
    "    return x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now easily apply the same function to all of our variables, without repeating several lines of code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "floor(a): 1\n",
      "floor(b): -4\n",
      "floor(c): 7\n"
     ]
    }
   ],
   "source": [
    "print(\"floor(a):\", floor(a))\n",
    "print(\"floor(b):\", floor(b))\n",
    "print(\"floor(c):\", floor(c))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more on functions, including various ways to define them and call them, see the [Appendix](#B.-More-on-functions)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## II. Namespaces and scope"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before moving on to classes, it is instructive to understand how mappings between objects and values are handled in python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the definition of `floor` we created an argument called `x`, which we modified within the function. No variable `x` was defined prior to the function definition. And even though we have called `floor` three times, no variable `x` exists in the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'x' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-8-fc17d851ef81>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mx\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m: name 'x' is not defined"
     ]
    }
   ],
   "source": [
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To understand what's going on here, let's establish a few definitions. When we set `a = 1.234`, we created a *mapping* from the object called `a` to the value `1.234`. We created similar mappings for `b` and `c`. Likewise, when we defined the function `floor`, we created a mapping from the object called `floor` to the block of code defined above. A collection of mappings is called a *namespace*. Currently, the namespace of our notebook/module (called the module's `global` namespace) is `a`, `b`, `c`, and `floor`. Our notebook also has access to Python's `builtins` namespace. The *[scope](https://en.wikipedia.org/wiki/Scope_(computer_science))* of the notebook --- i.e., the collection of namespaces that are searched to resolve objects --- is the notebook's namespace plus the `builtins`.\n",
    "\n",
    "When we define a function, we essentially define a new, *local* namespace within that function. The function's local namespace includes all of the arguments that the function takes, plus any mappings that are created within that function. So, when we called `floor(a)`, a namespace was created in which a local object `x` was mapped to the value of `a`, `1.234`. The code within `floor` was then evaluated. Since `1.234` is greater than 0, this line was executed:\n",
    "```\n",
    "    x = int(x)\n",
    "```\n",
    "At this point the local `x` is remapped to the integer `1`. The line `return x` then passes the value that `x` is mapped to back to the notebook. At this point, *the function's namespace is deleted*, meaning that the object `x` ceases to exist. The same applies to any mappings that are defined within the function. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "def quadsum(a, b):\n",
    "    x = a**2\n",
    "    y = b**2\n",
    "    return (x + y)**(0.5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.85490929292\n"
     ]
    }
   ],
   "source": [
    "print(quadsum(b, c))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'y' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-11-d9183e048de3>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0my\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m: name 'y' is not defined"
     ]
    }
   ],
   "source": [
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want the result of `quadsum` to exist in the notebook's namespace, we need to assign an object to it; e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.85490929292\n"
     ]
    }
   ],
   "source": [
    "d = quadsum(b, c)\n",
    "print(d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Likewise, if we want other objects that were created within a function to persist, we need to pass those objects using `return`. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "def prodquot(a, b):\n",
    "    prod = a*b\n",
    "    quot = a / b\n",
    "    return prod, quot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-22.608 -0.436111111111\n"
     ]
    }
   ],
   "source": [
    "btc, bdc = prodquot(b, c)\n",
    "print(btc, bdc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In both `quadsum` and `prodquot`, the arguments of the function were called `a` and `b`. But we already had an `a` and `b` defined in the notebook's namespace! This was not problematic because whenever Python is evaluating a block of code, *local mappings take precedence*. So, when we called `prodquot(b, c)`, a local namespace was created in which `a` was mapped to the notebook's `b`, and a local `b` was mapped to the notebook's `c`.\n",
    "\n",
    "If a function uses an object that is not defined in the local namespace, then Python will step out to the next local namespace to look for it. This process will repeat until it gets to the module's `global` namespace, followed by the `builtins`; if nothing can be found there, a `NameError` is raised.\n",
    "\n",
    "For example, when the code inside `prodquot(b, c)` is being evaluated, 3 namespaces exist. In order of object resolution, they are:\n",
    "  1. `prodquot` namespace: `{a: -3.14, b: 7.2}`\n",
    "  2. `global` namespace: `{a: 1.234, b: -3.14, c: 7.2, prodquot: <prodquot code>, ... }`\n",
    "  3. `builtin` namespace: `{*: <multiply>, /: <divide>, ... }`\n",
    "\n",
    "As we will see below, understanding nested namespaces is key to understanding how classes work."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*****\n",
    "<center><div class=\"alert alert-block alert-danger\"><b>Warning</b></div></center>\n",
    "\n",
    "*****\n",
    "\n",
    "Due to the way mappings are resolved, it is possible to define a function that uses a variable from outside of its local namespace. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "def dontdothis(b):\n",
    "    return a + b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8.434000000000001"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dontdothis(c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, because `a` was not listed in `dontdothis`'s arguments (and was not defined anywhere in the function), Python ends up using the `a` defined in the notebook's `global` namespace. We therefore end up with `-3.14 + 7.2`.\n",
    "\n",
    "If it wasn't clear from the function name, **don't do this.** The danger is the output of the function can change depending on where it is called in the code even if the arguments are the same. For example, if at some later point we set `a` to a different value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = 10.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then calling `dontdothis` with the same argument will yield a different result:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "17.2"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dontdothis(c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can lead to unexpected bugs that are hard to track down. Thus:\n",
    "<br>\n",
    "<br>\n",
    "<center><div class=\"alert alert-block alert-info\">\n",
    "    <b><big>You should include all variables needed by a function in its list of arguments.</big></b>\n",
    "    <br>\n",
    "</div></center>\n",
    "<br>\n",
    "There are some cases where this rule may need to be broken, but these are rare, and should be avoided if possible."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## III. Classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The need for classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is possible to write code in Python that only uses functions (this is known as [functional programming](https://en.wikipedia.org/wiki/Functional_programming)). However, in certain cases this can lead to unwieldy and difficult to manage code.\n",
    "\n",
    "As a simple example (borrowed from [here](https://stackoverflow.com/a/33072722)), say we wanted some code to keep track of a student's progress in a class. We could do this using a dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "# create student Jane\n",
    "jane = {}\n",
    "jane['name'] = 'Jane'\n",
    "jane['homework_grades'] = [87., 90., 82., 75., 97.]\n",
    "jane['exam_grades'] = [88., 80., 94.]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You also give your students the opportunity to earn extra credit by writing a report. Jane, the hardworking student that she is, takes advantage of this and writes an excellent report. You add that to her grades:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "jane['extra_credit'] = 99."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You now write a function to calculate your students' GPA:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "def gpa(student):\n",
    "    homeworkavg = float(sum(student['homework_grades']))/len(student['homework_grades'])\n",
    "    examavg = float(sum(student['exam_grades']))/len(student['exam_grades'])\n",
    "    totalavg = (homeworkavg + examavg + student['extra_credit'])/3.\n",
    "    return 4.0 * totalavg / 100."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... which you use on to get Jane's score:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.63377777778\n"
     ]
    }
   ],
   "source": [
    "print(gpa(jane))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you want to do the same for your other student, Susie:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "susie = {}\n",
    "susie['name'] = 'Susie'\n",
    "susie['homework_grades'] = [80., 73., 77., 50., 0.]\n",
    "susie['exam_grades'] = [70., 63., 50.]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "ename": "KeyError",
     "evalue": "'extra_credit'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mKeyError\u001b[0m                                  Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-24-5e21b203c084>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mgpa\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msusie\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m<ipython-input-21-368b4bb03295>\u001b[0m in \u001b[0;36mgpa\u001b[0;34m(student)\u001b[0m\n\u001b[1;32m      2\u001b[0m     \u001b[0mhomeworkavg\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mfloat\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msum\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mstudent\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'homework_grades'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m/\u001b[0m\u001b[0mlen\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mstudent\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'homework_grades'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      3\u001b[0m     \u001b[0mexamavg\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mfloat\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msum\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mstudent\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'exam_grades'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m/\u001b[0m\u001b[0mlen\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mstudent\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'exam_grades'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 4\u001b[0;31m     \u001b[0mtotalavg\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m(\u001b[0m\u001b[0mhomeworkavg\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mexamavg\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mstudent\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'extra_credit'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m/\u001b[0m\u001b[0;36m3.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      5\u001b[0m     \u001b[0;32mreturn\u001b[0m \u001b[0;36m4.0\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0mtotalavg\u001b[0m \u001b[0;34m/\u001b[0m \u001b[0;36m100.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mKeyError\u001b[0m: 'extra_credit'"
     ]
    }
   ],
   "source": [
    "print(gpa(susie))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Oh! Susie - a bit of a slacker - didn't do the extra credit (even though she needed it more). As a result, you forgot to add an extra credit entry for her, leading to a problem with your function. You can fix this by going back and changing your `gpa` function, or by adding the missing data to Susie's dictionary. However, this highlights a disadvantage to this type of programming: the object (in this case a student, represented by a dictionary) *is not well defined.* This can lead to pitfalls when trying to write functions that will manipulate your objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python classes are a way to bundle data and functions together into logically coherent objects (this is known as [object oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming)). Like functions, they create their own local namespaces within your program within which you can manipulate objects. Unlike functions, these namespaces persist even when you are not interacting with the class.\n",
    "\n",
    "To illustrate how classes work, let's revisit the above problem. We want an object that represents a student, which has a number of *attributes*, such as `name`, `homework_grades`, etc. To do that, we define a `class`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Student(object):\n",
    "    \"\"\"Stores information about students.\"\"\"\n",
    "    \n",
    "    def __init__(self, name):\n",
    "        self.name = name\n",
    "        self.homework_grades = []\n",
    "        self.exam_grades = []\n",
    "        self.extra_credit = None\n",
    "\n",
    "    def homework_avg(self):\n",
    "        \"\"\"Average homework grade.\"\"\"\n",
    "        return sum(self.homework_grades)/float(len(self.homework_grades))\n",
    "    \n",
    "    def exam_avg(self):\n",
    "        \"\"\"Average exam grade.\"\"\"\n",
    "        return sum(self.exam_grades)/float(len(self.exam_grades))\n",
    "    \n",
    "    def gpa(self):\n",
    "        \"\"\"GPA (on a 4.0 scale).\"\"\"\n",
    "        if self.extra_credit is not None:\n",
    "            totalavg = (self.homework_avg() + self.exam_avg() + self.extra_credit) / 3.\n",
    "        else:\n",
    "            totalavg = (self.homework_avg() + self.exam_avg())/2.\n",
    "        return 4.0 * totalavg / 100."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we create `Student` *instances*, one for Jane, and one for Susie:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "jane = Student('Jane')\n",
    "jane.homework_grades = [87., 90., 82., 75., 97.]\n",
    "jane.exam_grades = [88., 80., 94.]\n",
    "jane.extra_credit = 99.\n",
    "\n",
    "susie = Student('Susie')\n",
    "susie.homework_grades = [80., 73., 77., 50., 0.]\n",
    "susie.exam_grades = [70., 63., 50.]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now get their GPAs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.6337777777777776"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "jane.gpa()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2.34"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "susie.gpa()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What did we do here? First, we defined the class `Student`, to which we added methods `__init__`, `homework_avg`, `exam_avg`, and `gpa`. No code was executed until we created an *instance* of `Student` by calling:\n",
    "```\n",
    "jane = Student('Jane')\n",
    "```\n",
    "At this point, a local namespace called `jane` was created, which contained the mappings:\n",
    "```\n",
    "{name: 'Jane', homework_grades: [], exam_grades: [], extra_credit: None,\n",
    " homework_avg: <Student.homework_avg code>, exam_avg: <Student.exam_avg code>,\n",
    " gpa: <Student.gpa code>}\n",
    "```\n",
    "This is similar to what happens when a function is called. However, unlike a function, the namespace persisted after this line, allowing us to access its attributes with `.`; e.g., `jane.homework_grades`. Once we populated the relevant attributes, we were then able to call `gpa` to get Jane's GPA."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What's the deal with `self`?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions that are defined in a class are called *methods*. Their purpose is to act on a class instance's attributes. In our `Student` example there were four methods: `__init__`, `homework_avg`, `exam_avg`, and `gpa`. All of these took `self` as their first argument. Why?\n",
    "\n",
    "In order for a method to act on an instance's attributes, it must have some way to reference the class *instance*. For example, when we call `jane.gpa()`, we want the function `Student.gpa` to act on *Jane*'s grades. This is the purpose of `self`: it represents the class instance, so that we can access attributes of the instance within the function definition.\n",
    "\n",
    "Note that when we called `jane.gpa()` we did not need to provide any arguments. This is because **Python automatically adds the class instance as the first argument when a method is called.** Thus:\n",
    "<br>\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b><big>1. All class method definitions must have <code>self</code> as their first argument.</big></b> (With two exceptions; see Appendix A, below.)\n",
    "    <br>\n",
    "    <br>\n",
    "    <b><big>2. When calling a method of a class instance, you do not pass the instance in the function arguments.</big></b>\n",
    "    </div>\n",
    " \n",
    "So..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Correct:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.6337777777777776"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "jane.gpa()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Not correct:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "gpa() takes exactly 1 argument (2 given)",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-30-58818409d224>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mjane\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mgpa\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mjane\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m: gpa() takes exactly 1 argument (2 given)"
     ]
    }
   ],
   "source": [
    "jane.gpa(jane)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although you can do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.6337777777777776"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Student.gpa(jane)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Note:* The name `self` in a method definition isn't special. What matters is the argument order: the *first* argument of the class method is assumed to be the class instance, regardless of what it is named. Using `self` for this is just a convention."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The `__init__` method"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the most part, you can add any number of methods with various names to a class. However, there are a few special method names that Python recognizes (all of which begin and end with `__`). The most common of these is the  `__init__` method.\n",
    "\n",
    "The `__init__` method is called while the class is initialized. The arguments of `__init__` determine what arguments need to be passed to the class when it is initialized. In our example, `Student.__init__` was defined as needing `name` (in addition to `self`, which is always required). As a result, when we initialized the class we had to pass in a string representing the student's name.\n",
    "\n",
    "The `__init__` method is used to add attributes to a class and set their initial values. It is not necessary to have an `__init__` method, however. Nor must attributes be assigned in `__init__`. Attributes may be added to a class instance *after* the class is initialized. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10.0\n"
     ]
    }
   ],
   "source": [
    "class Foo(object):\n",
    "    pass\n",
    "\n",
    "foo = Foo()\n",
    "foo.bar = 10.\n",
    "print(foo.bar)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The catch is that any attribute added to an instance *only exists for that instance*. This means that if we create another instance of `Foo`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "foo2 = Foo()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It will *not* have a `bar` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "ename": "AttributeError",
     "evalue": "'Foo' object has no attribute 'bar'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-34-cb7e4759801a>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mfoo2\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mbar\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m: 'Foo' object has no attribute 'bar'"
     ]
    }
   ],
   "source": [
    "print(foo2.bar)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The benefit of `__init__` is that it ensures that all instances of a class have at least the attributes that are set within it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## IV. Class inheritance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A major feature of classes is that they can *inherit* from other classes, allowing us to reuse code to build more complex objects. To do this, you pass the class (or classes) that you want to inherit from in the class definition.\n",
    "\n",
    "For example, say we are teaching a course that includes a lab component, in addition to homework and exams. Now we want to able to store grades for students' labs, and incorporate that into their GPA. Rather then recreating a `Student` class from scratch, let's inherit from our current `Student` class, adding in the new attributes we need:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "class LabStudent(Student):\n",
    "    \"\"\"A student with lab grades.\"\"\"\n",
    "    \n",
    "    def __init__(self, name):\n",
    "        super(LabStudent, self).__init__(name)\n",
    "        self.lab_grades = []\n",
    "\n",
    "    def lab_avg(self):\n",
    "        return sum(self.lab_grades)/float(len(self.lab_grades))\n",
    "    \n",
    "    def gpa(self):\n",
    "        if self.extra_credit is not None:\n",
    "            totalavg = (self.homework_avg() + self.exam_avg() + self.lab_avg()\n",
    "                        + self.extra_credit)/4.\n",
    "        else:\n",
    "            totalavg = (self.homework_avg() + self.exam_avg() + self.lab_avg())/3.\n",
    "        return 4.0 * totalavg / 100."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.4433333333333334"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# now lets create a lab student, and enter their grades\n",
    "kelly = LabStudent('Kelly')\n",
    "kelly.homework_grades = [92., 88., 95., 96.]\n",
    "kelly.exam_grades = [94., 97.]\n",
    "kelly.lab_grades = [65., 70., 72., 73.]  # Kelly is clearly destined to be a theorist\n",
    "kelly.gpa()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that in the definition of `LabStudent`, we did not include definitions for `homework_avg` or `exam_avg`. Even so, they are attributes of `LabStudent`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "92.75\n",
      "95.5\n"
     ]
    }
   ],
   "source": [
    "print(kelly.homework_avg())\n",
    "print(kelly.exam_avg())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is because we automatically inherited them from `Student`.\n",
    "\n",
    "We did, however, redefine `__init__` and `gpa`. Whenever you define a method or attribute with the same name as something in the parent class, that new method/attribute takes precedence. This is because if a class inherits from a parent, its local namespace will be nested inside of its parent's namespace (which is nested inside its parent's, ..., which is nested in the `global` namespace, which is nested in the `builtins` namespace).\n",
    "\n",
    "Recall that when resolving a method or attribute, Python will begin by checking the inner-most namespace for a name match. If none is found, it will step outward until it finds a name match. So, when we call `kelly.gpa()`, we end up executing the `gpa` function defined in `LabStudent` (with `kelly` passed as `self`). Within that function, a call to `self.homework_avg()` is made. Since `homework_avg` is not defined in `LabStudent`'s namespace, Python stepped up to the namespace of the parent class, `Student`. There it found a `homework_avg`, so it executed that function, passing it `self` (which maps to `kelly`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using `super`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We needed to override the entirety of `Student.gpa` so as to add in the lab grades. But in the case of `__init__`, we only needed to *add* functionality to `Student.__init__` so as to create an attribute for `lab_grades`. We still wanted to run the same code that was in `Student.__init__`. To do this, we could of copied the code in `Student.__init__`, but that would break our rule about not repeating code. It would be best if we could call the parent class's method. But how do we do that, if the method name has been overridden in the child class?\n",
    "\n",
    "The `super` function provides a way of accessing and calling methods of the parent class. It takes two arguments, the child class who's parent you want to access, and the instance of the child class to act on. So,\n",
    "```\n",
    "super(LabStudent, self).__init__(name)\n",
    "```\n",
    "is equivalent to:\n",
    "```\n",
    "Student.__init__(self, name)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multiple inheritance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is possible to inherit from multiple classes. This is useful if you want to *compose* a class out of smaller, simpler classes. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Foo(object):\n",
    "    def foo(self):\n",
    "        return \"foo\"\n",
    "\n",
    "class Bar(object):\n",
    "    def bar(self):\n",
    "        return \"bar\"\n",
    "\n",
    "class FooBar(Foo, Bar):\n",
    "    def foobar(self):\n",
    "        return self.foo() + self.bar()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "foo bar foobar\n"
     ]
    }
   ],
   "source": [
    "foobar = FooBar()\n",
    "print(foobar.foo(), foobar.bar(), foobar.foobar())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But what happens if both parent classes define the same function? Which one takes precedence? Let's add a common function, `cat` to both `Foo` and `Bar` and see what happens:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Foo(object):\n",
    "    def foo(self):\n",
    "        return \"foo\"\n",
    "    \n",
    "    def cat(self):\n",
    "        return \"I'm Foo's cat.\"\n",
    "\n",
    "class Bar(object):\n",
    "    def bar(self):\n",
    "        return \"bar\"\n",
    "    \n",
    "    def cat(self):\n",
    "        return \"I'm Bar's cat.\"\n",
    "\n",
    "class FooBar(Foo, Bar):\n",
    "    def foobar(self):\n",
    "        return self.foo() + self.bar()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "I'm Foo's cat.\n"
     ]
    }
   ],
   "source": [
    "foobar = FooBar()\n",
    "print(foobar.cat())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So `Foo`'s `cat` took precedence over `Bar`'s. What happens if we flip the order of the parent classes?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [],
   "source": [
    "class BarFoo(Bar, Foo):\n",
    "    def foobar(self):\n",
    "        return self.foo() + self.bar()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "I'm Bar's cat.\n"
     ]
    }
   ],
   "source": [
    "barfoo = BarFoo()\n",
    "print(barfoo.cat())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now `Bar`'s cat has taken precedence over `Foo`'s. We see that:\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b><big>The <i>method resolution order</i> of a class works left to right in the list of its parent classes.</big></b>\n",
    "    </div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Building children classes from multiple, simple parent classes can be very useful for reusing core functionality over multiple classes. This is done extensively in the [pycbc.inference.sampler](https://pycbc.org/pycbc/latest/html/pycbc.inference.sampler.html) package, for example.\n",
    "\n",
    "However, this can quickly lead to confusing code in which it is difficult to figure out what happens where. This is particularly true if you inherit from classes which themselves have multiple inheritance, and have common method names as the other parents. (For nitty-gritty details on how method resolution order works in these more complicated cases, see [this blog post](https://medium.com/technology-nineleaps/python-method-resolution-order-4fd41d2fcc).)\n",
    "\n",
    "It can also get to be very confusing if you make classes that have many generations of parents, i.e., you have something like:\n",
    "```\n",
    "class A(object):\n",
    "    <...>\n",
    "\n",
    "class B(A):\n",
    "    <...>\n",
    "\n",
    "class C(B):\n",
    "    <...>\n",
    "\n",
    "etc.\n",
    "```\n",
    "(I've certainly been guilty of this.)\n",
    "\n",
    "**When using multiple inheritance, it's best to only inherit from parent classes that do not have multiple parents, and do not have conflicting method names. In general, even if you only inherit from a single parent, try to limit the number of generations of inheritance.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## V. Abstract Base Classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In PyCBC Inference we have support for several different samplers, such as `emcee`, `emcee_pt`, etc. Each of these samplers has different properties that need to be set in order for it to function correctly. For example, `emcee` needs to know how many walkers to use, whereas `emcee_pt` needs to have the number of walkers *and* the number of temperatures set. For this reason, we define a different class for each sampler; e.g., for `emcee` we use the [EmceeEnsembleSampler](https://pycbc.org/pycbc/latest/html/pycbc.inference.sampler.html#pycbc.inference.sampler.emcee.EmceeEnsembleSampler) class while for `emcee_pt` we use the [EmceePTSampler](https://pycbc.org/pycbc/latest/html/pycbc.inference.sampler.html#pycbc.inference.sampler.emcee_pt.EmceePTSampler) class.\n",
    "\n",
    "The samplers do share some common properties though. Given a *model* that has a prior and a likelihood function, we expect all samplers to run for some time, producing posterior samples at the end. We might expect that the API for these common methods -- what the name of the method is and what arguments it takes -- should be the same for all of these classes. Then we can write a program like `pycbc_inference` that, regardless of the sampler that the user selects, can simply do `sampler.run()`.\n",
    "\n",
    "It makes sense that all of the sampler classes should inherit from a common parent class. However, although all of the sampler's have a `run` method, what code those methods need to execute may differ between samplers. What we need is a parent class that defines common methods and arguments, but not have those methods actually do anything.\n",
    "\n",
    "*Abstract base classes* are classes that do just this. They are used to define *abstract* methods. Abstract methods don't do anything, and in fact must be overridden by children classes. Their purpose is to establish a common API for all children classes.\n",
    "\n",
    "A simple example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABCMeta, abstractmethod"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [],
   "source": [
    "class BaseCar(object):\n",
    "    \"\"\"Abstract base class representing a car.\"\"\"\n",
    "    __metaclass__ = ABCMeta\n",
    "    \n",
    "    @abstractmethod\n",
    "    def accelerate(self, pedal_position):\n",
    "        \"\"\"Accelerates the car.\n",
    "        \n",
    "        The amount of acceleration depends on the pedal position.\n",
    "        \n",
    "        Parameters\n",
    "        ----------\n",
    "        pedal_position : float\n",
    "            A float between 0 and 100 indicating how far the\n",
    "            gas pedal is depressed (0 = not at all,\n",
    "            100 = all the way to the floor).\n",
    "        \"\"\"\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we've created a class to represent cars. All cars must have a gas pedal that, when depressed, accelerates the car. We've therefore defined an `accelerate` method that depends on how much the pedal is pressed. But what happens under the hood (literally) when the pedal is pressed depends on the type of engine the car has. So we've made `accelerate` an abstract method by sticking the `@abstractmethod` *decorator* above it. (For more on decorators, see the [Appendix](#A.-Decorators).) The method doesn't actually do anything. In fact, if we try to instantiate `BaseCar`, we'll get an error:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "Can't instantiate abstract class BaseCar with abstract methods accelerate",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-46-e5657ef7c63f>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mBaseCar\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m: Can't instantiate abstract class BaseCar with abstract methods accelerate"
     ]
    }
   ],
   "source": [
    "BaseCar()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`BaseCar`'s only purpose is to be inherited by other classes, which must define their own `accelerate`. Here are a couple of examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [],
   "source": [
    "class GasCar(BaseCar):\n",
    "    \"\"\"A car that has a gas engine.\"\"\"\n",
    "    \n",
    "    def accelerate(self, pedal_position):\n",
    "        print(\"Increasing fuel flow to injectors by {} percent.\"\n",
    "              .format(pedal_position))\n",
    "\n",
    "        \n",
    "class ElectricCar(BaseCar):\n",
    "    \"\"\"A car that has an electric engine.\"\"\"\n",
    "    \n",
    "    def accelerate(self, pedal_position):\n",
    "        print(\"Increasing power drain from batteries \"\n",
    "              \"by {} percent.\".format(pedal_position))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can instantiate these classes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas_car = GasCar()\n",
    "tesla = ElectricCar()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now call their `accelerate` methods using the same syntax even though they do different things:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Increasing fuel flow to injectors by 50 percent.\n"
     ]
    }
   ],
   "source": [
    "gas_car.accelerate(50)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Increasing power drain from batteries by 50 percent.\n"
     ]
    }
   ],
   "source": [
    "tesla.accelerate(50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The end result - the car goes faster - would be the same for both."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## VI. Usage in `pycbc.inference`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This pattern of defining a base class for a common set of classes is used throughout the `pycbc.inference` package:\n",
    " * There is a unique class for each sampler supported by `pycbc_inference`. All of these sampler classes must inherit from the [BaseSampler](https://pycbc.org/pycbc/latest/html/pycbc.inference.sampler.html#pycbc.inference.sampler.base.BaseSampler) class. This allows the executable `pycbc_inference` to interact with all of these samplers using a common interface.\n",
    " * All samplers have an `io` attribute. This is another type of class that handles reading and writing results to HDF files. There is a unique `io` class for each sampler, all of which inherit from their own abstract base class, [BaseInferenceFile](https://pycbc.org/pycbc/latest/html/pycbc.inference.io.html#pycbc.inference.io.base_hdf.BaseInferenceFile).\n",
    " * Different types of models are supported, with each model having its own class. Again, all of these classes must inherit from the same abstract base class, in this case [BaseModel](https://pycbc.org/pycbc/latest/html/pycbc.inference.models.html#pycbc.inference.models.base.BaseModel).\n",
    " \n",
    "The PyCBC Inference documentation pages have more details on how the [sampler](https://pycbc.org/pycbc/latest/html/inference/sampler_api.html) and [io](https://pycbc.org/pycbc/latest/html/inference/io.html) modules are organized. For more information about the `model` classes, see Alex Nitz's tutorials."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further reading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. Python's tutorial on classes, which includes more details on namespaces and scope: https://docs.python.org/3.7/tutorial/classes.html\n",
    "2. Another tutorial on object oriented programming in Python: https://jeffknupp.com/blog/2014/06/18/improve-your-python-python-classes-and-object-oriented-programming/\n",
    "3. More on method resolution order, from the former \"Benevolent Dictator for Life\" [Guido van Rossum](https://en.wikipedia.org/wiki/Guido_van_Rossum): http://python-history.blogspot.com/2010/06/method-resolution-order.html\n",
    "3. The following are doc pages for the `abc` module, which includes more details on abstract base classes. Unfortunately, the syntax has changed a bit between Python 2.7 and 3, so I've included both here. Currently, PyCBC usese the 2.7 syntax, but we will be switching to 3 in the future.\n",
    "   * [abc in Python 2.7](https://docs.python.org/2.7/library/abc.html)\n",
    "   * [abc in Python 3.7](https://docs.python.org/3.7/library/abc.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Appendix"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A. Decorators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Consider the following modification of our `Student` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Student(object):\n",
    "    \"\"\"Stores information about students.\"\"\"\n",
    "    \n",
    "    def __init__(self, name):\n",
    "        self.name = name\n",
    "        self.homework_grades = []\n",
    "        self.exam_grades = []\n",
    "        self.extra_credit = None\n",
    "\n",
    "    @classmethod\n",
    "    def from_dict(cls, sdict):\n",
    "        \"\"\"Initialize a Student using the given dictionary.\"\"\"\n",
    "        student = cls(sdict['name'])\n",
    "        if 'homework_grades' in sdict:\n",
    "            student.homework_grades = sdict['homework_grades']\n",
    "        if 'exam_grades' in sdict:\n",
    "            student.exam_grades = sdict['exam_grades']\n",
    "        if 'extra_credit' in sdict:\n",
    "            student.extra_credit = sdict['extra_credit']\n",
    "        return student\n",
    "    \n",
    "    @staticmethod\n",
    "    def avg(values):\n",
    "        return sum(values)/float(len(values))\n",
    "    \n",
    "    @property\n",
    "    def homework_avg(self):\n",
    "        \"\"\"Average homework grade.\"\"\"\n",
    "        return self.avg(self.homework_grades)\n",
    "    \n",
    "    @property\n",
    "    def exam_avg(self):\n",
    "        \"\"\"Average exam grade.\"\"\"\n",
    "        return self.avg(self.exam_grades)\n",
    "    \n",
    "    @property\n",
    "    def gpa(self):\n",
    "        \"\"\"GPA (on a 4.0 scale).\"\"\"\n",
    "        scores = [self.homework_avg, self.exam_avg]\n",
    "        if self.extra_credit is not None:\n",
    "            scores.append(self.extra_credit)\n",
    "        return 4.0 * self.avg(scores)/100."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What are all of those things with `@` before the function definitions? And why don't the `from_dict` and `avg` methods not have `self` as their first arguments?!?\n",
    "\n",
    "The names beginning with `@`, such as `@classmethod`, are called *decorators*. Essentially, decorators are wrappers around functions that modify the behavior of that function. They can be used on any Python function, but they are most often seen in classes.\n",
    "\n",
    "Using and creating decorators is a large topic itself, the details of which we won't get into here (if you're interested, see [here](https://realpython.com/primer-on-python-decorators/) for an excellent tutorial). However, there are three predefined decorators in the Python `builtins` that often come up in class definitions (and which we make heavy use of in the `pycbc.inference` package) that I want highlight here: `@classmethod`, `@staticmethod`, and `@property`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### @classmethod"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `@classmethod` decorator modifies methods so that instead of taking an *instance* of a class as the first argument (what we normally call `self`) it takes the *class itself* (which we normally call `cls`). This is typically used to provide a way to instantiate a class using alternate input arguments than what is defined in `__init__`. For example, say we had a dictionary that specifies all of the information about Susie:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [],
   "source": [
    "susie_dict = {}\n",
    "susie_dict['name'] = 'Susie'\n",
    "susie_dict['homework_grades'] = [80., 73., 77., 50., 0.]\n",
    "susie_dict['exam_grades'] = [70., 63., 50.]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now instantiate a `Student` representation of Susie using the `from_dict` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Susie\n",
      "[80.0, 73.0, 77.0, 50.0, 0.0]\n",
      "[70.0, 63.0, 50.0]\n"
     ]
    }
   ],
   "source": [
    "susie = Student.from_dict(susie_dict)\n",
    "\n",
    "print(susie.name)\n",
    "print(susie.homework_grades)\n",
    "print(susie.exam_grades)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that when we used `from_dict` we only provided the dictionary, even though the definition of `from_dict` had two arguments, `cls` and `sdict`. As with normal methods, `@classmethod` automatically adds in the class as the first argument.\n",
    "\n",
    "In PyCBC Inference we most often use `@classmethod` to define a `from_config` function for a class. These functions extract the information needed to initialize the class from a configuration file. For example, [EmceeEnsembleSampler.from_config](http://pycbc.org/pycbc/latest/html/pycbc.inference.sampler.html#pycbc.inference.sampler.emcee.EmceeEnsembleSampler.from_config) creates an instance of an `emcee` sampler using information provided in the given configuration file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### @staticmethod"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `@staticmethod` decorator modifies methods so that the class instance `self` is *not* automatically added when the method is called. As a result, we do not need to reserve the first argument in the definition of a `@staticmethod`. We see that in the above example: `avg` takes a single argument `values`, which is a list of values to calculate an average for.\n",
    "\n",
    "Since methods wrapped with `@staticmethod` do not do any automatic substitutions, it's possible to use them without needing to create a class instance. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "65.0"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Student.avg([60., 70.])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In fact, we could have just defined `avg` outside of `Student` in the global namespace. In that case we would of called `avg(...)` instead of `self.avg(...)` inside of `Student`.\n",
    "\n",
    "So why use `@staticmethod`? Its main purpose is to provide a function that is heavily used by a class, but may have little meaning outside of the class. This can make code a easier to read and understand (\"[syntactic sugar](https://en.wikipedia.org/wiki/Syntactic_sugar)\"). Basically, `@staticmethod` is a way of logically organizing functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### @property"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `@property` decorator is another form of syntactic sugar that modifies how a method is called. Basically, it makes a method look like an attribute.\n",
    "\n",
    "For example, in the above `homework_avg`, `exam_avg`, and `gpa` were all methods. Normally you would call them like `susie.gpa()` (as we did in the [Classes](#III.-Classes) section). However, because we stuck the `@property` decorator on each of these methods, we instead do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2.34"
      ]
     },
     "execution_count": 55,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "susie.gpa"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In other words, we no longer include the `()` after the name. Note that `@property` **only works with methods that take no arguments.**\n",
    "\n",
    "The `@property` is used when we want to run some additional code under the hood when an attribute is accessed. It is typically paired with a \"setter\", which allows us to also run some code when an attribute is set. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Star(object):\n",
    "    _mass = None\n",
    "    \n",
    "    @property\n",
    "    def mass(self):\n",
    "        if self._mass is None:\n",
    "            raise ValueError(\"no mass set\")\n",
    "        return self._mass\n",
    "    \n",
    "    @mass.setter\n",
    "    def mass(self, value):\n",
    "        if value <= 0:\n",
    "            raise ValueError(\"mass must be > 0\")\n",
    "        self._mass = value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [],
   "source": [
    "star = Star()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "no mass set",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-58-523e8c42a617>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mstar\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mmass\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m<ipython-input-56-5d9e60710c21>\u001b[0m in \u001b[0;36mmass\u001b[0;34m(self)\u001b[0m\n\u001b[1;32m      5\u001b[0m     \u001b[0;32mdef\u001b[0m \u001b[0mmass\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mself\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      6\u001b[0m         \u001b[0;32mif\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0m_mass\u001b[0m \u001b[0;32mis\u001b[0m \u001b[0mNone\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 7\u001b[0;31m             \u001b[0;32mraise\u001b[0m \u001b[0mValueError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"no mass set\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      8\u001b[0m         \u001b[0;32mreturn\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0m_mass\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      9\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mValueError\u001b[0m: no mass set"
     ]
    }
   ],
   "source": [
    "print(star.mass)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10.0\n"
     ]
    }
   ],
   "source": [
    "star.mass = 10.\n",
    "print(star.mass)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "mass must be > 0",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-60-8ab51371277a>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0mstar2\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mStar\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m \u001b[0mstar2\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mmass\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m-\u001b[0m\u001b[0;36m3\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m<ipython-input-56-5d9e60710c21>\u001b[0m in \u001b[0;36mmass\u001b[0;34m(self, value)\u001b[0m\n\u001b[1;32m     11\u001b[0m     \u001b[0;32mdef\u001b[0m \u001b[0mmass\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mself\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mvalue\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     12\u001b[0m         \u001b[0;32mif\u001b[0m \u001b[0mvalue\u001b[0m \u001b[0;34m<=\u001b[0m \u001b[0;36m0\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 13\u001b[0;31m             \u001b[0;32mraise\u001b[0m \u001b[0mValueError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"mass must be > 0\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m     14\u001b[0m         \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0m_mass\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mvalue\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mValueError\u001b[0m: mass must be > 0"
     ]
    }
   ],
   "source": [
    "star2 = Star()\n",
    "star2.mass = -3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## B. More on functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multiple variables"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our `floor` function defined above is simple function of one argument. We can build more complicated functions that act on multiple arguments. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {},
   "outputs": [],
   "source": [
    "def floorplus(a, b):\n",
    "    \"\"\"Takes the floor of a and adds it to b.\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    a : float\n",
    "        The value to take the floor of.\n",
    "    b : float\n",
    "        The value to add to.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    float :\n",
    "        Returns floor(a) + b.\n",
    "    \"\"\"\n",
    "    return floor(a) + b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "6.86\n",
      "3.2\n"
     ]
    }
   ],
   "source": [
    "print(floorplus(a, b))\n",
    "print(floorplus(b, c))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, `floorplus` is a function of two arguments, both of which are required. We can also define functions that use default values for some arguments. If we don't provide the values for these arguments when calling the function, the default is used. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {},
   "outputs": [],
   "source": [
    "def floorplus2(a, b, offset=0):\n",
    "    return floor(a) + b + offset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "6.86\n",
      "7.86\n"
     ]
    }
   ],
   "source": [
    "print(floorplus2(a, b))\n",
    "print(floorplus2(a, b, offset=1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Positional v. keyword arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we called `floorplus2` in the second example, we just passed `a` and `b`, but explicitly set `offset=1`. But we did not need to set `offset` in this manner; this works just as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.86\n"
     ]
    }
   ],
   "source": [
    "print(floorplus2(a, b, 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, we could have been explicit with all three arguments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.86\n"
     ]
    }
   ],
   "source": [
    "print(floorplus2(a=a, b=b, offset=1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When arguments are passed without explicitly setting their names, they are called **positional** arguments. When arguments are passed with their names explicitly set, they are called **keyword** arguments.\n",
    "\n",
    "If we provide all arguments as keyword arguments, as we did in the second case, we do not need to respect the order of the arguments. To illustrate this, let's define a new function that simply prints what value it is given for each argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [],
   "source": [
    "def printargs(a, b, c=3, d=4):\n",
    "    print('a:', a, 'b:', b, 'c:', c, 'd:', d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we get the same result in all of the following ways:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a: 1 b: 2 c: 3 d: 4\n",
      "a: 1 b: 2 c: 3 d: 4\n",
      "a: 1 b: 2 c: 3 d: 4\n",
      "a: 1 b: 2 c: 3 d: 4\n"
     ]
    }
   ],
   "source": [
    "printargs(1, 2)\n",
    "printargs(1, 2, 3, 4)\n",
    "printargs(a=1, b=2, c=3, d=4)\n",
    "printargs(c=3, a=1, d=4, b=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Calling functions with the `*` and `**` operators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python provides another, even more flexible way to call functions. Say we have a list of values that we want our `printargs` function to operate on:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "metadata": {},
   "outputs": [],
   "source": [
    "args = [5, 6, 7, 8]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can then do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a: 5 b: 6 c: 7 d: 8\n"
     ]
    }
   ],
   "source": [
    "printargs(*args)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, if we have a dictionary of values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "metadata": {},
   "outputs": [],
   "source": [
    "kwargs = {'a': 5, 'b': 6, 'c': 7, 'd': 8}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a: 5 b: 6 c: 7 d: 8\n"
     ]
    }
   ],
   "source": [
    "printargs(**kwargs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In other words, if we have a list of values, we can pass the elements of the list as positional arguments to a function using the `*` operator followed by the list. If we have a dictionary of values, we can pass the dictionary as keyword arguments to the function using the `**` operator.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\"><b>Note:</b> <code>*</code> and <code>**</code> are also used as multiplication and exponent operators, respectively. What they are being used for will always be obvious from the context.</div>\n",
    "    \n",
    "This functionality is useful when handling functions programmatically. For example, if you don't know ahead of time if a user is going to provide one or more default arguments, you can set up a dictionary and populate it accordingly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining functions with the `*` and `**` operators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also define functions using these operators. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "metadata": {},
   "outputs": [],
   "source": [
    "def printargs2(*args, **kwargs):\n",
    "    print('args:', args)\n",
    "    print('kwargs:', kwargs)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "args: (0, 1, 2)\n",
      "kwargs: {'foo': 100, 'bar': 200, 'cat': 'hat'}\n"
     ]
    }
   ],
   "source": [
    "args = range(3)\n",
    "kwargs = {'foo': 100, 'bar': 200, 'cat': 'hat'}\n",
    "printargs2(*args, **kwargs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The advantage with this is you can define functions for which you do not know how many arguments will be passed at run time. This can happen if the number of argument and names of the arguments the function will need will change depending on the context. This is made use of by PyCBC's [waveform.get_td_waveform](http://pycbc.org/pycbc/latest/html/pycbc.waveform.html#pycbc.waveform.waveform.get_td_waveform) and [waveform.get_fd_waveform](http://pycbc.org/pycbc/latest/html/pycbc.waveform.html#pycbc.waveform.waveform.get_fd_waveform) functions, for example.\n",
    "\n",
    "The disadvantage to defining functions in this way is it obfuscates what the function does and what arguments are needed. For this reason, **defining functions in this manner should only be used sparingly**."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}