From c97970a88e0e0f82b16d15da20771ad9bb2b9f16 Mon Sep 17 00:00:00 2001
From: Robert Lanzafame <R.C.Lanzafame@tudelft.nl>
Date: Sat, 8 Jun 2024 08:17:27 +0200
Subject: [PATCH] delete files from add-numpy-reference branch
---
book/programming/code/numpy_0.ipynb | 599 -----------
book/programming/code/numpy_1.ipynb | 531 ----------
book/programming/code/numpy_2.ipynb | 456 ---------
book/programming/code/numpy_3.ipynb | 234 -----
book/programming/code/numpy_files/arr.npy | Bin 216 -> 0 bytes
.../code/numpy_files/barcharts.png | Bin 54693 -> 0 bytes
.../code/numpy_files/example_data.csv | 10 -
.../code/numpy_files/example_data.txt | 10 -
.../code/numpy_files/plotting_functions.py | 18 -
.../code/numpy_files/taxi_duration.txt | 182 ----
.../python_topics/classes_solution.ipynb | 961 ------------------
.../python_topics/modules_solution.ipynb | 565 ----------
12 files changed, 3566 deletions(-)
delete mode 100644 book/programming/code/numpy_0.ipynb
delete mode 100644 book/programming/code/numpy_1.ipynb
delete mode 100644 book/programming/code/numpy_2.ipynb
delete mode 100644 book/programming/code/numpy_3.ipynb
delete mode 100644 book/programming/code/numpy_files/arr.npy
delete mode 100644 book/programming/code/numpy_files/barcharts.png
delete mode 100644 book/programming/code/numpy_files/example_data.csv
delete mode 100644 book/programming/code/numpy_files/example_data.txt
delete mode 100644 book/programming/code/numpy_files/plotting_functions.py
delete mode 100644 book/programming/code/numpy_files/taxi_duration.txt
delete mode 100644 book/programming/python_topics/classes_solution.ipynb
delete mode 100644 book/programming/python_topics/modules_solution.ipynb
diff --git a/book/programming/code/numpy_0.ipynb b/book/programming/code/numpy_0.ipynb
deleted file mode 100644
index c4b24910..00000000
--- a/book/programming/code/numpy_0.ipynb
+++ /dev/null
@@ -1,599 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Numpy: How it Works\n",
- "\n",
- "Introduction\n",
- "\n",
- "[theory](https://tudelft-citg.github.io/learn-python/05/Theory/01.html)\n",
- "[quick reference](https://tudelft-citg.github.io/learn-python/05/In_a_Nutshell/01.html)\n",
- "\n",
- "Exercises: [airpplane velocity](https://tudelft-citg.github.io/learn-python/05/Exercises/01.html) and [bending moment](https://tudelft-citg.github.io/learn-python/05/Exercises/02.html)."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "This notebook is based on the Numpy lesson from [Aalto Scientific Computing: Python for Scientific Computing](https://github.com/AaltoSciComp/python-for-scicomp/) and [W3Schools](https://www.w3schools.com/python/numpy/)."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "tags": []
- },
- "source": [
- "## See also\n",
- "\n",
- "\n",
- "* NumPy manual <https://numpy.org/doc/stable/reference/>`\n",
- "* Basic array class reference <https://numpy.org/doc/stable/reference/arrays.html>\n",
- "* Indexing <https://numpy.org/doc/stable/reference/arrays.indexing.html>`\n",
- "* ufuncs <https://numpy.org/doc/stable/reference/ufuncs.html>`\n",
- "* 2020 Nature paper on NumPy's role and basic concepts <https://www.nature.com/articles/s41586-020-2649-2>`"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "jp-MarkdownHeadingCollapsed": true,
- "tags": []
- },
- "source": [
- "## What is an array?\n",
- "\n",
- "For example, consider `[1, 2.5, 'asdf', False, [1.5, True]]` - this is a Python list but it has different types for every element. When you do math on this, every element has to be handled separately.\n",
- "\n",
- "Lists may serve the purpose of arrays, but they are slow to process. Numpy aims to provide an array object that is up to 50x faster than traditional Python lists. Numpy is the most used library for scientific computing. Even if you are not using it directly, chances are high that some library uses it in the background.\n",
- "\n",
- "The array data structure in numpy is called `ndarray`, it provides a lot of supporting functions that make working with `ndarray` very easy.\n",
- "\n",
- "An array is a ‘grid’ of values, with all the same types. It is indexed by tuples of non negative indices and provides the framework for multiple dimensions. An array has:\n",
- "\n",
- "- `dtype` - data type. Arrays always contain one type\n",
- "- `shape` - shape of the data, for example 3×2 or 3×2×500 or even 500 (one dimensional) or [] (zero dimensional).\n",
- "- `data` - raw data storage in memory. This can be passed to C or Fortran code for efficient calculations."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Performance check\n",
- "\n",
- "To quickly show the fast performances of NumPy arrays, we can compare the results of a basic operations using lists and array. In particular we will compute the square of 10000 elements."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "We first do this using Python lists, by creating a list with values from 0 to 9999, and one ‘empty’ list, to store the result in."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-07-01T15:53:26.360758Z",
- "start_time": "2022-07-01T15:53:26.350363Z"
- }
- },
- "outputs": [],
- "source": [
- "a = list(range(10000))\n",
- "b = [ 0 ] * 10000"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "%%timeit\n",
- "for i in range(len(a)):\n",
- " b[i] = a[i]**2"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "That looks and feels quite fast. But let’s take a look at how NumPy performs for the same task. We first import the `numpy` module, then we create our *a* and *b* containers again, which are now `ndarray` objects. Finally we perform the square operation."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "import numpy as np\n",
- "a = np.arange(10000)\n",
- "b = np.zeros(10000)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "%%timeit\n",
- "b = a ** 2"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "We see that working with numpy arrays provides substantial performance improvements."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-07-01T15:53:31.006650Z",
- "start_time": "2022-07-01T15:53:27.226245Z"
- }
- },
- "source": [
- "> **Note**: To evaluate the time of the computation we used the `%%timeit` command. `%%timeit` is a so-called Jupyter notebook *magic command* which is intiated with a `%` or `%%` prefix for line and cell commands, respectively. This `%%` cell magic has to be the first thing in the Jupyter cell, otherwise it will not work. There are many other interesting magic commands available, such as shown [here](https://towardsdatascience.com/top-8-magic-commands-in-jupyter-notebook-c1582e813560).\n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Creating arrays"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Arrays can be created using many different functions, this section will provide an overview in the many useful ways in which arrays can be created."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "You can create an array from a Python list by using `np.array` and passing a Python list:"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- ">**Note**: To print the values of variables, we will make use of *f-strings*. F-strings have been introduced in Python 3.6, and they are recommended for print formatting since they improve code readability and are less prone to errors. We use f-strings by adding the letter *f* before the string we want to print, and then entering the name of the variables within curly brackets `{` and `}`. More info can be found [here](https://www.geeksforgeeks.org/formatted-string-literals-f-strings-python/)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-07-01T15:53:36.717514Z",
- "start_time": "2022-07-01T15:53:36.707698Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.array([1,2,3]) # 1-dimensional array (rank 1)\n",
- "b = np.array([[1,2,3],[4,5,6]]) # 2-dimensional array (rank 2)\n",
- "\n",
- "# the print statements use f-strings to format the print output. \n",
- "print(f'a:{a}\\n') # \\n creates a new line \n",
- "print(f'a:\\t{a}\\n') # \\n adds a tab, a specific character for indentation\n",
- "print(f'b:\\n{b}\\n')\n",
- "print(f'shape of a: {a.shape}') # the shape (# rows, # columns)\n",
- "print(f'shape of b: {b.shape}') # the shape (# rows, # columns)\n",
- "print(f'size of a: {a.size}') # number of elements in the array b\n",
- "print(f'size of b: {b.size}') # number of elements in the array b"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Often it is useful to create an array with constant values; the following functions can be used to achieve this:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-07-01T15:53:36.770186Z",
- "start_time": "2022-07-01T15:53:36.750150Z"
- }
- },
- "outputs": [],
- "source": [
- "print(np.zeros((2, 3)), '\\n') # Create a 2x3 array with all elements set to 0\n",
- "print(np.ones((1,2)), '\\n') # Create a 1x2 array with all elements set to 1\n",
- "print(np.full((2,2),7), '\\n') # Create a 2x2 array with all elements set to 7\n",
- "print(np.eye(2), '\\n') # Create a 2x2 identity matrix"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Other common ways to create a vector include using evenly spaced values in an interval or by specifying the data type"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-07-01T15:53:36.841345Z",
- "start_time": "2022-07-01T15:53:36.820880Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.arange(10) # Evenly spaced values in an interval, with default stepsize 1\n",
- "b = np.linspace(0,9,10) # An array with 10 values between 0 and 9 \n",
- " # (check the difference with np.arange in the next section)\n",
- "\n",
- "c = np.ones((3, 2), bool) # 3x2 boolean array\n",
- "\n",
- "print(f'a:\\n{a}\\n')\n",
- "print(f'b:\\n{b}\\n')\n",
- "print(f'c:\\n{c}')"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "tags": []
- },
- "source": [
- " ---\n",
- " ## Array Data types\n",
- "\n",
- " What exactly is the difference between `np.arange(10)` and `np.linspace(0,9,10)`? \n",
- " \n",
- " - ``np.arange(10)`` results in ``array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])`` with dtype **int64**,\n",
- " - while ``np.linspace(0,9,10)`` results in ``array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])`` with dtype **float64**.\n",
- "\n",
- " Both ``np.linspace`` and ``np.arange`` take dtype (data type) as an argument and can be adjusted to match each other in that way:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-07-01T15:53:36.923930Z",
- "start_time": "2022-07-01T15:53:36.889193Z"
- }
- },
- "outputs": [],
- "source": [
- "print('As int64:')\n",
- "print(np.arange(10))\n",
- "print(np.linspace(0,9,10, dtype=np.int64))\n",
- "print('\\n')\n",
- "\n",
- "print('As float64:')\n",
- "print(np.arange(10, dtype=np.float64))\n",
- "print(np.linspace(0,9,10))"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "In many occasions (especially when something goes different than expected) it is useful to check and control, or change, the datatype of the array:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-07-01T15:53:36.958655Z",
- "start_time": "2022-07-01T15:53:36.950718Z"
- }
- },
- "outputs": [],
- "source": [
- "d = np.ones((3, 2), bool)\n",
- "\n",
- "print(f'd:\\n{d}\\n')\n",
- "print(f'datatype of d:\\n{d.dtype}\\n')\n",
- "\n",
- "e = d.astype(int)\n",
- " \n",
- "print(f'e:\\n{e}\\n')\n",
- "print(f'datatype of d:\\n{e.dtype}\\n')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "When converting floats to integers using `.astype()`, all floats in a numpy array are rounded to the largest integer lower than or equal to the float representation:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:18:04.756250Z",
- "start_time": "2022-06-30T19:18:04.748300Z"
- }
- },
- "outputs": [],
- "source": [
- "nums = np.linspace(0,2,11)\n",
- "print(f'nums:\\n{nums}\\n')\n",
- "\n",
- "numsint = nums.astype(np.int64)\n",
- "print(f'nums as integer:\\n{numsint}\\n')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Did you notice anything in the previous two cells?\n",
- "\n",
- "Right! We called the `astype` function not from the `np` module, but from the `ndarray` objects themselves. These are indeed *methods*, rather than *functions*. The main differences are highlighted in the table below.\n",
- "\n",
- "\n",
- "|Method | Function|\n",
- "| :----------- | :-----------|\n",
- "| is associated with the objects of the class they belong to | is not associated with any object|\n",
- "| is called 'on' an object and we cannot invoke it just by its name | we can invoke a function just by its name.|\n",
- "\n",
- "Nearly all the method versions do the same thing as the function versions. Choosing the method or the function will usually depend on which one is easier to type or read. Some examples will be provided later in this notebook."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "### <font color='red'>Exercise</font>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Create an array with elements ranging from 10 up to 15 (inclusive), with data type=unsigned 8 bit integer. \n",
- "Use the following functions:\n",
- "- Creating a python list and converting it to an array using `np.array()`\n",
- "- using `np.linspace()`\n",
- "- using `np.arange()`"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:18:04.816547Z",
- "start_time": "2022-06-30T19:18:04.796928Z"
- }
- },
- "outputs": [],
- "source": [
- "print('Your code here')\n",
- "print('Your code here')\n",
- "print('Your code here')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "tags": []
- },
- "source": [
- "## Types of operations\n",
- "\n",
- "There are different types of standard operations in NumPy:\n",
- "\n",
- "**ufuncs**, or universal functions operats on ndarrays in an element-by-element fashion. They can be *unary*, operating on a single input, or *binary*, operating on two inputs.\n",
- "\n",
- "They are used to implement vectorization in NumPy which is way faster than iterating over elements. They also provide broadcasting and additional methods like reduce, accumulate etc. that are very helpful for computation.\n",
- "\n",
- "ufuncs also take additional arguments, like:\n",
- "\n",
- "`where` boolean array or condition defining where the operations should take place.\n",
- "\n",
- "`dtype` defining the return type of elements.\n",
- "\n",
- "`out` output array where the return value should be copied.\n",
- "\n",
- "A thorough explanation and list of ufunc is available at [W3Schools](https://www.w3schools.com/python/numpy/numpy_ufunc.asp)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "There are ufunc equivalents for Python's native arithmetic operators, e.g., the standard addition, subtraction, multiplication, division, negation, exponentiation, and so on. The ufunc however allows for more control, for instance we can use the `out` argument to specify the array where the result of the calculation will be stored (rather than creating a temporary array). This turns out to be particularly useful for large computations."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Example: in-place addition. Create an array, add it to itself using a ufunc."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:18.981700Z",
- "start_time": "2022-06-19T14:12:18.968190Z"
- }
- },
- "outputs": [],
- "source": [
- "x = np.array([1, 2, 3])\n",
- "\n",
- "print(f'x before addition: {x}')\n",
- "print(f'id before addition: {id(x)}') # get the memory-ID of x\n",
- "np.add(x, x, x) # Third argument is output array\n",
- "np.add(x, x, x)\n",
- "print(f'x after addition: {x}')\n",
- "print(f'id after addition: {id(x)}') # get the memory-ID of x\n",
- " # - notice it is the same!"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Example: broadcasting. Can you add a 1-dimensional array of shape `(3)`\n",
- " to an 2-dimensional array of shape `(3, 2)`? With broadcasting you\n",
- " can, and most of the times it happens 'under the hood'."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:19.313612Z",
- "start_time": "2022-06-19T14:12:19.290281Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.array([[1, 2, 3],\n",
- " [4, 5, 6]])\n",
- "print(f'a:\\n{a}\\n') # Print a \n",
- "\n",
- "b = np.array([10, 10, 10])\n",
- "print(f'b:\\n{b}\\n') # Print b\n",
- "\n",
- "print(f'np.add(a, b):\\n{np.add(a, b)}\\n') # add arrays a and b"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Broadcasting is smart and consistent about what it does. The basics of broadcasting are [documented here](https://numpy.org/doc/stable/user/basics.broadcasting.html). The basic idea is that it expands dimensions of the smaller array so that they are compatible in shape."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### Array methods\n",
- "Array methods also implement useful operations, sometimes similar to the ufuncs.\n",
- "\n",
- "Remember that array methods are called on the `ndarray` object. You can find the full list of methods [here](https://numpy.org/doc/stable/reference/arrays.ndarray.html) along with all other important informations on `ndarray`. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:19.774526Z",
- "start_time": "2022-06-19T14:12:19.754807Z"
- }
- },
- "outputs": [],
- "source": [
- "x = np.arange(12)\n",
- "x.shape = (3, 4)\n",
- "x # array([[ 0, 1, 2, 3],\n",
- " # [ 4, 5, 6, 7],\n",
- " # [ 8, 9, 10, 11]])\n",
- "x.max() # 11"
- ]
- }
- ],
- "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.9.17"
- },
- "widgets": {
- "application/vnd.jupyter.widget-state+json": {
- "state": {},
- "version_major": 2,
- "version_minor": 0
- }
- }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
diff --git a/book/programming/code/numpy_1.ipynb b/book/programming/code/numpy_1.ipynb
deleted file mode 100644
index c1a18f21..00000000
--- a/book/programming/code/numpy_1.ipynb
+++ /dev/null
@@ -1,531 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# How to Use Arrays (ndarray)\n",
- "\n",
- "text"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "This notebook is based on the Numpy lesson from [Aalto Scientific Computing: Python for Scientific Computing](https://github.com/AaltoSciComp/python-for-scicomp/) and [W3Schools](https://www.w3schools.com/python/numpy/)."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Indexing and Slicing\n",
- "\n",
- "NumPy has many ways to extract values out of arrays:\n",
- "\n",
- "- You can select a single element\n",
- "- You can select rows or columns\n",
- "- You can select ranges where a condition is true.\n",
- "\n",
- "An example of some ways of indexing is shown in the following image (credits GeeksForGeeks):\n",
- "\n",
- "<img src=\"https://media.geeksforgeeks.org/wp-content/uploads/Numpy1.jpg\" alt=\"indexing\" style=\"width:400px;\"/>\n",
- "\n",
- "\n",
- "\n",
- "Clever and efficient use of these operations is a key to NumPy's speed. "
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "<font color='red'>Reminder: In python, all indexing starts at zero, so to select the index of the first element in a list or numpy array is represented by a 0!</font>"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:37.393492Z",
- "start_time": "2022-06-30T19:26:37.387136Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.arange(16).reshape(4, 4) # 4x4 matrix from 0 to 15\n",
- "print(f'a:\\n{a}\\n')\n",
- "print(f'a[0]:\\n{a[0]}\\n') # first row\n",
- "print(f'a[:,0]:\\n{a[:,0]}\\n') # first column\n",
- "print(f'a[1:3,1:3]:\\n{a[1:3,1:3]}\\n') # middle 2x2 array\n",
- "\n",
- "print(f'a[(0, 1), (1, 1)]:\\n{a[(0, 1), (1, 1)]}') # second element of first and second row as array"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "You can also perform *boolean indexing* on arrays, such as shown below:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:38.247841Z",
- "start_time": "2022-06-30T19:26:38.242145Z"
- }
- },
- "outputs": [],
- "source": [
- "print(f'a > 7:\\n{a > 7}\\n') # creates boolean matrix of same size as a \n",
- "print(f'a[a > 7]:\\n{a[a > 7]}\\n') # array with matching values of above criterion"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "### <font color='red'>Exercise</font>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "For the reshaped taxi ride duration array `taxi_weeks`, create the following arrays using slicing:\n",
- "- An array containing only daily total durations of *fridays* \n",
- "- An array containing *monday's* total durations from week 2 up to week 5\n",
- "- An array containing only entries with a total duration of more than 600 minutes"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:39.913802Z",
- "start_time": "2022-06-30T19:26:39.910639Z"
- }
- },
- "outputs": [],
- "source": [
- "fridays = 'Your code here'\n",
- "print(fridays)\n",
- "\n",
- "mondays_week_2_to_5 = 'Your code here'\n",
- "print(mondays_week_2_to_5)\n",
- "\n",
- "total_duration_over_6000 = 'Your code here'\n",
- "print(total_duration_over_6000)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-26T10:00:34.938121Z",
- "start_time": "2022-06-26T10:00:34.934887Z"
- },
- "code_folding": []
- },
- "source": [
- "### <font color='red'>Exercise</font>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The reshaped array `taxi_weeks` currently starts on a friday because this is the first day of the year. People often prefer to have the first column of the array corresponding to a monday instead. Using *slicing* and *reshaping*, create a new version of `taxi_weeks` from the `durations` array where the first column represents monday and chronological order is maintained."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "> Hint: It is easier if you remove some observations at the beginning and the end because they are not part of a full week of observations."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:45.492564Z",
- "start_time": "2022-06-30T19:26:45.488855Z"
- }
- },
- "outputs": [],
- "source": [
- "taxi_weeks_monday = 'Your code here'"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Again, we visualise the result:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:27:19.811872Z",
- "start_time": "2022-06-30T19:27:19.418465Z"
- },
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "labels = ['monday', 'tuesday', 'wednesday', 'thursday','friday', 'saturday', 'sunday']\n",
- "plot_taxi_weeks(taxi_weeks_monday,labels)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "## Array reshaping\n",
- "Arrays can be [reshaped](https://numpy.org/doc/stable/reference/generated/numpy.reshape.html) in many different ways, as long as the number of entries in the new shape does not differ from the number of entries in the original array. \n",
- "For example, the following array can be reshaped into a 3 by 3 array:\n",
- "\n",
- "<img src=\"./1dim.png\" alt=\"drawing\" width=\"600\"/>\n",
- "\n",
- "By reshaping this array into a 3 by 3 array using the default reading order, the following array is created:\n",
- "\n",
- "<img src=\"./2dim.png\" alt=\"drawindg\" style=\"width:200px;\"/>\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T15:45:00.005091Z",
- "start_time": "2022-06-19T15:44:59.973626Z"
- },
- "tags": [
- "allow_errors"
- ]
- },
- "outputs": [],
- "source": [
- "arr = np.arange(10)\n",
- "print(f'original:\\n{arr}')\n",
- "print(f'\\n5 rows and 2 columns:\\n{arr.reshape((5, 2))}')\n",
- "print(f'\\n2 rows and 5 columns:\\n{arr.reshape((2, -1))}') # -1 provides the fitting lenght of the dimension\n",
- "print(f'\\n1 row and 5 columns:\\n{arr.reshape((1, 5))}') # This action will cause an error because \n",
- " # 10 entries do not fit in a 1 by 5 array"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "### <font color='red'>Exercise</font>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Reshape the Taxi array as loaded in the previous exercise such that the array columns represent weekdays and the array rows represent different weeks in the period of the data set. Note that the first day of the year 2016 was a *friday*, so the week representation in the columns will start at *friday*."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:22:10.446976Z",
- "start_time": "2022-06-30T19:22:10.442911Z"
- },
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "taxi_weeks = 'Your code here'"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-26T09:24:54.678197Z",
- "start_time": "2022-06-26T09:24:54.637068Z"
- }
- },
- "source": [
- "A visualization of the reshaped array:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:23:19.025535Z",
- "start_time": "2022-06-30T19:23:18.668725Z"
- }
- },
- "outputs": [],
- "source": [
- "from plotting_functions import plot_taxi_weeks\n",
- "plot_taxi_weeks(taxi_weeks, labels = ['friday','saturday','sunday','monday','tuesday','wednesday','thursday'])"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "## View vs copy\n",
- "See the cell below:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:18.162370Z",
- "start_time": "2022-06-19T14:12:18.149896Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.eye(4) # Create an array\n",
- "print(f'a:\\n{a}\\n') # Print a\n",
- "\n",
- "b = a[:,0] # Set variable b as the first column of b\n",
- "b[0] = 5 # Set all elements in b to 5\n",
- "print(f'b:\\n{b}\\n') # print b\n",
- "\n",
- "print(f'a:\\n{a}\\n') # print a again"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The change in ``b`` has also changed the array ``a``!\n",
- "This is because ``b`` is merely a *view* of a part of array ``a``. Both\n",
- "variables point to the same memory. Hence, if one is changed, the other\n",
- "one also changes! If you need to keep the original array as is, use `np.copy(a)` or `a.copy()`."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:18.662616Z",
- "start_time": "2022-06-19T14:12:18.640303Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.eye(4) # Create an array\n",
- "print(f'a:\\n{a}\\n') # Print a \n",
- "\n",
- "b = np.copy(a)[:,0] # Set variable b as a copy of the first column of b\n",
- "b[0] = 5 # Set all elements in b to 5\n",
- "print(f'b:\\n{b}\\n') # print b\n",
- "\n",
- "print(f'a:\\n{a}\\n') # print a again"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": []
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "tags": []
- },
- "source": [
- "---\n",
- "## Saving and loading arrays\n",
- "When working with arrays, it might be useful to save or load an array to a file on your computer. This can be done using the `np.save()` and `np.load()` functions respectively:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:17.037022Z",
- "start_time": "2022-06-19T14:12:17.023276Z"
- },
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "arr = np.linspace(0, 10, 11) # Create an array\n",
- "print(f'arr:\\n{arr}')\n",
- "\n",
- "np.save('arr.npy', arr) # Save the array to a file on your computer\n",
- "arr = None # Setting the arr parameter to None\n",
- "print(f'arr:\\n{arr}')\n",
- "\n",
- "arr = np.load('arr.npy') # Load the array from the created .npy file \n",
- "print(arr)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "You now saved `arr.npy` such that you can use it later and in different scripts! It is also possible to load csv or txt files using the `np.loadtxt()` function. by passing the correct string representing the delimiter character, a txt or csv file can be loaded as an array:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:17.049361Z",
- "start_time": "2022-06-19T14:12:17.040476Z"
- }
- },
- "outputs": [],
- "source": [
- "arr_from_csv = np.loadtxt('./numpy_files/example_data.csv', delimiter=',') # This file uses the comma as the seperating character\n",
- "\n",
- "arr_from_txt = np.loadtxt('./numpy_files/example_data.txt', delimiter='\\t') # This file uses a tab as the seperating character\n",
- "\n",
- "print(f'array from csv file:\\n{arr_from_csv}\\n')\n",
- "print(f'array from txt file:\\n{arr_from_txt}')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "### <font color='red'>Exercise</font>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Load the provided csv `taxi_duration.txt` using the `np.loadtxt` function. The text file contains two columns: one representing the day of the year, and the other representing the daily total duration of taxi rides corresponding to the day of the year. Check the number of days in your loaded dataset. You can preview the file in a text editor if you want."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:18:24.834359Z",
- "start_time": "2022-06-30T19:18:24.824656Z"
- }
- },
- "outputs": [],
- "source": [
- "taxis = 'Your code here'\n",
- "# print(f'The dataset is {len(taxis)} days long.')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Now, visualize the dataset by running the cell below"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:20:22.724156Z",
- "start_time": "2022-06-30T19:20:22.455107Z"
- }
- },
- "outputs": [],
- "source": [
- "from numpy_files.plotting_functions import plot_taxi_time_series\n",
- "plot_taxi_time_series(taxis)"
- ]
- }
- ],
- "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.9.17"
- },
- "widgets": {
- "application/vnd.jupyter.widget-state+json": {
- "state": {},
- "version_major": 2,
- "version_minor": 0
- }
- }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
diff --git a/book/programming/code/numpy_2.ipynb b/book/programming/code/numpy_2.ipynb
deleted file mode 100644
index 2462bb6a..00000000
--- a/book/programming/code/numpy_2.ipynb
+++ /dev/null
@@ -1,456 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Using Numpy for Mathematics\n",
- "\n",
- "using it more"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "This notebook is based on the Numpy lesson from [Aalto Scientific Computing: Python for Scientific Computing](https://github.com/AaltoSciComp/python-for-scicomp/) and [W3Schools](https://www.w3schools.com/python/numpy/)."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Clearly, you can do math on arrays. Math in NumPy is fast because it is implemented in C or Fortran, just like in most other high-level languages such as R and Matlab.\n",
- "\n",
- "By default, in NumPy all math is performed element-by-element. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:28.411658Z",
- "start_time": "2022-06-30T19:26:28.402647Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.array([[1,2],[3,4]])\n",
- "b = np.array([[5,6],[7,8]])\n",
- "\n",
- "c = a + b\n",
- "d = np.add(a,b)\n",
- "\n",
- "print('a\\n', a, '\\n')\n",
- "print('b:\\n', b, '\\n')\n",
- "\n",
- "print('a + b:\\n', a + b, '\\n')\n",
- "print('a * b:\\n', a * b, '\\n')\n",
- "print('a / b:\\n', a / b, '\\n')\n",
- "print('square root of a:\\n', np.sqrt(a), '\\n')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Also the sum or mean an array can be obtained through the `np.mean` and `np.std` functions:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:28.898518Z",
- "start_time": "2022-06-30T19:26:28.878550Z"
- }
- },
- "outputs": [],
- "source": [
- "print('sum of a:\\n', np.sum(a), '\\n')\n",
- "print('mean of a:\\n', np.mean(a), '\\n')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "\n",
- "In the above cell we see that `np.sum(a)` provides the sum of all elements in a. If we wish to get the sum per row or per column we can specify the *axis* over which to sum (0 corresponds to rows and 1 corresponds to columns):"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:29.610745Z",
- "start_time": "2022-06-30T19:26:29.601866Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.array([[1,2],[3,4]])\n",
- "\n",
- "print('a\\n', a, '\\n')\n",
- "print('sum of a:\\n', np.sum(a), '\\n') # No specified axis\n",
- "print('sum of a per column:\\n', np.sum(a, axis = 0), '\\n') # sum over axis 0\n",
- "print('sum of a per row:\\n', np.sum(a, axis = 1)) # sum over axis 1"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "### <font color='red'>Exercise</font>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Compute the standard deviation of the trip *duration* data, using the following functions: `np.sqrt()`, `np.mean()`, `np.sum()`, `np.size()`, and the mathematical operators `-` and `/`.\n",
- "\n",
- "The standard deviation is defined as $\\sqrt{\\frac{\\sum^{n}_{i=0} \\left( x_i - \\bar{x} \\right)^2}{n}}$ for a vector x with size n. Compare the result with the usage of the `np.std()` function.\n",
- "\n",
- "The array to use for this exercise is the `durations` array as defined below, which contains only the Taxi ride durations of the original imported array (no day of the year column)."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "taxis = np.loadtxt('./numpy_files/taxi_duration.txt', delimiter=',')"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:30.709843Z",
- "start_time": "2022-06-30T19:26:30.702703Z"
- }
- },
- "outputs": [],
- "source": [
- "durations = taxis[:,1]\n",
- "\n",
- "mean_duration = 'Your code here'\n",
- "std_duration = 'Your code here'\n",
- "\n",
- "print(f'Mean duration: {mean_duration}\\nStandard deviation of the duration: {std_duration}')\n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Next, compute the mean and standard deviation per weekday using the `taxi_weeks` array:\n",
- "- On which weekday, on average, does the highest taxi ride duration occur?"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:31.420314Z",
- "start_time": "2022-06-30T19:26:31.416623Z"
- },
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "mean_duration = 'Your code here'\n",
- "std_duration = 'Your code here'\n",
- "\n",
- "print(f'Mean duration: {mean_duration}\\nStandard deviation of the duration: {std_duration}')\n",
- "print(np.std(taxi_weeks, axis=0))"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "## Dot product and matrix multiplication\n",
- "As we saw in the previous example, the `*` operator or `.multiply()` function performs an element wise multiplication. To perform matrix multiplication, the `@` operator can be used:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:32.265450Z",
- "start_time": "2022-06-30T19:26:32.247773Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.eye(3) * 2\n",
- "b = np.arange(1,10, dtype=np.float64).reshape((3,3))\n",
- "\n",
- "print(f'a\\n{a}\\n') \n",
- "print(f'b:\\n{b}\\n')\n",
- "print(f'a * b:\\n{a * b}\\n') # Element-wise multiplication\n",
- "print(f'a @ b:\\n{a @ b}\\n') # dot product or matrix multiplication\n",
- "print(f'np.dot(a, b):\\n{np.dot(a, b)}\\n') # dot product or matrix multiplication"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "To transpose an array representing a vector or matrix, the `np.transpose()` function can be used. Alternatively, an array can be transposed by accessing its `.T` attribute. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:33.118948Z",
- "start_time": "2022-06-30T19:26:33.112240Z"
- }
- },
- "outputs": [],
- "source": [
- "a = np.arange(6)\n",
- "a = a.reshape((3,2)) # a now has 3 rows and 2 columns\n",
- "print(f'a:\\n{a}\\n')\n",
- "print(f'np.transpose(a):\\n{np.transpose(a)}\\n') # a now has 2 rows and 3 columns\n",
- "print(f'a.T:\\n{a.T}') # a now has 2 rows and 3 columns (same outcome as line above)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "### <font color='red'>Exercise</font>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Create the two matrices A and B as numpy arrays: $A = \\begin{bmatrix} 1&4&2\\\\0&2&1\\\\3&7&6 \\end{bmatrix}$, $B = \\begin{bmatrix} 2&0&1\\\\0&3&0\\\\1&2&0 \\end{bmatrix}$.\n",
- "\n",
- "Next, perform the following operations:\n",
- "- Compute $C = A + B$\n",
- "- Compute $D = A \\cdot B$\n",
- "- Compute $D^T$"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-30T19:26:34.557000Z",
- "start_time": "2022-06-30T19:26:34.552438Z"
- }
- },
- "outputs": [],
- "source": [
- "A = 'Your code here'\n",
- "B = 'Your code here'\n",
- "C = 'Your code here'\n",
- "D = 'Your code here'\n",
- "\n",
- "print(f'{A}\\n')\n",
- "print(f'{B}\\n')\n",
- "print(f'{C}\\n')\n",
- "print(f'{D}\\n')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Example: Linear algebra using Numpy\n",
- "\n",
- "In this short example, we will solve a linear system of equations using numpy. \n",
- "\n",
- "Let's say we want to fit a polynomial $y = a_0 x^2 + a_1 x + a_2$ through the points $(1,0)$, $(2,2)$, and $(3,1)$.\n",
- "We can obtain the variables $a_0$, $a_1$, and $a_2$ by solving the folowing linear system of equations:\n",
- "\n",
- "$\\begin{bmatrix} 1 & 1 & 1\\\\ 4 & 2 & 1\\\\ 9 & 3 & 1 \\end{bmatrix} \\begin{bmatrix} a_0\\\\ a_1\\\\ a_2 \\end{bmatrix} = \\begin{bmatrix} 0\\\\ 2\\\\ 1 \\end{bmatrix}$\n",
- "\n",
- "If we want to solve a simple system of linear equations in the form of $\\mathbf{A}\\mathbf{x} = \\mathbf{b}$, when given A and b. If A is invertable, then this equation can be solved by inverting rearranging the matrix and vectors: $\\mathbf{A}^{-1}\\mathbf{b} = \\mathbf{x}$"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:20.095747Z",
- "start_time": "2022-06-19T14:12:20.080533Z"
- }
- },
- "outputs": [],
- "source": [
- "A = np.array([[1, 1, 1], \n",
- " [4, 2, 1], \n",
- " [9, 3, 1]])\n",
- "b = np.array([0, 2, 1]).T\n",
- "\n",
- "x = np.linalg.inv(A) @ b\n",
- "\n",
- "print(f'A:\\n{A}\\n')\n",
- "print(f'b:\\n{b}\\n')\n",
- "print(f'x:\\n{x}\\n')"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Checking the specified conditions:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:24.949348Z",
- "start_time": "2022-06-19T14:12:24.942277Z"
- }
- },
- "outputs": [],
- "source": [
- "a0, a1, a2 = x \n",
- "\n",
- "print(f'a0 * 1**2 + a1 * 1 + a2 = {a0 * 1**2 + a1 * 1 + a2:.2f}') # Check solution at x = 1\n",
- "print(f'a0 * 2**2 + a1 * 2 + a2 = {a0 * 2**2 + a1 * 2 + a2:.2f}') # Check solution at x = 2\n",
- "print(f'a0 * 3**2 + a1 * 3 + a2 = {a0 * 3**2 + a1 * 3 + a2:.2f}') # Check solution at x = 3"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "It can be seen that the solution is nearly correct... The values of used in these calculations are floats, which cannnot represent every number exactly. Therefore, when performing calculations, the outcome might differ by a very small amount in the order of 1e-15 times the magnitude of the number."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "Alternatively, we could have used the `np.linalg.solve()` function to solve the equation $\\mathbf{A}\\mathbf{x} = \\mathbf{b}$ given **A** and **b**:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:25.385378Z",
- "start_time": "2022-06-19T14:12:25.370247Z"
- }
- },
- "outputs": [],
- "source": [
- "x = np.linalg.solve(A, b)\n",
- "print(x)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "Another way of obtaining the parameters of a polynomial fitted to a number of coordinates (utilizing the least squares method) is through the `np.polyfit()` function, where the x and y coordinates of the coordinates must be passed in two seperate arrays:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:25.731155Z",
- "start_time": "2022-06-19T14:12:25.713075Z"
- }
- },
- "outputs": [],
- "source": [
- "coordinates = np.array([[1, 0], # Define an array containing the required coordinates\n",
- " [2, 2],\n",
- " [3, 1]])\n",
- "\n",
- "x = np.polyfit(coordinates[:,0], coordinates[:,1], deg=2) # Use the np.polyfit function specifying the coordinates and the degree of polynomial\n",
- "print(x)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---\n",
- "This shows that there are always multiple options to tackling a poblem using numpy, and for a lot of scenarios there is likely already a numpy function which can be used to reduce the amount of code needed to perform a task."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## More linear algebra and other advanced math\n",
- "\n",
- "In general, you use `arrays` (n-dimensions), not `matrixes`\n",
- "(specialized 2-dimensional) in NumPy.\n",
- "\n",
- "Internally, NumPy doesn't invent its own math routines: it relies on\n",
- "[BLAS](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms)\n",
- "and [LAPACK](https://en.wikipedia.org/wiki/LAPACK) to do this kind\n",
- "of math - the same as many other languages.\n",
- "\n",
- "- [Linear algebra in numpy documentation](https://numpy.org/doc/stable/reference/routines.linalg.html)\n",
- "\n",
- "- [Scipy](https://docs.scipy.org/doc/scipy/reference/) has\n",
- " more usful functions\n",
- "\n",
- "- Many other libraries use NumPy arrays as the standard data\n",
- " structure: they take data in this format, and return it similarly.\n",
- " Thus, all the other packages you may want to use are compatible\n"
- ]
- }
- ],
- "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.9.17"
- },
- "widgets": {
- "application/vnd.jupyter.widget-state+json": {
- "state": {},
- "version_major": 2,
- "version_minor": 0
- }
- }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
diff --git a/book/programming/code/numpy_3.ipynb b/book/programming/code/numpy_3.ipynb
deleted file mode 100644
index 59f950c8..00000000
--- a/book/programming/code/numpy_3.ipynb
+++ /dev/null
@@ -1,234 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Exercises\n",
- "\n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {
- "tags": []
- },
- "source": [
- "## Optional Exercises\n",
- "\n",
- " If you have extra time, try these out.\n",
- "\n",
- " 1. Reverse a vector: given a vector, reverse it such that the last\n",
- " element becomes the first, e.g. ``[1, 2, 3]`` => ``[3, 2, 1]``\n",
- "\n",
- " 2. Create a 2D array with zeros on the borders and 1 inside.\n",
- "\n",
- " 3. Create a random array of length 20 with elements [0, 1), then add 10 to all\n",
- " elements in the range [0.2, 0.7).\n",
- "\n",
- " 4. What is `np.round(0.5)`? What is ``np.round(1.5)``? Why?\n",
- "\n",
- " 5. In addition to ``np.round``, explore `numpy.ceil`, `numpy.floor`,\n",
- " `numpy.trunc`. In particular, take note of how they behave with\n",
- " negative numbers.\n",
- "\n",
- " 6. Recall the identity $sin^2(x) + cos^2(x) = 1$. Create a\n",
- " random 4x4 array with values in the range [0, 10). Now test the\n",
- " equality with `numpy.equal`. What result do you get with\n",
- " `numpy.allclose` instead of ``np.equal``?\n",
- "\n",
- " 7. Create a 1D array with 10 random elements. Sort it.\n",
- "\n",
- " 8. What's the difference between `np_array.sort()` and\n",
- " `np.sort(np_array)`?\n",
- "\n",
- " 9. For the random array in question 8, instead of sorting it, perform\n",
- " an indirect sort. That is, return the list of indices which would\n",
- " index the array in sorted order.\n",
- "\n",
- " 10. Create a 4x4 array of zeros, and another 4x4 array of ones. Next\n",
- " combine them into a single 8x4 array with the content of the zeros\n",
- " array on top and the ones on the bottom. Finally, do the same,\n",
- " but create a 4x8 array with the zeros on the left and the ones on\n",
- " the right."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:26.224649Z",
- "start_time": "2022-06-19T14:12:26.206876Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 1\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:26.474002Z",
- "start_time": "2022-06-19T14:12:26.460567Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 2\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:26.702969Z",
- "start_time": "2022-06-19T14:12:26.696217Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 3\n",
- "# YOUR SOLUTION MAY BE DIFFERENT IF YOU USE A DIFFERENT SEED\n",
- "np.random.seed(42)\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:26.929738Z",
- "start_time": "2022-06-19T14:12:26.925391Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 4\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:27.229140Z",
- "start_time": "2022-06-19T14:12:27.208488Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 5\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:27.483903Z",
- "start_time": "2022-06-19T14:12:27.479675Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 6\n",
- "# YOUR SOLUTION MAY BE DIFFERENT IF YOU USE A DIFFERENT SEED\n",
- "np.random.seed(42)\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:27.731045Z",
- "start_time": "2022-06-19T14:12:27.726535Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 7\n",
- "# YOUR SOLUTION MAY BE DIFFERENT IF YOU USE A DIFFERENT SEED\n",
- "np.random.seed(42)\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:28.084292Z",
- "start_time": "2022-06-19T14:12:28.079122Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 8\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:28.274953Z",
- "start_time": "2022-06-19T14:12:28.259871Z"
- }
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 9\n",
- "# YOUR SOLUTION MAY BE DIFFERENT IF YOU USE A DIFFERENT SEED\n",
- "np.random.seed(42)\n"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "ExecuteTime": {
- "end_time": "2022-06-19T14:12:28.519886Z",
- "start_time": "2022-06-19T14:12:28.513541Z"
- },
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "# Answer for Ex. 10.\n"
- ]
- }
- ],
- "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.9.17"
- },
- "widgets": {
- "application/vnd.jupyter.widget-state+json": {
- "state": {},
- "version_major": 2,
- "version_minor": 0
- }
- }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
diff --git a/book/programming/code/numpy_files/arr.npy b/book/programming/code/numpy_files/arr.npy
deleted file mode 100644
index 20cb770683b2ee8d5c9ebd524c50cf77285bfae2..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 216
zcmbR27wQ`j$;eQ~P_3SlTAW;@Zl$1ZlV+i=qoAIaUsO_*m=~X4l#&V(cT3DEP6dh=
zXCxM+0{I$-hB}%$3bhL411<&>@WCF+b%4+uP+9;=i$G}!C@lk}6`-^dlvZ&70C}4q
Aq5uE@
diff --git a/book/programming/code/numpy_files/barcharts.png b/book/programming/code/numpy_files/barcharts.png
deleted file mode 100644
index a1b76a463c3da75ed4c29f93a1f694856ebc4087..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 54693
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
HF6;g;dsb)z
diff --git a/book/programming/code/numpy_files/example_data.csv b/book/programming/code/numpy_files/example_data.csv
deleted file mode 100644
index 3d51010b..00000000
--- a/book/programming/code/numpy_files/example_data.csv
+++ /dev/null
@@ -1,10 +0,0 @@
-0.1, 5.0
-0.2, 6.0
-0.3, 5.7
-0.4, 6.7
-0.5, 5.8
-0.6, 4.5
-0.7, 4.9
-0.8, 5.6
-0.9, 5.7
-1.0, 5.3
\ No newline at end of file
diff --git a/book/programming/code/numpy_files/example_data.txt b/book/programming/code/numpy_files/example_data.txt
deleted file mode 100644
index deb64837..00000000
--- a/book/programming/code/numpy_files/example_data.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-0.1 5.0
-0.2 6.0
-0.3 5.7
-0.4 6.7
-0.5 5.8
-0.6 4.5
-0.7 4.9
-0.8 5.6
-0.9 5.7
-1.0 5.3
\ No newline at end of file
diff --git a/book/programming/code/numpy_files/plotting_functions.py b/book/programming/code/numpy_files/plotting_functions.py
deleted file mode 100644
index 6a62ecfd..00000000
--- a/book/programming/code/numpy_files/plotting_functions.py
+++ /dev/null
@@ -1,18 +0,0 @@
-import numpy as np
-import matplotlib.pyplot as plt
-
-def plot_taxi_time_series(array):
- plt.figure(figsize=(10, 10))
- plt.plot(array[:,0], array[:,1])
- plt.xlabel('Day of the year')
- plt.ylabel('Daily total duration of taxi rides [minutes]')
- plt.show()
-
-def plot_taxi_weeks(array, labels):
- plt.figure(figsize=(5, 8))
- plt.imshow(array)
- plt.xticks([0, 1, 2, 3, 4, 5, 6], labels, rotation=60)
- plt.ylabel('Week number')
- plt.yticks(np.arange(26), np.arange(1,27))
- bar = plt.colorbar()
- bar.set_label('Total daily taxi ride duration [minutes]')
\ No newline at end of file
diff --git a/book/programming/code/numpy_files/taxi_duration.txt b/book/programming/code/numpy_files/taxi_duration.txt
deleted file mode 100644
index 13fa3966..00000000
--- a/book/programming/code/numpy_files/taxi_duration.txt
+++ /dev/null
@@ -1,182 +0,0 @@
-1,2975
-2,2412
-3,2523
-4,2805
-5,2856
-6,3447
-7,3546
-8,3908
-9,3505
-10,3371
-11,2996
-12,3138
-13,3458
-14,3541
-15,3686
-16,5049
-17,2746
-18,2639
-19,2999
-20,3794
-21,4069
-22,3793
-23,948
-24,1410
-25,3661
-26,5528
-27,3787
-28,3934
-29,4304
-30,5325
-31,3256
-32,3370
-33,3260
-34,4189
-35,5326
-36,3440
-37,3362
-38,3209
-39,3005
-40,3378
-41,4977
-42,4161
-43,4618
-44,4900
-45,5319
-46,2715
-47,3843
-48,5568
-49,3926
-50,3948
-51,6351
-52,4516
-53,3543
-54,4258
-55,3799
-56,4430
-57,4498
-58,5527
-59,3681
-60,4562
-61,3437
-62,4249
-63,5609
-64,9037
-65,4214
-66,3203
-67,3059
-68,3512
-69,4237
-70,4365
-71,4296
-72,5610
-73,3309
-74,5634
-75,7116
-76,3968
-77,4662
-78,4471
-79,5910
-80,3328
-81,4724
-82,3546
-83,3625
-84,5433
-85,4161
-86,3362
-87,4382
-88,3140
-89,5174
-90,3832
-91,6672
-92,4251
-93,4009
-94,5259
-95,4956
-96,4362
-97,3866
-98,6665
-99,5761
-100,4226
-101,3376
-102,3412
-103,4365
-104,4058
-105,5140
-106,5195
-107,5920
-108,4069
-109,3182
-110,3867
-111,5206
-112,3593
-113,4563
-114,4758
-115,3331
-116,3227
-117,4671
-118,4052
-119,4025
-120,5847
-121,4136
-122,4802
-123,3080
-124,4217
-125,3796
-126,4709
-127,5155
-128,4247
-129,4697
-130,4922
-131,3849
-132,3358
-133,6704
-134,6826
-135,3940
-136,5711
-137,5282
-138,4880
-139,5752
-140,4630
-141,5028
-142,4476
-143,3683
-144,3141
-145,3865
-146,5943
-147,4996
-148,3846
-149,4437
-150,3188
-151,3444
-152,3505
-153,4176
-154,5929
-155,4126
-156,4093
-157,3929
-158,4869
-159,3794
-160,4278
-161,6276
-162,4529
-163,4842
-164,4637
-165,3019
-166,4050
-167,4497
-168,5103
-169,5242
-170,3530
-171,3362
-172,3577
-173,3843
-174,4206
-175,3849
-176,5426
-177,4815
-178,3282
-179,4356
-180,3528
-181,3540
-182,3724
diff --git a/book/programming/python_topics/classes_solution.ipynb b/book/programming/python_topics/classes_solution.ipynb
deleted file mode 100644
index ae1082c1..00000000
--- a/book/programming/python_topics/classes_solution.ipynb
+++ /dev/null
@@ -1,961 +0,0 @@
-{
- "cells": [
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Classes and Object-Oriented Programming in Python"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "<img src=\"https://surfdrive.surf.nl/files/index.php/apps/files_sharing/ajax/publicpreview.php?x=1920&y=452&a=true&file=header.png&t=meVX4gGMjLbKX1z&scalingup=0\" alt=\"header\" border=\"0\"/>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Learning Objectives:\n",
- "By the end of this class, students should be able to:\n",
- "\n",
- "- Understand the fundamental concepts of classes and object-oriented programming (OOP) in Python.\n",
- "- Comprehend the key principles of encapsulation, inheritance, and polymorphism in OOP.\n",
- "- Define and create classes in Python.\n",
- "- Create objects from classes and understand the relationship between classes and objects."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Contents\n",
- "===\n",
- "- [Introduction to Object-Oriented Programming](#Introduction-to-Object-Oriented-Programming)\n",
- "- [What are classes?](#What-are-classes?)\n",
- "- [Adding parameters to the class](#Adding-parameters-to-the-class)\n",
- " - [Accepting parameters for the \\_\\_init\\_\\_() method](#Accepting-parameters-for-the-__init__%28%29-method)\n",
- " - [Accepting parameters in a method](#Accepting-parameters-in-a-method)\n",
- "- [Encapsulation](#Encapsulation)\n",
- "- [Inheritance](#Inheritance)\n",
- "- [Polymorphism](#Polymorphism)\n",
- "- [Exercises](#Exercises)\n",
- "- [Additional Information (optional)](#Additional-Information-(optional))\n",
- "- [References and used resources](#References-and-used-resources)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Introduction to Object-Oriented Programming\n",
- "===\n",
- "Object-Oriented Programming (OOP) is a programming paradigm that organizes code into reusable blocks of code called *classes*, which bundle data (*attributes*) and behaviors (*methods*) together.\n",
- "When you want to use a class in one of your programs, you make an **object** from that class, which is where the phrase \"object-oriented\" comes from.\n",
- "\n",
- "OOP promotes:\n",
- "- modularity: making multiple modules or functions and then combining them to form a complete system\n",
- "- reusability: shared attributes and functions can be reused without the need of rewriting code\n",
- "- better code organization: less code and more reuse\n",
- "<!-- \n",
- "OOP is defined by 4 main concepts:\n",
- "- Encapsulation: concept of bundling data and methods that operate on that data into a single unit called a class. Its purpose is to help in organizing and protecting an object's internal state and behavior;\n",
- "- Inheritance: mechanism that allows a new class to inherit attributes and methods from an existing class. Its purpose is to promote code reusability, extensibility, and the creation of class hierarchies, where subclasses can build upon the functionality of their parent classes;\n",
- "- Polymorphism: ability of different objects to respond to the same method name in a way that is specific to their class. It simplifies code by enabling flexibility and dynamic behavior;\n",
- "- Abstraction: process of simplifying complex systems by modeling classes based on their essential properties. It reduces complexity, making code more understandable and maintainable. -->\n",
- "\n",
- "These concepts may seem abstract for now but they will start to make more sense throughout the rest of the notebook."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "What are classes?\n",
- "===\n",
- "Classes can be thought of as blueprints or templates for creating objects. \n",
- "\n",
- "A **class** is a body of code that defines the **attributes** and **behaviors** required to accurately model something you need for your program. Each class encapsulates both properties (attributes) and functions (methods) related to that type of object.\n",
- "\n",
- "An **attribute** is a piece of information. In code, an attribute is just a variable that is part of a class.\n",
- "\n",
- "A **method** is an action that is defined within a class, i.e., just a function that is defined for the class.\n",
- "\n",
- "An **object** is a particular instance of a class. An object has a certain set of values for all of the attributes (variables) in the class. You can have as many objects as you want for any one class."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Let's consider an example using a rocket ship in a game.\n",
- "When defining the Rocket class, we have to imagine what are properties and actions that are common to all rockets in this hypotethic game.\n",
- "For example, the a very simple rocket will have some x and y coordinates and will be able to move up.\n",
- "Here is what the rocket class can look like in code:\n",
- "<img src=\"https://surfdrive.surf.nl/files/index.php/apps/files_sharing/ajax/publicpreview.php?x=1920&y=452&a=true&file=Cartoon_space_rocket.png&t=KEEPyzZeDZPfcLj&scalingup=0\" alt=\"Rocket\" border=\"0\" width=\"200\" align=\"right\"/>\n",
- "\n",
- "```python\n",
- "class Rocket:\n",
- " # Rocket simulates a rocket ship for a game.\n",
- " \n",
- " def __init__(self):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = 0\n",
- " self.y = 0\n",
- "\n",
- " def move_up(self):\n",
- " # Each rocket can move along the y-axis.\n",
- " self.y += 1\n",
- "```\n",
- "\n",
- "Now let's examine how we created this class.\n",
- "\n",
- "The first line, with the keyword **class**, tells Python that you are about to define a class. The naming convention for classes is the CamelCase, a convention where each letter that starts a word is capitalized, with no underscores in the name. \n",
- "It is recommended that the class name does not have any parentheses after it, unless it inherits from another class (we'll see this better later).\n",
- "\n",
- "It is good practice to write a comment at the beginning of your class, describing the class. There is a [more formal syntax](http://www.python.org/dev/peps/pep-0257/) for documenting your classes, but you can wait a little bit to get that formal. For now, just write a comment at the beginning of your class summarizing what you intend the class to do. Writing more formal documentation for your classes will be easy later if you start by writing simple comments now.\n",
- "\n",
- "One of the first things you do when creating a class is to define the `__init__()` method. \n",
- "The `__init__()` method is called automatically when you create an object from your class and sets the values for any parameters that need to be defined when an object is first created. 0\n",
- "We call this method a ***constructor***. \n",
- "In this case, The `__init__()` method initializes the x and y values of the Rocket to 0.\n",
- "\n",
- "The ***self*** part is a syntax that allows you to access variables and methods from anywhere else in the class.\n",
- "The word \"self\" refers to the current object that you are working with. Basically, all methods in a class need the *self* object as their first argument, so they can access any attribute that is part of the class.\n",
- "\n",
- "Methods define a specific action that the class can do.\n",
- "A method is just a function that is part of a class. Since it is just a function, you can do anything with a method that you learned about with functions.\n",
- "Each method generally accepts at least one argument, the value **self**. This is a reference to the particular object that is calling the method."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "With this code, we just defined the class, which is a blueprint.\n",
- "To define the actual object, we have to create an *instance* of the class.\n",
- "In other words, you create a variable that takes all of the attributes and methods as the Rocket class.\n",
- "\n",
- "This can be done simply as follows:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Rocket:\n",
- " # Rocket simulates a rocket ship for a game,\n",
- " \n",
- " def __init__(self):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = 0\n",
- " self.y = 0\n",
- " \n",
- " def move_up(self):\n",
- " # Increment the y-position of the rocket.\n",
- " self.y += 1\n",
- "\n",
- "# Create a Rocket object.\n",
- "my_rocket = Rocket()\n",
- "print(my_rocket)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Once you have a class, you can define an object and use its methods. Here is how you might define a rocket and have it start to move up:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "# Create a Rocket object, and have it start to move up.\n",
- "my_rocket = Rocket()\n",
- "print(f\"Rocket altitude: {my_rocket.y}\", )\n",
- "\n",
- "my_rocket.move_up()\n",
- "print(f\"Rocket altitude: {my_rocket.y}\")\n",
- "\n",
- "my_rocket.move_up()\n",
- "print(f\"Rocket altitude: {my_rocket.y}\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "To access an object's variables or methods, you give the name of the object and then use *dot notation* to access the variables and methods. \n",
- "So to get the y-value of `my_rocket`, you use `my_rocket.y`. \n",
- "\n",
- "To use the `move_up()` method on my_rocket, you write `my_rocket.move_up()`.\n",
- "This tells Python to apply the method `move_up()` to the object `my_rocket`.\n",
- "Python finds the y-value associated with `my_rocket` and adds 1 to that value. \n",
- "This process is repeated several times, and you can see from the output that the y-value is in fact increasing."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Making multiple objects from a class\n",
- "---\n",
- "One of the goals of object-oriented programming is to create reusable code. Once you have written the code for a class, you can create as many objects from that class as you need. It is worth mentioning at this point that classes are usually saved in a separate file, and then imported into the program you are working on. So you can build a library of classes, and use those classes over and over again in different programs. Once you know a class works well, you can leave it alone and know that the objects you create in a new program are going to work as they always have.\n",
- "\n",
- "You can see this \"code reusability\" already when the Rocket class is used to make more than one Rocket object. Each object is its own instance of that class, with its own separate variables. All of the objects are capable of the same behavior, but each object's particular actions do not affect any of the other objects.\n",
- "Here is the code that made a fleet of Rocket objects:\n",
- "\n",
- "<img src=\"https://surfdrive.surf.nl/files/index.php/apps/files_sharing/ajax/publicpreview.php?x=1920&y=452&a=true&file=many.png&t=XnqII6NO70dgxjw&scalingup=0\" alt=\"Fleet of rockets\" border=\"0\" width=\"800\"/>"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Rocket:\n",
- " # Rocket simulates a rocket ship for a game,\n",
- " # or a physics simulation.\n",
- " \n",
- " def __init__(self):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = 0\n",
- " self.y = 0\n",
- " \n",
- " def move_up(self):\n",
- " # Increment the y-position of the rocket.\n",
- " self.y += 1\n",
- " \n",
- "# Create a fleet of 3 rockets, and store them in a list.\n",
- "rocket_1 = Rocket()\n",
- "rocket_2 = Rocket()\n",
- "rocket_3 = Rocket()\n",
- "\n",
- "# Show that each rocket is a separate object.\n",
- "print(rocket_1, rocket_2, rocket_3)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "You can see that each rocket is at a separate place in memory and therefore printed in a different way."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "You can show that each rocket has its own x and y values by moving just one of the rockets:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "# Move the third rocket up.\n",
- "rocket_3.move_up()\n",
- "\n",
- "# Show that only the third rocket has moved.\n",
- "print(f\"Rocket altitudes: {rocket_1.y}, {rocket_2.y}, {rocket_3.y}\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "A quick check-in\n",
- "---\n",
- "If all of this makes sense, then the rest of your work with classes will involve learning a lot of details about how classes can be used in more flexible and powerful ways. If this does not make any sense, you could try a few different things:\n",
- "\n",
- "- Reread the previous sections, and see if things start to make any more sense.\n",
- "- Type out these examples in your own editor, and run them. Try making some changes, and see what happens.\n",
- "- Read on. The next sections are going to add more functionality to the Rocket class. These steps will involve rehashing some of what has already been covered, in a slightly different way.\n",
- "\n",
- "Classes are a huge topic, and once you understand them you will probably use them for the rest of your life as a programmer. If you are brand new to this, be patient and trust that things will start to sink in."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Adding parameters to the class\n",
- "===\n",
- "The Rocket class so far is very simple. It can be made a little more interesting with some refinements to the `__init__()` method, and by the addition of some methods."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Accepting parameters for the \\_\\_init\\_\\_() method\n",
- "---\n",
- "The `__init__()` method is run automatically one time when you create a new object from a class. The `__init__()` method for the Rocket class so far is pretty simple.\n",
- "But we can easily add keyword arguments so that new rockets can be initialized at any position:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Rocket:\n",
- " # Rocket simulates a rocket ship for a game,\n",
- " # or a physics simulation.\n",
- " \n",
- " def __init__(self, x=0, y=0):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = x\n",
- " self.y = y\n",
- " \n",
- " def move_up(self):\n",
- " # Increment the y-position of the rocket.\n",
- " self.y += 1"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Now when you create a new Rocket object you have the choice of passing in arbitrary initial values for x and y:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "# Make a series of rockets at different starting places.\n",
- "rockets = []\n",
- "rockets.append(Rocket())\n",
- "rockets.append(Rocket(0,10))\n",
- "rockets.append(Rocket(100,0))\n",
- "\n",
- "# Show where each rocket is.\n",
- "for index, rocket in enumerate(rockets):\n",
- " print(f\"Rocket {index} is at (x,y)=({rocket.x}, {rocket.y}).\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Accepting parameters in a method\n",
- "---\n",
- "The `__init__()` method is just a special method that serves a particular purpose, which is to help create new objects from a class. Any method in a class can accept parameters of any kind. With this in mind, the `move_up()` method can be made much more flexible. By accepting keyword arguments, the `move_up()` method can be rewritten as a more general `move_rocket()` method. This new method will allow the rocket to be moved any amount, in any direction:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Rocket():\n",
- " # Rocket simulates a rocket ship for a game,\n",
- " # or a physics simulation.\n",
- " \n",
- " def __init__(self, x=0, y=0):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = x\n",
- " self.y = y\n",
- " \n",
- " def move_rocket(self, x_increment=0, y_increment=1):\n",
- " # Move the rocket according to the paremeters given.\n",
- " # Default behavior is to move the rocket up one unit.\n",
- " self.x += x_increment\n",
- " self.y += y_increment"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The paremeters for the move() method are named x_increment and y_increment rather than x and y. It's good to emphasize that these are changes in the x and y position, not new values for the actual position of the rocket. By carefully choosing the right default values, we can define a meaningful default behavior. If someone calls the method `move_rocket()` with no parameters, the rocket will simply move up one unit in the y-direciton. Note that this method can be given negative values to move the rocket left or right:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Rocket():\n",
- " # Rocket simulates a rocket ship for a game,\n",
- " # or a physics simulation.\n",
- " \n",
- " def __init__(self, x=0, y=0):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = x\n",
- " self.y = y\n",
- " \n",
- " def move_rocket(self, x_increment=0, y_increment=1):\n",
- " # Move the rocket according to the paremeters given.\n",
- " # Default behavior is to move the rocket up one unit.\n",
- " self.x += x_increment\n",
- " self.y += y_increment\n",
- "\n",
- " \n",
- "# Create three rockets.\n",
- "rockets = [Rocket() for x in range(0,3)]\n",
- "\n",
- "# Move each rocket a different amount.\n",
- "rockets[0].move_rocket()\n",
- "rockets[1].move_rocket(10,10)\n",
- "rockets[2].move_rocket(-10,0)\n",
- " \n",
- "# Show where each rocket is.\n",
- "for index, rocket in enumerate(rockets):\n",
- " print(f\"Rocket {index} is at ({rocket.x}, {rocket.y}).\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Adding a new method\n",
- "---\n",
- "One of the strengths of object-oriented programming is the ability to closely model real-world phenomena by adding appropriate attributes and behaviors to classes. One of the jobs of a team piloting a rocket is to make sure the rocket does not get too close to any other rockets. Let's add a method that will report the distance from one rocket to any other rocket. Note how this method uses another instance of the same class as one of its arguments!\n",
- "\n",
- "If you are not familiar with distance calculations, there is a fairly simple formula to tell the distance between two points if you know the x and y values of each point. This new method performs that calculation, and then returns the resulting distance."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "from math import sqrt\n",
- "\n",
- "class Rocket:\n",
- " # Rocket simulates a rocket ship for a game,\n",
- " # or a physics simulation.\n",
- " \n",
- " def __init__(self, x=0, y=0):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = x\n",
- " self.y = y\n",
- " \n",
- " def move_rocket(self, x_increment=0, y_increment=1):\n",
- " # Move the rocket according to the paremeters given.\n",
- " # Default behavior is to move the rocket up one unit.\n",
- " self.x += x_increment\n",
- " self.y += y_increment\n",
- " \n",
- " def get_distance(self, other_rocket):\n",
- " # Calculates the distance from this rocket to another rocket,\n",
- " # and returns that value.\n",
- " distance = sqrt((self.x-other_rocket.x)**2+(self.y-other_rocket.y)**2)\n",
- " return distance\n",
- " \n",
- "# Make two rockets, at different places.\n",
- "rocket_0 = Rocket()\n",
- "rocket_1 = Rocket(10,5)\n",
- "\n",
- "# Show the distance between them.\n",
- "distance = rocket_0.get_distance(rocket_1)\n",
- "print(f\"The rockets are {distance:.6f} units apart.\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "<img src=\"https://surfdrive.surf.nl/files/index.php/apps/files_sharing/ajax/publicpreview.php?x=1920&y=452&a=true&file=distance.png&t=DVIenuADtGb249E&scalingup=0\" alt=\"Distance between rockets\" border=\"0\" width=\"600\" align=\"left\"/>"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Hopefully these short refinements show that you can extend a class' attributes and behavior to model the phenomena you are interested in as closely as you want. The rocket could have a name, a crew capacity, a payload, a certain amount of fuel, and any number of other attributes. You could define any behavior you want for the rocket, including interactions with other rockets and launch facilities, gravitational fields, and whatever you need it to! There are techniques for managing these more complex interactions, but what you have just seen is the core of object-oriented programming."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Encapsulation\n",
- "===\n",
- "As we have mentioned before using dictionaries is not useful to create objects that consist of several attributes. Encapsulation entails the wrapping of attributes and methods within one unit. This is beneficial as it enables engineers to write code that is easy to maintain. For example, if you add a new attribute or a method to a class, you will not need to update all your objects, but only the class itself.\n",
- "\n",
- "A nice feature that encapsulation provides is private attributes and private methods. Those are units, which are meant to only be used internally in a class and not accessed outside of it. By convention programmers should not access them via the object. Furthermore, in order to create a private attribute or a private method, you need to put 2 leading underscores (`_`) before their name.\n",
- "\n",
- "You can think of the `__init__` method for an example. You are not supposed to call the method, as it is automatically called when you create a new object. Furthermore, note that it has 2 leading and 2 trailing underscores. This is meant to show that this method is resereved in Python. **Therefore, you should not make attributes or methods that have both leading and trailing underscores, because you may mess up how Python works**. Besides the `__init__` method, there are more built-in methods that start and end with 2 underscores. These are called **magic methods**, and determine the behaviour when certain operations (for example: +, - or `print()`) are performed on an object.\n",
- "\n",
- "Have a look at the Rocket class below, which contains a private attribute `creation_date`. We will call this attribute `__creation_date` to tell Python that we want it to be private. This attribute is set inside the `__init__` method and should not be accessed outside the class unless we create a method, which returns it:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "from math import sqrt\n",
- "import datetime\n",
- "\n",
- "class Rocket:\n",
- " # Rocket simulates a rocket ship for a game,\n",
- " # or a physics simulation.\n",
- " \n",
- " def __init__(self, x=0, y=0):\n",
- " # Each rocket has an (x,y) position.\n",
- " self.x = x\n",
- " self.y = y\n",
- " self.__creation_time = datetime.datetime.now()\n",
- " \n",
- " def move_rocket(self, x_increment=0, y_increment=1):\n",
- " # Move the rocket according to the paremeters given.\n",
- " # Default behavior is to move the rocket up one unit.\n",
- " self.x += x_increment\n",
- " self.y += y_increment\n",
- " \n",
- " def get_distance(self, other_rocket):\n",
- " # Calculates the distance from this rocket to another rocket,\n",
- " # and returns that value.\n",
- " distance = sqrt((self.x-other_rocket.x)**2+(self.y-other_rocket.y)**2)\n",
- " return distance\n",
- " \n",
- " def get_creation_time(self):\n",
- " # Returns the time the Rocket was made.\n",
- " return self.__creation_time\n",
- " \n",
- "# Make a rocket.\n",
- "rocket_0 = Rocket()\n",
- "\n",
- "# Try to get the creation time via a method.\n",
- "date = rocket_0.get_creation_time()\n",
- "print(f\"Rocket was made in: {date}\")\n",
- "\n",
- "# Try to get the creation time directly.\n",
- "date = rocket_0.__creation_time\n",
- "print(f\"Rocket was made in: {date}\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "As seen in the example above, we can only access `__creation_time` via the method `get_creation_time` and get an `AttributeError` if we attempt to directly use the *dot notation* on the object `rocket_0`."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Inheritance\n",
- "===\n",
- "Another of the most important goals of the object-oriented approach to programming is the creation of stable, reliable, reusable code. If you had to create a new class for every kind of object you wanted to model, you would hardly have any reusable code. In Python and any other language that supports OOP, one class can **inherit** from another class. This means you can base a new class on an existing class; the new class *inherits* all of the attributes and behavior of the class it is based on. A new class can override any undesirable attributes or behavior of the class it inherits from, and it can add any new attributes or behavior that are appropriate. The original class is called the **parent** class or **superclass**, and the new class is a **child** or **subclass** of the parent class.\n",
- "\n",
- "The child class inherits all attributes and behavior from the parent class, but any attributes that are defined in the child class are not available to the parent class. This may be obvious to many people, but it is worth stating. This also means a child class can ***override*** behavior of the parent class. If a child class defines a method that also appears in the parent class, objects of the child class will use the new method rather than the parent class method.\n",
- "\n",
- "To better understand inheritance, let's look at an example of a class that can be based on the Rocket class."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The Shuttle class\n",
- "---\n",
- "If you wanted to model a space shuttle, you could write an entirely new class. But a space shuttle is just a special kind of rocket. Instead of writing an entirely new class, you can inherit all of the attributes and behavior of a Rocket, and then add a few appropriate attributes and behavior for a Shuttle.\n",
- "\n",
- "One of the most significant characteristics of a space shuttle is that it can be reused. So the only difference we will add at this point is to record the number of flights the shutttle has completed. Everything else you need to know about a shuttle has already been coded into the Rocket class.\n",
- "\n",
- "Here is what the Shuttle class looks like:\n",
- "\n",
- "<img src=\"https://surfdrive.surf.nl/files/index.php/apps/files_sharing/ajax/publicpreview.php?x=1920&y=452&a=true&file=shuttle-boosters-colour.png&t=O5AhNTVFPoYB0Iv&scalingup=0\" alt=\"Shuttle image\" border=\"0\" width=\"200\" align=\"left\"/>"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Shuttle(Rocket):\n",
- " # Shuttle simulates a space shuttle, which is really\n",
- " # just a reusable rocket.\n",
- " \n",
- " def __init__(self, x=0, y=0, flights_completed=0):\n",
- " super().__init__(x, y)\n",
- " self.flights_completed = flights_completed\n",
- " \n",
- "shuttle = Shuttle(10,0,3)\n",
- "print(shuttle.x)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "When a new class is based on an existing class, you write the name of the parent class in parentheses when you define the new class:\n",
- "```python\n",
- "class NewClass(ParentClass):\n",
- "```"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The `__init__()` function of the new class needs to call the `__init__()` function of the parent class. The `__init__()` function of the new class needs to accept all of the parameters required to build an object from the parent class, and these parameters need to be passed to the `__init__()` function of the parent class. The `super().__init__()` function takes care of this:\n",
- "\n",
- "```python\n",
- "class NewClass(ParentClass):\n",
- " \n",
- " def __init__(self, arguments_parent_class, arguments_new_class):\n",
- " super().__init__(arguments_parent_class)\n",
- " # Code for initializing an object of the new class.\n",
- "```"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The `super()` function passes the *self* argument to the parent class automatically."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Inheritance is a powerful feature of object-oriented programming. Using just what you have seen so far about classes, you can model an incredible variety of real-world and virtual phenomena with a high degree of accuracy. The code you write has the potential to be stable and reusable in a variety of applications."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Polymorphism\n",
- "===\n",
- "Another important goal of the object-oriented approach to programming is to provide flexibility of your code. This can be achived by Polymorphism, which entails that an entity is able to take multiple forms. In Python polymorphism allows us to create methods in a child class with the same name as a method in a parent class. This would mean that a method can serve one purpose in a parent class and different one in a child class.\n",
- "\n",
- "Child classes inherit all the methods of their parent classes, however, sometimes those methods need to be modified to fit the function of the child. This is achieved by reimplementing the parent methods in the child class.\n",
- "\n",
- "To better understand polymorphism, let's look at an example of a class that can be based on the Shuttle class and transitively on the Rocket class as well."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The ImprovedShuttle class\n",
- "---\n",
- "Our Shuttle class already improves the basic Rocket class, however, the information we receive from the Rocket class such as `get_distance` is very limited. This is because we currently only get information about the absolute distance, but we do not know the direction, which we need to face to get to that place the fastest.\n",
- "\n",
- "Therefore, we will create an improved Shuttle, which will be based on the initial Shuttle and will provide better distance information such as angle in which we need to rotate. The formula used is based on taking arctangent of the 2-dimension distances and transforming from radians to degrees.\n",
- "\n",
- "Here is what the ImprovedShuttle class looks like:\n",
- "\n",
- "<img src=\"https://surfdrive.surf.nl/files/index.php/apps/files_sharing/ajax/publicpreview.php?x=1920&y=452&a=true&file=space-shuttle.png&t=Y8Vupg9FQNud80j&scalingup=0\" alt=\"ImprovedShuttle image\" border=\"0\" width=\"150\" align=\"left\"/>"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "from math import atan, pi, sqrt\n",
- "\n",
- "class ImprovedShuttle(Shuttle):\n",
- " # Improved Shuttle that provides better distance information\n",
- " # such as angle.\n",
- " \n",
- " def __init__(self, x=0, y=0, flights_completed=0):\n",
- " super().__init__(x, y)\n",
- " self.flights_completed = flights_completed\n",
- " \n",
- " def get_distance(self, other_rocket):\n",
- " # Calculates the distance from this rocket to another rocket,\n",
- " # the angle to rotate to face the other rocket,\n",
- " # and returns those values.\n",
- " distance = super().get_distance(other_rocket)\n",
- " angle = atan((other_rocket.y - self.y) / (other_rocket.x - self.x)) * (180 / pi)\n",
- " return distance, angle\n",
- " \n",
- "improvedShuttle = ImprovedShuttle(10,0,3)\n",
- "otherShuttle = ImprovedShuttle(13, 3)\n",
- "\n",
- "# Show the distance between them.\n",
- "distance, angle = improvedShuttle.get_distance(otherShuttle)\n",
- "print(f\"The shuttles are {distance:.6f} units apart.\")\n",
- "print(f\"The angle the initial shuttle needs to rotate in case it needs to go to the other shuttle is {angle:.2f} degrees.\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "As you can see in the example above, since ImprovedShuttle inherits Shuttle and Shuttle inherits Rocket, then transitively ImprovedShuttle is a child of Rocket class and has access to the parent `get_distance` method. It is possible to access that parent method by making a `super().get_distance()` call.\n",
- "\n",
- "As a result, class ImprovedShuttle has ***overridden*** Rocket's get_distance. This means that it has reimplemented the parent's method.\n",
- "\n",
- "It is important to mention that it is not necessary to override (reimplement) every method in the parent class when using inheritance, but if needed, it is possible. \n",
- "\n",
- "> Note: ImprovedShuttle's get_distance() now returns two outputs, while the parent class only returns one. Imagine you are looping a list containing a mix of Rockets and ImprovedShuttles to store their distance in an array (with as many elements as the length of the lists); this difference in the output may require some extra lines of code to handle potential problems."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "**Exercise:** It is time to practice what you have learned so far about classes, inheritance, and polymorphism.\n",
- "Given the predefined Person class, create a Student and Teacher classes that inherit from People and have the additional following requirements\n",
- "\n",
- "1. Create a class Student:\n",
- " 1. Make class Student inherit class Person;\n",
- " 2. Add parameters `start year` and `GPA grade` in the `__init__` method and reuse the parent constructor for the other attributes;\n",
- " 3. Create a method `change_grade`, which sets a new grade for the student;\n",
- " 4. Override the `introduce_yourself` method to account for the 2 new fields (start year and GPA grade). In your overriding try to reuse the parent `introduce_yourself` method implementation by calling `super()`;\n",
- "\n",
- "2. Create a class Teacher:\n",
- " 1. Make class Teacher inherit class Person;\n",
- " 2. Add an attribute called `students` of type `set` in the `__init__` method and reuse the parent constructor for the other attributes. Remember that a set is a collection of elements that contains no duplicates. A set can be initialised in multiple ways. For example, `my_set = set()` or `my_set = {}`;\n",
- " 3. Create a method `add_student`, which adds a student to the student set of a teacher. Elements to a set can be added using the method `add()`. For example, `my_set.add(3)`;\n",
- " 4. Create a method `print_classroom`, which prints the introductions of all the students in the classroom of the teacher. (Hint: call `introduce_yourself` on every Student object in the set).\n",
- " \n",
- "3. Similarly to the previous exercise, show your new classes are working properly by creating objects for each of them and calling their respective methods. Furthermore, add the necessary documentation for the classes and methods."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Person():\n",
- " def __init__(self, name, age, country_of_origin):\n",
- " \"\"\"Constructor to initialise a Person object.\n",
- " \n",
- " Keyword arguments:\n",
- " name -- the name of the person\n",
- " age -- the age of the person\n",
- " country_of_origin -- the country the person was born\n",
- " \"\"\"\n",
- " self.__name = name\n",
- " self.age = age\n",
- " self.country_of_origin = country_of_origin\n",
- " \n",
- " def introduce_yourself(self):\n",
- " \"\"\"Prints a brief introduction of the person.\"\"\"\n",
- " print(f\"Hello, my name is {self.__name}, I am {self.age} and I am from {self.country_of_origin}.\")\n",
- " \n",
- " def get_name(self):\n",
- " \"\"\"Gets the name of a person.\"\"\"\n",
- " return self.__name"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "\"\"\"Start of student exercise\"\"\"\n",
- "class Student(Person):\n",
- " def __init__(self, name, age, country_of_origin, start_year, gpa_grade):\n",
- " \"\"\"Constructor to initialise a Student object.\n",
- " \n",
- " Keyword arguments:\n",
- " name -- the name of the student\n",
- " age -- the age of the student\n",
- " country_of_origin -- the country the student was born\n",
- " start_year -- the year the education of the student began\n",
- " gpa_grade -- current gpa_grade of a student\n",
- " \"\"\"\n",
- " super().__init__(name, age, country_of_origin)\n",
- " self.start_year = start_year\n",
- " self.gpa_grade = gpa_grade\n",
- " \n",
- " def introduce_yourself(self):\n",
- " \"\"\"Prints a brief introduction of the student.\"\"\"\n",
- " super().introduce_yourself()\n",
- " print(f\"My GPA grade is {self.gpa_grade} and I started studying in year {self.start_year}.\")\n",
- " \n",
- " def change_grade(self, new_grade):\n",
- " \"\"\"Modifies current GPA grade of the student.\"\"\"\n",
- " self.gpa_grade = new_grade\n",
- "\n",
- "class Teacher(Person):\n",
- " def __init__(self, name, age, country_of_origin):\n",
- " \"\"\"Constructor to initialise a Teacher object.\n",
- " \n",
- " Keyword arguments:\n",
- " name -- the name of the teacher\n",
- " age -- the age of the teacher\n",
- " country_of_origin -- the country the teacher was born\n",
- " \"\"\"\n",
- " super().__init__(name, age, country_of_origin)\n",
- " self.students = set()\n",
- " \n",
- " def add_student(self, student):\n",
- " \"\"\"Adds a student to the classroom of a teacher.\n",
- " \n",
- " Keyword arguments:\n",
- " studnet -- student to add to the classroom\n",
- " \"\"\"\n",
- " self.students.add(student)\n",
- " \n",
- " def print_classroom(self):\n",
- " \"\"\"Prints the classroom of a teacher.\"\"\"\n",
- " print(\"The classroom consists of the following students:\")\n",
- " for student in self.students:\n",
- " student.introduce_yourself()\n",
- "\n",
- "\"\"\"End of student exercise\"\"\"\n",
- "\n",
- "print(\"Showing how class Student is defined:\")\n",
- "student = Student(\"Mike\", 22, \"Italy\", \"2021\", 7.3)\n",
- "\n",
- "student.change_grade(7.2)\n",
- "print(f\"New GPA grade of student is {student.gpa_grade}.\")\n",
- "print()\n",
- "\n",
- "print(\"Showing how class Teacher is defined:\")\n",
- "teacher = Teacher(\"Joe\", 42, \"Germany\")\n",
- "teacher.introduce_yourself()\n",
- "teacher.add_student(student)\n",
- "\n",
- "teacher.print_classroom()"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Additional information (optional)\n",
- "==="
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Revisiting PEP 8\n",
- "===\n",
- "If you recall, [PEP 8](http://www.python.org/dev/peps/pep-0008) is the style guide for writing Python code. Another document, [PEP 257](https://peps.python.org/pep-0257/), covers conventions for writing docstrings. As PEP 8 does not have as many rules as PEP 257 related to documentation of classes and methods, we will briefly cover the regulations on documenting your classes:"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Naming conventions\n",
- "---\n",
- "[Class names](http://www.python.org/dev/peps/pep-0008/#class-names) should be written in *CamelCase*, with an initial capital letter and any new word capitalized. There should be no underscores in your class names. For example, if you have a super cool class, you should name it `ASuperCoolClass`.\n",
- "\n",
- "[Method names](https://peps.python.org/pep-0008/#function-and-variable-names) should always have an initial lowercase letter, similar to the regulations on naming functions. Furthermore, the first argument of every class method should be the keyword `self`. For example, the method signature (the same as function signature - the function name and function arguments) of a method `move_up()` should be `move_up(self):`. Nevertheless, if a method name contains more than 1 word, then the words should be separated by underscore `_`. For instance, if you have an important method, you should name it `important_method`."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Docstrings\n",
- "---\n",
- "A docstring is a string literal that appears at the start of classes/methods.\n",
- "\n",
- "By convention, docstrings begin and end with 3 quotation marks: `\"\"\"docstring\"\"\"` and should be placed right below the signature of a method or the class signature. A rule of thumb is to have 1 line explaning what a method does, followed by 1 blank line, followed by zero/one/multiple lines explaning what each of the parameter does:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "class Rocket():\n",
- " \"\"\"Rocket simulates a rocket ship for a game,\n",
- " or a physics simulation.\n",
- " \"\"\"\n",
- " \n",
- " def __init__(self, x=0, y=0):\n",
- " \"\"\"Constructor to initialise a Rocket object.\n",
- " \n",
- " Keyword arguments:\n",
- " x -- x coordinate (default 0)\n",
- " y -- y coordinate (default 0)\n",
- " \"\"\"\n",
- " self.x = x\n",
- " self.y = y\n",
- "\n",
- " def move_rocket(self, x_increment=0, y_increment=1):\n",
- " \"\"\"Moves the rocket according to the paremeters given.\n",
- " \n",
- " Keyword arguments:\n",
- " x_increment -- units to move in x dimension (default 0)\n",
- " y_increment -- units to move in y dimension (default 1)\n",
- " \"\"\"\n",
- " self.x += x_increment\n",
- " self.y += y_increment\n",
- " \n",
- " def get_distance(self, other_rocket):\n",
- " \"\"\"Calculates the distance from this rocket to another rocket\n",
- " and returns that value.\n",
- " \n",
- " Keyword arguments:\n",
- " other_rocket -- the other rocket, which distance to compare to\n",
- " \"\"\"\n",
- " distance = sqrt((self.x-other_rocket.x)**2+(self.y-other_rocket.y)**2)\n",
- " return distance\n",
- " \n",
- "# Check the documentation of Rocket class\n",
- "help(Rocket)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Note that the *self* argument is not explained the docstrings, because its use is implicitly known."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## References and used resources\n",
- "- http://introtopython.org/"
- ]
- }
- ],
- "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.12.0"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
diff --git a/book/programming/python_topics/modules_solution.ipynb b/book/programming/python_topics/modules_solution.ipynb
deleted file mode 100644
index d562070d..00000000
--- a/book/programming/python_topics/modules_solution.ipynb
+++ /dev/null
@@ -1,565 +0,0 @@
-{
- "cells": [
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Modules"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Contents\n",
- "===\n",
- "- [Introduction](#Introduction)\n",
- "- [Modules and classes](#Modules-and-classes)\n",
- " - [Storing a single class in a module](#Storing-a-single-class-in-a-module)\n",
- " - [Storing multiple classes in a module](#Storing-multiple-classes-in-a-module)\n",
- " - [A number of ways to import modules and classes, functions and variables](#A-number-of-ways-to-import-modules-of-classes,-functions-and-variables)\n",
- " - [A module of functions and variables](#A-module-of-functions-and-variables)\n",
- "- [How does module importing work](#How-does-module-importing-work)\n",
- "- [Modules and PEP8](#Modules-and-PEP8)\n",
- " - [Multiple imports](#Multiple-imports)\n",
- " - [Ordering imports](#Ordering-imports)\n",
- "- [Exercises](#Exercises)\n",
- "- [Optional material](#Optional-material)\n",
- " - [Command line arguments with `sys.argv`](#Command-line-arguments-with-sys.argv)\n",
- " - [Parsing command line arguments with `argparse`](#Parsing-command-line-arguments-with-argparse)"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Introduction\n",
- "Programming tasks usually require writing several lines of code which are much better organized in a **modular** fashion, rather than in single, extremely long Jupyter notebooks (or .py script files). Modularization refers to splitting such large programming tasks into smaller, separate, and more manageable subtasks. Python scripts are modularized through **functions**, **classes**, **modules**, and **packages**.\n",
- "\n",
- "While you should be already familiar with *functions* and *classes*, you should think of *modules* as a `.py` files containing Python functions, classes, definitions and statements. On the other hand, a package is a set of modules, i.e., a collection of `.py` files organized in folders and subfolders. Python accesses the modules in a package by referencing the package name.\n",
- "\n",
- "Modularity has the added advantage of isolating your code blocks into files that can be used in any number of different programs. Futhermore, if you want to extend their functionality, you would not need to modify multiple files, but only the file they reside in.\n",
- "\n",
- "You have been using Pyhon modularization all along, maybe without even realizing it.\n",
- "\n",
- "Here is a quick example:\n",
- "\n",
- "```python\n",
- "from matplotlib.pyplot import subplots\n",
- "``` \n",
- "\n",
- "which follows the format:\n",
- "\n",
- "```python\n",
- "from package_name.module_name import function_name\n",
- "``` \n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Modules and classes\n",
- "===\n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Storing classes in a module\n",
- "---\n",
- "\n",
- "A module is simply a file that contains one or more classes or functions, so the Shuttle and Rocket classes can also be in the same file. \n",
- "\n",
- "Now you can import the Rocket and the Shuttle class, and use them both in a clean uncluttered program file:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "from space import Rocket, Shuttle\n",
- "\n",
- "rocket = Rocket()\n",
- "print(f\"The rocket is at ({rocket.x}, {rocket.y}).\")\n",
- "\n",
- "shuttle = Shuttle()\n",
- "shuttle.move_rocket()\n",
- "print(f\"The shuttle is at ({shuttle.x}, {shuttle.y}).\")\n",
- "print(f\"The shuttle has completed {shuttle.flights_completed} flights.\")\n",
- "\n",
- "print(f\"The distance between the rocket and the shuttle is ({rocket.get_distance(shuttle)}).\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The first line tells Python to import both the *Rocket* and the *Shuttle* classes from the *rocket* module. You don't have to import every class in a module; you can pick and choose the classes you care to use, and Python will only spend time processing those particular classes."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "A number of ways to import modules of classes, functions and variables\n",
- "---\n",
- "There are several ways to import modules, and each has its own merits. We illustrate mainly how you can import classes, however, you can import functions and variables in the exact same way:"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### from *module_name* import *ClassName*\n",
- "\n",
- "The syntax for importing classes that was just shown:\n",
- "```python\n",
- "from module_name import ClassName\n",
- "```\n",
- "is straightforward, and is used quite commonly. It allows you to use the class names directly in your program, so you have very clean and readable code. "
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### import *module_name*\n",
- "\n",
- "Directly using the class names from a module can be a problem if the names of the classes you are importing conflict with names that have already been used in the program you are working on. For example, if a module contains a function or a class with the same name as one you have defined in your notebook. Have a look at the code cell below, where we have a Rocket class in the current cell and a Rocket class in module `space`:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "from space import Rocket\n",
- "\n",
- "class Rocket:\n",
- " def __init__(self, name):\n",
- " self.name = name\n",
- "\n",
- "# Instatiate a class from the current file\n",
- "rocket = Rocket(\"Ariance\")\n",
- "print(f\"The rocket is called {rocket.name}.\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The Rocket defined in the cell is taking precedence before the Rocket class in module `space`. For instance, the Rocket class in the module has no field `name`. Thus, it is not possible to directly use that class. In order to mitigate this, we can make use of the dot notation:\n",
- "\n",
- "The general syntax for this kind of import is:\n",
- "```python\n",
- "import module_name\n",
- "```\n",
- "\n",
- "After this, classes are accessed using dot notation:\n",
- "```python\n",
- "module_name.ClassName\n",
- "```"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "import space\n",
- "\n",
- "class Rocket:\n",
- " def __init__(self, name):\n",
- " self.name = name\n",
- "\n",
- "# Instatiate a class from the current file\n",
- "new_rocket = Rocket(\"Ariance\")\n",
- "print(f\"The rocket is called {new_rocket.name}.\")\n",
- "\n",
- "# Instatiate a class from module rocket\n",
- "module_rocket = space.Rocket()\n",
- "print(f\"\\nThe rocket is at ({module_rocket.x}, {module_rocket.y}).\")\n",
- "print(f\"The distance between the same rocket is ({module_rocket.get_distance(module_rocket)}).\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "This prevents some name conflicts. If you were reading carefully however, you might have noticed that the variable name *rocket* in the previous example had to be changed because it has the same name as the module itself. This is not good, because in a longer program that could mean a lot of renaming."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### import *module_name* as *local_module_name*\n",
- "\n",
- "There is another syntax for imports that is quite useful:\n",
- "```python\n",
- "import module_name as local_module_name\n",
- "```\n",
- "When you are importing a module into one of your projects, you are free to choose any name you want for the module in your project. So the last example could be rewritten in a way that the variable name *rocket* would not need to be changed:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "import space as space_module\n",
- "\n",
- "rocket = space_module.Rocket()\n",
- "print(f\"The rocket is at ({rocket.x}, {rocket.y}).\")\n",
- "\n",
- "shuttle = space_module.Shuttle()\n",
- "shuttle.move_rocket()\n",
- "print(f\"The shuttle is at ({shuttle.x}, {shuttle.y}).\")\n",
- "print(f\"The shuttle has completed {shuttle.flights_completed} flights.\")\n",
- "\n",
- "print(f\"The distance between the rocket and the shuttle is ({rocket.get_distance(shuttle)}).\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "This approach is often used to shorten the name of the module, so you don't have to type a long module name before each class name that you want to use. But it is easy to shorten a name so much that you force people reading your code to scroll to the top of your file and see what the shortened name stands for. In this example, you can abbreviate space to something like:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "import space as s"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Of course there are well known shortening examples, which you might have already seen:\n",
- "```python\n",
- "import numpy as np\n",
- "import matplotlib.pyplot as plt\n",
- "import pandas as pd\n",
- "```"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### from *module_name* import *\n",
- "There is one more import syntax that you should be aware of, but *you should probably avoid using*. This syntax imports **all of the available classes, all functions in a module and all variables in a module**. Note that functions or variables, which have leading underscore `_` in their name are excluded from this rule. Similarly to encapsulation in OOP, they are considered private:\n",
- "\n",
- "```python\n",
- "from module_name import *\n",
- "```\n",
- "\n",
- "This is not recommended, for a couple reasons. First of all, you may have no idea what all the names of the classes and functions in a module are. If you accidentally give one of your variables the same name as a name from the module, you will have naming conflicts. Also, you may be importing way more code into your program than you need.\n",
- "\n",
- "If you really need all the functions and classes from a module, just import the module and use the `module_name.ClassName` syntax in your program."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "You will get a sense of how to write your imports as you read more Python code, and as you write and share some of your own code."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "How does module importing work\n",
- "===\n",
- "Python has built-in modules, which are accessible anywhere. Examples of those are `sys`, `math`, `random`. For a full list, check the following link: https://docs.python.org/3/py-modindex.html\n",
- "\n",
- "When importing modules, Python searches for modueles in the following order:\n",
- "1. Looks if the module name matches any of the names in the index above. \n",
- "2. Searches for a python file in the same working directory as the file, which imports it\n",
- "3. Looks at PYTHONPATH - we will not cover this, but you can think of it as the default search path for modules\n",
- "4. Goes over installed packages if any match\n",
- "\n",
- "As a result, if you have the `numpy` package installed, but you also have a file `numpy.py` in the same working directory, Python will import the local file instead of the installed package. You should avoid naming modules after standard built-in modules or standard packages such as `numpy` or `matplotlib`."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Modules and PEP8\n",
- "===\n",
- "Modules also have their own list of rules in PEP8 Style guide:\n",
- "\n",
- "Multiple imports\n",
- "---\n",
- "In the case that we have multiple modules that we wish to import simultaneously, there are some requirements to follow. **Module imports should be done in multiple lines**. For instance, if you have the modules `os` and `sys`, it is recommended to use multiple `import` statements. In addition, modules within every group should be ordered **alphabetically**:\n",
- "```python\n",
- "import os\n",
- "import sys\n",
- "```\n",
- "The wrong way to do this is to import both of the modules on the same line:\n",
- "```python\n",
- "import os, sys\n",
- "```\n",
- "\n",
- "Ordering imports\n",
- "---\n",
- "Apart from separating every import in a new line, it is also important to group modules depending on their type. The correct order to import modules is the following:\n",
- "1. Standard library imports\n",
- "2. Related third party imports\n",
- "3. Local application/library specific imports\n",
- "\n",
- "Blank lines should be placed between each group.\n",
- "\n",
- "Here is an example of correct order of module imports:\n",
- "```python\n",
- "import os\n",
- "import sys\n",
- "\n",
- "import numpy as np\n",
- "import pandas as pd\n",
- "\n",
- "import rocket\n",
- "import shuttle\n",
- "```"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Exercises\n",
- "==="
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "from jupyterquiz import display_quiz\n",
- "\n",
- "display_quiz(\"https://surfdrive.surf.nl/files/index.php/s/wHKH0oP3SmbZHLP/download\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Optional material\n",
- "===\n",
- "The material in the subsections below is considered optional. Therefore, it is not mandatory to study and if you wish, you may skip it."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Command line arguments with `sys.argv`\n",
- "---\n",
- "Python files can also be used as scripts, which can run speicific tasks. For example, it is possible to create a python file, which when run executes pieces of code. For example, the code below will run a python script(file) and create an image `weather.png`, which displays temperatures over a period of time:"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Currently, we are reading from an old dataset, however, imagine that we were getting the data from a server, which adds more data everyday or even every hour to the dataset. Then it would be very convenient to regularly run this script and observe the changes via a graph. \n",
- "\n",
- "Although this looks easy to use, it is not very flexible, because we need to modify the script every time we run it if we want different periods of time or different plot file names. Hence, there is a solution to this setback in the `sys` module. More specifically by command line arguments in `sys.argv`. Command line arguments can be thought of as arguments you pass to a function.\n",
- "\n",
- "For example, suppose we could pick different start and end date of observations simply by passing those two values as arguments to the python file:\n",
- "```bash\n",
- "python weather_script.py \"01/03/2021\" \"31/05/2021\"\n",
- "```\n",
- "Here `weather_script.py` can be thought of as a function, which takes 2 arguments - start and end date.\n",
- "\n",
- "To achieve this, we the code uses as dates `sys.argv[index]` statements:\n",
- "```python\n",
- "import sys\n",
- "import pandas as pd\n",
- "import matplotlib.pyplot as plt\n",
- "\n",
- "...\n",
- "\n",
- "# set start and end time\n",
- "start_date = pd.to_datetime(sys.argv[1],dayfirst=True)\n",
- "end_date = pd.to_datetime(sys.argv[2],dayfirst=True)\n",
- "\n",
- "# preprocess the data\n",
- "\n",
- "...\n",
- "\n",
- "fig.savefig('weather.png')\n",
- "```"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "! python weather_script.py \"01/03/2021\" \"31/05/2021\"\n",
- "\n",
- "# Display the generated image\n",
- "from IPython import display\n",
- "display.Image(\"./weather.png\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Parsing command line arguments with `argparse`\n",
- "---\n",
- "We can take command line arguements a step further via the module `argparse`, which provides even more flexibility. For instance, you can have optional arguments with default values, arguments help, argument types and much more as described here: https://docs.python.org/3/library/argparse.html. We will briefly cover the basics of this module in this section."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Remember how Git has the command `git help` and also how we pass arguments using dash (`-`)? For example, when we are making a commit, we can pass the message in multiple ways:\n",
- "\n",
- "```bash\n",
- "git commit -m \"My first commit\"\n",
- "git commit --message \"My first commit\"\n",
- "```\n",
- "`argparse` module adds the same quirks of getting help and also having long and short arguments. To add `argparse` to our script, we need to rewrite the way we are getting the `start_date` and `end_date` as follows:\n",
- "```python\n",
- "import argparse\n",
- "import pandas as pd\n",
- "import matplotlib.pyplot as plt\n",
- "\n",
- "...\n",
- "\n",
- "parser = argparse.ArgumentParser()\n",
- "# set start and end time\n",
- "parser.add_argument('-s', '--start', type=str, default=\"1/1/2019\", help=\"Start time\")\n",
- "parser.add_argument('-e', '--end', type=str, default=\"1/1/2021\", help=\"End time\")\n",
- "\n",
- "args = parser.parse_args()\n",
- "\n",
- "start_date = pd.to_datetime(args.start,dayfirst=True)\n",
- "end_date = pd.to_datetime(args.end,dayfirst=True)\n",
- "\n",
- "# preprocess the data\n",
- "\n",
- "...\n",
- "\n",
- "fig.savefig('weather.png')\n",
- "```\n",
- "Note that if an argument is not passed to a script, it has a default value, which will be used"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "**Exercise:** Copy `weather_script` into a new python file called `weather_script_improved` (note you need to create that file yourself). Then, modify the new file as described above to make use of `argparse`. Finally, run the code cell below to verify your code is working. The expected output is a graph, which contains temperatures only in the range 01/03/2021 - 31/05/2021. Note that we can use both long and short versions of arguments."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "! python weather_script_improved.py -s \"01/03/2021\" --end \"31/05/2021\" --output \"weather.png\"\n",
- "\n",
- "# Display the generated image\n",
- "from IPython import display\n",
- "display.Image(\"./weather.png\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Run the next cell to check what arguments can be passed to the script:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "scrolled": true
- },
- "outputs": [],
- "source": [
- "! python weather_script_argparse.py --help"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "It looks similar to how git shows its help, right?"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "! git --help"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# References and used resources\n",
- "- http://introtopython.org/\n",
- "- https://aaltoscicomp.github.io/python-for-scicomp/scripts/#scripts\n",
- "- https://www.learnpython.org/en/Modules_and_Packages\n",
- "- https://docs.python.org/3/tutorial/modules.html"
- ]
- }
- ],
- "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.12.0"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
--
GitLab