01-pythonintro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to Python \n",
    "\n",
    "This tutorial is heavily based on [this tutorial on audio signal processing](https://github.com/spatialaudio/selected-topics-in-audio-signal-processing-exercises).\n",
    "\n",
    "For most of the exercises, we will use the very popular programming language [Python](https://www.python.org) together with a few external libraries from the [Scientific Python Stack](http://scipy.org).\n",
    "To get started, you might also want to have a look a those:\n",
    "\n",
    "* [Python Introduction](http://nbviewer.ipython.org/github/mgeier/python-audio/blob/master/intro-python.ipynb) (pure Python, no NumPy)\n",
    "\n",
    "* [Simple Signal Processing Example](http://nbviewer.ipython.org/github/mgeier/python-audio/blob/master/simple-signals.ipynb) (quite similar to the things on this very page)\n",
    "\n",
    "Note that Python is not the only option for the kind of tasks that we'll tackle here.\n",
    "If you are interested in some alternatives, have a look at [Julia](http://julialang.org/), [R](http://www.r-project.org/), [Octave](http://octave.org/) or [Scilab](http://www.scilab.org/).\n",
    "All the mentioned applications are open-source software and there are of course even more alternatives (both free and proprietary).\n",
    "\n",
    "Most of the exercises in this course (including the one you're reading right now) are presented as [Jupyter (formerly known as IPython) notebooks](http://jupyter.org/).\n",
    "They can be [viewed online](http://nbviewer.jupyter.org/github/spatialaudio/communication-acoustics-exercises/blob/master/index.ipynb), but it makes much more sense to download them and open and explore them locally with [Jupyter](http://jupyter.org/).\n",
    "\n",
    "For installation instructions, see the section [Getting Started](index.ipynb#Getting-Started) on the main page.\n",
    "\n",
    "To get an idea what Jupyter is all about, have a look at this [Jupyter Introduction](http://nbviewer.jupyter.org/github/mgeier/python-audio/blob/master/intro-jupyter.ipynb).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What Will We Learn Today?\n",
    "\n",
    "* Basics of Python, Jupyter/IPython, NumPy, SciPy, matplotlib and some other external libraries\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notebook Cells\n",
    "\n",
    "This notebook consists of so-called \"cells\", which can be used for normal text (see above) or for Python code (see below).\n",
    "*Code cells* can be selected by a mouse click (or with the arrow up/down keys and *Enter*), the code can be edited and then executed by pressing *Shift+Enter* or by clicking the <button class=\"fa fa-step-forward fa-play icon-play btn btn-xs btn-default\"></button> button in the top part of the page.\n",
    "\n",
    "Don't be shy, try it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "50 - 5 * 4 + 12"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Code cells can have multiple lines (use *Enter* for line breaks).\n",
    "When the code cell is executed, all lines are executed, but only the value of the last line is displayed (except if there is no value to display).\n",
    "\n",
    "Here's another code cell for you to play with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "New cells can be inserted by pressing the *a* or *b* keys (to insert *above* or *below* the current cell) or via the menu. You should also have a look at \"Help\" -> \"Keyboard Shortcuts\".\n",
    "\n",
    "You can step through all cells in the notebook by repeatedly pressing *Shift+Enter*.\n",
    "Alternatively, you can click \"Run All\" in the \"Cell\" menu."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Basics\n",
    "Below is a Python program containing a lot of the operations you will typically need: Assignments, arithmetics, logical operators, printing, comments. As you see, Python is quite easy to read, I am sure you can figure out the meaning of each line yourself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 34 - 23 # A comment.\n",
    "y = \"Hello\" # Another one.\n",
    "z = 3.45\n",
    "if z == 3.45 or y == \"Hello\":\n",
    "    x = x + 1\n",
    "    y = y + \" World\"\n",
    "print(x)\n",
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Indentation\n",
    "Python handles blocks in a different way than other programming languages you might know, like Java or C: The first line with less indentation is outside of the block, the first line with more indentation starts a nested block. A colon often starts a new block. For example, in the code below, the fourth line is always executed, because it is not part of the block:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if 17<16:\n",
    "    print(\"executed conditionally\")\n",
    "    print(\"also conditionally\")\n",
    "print(\"always executed, because not part of the block above\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reference Semantics\n",
    "Assignments behave as you might know from Java: For atomic data types, assignments work \"by value\", for all other data types (e.g. lists), assignments work \"by reference\": If we manipulate an object, this influences all references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a=17\n",
    "b=a #assign the *value* of a to b\n",
    "a=12\n",
    "print(b) #still 12, because assinment by value\n",
    "\n",
    "x=[1,2,3] #this is what lists look like\n",
    "y=x #assign reference to the list to y\n",
    "x.append(4) #manipulate the list by adding a value\n",
    "print(y) #y also changed, because of assingment by reference"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Lists\n",
    "Lists are written in square brackets, as you have seen above. Lists can contain values of mixed types. List indices start with 0, as you can see here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "li = [17,\"Hello\",4.1,\"Bar\",5,6]\n",
    "li[2]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use negative indices, which means that we start counting from the right:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "li[-2]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also select subsets of lists (\"slicing\"), like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "li[2:4]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that slicing returns a copy of the sub-list."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Some more list operators\n",
    "Here are some more operators you might find useful."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Boolean test whether a value is in a list: the in operator\n",
    "t = [1,2,3,4]\n",
    "2 in t \n",
    "\n",
    "# Concatenate lists: the + operator\n",
    "a = [1,2,3,4]\n",
    "b = [5,6,7]\n",
    "c = a + b\n",
    "c\n",
    "\n",
    "# Repeat a list n times: the * operator\n",
    "a=[1,2,3]\n",
    "3*a\n",
    "\n",
    "# Append lists\n",
    "a=[1,2,3]\n",
    "a.append(4)\n",
    "\n",
    "# Index of first occurence\n",
    "a.index(2)\n",
    "\n",
    "# Number of occurences\n",
    "a = [1,2,3,2,1,2]\n",
    "a.count(2)\n",
    "\n",
    "# Remove first occurence\n",
    "a.remove(2)\n",
    "\n",
    "# Revese the list\n",
    "a.reverse()\n",
    "\n",
    "# Sort the list\n",
    "a.sort()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dictionaries: A mapping type\n",
    "Dictionaries are known as maps in other languages: They store a mapping between a set of keys and a set of values. Below is an example on how to use dictionaries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a new dictionary\n",
    "d = {'user':'bozo', 'pswd':1234}\n",
    "\n",
    "# Access the values via a key\n",
    "print(d['user'])\n",
    "d['pswd']\n",
    "\n",
    "# Add key-value pairs\n",
    "d['id']=17\n",
    "\n",
    "# List of keys\n",
    "d.keys()\n",
    "\n",
    "# List of values\n",
    "d.values()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Functions\n",
    "Functions in Python work as you would expect: Arguments to functions are passed by assignment, that means passed arguments are assigned to local names. Assignments to arguments cannot affect the caller, but changing mutable arguments might. Here is an example of defining and calling a function:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def myfun(x,y):\n",
    "    print(\"The function is executed.\")\n",
    "    y[0]=8 # This changes the list that y points to\n",
    "    return(y[1]+x)\n",
    "\n",
    "mylist = [1,2,3]\n",
    "result=myfun(17,mylist)\n",
    "print(\"Function returned: \",result)\n",
    "print(\"List is now: \",mylist)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Optional Arguments\n",
    "We can define defaults for arguments that do not need to be passed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def func(a, b, c=10, d=100):\n",
    "    print(a, b, c, d)\n",
    "func(1,2)\n",
    "func(1,2,d=4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some more facts about functions:\n",
    "* All functions in Python have a return value, functions without a return statement have the special return value None\n",
    "* There is no function overloading in Python\n",
    "* Functions can be used as any other data types: They can be arguments to functions, return values of functions, assigned to variables, etc. This means Python is a functional programming language, and we can do many of things you know and love from Haskell, like higher-order functions!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Control of Flow\n",
    "We have already seen If-branches above. For- and While-Loops also work exactly as you would expect, Here are just some examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 3\n",
    "while x < 10:\n",
    "    if x > 7:\n",
    "        x += 2\n",
    "        continue\n",
    "    x = x + 1\n",
    "    print(\"Still in the loop.\")\n",
    "    if x == 8:\n",
    "        break\n",
    "print(\"Outside of the loop.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for x in range(10):\n",
    "    if x > 7:\n",
    "        x += 2\n",
    "        continue\n",
    "    x = x + 1\n",
    "    print(\"Still in the loop.\")\n",
    "    if x == 8:\n",
    "        break\n",
    "print(\"Outside of the loop.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Exercise: Implement a function that tests whether a given number is prime."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def isPrime(x):\n",
    "    # TODO\n",
    "    \n",
    "isPrime(18)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# List Comprehensions, \n",
    "There is a special syntax for list comprehensions (which you might know from Haskell)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# List of all multiples of 3 that are <100:\n",
    "evens = [x for x in range(3,100) if x%3==0]\n",
    "print(evens)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Exercise: Use a list comprehension to make a list of all primes < 1000."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Numpy\n",
    "Numpy is a very popular Python package that allows to work more easily with numeric arrays. It is the basis for much of what you will see in this course."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing Modules/Packages\n",
    "\n",
    "In order to work with numeric arrays, we import the [NumPy](http://www.numpy.org) package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can use all NumPy functions (by prefixing \"`np.`\")."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.zeros(10000)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tab Completion\n",
    "\n",
    "*Exercise:* Type \"`np.ze`\" (without the quotes) and then hit the *Tab* key ..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Array, Vector, Matrix\n",
    "\n",
    "Arrays can have arbitrarily many dimensions, but let's use only one-dimensional arrays for now.\n",
    "Arrays can be created with [numpy.array()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.array.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the result is not displayed when you assign to a variable (because assignment is a *statement* and not an *expression*).\n",
    "To show the data, write the variable name separately as the last (or only) line of a code cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "BTW, there is an easier way to get this particular array (using [numpy.arange()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.arange.html)):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b = np.arange(2,10,2)\n",
    "b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Help\n",
    "\n",
    "If you want to know details about the usage of `np.arange()` and all its supported arguments, have a look at its help text.\n",
    "Just append a question mark to the function name (without parentheses!):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.arange?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A help window should open in the lower part of the browser window.\n",
    "This window can be closed by hitting the *q* key (like \"quit\").\n",
    "\n",
    "Let's get some more help:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.zeros?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also get help for the whole NumPy package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can get help for any object by appending (or prepending) a question mark to the name of the object.\n",
    "Let's check what the help system can tell us about our variable `a`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The help system may come in handy when solving the following exercises ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `np.arange()`\n",
    "\n",
    "We'll often need sequences of evenly spaced numbers, so let's create some.\n",
    "\n",
    "*Exercise:* Create a sequence of numbers with `np.arange()`, starting with 0 and up to (but not including) 6 with a step size of 1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* Create a sequence of numbers with `np.arange()`, starting with 0 and up to (but not including) 0.6 with a step size of 0.1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* Create a sequence of numbers with `np.arange()`, starting with 0.5 and up to (but not including) 1.1 with a step size of 0.1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The previous exercise is somewhat tricky.\n",
    "If you got it right, have a look at [arange considered harmful](http://nbviewer.ipython.org/github/mgeier/python-audio/blob/master/misc/arange.ipynb) for what you *could have* done wrong.\n",
    "If you got an unexpected result, have a look at [arange considered harmful](http://nbviewer.ipython.org/github/mgeier/python-audio/blob/master/misc/arange.ipynb) for an explanation.\n",
    "\n",
    "*Exercise:* Can you fix the problem?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What do we learn from all this?\n",
    "$\\Rightarrow$\n",
    "`np.arange()` is great, but use it only with integer step sizes!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `np.linspace()`\n",
    "\n",
    "Another, slightly different method to create a sequence of evenly spaced numbers is [numpy.linspace()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.linspace.html).\n",
    "Have a look at the documentation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.linspace?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* Create a sequence of numbers with `np.linspace()`, starting with 0 and up to (including) 6 with a step size of 1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the resulting array will have a *floating point* data type even if all inputs (and the step size) are integers.\n",
    "This is not the case with `np.arange()`.\n",
    "\n",
    "*Exercise:* Create a sequence of numbers with `np.linspace()`, starting with 0 and up to (but not including) 6 with a step size of 1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* Create a sequence of numbers with `np.linspace()`, starting with 0 and up to (but not including) 0.6 with a step size of 0.1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* Create a sequence of numbers with `np.linspace()`, starting with 0.5 and up to (but not including) 1.1 with a step size of 0.1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that `np.linspace()` doesn't have the above-mentioned problem we had with `np.arange()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a Sine Wave\n",
    "\n",
    "Let's create some more interesting array, representing a digital sine signal. The signal will follow the equation $y(t) = A\\sin(\\omega t)$ with $\\omega = 2\\pi f$ and $f$ being the frequency of the sine.\n",
    "The maximum signal amplitude is given by $A$.\n",
    "The variable $t$ obviously represents time.\n",
    "Let's create a digital signal with evenly spaced values for $t$.\n",
    "\n",
    "We can use the function [numpy.sin()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.sin.html) to create a sine tone. Let's look at its help text first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.sin?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we know which function to call, we need appropriate input.\n",
    "And that's where our sequences of evenly spaced values from above come into play.\n",
    "\n",
    "The nice thing about NumPy functions like `np.sin()` is that they can operate on whole arrays at once, so it is not necessary to call the function on each single value separately.\n",
    "Therefore, we can store the whole range of values for our time variable $t$ in one array.\n",
    "\n",
    "According to the equation, each value of $t$ has to be multiplied with (the constant) $\\omega$.\n",
    "That's another nice thing about NumPy: we don't have to multiply every value of the array $t$ separately with $\\omega$, we can multiply the whole array with a scalar at once, and NumPy does the element-wise multiplication for us.\n",
    "This is called [\"broadcasting\"](http://docs.scipy.org/doc/numpy/user/basics.broadcasting.html), in case you stumble upon that word in the docs.\n",
    "The array returned by `np.sin()` can (again using broadcasting) be multiplied by the constant scalar $A$ to get the final result.\n",
    "\n",
    "The only thing that's still missing is $\\pi$, but that's simple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.pi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let us create a sine wave with a frequency of 2 Hz, a duration of 1 second and an amplitude of 0.3.\n",
    "We use a sampling rate of 44.1 kHz."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "dur = 1  # duration in seconds\n",
    "amp = 0.3  # maximum amplitude\n",
    "freq = 2  # frequency of the sine tone in Hertz\n",
    "fs = 44100  # sampling frequency in Hertz\n",
    "\n",
    "t = np.arange(np.ceil(dur * fs)) / fs\n",
    "y = amp * np.sin(2 * np.pi * freq * t)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* Use the [built-in len() function](https://docs.python.org/3/library/functions.html#len) to find out how many samples the resulting signal has.\n",
    "How many is it supposed to have?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "t"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting\n",
    "\n",
    "Python and NumPy cannot plot by themselves, they need some help from [matplotlib](http://matplotlib.org/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can plot the data from our array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As always, for more info:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tweaking the Plot\n",
    "\n",
    "Let's look again at our plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(y);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since we passed only a single array to the `plot()` function, the x-axis shows the sample index from 0 to the length of the signal in samples (minus one).\n",
    "It may be more meaningful to show the time in seconds.\n",
    "\n",
    "But let's close the previous plot first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we pass two arrays to the `plot()` function, the first one defines the mapping from sample indices to the actual values displayed on the x-axis, the second one specifies the corresponding y values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(t, y);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Good, now the x-axis shows the time in seconds.\n",
    "Let's create axis labels so that everyone knows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(t, y)\n",
    "plt.xlabel(\"Time / Seconds\")\n",
    "plt.ylabel(\"Amplitude\")\n",
    "plt.title(\"Sine Tone with {} Hz\".format(freq));"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more information, have a look at [Getting Started With `matplotlib`](http://nbviewer.ipython.org/github/mgeier/python-audio/blob/master/plotting/matplotlib.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Two-Dimensional Arrays\n",
    "\n",
    "Two-dimensional arrays somewhat look like lists of lists, but internally, they are still stored in one contiguous area of memory.\n",
    "\n",
    "There are several functions for creating arrays which allow to specify the number of rows and columns, e.g. [numpy.zeros()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.zeros.html) and [numpy.ones()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.ones.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.zeros((4, 2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.ones((4, 2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Arrays can also be created from lists of lists (a.k.a. *nested* lists) with [numpy.array()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.array.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.array([[.1, .2], [.3, .4], [.5, .6], [.7, .8]])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the inner lists provide the individual rows of the array.\n",
    "\n",
    "Two-dimensional arrays can also be created by concatenating a list of one-dimensional arrays (or lists) by columns using [numpy.column_stack()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.column_stack.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = np.column_stack([[.1, .2, .3, .4], [.5, .6, .7, .8]])\n",
    "a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to flip rows and columns, you can transpose the array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b = a.T\n",
    "b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The transposed array is *not* a copy of the original one, it's rather a different *view* into the same memory.\n",
    "This means that if you change an element of the transposed array, this change will also be visible in the original array!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b[1, 2] = 0\n",
    "a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Array Properties\n",
    "\n",
    "Let's create some two-dimensional array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.random.normal(scale=0.2, size=(int(1.5 * fs), 2))\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* Try those different ways to obtain the size of the array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "len(x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.size"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.nbytes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* There's much more information about the array, try the following commands and find out what they mean."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.ndim"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.dtype"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.itemsize"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.strides"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.flags"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:*\n",
    "You can also get some statistical values about the data in the array.\n",
    "Check if they are consistent with the given normally distributed noise signal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.max()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.min()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.ptp()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.mean()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.std()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.var()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most of these *methods* also exist as *functions*, e.g."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.max(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both the functions and the methods have an optional *axis* argument.\n",
    "\n",
    "*Exercise:* Try `axis=0` with all of the above functions/methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x.std(axis=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.mean(x, axis=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Exercise:* What's the difference between `axis=0` and `axis=1`?\n",
    "What does `axis=-1` mean?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Broadcasting\n",
    "\n",
    "We already saw before, that when a scalar is multiplied by an array, this multiplication is done element-wise on the array.\n",
    "The NumPy people call this [broadcasting](http://docs.scipy.org/doc/numpy/user/basics.broadcasting.html).\n",
    "\n",
    "The great thing about it is that it is not limited to operations between a scalar and an array, but also between arrays of different numbers of dimensions.\n",
    "\n",
    "Let's, for example, take a one-dimensional array with two values and multiply it with our two-dimensional array `x` from before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.array([0.5, 100]) * x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although these two arrays clearly have a different shape and a different number of dimensions, the multiplication worked.\n",
    "In this case, each element of the first column of `x` was multiplied with the first value of the other array, and same for the second column and the second value of the array.\n",
    "\n",
    "In this example, the result has the same shape of one of the operands, and the other operand was \"stretched\" along its singular (or rather missing) dimension.\n",
    "\n",
    "But it doesn't have to be that way.\n",
    "Let's create a two-dimensional array that consists of only one column:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "y = np.random.normal(scale=0.2, size=(int(1.5 * fs), 1))\n",
    "y"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "y.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we multiply a one-dimensional array with this two-dimensional column-array, none of the dimensions have the same size.\n",
    "Nevertheless, we can multiply them and both arrays get \"stretched\" (along their singular/missing dimension) leading to a result having a shape larger than any of the operands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.array([0.5, 100]) * y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The left column of the result is `y` multiplied by the first element of the one-dimensional array, the right column is the same `y` multiplied by the second element."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p xmlns:dct=\"http://purl.org/dc/terms/\">\n",
    "  <a rel=\"license\"\n",
    "     href=\"http://creativecommons.org/publicdomain/zero/1.0/\">\n",
    "    <img src=\"http://i.creativecommons.org/p/zero/1.0/88x31.png\" style=\"border-style: none;\" alt=\"CC0\" />\n",
    "  </a>\n",
    "  <br />\n",
    "  To the extent possible under law,\n",
    "  <span rel=\"dct:publisher\" resource=\"[_:publisher]\">the person who associated CC0</span>\n",
    "  with this work has waived all copyright and related or neighboring\n",
    "  rights to this work.\n",
    "</p>"
   ]
  }
 ],
 "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.7.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}