improvements after Roxy comments

Author: giumas

OOP_000_First_Steps_of_a_Class.ipynb

@@ -19,7 +19,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "[Object-Oriented Programming (OOP)](https://en.wikipedia.org/wiki/Object-oriented_programming) is a powerful approach on how to organize code for short programs (scripts), libraries, and applications."
+    "[Object-Oriented Programming (OOP)](https://en.wikipedia.org/wiki/Object-oriented_programming) is a powerful and popular approach adopted to organize code for short programs (scripts), libraries, and applications."
    ]
   },
   {
@@ -31,29 +31,63 @@
     "OOP is based on the concept of **objects**. An object is an instance of a **class**. A class is used to define all the required data structures as well as the functions (**methods**) that can be applied to the class data."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![Class and Object](images/OOP_000_000_class_and_object.png)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "In the [*A Class as a Data Container*](../python_basics/008_A_Class_as_a_Data_Container.ipynb) notebook, you have already learned how to create your own type using a **class** as a data container. This notebook will describe how to extend a data container class with methods."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
+    "\n",
+    "To review the concept of type in Python, read the [*Variable and Types*](../python_basics/001_Variables_and_Types.ipynb#Dynamic-Nature-of-a-Variable-Type) notebook."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
     "\n",
-    "Differently from [*Programming Basics for Python* notebooks](https://github.com/hydroffice/python_basics), you will be asked to write your OOP code in separated `.py` files, each of them containing the definition of a single class. "
+    "You will be asked to write your OOP code in separated `.py` files, each of them represents a Python module containing the class definition. \n",
+    "**This is different from the approach adopted in [*Programming Basics for Python* notebooks](https://github.com/hydroffice/python_basics) where all the code is written in the notebook itself!**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The adopted approach imports the class code contained in modules, and then creates instances of such a class in the body of this notebook (and in the following ones)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
+    "\n",
+    "To review the concept of module in Python, read the [*Read and Write Text Files*](../python_basics/006_Read_and_Write_Text_Files.ipynb#Read-and-Write-Text-Files) notebook."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Then, in the body of this notebook (and in the following ones), you will just import such a code and create instances of such classes.\n",
+    "The following code cell performs two preliminary **required** operations:\n",
     "\n",
-    "To avoid to have to manually reload the classes when new changes are applied, we will execute the following code cell to use the `autoreload` extension that automatically reloads module before executing the code. The code cell then instructs Python to look in the `code` folder for local Python modules."
+    "* Load the `autoreload` [extension](https://jupyter-notebook.readthedocs.io/en/stable/extending/) to avoid to have to manually reload the classes when changes are applied. \n",
+    "* Instruct Python (using `sys.path.append()`) to look in the `code` folder for local Python modules."
    ]
   },
   {
@@ -106,6 +140,7 @@
     "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
     "\n",
     "Modify the empty `waterlevel.py` file located in the `mycode` folder to successfully execute the following code.\n",
+    "<br><br>\n",
     "*The solution code imports the `WaterLevel` class from the `waterlevel_definition` module located in the `solutions` folder.*"
    ]
   },
@@ -146,7 +181,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We now add a few attributes to the previously defined `WaterLevel` class:\n",
+    "We can now add a few attributes to the previously defined `WaterLevel` class:\n",
     "\n",
     "* Two lists (named `epochs` and `water_levels`, respectively)\n",
     "* A `metadata` dictionary with the following pairs of key and value:\n",
@@ -166,6 +201,7 @@
     "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
     "\n",
     "Extend the `WaterLevel` class in the `waterlevel.py` file (located in the `mycode` folder) to successfully execute the following code.\n",
+    "<br><br>\n",
     "*The solution code imports the `WaterLevel` class from the `waterlevel_attributes` module located in the `solutions` folder.*"
    ]
   },
@@ -221,6 +257,7 @@
     "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
     "\n",
     "Extend the `WaterLevel` class in the `waterlevel.py` file to be able to take a `data_path` parameter for the location of the data file.\n",
+    "<br><br>\n",
     "*The solution code imports the `WaterLevel` class from the `waterlevel_initialization` module located in the `solutions` folder.*"
    ]
   },
@@ -287,6 +324,7 @@
     "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
     "\n",
     "Extend the `__init__` method in the `WaterLevel` class in the `waterlevel.py` file to throw a meaningful error when the passed `data_path` does not actually exist.\n",
+    "<br><br>\n",
     "*The solution code imports the `WaterLevel` class from the `waterlevel_initialization_check` module located in the `solutions` folder.*"
    ]
   },
@@ -388,24 +426,17 @@
     "<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 `__str__(self)` method that returns a `str` with some meaningful information about the status of the object.\n",
+    "<br><br>\n",
     "*The solution code imports the `WaterLevel` class from the `waterlevel_str` module located in the `solutions` folder.*"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": null,
    "metadata": {
     "solution2": "hidden"
    },
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "WaterLevel[count: 0, path: C:\\code\\hyo2\\epom\\ocean_data_science\\data\\tide.txt]\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "from solutions.waterlevel_str import WaterLevel\n",
     "import os\n",
@@ -435,7 +466,7 @@
    "source": [
     "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
     "\n",
-    "There are not fixed rules of what to return as `str`. The only requirement is to be a **nicely printable representation** of an object."
+    "There are not fixed rules of what to return as `str`. Based on the official Python documentation, the only requirement is that it should be an [*\"informal or nicely printable string representation of an object\"*](https://docs.python.org/3.6/library/stdtypes.html#str)."
    ]
   },
   {

OOP_001_More_About_Classes.ipynb

@@ -37,21 +37,21 @@
    "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 name. "
+    "* 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 continue the learning process about OOP on your own."
+    "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 reasons explained in the previous notebook."
+    "But first, please execute the following code, for the smae reasons explained at the beginning of the previous notebook."
    ]
   },
   {
@@ -128,7 +128,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As first example of an interface method, we will add a `read(self)`. \n",
+    "As a first example of an interface method, we will add a `read(self)`. \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."
    ]
