008_A_Class_as_a_Data_Container.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/js5dnu0q39n6qe\"><img src=\"images/help.png\" alt=\"ePOM\" title=\"Ask questions on Piazza.com\" align=\"right\" width=\"10%\" alt=\"Piazza.com\\\"></a>\n",
    "# A Class as a Data Container"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You encountered several data types. Sometimes you may need a custom type. So it is time to learn how to define your own data type! "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Creating your own data type is a bit more complicated than writing functions, but it comes with big advantages that soon will be apparent."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A user-defined type is called a **class**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We used several built-in types (e.g., `int`, `str`, `list`), thus you should already have some familiarity with the concepts that we are going to introduce. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A class provides a powerful means of bundling data and functionalities together."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook will **only** use a class as a data container. And you will learn by example.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Class Definition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We want to create a class that is able to hold the content of the `sal.txt` file cited in a [previous notebook](006_Read_and_Write_Text_Files.ipynb). We will give this class the meaningful name of `SalinityData`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is what we need to define such a class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SalinityData:\n",
    "    \"\"\"A class for salinity data\"\"\"  # In Python, this is a special string named 'docstring'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first line of the above code contains: the `class` keyword, the class name (`SalinityData`), and  a `:`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second line is a special descriptive text, called `docstring`, that provides a brief explanation about the class. The description is between `\"\"\" \"\"\"` (i.e., triple quotes)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A class definition always starts with the `class` keyword. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once defined, we can create an object (**instance**) of the `SalinityData` class, by calling it with `()` at the end:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sal_data = SalinityData()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A **class** is a **factory** for creating new instances of a given type."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "**Class instances** are commonly called **objects**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "type(sal_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because the `SalinityData` class is defined in this notebook, the full name of the type is `__main__.SalinityData`. At this stage of learning Python, you can safely ignore the `__main__.` part."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the moment, this newly defined class is not that exciting. We will soon start to populate it with a number of useful **attributes** and **methods**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The **class attributes** are variables that capture all the information describing the class. Thus, **class attributes** maintain the **state** of each class instance. The **class methods** may modify the attributes and thus its state."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The **class methods** definition must **always** have `self` as first parameter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Class Initialization and Attributes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The **class initialization** is done by a special method called `__init__(self)`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you don't provide a `__init__(self)` method (like in the code below), Python will create one for you behind the scenes (**implicitly**)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the `__init__(self)` method, you should declare all the **class attributes**. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "A **class attribute** is a variable that will be present in each object instantiated from a given class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SalinityData:\n",
    "    \"\"\"A class for salinity data\"\"\"\n",
    "    \n",
    "    def __init__(self):\n",
    "        self.metadata = dict()\n",
    "        self.sal_values = list()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above code, we declared that the class has:\n",
    "\n",
    "* An attribute named `metadata` that will be initialized as an empty dictionary (see [How to create and populate a dict ](007_Dictionaries_and_Metadata.ipynb#How-to-create-and-populate-a-dict)).\n",
    "* An attribute named `sal_values` that will be initialized as an empty list (see [Creation of a List: Approach #2](002_Lists_of_Variables.ipynb#Creation-of-a-List:-Approach-#2))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can access the class attributes by using the `.` operator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sal_data = SalinityData()\n",
    "print(\"Salinity values: %s\" % (sal_data.sal_values))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above code prints the list content as `[]`. This is not surprising since an empty list was created in the `__init__(self)` method."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "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",
    "Write a `TemperatureData` class definition similar to the above `SalinityData`. Then, create an instance of that class and print the temperature values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "class TemperatureData:\n",
    "    \"\"\"A class for temperature data\"\"\"\n",
    "    \n",
    "    def __init__(self):\n",
    "        self.metadata = dict()\n",
    "        self.temp_values = list()\n",
    "    \n",
    "temp_data = TemperatureData()\n",
    "print(\"Temperature values: %s\" % (temp_data.temp_values, ))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is much more that you can do with a class, but this is the amount of information that you need to complete this *Programming Basics with Python* training. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "If you are interested in learning more about classes, you may want to explore the [Introduction to Ocean Data Science](https://www.hydroffice.org/manuals/epom/ocean_data_science_quickstart.html) notebooks."
   ]
  },
  {
   "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": [
    "* [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",
    "* [Foundations of Ocean Data Science](https://www.hydroffice.org/manuals/epom/foundations_of_ocean_data_science.html)"
   ]
  },
  {
   "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",
    "[< Dictionaries and Metadata](007_Dictionaries_and_Metadata.ipynb) | [Contents](index.ipynb) | [Summing-Up >](009_Summing-Up.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
}