chapter-7-abstraction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Abstraction\n",
    "\n",
    "<a href=\"../../_slides/chapter-7-slides.html\">See also the slides that summarize a portion of this content.</a>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Abstract vs. concrete\n",
    "\n",
    "Abstract and concrete are at opposite ends of a spectrum; concrete refers to specific things, usually with more details in them, and abstract refers to general principles or ideas, usually unconnected to any specific example.  The following table may help clarify this.\n",
    "\n",
    "|       | Concrete (or specific) | Abstract (or general) |\n",
    "|-------|----------------------|------------------------|\n",
    "| Example from science: | When we drop things, they fall to earth. | Gravitation obeys the principle $G_{\\mu v}+\\Lambda g_{\\mu v}=\\frac{8\\pi G}{c^4}T_{\\mu v}$ |\n",
    "| Example from business: | That startup failed because each partner tried to pull it in a different direction. | Organizations need everyone to pursue a single, clear vision. |\n",
    "| Example from ethics: | The Nazis' attacks on the Jews were a great evil. | Systematically disadvantaging any racial group is wrong. |\n",
    "\n",
    "*Abstraction* is therefore the process of moving from the concrete toward the abstract, or from the specific to the general.  Therefore it's also called *generalization.*  Humans are pretty good at learning general principles from specific examples, so this is a natural thing for us to do.\n",
    "\n",
    "It's very useful in all kinds of programming, including data-related work, so it's our focus in this chapter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Abstraction in mathematics\n",
    "\n",
    "### Example 1: Algebra class\n",
    "\n",
    "My kids are teenagers and have recently taken algebra classes where they learned to \"complete the square.\"  This procedure takes a quadratic equation like $16x^2-9x+5=0$ and manipulates it into a form that's easy to solve.\n",
    " * Each homework problem was a *specific* example of this technique.\n",
    " * If you apply the technique to the equation $ax^2+bx+c=0$, the result is the quadratic formula, $x=\\frac{-b\\pm\\sqrt{b^2-4ac}}{2a}$, a *general* solution to all quadratic equations.\n",
    "\n",
    "Abstraction from the specific to the general tends to create more powerful tools, because they can be applied to any specific instance of the problem.  The quadratic formula is a powerful tool because it can solve any quadratic equation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 2: Excel formulas\n",
    "\n",
    "If you took the grading policy out of the syllabus for this class, you could compute your grade in the course based on your scores on each assignment.  You could do this by hand with pencil and paper, or with a calculator.  Doing so would give you one specific course grade, for the specific assignment grades you started with.\n",
    "\n",
    "Alternately, you could fire up a spreadsheet like Excel, and create cells for each assignment's score, then create formulas that would do the appropriate computation and give you the corresponding course grade.  This general solution works for any specific assignment grades you might type into the spreadsheet's input cells.\n",
    "\n",
    "Again, the general version is more useful."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Observations\n",
    "\n",
    "Both of these mathematical examples involved replacing numbers with variables.  In Example 1, the coefficients in the specific example $16x^2-9x+5=0$ turned into $a$, $b$, and $c$ in $ax^2+bx+c=0$.  In Example 2, you didn't write formulas that had specific scores in them (as you would have if computing the scores by hand), but wrote formulas that contained Excel-style variables, which have names like A5 and B14, that come from the relevant cells.  In math (and in programming as well), abstraction typically involves *replacing specific constants with variables.*\n",
    "\n",
    "Once we've rephrased our computation in terms of variables, we can do many different mathematical operations with it.\n",
    "\n",
    " 1. We can think of our computation as a function.\n",
    "     * In Example 1, the quadratic formula can be seen as a function that takes as input the values $a,b,c$ and yields as output the two solutions of the equation.\n",
    "     * In Example 2, the Excel formulas can be seen as a function that take the assignment grades as input and yield the course grade as output.\n",
    " 2. We can ask what happens when one of the variables changes, a question that calculus focuses on.\n",
    "     * For instance, you could ask what happens to your computation as one of the variables gets larger and larger.  (In calculus, we wrote this as $\\lim_{x\\to\\infty}$.)\n",
    "     * Or you could ask how quickly the result of the computation responds to changes in one input variable.  (In calculus, we wrote this as $\\frac{d}{dx}$.)\n",
    " 3. We can make statements about the computation in terms of the input variables.\n",
    "     * In Example 1, we might say that \"Every quadratic equation has two complex number solutions.\"\n",
    "     * In Example 2, we might say that \"It's still possible for me to get an A- in this course if my final exam score is good enough.\"\n",
    "\n",
    "The statement you just read about every quadratic equation is a *universal* statement, also called a \"for all\" statement.  You could rephrase it as:  For all inputs $a,b,c$, the outputs of the quadratic formula are two complex numbers.  The statement from Example 2 is an *existence* statement, also called a \"for some\" statement.  You could rephrase it as:  For some final exam scores, my final course grade is still a 4.0.  For all/for some statements are central to mathematics and we will see them show up a lot.  \"For all\" and \"for some\" are called *quantifiers* and are sometimes written $\\forall$ (for all) and $\\exists$ (for some, or \"there exists\")."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Abstraction in programming\n",
    "\n",
    "```{admonition} Big Picture - The value of abstraction in programming\n",
    "---\n",
    "class: alert alert-primary\n",
    "---\n",
    "This section covers the value of abstraction for every programmer.  It is a valuable viewpoint to have and skill to be able to employ.  See the rest of this section for details on how it works and how to use it.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 3: Copying and pasting code\n",
    "\n",
    "Best practices for coding include writing DRY code, where DRY stands for Don't Repeat Yourself.  If you find yourself writing the same code (or extremely similar code) more than once, especially if you're copying and pasting, this is a sure sign that you are not writing DRY code and should try to correct this style error.  The way to correct it is with abstraction, as shown below.  (The opposite of DRY code is WET code--Write Everything Twice.  Don't do that.)\n",
    "\n",
    "In Spring and Fall 2020, my MA346 students analyzed COVID-19 case data from various states in the U.S.  They had DataFrames with case numbers, death numbers, and recovery numbers.  Let's imagine that they wanted to keep just the first 8 columns and give them clearly readable names.  The code might look like this.\n",
    "\n",
    "```python\n",
    "df_cases.drop( columns=df_cases.columns[8:], inplace=True )\n",
    "df_cases.columns = [ 'State', 'Country', 'Latitude', 'Longitude',\n",
    "                     'January', 'February', 'March', 'April' ]\n",
    "df_deaths.drop( columns=df_deaths.columns[8:], inplace=True )\n",
    "df_deaths.columns = [ 'State', 'Country', 'Latitude', 'Longitude',\n",
    "                      'January', 'February', 'March', 'April' ]\n",
    "df_recoveries.drop( columns=df_recoveries.columns[8:], inplace=True )\n",
    "df_recoveries.columns = [ 'State', 'Country', 'Latitude', 'Longitude',\n",
    "                          'January', 'February', 'March', 'April' ]\n",
    "```\n",
    "\n",
    "The typical way of creating code like what's shown above is to write just the code for `df_cases`, run it, verifiy that it works, and then copy and paste it twice and change the details to apply the same code to the other two DataFrames.  But this code can be made much cleaner through abstraction.\n",
    "\n",
    "Rather than copy and paste the code and change key parts of it, replace those key parts with a *general* (that is, abstract) variable name, and then turn the code into a function.  Since this code drops the columns we don't care about, we could have made that the name of the function.\n",
    "\n",
    "```python\n",
    "def drop_unneeded_columns ( df ):\n",
    "    df.drop( columns=df.columns[8:], inplace=True )\n",
    "    df.columns = [ 'State', 'Country', 'Latitude', 'Longitude',\n",
    "                   'January', 'February', 'March', 'April' ]\n",
    "```\n",
    "\n",
    "Once this general version is complete, we can apply it to each specific case we need.\n",
    "\n",
    "```python\n",
    "drop_unneeded_columns( df_cases )\n",
    "drop_unneeded_columns( df_deaths )\n",
    "drop_unneeded_columns( df_recoveries )\n",
    "```\n",
    "\n",
    "There are several advantages to this new version.\n",
    "\n",
    " 1. While it is still six lines of code, half of them are much shorter, so there's less to read and understand.\n",
    " 2. What the code is doing is more obvious, because we've given it a name; we're obviously dropping columns we don't need.\n",
    " 3. It wasn't immediately obvious in the first version of the code that we were repeating the same procedure three times.  Now it is.\n",
    " 4. If you later need to change which columns you keep or how you name them, you have to make that change in only one place (inside the function).  Before, you would have had to make the same change three times.\n",
    " 5. Also, if you tried to make a change to the code later, but accidentally forgot to change one of the three copies, you'd have broken your code and maybe not realized it.\n",
    " 6. You could share this same function to other notebooks or with other coders if needed.\n",
    "\n",
    "So the moment you find yourself copying and pasting code, remember to stay DRY instead---create a function and call it multiple times, so that you get all these benefits."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Alternatives\n",
    "\n",
    "Another method of abstraction would have been a loop instead of a function.  Since the original code does the same thing three times, we could have rewritten it as follows instead.\n",
    "\n",
    "```python\n",
    "for df in [ df_cases, df_deaths, df_recoveries ]:\n",
    "    df.drop( columns=df.columns[8:], inplace=True )\n",
    "    df.columns = [ 'State', 'Country', 'Latitude', 'Longitude',\n",
    "                   'January', 'February', 'March', 'April' ]\n",
    "```\n",
    "\n",
    "This has all the same benefits as the previous method, except for \\#6.\n",
    "\n",
    "One could even combine the two methods together, as follows.\n",
    "\n",
    "```python\n",
    "def drop_unneeded_columns ( df ):\n",
    "    df.drop( columns=df.columns[8:], inplace=True )\n",
    "    df.columns = [ 'State', 'Country', 'Latitude', 'Longitude',\n",
    "                   'January', 'February', 'March', 'April' ]\n",
    "\n",
    "for df in [ df_cases, df_deaths, df_recoveries ]:\n",
    "    drop_unneeded_columns( df )\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 4: Testing a computation\n",
    "\n",
    "Let’s imagine that the same student as above, who has COVID-19 data, wants to investigate its connection to the polarized political climate in the U.S., since COVID-19 response has been very politicized. They want to ask whether there’s any correlation between the spread of the virus in a state and that state’s prevailing political leaning. So the student gets another dataset, this one listing the percentage of registered Republicans and Democrats in each U.S. state. They will want to look up each state in the COVID-19 dataset in this new dataset, to connect them. They try this:\n",
    "\n",
    "So the student gets a second dataset, this one listing the percentage of registered Republicans and Democrats in each U.S. state.  They will want to look up each state in the COVID-19 dataset in this new dataset, to connect them.  They try this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": [
       "0.26"
      ]
     },
     "metadata": {},
     "execution_count": 4
    }
   ],
   "source": [
    "# load political data\n",
    "import pandas as pd\n",
    "df_registration = pd.read_excel( '_static/political-registrations.xlsx',\n",
    "                                 sheet_name=0 )\n",
    "\n",
    "# make dictionaries for easy lookup:\n",
    "percent_republican = dict( zip( df_registration['State'], df_registration['R%'] ) )\n",
    "percent_democratic = dict( zip( df_registration['State'], df_registration['D%'] ) )\n",
    "\n",
    "# see if it works on Alaska:\n",
    "percent_republican['AK']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great, progress!  Let's just try one or two more random examples to be sure that wasn't a fluke."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "output_type": "error",
     "ename": "KeyError",
     "evalue": "'AL'",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mKeyError\u001b[0m                                  Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-5-18a057d6e676>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0;31m# see if it works on Alabama:\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[0mpercent_republican\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'AL'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mKeyError\u001b[0m: 'AL'"
     ]
    }
   ],
   "source": [
    "# see if it works on Alabama:\n",
    "percent_republican['AL']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Uh-oh.  Checking [the website where they got the data](http://centerforpolitics.org/crystalball/articles/registering-by-party-where-the-democrats-and-republicans-are-ahead/), the student finds that Alabama doesn't register voters by party, so Alabama isn't in the data.  They need some code that won't cause errors for any state input, so they update it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": [
       "nan"
      ]
     },
     "metadata": {},
     "execution_count": 6
    }
   ],
   "source": [
    "import numpy as np\n",
    "percent_republican['AL'] if 'AL' in percent_republican else np.nan"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This technique looks like it will work for any input, because instead of giving an error it returns NaN.  Because NaN is the standard way to represent missing values, this makes sense.  Good, let's turn it into a function and test that function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": [
       "(0.26, nan)"
      ]
     },
     "metadata": {},
     "execution_count": 7
    }
   ],
   "source": [
    "def get_percent_republican ( state_code ):\n",
    "    return percent_republican[state_code] if state_code in percent_republican else np.nan\n",
    "def get_percent_democratic ( state_code ):\n",
    "    return percent_democratic[state_code] if state_code in percent_democratic else np.nan\n",
    "\n",
    "get_percent_republican( 'AK' ), get_percent_republican( 'AL' )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": [
       "(0.14, nan)"
      ]
     },
     "metadata": {},
     "execution_count": 8
    }
   ],
   "source": [
    "get_percent_democratic( 'AK' ), get_percent_democratic( 'AL' )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So Example 4 has shown us that abstracting a computation into a function can be done as part of an ordinary coding workflow:  Start easy, by doing the computation on just one input and get that working.  Once it does, test it on some other inputs.  Then create a function that works in general.\n",
    "\n",
    "The benefits of this include all the benefits discussed after Example 3, plus this one:  The student wanted to run this computation for every row in a DataFrame.  That's easy to do now, with code like the following.\n",
    "\n",
    "```python\n",
    "df_cases['percent_republican'] = df_cases['Province/State'].apply( get_percent_republican )\n",
    "df_cases['percent_democratic'] = df_cases['Province/State'].apply( get_percent_democratic )\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Little abstractions (`lambda`)\n",
    "\n",
    "When it would be handy to create a function, but the function is so small that it seems like giving it a name with `def` is overkill, you can use Python's `lambda` syntax to create the function.\n",
    "\n",
    "(The name comes from the fact that some branches of computer science use notation like $\\lambda x.3x+1$ to mean \"the function that takes $x$ as input and gives $3x+1$ as output.\"  So they could write $f=\\lambda x.3x+1$ instead of $f(x)=3x+1$.)\n",
    "\n",
    "For example, let's say you have a dataset in which each row represents an hour of trading on an exchange, and the volume is classified using the codes 0, 1, 2, and 3, which stand (respectively) for low volume, medium volume, high volume, and unknown (missing data).  We'd like the dataset to be more readable, so we'd like to replace those numbers with the actual words low, medium, high, and unknown.  We could do it as follows.\n",
    "\n",
    "```python\n",
    "def explain_code ( code ):\n",
    "    words = [ 'low', 'medium', 'high', 'unknown' ]\n",
    "    return words[code]\n",
    "\n",
    "df['volume'] = df['volume'].apply( explain_code )\n",
    "```\n",
    "\n",
    "But this requires several lines of code to do this simple task.  We could compress it into a one-liner as follows.\n",
    "\n",
    "```python\n",
    "df['volume'] = df['volume'].apply( lambda code: ['low','medium','high','unknown'][code] )\n",
    "```\n",
    "\n",
    "The limitation to Python's `lambda` syntax is that you can put inside only a single expression, which the function will return.  A function that needs to do several preparatory computations before returning an answer cannot be converted into `lambda` form."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to do abstraction\n",
    "\n",
    "If you aren't sure how to take specific code and turn it into a general function, I suggest following the steps given here.  Once you've done this a few times, it will come naturally, without thinking through the steps.\n",
    "\n",
    "Let's use the following example code to illustrate the steps.  It's useful in DataFrames imported from a file where dollar amounts were written in a form like $4,320,000.00, which pandas won't recognize as a number, because of the commas and the dollar sign.  This code converts such a column to numeric.  Since it's so useful, we may want to use it on multiple columns.\n",
    "\n",
    "```python\n",
    "df['Tuition'] = df['Tuition'].str.replace( \"$\", \"\" ) # remove dollar signs\n",
    "df['Tuition'] = df['Tuition'].str.replace( \",\", \"\" ) # remove commas\n",
    "df['Tuition'] = df['Tuition'].astype( float )        # convert to float type\n",
    "```\n",
    "\n",
    "### Step 1:  Decide which parts of the code are customizable.  That is, which parts of the code might change the next time you want to use it?\n",
    "\n",
    "In this code, we certainly want to be able to specify a different column, so `'Tuition'` needs to be customizable.  Also, we've converted this column to type `float`, but perhaps some other column of money might better be represented as `int`, so we'll want the data type to be customizable also.\n",
    "\n",
    "### Step 2:  Move each of the customizable pieces of code out into a variable with a helpful name, declared before the code is run.\n",
    "\n",
    "This is probably clearest if it's illustrated:\n",
    "\n",
    "```python\n",
    "column = 'Tuition'\n",
    "new_type = float\n",
    "df[column] = df[column].str.replace( \"$\", \"\" ) # remove dollar signs\n",
    "df[column] = df[column].str.replace( \",\", \"\" ) # remove commas\n",
    "df[column] = df[column].astype( new_type )     # convert to new type\n",
    "```\n",
    "\n",
    "You can then re-run this code to be sure it still does what it's supposed to do.   (That is, check to be sure you haven't accidentally changed the code's meaning.)\n",
    "\n",
    "### Step 3:  Decide on a succinct description for what your code does, to use as the name of a new function.\n",
    "\n",
    "In this case, we're converting a column of currency to a new type, but I don't want to call it `convert_currency` because that sound like we're using exchange rates between two currencies.  Let's call it `simplify_currency`.\n",
    "\n",
    "### Step 4:  Indent your original code and introduce a `def` line to define a new function with your chosen name.  Its inputs should be the names of the variables you created.\n",
    "\n",
    "In our example:\n",
    "\n",
    "```python\n",
    "def simplify_currency ( column, new_type ):\n",
    "    df[column] = df[column].str.replace( \"$\", \"\" ) # remove dollar signs\n",
    "    df[column] = df[column].str.replace( \",\", \"\" ) # remove commas\n",
    "    df[column] = df[column].astype( new_type )     # convert to new type\n",
    "```\n",
    "\n",
    "If you run it at this point, it doesn't actually do anything to your DataFrame, because the code shown above just defines a function.  So we need one more step.\n",
    "\n",
    "### Step 5:  Call your new function to accomplish what your original code used to accomplish.\n",
    "\n",
    "```python\n",
    "def simplify_currency ( column, new_type ):\n",
    "    df[column] = df[column].str.replace( \"$\", \"\" ) # remove dollar signs\n",
    "    df[column] = df[column].str.replace( \",\", \"\" ) # remove commas\n",
    "    df[column] = df[column].astype( new_type )     # convert to new type\n",
    "\n",
    "simplify_currency( 'Tuition', float )  # <--- Here we use our function.\n",
    "```\n",
    "\n",
    "This should have the same effect as the original code.  Except now you can re-use it on as many inputs as you like.\n",
    "\n",
    "```python\n",
    "simplify_currency( 'Fees', float )\n",
    "simplify_currency( 'Books', float )\n",
    "simplify_currency( 'Room and board', float )\n",
    "```\n",
    "\n",
    "Sorry, that's a depressing example.  Let's move on...\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How do I know when to use abstraction?\n",
    "\n",
    "Whenever you find yourself copying and pasting code with minor changes, this is a sure sign that you should write a function instead.  The reasons why are all the benefits listed at the end of [Example 3](#example-3-copying-and-pasting-code), above.\n",
    "\n",
    "Also, if you have several lines of code in a row with only one thing changing, you can use abstraction to create a loop instead of a function.  We saw an example of this in the [Alternatives](#alternatives) section, above.  This is especially important if there's a numeric progression involved.\n",
    "\n",
    "**Later, the skill of abstracting code will be a crucial part of our work on creating interactive dashboards.**  In class, we will practice using abstraction to improve code written in a redundant style."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```{admonition} Learning on Your Own - Writing Python modules\n",
    "---\n",
    "class: alert alert-danger\n",
    "---\n",
    "Once you've created a useful function, such as the `simplify_currency` function above, that you might want to reuse in many Python scripts or Jupyter notebooks, where should you store it?  Copying and pasting it across many notebooks creates the same problems that copying and pasting any code causes.  The best strategy is to create a Python module.\n",
    "```\n",
    "\n",
    "A tutorial on writing Python modules could answer the following questions.\n",
    "\n",
    " * How do I start creating a Python module?\n",
    " * How do I move a function I've written into my new Python module?\n",
    " * Where do I store a Python module I've created?\n",
    " * How do I import my new module into scripts or notebooks I write?\n",
    " * How do I use the functions in my module after I've imported it?\n",
    " * Can I publish my module online in an official way?\n",
    "\n",
    "```{admonition} Learning on Your Own - Jupyter `%run` magic\n",
    "---\n",
    "class: alert alert-danger\n",
    "---\n",
    "In a Jupyter notebook, the `%run` command tells Jupyter to execute an entire other Jupyter notebook or Python script as if it had been inserted into a single cell in your current notebook.  (It's called a \"magic\" command because the `%` sign gives it a meaning beyond normal Python code.)  This command could be used to avoid creating Python modules in some cases.\n",
    "```\n",
    "\n",
    "A tutorial on the `%run` magic command would address these questions:\n",
    "\n",
    " * How exactly do I use the `%run` command to run one Jupyter notebook inside another?\n",
    " * Why might I want to write a Jupyter notebook instead of a Python module?\n",
    " * What are the pros and cons of doing this instead of writing a Python module?\n"
   ]
  },
  {
   "source": [
    "## What if abstraction seems tricky?\n",
    "\n",
    "It's always good to be careful!  If writing Python functions is new to you, or you aren't sure that the functions you write are working correctly, it's good to stop and test them carefully before you rely on them.\n",
    "\n",
    "If your function returns a value, you can run it on a few example inputs to be sure it works.  Let's say we had to write a Celsius-to-Fahrenheit converter, like this."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "def convert_C_to_F ( C ):\n",
    "    return 9/5*C+32"
   ]
  },
  {
   "source": [
    "We could test to be sure that it works by plugging in some values for which we know the answer, and ensuring it gives the right output."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": [
       "(32.0, 212.0)"
      ]
     },
     "metadata": {},
     "execution_count": 10
    }
   ],
   "source": [
    "convert_C_to_F( 0 ), convert_C_to_F( 100 )"
   ]
  },
  {
   "source": [
    "But then we still have to manually observe and verify that the numbers are correct.  Later, if something changes (perhaps we accidentally edited our original function), we could easily not notice, because we weren't re-checking these test outputs.\n",
    "\n",
    "To solve that problem, Python provides the `assert` keyword.  It lets you, well, assert things that you think are true, and Python will check them.  If they are true, Python does nothing.  But if they aren't true, then Python throws an error message so that the problem will become visually obvious to you in your notebook.\n",
    "\n",
    "So we could convert our tests up above into the `assert` format as follows."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert convert_C_to_F( 0 ) == 32\n",
    "assert convert_C_to_F( 100 ) == 212"
   ]
  },
  {
   "source": [
    "Notice that there is no output.  That's a good thing.  Python is silent because there are no problems here.  If we had asserted something false, it would have given us an obvious error message, to increase the likelihood that we would notice and fix the problem.\n",
    "\n",
    "Here's an assertion that's intentionally wrong, so you can see what the error messages look like."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "output_type": "error",
     "ename": "AssertionError",
     "evalue": "",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-12-766b548a1053>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32massert\u001b[0m \u001b[0mconvert_C_to_F\u001b[0m\u001b[0;34m(\u001b[0m \u001b[0;36m0\u001b[0m \u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0;36m0\u001b[0m  \u001b[0;31m# intentionally wrong...gives an error\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m: "
     ]
    }
   ],
   "source": [
    "assert convert_C_to_F( 0 ) == 0        # this should give an error..."
   ]
  },
  {
   "source": [
    "But some functions don't return values.  The `drop_unneded_columns` function from earlier just modifies a DataFrame that we had already loaded.  In that case, since there is no output of the function for us to test, we could test its effectiveness by using `assert` on the DataFrame that was modified.  We might write statements like the following.\n",
    "\n",
    "```python\n",
    "assert len( df_cases.columns ) == 8\n",
    "assert df_cases.columns[4] == 'January'\n",
    "```\n",
    "\n",
    "Putting a few of these checks throughout your notebooks will ensure that if you change something important without realizing it, the next time you re-run your notebook, you'll immediately see the problem and can fix it.  This helps avoid compounding problems over time, and gives a sense of reassurance, when all the `assert`ions pass, that your code is still working smoothly."
   ],
   "cell_type": "markdown",
   "metadata": {}
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.2",
   "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.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}