@@ -153,15 +153,15 @@
     "|   2   | Hours       |\n",
     "|   3   | Minutes     |\n",
     "|   4   | Seconds     |\n",
-    "|   5   | Epoch       |\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 (epoch), and an associated water level observation in meters. The epoch for each record is represented two times: \n",
+    "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)."
@@ -180,7 +180,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Since POSIX time is independent of the time zone in which the data is collected, an epoch is represented by a single number, thereby simplifying math involving time spans."
+    "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."
    ]
   },
   {
@@ -226,6 +226,7 @@
     "<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 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.*"
    ]
   },
@@ -291,6 +292,8 @@
     "* [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)"
    ]
   },

images/OOP_000_000_class_and_object.png

@@ -18,21 +18,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Ocean [data science](https://en.wikipedia.org/wiki/Data_science) is a broad and interdisciplinary subject that requires statistical/modeling knowledge and computer science skills, coupled with domain-specific expertise. "
+    "Ocean [data science](https://en.wikipedia.org/wiki/Data_science) is a broad and interdisciplinary topic that requires statistical and modeling knowledge as well as computer science skills, coupled with domain-specific expertise. "
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As you can imagine, it would be a long and overwhelming goal to cover all the aspects involved in the subject, and there will be very likely many duplications with other courses. The aim of the [*Foundations of Ocean Data Science* notebooks](https://github.com/hydroffice/ocean_data_science) is instead to teach you a selected number of basic concepts in ocean data science and to introduce some popular Python libraries related to the subject, to prepare you to the assignments for those other courses as well as to conduct your own research. "
+    "As you can imagine, it would be an overwhelming goal to cover all the aspects of ocean data science, and there will likely be many cross-overs with material covered in other courses. The [*Foundations of Ocean Data Science* notebooks](https://github.com/hydroffice/ocean_data_science) will only teach you a selected number of basic concepts in ocean data science and will introduce some popular Python libraries related to the subject. This will help you to prepare you for coming assignments (for this and other courses) and your own research. "
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The notebooks assume the level of Python knowledge described in [*Programming Basics for Python* notebooks](https://github.com/hydroffice/python_basics). If you are not familiar with these latter notebooks, you should start from [Programming Basics with Python - Quick Start](https://www.hydroffice.org/manuals/epom/python_basics_quickstart.html)."
+    "The notebooks assume some level of Python knowledge. Mainly, you need the concepts introduced in the [*Programming Basics for Python* notebooks](https://github.com/hydroffice/python_basics). If you are not familiar with these earlier notebooks, you should start from [Programming Basics with Python - Quick Start](https://www.hydroffice.org/manuals/epom/python_basics_quickstart.html)."
    ]
   },
   {

images/resources/resources.pptx

@@ -3,8 +3,8 @@ class WaterLevel:
 
     def __init__(self):  # new method
 
-        self.epochs = list()
+        self.times = list()
         self.water_levels = list()
         self.metadata = dict()
         self.metadata["units"] = "m"
-        self.metadata["count"] = 0
+        self.metadata["count"] = 0

index.ipynb

@@ -2,9 +2,9 @@ class WaterLevel:
     """A Class for Water Level Data"""
 
     def __init__(self, data_path):  # new code
-
+        
         self.data_path = data_path  # new code
-        self.epochs = list()
+        self.times = list()
         self.water_levels = list()
         self.metadata = dict()
         self.metadata["units"] = "m"

solutions/waterlevel_attributes.py

@@ -7,10 +7,10 @@ class WaterLevel:
     def __init__(self, data_path):
 
         if not os.path.exists(data_path):  # new code
-             raise RuntimeError('Unable to locate the data file: %s' % data_path)  # new code
+            raise RuntimeError('Unable to locate the data file: %s' % data_path)  # new code
 
         self.data_path = data_path
-        self.epochs = list()
+        self.times = list()
         self.water_levels = list()
         self.metadata = dict()
         self.metadata["units"] = "m"

solutions/waterlevel_initialization.py

@@ -8,10 +8,10 @@ class WaterLevel:
     def __init__(self, data_path):
 
         if not os.path.exists(data_path):
-             raise RuntimeError('Unable to locate the data file: %s' % data_path)   
+            raise RuntimeError('Unable to locate the data file: %s' % data_path)   
 
         self.data_path = data_path
-        self.epochs = list()
+        self.times = list()
         self.water_levels = list()
         self.metadata = dict()
         self.metadata["uom"] = "m"
@@ -34,8 +34,8 @@ def read(self):
         count = 0  # initialize the counter for the number of rows read
         for wl_line in wl_lines:
             observations = wl_line.split()  # Tokenize the string
-            epoch = datetime.fromtimestamp(float(observations[5]), timezone.utc)
-            self.epochs.append(epoch)
+            time = datetime.fromtimestamp(float(observations[5]), timezone.utc)
+            self.times.append(time)
             self.water_levels.append(float(observations[6]))
             count += 1
         self.metadata["count"] = count

solutions/waterlevel_initialization_check.py

@@ -10,7 +10,7 @@ def __init__(self, data_path):
             raise RuntimeError('Unable to locate the data file: %s' % data_path)   
 
         self.data_path = data_path
-        self.epochs = list()
+        self.times = list()
         self.water_levels = list()
         self.metadata = dict()
         self.metadata["uom"] = "m"