05 Library functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "A feature of modern programming languages is an extensive library of *standard functions*. This means that we can make use of well-tested and optimised functions for performing common tasks rather than writing our own. This makes our programs shorter and of higher quality, and in most cases faster.\n",
    "\n",
    "## Objectives\n",
    "\n",
    "- Introduce use of standard library functions\n",
    "- Importing and using modules\n",
    "- Introduction to namespaces\n",
    "- Print formatting of floats\n",
    "- Accessing documentation for functions and modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The standard library\n",
    "\n",
    "You have already used some standard library types and functions. In previous activities we have used built-in types like `string` and `float`, and the function `abs` for absolute value. We have made use of the standard library function `print` to display to the screen.\n",
    "\n",
    "Python has a large standard library. To organise it, most functionality is arranged into 'modules', with each module providing a range of related functions. Before you program a function, check if there is a library function that can perform the task. The Python standard library is documented at https://docs.python.org/3/library/.\n",
    "Search engines are a good way to find library functions, e.g. entering \"Is there a Python function to compute the hyperbolic tangent of a complex number\" into a search engine will take you to the function `cmath.tanh`. Try this link: https://bfy.tw/7aMc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Other libraries\n",
    "\n",
    "The standard library tools are general purpose and will be available in any Python environment.\n",
    "Specialised tools are usually made available in other libraries (modules). There is a huge range of Python libraries available for specialised problems. We have already used some parts\n",
    "of NumPy (https://www.numpy.org/), which is a specialised library for numerical computation.\n",
    "\n",
    "The simplest way to install a non-standard library is using the command `pip`. From the command line, the library NumPy is installed using:\n",
    "\n",
    "    pip install numpy\n",
    "    \n",
    "and from inside a Jupyter notebook use:\n",
    "\n",
    "    %pip install numpy\n",
    "\n",
    "NumPy is so commonly used it is probably already installed on computers you will be using.\n",
    "You will see `pip` being used in some later notebooks to install special-purpose modules.\n",
    "\n",
    "When developing programs outside of learning exercises,\n",
    "if there is a no standard library module for a problem you are trying to solve, \n",
    "search online for a module before implementing your own.\n",
    "\n",
    "Let's make sure the libraries we need now and later are installed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: numpy in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (1.22.2)\n",
      "Note: you may need to restart the kernel to use updated packages.\n",
      "Requirement already satisfied: matplotlib in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (3.5.1)\n",
      "Requirement already satisfied: packaging>=20.0 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (21.3)\n",
      "Requirement already satisfied: fonttools>=4.22.0 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (4.29.1)\n",
      "Requirement already satisfied: python-dateutil>=2.7 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (2.8.2)\n",
      "Requirement already satisfied: cycler>=0.10 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (0.11.0)\n",
      "Requirement already satisfied: kiwisolver>=1.0.1 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (1.3.2)\n",
      "Requirement already satisfied: pyparsing>=2.2.1 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (3.0.6)\n",
      "Requirement already satisfied: numpy>=1.17 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (1.22.2)\n",
      "Requirement already satisfied: pillow>=6.2.0 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from matplotlib) (9.0.1)\n",
      "Requirement already satisfied: six>=1.5 in /home/studio-lab-user/.conda/envs/default/lib/python3.9/site-packages (from python-dateutil>=2.7->matplotlib) (1.16.0)\n",
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "%pip install numpy\n",
    "%pip install matplotlib\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using library functions: `math` example\n",
    "\n",
    "To use a function from a module we need to make it available in our program. \n",
    "This is called 'importing'. We have done this in previous notebooks with the `math` module, but without explanation. The process is explained below.\n",
    "\n",
    "The `math` module (https://docs.python.org/3/library/math.html) provides a wide range of mathematical functions. For example, to compute the square root of a number, we do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.4142135623730951\n"
     ]
    }
   ],
   "source": [
    "import math\n",
    "\n",
    "x = 2.0\n",
    "x = math.sqrt(x)\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dissecting the above code block, the line \n",
    "```python\n",
    "import math \n",
    "```\n",
    "makes the math module available in our program. It is good style to put all `import` statements at the top of a file (or at the top of a cell when using a Jupyter notebook). \n",
    "\n",
    "The function call\n",
    "```python\n",
    "x = math.sqrt(x)\n",
    "```    \n",
    "says 'use the `sqrt` function from the `math` module to compute the square root'.\n",
    "\n",
    "By prefixing `sqrt` with `math`, we are using a *namespace* (which in this case is `math`).\n",
    "This makes clear precisely which `sqrt` function we want to use - there could be more than one `sqrt` function available.\n",
    "\n",
    "> *Namespaces:* The prefix '`math`' indicates which '`sqrt`' function we want to use. This\n",
    "might seem pedantic, but in practice there are often different algorithms for performing the same or similar  operation. They might vary in speed and accuracy. In some applications we might need an accurate (but slow)  method for computing the square root, while for other applications we might need speed with a compromise on accuracy. But, if two functions have the same name and are not distinguished by a name space, we have a *name clash*.\n",
    "\n",
    "> In a large program, two developers might choose the same name for two functions that perform similar but slightly different tasks. If these functions are in different modules, there will be no name clash since the module name provides a 'namespace'  - a prefix that provides a distinction between the two functions. Namespaces are extremely helpful for multi-author programs. Older languages, like C and Fortran, might not support namespaces. Most modern languages do support namespaces.  \n",
    "\n",
    "We can import specific functions from a module, e.g. importing only the `sqrt` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.4142135623730951\n"
     ]
    }
   ],
   "source": [
    "from math import sqrt\n",
    "\n",
    "x = 2.0\n",
    "x = sqrt(x)\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This way, we are importing (making available) only the `sqrt` function from the `math` module (the `math` module has a large number of functions).\n",
    "\n",
    "We can even choose to re-name functions that we import:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.4142135623730951\n"
     ]
    }
   ],
   "source": [
    "from math import sqrt as some_math_function \n",
    "\n",
    "x = 2.0\n",
    "x = some_math_function(x)\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Renaming functions at import can be helpful to keep code short, and we will see below it can be useful for switching between different functions.\n",
    "However the above choice of name is very poor practice - the name '`some_math_function`' is not descriptive.\n",
    "Below is a more sensible example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Say we program a function that computes the roots of a quadratic function using the quadratic formula:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-0.10435607626104004 -2.3956439237389597\n"
     ]
    }
   ],
   "source": [
    "from math import sqrt as square_root\n",
    "\n",
    "def compute_roots(a, b, c):\n",
    "    \"Compute roots of the polynomial f(x) = ax^2 + bx + c\"\n",
    "    root0 = (-b + square_root(b*b - 4*a*c))/(2*a)\n",
    "    root1 = (-b - square_root(b*b - 4*a*c))/(2*a)\n",
    "    return root0, root1\n",
    "\n",
    "# Compute roots of f = 4x^2 + 10x + 1\n",
    "root0, root1 = compute_roots(4, 10, 1)\n",
    "print(root0, root1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above is fine as long as the polynomial has real roots. However, the function `math.sqrt` \n",
    "will give an error (technically, it will 'raise an exception') if a negative argument is passed to it. This is to stop naive mistakes.\n",
    "\n",
    "We do know about complex numbers, so we want to compute complex roots. The Python module `cmath` provides functions for complex numbers. If we were to use `cmath.sqrt` to compute the square root, our function would support complex roots. We do this by importing the `cmath.sqrt` functions as `square_root`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(-0.125+0.09682458365518543j) (-0.125-0.09682458365518543j)\n",
      "(-0.10435607626104004+0j) (-2.3956439237389597+0j)\n"
     ]
    }
   ],
   "source": [
    "# Use the function from cmath as square_root to compute the square root\n",
    "# (this will replace the previously imported sqrt function)\n",
    "from cmath import sqrt as square_root\n",
    "\n",
    "# Compute roots (roots will be complex in this case)\n",
    "root0, root1 = compute_roots(40, 10, 1)\n",
    "print(root0, root1)\n",
    "\n",
    "# Compute roots (roots will be real in this case, but cmath.sqrt always returns a complex type)\n",
    "root0, root1 = compute_roots(4, 10, 1)\n",
    "print(root0, root1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function now works for all cases because `square_root` is now using `cmath.sqrt`. Note that `cmath.sqrt` always returns a complex number type, even when the complex part is zero."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# String functions and string formatting\n",
    "\n",
    "A standard function that we have used from the start is '`print`'. This function turns arguments into a string and displays the string to the screen. So far, we have only printed simple variables and relied mostly on the default conversions to a string for printing to the screen (the exception was printing the floating point representation of 0.1, where we needed to specify the number of significant digits to see the inexact representation in binary)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Formatting\n",
    "\n",
    "We can control how strings are formatted and displayed. Below is an example of inserting a string variable and a number variable into a string of characters. Not the `f` before the string. This indicates it is a formatted string and that the variables should be inserted."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "My name is Amber and I am 19 years old.\n",
      "My name is Ashley and I am 21 years old.\n"
     ]
    }
   ],
   "source": [
    "# Format a string with name and age\n",
    "name = \"Amber\"\n",
    "age = 19\n",
    "text_string = f\"My name is {name} and I am {age} years old.\"\n",
    "\n",
    "# Print to screen \n",
    "print(text_string)\n",
    "\n",
    "# Short-cut for printing without assignment\n",
    "name = \"Ashley\"\n",
    "age = 21\n",
    "print(f\"My name is {name} and I am {age} years old.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For floating-point numbers we often want to control the formatting, and in particular the number of significant figures displayed. Using the display of $\\pi$ as an example: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The value of π using the default formatting is: 3.141592653589793\n",
      "The value of π to 5 significant figures is: 3.1416\n",
      "The value of π to 8 significant figures is: 3.1415927\n",
      "The value of π to 20 significant figures and using scientific notation is: 3.14159265358979311600e+00\n"
     ]
    }
   ],
   "source": [
    "# Import math module to get access to math.pi\n",
    "import math\n",
    "\n",
    "# Default formatting\n",
    "print(f\"The value of π using the default formatting is: {math.pi}\")\n",
    "\n",
    "# Control number of significant figures in formatting\n",
    "print(f\"The value of π to 5 significant figures is: {math.pi:.5}\")\n",
    "print(f\"The value of π to 8 significant figures is: {math.pi:.8}\")\n",
    "print(f\"The value of π to 20 significant figures and using scientific notation is: {math.pi:.20e}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are many more ways in which float formatting can be controlled - search online if you want to format a float in a particular way.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Module example: fractions and statistics\n",
    "\n",
    "Python has standard library support for fractions and statistical operations. Summing fractions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Fraction: 23/21\n",
      "Float: 1.0952380952380953\n"
     ]
    }
   ],
   "source": [
    "from fractions import Fraction\n",
    "\n",
    "f0 = Fraction(2, 3)\n",
    "f1 = Fraction(3, 7)\n",
    "result = f0 + f1\n",
    "print(\"Fraction:\", result)\n",
    "print(\"Float:\", float(result))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use the `statistics` module perform statistical operations on a list of numbers. In this example we will represent the numbers using `fractions.Fraction`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "numbers: [Fraction(1, 2), Fraction(2, 1), Fraction(1, 3), Fraction(1, 17), Fraction(-1, 13)]\n",
      "mean: 3733/6630\n",
      "mode: 1/2\n",
      "variance: 3060917/4395690 (0.6963450561800308)\n",
      "variance : 3060917/4395690 (0.6963450561800308)\n"
     ]
    }
   ],
   "source": [
    "import statistics\n",
    "\n",
    "data = [Fraction(1, 2), Fraction(2, 1), Fraction(1, 3), Fraction(1, 17), Fraction(-1, 13)]\n",
    "print(\"numbers:\", data)\n",
    "\n",
    "print(\"mean:\", statistics.mean(data))\n",
    "print(\"mode:\", statistics.mode(data))\n",
    "var = statistics.variance(data)\n",
    "#print(\"variance: {} ({})\".format(var, float(var))) #alterntiave way to format strings\n",
    "print(f\"variance : {var} ({float(var)})\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tab completion\n",
    "\n",
    "Tab completion is useful for seeing which functions a module provides. For example, after importing the `math` module type `math.` and press `tab`. This will show all the available functions in `math`. Typing `math.c` and pressing `tab` will show all the available functions that start with 'c'. Why not try this below..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Accessing function documentation\n",
    "\n",
    "The documentation for a function can be accessed using the `help` function, e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function factorial in module math:\n",
      "\n",
      "factorial(x, /)\n",
      "    Find x!.\n",
      "    \n",
      "    Raise a ValueError if x is negative or non-integral.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(math.factorial)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `help` function can also be used to access the documentation for a module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on module math:\n",
      "\n",
      "NAME\n",
      "    math\n",
      "\n",
      "MODULE REFERENCE\n",
      "    https://docs.python.org/3.9/library/math\n",
      "    \n",
      "    The following documentation is automatically generated from the Python\n",
      "    source files.  It may be incomplete, incorrect or include features that\n",
      "    are considered implementation detail and may vary between Python\n",
      "    implementations.  When in doubt, consult the module reference at the\n",
      "    location listed above.\n",
      "\n",
      "DESCRIPTION\n",
      "    This module provides access to the mathematical functions\n",
      "    defined by the C standard.\n",
      "\n",
      "FUNCTIONS\n",
      "    acos(x, /)\n",
      "        Return the arc cosine (measured in radians) of x.\n",
      "        \n",
      "        The result is between 0 and pi.\n",
      "    \n",
      "    acosh(x, /)\n",
      "        Return the inverse hyperbolic cosine of x.\n",
      "    \n",
      "    asin(x, /)\n",
      "        Return the arc sine (measured in radians) of x.\n",
      "        \n",
      "        The result is between -pi/2 and pi/2.\n",
      "    \n",
      "    asinh(x, /)\n",
      "        Return the inverse hyperbolic sine of x.\n",
      "    \n",
      "    atan(x, /)\n",
      "        Return the arc tangent (measured in radians) of x.\n",
      "        \n",
      "        The result is between -pi/2 and pi/2.\n",
      "    \n",
      "    atan2(y, x, /)\n",
      "        Return the arc tangent (measured in radians) of y/x.\n",
      "        \n",
      "        Unlike atan(y/x), the signs of both x and y are considered.\n",
      "    \n",
      "    atanh(x, /)\n",
      "        Return the inverse hyperbolic tangent of x.\n",
      "    \n",
      "    ceil(x, /)\n",
      "        Return the ceiling of x as an Integral.\n",
      "        \n",
      "        This is the smallest integer >= x.\n",
      "    \n",
      "    comb(n, k, /)\n",
      "        Number of ways to choose k items from n items without repetition and without order.\n",
      "        \n",
      "        Evaluates to n! / (k! * (n - k)!) when k <= n and evaluates\n",
      "        to zero when k > n.\n",
      "        \n",
      "        Also called the binomial coefficient because it is equivalent\n",
      "        to the coefficient of k-th term in polynomial expansion of the\n",
      "        expression (1 + x)**n.\n",
      "        \n",
      "        Raises TypeError if either of the arguments are not integers.\n",
      "        Raises ValueError if either of the arguments are negative.\n",
      "    \n",
      "    copysign(x, y, /)\n",
      "        Return a float with the magnitude (absolute value) of x but the sign of y.\n",
      "        \n",
      "        On platforms that support signed zeros, copysign(1.0, -0.0)\n",
      "        returns -1.0.\n",
      "    \n",
      "    cos(x, /)\n",
      "        Return the cosine of x (measured in radians).\n",
      "    \n",
      "    cosh(x, /)\n",
      "        Return the hyperbolic cosine of x.\n",
      "    \n",
      "    degrees(x, /)\n",
      "        Convert angle x from radians to degrees.\n",
      "    \n",
      "    dist(p, q, /)\n",
      "        Return the Euclidean distance between two points p and q.\n",
      "        \n",
      "        The points should be specified as sequences (or iterables) of\n",
      "        coordinates.  Both inputs must have the same dimension.\n",
      "        \n",
      "        Roughly equivalent to:\n",
      "            sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))\n",
      "    \n",
      "    erf(x, /)\n",
      "        Error function at x.\n",
      "    \n",
      "    erfc(x, /)\n",
      "        Complementary error function at x.\n",
      "    \n",
      "    exp(x, /)\n",
      "        Return e raised to the power of x.\n",
      "    \n",
      "    expm1(x, /)\n",
      "        Return exp(x)-1.\n",
      "        \n",
      "        This function avoids the loss of precision involved in the direct evaluation of exp(x)-1 for small x.\n",
      "    \n",
      "    fabs(x, /)\n",
      "        Return the absolute value of the float x.\n",
      "    \n",
      "    factorial(x, /)\n",
      "        Find x!.\n",
      "        \n",
      "        Raise a ValueError if x is negative or non-integral.\n",
      "    \n",
      "    floor(x, /)\n",
      "        Return the floor of x as an Integral.\n",
      "        \n",
      "        This is the largest integer <= x.\n",
      "    \n",
      "    fmod(x, y, /)\n",
      "        Return fmod(x, y), according to platform C.\n",
      "        \n",
      "        x % y may differ.\n",
      "    \n",
      "    frexp(x, /)\n",
      "        Return the mantissa and exponent of x, as pair (m, e).\n",
      "        \n",
      "        m is a float and e is an int, such that x = m * 2.**e.\n",
      "        If x is 0, m and e are both 0.  Else 0.5 <= abs(m) < 1.0.\n",
      "    \n",
      "    fsum(seq, /)\n",
      "        Return an accurate floating point sum of values in the iterable seq.\n",
      "        \n",
      "        Assumes IEEE-754 floating point arithmetic.\n",
      "    \n",
      "    gamma(x, /)\n",
      "        Gamma function at x.\n",
      "    \n",
      "    gcd(*integers)\n",
      "        Greatest Common Divisor.\n",
      "    \n",
      "    hypot(...)\n",
      "        hypot(*coordinates) -> value\n",
      "        \n",
      "        Multidimensional Euclidean distance from the origin to a point.\n",
      "        \n",
      "        Roughly equivalent to:\n",
      "            sqrt(sum(x**2 for x in coordinates))\n",
      "        \n",
      "        For a two dimensional point (x, y), gives the hypotenuse\n",
      "        using the Pythagorean theorem:  sqrt(x*x + y*y).\n",
      "        \n",
      "        For example, the hypotenuse of a 3/4/5 right triangle is:\n",
      "        \n",
      "            >>> hypot(3.0, 4.0)\n",
      "            5.0\n",
      "    \n",
      "    isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)\n",
      "        Determine whether two floating point numbers are close in value.\n",
      "        \n",
      "          rel_tol\n",
      "            maximum difference for being considered \"close\", relative to the\n",
      "            magnitude of the input values\n",
      "          abs_tol\n",
      "            maximum difference for being considered \"close\", regardless of the\n",
      "            magnitude of the input values\n",
      "        \n",
      "        Return True if a is close in value to b, and False otherwise.\n",
      "        \n",
      "        For the values to be considered close, the difference between them\n",
      "        must be smaller than at least one of the tolerances.\n",
      "        \n",
      "        -inf, inf and NaN behave similarly to the IEEE 754 Standard.  That\n",
      "        is, NaN is not close to anything, even itself.  inf and -inf are\n",
      "        only close to themselves.\n",
      "    \n",
      "    isfinite(x, /)\n",
      "        Return True if x is neither an infinity nor a NaN, and False otherwise.\n",
      "    \n",
      "    isinf(x, /)\n",
      "        Return True if x is a positive or negative infinity, and False otherwise.\n",
      "    \n",
      "    isnan(x, /)\n",
      "        Return True if x is a NaN (not a number), and False otherwise.\n",
      "    \n",
      "    isqrt(n, /)\n",
      "        Return the integer part of the square root of the input.\n",
      "    \n",
      "    lcm(*integers)\n",
      "        Least Common Multiple.\n",
      "    \n",
      "    ldexp(x, i, /)\n",
      "        Return x * (2**i).\n",
      "        \n",
      "        This is essentially the inverse of frexp().\n",
      "    \n",
      "    lgamma(x, /)\n",
      "        Natural logarithm of absolute value of Gamma function at x.\n",
      "    \n",
      "    log(...)\n",
      "        log(x, [base=math.e])\n",
      "        Return the logarithm of x to the given base.\n",
      "        \n",
      "        If the base not specified, returns the natural logarithm (base e) of x.\n",
      "    \n",
      "    log10(x, /)\n",
      "        Return the base 10 logarithm of x.\n",
      "    \n",
      "    log1p(x, /)\n",
      "        Return the natural logarithm of 1+x (base e).\n",
      "        \n",
      "        The result is computed in a way which is accurate for x near zero.\n",
      "    \n",
      "    log2(x, /)\n",
      "        Return the base 2 logarithm of x.\n",
      "    \n",
      "    modf(x, /)\n",
      "        Return the fractional and integer parts of x.\n",
      "        \n",
      "        Both results carry the sign of x and are floats.\n",
      "    \n",
      "    nextafter(x, y, /)\n",
      "        Return the next floating-point value after x towards y.\n",
      "    \n",
      "    perm(n, k=None, /)\n",
      "        Number of ways to choose k items from n items without repetition and with order.\n",
      "        \n",
      "        Evaluates to n! / (n - k)! when k <= n and evaluates\n",
      "        to zero when k > n.\n",
      "        \n",
      "        If k is not specified or is None, then k defaults to n\n",
      "        and the function returns n!.\n",
      "        \n",
      "        Raises TypeError if either of the arguments are not integers.\n",
      "        Raises ValueError if either of the arguments are negative.\n",
      "    \n",
      "    pow(x, y, /)\n",
      "        Return x**y (x to the power of y).\n",
      "    \n",
      "    prod(iterable, /, *, start=1)\n",
      "        Calculate the product of all the elements in the input iterable.\n",
      "        \n",
      "        The default start value for the product is 1.\n",
      "        \n",
      "        When the iterable is empty, return the start value.  This function is\n",
      "        intended specifically for use with numeric values and may reject\n",
      "        non-numeric types.\n",
      "    \n",
      "    radians(x, /)\n",
      "        Convert angle x from degrees to radians.\n",
      "    \n",
      "    remainder(x, y, /)\n",
      "        Difference between x and the closest integer multiple of y.\n",
      "        \n",
      "        Return x - n*y where n*y is the closest integer multiple of y.\n",
      "        In the case where x is exactly halfway between two multiples of\n",
      "        y, the nearest even value of n is used. The result is always exact.\n",
      "    \n",
      "    sin(x, /)\n",
      "        Return the sine of x (measured in radians).\n",
      "    \n",
      "    sinh(x, /)\n",
      "        Return the hyperbolic sine of x.\n",
      "    \n",
      "    sqrt(x, /)\n",
      "        Return the square root of x.\n",
      "    \n",
      "    tan(x, /)\n",
      "        Return the tangent of x (measured in radians).\n",
      "    \n",
      "    tanh(x, /)\n",
      "        Return the hyperbolic tangent of x.\n",
      "    \n",
      "    trunc(x, /)\n",
      "        Truncates the Real x to the nearest Integral toward 0.\n",
      "        \n",
      "        Uses the __trunc__ magic method.\n",
      "    \n",
      "    ulp(x, /)\n",
      "        Return the value of the least significant bit of the float x.\n",
      "\n",
      "DATA\n",
      "    e = 2.718281828459045\n",
      "    inf = inf\n",
      "    nan = nan\n",
      "    pi = 3.141592653589793\n",
      "    tau = 6.283185307179586\n",
      "\n",
      "FILE\n",
      "    /home/studio-lab-user/.conda/envs/default/lib/python3.9/lib-dynload/math.cpython-39-x86_64-linux-gnu.so\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(math)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a notebook it is also possible to use `?` to access the documentation, which will be displayed at the bottom of the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[0;31mSignature:\u001b[0m \u001b[0mrandom\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mgauss\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmu\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msigma\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
       "\u001b[0;31mDocstring:\u001b[0m\n",
       "Gaussian distribution.\n",
       "\n",
       "mu is the mean, and sigma is the standard deviation.  This is\n",
       "slightly faster than the normalvariate() function.\n",
       "\n",
       "Not thread-safe without a lock around calls.\n",
       "\u001b[0;31mFile:\u001b[0m      ~/.conda/envs/default/lib/python3.9/random.py\n",
       "\u001b[0;31mType:\u001b[0m      method\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import random\n",
    "random.gauss?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "78bec42b97a384da1258851020c6e40a",
     "grade": false,
     "grade_id": "cell-430d835796356075",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "## Exercise 05.1 (random numbers)\n",
    "\n",
    "- Using the '`randint`' function from the '`random`' module (https://docs.python.org/3/library/random.html#random.randint), \n",
    "  develop a function `dice_roll` that emulates the roll of a dice with $n$ sides.\n",
    "\n",
    "- For $n=6$, devise and implement a test to check that it is a fair dice. To solve this you could use a list to save the results of rolls. If you do not know how to do this then complete the next notebook before coming back to this part."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "61e2a56d004d8d8ae67a9fcdfd923411",
     "grade": false,
     "grade_id": "cell-12092bd5f2adea76",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "#### (a) Dice roll code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "4bf12682ccd10675634d0e03f8d9e03f",
     "grade": false,
     "grade_id": "cell-70a83466894475ee",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method randint in module random:\n",
      "\n",
      "randint(a, b) method of random.Random instance\n",
      "    Return random integer in range [a, b], including both end points.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import random\n",
    "\n",
    "help(random.randint)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def dice_roll(n):\n",
    "    a = random.randint(1, n) \n",
    "    return a\n",
    "\n",
    "#test for n=6 \n",
    "dice_roll(6)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "cc96b22a27a50764737999a68f55cee7",
     "grade": true,
     "grade_id": "cell-0970743b0c035f78",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "for n in range(1, 20):\n",
    "    for j in range(100):\n",
    "        value = dice_roll(n) \n",
    "        assert value >= 1 and value <= n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "d5b750f62a69a71bfde95d5766edb830",
     "grade": false,
     "grade_id": "cell-8fd8c957cbce8e91",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "#### (b) Test for fairness"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "3efa13bd797422d747fe0f35cd3668d5",
     "grade": true,
     "grade_id": "cell-0826760c62c21bff",
     "locked": false,
     "points": 0,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "No. of ones rolled:  16648\n",
      "Expected frequency:  16666.666666666668\n"
     ]
    }
   ],
   "source": [
    "# TEST 1 - NOT USING A LIST\n",
    "\n",
    "#define number of sides on a dice \n",
    "n = 6\n",
    "\n",
    "#define number of rolls\n",
    "no_rolls = 100000\n",
    "\n",
    "#varaible for how many ones were rolled\n",
    "num_ones = 0\n",
    "\n",
    "for i in range (no_rolls):\n",
    "    a = dice_roll(n)\n",
    "    if a == 1:\n",
    "        num_ones = num_ones + 1\n",
    "\n",
    "#if these numbers are similar then the test is far\n",
    "print('No. of ones rolled: ', num_ones)\n",
    "print('Expected frequency: ', no_rolls / 6)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "nbgrader": {
     "cell_type": "code",
     "checksum": "3efa13bd797422d747fe0f35cd3668d5",
     "grade": true,
     "grade_id": "cell-0826760c62c21bff",
     "locked": false,
     "points": 0,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1, 2, 3, 4, 5, 6]), array([16600, 16570, 16655, 16746, 16600, 16829]))"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# TEST 2 - USING A LIST\n",
    "import numpy as np\n",
    "\n",
    "#define number of sides on a dice \n",
    "n = 6\n",
    "\n",
    "#define number of rolls\n",
    "no_rolls = 100000\n",
    "\n",
    "#define list to record results in\n",
    "results = []\n",
    "\n",
    "#create a list of dice roll results \n",
    "for i in range (no_rolls):\n",
    "    a = dice_roll(n)\n",
    "    results.append(a)\n",
    "\n",
    "#find the frequency of each dice roll\n",
    "results_np = np.array(results)\n",
    "np.unique(results_np, return_counts=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "36bcc27ebc5dd171db48bb5806f8aaf6",
     "grade": false,
     "grade_id": "cell-007e984f33e27da1",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "## Exercise 05.2 (data compression)\n",
    "\n",
    "**This is an advanced exercises. You may not feel confident tackling this initially. You may want to come back and try this later.**\n",
    "\n",
    "For devices with limited memory, data compression can be important. Data compression is\n",
    "a field of its own, but with libraries we can compress (and uncompress) data easily without being expert in\n",
    "the details.\n",
    "\n",
    "Below is a program code for compressing a passage from Hamlet, by Shakespeare."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "76fd7da1deb076195800c6277428ff17",
     "grade": false,
     "grade_id": "cell-3c2032bdba4a917a",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'bytes'>\n",
      "Number of bytes for uncompressed string: 785\n",
      "Number of bytes for compressed string: 466\n",
      "Compression efficiency:  0.5936305732484076\n"
     ]
    }
   ],
   "source": [
    "# Import the compression module\n",
    "import zlib\n",
    "\n",
    "# Create a string that we wish to compress\n",
    "text = \"\"\"\n",
    "Welcome, dear Rosencrantz and Guildenstern!\n",
    "Moreover that we much did long to see you,\n",
    "The need we have to use you did provoke\n",
    "Our hasty sending. Something have you heard\n",
    "Of Hamlet's transformation; so call it,\n",
    "Sith nor the exterior nor the inward man\n",
    "Resembles that it was. What it should be,\n",
    "More than his father's death, that thus hath put him\n",
    "So much from the understanding of himself,\n",
    "I cannot dream of: I entreat you both,\n",
    "That, being of so young days brought up with him,\n",
    "And sith so neighbour'd to his youth and havior,\n",
    "That you vouchsafe your rest here in our court\n",
    "Some little time: so by your companies\n",
    "To draw him on to pleasures, and to gather,\n",
    "So much as from occasion you may glean,\n",
    "Whether aught, to us unknown, afflicts him thus,\n",
    "That, open'd, lies within our remedy.\"\"\"\n",
    "\n",
    "# Convert Python string to bytes and check type\n",
    "text_bytes = text.encode(\"utf-8\")\n",
    "print(type(text_bytes))\n",
    "\n",
    "# Get number of bytes used to store string\n",
    "print(\"Number of bytes for uncompressed string:\", len(text_bytes))\n",
    "\n",
    "# Compress string and get number of byes used for compressed string\n",
    "text_comp = zlib.compress(text_bytes)\n",
    "print(\"Number of bytes for compressed string:\", len(text_comp))\n",
    "\n",
    "# Display the compression efficiency\n",
    "print(\"Compression efficiency: \", len(text_comp)/len(text_bytes))\n",
    "\n",
    "# Decompress the string\n",
    "text_decomp = zlib.decompress(text_comp)\n",
    "\n",
    "# Check that original and decompressed string are the same (more on aseret)\n",
    "if text != text_decomp.decode(\"utf-8\"):\n",
    "    print(\"Problem: original and decompressed string differ.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "0fe54aee845d95687889dc19b435ba77",
     "grade": false,
     "grade_id": "cell-f80062a015942c13",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "Using the above as a guide, examine the compression efficiency of \n",
    "\n",
    "1. Compressing one large string made up of the the passage by Shakespeare repeated 100 times; and\n",
    "2. Compressing a random string of the same length as the repeated Shakespeare passage.\n",
    "\n",
    "To help you, the below function generates random string of length `N`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "28a57abbb021d924834ef4705e0f90bb",
     "grade": false,
     "grade_id": "cell-6e2a283ca091e187",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "asiF99xc\n"
     ]
    }
   ],
   "source": [
    "import random\n",
    "import string\n",
    "\n",
    "def random_string(N):\n",
    "    return ''.join([random.choice(string.ascii_letters + string.digits) for n in range(N)])\n",
    "\n",
    "print(random_string(8))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "f2cd0f781558ed7eb4413c8b2c2198cf",
     "grade": false,
     "grade_id": "cell-169d40e6f3aadc18",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "# Create a string\n",
    "text = \"\"\"\n",
    "Welcome, dear Rosencrantz and Guildenstern!\n",
    "Moreover that we much did long to see you,\n",
    "The need we have to use you did provoke\n",
    "Our hasty sending. Something have you heard\n",
    "Of Hamlet's transformation; so call it,\n",
    "Sith nor the exterior nor the inward man\n",
    "Resembles that it was. What it should be,\n",
    "More than his father's death, that thus hath put him\n",
    "So much from the understanding of himself,\n",
    "I cannot dream of: I entreat you both,\n",
    "That, being of so young days brought up with him,\n",
    "And sith so neighbour'd to his youth and havior,\n",
    "That you vouchsafe your rest here in our court\n",
    "Some little time: so by your companies\n",
    "To draw him on to pleasures, and to gather,\n",
    "So much as from occasion you may glean,\n",
    "Whether aught, to us unknown, afflicts him thus,\n",
    "That, open'd, lies within our remedy.\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "5ff95e98d7993220b5b491a4081c44c0",
     "grade": false,
     "grade_id": "cell-6dd8e7572f189eff",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "Import the necessary modules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "1f92d1231c21a688b037ef6d9cc9294a",
     "grade": false,
     "grade_id": "cell-93be06c0b8818e9e",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "import random\n",
    "import string\n",
    "import zlib"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "79b8ee9892e83429e39f65d2e075fa45",
     "grade": false,
     "grade_id": "cell-6c9348155e28f467",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "Repeat the Shakespeare string 100 times, and compress:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "edac5251a56b1190fee5c9e7349d3f63",
     "grade": false,
     "grade_id": "cell-c08bb020d9be6620",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Create string of Shakespeare passage repeated 100 times\n",
    "# YOUR CODE HERE\n",
    "long_text = text * 100\n",
    "long_text_bytes = long_text.encode(\"utf-8\")\n",
    "long_text_comp = zlib.compress(long_text_bytes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "16883ec26de137558d302ac47ad9743c",
     "grade": false,
     "grade_id": "cell-ea781714f8a7db87",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "Create random string and compress:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "b7442cbb06e29f3f3ca705b05487f55c",
     "grade": false,
     "grade_id": "cell-c5d8c07589ec3cd1",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# YOUR CODE HERE\n",
    "rand_text = random_string(len(long_text))\n",
    "rand_text_bytes = rand_text.encode(\"utf-8\")\n",
    "rand_text_comp = zlib.compress(rand_text_bytes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "c6cc082101b86f87ac9d8df2b18b307e",
     "grade": false,
     "grade_id": "cell-36c10b63438d6d4a",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "Compare compression efficiency:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "66aa622e93c710b8a7ce0d6bcb6f5ff3",
     "grade": true,
     "grade_id": "cell-a2dd98ee370e22a3",
     "locked": false,
     "points": 0,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Compression efficiency:  0.01178343949044586\n",
      "Compression efficiency:  0.7520764331210191\n"
     ]
    }
   ],
   "source": [
    "# YOUR CODE HERE\n",
    "# Display the compression efficiency\n",
    "print(\"Compression efficiency: \", len(long_text_comp)/len(long_text_bytes))\n",
    "print(\"Compression efficiency: \", len(rand_text_comp)/len(rand_text_bytes))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "default:Python",
   "language": "python",
   "name": "conda-env-default-py"
  },
  "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}