OOP_001_More_About_Classes.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://www.hydroffice.org/epom/\"><img src=\"images/000_000_epom_logo.png\" alt=\"ePOM\" title=\"Open ePOM home page\" align=\"center\" width=\"12%\" alt=\"Python logo\\\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://piazza.com/class/jtn9igrguw476h\"><img src=\"images/help.png\" alt=\"ePOM\" title=\"Ask questions on Piazza.com\" align=\"right\" width=\"10%\" alt=\"Piazza.com\\\"></a>\n",
    "# More About Classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Python `class` has all the standard features required for [object-oriented programming (OOP)](https://en.wikipedia.org/wiki/Object-oriented_programming)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "These standard features are:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The presence of a [class inheritance mechanism](https://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming)). (Multiple base classes are allowed.)\n",
    "* The property that a derived class can [override any methods](https://en.wikipedia.org/wiki/Method_overriding) of its base class. \n",
    "* The possibility for a method to call the method of a base class with the same function name. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An in-depth explanation of the above features is outside of the scope of this course. However, after this notebook, you will know how to add methods to a `class` in Python. The acquired notions should provide you with a good base to allow you to continue the learning process about OOP on your own."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But first, please execute the following code, for the same reasons explained at the beginning of the previous notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "\n",
    "import sys\n",
    "import os\n",
    "\n",
    "sys.path.append(os.getcwd())  # add the current folder to the list of paths where Python looks for modules "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Class Interface"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we have seen in the [past notebook](OOP_000_First_Steps_of_a_Class.ipynb), objects may contain data as **class attributes**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The values of all the class attributes characterize the **class state**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although you can directly modify the class attributes (and, thus, the class state), the proper way to proceed is to define the so-called **class interface**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The **class interface** is represented by the set of the available methods for a class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What is the advantage of designing and maintaining a **class interface**? \n",
    "\n",
    "You can change the internal implementation (e.g., some attributes) without having to change the interface. This means that other parts of your program do **not** have to change to accommodate those changes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding a `read(self)` Method"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a first step to build a class interface, we will create a `read(self)` method. \n",
    "\n",
    "This method will perform similar operations to what was described in the [Read and Write Text Files notebook](../python_basics/006_Read_and_Write_Text_Files), but using the internal class attributes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click on [this link](data/tide.txt) to visualize the content of the `tide.txt` file. As you can notice following the link, there are no metadata contained within the file. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each row has the following seven fields:\n",
    "\n",
    "| Index | Field |\n",
    "| ----- | ----- |\n",
    "|   0   | Year        |\n",
    "|   1   | [Ordinal Day](https://en.wikipedia.org/wiki/Ordinal_date)|\n",
    "|   2   | Hours       |\n",
    "|   3   | Minutes     |\n",
    "|   4   | Seconds     |\n",
    "|   5   | POSIX Time  |\n",
    "|   6   | Water Level |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As such, each row in the data file represents a record with a specific time and date, and an associated water level observation in meters. The time for each record is represented in two ways: \n",
    "\n",
    "* By a combination of the year, ordinal day (aka, year-day), hour and minute (as integer values) and seconds (as float values). \n",
    "* The [POSIX time](https://en.wikipedia.org/wiki/Unix_time) in seconds (as float value)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "**POSIX time** (alternatively **Unix time** or **Unix Epoch time**) is the number of elapsed seconds since  midnight January 1, 1970 UTC."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since POSIX time is independent of the time zone in which the data is collected, a time is represented by a single number, thereby simplifying math involving time spans."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the `read(self)` method, we will only use two fields for each row in the data file: the POSIX time and the water level."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `datetime` class has a method named `fromtimestamp` to convert POSIX time to a Python `datetime` object. As described in the [documentation](https://docs.python.org/3.6/library/datetime.html#datetime.datetime.fromtimestamp), we need to specify the [timezone](https://en.wikipedia.org/wiki/Time_zone) (i.e., UTC) otherwise the method will default to the platform's local date and time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code uses the `fromtimestamp` method with 0 seconds, thus the expected printed date should be January 1, 1970 and the time 00:00:00 UTC. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime, timezone\n",
    "\n",
    "zero_timestamp = datetime.fromtimestamp(0, timezone.utc)\n",
    "print(zero_timestamp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Extend the `WaterLevel` class in the `waterlevel.py` file with a `read(self)` that reads and stores two fields for each row in the data file: the UTC time (converted from the POSIX time) and the water level.\n",
    "<br><br>\n",
    "*The solution code imports the `WaterLevel` class from the `waterlevel_read` module located in the `solutions` folder.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "from solutions.waterlevel_read import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"tide.txt\")  # the 'tide.txt' file is located under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "wl.read()\n",
    "print(wl)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mycode.waterlevel import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"tide.txt\")  # the 'tide.txt' file is located under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "wl.read()\n",
    "print(wl)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the printed output from the above code, you should read `count: 3141` since the data file contains 3,141 records of water level. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px; padding-top:10px;\" src=\"images/refs.png\">\n",
    "\n",
    "## Useful References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Introduction to Ocean Data Science - Object-Oriented Programming slides](https://bitbucket.org/hydroffice/hyo_epom/downloads/ePOM.Intro_to_Ocean_Data_Science.Object_Oriented_Programming.pdf)\n",
    "* [The official Python 3.6 documentation](https://docs.python.org/3.6/index.html)\n",
    "  * [Classes](https://docs.python.org/3.6/tutorial/classes.html)\n",
    "* [Object-oriented Programming](https://en.wikipedia.org/wiki/Object-oriented_programming)\n",
    "* [POSIX time](https://en.wikipedia.org/wiki/Unix_time)\n",
    "* [Time zone](https://en.wikipedia.org/wiki/Time_zone)\n",
    "* [Programming Basics with Python](https://github.com/hydroffice/python_basics)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"5%\" style=\"padding-right:10px;\" src=\"images/email.png\">\n",
    "\n",
    "*For issues or suggestions related to this notebook, write to: epom@ccom.unh.edu*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "[< First Steps of a Class](OOP_000_First_Steps_of_a_Class.ipynb) | [Contents](index.ipynb) |"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}