Week 05 - Files.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Week 5: Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Drill"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden",
    "solution2_first": true,
    "solution_first": true
   },
   "source": [
    "Write a function `isodd()` that will return `-1` if the number is an even number, or `1` if the number is an odd number. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "solution": "hidden",
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "def isodd(num): \n",
    "    if num % 2 == 0: \n",
    "        return 1\n",
    "    else: \n",
    "        return -1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden",
    "solution2_first": true,
    "solution_first": true
   },
   "source": [
    "Write a code that will do the following: \n",
    "* If the number can be divided by $2$, plus $1$ to the number and run the next rule. \n",
    "* If the number can be divided by $3$, print $-1$ and exit the code. \n",
    "* If the number can be divided by $5$, print $-1$ and exit the code. \n",
    "* If none of the rules apply, then print `'Congrats! You have found the number!'`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "number = int(input())   # You can predefine the number instead of using input()\n",
    "while True: \n",
    "    if number % 2 == 0: \n",
    "        number += 1\n",
    "    elif number % 3 == 0: \n",
    "        print('-1')\n",
    "        break\n",
    "    elif number % 5 == 0: \n",
    "        print('-1')\n",
    "        break\n",
    "    else: \n",
    "        print('Congrats! You have found the number!')\n",
    "        break"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden",
    "solution2_first": true,
    "solution_first": true
   },
   "source": [
    "Write a function `positive_match()` that will return the words (of a string) that matches with the given list `positive_words`. Print the words line by line. The `split()` method and the `in` keyword may help you. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['friendliness', 'enthusiastic', 'joyful']"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Solution\n",
    "essay = 'In its darkest time let truth and friendliness show. Aggie sniffed Mattias, as if it is like the first day they have been met. The rain poured heavily, but now, it washed all the embarrassments and hard times on their face. Mattias wanted to move his face muscle. His speaking was weak, but his tips tried, harder and harder. Aggie gazed at Mattias. It seems a dog would even be enthusiastic on what Mattias wants to say. Mattias smiled. It is the first time since he had a joyful face. That had never been shown before. Aggie healed Mattias, but so as himself.'\n",
    "positive_words = ['accepted', 'attractive', 'enthusiastic', 'friendliness', 'happy', 'joyful', 'right', 'robust']\n",
    "\n",
    "def positive_match(words, positive_words):\n",
    "    words = words.split()\n",
    "    words = [word.strip(',') for word in words]\n",
    "    words = [word.strip('.') for word in words]\n",
    "    target_match = []\n",
    "    for word in words: \n",
    "        if word in positive_words: \n",
    "            target_match.append(word)\n",
    "    return target_match\n",
    "\n",
    "positive_match(essay, positive_words)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "essay = 'In its darkest time let truth and friendliness show. Aggie sniffed Mattias, as if it is like the first day they have been met. The rain poured heavily, but now, it washed all the embarrassments and hard times on their face. Mattias wanted to move his face muscle. His speaking was weak, but his tips tried, harder and harder. Aggie gazed at Mattias. It seems a dog would even be enthusiastic on what Mattias wants to say. Mattias smiled. It is the first time since he had a joyful face. That had never been shown before. Aggie healed Mattias, but so as himself.'\n",
    "positive_words = ['accepted', 'attractive', 'enthusiastic', 'friendliness', 'happy', 'joyful', 'right', 'robust']\n",
    "\n",
    "def positive_match(): \n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python is very useful in writing automation and data analysis. They are the pivot point of other computer files. So that either the data stored in the files are leveraged, or the computer controlled applicances are activated. So for Python, there is an interface to use files. In this week, we will be look at \n",
    "* how to read files, and \n",
    "* how to write files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### File Formats\n",
    "\n",
    "For the purpose of this course, we differentiate between files as __containing data__ while our Python script contains instructions to read and/ or manipulate them. Here are the common file formats: \n",
    "* Text files (e.g. `.txt`, `.csv`)\n",
    "* Image (e.g. `.png`, `.jpg`)\n",
    "* Spatial data (e.g. `.kml`)\n",
    "\n",
    "File formats represent what type of data they are. It is separated with the file name by the dot. The common feature of files are the fact they are represented by 1's and 0's. With different arrangemens of these 1's and 0's, it made the computer able to interpret whether it is a text file, or an image. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The difference between file formats and formats, are the standard they follow. For example, a text follows ASCII or Unicode standard. Each characters are represented by a character code. `'a'` is represented by 97. To represent 97 in 1's and 0's, we must understand how to convert binary numbers to decimals. Taking 97 itself, it can be decomposed by $97\\;=\\;9\\;\\times\\;10\\;+\\;7\\;\\times\\;1$. $1$ and $10$ represents the order of decimal digits. So $1$, $2$, $4$ represents the binary digits. So 97 is represented as 1100001 in binary digits. \n",
    "\n",
    "You can try this below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "97"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "1*64+1*32+0*16+0*8+0*4+0*2+1*1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So as a computer, it would send a series of pulse-pulse-silence-silence-silence-silence-pulse to represent the letter `'a'`. For images, an electron pulse would represent the point in the image (i.e. pixel). Different file formats have a different standard, and this is the key when analysing the data from files. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Delimeter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Data points are separated by something to distinguish themselves. This is called a delimeter, and it can be any characters. Often the delimeters would be: \n",
    "* tab\n",
    "* space\n",
    "* new line\n",
    "* comma"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Python, we could write these characters inside strings. For example, \n",
    "* `'\\t'` represents tab characters.\n",
    "* `'\\n'` represents a new line character. \n",
    "\n",
    "Often we do not like new lines, and this is always read from files. It means for a file we read we will see \n",
    "```\n",
    "Baby baby, who's on board. \n",
    "\n",
    "Now how her Edward engage not horses. \n",
    "\n",
    "Oh! Resolution he dissimilar precaution to comparison an.\n",
    "\n",
    "```\n",
    "There is an extra new line character instead of this \n",
    "```\n",
    "Baby baby, who's on board. \n",
    "Now how her edward engage not horses. \n",
    "Oh! Resolution he dissimilar precaution to comparison an.\n",
    "\n",
    "```\n",
    "To clear these new line characters, we use the `strip()` method. This is an example: \n",
    "```python\n",
    "some_strings.strip()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden",
    "solution2_first": true,
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Write a program that will clear the new line character in the following provided string. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Writing is painful but it is part of process.\n"
     ]
    }
   ],
   "source": [
    "# Solution\n",
    "string = 'Writing is painful but it is part of process.\\n'\n",
    "print(string.strip())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "string = 'Writing is painful but it is part of process.\\n'\n",
    "print(string)\n",
    "\n",
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden",
    "solution2_first": true,
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Write a program that will clear the new line characters in the following provided paragraphs. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Writting is painful but it is part of process.\n",
      "Then so as sunset over went dull on.\n",
      "Likewise offended humoured mrs fat trifling answered.\n",
      "On ye position greatest so desirous.\n",
      "So wound stood guest weeks no terms up sought.By so these am so rapid blush songs begin.\n",
      "Nor but mean time one over.\n"
     ]
    }
   ],
   "source": [
    "# Solution\n",
    "strings = ['Writing is painful but it is part of process.\\n', 'Then so as sunset over went dull on.\\n', 'Likewise offended humoured mrs fat trifling answered.\\n', 'On ye position greatest so desirous.\\n', 'So wound stood guest weeks no terms up sought.' 'By so these am so rapid blush songs begin.\\n', 'Nor but mean time one over.\\n']\n",
    "\n",
    "for i in strings: \n",
    "    i = i.strip()    # Remember it's the string itself\n",
    "    print(i)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Writting is painful but it is part of process.\n",
      "\n",
      "Then so as sunset over went dull on.\n",
      "\n",
      "Likewise offended humoured mrs fat trifling answered.\n",
      "\n",
      "On ye position greatest so desirous.\n",
      "\n",
      "So wound stood guest weeks no terms up sought.By so these am so rapid blush songs begin.\n",
      "\n",
      "Nor but mean time one over.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "strings = ['Writing is painful but it is part of process.\\n', 'Then so as sunset over went dull on.\\n', 'Likewise offended humoured mrs fat trifling answered.\\n', 'On ye position greatest so desirous.\\n', 'So wound stood guest weeks no terms up sought.' 'By so these am so rapid blush songs begin.\\n', 'Nor but mean time one over.\\n']\n",
    "for i in strings: \n",
    "    print(i)\n",
    "# Change above code "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We could also do list comprehension to simplify the loop above. This is \n",
    "```python\n",
    "strings = [x.strip() for x in strings]\n",
    "```\n",
    "Where the `x` above represents the elements in the list of strings. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "strings = [x.strip() for x in strings]\n",
    "print(strings)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reading a File"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To read a file is easy in Python. Firstly, you will need to create a file object. In the following, we name it as `f`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "solution": "hidden"
   },
   "outputs": [],
   "source": [
    "f = open('files/first_texts.txt', 'r')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `open()` function is where we assign the variable `f` as a file object. The function accepts 2 parameters: \n",
    "* The file path\n",
    "* The mode, which is `'r'` for reading only. \n",
    "\n",
    "So `f` contains the contents of the file, not just the texts but also the metadata. Let's see by printing `f` as in below. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself, what will be printed\n",
    "print(f)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So if printing `f` does not mean printing the lines, what can we do? In Python we have `readlines()` function to extract the texts.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself, is this enough for later use?\n",
    "f.readlines()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `readlines()` function will extract the texts and put them into a list. We can store them in a variable. How can you do that?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden",
    "solution2_first": true,
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Later we will use the texts for the exercises. What would you to make this happen? "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "solution": "hidden",
    "solution2": "hidden"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[\"Oh! It's me here. My name is Sherry and I come from Mars.\"]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Solution, variable name is an example\n",
    "text = f.readlines()\n",
    "text"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we need to close the file (i.e. disconnect the program with the text file). This could prevent bugs happening, especially if we are reading then writing files in the next. To close the file, we do "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "f.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The process of reading (or writing) a file is simple as opening a file, then do something (directly) with the file and close it. The following is the flowchart of what was done above. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.display import Image\n",
    "Image(\"fig/read_file.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The process means users must remember to open a file, and close it manually. If the user does not remember to close it it could be a problem. However, there is a more faster way to handle files in Python. This is using the `with` keyword. Let us see how it is used with `readline()`. Which is the one-line version of `readlines()`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "with open('files/negative-words.txt', 'r') as pos_f: \n",
    "    string = pos_f.readline()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "print(string)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course, with `readlines()`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "with open('files/negative-words.txt', 'r') as pos_fs: \n",
    "    strings_ls = pos_fs.readlines()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "print(strings_ls)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Exercise:__ Create a text file with (random) texts, or any existing `.txt` files. Write a code that will read the file and list them line by line. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Your code\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One more note before we finish. Python will find the file when reading it. If they cannot find the file, an exception will be raised. We will talk about this at the end of class. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### File Path: Absolute and Relative Path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this exercise, we obtained our data files from a folder called `files/`. This folder is located one level below from our class sheets. To let Python find our files, we need to specify the file path in the `open()` function. Remember the file path was \n",
    "```bash\n",
    "files/negative-words.txt\n",
    "```\n",
    "This is to ask Python to find the folder (from where this document locates) called `files`. The `negative-words.txt` is there. In Python, we use either \n",
    "* abolute file path\n",
    "* relative file path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An absolute file path means the path from the absolute top. In Windows, it is the drives (e.g. `C:` or `D:`). In Linux, it is `usr`. You can find the abolute path by clicking the address in your file explorer. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.display import Image\n",
    "Image(\"fig/file_explorer.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In most cases, especially when your code needs to be used at some other computers. The path file in your computer does not apply to the other. So we need the relative file path. It means __where is your target file relative to where we are at the moment__. Let us say our class file is located in a folder called `Python Course`. Which the structure of the files are as below: \n",
    "```\n",
    "Python Course\n",
    "|_ Week 01.ipynb\n",
    "|_ Week 02.ipynb\n",
    "|_ ...\n",
    "|_ files\n",
    "|  |_ sample_text.txt\n",
    "|  |_ first_texts.txt\n",
    "|_ modules\n",
    "|  |_ __init__.py\n",
    "|  |_ happy_function.py\n",
    "|_ hw\n",
    "|  |_ Week 01.pdf\n",
    "|  |_ Week 02.pdf\n",
    "|  ...\n",
    "|_ fig\n",
    "   |_ test\n",
    "   |  |_ test01.png\n",
    "   |_ file_explorer.png\n",
    "   |_ toilet.png\n",
    "```\n",
    "\n",
    "So to find `sample.txt`, we need to use a stroke `/` to say this folder is under where we are currently located. Which means the relative file path is `files/sample.txt`. Note where the stroke is located. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For files in lower levels, such as `test_01.png` under the `test` folder. We would need more strokes like `fig/test/test_01.png`. \n",
    "\n",
    "Note that the current folder was not mentioned anywhere in the file path. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exericse:__ You need to run analysis of the photos in your computer. Your analysis program is located at the `cat_photos` folder. The file you will need to import is called `metadata.txt`. How would you write the relative file path in the `.open()` function? The following is the folder structure. \n",
    "```\n",
    "cat_photos\n",
    "|_ 2017\n",
    "|  |_ init.py\n",
    "|  |_ metadata.txt\n",
    "|_ 2018\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden"
   },
   "source": [
    "The filepath is ```2017/metadata.txt```. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Just the filepath below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If one needs to find the file in __above level__, the __dot__ `.` operator would be helpful. For example, the folder `Python Course` is located under `My Documents`. To find a file in `My Documents`, we will need to use `./some_file.txt`. \n",
    "\n",
    "If one needs to go one more level upwards, then we will need more dots in our file path. Such as `..`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Writing a File"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When Python is about to write a file, it does not have to be an existing file. In the following, let us write into a file called `my_posts.txt`. Before this __let us check if the file is in the `/files` directory.__ If there is no such file, then let's continue.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To write a file, there are 2 points that differs with previously when we read a file. Which are: \n",
    "* In opening a file, we use `'w'` instead of `'r'`. \n",
    "* We use `write()` function to write what we want. However, the contents are located inside the brackets (e.g. `write('I am writing to you...')`.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Write a code that will write texts into `my_posts.txt`. At the moment, there are no texts to be written in. Use the `with` keyword. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "solution": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "with open('files/my_posts.txt', 'w') as my_file: \n",
    "    write()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Append Contents into a File"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To append contents into a file, we will need to change the open mode as `'a'`. This is for appending texts. Again, Python will create the file is not exists. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ You would like to write one more message into `my_posts.txt`. Write a code to do that. An `input()` function may help you to input the message. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "solution": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "with open('files/my_posts.txt', 'a') as file_2: \n",
    "    file_2.write(input())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pandas and Data Frames"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One application of reading and write files is using data frames from `pandas`. A data frame is an object where the data is stored. It is represented as a tabular data structure, with rows and columns. Rows have a specific index to access them, which can be any name or value. In Pandas, the columns are called __Series__, a special type of data, which in essence consists of a list of several values, where each value has an index. \n",
    "\n",
    "To start with, let us call the package `pandas` by "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So in the following, when we are calling the methods from `pandas` we will just use the shortform `pd`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this course, we will use an existing file called `elementary_particles.csv` in the `files` folder. This a data file about different elementary particles. If you are not sure what it means, there is a [Wikipedia article](https://simple.wikipedia.org/wiki/Elementary_particle) that introduces what they means. \n",
    "\n",
    "To read the file with `pandas`, we write "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run this\n",
    "df = pd.read_csv('files/elementary_particles.csv')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Where `df` stands for data frame. It is a conventional variable when using `pandas`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To see what does a data frame mean, we can use the `.head()` method to show the tabular structure. It shows the first rows (specified in the brackets, if not then 5 rows). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Type</th>\n",
       "      <th>Generation</th>\n",
       "      <th>Spin</th>\n",
       "      <th>Charge</th>\n",
       "      <th>Mass</th>\n",
       "      <th>Interaction</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.67</td>\n",
       "      <td>2.2</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>-0.33</td>\n",
       "      <td>4.6</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.67</td>\n",
       "      <td>1280.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>-0.33</td>\n",
       "      <td>96.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>3.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.67</td>\n",
       "      <td>173100.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     Type  Generation  Spin  Charge      Mass Interaction\n",
       "0  Quarks         1.0   0.5    0.67       2.2         NaN\n",
       "1  Quarks         1.0   0.5   -0.33       4.6         NaN\n",
       "2  Quarks         2.0   0.5    0.67    1280.0         NaN\n",
       "3  Quarks         2.0   0.5   -0.33      96.0         NaN\n",
       "4  Quarks         3.0   0.5    0.67  173100.0         NaN"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Try yourself, change the parameter to see how many first rows you wanted to see. \n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ How can you view the first __3__ rows?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "solution": "hidden"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Type</th>\n",
       "      <th>Generation</th>\n",
       "      <th>Spin</th>\n",
       "      <th>Charge</th>\n",
       "      <th>Mass</th>\n",
       "      <th>Interaction</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.67</td>\n",
       "      <td>2.2</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>-0.33</td>\n",
       "      <td>4.6</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.67</td>\n",
       "      <td>1280.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     Type  Generation  Spin  Charge    Mass Interaction\n",
       "0  Quarks         1.0   0.5    0.67     2.2         NaN\n",
       "1  Quarks         1.0   0.5   -0.33     4.6         NaN\n",
       "2  Quarks         2.0   0.5    0.67  1280.0         NaN"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Solution\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Your code \n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see the data frame with the `.tail()` method. This will show the last n-th records. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Type</th>\n",
       "      <th>Generation</th>\n",
       "      <th>Spin</th>\n",
       "      <th>Charge</th>\n",
       "      <th>Mass</th>\n",
       "      <th>Interaction</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>16</th>\n",
       "      <td>Bosons</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>125.9</td>\n",
       "      <td>Mass</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>17</th>\n",
       "      <td>Bosons</td>\n",
       "      <td>NaN</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>Gravitation</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>18</th>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>19</th>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>20</th>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      Type  Generation  Spin  Charge   Mass  Interaction\n",
       "16  Bosons         NaN   0.0     0.0  125.9         Mass\n",
       "17  Bosons         NaN   2.0     0.0    0.0  Gravitation\n",
       "18     NaN         NaN   NaN     NaN    NaN          NaN\n",
       "19     NaN         NaN   NaN     NaN    NaN          NaN\n",
       "20     NaN         NaN   NaN     NaN    NaN          NaN"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Try yourself, change the parameter to see how many last rows you wanted to see. \n",
    "df.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to know the names of the __columns__ or the __names__ of the indexes, we can use the DataFrame attributes columns and index respectively. The names of the columns or indexes can be changed by assigning a new list of the same length to these attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "df.column"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "df.index"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "df.values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A compact way of doing above is using the `.shape` attribute. It will return the number of rows (record), the number of columns (features). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(21, 6)"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Exercise:__ How many rows and columns are there in `df`?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are \n",
    "* 21 rows and, \n",
    "* 6 columns. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ How can I access the number of rows in `df` using `df.shape`?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "solution": "hidden"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "21"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Solution\n",
    "'''df.shape is a tuple so we find the 0th element. '''\n",
    "df.shape[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we just want quick statistical information on all the numeric columns in a data frame, we can use the `.describe()` method. The result shows \n",
    "* count\n",
    "* mean\n",
    "* standard deviation \n",
    "* minimum and maximum, and\n",
    "* the percentiles, by default, the 25th, 50th, and 75th, \n",
    "for all the values in each column or series. This is already shown in the homework in week 2. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try this\n",
    "df.describe()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden"
   },
   "source": [
    "You can see that not all columns are included in the table. This is because by default it will show only numerical columns. That said, `.describe()`has an option called `include`. You can investigate that to see which one suits you. For example, \n",
    "* To see all columns, use `include='all'`, \n",
    "* To see all other columns, use `include=[object]`, \n",
    "* To see all categorical columns, use `include=['category']`, \n",
    "* The default option uses `include=[np.number]`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Exercise:__ Identify the statistical information using the `describe()` as in your week 2 homework. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we wanted to select the data from a particular column, we use the syntax learnt from dictionaries. For example, to select `'Spin'` we write "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "df['Spin']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More often, we don't need all rows but relevant ones. This means we select the data based on a criteria. To do this we "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df[df['Spin'] > 0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# We can see their difference by finding their number of rows. \n",
    "df['Spin'].size()\n",
    "df[df['Spin'] > 0].size()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we wish to select some of the records (rows), we could slice the rows. This can be done by "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Type</th>\n",
       "      <th>Generation</th>\n",
       "      <th>Spin</th>\n",
       "      <th>Charge</th>\n",
       "      <th>Mass</th>\n",
       "      <th>Interaction</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>-0.33</td>\n",
       "      <td>4.6</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.67</td>\n",
       "      <td>1280.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>-0.33</td>\n",
       "      <td>96.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>3.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.67</td>\n",
       "      <td>173100.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>Quarks</td>\n",
       "      <td>3.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>-0.33</td>\n",
       "      <td>4180.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     Type  Generation  Spin  Charge      Mass Interaction\n",
       "1  Quarks         1.0   0.5   -0.33       4.6         NaN\n",
       "2  Quarks         2.0   0.5    0.67    1280.0         NaN\n",
       "3  Quarks         2.0   0.5   -0.33      96.0         NaN\n",
       "4  Quarks         3.0   0.5    0.67  173100.0         NaN\n",
       "5  Quarks         3.0   0.5   -0.33    4180.0         NaN"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Try yourself, change the number of rows to be selected \n",
    "df[1: 6]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Remember data frame index starts at $0$. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Furthermore, if we wish to select a subset of columns, we could do the following "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "df[1: 6, ['Type', 'Charge']]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we wanted to select multiple columns, we use double square brakets to do that. For example, if you wanted to see the type and the charge of the particle. You can write "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try this\n",
    "df[['Type', 'Charge']]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Group Data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Often we will need to see the aggregated results from grouped data. This is done by the `.groupby()` method. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try this\n",
    "grouped_df = df.groupby(by=['Type'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What will happen? Can you explain that? Run the following code will help you. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Generation</th>\n",
       "      <th>Spin</th>\n",
       "      <th>Charge</th>\n",
       "      <th>Mass</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Type</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Bosons</th>\n",
       "      <td>NaN</td>\n",
       "      <td>1.0</td>\n",
       "      <td>-0.166667</td>\n",
       "      <td>49.578750</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Leptons</th>\n",
       "      <td>2.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>-0.500000</td>\n",
       "      <td>316.456834</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Quarks</th>\n",
       "      <td>2.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>0.170000</td>\n",
       "      <td>29777.133333</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         Generation  Spin    Charge          Mass\n",
       "Type                                             \n",
       "Bosons          NaN   1.0 -0.166667     49.578750\n",
       "Leptons         2.0   0.5 -0.500000    316.456834\n",
       "Quarks          2.0   0.5  0.170000  29777.133333"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Try this\n",
    "df.groupby(by=['Type']).mean()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Print the descriptions for all columns in `df`, grouped by `'Type'`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "solution": "hidden"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead tr th {\n",
       "        text-align: left;\n",
       "    }\n",
       "\n",
       "    .dataframe thead tr:last-of-type th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr>\n",
       "      <th></th>\n",
       "      <th colspan=\"8\" halign=\"left\">Generation</th>\n",
       "      <th colspan=\"2\" halign=\"left\">Spin</th>\n",
       "      <th>...</th>\n",
       "      <th colspan=\"2\" halign=\"left\">Charge</th>\n",
       "      <th colspan=\"8\" halign=\"left\">Mass</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th></th>\n",
       "      <th>count</th>\n",
       "      <th>mean</th>\n",
       "      <th>std</th>\n",
       "      <th>min</th>\n",
       "      <th>25%</th>\n",
       "      <th>50%</th>\n",
       "      <th>75%</th>\n",
       "      <th>max</th>\n",
       "      <th>count</th>\n",
       "      <th>mean</th>\n",
       "      <th>...</th>\n",
       "      <th>75%</th>\n",
       "      <th>max</th>\n",
       "      <th>count</th>\n",
       "      <th>mean</th>\n",
       "      <th>std</th>\n",
       "      <th>min</th>\n",
       "      <th>25%</th>\n",
       "      <th>50%</th>\n",
       "      <th>75%</th>\n",
       "      <th>max</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Type</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Bosons</th>\n",
       "      <td>0.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>6.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>...</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>6.0</td>\n",
       "      <td>49.578750</td>\n",
       "      <td>56.354953</td>\n",
       "      <td>0.000000</td>\n",
       "      <td>0.00000</td>\n",
       "      <td>40.1925</td>\n",
       "      <td>88.486875</td>\n",
       "      <td>125.90</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Leptons</th>\n",
       "      <td>6.0</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.894427</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.25</td>\n",
       "      <td>2.0</td>\n",
       "      <td>2.75</td>\n",
       "      <td>3.0</td>\n",
       "      <td>6.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>...</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>6.0</td>\n",
       "      <td>316.456834</td>\n",
       "      <td>716.627508</td>\n",
       "      <td>0.000002</td>\n",
       "      <td>0.25525</td>\n",
       "      <td>8.0055</td>\n",
       "      <td>83.150000</td>\n",
       "      <td>1776.86</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Quarks</th>\n",
       "      <td>6.0</td>\n",
       "      <td>2.0</td>\n",
       "      <td>0.894427</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.25</td>\n",
       "      <td>2.0</td>\n",
       "      <td>2.75</td>\n",
       "      <td>3.0</td>\n",
       "      <td>6.0</td>\n",
       "      <td>0.5</td>\n",
       "      <td>...</td>\n",
       "      <td>0.67</td>\n",
       "      <td>0.67</td>\n",
       "      <td>6.0</td>\n",
       "      <td>29777.133333</td>\n",
       "      <td>70231.992745</td>\n",
       "      <td>2.200000</td>\n",
       "      <td>27.45000</td>\n",
       "      <td>688.0000</td>\n",
       "      <td>3455.000000</td>\n",
       "      <td>173100.00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>3 rows × 32 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "        Generation                                            Spin       ...  \\\n",
       "             count mean       std  min   25%  50%   75%  max count mean  ...   \n",
       "Type                                                                     ...   \n",
       "Bosons         0.0  NaN       NaN  NaN   NaN  NaN   NaN  NaN   6.0  1.0  ...   \n",
       "Leptons        6.0  2.0  0.894427  1.0  1.25  2.0  2.75  3.0   6.0  0.5  ...   \n",
       "Quarks         6.0  2.0  0.894427  1.0  1.25  2.0  2.75  3.0   6.0  0.5  ...   \n",
       "\n",
       "        Charge        Mass                                                  \\\n",
       "           75%   max count          mean           std       min       25%   \n",
       "Type                                                                         \n",
       "Bosons    0.00  0.00   6.0     49.578750     56.354953  0.000000   0.00000   \n",
       "Leptons   0.00  0.00   6.0    316.456834    716.627508  0.000002   0.25525   \n",
       "Quarks    0.67  0.67   6.0  29777.133333  70231.992745  2.200000  27.45000   \n",
       "\n",
       "                                           \n",
       "              50%          75%        max  \n",
       "Type                                       \n",
       "Bosons    40.1925    88.486875     125.90  \n",
       "Leptons    8.0055    83.150000    1776.86  \n",
       "Quarks   688.0000  3455.000000  173100.00  \n",
       "\n",
       "[3 rows x 32 columns]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Solution\n",
    "df.groupby(by=['Type']).describe()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Your code below\n",
    "df.groupby(by=['Type'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Manipulate Data Frames"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we start manipulating the data, it is best to remember that everytime __you should create a new column__. It will prevent you from wrecking the data frame in later. To create a new column, we could just assign the formula into a new column name. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this exercise, we crate a sample dataframe. Which is created for you in below: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>a</th>\n",
       "      <th>b</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>2</td>\n",
       "      <td>4</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>3</td>\n",
       "      <td>5</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   a  b\n",
       "0  1  3\n",
       "1  2  4\n",
       "2  3  5"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "df01 = pd.DataFrame({'a': [1, 2, 3], 'b': [3, 4, 5]})\n",
    "df01"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, let's duplicate all values in column `'b'`. To do so, we write "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself, note that the column name was never seen before. \n",
    "df01['b'] = df01['b'] * 2   # Some formulas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once we know how to select the desired data, the next thing we need to know is how to manipulate data. \n",
    "One of the most straightforward things we can do is to operate with columns or rows  using aggregation functions. The following list shows the most common aggregation functions.\n",
    "\n",
    "| Function  | Description | \n",
    "|-----------|-------------|\n",
    "| count()   |Number of non-null observations|  \n",
    "| sum()     |Sum of values|\n",
    "| mean()    |Mean of values            | \n",
    "| median()  |Arithmetic median of values             |\n",
    "| min()     |Minimum|\n",
    "| max()     |Maximum|\n",
    "| prod()    |Product of values|\n",
    "| std()     |Unbiased standard deviation|\n",
    "| var()     | Unbiased variance|\n",
    "\n",
    "The result of all these functions applied to a row or column is always a number. Meanwhile, if a function is applied to a data frame or a selection of rows and columns, then you can specify if the function should be applied to the rows for each column  (putting the **axis=0** keyword on the invocation of the function), or it should be applied on the columns for each row (putting the **axis=1** keyword on the invocation of the function)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Run this\n",
    "df01.max(axis=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that these are functions specific to Pandas, not the generic Python functions. There are differences in their implementation. In Python ,`NaN` values propagate through all operations without raising an exception. In contrast, Pandas operations exclude `NaN` values representing missing data. For example, the pandas **max** function excludes `NaN`  values, thus they are interpreted as missing values, while the standard Python **max** function will take the mathematical interpretation of `NaN` and return it as the maximum:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Run this\n",
    "print('Pandas max function:', df01['b'].max())\n",
    "print('Python max function:', max(df01['b']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "We can also apply mathematical operators into data frames. This will apply the elementary operations. For example, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Run this\n",
    "df01['a'] = df01['a']/2\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Add or Remove Columns or Rows"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we wanted to add a new column, we simply define a new column as like in dictionaries. For example, to add a new column `'c'` we write: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run this\n",
    "df01['c'] = [6, 7, 8]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we wish to remove a row/ column, we use `.drop()` method. This removes the indicated rows if `axis=0`, or the indicated columns if `axis=1`. \n",
    "```python\n",
    "# Remove column `'c'`, remember to add `axis=1`\n",
    "df.drop(['c'], axis=1)\n",
    "\n",
    "# Remove 0-th row\n",
    "df.drop([0], axis=0)\n",
    "```\n",
    "\n",
    "At this point, we are not going to remove any rows as they are for the next exercise. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we wish to append a row, we could use the `.append()` method. Note that Python will copy the data frame each time, it means this method is not as efficient. You must be aware to setting the `ignore_index` flag in the append method to `True`, otherwise the index `0` is given to this new row, what will produce an error if it already exists. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ The elementary particles dataset does not include the name of the particles. Use your research and find out which row belongs to what particles. Create a column called `'Name'` for `df`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "df['Name'] = ['Up', 'Down', 'Charm', 'Strange', 'Top', 'Bottom', 'Electron', 'Electron neutrino', 'Muon', 'Muon neutrino', 'Tau', 'Tau neutrino', 'Photon', 'W boson', 'Z boson', 'Gluon', 'Higgs boson', 'Graviton']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Looping in Data Frames"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each rows in data frames are called `Series` object. Often when we are iterating with objects, it is faster (for computers) to use the `.apply()` method to loop over them. This can be done by "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself.\n",
    "import numpy as np\n",
    "df['c'].apply(np.sqrt)\n",
    "df['c'].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To apply more complicated functions, can also use lambda functions in `.apply()`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "df['a'].apply(lambda x: 2*x)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also manipulate multiple columns to obtain new data. In this case, we are creating a column `'d'` and it is the element-wise division of columns `'a'` and `'c'`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "df['d'] = df['a']/df['c']\n",
    "df['d'].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Apply in Data Frame Elements (Optional)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Remember last week we talked about `map()` and `reduce()`? In `pandas` data frames, they offer `apply()` method which acts like the `map()` function. First we initiate a new data frame. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "df = pd.DataFrame({\"A\": [1, 2, 3, 4, 5]})\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, we double the values and use `.apply()` for that. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.apply(lambda x: 2 * x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For functions like `reduce()` we can use the native methods from `numpy`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "df.apply(np.sum)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How about the filter function? This is already covered when we try to condition from columns. This is one convenient functions that `pandas` data frame can offer. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a note, these functions including lambda functions are not restricted to numerical computations. We can use string functions/ methods and apply to string elements. `.apply()` is very useful when comes to complex computations. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this course, we have looked at importing `numpy`. `numpy` contains many useful functions that helped us in computing efficiently. Import is an important part of coding, it saves our time in writing functions and use someone else's. In the following we will use the `math` package. To import `math`, we can write "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "import math"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us test the package, to find square root $2$ we can write "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "print(math.sqrt(2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we need to use the `sqrt()` function often, we can use the following to save time. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself\n",
    "from math import sqrt\n",
    "sqrt(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While import does not limit to built in libraries. We can create our own modules. To do this, it is best to create the modules in the folder in or below our current directory. __Secondly,__ the folder that contains the packages will have an (empty) file called `__init__.py`. \n",
    "\n",
    "Once this has been done, we can import the modules by specifying where it is located. The folder/ file path is what we called as the __package__. For example, our class files has the following folder structure: \n",
    "\n",
    "```\n",
    "...\n",
    "|_ Week 8.ipynb\n",
    "|_ modules\n",
    "  |_ __init__.py\n",
    "  |_ sample_module.py\n",
    "```\n",
    "Let us assume a predfined function was located in the module `sample_module.py`, we can write \n",
    "```python\n",
    "from modules import sample_module\n",
    "```\n",
    "So when we call the functions `sample_module.py`, we do not require to write the file name again. To see this, let us say there is a function called `get_beautiful_picture()` in `sample_module.py`. We can say \n",
    "```python \n",
    "get_beautiful_picture()\n",
    "```\n",
    "without specifying where it comes from. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Write a function `get_success()` in a module file called `week08.py`. The Python code will be stored in the `module` folder. \n",
    "\n",
    "Your function `get_success()` will print `'Good job!'` when prompted below. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "solution": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "import week08\n",
    "print(get_success())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# If your code is successful, you will see the message. Write the code below. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Handling Exceptions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By properly handle exception well, you will able to prevent your program ended unexceptedly. This is important when running the code, while before writing the data files, you will wish the code still runs. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "ename": "ZeroDivisionError",
     "evalue": "division by zero",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mZeroDivisionError\u001b[0m                         Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-3-6f83451070fb>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0mdivisor\u001b[0m \u001b[1;33m=\u001b[0m \u001b[1;36m0\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m----> 3\u001b[0;31m \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;36m22\u001b[0m\u001b[1;33m/\u001b[0m\u001b[1;36m0\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      4\u001b[0m \u001b[0mnumber\u001b[0m \u001b[1;33m=\u001b[0m \u001b[1;36m22\u001b[0m\u001b[1;33m/\u001b[0m\u001b[0mdivisor\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m'The number is {}'\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mformat\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mnumber\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mZeroDivisionError\u001b[0m: division by zero"
     ]
    }
   ],
   "source": [
    "divisor = 0\n",
    "\n",
    "print(22/0)\n",
    "number = 22/divisor\n",
    "print('The number is {}'.format(number))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "To handle the `ZeroDivisionError`, we use the `try` block for our main code. This is the syntax of such. \n",
    "```python\n",
    "try: \n",
    "    pass  # Your main code\n",
    "except ZeroDivisionError:\n",
    "    print('Oh no!')\n",
    "```\n",
    "Let us try to use this as in below. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The number is 0\n"
     ]
    }
   ],
   "source": [
    "# Try yourself\n",
    "try: \n",
    "    divisor = 0\n",
    "    number = 22/divisor\n",
    "    print('The number is {}'.format(number))\n",
    "except ZeroDivisionError:\n",
    "    number = 0\n",
    "    print('The number is {}'.format(number))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "We can put `finally` to show after the exception has been show. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The number is 0\n"
     ]
    }
   ],
   "source": [
    "try: \n",
    "    divisor = 0\n",
    "    number = 22/divisor\n",
    "except ZeroDivisionError:\n",
    "    number = 0\n",
    "finally: \n",
    "    print('The number is {}'.format(number))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "As you can see, the code will capture the exception and do something while in the `try` block. So __make sure you use `try` statement when you are expecting an exception will be raised.__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Raise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes we would like to prevent incorrect data continue to be computed in a code. So we will need to raise an exception in order to let it continue. To do this we use the `raise` keyword. For example, if we wish to let the code head to `ZeroDivisionError` earlier, we could write \n",
    "```python\n",
    "if condition: \n",
    "    raise ZeroDivisionError\n",
    "```\n",
    "Provide that the condition has occured, so that we need to raise the exception. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Write the code which performs the division as above. This time, define a dividor which is what the number will be divided with. Raise the `ZeroDivisionError` at suitable place. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "try: \n",
    "    a = 22\n",
    "    b = 0\n",
    "    if b == 0: \n",
    "        raise ZeroDivisionError\n",
    "    num = a/b\n",
    "except ZeroDivisionError: \n",
    "    number = 0\n",
    "finally: \n",
    "    print('The number is {}'.format(number))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Try and Else"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "In the situation that your code will not run into an exception, the `else` block will run. For example, let us come back to the division example. We can write "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try yourself \n",
    "try: \n",
    "    divisor = 0\n",
    "    number = 22/divisor\n",
    "except ZeroDivisionError:\n",
    "    number = 0\n",
    "else: \n",
    "    print('The number is {}'.format(number))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "So in above, change the numbers for example: \n",
    "* a $0$, or\n",
    "* not $0$\n",
    "\n",
    "and note the outcome. What is different when we did not use `finally`? "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Continue from Exceptions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One reason to handle exceptions is when it occurs, we would want the code to still run. To do that we need: \n",
    "* `while` (or `for`) loop\n",
    "* breaking condition\n",
    "* the `continue` keyword \n",
    "\n",
    "We can see this in the following. Let us say we would like to test some of the input files, and some of them will raise `ValueError`. \n",
    "```python\n",
    "inputs = [...]  # The contents in a list. \n",
    "for i in range(len(input)): \n",
    "    try: \n",
    "        print('This person has the opinion of {}'.format(input[i]))\n",
    "    except ValueError: \n",
    "        continue\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will do an exercise of this later. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### TypeError and ValueError"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "In handling errors, the most common exceptions you will see are `TypeError` and `ValueError`. \n",
    "* `ValueError` means the function does not accept this value. \n",
    "* `TypeError` means the function obtained an incorrect type. \n",
    "\n",
    "Let us see from the examples below, try running the cells. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try this \n",
    "from math import sqrt\n",
    "sqrt(-55)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Try this\n",
    "sum(-55)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "From the first example, it not possible to square root a negative number. You can try by multiplying $2$ negative numbers and they will still become a positive number. While in the latter example, the `sum()` function expects a list in order to perform a summation. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "solution": "hidden",
    "solution_first": true
   },
   "source": [
    "__Exercise:__ Write a code that accepts a list of names. If the name given starts with `'A'`, then raise a suitable error. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "solution": "hidden"
   },
   "outputs": [],
   "source": [
    "# Solution\n",
    "for i in range(len(ls)): \n",
    "    try: \n",
    "        if ls[i][0] == 'A': \n",
    "            raise ValueError\n",
    "    except ValueError: \n",
    "        break"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Your code below\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conclusion"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the week, we have looked at \n",
    "* How to read and write files\n",
    "* How to use `pandas`\n",
    "* How to handle exceptions\n",
    "\n",
    "Some of the texts are sourced from `github.com/DataScienceUB/introduction-datascience-python-book`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Further Reading\n",
    "\n",
    "* [https://stackoverflow.com/questions/4383571/importing-files-from-different-folder](https://stackoverflow.com/questions/4383571/importing-files-from-different-folder)\n",
    "* [https://docs.python.org/3/library/exceptions.html](https://docs.python.org/3/library/exceptions.html)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.12"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": true,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}