python4mri.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python4mri\n",
    "This notebook contains a tutorial (+ exercises) to get familiar with Python in general and how to leverage it for (f)MRI analyses.\n",
    "\n",
    "## Before you get started\n",
    "To run this notebook, make sure you have the following packages installed:\n",
    "\n",
    "- numpy\n",
    "- scipy\n",
    "- matplotlib\n",
    "- nibabel\n",
    "\n",
    "An easy way to install these packages (assuming you have `pip` installed) is by running the following line in a terminal (in the same directory as this notebook):\n",
    "\n",
    "```\n",
    "pip install -r requirements.txt\n",
    "```\n",
    "\n",
    "Make sure to close and restart the notebook after running this line (or restart the kernel: Kernel &rarr; Restart).\n",
    "\n",
    "## About this tutorial\n",
    "This tutorial is about the programming language Python and how to use it for neuroimaging analysis. It is adapted from the first computer lab of the \"Neuroimaging: BOLD-MRI\" course given at the University of Amsterdam (Research Master Psychology). \n",
    "\n",
    "First, we'll discuss \"Jupyter notebooks\" and how to use them. Then, we'll discuss some basic Python syntax and constructs; this should be doable for people who are comfortable with programming (e.g., from previous experience with other programming languages, like Matlab or R). If you're not comfortable with programming, or you notice during this tutorial that you get stuck often, we recommend working through the free [Codecademy course](https://www.codecademy.com/learn/learn-python) up to and including unit 8 (loops). Note: you don't have to do the Codecademy quizzes (because you need to pay for that).\n",
    "\n",
    "After discussing basic Python syntax, we'll go over 'numpy' (Python's scientific computing package), followed by a section on 'Matplotlib' (Python's main plotting package). Finally, this tutorial ends with a section on how to interact with Nifti-files - the file format used most in the MRI community.\n",
    "\n",
    "## What you'll learn\n",
    "After this week's lab ... \n",
    "\n",
    "* you know how to work with Jupyter notebooks\n",
    "* you understand Python's basic syntax\n",
    "* you know how to leverage Numpy's powerful array-based functionality\n",
    "* you can plot data in various ways using Matplotlib\n",
    "* you know how to load, manipulate, and analyze Nifti-files\n",
    "\n",
    "In sum: at the end of this tutorial, you are able to implement any computation/routine necessary for complex fMRI analysis using a combination of basic Python and Numpy.\n",
    "\n",
    "**Credits**: Created by Lukas Snoek. This tutorial is partly based on work by [Tomas Knapen and Daan van Es](https://tknapen.github.io) (VU University). <br>\n",
    "**Estimated time to complete**: 4-10 hours (depending on your familiarity with Python)<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Contents:\n",
    "\n",
    "1. Jupyter notebooks\n",
    "2. General Python\n",
    "3. Numpy\n",
    "4. Matplotlib / plotting\n",
    "5. Interacting with Nifti-files\n",
    "\n",
    "But before anything else, let's get more familiar with the Jupyter notebook environment!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Jupyter Notebooks\n",
    "\n",
    "So, what are Jupyter notebooks, actually? Basically, using Jupyter notebooks is like using the web-browser as a kind of editor from which you can run Python code, similar to the MATLAB interactive editor or RStudio. Just like any editor, code in Jupyter notebooks is interpreted and executed by Python software on your computer/server.\n",
    "\n",
    "The cool thing about these notebooks is that they allow you to mix code \"cells\" (see below) and text \"cells\" (such as this one). The (printed) output from code blocks are displayed right below the code blocks themselves. \n",
    "\n",
    "Jupyter notebooks have two **modes**: edit mode and command mode.\n",
    "\n",
    "- *Command mode* is indicated by a grey cell border with a blue left margin (as is the case now!): When you are in command mode, you are able to edit the notebook as a whole, but not type into individual cells. Most importantly, in command mode, the keyboard is mapped to a set of shortcuts that let you perform notebook and cell actions efficiently (some shortcuts in command mode will be discussed later!). Enter command mode by pressing **Esc** or using the mouse to click outside a cell’s editor area; <br><br>\n",
    "- *Edit mode* is indicated by a green cell border and a prompt showing in the editor area: When a cell is in edit mode, you can type into the cell, like a normal text editor. Enter edit mode by pressing Enter or using the mouse to double-click on a cell’s editor area.\n",
    "\n",
    "When you're reading and scrolling through the tutorials, you'll be in the command mode mostly. But once you have to program (or write) stuff yourself, you have to switch to edit mode. But we'll get to that. First, we'll explain something about the two types of cells: code cells and text cells."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1. Code cells\n",
    "\n",
    "Code cells are the place to write your Python code, similar to MATLAB 'code sections' (which are usually deliniated by %%). Importantly, unlike the interactive editors in RStudio and MATLAB, a code cell in Jupyter notebooks can only be run all at once. This means you cannot run it line-by-line, but you have to run the entire cell!\n",
    "\n",
    "#### 1.1.1. Running cells\n",
    "Let's look at an example. Below, you see a code-cell with two print-statements. To run the cell, select it (i.e., the cell should have a green or blue frame around it; doesn't matter whether you're in edit or command mode), and click on the \"&#9654; `Run`\" icon or press `ctr+Enter`). Try it with the cell below!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"I'm printing Python code\")\n",
    "print(3 + 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(You might be confused because we use the `print` statement with brackets -- `print()` -- while you've learned in Codecademy that you should use `print` without brackets. This is because Codecademy uses an old version of Python, Python2.7, while we use a newer version, Python3.5. In the new version, `print()` should be used with brackets!)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.1.2. Stop running/execution of cells\n",
    "Sometimes, you might want to quit the execution of a code-cell because it's taking too long (or worse, you created an infinite loop!). To do so, click the stop icon &#9632; in the top menu!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.1.3. Restarting the kernel\n",
    "Sometimes, you accidentally 'crash' the notebook, for example when creating an infinite loop or when loading in too much data. You know your notebook 'crashed' when stopping the cell (&#9632;) does not work and your cell continues its execution, as evident by the `In [*]:` prompt next to the cell. In those cases, you need to completely restart the notebook, or in programming lingo: you need to \"restart the kernel\". To do so, click `Kernel` and `Restart`.\n",
    "\n",
    "Importantly, when you restart the kernel, it will keep all text/code that you've written, but it will **not** remember all the variables that you defined before restarting the kernel, including the imports. So if you restart the kernel, you will have to re-import everything (e.g. run `import numpy as np` again)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.1.3. Inserting cells\n",
    "As you can see in the code cell above, you can only run the entire cell (i.e. both `print` statements). Sometimes, of course, you'd like to organise code across multiple cells. To do this, you can simply add new blocks (cells) by selecting \"Insert &rarr; Insert Cell Below\" on the toolbar (or use the shortcut by pressing the \"B\" key when you're in command mode; \"B\" refers to \"**b**elow\"). This will insert a new code cell below the cell you have currently highlighted (the currently highlighted cell has a blue box around it). \n",
    "\n",
    "Try inserting a cell below and write some code (e.g. `print(10 * 10)`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.1.4. Inline plotting\n",
    "Another cool feature of Jupyter notebooks is that you can display figures in the same notebook! You simply define some plots in a code cell and it'll output the plot below it.\n",
    "\n",
    "Check it out by executing (click the \"play\" button or `ctr+Enter`) the next cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We'll get to what the code means later in the tutorial\n",
    "import matplotlib.pyplot as plt # The plotting package 'Matplotlib' is discussed in section 3!\n",
    "\n",
    "# This command makes sure that the figure is plotted in the notebook instead of in a separate window!\n",
    "%matplotlib inline \n",
    "\n",
    "# Now, let's plot something\n",
    "plt.plot(range(10))\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.2. Text ('markdown') cells\n",
    "Next to code cells, jupyter notebooks allow you to write text in so-called \"markdown cells\" (the cell this text is written in is, obviously, also a markdown cell). Markdown cells accept plain text and can be formatted by special markdown-syntax. A couple of examples:\n",
    "\n",
    "\\# One hash creates a large header <br>\n",
    "\\#\\# Two hashes creates a slightly smaller header (this goes up to four hashes)\n",
    "\n",
    "**Bold text** can be created by enclosing text in \\*\\*double asterisks\\*\\* and italicized text can be created by enclosing text in \\*single asterisks\\*. You can even include URLs and insert images from the web; check this [link](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for a cheatsheet with markdown syntax and options! All the special markdown-syntax and options will be converted to readable text *after running the text cell* (again, by pressing the \"play\" icon in the toolbar or by `ctr+Enter`).\n",
    "\n",
    "To insert a text (markdown) cell, insert a new cell (\"Insert &rarr; Insert Cell Below\" or \"B\" in command mode). Then, *while highlighting the new cell*, press \"Cell &rarr; Cell Type &rarr; Markdown\" on the toolbar on top of the notebook (or, while in command mode, press the \"m\" key; \"m\" refers to \"markdown\"). You should see the prompt (the **`In [ ]`** thingie) disappear. Voilà, now it's a text cell!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Try it out yourself! Insert a new markdown cell and try to write the following (without peeking at this cell!):\n",
    "\n",
    "\"**OMG**, this is the most awesome Python tutorial *ever*.\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.3. Changing cell type\n",
    "Sometimes you might accidentally change the cell type from \"code\" to \"markdown\". To change it back, you can click \"Cell\" &rarr; \"Cell Type\" &rarr; \"Code\" or \"Markdown\" (or use the shortcuts, in command mode, \"m\" for markdown or \"y\" for code). \n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Try it out yourself! Change the code cell, which contains markdown, into a markdown cell!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "This is a code cell, but it contains markdown, **oh no**!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.4. Getting help\n",
    "Throughout this tutorial you'll encounter situations in which you have to use functions that you'd like to get some more information on, e.g. which inputs it expects. To get help on any python function you'd like to use, you can simply write the function-name appended with a \"?\" and run the cell. This will open a window below with the \"docstring\" (explanation of the function). Take for example the built-in function **`len()`**. To get some more information, simply type `len?` in a code cell and run the cell.\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Try it out yourself: create a code cell below, type `len?` and check the output!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If this method (i.e. appending with \"?\") does not give you enough information, try to google (or just whatever search engine) the name of the function together with 'python' and, if you know from which package the function comes, the name of that package. For instance, for len() you could google: ['python len()'](http://lmgtfy.com/?q=python+len), or later when you'll use the numpy package, and you'd like to know how the `numpy.arange` function works you could google: 'python numpy arange'. \n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "    <b>REMEMBER</b>: Google is your friend! Googling things is an integral aspect of programming. If you're stuck, try to figure it out yourself by trying to find the solution online. At first, this might seem frustrating, but in the long run, it will make you a better programmer.\n",
    "</div>\n",
    "\n",
    "If you still can't figure out your problem, you can of course ask your classmates or tutors."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.5. Saving your work & closing down the notebook\n",
    "You're running and actively editing the notebook in a browser, but remember that it's still just a file located on your account on your laptop. Therefore, for your work to persist, you need to save the notebook once in a while (and definitely before closing the notebook). To save, simply press the floppy-disk image in the top-left (or do `ctr+s` while in command mode).\n",
    "\n",
    "If you saved your notebook and want to cloe it, click \"File\" &rarr; \"Close and halt\". This will stop your notebook from running and close it.\n",
    "\n",
    "Alright. Now that you've had your first contact with Jupyter notebooks - let's talk about about exercises and assignments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.6. Exercises (ToDo/ToThink) and assignments\n",
    "We believe that the best way to learn how to do neuroimaging analysis is by *actually programming* the analyses yourself. You have already seen some of these (ungraded) exercises, which we call \"ToDos\". There are different types of exercises throughout the notebook, including:\n",
    "\n",
    "- <font color='orange'>ToDos</font> : short programming exercises, either zero or for a few points\n",
    "- <font color='blue'>ToThinks</font>: questions about the (preceding) text/material, either zero or for a few points\n",
    "- <font color='red'>Assignments</font>: a larger programming exercise (sometimes with additional questions), usually for a larger amount of points\n",
    "\n",
    "Sometimes, you also encounter <font color='green'>Tips and Tricks</font>, which may contain advice, more information on a specific topic, or links to relevant websites or material.\n",
    "\n",
    "We highly recommend doing/answering the ToDos/ToThinks, not only because they are (often) worth points, but also because they are designed to improve your understanding of the material!\n",
    "\n",
    "Anyway, a \"ToDo\" would look something like this:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "In the code-cell below, set the variable `x` to 5 (without quotes!) and remove the `raise NotImplementedError` statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "8f31a4f573930bb4b916dd7d1d8b2309",
     "grade": false,
     "grade_id": "cell-18f974e3fcc0d18f",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "x = 'not yet 5'\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each answer-cell will contain the statement `raise NotImplementedError`. When implementing your ToDo, you always have to remove this statement (this will inform us, during grading, that you actually implemented something)!\n",
    "\n",
    "Then, *after* each code-cell corresponding to the ToDo, there are one or more code cell(s) with \"tests\" written by us. These tests may provide you with feedback about whether you implemented the \"ToDo\" correctly, and optionally gives you some hints on how to solve your error(s). If you run this cell and you don't get any errors, you did it correctly and you'll receive the point(s) for that ToDo. If it gives any errors, try to use the information from the error and/or print statements to solve the ToDo. \n",
    "\n",
    "These tests are usually implemented as a set of `assert` statements, which 'assert' whether a specific statement is true. If it evaluates to `False`, then that means you've made an error. For example, for the above `ToDo`, we simply evaluated the statement `assert(x == 5)` to check whether you set `x` to 5 correctly, as is shown in the cell below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "8dc07aa1bc2445444d614a80e1935ee9",
     "grade": true,
     "grade_id": "cell-9eb6167410bb1e5b",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Checks whether the above ToDo is correct. '''\n",
    "try:\n",
    "    assert(x == 5)\n",
    "except AssertionError as e:\n",
    "    print(\"x does not evaluate to 5! Did you replace 'not yet 5' with 5?\")\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: this week, each *ToDo* is explicitly tested, so you can always check your answer (and continue trying until you get it right). However, from next week onwards, we will also include **hidden tests**, which you won't see. We will only run these tests when grading your notebook. Therefore, from next week onwards, passing all tests in your ToDos/Assignments does not necessarily mean that you will score a 100% for that week's lab, because you might have made a mistake in the hidden tests.\n",
    "\n",
    "For this week, however, there are no hidden tests, so you can continue working on your ToDos until you get the answer right. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's try another one, but this time for real! It's a super simple one, so use this to earn a free point. Note that it is followed by two test-cells, which test different aspects of your implementation (each passed test gives you 0.5 points)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "In the code-cell below, set the variable `y` to `x * 2`, so you have to replace `None` with `x * 2` (yes, this is as easy as it sounds)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "bb91a25084e5ac82d8f0b0929c68a407",
     "grade": false,
     "grade_id": "cell-ab70f6aba1198918",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "x = 2\n",
    "y = None\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "d2e7b35c0f870512d39aa61fdd8c033c",
     "grade": true,
     "grade_id": "cell-3beed6559429c800",
     "locked": true,
     "points": 0.5,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' This tests the above ToDo. '''\n",
    "try:\n",
    "    assert(y == x * 2)\n",
    "except AssertionError as e:\n",
    "    print(\"y does not evaluate to x * 2 (i.e., 4)! Did you replace y with x * 2?\")\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "855c4a008ece8f9a9de5ca365c382e46",
     "grade": true,
     "grade_id": "cell-4bc66c72a83cb48e",
     "locked": true,
     "points": 0.5,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' This tests the above ToDo as well. '''\n",
    "try:\n",
    "    assert(isinstance(y, int))\n",
    "except AssertionError as e:\n",
    "    print(\"y doesn't seem to be an integer (it is of type %s; make sure it is!\" % type(y))\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-danger\">\n",
    "<b>WARNING</b>: You might think that simply editing the test-cell such that everything passes (e.g. by removing the assert statement) is a smart way to get all the points; we however record the original state of the (test-)cells in a database, and we'll use those tests to grade your answers, so no easy way to cheat!\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Throughout the notebook you'll encounter several 'ToDos' - some are worth points, some are not. In addition to these 'ToDos', you'll also encounter 'ToThinks', which are short questions about the material, meant to make you think about what you're doing. Like the 'ToDos', some of these are worth points, others don't. Each 'ToThink' cell is followed by a markdown-cell in which you can write your answer. Obviously, these answers cannot be automatically tested, so there won't be a test-cell with `asserts`. These 'ToThinks' are graded manually by us. \n",
    "\n",
    "A typical 'ToThink' may look like this:  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-info'>\n",
    "<b>ToThink</b> (1 point)\n",
    "</div>\n",
    "\n",
    "What's your name? Please write it in the text-cell below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "2710a9a42938c9e699491d3bd74afbc5",
     "grade": true,
     "grade_id": "cell-1b7dde716f8757c0",
     "locked": false,
     "points": 1,
     "schema_version": 3,
     "solution": true
    }
   },
   "source": [
    "YOUR ANSWER HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Make sure you actually write your name in the cell above for another free point! (You'll have to double-click the text-cell to go into 'edit mode' and replace 'YOUR ANSWER HERE' with your name.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next to 'ToDos' and 'ToThinks', some labs may contain 'Assignments'. These are basically just a collection of programming exercises and/or open questions, each with a certain amount of points associated with it. You'll encounter assignments usually at the end of a specific section. Usually, altogether these assignments are worth substantially more points than 'ToDos' or 'ToThinks'.\n",
    "\n",
    "An assigment may look like this:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-danger'>\n",
    "<b>Assignment</b> (5 points)\n",
    "</div>\n",
    "\n",
    "This is an example assignment; it's not actually worth any points. In a real assignment, you would see one or more coding assignments or open questions below. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. General Python\n",
    "This section will provide short tutorial on basic Python syntax and concepts (if you've done Codecademy, this should all be familiar).\n",
    "\n",
    "Here, we will cover:\n",
    "\n",
    "* Python data types (integers, floats, lists, dictionaries)\n",
    "* Python functions\n",
    "* Python classes\n",
    "* Conditionals (if-then-else)\n",
    "* Loops (for-loop, list-comprehensions)\n",
    "* Imports\n",
    "\n",
    "**Note**: while there are exercises in this section, there are not worth any points. So if you feel comfortable with Python, you may skip it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1. Structure of Python\n",
    "\n",
    "Python is a multipurpose programming language, meaning it can be used for almost anything. While the \"standard library\" of Python (i.e., the functionality that is shipped with any Python installation) contains the bare minimum for any programming language, Python's versatility comes from a massive community of developers that created many different \"third-party\" packages for almost any purpose you can think of (e.g., visualization, machine learning, web frameworks, etc.).\n",
    "\n",
    "For example:\n",
    "* the [scipy](https://www.scipy.org/) package provides functionality for scientific computing (e.g. statistics, signal processing);\n",
    "* the [numpy](http://www.numpy.org/) package provides data structures and functionality for (very fast) numeric computing (e.g. multidimensional numeric array computations, some linear algebra);\n",
    "* the [matplotlib](http://matplotlib.org/) package provides plotting functions;\n",
    "* and various specialied neuroimaging packages provide functionality to work and analyze (f)MRI (e.g. [nibabel](http://nipy.org/nibabel/) and [nipype](http://nipy.org/nipype)) and MEG/EEG (e.g. [MNE](http://www.martinos.org/mne/stable/index.html)).\n",
    "\n",
    "Basically, there are packages for everything you can think of (also: creating websites, game programming, etc.)! In this course, we will mostly use basic Python in combination with the scientific computing packages ('numpy', 'scipy') and specialized neuroimaging packages ('nibabel', 'nipype').  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Import statements\n",
    "As explained above, Python ships with some default functionality. This means that it's already available upon starting a notebook (or any other Python environment) and doesn't need to be imported. An example is the function `len()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_list = [1, 2, 3]\n",
    "print(len(my_list))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, non-built-in packages - such as `numpy` - need to be explicitly imported to access their functionality. After importing, their functions are accessible as: `{package}.{function}`.\n",
    "\n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy\n",
    "\n",
    "# Now you can access the numpy function `add()` as numpy.add()\n",
    "print(numpy.add(5, 3)) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, writing `numpy` in front of every function you access from it becomes annoying very quickly. Therefore, we usually abbreviate the package name by two or three characters, which can be achieved through:\n",
    "\n",
    "```\n",
    "import {package} as {abbreviation}\n",
    "```\n",
    "\n",
    "For example, people usually abbreviate the numpy import as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "# Now you can access numpy functions such as 'add()' as:\n",
    "print(np.add(5, 3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Often (but not always), Python packages consist of subpackages. These subpackages are often used to group similar functions/code together. For example, the `numpy` package has the subpackage (also called \"module\") `random`, which contains functions that allow you to generate random data from different distributions.\n",
    "\n",
    "In the previous cell, we imported the **entire** `numpy` package by running `import numpy as np`. However, sometimes you might only need a particular subpackage (\"module\"), like the subpackage `random` from `numpy`. To import **only** the `random` subpackage, you can do the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy.random"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, you can use functions from the `numpy.random` class! Technically, even subpackages may contain their own subpackages. Importing subpackages from subpackages works the same way:\n",
    "\n",
    "```import mainpackage.somesubpackage.anothersubpackge.yetanothersubpackage\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Throughout the tutorials, you'll see different packages (e.g. `nibabel` and `scipy`) being imported using abbreviations (e.g., `import nibabel as nib`). \n",
    "\n",
    "Also, you don't need to import an *entire* package, but you can also import a specific function or class. This is done as follows:\n",
    "\n",
    "```\n",
    "from {package} import {function1}, {function2}, {etc}\n",
    "```\n",
    "\n",
    "An example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy import add, subtract\n",
    "\n",
    "# Now I can simply call add() and subtract()\n",
    "print(add(5, 3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that some packages have a hierarchical structure with subpackages (also called modules). For example, scipy has a subpackage `ndimage` (with functions for n-dimensional arrays). To import *only* this subpackage, do the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy import ndimage\n",
    "# Now you can call functions from the ndimage subpackage,\n",
    "# e.g. gaussian_filter\n",
    "\n",
    "print(ndimage.gaussian_filter([10, 5, 4], 2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that you can mix and match all of these operations to customize the import to your own liking (see cell below for such a fancy import). In this course, we'll usually just import entire packages (e.g. `import numpy as np`) or specific functions/subpackages (e.g. `from scipy import stats`). \n",
    "\n",
    "Another thing you can do with imports is renaming the function/module you're importing. This follows the following syntax:\n",
    "\n",
    "```\n",
    "from {package} import {some function/module} as {new name}\n",
    "```\n",
    "\n",
    "See the cell below for an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# a fancy import\n",
    "from scipy.stats import binom_test as omg_binomial_testing_so_cool\n",
    "\n",
    "print(omg_binomial_testing_so_cool(0.5, 10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Import the function \"randn\" (which generates random numbers from a standard normal distribution) from the numpy subpackage \"random\" and rename it \"random_normal_generator\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "43f2423d1c20ef21c402a16a73bc0c27",
     "grade": false,
     "grade_id": "cell-87af56a740628389",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "c4915239b2ad8cdb97990e25181caa20",
     "grade": true,
     "grade_id": "cell-f7c6fda0670851b5",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "try:\n",
    "    assert('random_normal_generator' in dir())\n",
    "except AssertionError as e:\n",
    "    print(\"I couldn't find the function 'random_normal_generator'; did you spell it correctly?\")\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "5b2e1c58cd877ed7d81c4bbae39aad9f",
     "grade": true,
     "grade_id": "cell-2ec6efb629701eda",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Another test for the above ToDo. '''\n",
    "try:\n",
    "    assert(random_normal_generator.__name__ == 'randn')\n",
    "except AssertionError as e:\n",
    "    print(\"Your 'random_normal_generator' function does not point to the 'randn' numpy.random subpackage!\")\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-danger\">\n",
    "<b>Wildcard imports.</b> Python allows also \"wildcard\" imports, like: <code>from numpy import *</code>, which says: import <em>everything</em> from the <code>numpy</code> package. This is often discouraged, because the beauty of having explicit imports (unlike MATLAB) is that you known where your functions come from (e.g., is it a base Python function or a numpy function?). \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Whitespace for indentation\n",
    "In most programming languages, code blocks (e.g., if-else blocks, or for-loops) are delineated by dedicated symbols (often curly brackets, `{}`). For example, an if-else block in R is written like this:\n",
    "\n",
    "```\n",
    "if (x > 0) {\n",
    "   y = x + 5\n",
    "} else {\n",
    "   y = x - 5\n",
    "}\n",
    "```\n",
    "\n",
    "While in languages like R and MATLAB whitespace/indentation is used for readability, it is not necessary! The above if-else statement in R can also be written as:\n",
    "\n",
    "```\n",
    "if (x > 0) { y = x + 5 } else { y = x - 5 }\n",
    "```\n",
    "\n",
    "However, in Python, whitespace and indentation is important! In Python, indendation - instead of curly braces - delineates code blocks, and if code is incorrectly indented, Python will give an error! For example, an if-else statement in Python must be indented (always with 4 spaces or a tab). If you don't do this, it will give an `IdentationError`, as show below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 0\n",
    "if x < 0:\n",
    "y = x + 5\n",
    "else:\n",
    "y = x - 5   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you make sure the two statements beginning with `y = ...` are indented with 4 spaces/a tab, the error disappears."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Fix the code block above by identing it correctly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Note: Python versions\n",
    "As a side note: there are currently two different supported versions of Python, 2.7 and 3.x (with \"x\" being at 3.7 currently). Somewhat confusingly, Python 3.0 introduced many backwards-incompatible changes to the language, so code written for 2.7 may not work under 3.x and vice versa. For this class all code will use Python **3.6** (but 90% of this notebook should be compatible with Python 2.7., we think ...). So if you want to use code from this class on your own computer, make sure you use Python 3.6 (or higher)!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2 Basic data types\n",
    "Base (i.e. built-in) Python has mostly the same data types as you might know from MATLAB or R, such as numbers (integers/floats), strings, and lists (cells in MATLAB; lists in R). Also, Python has to data types that might be unknown to MATLAB/R users, such as \"dictionaries\" and \"tuples\", which are explained later. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.1. Numbers\n",
    "Numbers are represented either as integers (\"whole\" numbers) or floats (numbers with decimals, basically)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 3\n",
    "print('x is of type', type(x))  # use type(variable) to find out of what data-type something is!\n",
    "\n",
    "y = 3.1415\n",
    "print('y is of type', type(y))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's try to apply arithmetic to x as defined above with some basic operations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(x + 1)   # Addition;\n",
    "print(x - 1)   # Subtraction;\n",
    "print(x / 2)   # Division;\n",
    "print(x * 2)   # Multiplication;\n",
    "print(x ** 2)  # Exponentiation;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above commands apply operations to x, but do not *change* x itself. To permanently change x, you have to store the results of the operation (e.g. `x + 1`) into a variable (e.g. `x2 = x + 1`), as shown in the cell below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 3\n",
    "x_new = x + 2\n",
    "\n",
    "# If you simply want to update an existing variable, you can do this in two ways:\n",
    "x = x + 1\n",
    "\n",
    "# ... or:\n",
    "x += 1\n",
    "\n",
    "print(x)  \n",
    "\n",
    "x *= 2 # This is the same as: x = x * 2\n",
    "print(x) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "<b>ToDo</b> (0 points) \n",
    "</div>\n",
    "\n",
    "In the cell below, make a new variable, `y`, which should contain `x` minus 5 and subsequently raised to the 4th power."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "f5764a32deafdc2140572c18ec083ed9",
     "grade": false,
     "grade_id": "cell-b1f3eff2d86022f9",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "x = 8\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "0bc4db91858dbdd4648d2f64f9939ec6",
     "grade": true,
     "grade_id": "cell-86a18c4fb5804a78",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo.'''\n",
    "\n",
    "# Check if there exists a variable 'y'\n",
    "try:\n",
    "    assert('y' in dir())\n",
    "except AssertionError as e:\n",
    "    print(\"The variable 'y' doesn't seem to exist! Did you name it correctly?\")\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done! 1 out of tests 2 passed\")\n",
    "\n",
    "# Check if it has the correct number\n",
    "try:\n",
    "    assert(y == 81)\n",
    "except AssertionError as e:\n",
    "    print(\"The variable y does not seem to equal x minus 5, raised to the power 4.\")\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done! 2 out of tests 2 passed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-success'>\n",
    "    <b>Tip!</b>\n",
    "    When you're working on your ToDo, it's often informative to print (intermediate) output/variables of your solution (in a new code cell for example). This might give insight into (potentially) failing tests! \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.2. Booleans\n",
    "Python implements all of the usual operators for comparisons. Similar to what you might know from other languages, `==` tests equivalence, `!=` for not equivalent, and `<` and `>` for larger/smaller than. The result of those comparisons are a datatype called a \"boolean\", representing truth values. Booleans can take on the value `True` or `False`.\n",
    "\n",
    "Check out some examples below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = 3\n",
    "b = 5\n",
    "is_a_equal_to_b = (a == b)\n",
    "\n",
    "print(is_a_equal_to_b)\n",
    "print('the ouput is of type', type(is_a_equal_to_b)) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some more examples of Boolean operators:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bool_1 = 3 > 5 # False, because 3 is not greater than 5\n",
    "bool_2 = (5 == 5) # True, because, well, 5 is 5\n",
    "print(bool_1)\n",
    "print(bool_2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, for some Boolean logic, python doesn't use operators (such as && for \"and\" and | for \"or\") but uses special (regular English) **words**: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# note: bool_1 is False, bool_2 is True\n",
    "print(bool_1 and bool_2)  # Logical AND, both have to be True\n",
    "print(bool_1 or bool_2)   # Logical OR, either one of them has to be True\n",
    "print(not bool_1)         # Logical NOT, the inverse of bool_1\n",
    "print(bool_1 != bool_2)   # Logical XOR, yields True when bool_1 and bool_2 are not equal"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(Although, technically, the keyword `and` and `&`, and `or` and `|` can be used interchangeably.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Mess around with booleans in the cell below. Try some more complex things, like: `not ((3 > 5) and not (5 < 2))`. \n",
    "Do you understand why the result is the way it is? Try to follow the logic in the sequence of statements (not graded, so no tests follow the code block)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Do your ToDo here:\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.3. Strings\n",
    "Strings in Python are largely the same as in other languages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "h = 'hello'   # String literals can use single quotes\n",
    "w = \"world\"   # or double quotes; it does not matter.\n",
    "\n",
    "print(h)\n",
    "print(len(h))  # see how many characters in this string"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A very nice feature of Python strings is that they are easy to concatenate: just use '+'!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hw = h + ', ' + w + '!' # String concatenation\n",
    "print(hw)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also create and combine strings with what is called 'string formatting'. This is accomplished by inserting a placeholder in a string, that you can fill with variables. An example is given below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Here, we have a string with a placeholder '%s' (the 's' refers to 'string' placeholder)\n",
    "my_string = 'My favorite programming language is: %s'\n",
    "print('Before formatting:')\n",
    "print(my_string)\n",
    "\n",
    "# Now, to 'fill' the placeholder, do the following:\n",
    "my_fav_language = 'Python'\n",
    "my_string = 'My favorite programming language is: %s' % my_fav_language\n",
    "\n",
    "print('After formatting')\n",
    "print(my_string)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use specific placeholders for different data types:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "week_no = 1 # integer\n",
    "string1 = 'This is week %i of neuroimaging' % week_no # the %i expects an integer!\n",
    "print(string1)\n",
    "\n",
    "project_score = 99.50 # float\n",
    "string2 = 'I will get a %f on my midterm exam!' % project_score\n",
    "print(string2)\n",
    "\n",
    "# You can also combine different types in a string:\n",
    "string3 = 'In week %i of neuroimaging, %s will get a %f (or higher) for my lab-assignment' % (week_no, \"I\", 95.00)\n",
    "print(string3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For a full list of placeholders see https://docs.python.org/2/library/stdtypes.html#string-formatting-operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 point)\n",
    "</div>\n",
    "\n",
    "Modify the variable `to_print` defined below, such that printing it (i.e., running `print(to_print)`) will print:\n",
    "\n",
    "```\n",
    "Neuroimaging will be my favorite course 4ever\n",
    "```\n",
    "So you'll have to \"fill\" the \"%\" placeholders using string formatting. That is, you have to put a `%` sign after the `to_print` variable and \"fill\" it with the correct inputs. And don't forget to remove the `NotImplementedError`.\n",
    "\n",
    "(This is a manually graded answer, so no tests!)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "1eee594b23d327a793aadbf548da3c98",
     "grade": false,
     "grade_id": "cell-b08c34ab23707a68",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "to_print = \"%s will be my favorite course %iever\"\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "5ea86aeab0930fbaa1c43cdead1d5d6e",
     "grade": true,
     "grade_id": "cell-eb152527160ad636",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo'''\n",
    "try:\n",
    "    assert(to_print == 'Neuroimaging will be my favorite course 4ever')\n",
    "except AssertionError as e:\n",
    "    print(\"This string is not formatted correctly!\")\n",
    "    raise(e)\n",
    "else:\n",
    "    print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.4. Lists\n",
    "A list is the Python equivalent of an array, but can be resized and can contain elements of different types. It is similar to a list in R and a cell in MATLAB. Note that indices in python start with 0! This means that the 3rd element of the list below is accessed through `[2]`.\n",
    "\n",
    "Let's check out some lists and how to index them!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note that list may contain numbers ...\n",
    "list1 = [3, 1, 2]\n",
    "\n",
    "# ... or strings\n",
    "list2 = ['hello', 'world']\n",
    "\n",
    "# ... or, actually, anything at all! List lists themselves\n",
    "list3 = ['hello', [3, 1, 2], 'world', 5.3, -999]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whatever the contents of a list, they are indexed the same way: using square brackets with an integer, e.g. `[0]`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print('The first element of list1 is: %i' % list1[0])\n",
    "print('The second element of list2 is: %s' % list2[1])\n",
    "print('The last element of list3 is: %i' % list3[-1])\n",
    "print('The second-to-last element of list3 is: %f' % list3[-2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that you can also use negative indices! Negative indices start indexing from the end of the list, so `[-1]` indexes the last element, `[-2]` indexes the second-to-last element, etc.\n",
    "\n",
    "We cannot only 'extract' element from lists using indexing, but we can also replace them! This works as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "some_list = [1, 2, 3, ['A', 'B', 'C']]\n",
    "\n",
    "# Let's set the first element of some_list to 100:\n",
    "some_list[0] = 100\n",
    "print(some_list)\n",
    "\n",
    "# Note that indexing a list within a list is done with sequential square brackets,\n",
    "# so if we want to index the element 'A' in some_list, we do:\n",
    "some_list[-1][0] = 'ANOTHER STRING'\n",
    "print(some_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "In the cell below, replace the element 'TO_REPLACE_1' with 'REPLACED' and the element 'TO_REPLACE_2' also with 'REPLACED' in the list `todo_list`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "ed823e1e79d18d70834f97f9088f602d",
     "grade": false,
     "grade_id": "cell-fcaca4cbf6963307",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "todo_list = [1, 'B', 'TO_REPLACE_1', [5, 3, 1038, 'C'], [1, 3, 5, [9, 3, 1, 'TO_REPLACE_2']]]\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: the code-cell below as usual tests your ToDo, but we haven't written out the tests in the cell itself. Instead, we wrote the tests in a separate Python module (a file with a collection of functions, objects, etc.), which we import here. (We do this, because writing out the tests here would give you the answer rightaway!)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "3608747d0ed9f305a6ccc1aa14d60f78",
     "grade": true,
     "grade_id": "cell-6cc25540df324d7d",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo with a custom function. '''\n",
    "# Below, we import all the tests (*) from the neuroedu package\n",
    "from nb_tests import test_list_indexing\n",
    "test_list_indexing(todo_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to accessing list elements one at a time, Python provides concise syntax to access specific parts of a list (sublists); this is known as **slicing**. \n",
    "\n",
    "Let's look at some slice operations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n",
    "print(nums)         # Our original list\n",
    "\n",
    "# Get a slice form index 2 to 4 (exclusive); prints \"[2, 3]\"\n",
    "print(nums[2:4])    \n",
    "\n",
    "# Get a slice from index 2 to the end; prints \"[2, 3, 4, 5, 6, 7, 8, 9]\"\n",
    "print(nums[2:])  \n",
    "\n",
    "# Get a slice from the start to index 3 (exclusive); prints \"[0, 1, 2]\"\n",
    "print(nums[:3])     \n",
    "\n",
    "# Get a slice of the whole list; prints [\"0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\"\n",
    "print(nums[:])\n",
    "\n",
    "# Slice indices can be negative; prints [\"0, 1, 2, 3, 4, 5, 6, 7, 8]\",\n",
    "# so everything up to (but not including) the last element\n",
    "print(nums[:-1])    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Importantly, slices are ënd exclusive\", which means that if you slice from `0` to `5`, you get the indices `0, 1, 2, 3, 4`! While this may seem confusing at first, you'll get used to it. To appreciate the use of \"end exclusive indexing\", do the next ToDo."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Slice the list below, `to_be_split`, into two separate lists: one called `first_half` with the first half of the list values, and one called `second_half`, with the second half of the list values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "ad601645ce2d3acf39debc98cac6894b",
     "grade": false,
     "grade_id": "cell-f5cbfc80f5ab048f",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "to_be_split = [10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25]\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "2772ab129259615795e9dbfc4d856748",
     "grade": true,
     "grade_id": "cell-c58380642ef1d9f6",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo '''\n",
    "assert(first_half == [10, 11, 12, 13, 14, 15, 16, 17])\n",
    "assert(second_half == [18, 19, 20, 21, 22, 23, 24, 25])\n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Apart from the syntax `[from:to]`, you can also specify a \"stride\" (sort of step-size) of your slice using the syntax `[from:to:stride]`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Return values in steps of 2\n",
    "print(nums[::2])    \n",
    "\n",
    "# Returns values in steps of 3, but starting from the second element\n",
    "print(nums[1::3])   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With 'normal' indexing of lists, you can only index a subsequently set/replace one element at the time. With slices, however, you can set multiple elements at the same time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums[2:4] = [100, 200] # Assign a new sublist to a slice\n",
    "print(nums)         # Prints \"[0, 1, 100, 200, 4, 5, 6, 7, 8, 9]\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<font color='blue'><b>Tip</b></font>: instead of creating sequential lists like:\n",
    "\n",
    "`num = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]`\n",
    "\n",
    "... we can also create a list using the syntax: \n",
    "\n",
    "`num = list(range(starting_point, exclusive_end_point))`\n",
    "\n",
    "For example, to create a list from 5 to 15, use the following:\n",
    "\n",
    "`num = list(range(5, 16))` \n",
    "\n",
    "We'll use this construction (`list(range(x, y))`, or without the `list`) quite often in this course!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "From the list (`my_list`) below, extract the numbers 2, 3, 4, 5, and 6 using a slice and store it in a new variable named `my_new_list`!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "df2e1183f447b3c478d4b0bb7376967e",
     "grade": false,
     "grade_id": "cell-daeb7ca767d21986",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "my_list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "9e237d5227d06b6f49e9eb70f49cdf0d",
     "grade": true,
     "grade_id": "cell-326bc8ff7960e645",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "from nb_tests import test_slicing_1\n",
    "available_vars = dir()\n",
    "if 'my_new_list' not in available_vars:\n",
    "    raise ValueError(\"You did not store the results in a new variable caleld 'my_new_list'!\")\n",
    "    \n",
    "test_slicing_1(my_new_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 point) \n",
    "</div>\n",
    "\n",
    "From the list below (`my_list_2`), extract the values `[5, 7, 9, 11]` using a slice (i.e., in a single operation!) and store it in a new variable named `my_new_list_2`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "aadd3e5a614c9a886a431dc42c096aea",
     "grade": false,
     "grade_id": "cell-cfe59b0d7902a00a",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "my_list_2 = [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21]\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "682475127fda308c30c32b13bf89d625",
     "grade": true,
     "grade_id": "cell-fac7511a9ff08758",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo '''\n",
    "from nb_tests import test_slicing_2\n",
    "available_vars = dir()\n",
    "\n",
    "if 'my_new_list_2' not in available_vars:\n",
    "    raise ValueError(\"You didn't define the variable 'my_new_list_2'!\")\n",
    "\n",
    "test_slicing_2(my_new_list_2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE**: you can index *strings* the same way as you index lists! Try to see it this way: a string is, quite literally, a *string* (\"list\") of characters. So, to get the first letter of some string s (e.g, 'this is a string'), you simply write: `s[0]`. To get first 5 characters, you write `s[:5]`, etc etc. Remember this!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check out string slicing/indexing below\n",
    "s = 'neuroimaging'\n",
    "print(s[0:7:2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Dictionaries\n",
    "Dictionaries might be new for those who are used to MATLAB or R. Basically, a dictionary is an **unordered** list in which list entries have a name (which is also referred to as a \"key\"). To get a value from a dictionary, you have to use the \"key\" as index instead of using an integer (although, strictly speaking, keys can also be integers ... but that's not important for now).\n",
    "\n",
    "Let's check out such a dictionary and how to index it. We build a dictionary using the following syntax: \n",
    "\n",
    "`{some_key: value, another_key: another_value, etc: etc}`\n",
    "\n",
    "The keys can be anything! Strings, integers, lists ... doesn't matter! Mostly, though, strings are used as keys. \n",
    "So, let's look at an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_dict = {'cat': 'cute', 'dog': 'furry'}  # Create a new dictionary with some data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To index a dictionary, we'll use square brackets `[]` again, just like with lists. But now, we can index using the key!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "indexed_value = my_dict['cat']\n",
    "print(indexed_value)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Adding new key-value pairs to dictionaries is easy! Just index it with a new key, and assign the value to it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_dict['fish'] = 'wet'     # Set an entry in a dictionary\n",
    "print(my_dict['fish'])      # Prints \"wet\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like a list, an entry in a dictionary can be of any data type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_dict['rabbit'] = ['omg', 'so', 'cute']\n",
    "print(my_dict['rabbit'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you try to 'index' a dictionary with a key that doesn't exist, it raises a \"KeyError\", which means you're trying to index something that doesn't exist:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(my_dict['monkey'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "In the code cell below, add a new key to the dictionary `my_dict` named `\"rat\"` and with the value `\"nasty\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "7173fd8423884f5dff6927e53a79fb1f",
     "grade": false,
     "grade_id": "cell-121f9f1b0a5263be",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Add the key-value pair here!\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "fc3b082b366fed30f3dd98b44499e4c3",
     "grade": true,
     "grade_id": "cell-0db58b3f530e7219",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "\n",
    "try:\n",
    "    assert('rat' in my_dict)\n",
    "except AssertionError as e:\n",
    "    print(\"There exists no key 'rat' in my_dict!\")\n",
    "    raise(e)\n",
    "\n",
    "try:\n",
    "    assert(my_dict['rat'] == 'nasty')\n",
    "except AssertionError as e:\n",
    "    print(\"The value of key 'rat' is '%s' and NOT 'nasty'\" % my_dict['rat'])\n",
    "\n",
    "print('Well done!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 point)\n",
    "</div>\n",
    "\n",
    "Values of dictionaries can be any type of object, even dictionaries themselves! So, add a new key to the dictionary `my_dict` named `\"another_dict\"` with the value of *another* dictionary with the keys `\"a\"` and `\"b\"` and the corresponding values `1` and `2`. Also, try to figure out how to index the value `1` from the 'nested' dictionary (this is not graded, but try it nonetheless!)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "681884a8b2eef98295497fe5a747c4ea",
     "grade": false,
     "grade_id": "cell-8c0d0b8e890bfb78",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Do the ToDo here\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "50e8e5703173e11917387b66cdcbb3ef",
     "grade": true,
     "grade_id": "cell-83ed96f5b23bddbe",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "\n",
    "try:\n",
    "    assert('another_dict' in my_dict)\n",
    "except AssertionError as e:\n",
    "    print(\"There exists no key 'another_dict' in my_dict!\")\n",
    "    raise(e)\n",
    "\n",
    "try:\n",
    "    assert(my_dict['another_dict']['a'] == 1)\n",
    "    assert(my_dict['another_dict']['b'] == 2)\n",
    "except AssertionError as e:\n",
    "    print(\"The key 'another_dictionary' should contain a dictionary with keys 'a' and 'b', corresponding\"\n",
    "          \"to values 1 and 2, respectively.\")\n",
    "    raise(e)\n",
    "\n",
    "print('Well done!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### tuples\n",
    "Tuples are very much like lists, but the main difference is that they are immutable. In other words, after creating them, they cannot be modified (their values cannot be replaced/altered):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# A list can be modified ...\n",
    "my_list = [1, 2, 3]\n",
    "my_list[0] = 0\n",
    "print(my_list)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ... but a tuple cannot (and will give an error!)\n",
    "my_tuple = (1, 2, 3)\n",
    "print(my_tuple[0]) # you can print parts of tuple ...\n",
    "my_tuple[0] = 0   # but you cannot modify it!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You probably won't use tuples a lot, but you might come across them when using and writing functions, as multiple outputs from functions are stored in tuples (see below; but more about that in the next section!)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def my_epic_function(integer):\n",
    "    \n",
    "    return integer, integer * 2\n",
    "\n",
    "outputs = my_epic_function(10)\n",
    "print(outputs)\n",
    "print(type(outputs))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.3 Functions and methods\n",
    "If you followed the Codecademy tutorial, you are familiar with the basic syntax of functions in Python; if you're familiar with other programming languages, you'll see that the syntax of Python functions is quite similar to what you're used to.\n",
    "\n",
    "A function definition in Python starts with the keyword `def`, followed by the function name and round brackets with the arguments to the function, and finally the contents of the function, like so (note the indentation with four spaces/tab!!!):\n",
    "\n",
    "```python\n",
    "def my_awesome_function(arg_1, arg_2):\n",
    "    print(\"Argument 1: %s\" % arg_1)\n",
    "    print(\"Argument 2: %s\" % arg_2)\n",
    "```\n",
    "\n",
    "This dummy-function above prints some stuff, but does not **return** something. Similar to R (but unlike MATLAB), you have to explicitly state what you want to **return** from the function by the \"return\" statement. \n",
    "\n",
    "So, suppose you have a function that adds 2 to any number. Let's define it as follows (you have to run the cell to let Python know you've defined this function):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add_2_to_a_number(some_number):\n",
    "    new_number = some_number + 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we omitted a **return** statement to return the value of `new_number`. This is a problem, because in Python (like most languages) you cannot 'peek' inside the function after using it! You can only access whatever is returned. \n",
    "\n",
    "So, in the function defined above, we cannot access the value of `new_number`, because we didn't return it (so it will give an error):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This will give an error!\n",
    "add_2_to_a_number(5)\n",
    "print(new_number)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, to access the *value* of `new_number` (that is, *not* `new_number` itself, but its associated value), we need to return it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add_2_to_a_number_fixed(some_number):\n",
    "    new_number = some_number + 2\n",
    "    return new_number"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "value_contained_in_new_number = add_2_to_a_number_fixed(5)\n",
    "print(\"Results of function 'add_2_to_a_number' with argument '5': %i\" % value_contained_in_new_number)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Importantly, you can name the variable to which you assign the return value *anyway you like*. This doesn't have to be `new_number`! Like above, we named it `value_contained_in_new_number`, but it really doesn't matter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points) \n",
    "</div>\n",
    "\n",
    "In the code cell below, we've started writing a function named `extract_last_element` that takes one input-argument - a list - and returns the last element of the list. Some parts of the function are missing, though, which you need to write! When you're done, run the test-cell below it to check if it's right!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "5fdbf4e12fbca1900271b1181837a46d",
     "grade": false,
     "grade_id": "cell-844cc0bf2fe08f21",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "def extract_last_element(input_list):\n",
    "    \n",
    "    # YOUR CODE HERE\n",
    "    raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "c25a25f905077c19a0db7b203f6dc70d",
     "grade": true,
     "grade_id": "cell-cce2e863aae1f1d8",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "try:\n",
    "    assert(extract_last_element(input_list=[0, 1, 2]) == 2)\n",
    "except AssertionError as e:\n",
    "    print(\"Your function fails for input [0, 1, 2]\")\n",
    "    raise(e)\n",
    "\n",
    "try:\n",
    "    assert(extract_last_element(input_list=[0]) == 0)\n",
    "except AssertionError as e:\n",
    "    print(\"Your function fails for input [0]\")\n",
    "    raise(e)\n",
    "\n",
    "try:\n",
    "    assert(extract_last_element(input_list=['string1', 'string2', 'string3']) == 'string3')\n",
    "except AssertionError as e:\n",
    "    print(\"Your function fails for input ['string1', 'string2', 'string3']\")\n",
    "    raise(e)\n",
    "\n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alright, that was probably relatively easy. Let's do a slightly harder one."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 point) \n",
    "</div>\n",
    "\n",
    "Write a completely new function named `get_values_from_odd_indices` (so you have to write the `def ...` part!) that takes one input-argument - a list - and returns all values from the odd indices of that list. So, suppose you have a list:\n",
    "\n",
    "`[2, 100, 25, 48, 92, -5, 12]`\n",
    "\n",
    "... your function should return: \n",
    "\n",
    "`[100, 48, -5]`\n",
    "\n",
    "... i.e, the values from odd indices (here: 1, 3, 5; we exclude index zero!)\n",
    "\n",
    "Hint: slices might be useful here!\n",
    "\n",
    "When you're done, run the test-cell below it to check if it's right!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "5e9c114d79e997c4538fdff761d34a0b",
     "grade": false,
     "grade_id": "cell-b53fdc7b50d5fcf3",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Implement your function (called get_values_from_odd_indices) here:\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "a44b51b302202ea6cbe975295632b72c",
     "grade": true,
     "grade_id": "cell-f0aba01f8698280a",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the ToDo above. '''\n",
    "try:\n",
    "    assert('get_values_from_odd_indices' in dir())\n",
    "    assert(callable(get_values_from_odd_indices))\n",
    "except AssertionError as e:\n",
    "    print(\"Your function 'get_values_from_odd_indices' does not seem to exist!\")\n",
    "\n",
    "try:\n",
    "    out = get_values_from_odd_indices([0, 1, 2])\n",
    "    if out is None:\n",
    "        msg = \"ERROR: did you forget the Return statement?\"\n",
    "        raise ValueError(msg)\n",
    "except ValueError as e:\n",
    "    raise(e)\n",
    "    \n",
    "print(\"Well done (also run the next cell with tests)!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "bcc6e473b5348edbe7a7d68126a4e596",
     "grade": true,
     "grade_id": "cell-3dbc2e60c3240847",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Some other tests for the ToDo above. '''\n",
    "inp = [0, 1, 2]\n",
    "outp = get_values_from_odd_indices(inp)\n",
    "ans = [1]\n",
    "try:\n",
    "    assert(outp == ans)\n",
    "except AssertionError as e:\n",
    "    print(\"Your function returned '%r' but I expected '%r'\" % (outp, ans))\n",
    "    raise(e)\n",
    "\n",
    "inp = [5, 7, 9, 11, 13, 15, 18, 20, 21]\n",
    "outp = get_values_from_odd_indices(inp)\n",
    "ans = [7, 11, 15, 20]\n",
    "try:\n",
    "    assert(outp == ans)\n",
    "except AssertionError as e:\n",
    "    print(\"Your function returned '%r' but I expected '%r'\" % (outp, ans))\n",
    "    raise(e)\n",
    "\n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**IMPORTANT**: it is possible to return *multiple things* from a function. The function, then, returns these things as a tuple, which can subsequently be \"unpacked\". Let's check out an example using a custom function called `minmax_of_list` which returns both the minimum and maximum of a list:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def minmax_of_list(some_list):\n",
    "    ''' Returns both the minimum and maximum of a list.\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    some_list : list\n",
    "        A list with numbers (int/float) only\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    min_value : a float or int\n",
    "        The minimum of a list\n",
    "    max_value : a float or int\n",
    "        The maximum of a list\n",
    "    '''\n",
    "    min_value = min(some_list)\n",
    "    max_value = max(some_list)\n",
    "    \n",
    "    return min_value, max_value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, returning multiple things is a simple as adding more variables after the `return` statement, separated by commas. If we now call the function with a particular list, it gives us back a tuple of size 2 (one value for the minimum, one value for the maximum):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output_from_function = minmax_of_list([0, 1, 2, 3])\n",
    "print(output_from_function)\n",
    "print(type(output_from_function))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now \"unpack\" the tuple (i.e., extract the separate values) in several ways. One way is to simply index the values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output_from_function = minmax_of_list([0, 1, 2, 3])\n",
    "minimum = output_from_function[0]\n",
    "print(\"Minimum: %i\" % minimum)\n",
    "\n",
    "maximum = output_from_function[1]\n",
    "print(\"Maximum: %i\" % maximum)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, we can already \"extract\" one value, let's say the maximum (index 1 of the tuple) right after calling the function, so we can skip dealing with the tuple altogether:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "maximum = minmax_of_list([0, 1, 2, 3])[1]  # The [1] extracts the maximum from the output of the function immediately!\n",
    "print(\"Maximum: %i\" % maximum)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keep this feature of returning multiple things and tuple unpacking in mind for the rest of the course (you'll definitely encounter it more often!)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Write a function called `get_length_first_and_last_value` which takes a list as single input argument, and returns the length of the list (the first output), the first value of the list (the second output), and the last value of the list (the third output). So, e.g., for the list `[0, 1, 2, 3, 4]`, the function should return `(5, 0, 4)` (a tuple of length 3, with the three outputs). Note that it should work for lists of arbitrary lengths and value types!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "fda906aa4feb6ebc406134bddad0c88a",
     "grade": false,
     "grade_id": "cell-1d7353d763e789a1",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "3695a6c117a060981591dd15fcf6850a",
     "grade": true,
     "grade_id": "cell-2df42fc82e0bc822",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo'''\n",
    "try:\n",
    "    assert('get_length_first_and_last_value' in dir())\n",
    "    assert(callable(get_length_first_and_last_value))\n",
    "except AssertionError as e:\n",
    "    print(\"Your function 'get_length_first_and_last_value' does not seem to exist!\")\n",
    "\n",
    "out = get_length_first_and_last_value([0, 1, 2])\n",
    "if out is None:\n",
    "    msg = \"ERROR: did you forget the Return statement?\"\n",
    "    raise ValueError(msg)\n",
    "    \n",
    "if len(out) != 3:\n",
    "    msg = \"ERROR: you returned %i things; this should be 3!\" % len(out)\n",
    "    raise ValueError(msg)\n",
    "\n",
    "assert(out == (3, 0, 2))\n",
    "assert(get_length_first_and_last_value([2, 3, 4, 5, 6, 7]) == (6, 2, 7))\n",
    "assert(get_length_first_and_last_value([0]) == (1, 0, 0))\n",
    "assert(get_length_first_and_last_value(['a', 'b']) == (2, 'a', 'b'))\n",
    "\n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Methods\n",
    "However, in Python, functions are not the only things that allow you to 'do' things with data. In others' code, you'll often see function-like expressions written with periods, like this: `some_variable.function()`. These `.function()` parts are called 'methods', which are like functions 'inherent' to a specific type of object. In other words, it is a function that is applied to the object it belongs to. \n",
    "\n",
    "Different type of objects in Python, such as stings and lists, have their own set of methods. For example, the function you defined above (`extract_last_element()`) also exists as a method each list has, called `pop()`! (This is a builtin, standard, method that each list in Python has.) See for yourself in the block below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_list = [0, 5, 10, 15] \n",
    "print(my_list.pop())\n",
    "\n",
    "# You can also just do the following (i.e. no need to define a variable first!):\n",
    "print([0, 5, 10, 15].pop())\n",
    "\n",
    "# ... which is the same as:\n",
    "print(extract_last_element([0, 5, 10, 15]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Not only lists, but also other data-types (such as strings, dictionaries, and, as we'll see later, numpy arrays) have their own methods. How methods work exactly is not really important (this belongs to the topic of 'object-oriented programming'), but it is necessary to know **what** it does, as you'll see them a lot throughout this course. \n",
    "\n",
    "We'll show you a couple of (often-used) examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# For lists, we have .append()\n",
    "x = [0, 10, 15]\n",
    "x.append(20) # Add a new element to the end of the list using the append() method!\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: sometimes, methods modify the object (above: `x`) *in-place*, which means that the method does not return anything, so you don't have to assign it to a new variable. If you accidentally do this, the new object's value is `None`, as you see below: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = [0, 10, 15]\n",
    "x_new = x.append(20)\n",
    "print(x_new)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some often-used methods for dictionaries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_dict = {'a': 0, 'b': 1, 'c': 2}\n",
    "\n",
    "# The .values() method returns all the values of the dictionary \n",
    "print(list(my_dict.values()))\n",
    "\n",
    "# And the .keys() method returns all the keys of the dictionary\n",
    "print(list(my_dict.keys()))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: these dictionary-methods actually *do* return values! "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some often-used methods for strings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_string = 'neuroimaging is fun!'\n",
    "\n",
    "# The .upper() method returns the string in uppercase!\n",
    "print(my_string.upper())\n",
    "\n",
    "# The .count(substring) method returns the number of times a substring occurs in a string\n",
    "print(my_string.count('n'))\n",
    "\n",
    "# The .replace(old, new) method replaces substrings\n",
    "print(my_string.replace('fun', 'awesome'))\n",
    "\n",
    "# The .split(separator) splits a string into subparts (returned as a list)\n",
    "print(my_string.split(' '))  # split by whitespace"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Default arguments in functions/methods\n",
    "Importantly, and unlike most (scientific) programming languages, Python supports the use of 'default' arguments in functions. Basically, if you don't specify an optional argument, it uses the default:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def exponentiate_number(number, power=2):\n",
    "    return number ** power\n",
    "\n",
    "print(exponentiate_number(2)) # now it uses the default!\n",
    "print(exponentiate_number(2, 10)) # now it \"overwrites\" the default and uses power=10\n",
    "print(exponentiate_number(number=2, power=10)) # also note that you can 'name' arguments "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.4 If-statements\n",
    "If-elif-else statements in Python are quite straightforward. An example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 5\n",
    "\n",
    "if x > 0:\n",
    "    print('x is larger than 0')\n",
    "elif x < 0:\n",
    "    print('x is smaller than 0')\n",
    "else:\n",
    "    print('x must be exactly 0!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If-statements contain at least an `if` keyword, but optionally also one or more `elif` (\"else if\") statements and an optional `else` statement. We'll practice this (in a `ToDo`) after the section on Loops."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.4 Loops\n",
    "Loops in Python (for- and while-loops) are largely similar to MATLAB and R loops, with some minor differences in  their syntax:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "animals = ['cat', 'dog', 'monkey']\n",
    "for animal in animals:\n",
    "    print(animal)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Basically, each data type that is also an \"iterable\" (something that you can iterate over) can be used in loops, including lists, dictionaries, and tuples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# An example of looping over a list\n",
    "my_list = [1, 2, 3]\n",
    "for x in my_list:\n",
    "    print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "MATLAB users might be used to looping over indices instead of the actual list values, like the following:\n",
    "\n",
    "```\n",
    "for i=1:100\n",
    "    disp(some_list(i));\n",
    "end```\n",
    "\n",
    "In Python, however, you loop (by default) over the contents of a list:\n",
    "\n",
    "```\n",
    "for entry in some_list:\n",
    "    print(entry)\n",
    "```\n",
    "    \n",
    "If you want to access for the value **AND** the index, you can use the built-in `enumerate` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_list = ['a', 'b', 'c']\n",
    "for index, value in enumerate(my_list):\n",
    "    \n",
    "    print('Loop iteration number (index) = %i, value = %s' % (index, value))\n",
    "\n",
    "# Don't forget that Python indexing starts at zero!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Looping over a tuple (exactly the same as looping over a list)\n",
    "my_tuple = (1, 2, 3)\n",
    "for x in my_tuple:\n",
    "    print(x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Iterating over a dictionary can be done in a couple of ways!\n",
    "my_dict = {'a': 1, 'b': 2, 'c': 3}\n",
    "\n",
    "# Looping over the keys ONLY\n",
    "for key in my_dict:\n",
    "    print(key)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Looping over both the keys and the entries\n",
    "for key, entry in my_dict.items():\n",
    "    print(key, entry)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points) \n",
    "</div>\n",
    "\n",
    "Complete the function below - named `extract_values_smaller_than_0` - that takes a single list with numbers as input and returns a new list with *only the values smaller than 0* from the input-list. For example, suppose our input-list is:\n",
    "\n",
    "```\n",
    "[2, -5.3, 1.8, 0.0, -205.1, 6029]\n",
    "```\n",
    "\n",
    "... the function should return:\n",
    "\n",
    "```\n",
    "[-5.3, -205.1]\n",
    "```\n",
    "\n",
    "Hint: use an if-statement in combination with the `.append()` method of the empty list we initialized below (`list_to_return`) to fill the `list_to_return` variable in a for-loop. In other words, the function should contain an if-statement in a for-loop (in which you need to use the `.append()` method)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "b753ea5ea5372d6f569c05ef4eafa6c9",
     "grade": false,
     "grade_id": "cell-12b8cc33efcf2857",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Complete the function below (make sure to remove raise NotImplementedError!)\n",
    "def extract_values_smaller_than_0(input_list):\n",
    "    \n",
    "    # We initialize an empty list here (which you need to fill using a for-loop)\n",
    "    list_to_return = []\n",
    "    \n",
    "    # YOUR CODE HERE\n",
    "    raise NotImplementedError()\n",
    "    \n",
    "    return list_to_return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "2c9a1924c008015ab628c0b5859a5eda",
     "grade": true,
     "grade_id": "cell-edbdf3424641ffb9",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the ToDo above. '''\n",
    "inp = [-5, 2, 3, -8]\n",
    "outp = extract_values_smaller_than_0(inp)\n",
    "ans = [-5, -8]\n",
    "try:\n",
    "    assert(outp == ans)\n",
    "except AssertionError as e:\n",
    "    print(\"Your function  with input '%r' returned '%r', but I expected '%r'\" % (inp, outp, ans))\n",
    "    raise(e)\n",
    "    \n",
    "inp = [0, 2, -3]\n",
    "outp = extract_values_smaller_than_0(inp)\n",
    "ans = [-3]\n",
    "try:\n",
    "    assert(outp == ans)\n",
    "except AssertionError as e:\n",
    "    print(\"Your function  with input '%r' returned '%r', but I expected '%r'\" % (inp, outp, ans))\n",
    "    raise(e)\n",
    "\n",
    "inp = [0, 0, 0]\n",
    "outp = extract_values_smaller_than_0(inp)\n",
    "ans = []\n",
    "try:\n",
    "    assert(outp == ans)\n",
    "except AssertionError as e:\n",
    "    print(\"Your function  with input '%r' returned '%r', but I expected '%r'\" % (inp, outp, ans))\n",
    "    raise(e)\n",
    "\n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Advanced loops: list comprehensions\n",
    "Sometimes, writing (and reading!) for-loops can be confusing and lead to \"ugly\" code. Wouldn't it be nice to represent (small) for-loops on a single line? Python has a way to do this: using what is called `list comprehensions`. It does exactly the same thing as a for-loop: it takes a list, iterates over its entries (and does something with each entry), and (optionally) returns a (modified) list. \n",
    "\n",
    "Let's look at an arbitrary example of a for-loop over a list:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = [0, 1, 2, 3, 4]\n",
    "\n",
    "# Also, check out the way 'enumerate' is used here!\n",
    "for index, x in enumerate(nums):\n",
    "    nums[index] = x ** 2\n",
    "\n",
    "print(nums)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can make this code simpler using a list comprehension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = [0, 1, 2, 3, 4]\n",
    "squares = [x ** 2 for x in nums] # importantly, a list comprehension always returns a (modified) list!\n",
    "print(squares)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also, list comprehensions may contain if-statements!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "string_nums = ['one', 'two', 'three']\n",
    "starts_with_t = ['yes' if s[0] == 't' else 'no' for s in string_nums]\n",
    "print(starts_with_t)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Write a list comprehension that adds the string `'_check'` to each value in the list `my_list` below, except if the value is 'B'. (This is an optional ToDo to practice list comprehensions.) Note that (in this particular use of list-comprehensions) you always need *both* a \"if ..\" part *and* an \"else ...\" part! So, can you think of a way to add nothing to a string (i.e., the \"else ...\", when the element is not 'B', part of this list comprehension)?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_list = ['A', 'B', 'C', 'D']\n",
    "# Implement your list comprehension here!\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "List comprehensions are somewhat of a more advanced Python concept, so if you don't feel comfortable using them (correctly) in your future assignments, use regular for-loops by all means! In the upcoming tutorials, though, we'll definitely use them, so make sure you understand what they do!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Numpy\n",
    "This section is about Numpy, Python's core library for numeric computing. While the syntax of basic Python (as we've gone over in the previous section) is important to do neuroimaging analysis in Python, knowing numpy is **essential**. Basicially, Numpy is the go-to package whenever you want to do (anything related to) data analysis in Python. Make sure you understand what is going on in this section, as the rest of the course will feature a lot of Numpy-code!\n",
    "\n",
    "The most important feature of Numpy is it's core data structure: the numpy *ndarray* (which stands for *n*-dimensional array, referring to the fact that the array may be of any dimension: 1D, 2D, 3D, 180D ... *n*D). This is, just like basic lists/dictionaries/integers/tuples, a data structure with its own syntax, operations, and methods, as we will explain below.\n",
    "\n",
    "**Note**: even if you're a Numpy pro already, we recommend going through this section anyway as it contains a couple of graded ToDos!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1. Python lists vs. numpy arrays\n",
    "Basically, numpy arrays are a lot like Python lists. The major difference, however, is that **numpy arrays may contain only a single data-type**, while Python lists may contain different data-types within the same list.\n",
    "\n",
    "Let check this out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Python lists may contain mixed data-types: an integer, a float, a string, a list\n",
    "python_list = [1, 2.5, \"whatever\", [3, 4, 5]] \n",
    "\n",
    "for value in python_list:\n",
    "    \n",
    "    print(\"%s is a: %s\" % (str(value), type(value)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unlike Python lists, numpy only allows entries of the same data-type. This difference between Python lists and numpy arrays is basically the same as R lists (allow multiple data-types) versus R matrices/arrays (only allow one data type), and is also the same as MATLAB cells (allow multiple data-types) versus MATLAB matrices (only allow one data type).\n",
    "\n",
    "In fact, if you try to make a numpy array with different data-types, numpy will force the entries into the same data-type (in a smart way), as is shown in the example below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import numpy!\n",
    "import numpy as np\n",
    "\n",
    "# Importantly, you often specify your arrays as Python lists first, and then convert them to numpy\n",
    "to_convert_to_numpy = [1, 2, 3.5]               # specify python list ...\n",
    "numpy_array = np.array(to_convert_to_numpy)     # ... and convert ('cast') it to numpy\n",
    "\n",
    "for entry in numpy_array:\n",
    "    \n",
    "    print(entry)\n",
    "    print('this is a: %s \\n' % type(entry))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, Numpy converted our original list (to_convert_to_numpy), which contained both integers and floats, to an array with only floats! You might think that such a data structure that only allows one single data type is not ideal. However, the very fact that it only contains a single data-type makes operations on numpy arrays extremely fast. For example, loops over numpy arrays are often way faster than loops over python lists. This is because, internally, Python has to check the data-type of each loop entry before doing something with that entry. Because numpy arrays one allow a single data-type, it only has to check for the entries' data type **once**. If you imagine looping over an array or list of length 100,000, you probably understand that the numpy loop is way faster.\n",
    "\n",
    "Let's check out the speed difference between Python list operations and numpy array operations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %timeit is a cool 'feature' that you can use in Notebooks (no need to understand how it works)\n",
    "# it basically performs a computation that you specify a couple of times and prints how long it took on average\n",
    "results_python = %timeit -o [x * 2 for x in range(0, 100000)] "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And now let's do the same with numpy:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results_numpy = %timeit -o np.arange(0, 10000) * 2 \n",
    "\n",
    "ratio = results_python.average / results_numpy.average\n",
    "print(\"Numpy is %i times faster than base Python!\" % ratio)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You see that Numpy *much* faster! This really matters when you start doing more complex operations, on, let's say, multidimensional brain images!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2. Numpy arrays: creation\n",
    "As shown an earlier example, numpy arrays can be created as follows:\n",
    "\n",
    "1. Define a Python list (e.g. `my_list = [0, 1, 2]`) \n",
    "2. Convert the list to a numpy array (`numpy_array = np.array(my_list)`)\n",
    "\n",
    "Importantly, a simple Python list will be converted to a 1D numpy array, but a nested Python list will be converted to a 2D (or even higher-dimensional array). Nesting is simply combining different lists, separated by commans, as is shown here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_list = [1, 2, 3]\n",
    "my_array = np.array(my_list)\n",
    "\n",
    "print(\"A 1D (or 'flat') array:\")\n",
    "print(my_array, '\\n')\n",
    "\n",
    "my_nested_list = [[1, 2, 3],\n",
    "                  [4, 5, 6],\n",
    "                  [7, 8, 9]]\n",
    "\n",
    "my_2D_array = np.array(my_nested_list)\n",
    "print(\"A 2D array:\")\n",
    "print(my_2D_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can imagine, creating numpy arrays from nested lists becomes cumbersome if you want to create (large) arrays with more than 2 dimensions. There are, fortunately, a lot of other ways to create ('initialize') large, high-dimensional numpy arrays. One often-used method is to create an array with zeros using the numpy function `np.zeros`. This function takes one (mandatory) argument, which is a tuple with the dimensions of your desired array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_desired_dimensions = (2, 5) # suppose I want to create a matrix with zeros of size 2 by 5\n",
    "my_array = np.zeros(my_desired_dimensions)\n",
    "\n",
    "print(my_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Using the `np.zeros` function, create a five dimensional array of shape $2 \\times 3 \\times 5 \\times 3 \\times 7$ and store it in a variable named `array_5d`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "ac6c76c4242f8b9a90b2a4b5927f166b",
     "grade": false,
     "grade_id": "cell-ef19f7db953eecc1",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Implement your ToDo here\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "d2f7e4d4677de197be8acbd1f86654e9",
     "grade": true,
     "grade_id": "cell-1be0380d2ed4df4f",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "from nb_tests import test_create_array_with_zeros\n",
    "\n",
    "available_vars = dir()\n",
    "if 'array_5d' not in available_vars:\n",
    "    raise ValueError(\"You didn't define the variable 'array_5d'!\")\n",
    "\n",
    "test_create_array_with_zeros(array_5d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using arrays with zeros is often used in what is called 'pre-allocation', in which you create an 'empty' array with only zeros and for example, 'fill' that array in a loop.\n",
    "\n",
    "Below, we show you an example in which we pre-allocate an array with 5 zeros, and fill that in a for-loop with the squares of 1 - 5. Try to understand how it works! (You have to do something similar in the next ToDo!)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.zeros(5)\n",
    "\n",
    "print('Original zeros-array')\n",
    "print(my_array)\n",
    "\n",
    "for i in range(5):  # notice the range function here! This loop now iterates over [0, 1, 2, 3, 4]\n",
    "    number_to_calculate_the_square_of = i + 1\n",
    "    my_array[i] = number_to_calculate_the_square_of ** 2\n",
    "\n",
    "print('\\nFilled array')\n",
    "print(my_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Important**: realize that loops (not shown above), if-statements and other boolean logic is the same for numpy and python!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (2 points)\n",
    "</div>\n",
    "\n",
    "Write a loop in which you fill each value in the variable `my_array2` with the value 1 divided by the current index plus one. So, suppose the index (usually `i`, like the last example) is 3, then you should fill `my_array2` at index `i` with `1 / (3 + 1)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "d3a2cc84d096c1959520374efa88a151",
     "grade": false,
     "grade_id": "cell-83008cc6c353713c",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "my_array2 = np.zeros(8)\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "ef73b51327d48b88739e97b8624dffc2",
     "grade": true,
     "grade_id": "cell-f4f2daf173abb269",
     "locked": true,
     "points": 2,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "from nb_tests import test_fill_array_with_complement\n",
    "\n",
    "available_vars = dir()\n",
    "if 'my_array2' not in available_vars:\n",
    "    raise ValueError(\"The variable my_array2 does not exist!\")\n",
    "    \n",
    "test_fill_array_with_complement(my_array2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to `np.zeros`, you can create numpy arrays using other functions, like `np.ones` and `random` from the `np.random` module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ones = np.ones((5, 10)) # create an array with ones\n",
    "print(ones, '\\n')\n",
    "\n",
    "rndom = np.random.random((5, 10)) # Create an array filled with random values (0 - 1 uniform)\n",
    "print(rndom)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.3. Numpy: indexing\n",
    "Indexing (extracting a single value of an array) and slicing (extracting multiple values - a subset - from an array) of numpy arrays is largely the same as with regular Python lists and data structures from other scientific computing languages such as R and MATLAB. Let's check out a couple of examples of a 1D array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.arange(10, 21)  # numpy equivalent of list(range(10, 21))\n",
    "print('Full array:')\n",
    "print(my_array, '\\n') \n",
    "\n",
    "print(\"Index the first element:\")\n",
    "print(my_array[0], '\\n')\n",
    "\n",
    "print(\"Index the second-to-last element:\")\n",
    "print(my_array[-2], '\\n')\n",
    "\n",
    "print(\"Slice from 5 until (not including!) 8\")\n",
    "print(my_array[5:8], '\\n') \n",
    "\n",
    "print(\"Slice from beginning until 4\")\n",
    "print(my_array[:4])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Setting values in numpy arrays works the same way as lists:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.arange(10, 21)\n",
    "my_array[0] = 10000\n",
    "print(my_array)\n",
    "\n",
    "my_array[5:7] = 0\n",
    "print(my_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "In the array `my_array` below, set all odd indices (i.e., the first element, the third element, the fifth element, etc.) to the value `0.0` *in a single statement using a slice* (i.e., not a for-loop)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "4f2fcd39adcf28a2117e67fe69b1d0d2",
     "grade": false,
     "grade_id": "cell-586a858efcdccc4a",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Implement the ToDo here\n",
    "my_array = np.arange(3, 25)\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "bca8867dad250c94b9b98d714aaeddb2",
     "grade": true,
     "grade_id": "cell-c21cc459312c74b3",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "from nb_tests import test_set_odd_indices_to_zero\n",
    "test_set_odd_indices_to_zero(my_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Multidimensional indexing\n",
    "Often, instead of working on and indexing 1D array, we'll work with multi-dimensional (>1D) arrays. Indexing multi-dimensional arrays is, again, quite similar to other scientific computing languages. \n",
    "\n",
    "Like indexing Python lists, indexing multidimensional numpy arrays is done with square brackets `[]`, in which you can put as many comma-delimited numbers as there are dimensions in your array. \n",
    "\n",
    "For example, suppose you have a 2D array of shape $3 \\times 3$ and you want to index the value in the first row and first column. You would do this as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.zeros((3, 3)) # 3 by 3 array with zeros\n",
    "indexed_value = my_array[0, 0]\n",
    "print(\"Value of first row and first column: %.1f\" % indexed_value)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Using multidimensional indexing, set the value in the last row and last column of the 2D array `my_array` to `1.0`. In other words, set the value in the lower-right \"corner\" of the 2D array to 1.0."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "29bb7f8b04bd15ed511f5cddee67f133",
     "grade": false,
     "grade_id": "cell-6ab84bc4c9f46867",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "my_array = np.zeros((3, 3))\n",
    "\n",
    "print(my_array)\n",
    "\n",
    "# ToDo: set the value in the lower right corner to 1\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "a2333d02eb8632d390e47a8edb26bfcb",
     "grade": true,
     "grade_id": "cell-8053ddb5715da50d",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the ToDo above. '''\n",
    "from nb_tests import test_set_lower_right_value_to_one\n",
    "test_set_lower_right_value_to_one(my_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to setting specific slices to specific values, you can also extract sub-arrays using slicing/indexing. An important construct here is that you can use a single colon `:` to select all values from a particular dimension. For example, if you want to select all column-values (second dimension) from only the first row (first dimension), do this:\n",
    "\n",
    "```\n",
    "some_2d_arr[0, :]\n",
    "```\n",
    "\n",
    "We'll show you some examples below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.array([[1, 2, 3],\n",
    "                     [4, 5, 6],\n",
    "                     [7, 8, 9]])\n",
    "\n",
    "print(my_array, '\\n')\n",
    "\n",
    "all_column_values_from_first_row = my_array[0, :]\n",
    "print('First row')\n",
    "print(all_column_values_from_first_row, '\\n')\n",
    "\n",
    "all_row_values_from_first_col = my_array[:, 0]\n",
    "print('First column')\n",
    "print(all_row_values_from_first_col)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far, we only talked about 2D arrays, which are relatively easy to 'understand'. In neuroimaging, however, we usually work with 3D, 4D, or even higher-dimensional arrays. These arrays are great for organizing data (like 3D brain scans!), but they are somewhat unintuitive. This takes some time to get used to!\n",
    "\n",
    "To get you used to thinking in more than 2 (or 3) dimensions, consider the following scenario. Suppose that a researcher wants to test the efficacy of a particular medicine against high blood pressure. To do so, she/he measures the (average systolic) blood pressure of a group of twenty subjects every hour for 30 days when they're not on the medication. The same subjects are then again measured for another 30 days, but then when they're on medication.\n",
    "\n",
    "After this period of data collection, the researcher has $20\\ (subjects)\\ \\times\\ 24\\ (hours)\\ \\times\\ 30\\ (days)\\ \\times\\ 2\\ (conditions: \\mathrm{off/on}) = 28800$ measurements! We can then organize the data in a 4D array, in which each factor (subjects/hours/days/conditions) represents a separate dimension (also called \"axis\") of our array!\\*\n",
    "\n",
    "---\n",
    "\\* Note that this type of data is perhaps best represented in a \"table-like\" structure, such as a Dataframe in R (or a \"Pandas Dataframe\", the Python-equivalent of R's dataframe). But you can ignore that for this example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, let's generate some random data (from a normal distribution to generate 'realistic' blood pressure data) that could represent this blood pressure dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(42)  # this is not important for now\n",
    "bp_data = np.random.normal(loc=100, scale=5, size=(20, 24, 30, 2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(Note that we're not printing the `bp_data` variable here, because it's way too much to visualize/interpret at once anyway!)\n",
    "\n",
    "Now, suppose I would want to extract the blood pressure of subject 5 at 09.00 (AM) in the morning at day 21 when he/she was *not* on medication. In that case, I would do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note that I count midnight as the first measurement\n",
    "this_particular_datapoint = bp_data[4, 8, 20, 0]\n",
    "print(\"Blood pressure of participant 5 at 09.00 (AM) on day 21 in \"\n",
    "      \"the no-medication (off) condition is %.3f\" % this_particular_datapoint)\n",
    "\n",
    "# Also, remember that Python is zero-based, so e.g. participant 5 is indexed by index 4!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try to remember this: **in multidimensional arrays, each dimension (axis) represents a different \"attribute\" of your data (e.g. subjects, time, condition, etc.)**. This concept will become very important to understand later when we're going to analyze 4D MRI-datasets (with 3 spatial dimensions and 1 time dimension)!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Consider the blood-pressure dataset again. In the code-cell below, extract from all participants all data from day 18 in the medication (\"on\") condition. You'll have to use slices with the single `:`! Store the results of your index-operation in the variable `day_18_condition_on`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "afab837cc827cfede724b2269ceaebb4",
     "grade": false,
     "grade_id": "cell-3a374e09098c2611",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Implement your ToDo here (index the bp_data variable)\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "d9f15583384f553af0da16d09d05f6f3",
     "grade": true,
     "grade_id": "cell-e61a83c4f632675d",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "from nb_tests import test_bloodpressure_index\n",
    "\n",
    "if 'day_18_condition_on' not in dir():\n",
    "    raise ValueError(\"The variable 'day_18_condition_on' is not defined!\")\n",
    "    \n",
    "test_bloodpressure_index(day_18_condition_on)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multidimensional indexing using slices (especially the single colon `:` slice, i.e., selecting everything) is very common in scientific programming such as neuroimaging analyses. There is, however, yet another way of (multidimensional) indexing called \"boolean indexing\". \n",
    "\n",
    "In this type of indexing, you index an array with a boolean array (i.e. array with True and False values) of the same shape. Basically, when you're indexing the array `my_array` with boolean array `bool_array`, you're saying: \"give me all values in `my_array` that are `True` at the same location in `bool_array`!\"\n",
    "\n",
    "Let's look at an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.array([[1, 2, 3],\n",
    "                     [4, 5, 6],\n",
    "                     [7, 8, 9]])\n",
    "\n",
    "print(\"The original array:\\n\")\n",
    "print(my_array, '\\n')\n",
    "\n",
    "bool_array = np.array([[True, False, True],\n",
    "                       [False, True, False],\n",
    "                       [True, False, True]])\n",
    "\n",
    "print(\"The boolean array:\\n\")\n",
    "print(bool_array, '\\n')\n",
    "\n",
    "print('Result of indexing my_array with bool_array:\\n')\n",
    "print(my_array[bool_array])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Usually, you do not write out the boolean array in full (as we did above), but you base it on the data itself to \"filter\" it according to some criterion formalized as a logical statement (i.e., using the boolean operators >, <, ==, or !=). For example, suppose I want to extract only the values above 6 from the `my_array` variable in the above example. \n",
    "\n",
    "To do so, I could do the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.array([[1, 2, 3],\n",
    "                     [4, 5, 6],\n",
    "                     [7, 8, 9]])\n",
    "\n",
    "print(\"The original array:\\n\")\n",
    "print(my_array, '\\n')\n",
    "\n",
    "bool_array = my_array > 6\n",
    "\n",
    "print(\"The boolean array:\\n\")\n",
    "print(bool_array, '\\n')\n",
    "\n",
    "print('Result of indexing my_array with bool_array:\\n')\n",
    "print(my_array[bool_array])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Easy, right? Now try it yourself in the next ToDo!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Use a boolean index to extract all values whose square (i.e. $value^2$) is larger than 4 from the array (`my_array`) below. Store the results in a variable with the name `square_is_larger_than_4`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "7ee953499550d180b4bfb0fc33015630",
     "grade": false,
     "grade_id": "cell-e7444e2dc55212f2",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "my_array = np.array([[0, 1, -1, -2],\n",
    "                     [2, -5, 1, 4],\n",
    "                     [10, -2, -4, 20]])\n",
    "\n",
    "# Make a new boolean array below (name it whatever you want) ...\n",
    "\n",
    "# And use it to index my_array and store it in a variable `square_is_larger_than_4`.\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "583d628a5f38ccfa406f59cd9b4790e5",
     "grade": true,
     "grade_id": "cell-9078457efdeb3498",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo '''\n",
    "from nb_tests import test_boolean_indexing\n",
    "\n",
    "if 'square_is_larger_than_4' not in dir():\n",
    "    raise ValueError(\"Could not find the variable 'square_is_larger_than_4'; did you name it correctly?\")\n",
    "\n",
    "test_boolean_indexing(square_is_larger_than_4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, it's very important to understand how to (effectively) index multidimensional numpy arrays using slices and boolean indexing, as we'll use it a lot in this course!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.4. Numpy: data-types\n",
    "Every numpy array is a grid of values of the same type. Numpy provides a large set of numeric datatypes that you can use to construct arrays. Numpy guesses the datatype when you create an array, but functions that construct arrays usually also include an optional argument to explicitly specify the datatype.\n",
    "\n",
    "Here are a couple of examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x1 = np.array([1, 2])  # Let numpy choose the datatype (here: int)\n",
    "x2 = np.array([1.0, 2.0])  # Let numpy choose the datatype (here: float)\n",
    "x3 = np.array([1, 2], dtype=np.float64)  # Force a particular datatype (input: int, but converted to 64bit float)\n",
    "x4 = np.array([-1, 0, 1, 2], dtype=bool)  # Convert ints to booleans! 0 -> False, everthing else -> True \n",
    "\n",
    "print('%r (%s)' % (x1, type(x1[0])))\n",
    "print('%r (%s)' % (x2, type(x2[0])))\n",
    "print('%r (%s)' % (x3, type(x3[0])))\n",
    "print('%r (%s)' % (x4, type(x4[0])))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that, after creating the array, you can still change the datatype by using the numpy method `astype()`!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([1, 2, 3, 4])\n",
    "print(type(x[0]))\n",
    "\n",
    "# Now convert it to floasts!\n",
    "x = x.astype(float)  # or astype(np.float)\n",
    "print(type(x[0]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points)\n",
    "</div>\n",
    "\n",
    "Below, we've defined a boolean array named `bool_array`. Convert it to an array with integers and store it in a new array calle `bool2int_array`. Check out the values of the new array!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "7e3573789a8f85d1214806941fd01209",
     "grade": false,
     "grade_id": "cell-36dff506b5200a03",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "bool_array = np.array([True, True, False, False, True])\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "43a00e68a6e3fea4936200220063743b",
     "grade": true,
     "grade_id": "cell-688565f12ea25dfc",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo (not for points) '''\n",
    "np.testing.assert_array_equal(bool2int_array, np.array([1, 1, 0, 0, 1]))\n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.5. Numpy: methods vs. functions\n",
    "In the previous section (Basic Python), you've learned that, in addition to functions, 'methods' exist that are like functions of an object. In other words, methods are functions that are applied to the object itself. You've seen examples of list methods, e.g. `my_list.append(1)`, and string methods, e.g. `my_string.replace('a', 'b')`.\n",
    "\n",
    "Like lists and strings, numpy arrays have a lot of convenient methods that you can call (like the `astype` method we saw earlier). Again, this is just like a function, but then applied to itself. Often, numpy provides both a function and method for simple operations. \n",
    "\n",
    "Let's look at an example: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.arange(10)  # creates a numpy array from 0 until (excluding!) 10\n",
    "print(my_array, '\\n')\n",
    "\n",
    "mean_array = np.mean(my_array)\n",
    "print('The mean of the array is: %f' % mean_array, '\\n')\n",
    "\n",
    "mean_array2 = my_array.mean() \n",
    "print('The mean of the array (computed by its corresponding method) is: %f' % mean_array2, '\\n')\n",
    "\n",
    "print('Is the results from the numpy function the same as '\n",
    "      'the corresponding method? Answer: %s' % str(mean_array == mean_array2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If there is both a function and a method for the operation you want to apply to the array, it really doesn't matter what you choose! Let's look at some more (often used) methods of numpy ndarrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.array([[1, 2, 3],\n",
    "                     [4, 5, 6],\n",
    "                     [7, 8, 9]])\n",
    "\n",
    "std_my_array = my_array.std()  # same as np.std(array)\n",
    "print(\"Standard deviation of my_array: %.3f\" % std_my_array, '\\n')\n",
    "\n",
    "transpose_my_array = my_array.T  # same as np.transpose(array)\n",
    "print(\"Transpose of my_array:\\n%r\" % transpose_my_array, '\\n')\n",
    "\n",
    "min_my_array = my_array.min()  # same as np.min(array)\n",
    "print(\"Minimum of my_array: %i\" % my_array.min(), '\\n')\n",
    "\n",
    "max_my_array = my_array.max()  # same as np.max(array)\n",
    "print(\"Maximum of my_array: %i\" % max_my_array, '\\n')\n",
    "\n",
    "sum_my_array = my_array.sum()  # same as np.sum(array)\n",
    "print(\"Sum of my_array: %i\" % sum_my_array, '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Importantly, a method may or may not take arguments (input).\n",
    "If no arguments are given, it just looks like \"object.method()\", i.e. two enclosing brackets with nothing in between.\n",
    "However, a method may take one or more arguments (like the my_list.append(1) method)! \n",
    "This argument may be named or unnamed - doesn't matter. An example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array2 = np.random.random((3, 3))\n",
    "print('Original array:')\n",
    "print(my_array2, '\\n')\n",
    "\n",
    "print('Use the round() method with the argument 3:')\n",
    "print(my_array2.round(3), '\\n')\n",
    "\n",
    "print('Use the round() method with the named argument 5:')\n",
    "print(my_array2.round(decimals=5), '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Some methods that you'll see a lot in the upcoming tutorials**. In addition to the methods listed above, you'll probably see the following methods a lot in the rest of this course (make sure you understand them!):\n",
    "\n",
    "Reshaping arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.arange(10)\n",
    "print(my_array.reshape((5, 2))) # reshape to desired shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ravel (\"flatten\") an array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temporary = my_array.reshape((5, 2))\n",
    "print(\"Initial shape: %s\" % (temporary.shape,))\n",
    "print(temporary.ravel()) # unroll multi-dimensional array to single 1D array\n",
    "print(\"Shape after ravel(): %s\" % (temporary.ravel().shape,))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# .dot() does matrix multiplication (dot product: https://en.wikipedia.org/wiki/Dot_product)\n",
    "# This linear algebra operation is used very often in neuroimaging research \n",
    "# (which depends heavily on the General Linear Model!)\n",
    "array1 = np.array([0, 1, 2, 3])\n",
    "array2 = np.array([4, 5, 6, 7])\n",
    "\n",
    "dot_product = array1.dot(array2)\n",
    "print(dot_product)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Let's practice writing functions some more. Complete the function below, named `calculate_range`. This function takes  a single input-argument - a 1D numpy array - and subsequently calculates the [range](https://en.wikipedia.org/wiki/Range_(statistics)) of the array. The range is the difference between the maximum and minimum of any given array (vector) $x$:\n",
    "\n",
    "\\begin{align}\n",
    "range(x) = max(x) - min(x)\n",
    "\\end{align}\n",
    "\n",
    "You may use the corresponding numpy min/max methods or functions in your custom function, doesn't matter. Don't forget to explicitly return the value of the range! \n",
    "\n",
    "Note: this custom function that implements the *mathematical* formula for a vector's range is completely unrelated to the *Python function* `range` that is often used in for-loops! "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "67cbc24cb221cd0ed3fcaa00dac0155d",
     "grade": false,
     "grade_id": "cell-2efc174e66bba2aa",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Complete the function below\n",
    "def calculate_range(arr):\n",
    "    ''' Calculate the range of an array.\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    arr : a 1D numpy array\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    The range of the input arr\n",
    "    '''\n",
    "    \n",
    "    # YOUR CODE HERE\n",
    "    raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "4de520f7ce276c129202d3e1df36c63c",
     "grade": true,
     "grade_id": "cell-e9339bd405181849",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "\n",
    "outp = calculate_range(np.array([0, 1, 2, 3]))\n",
    "if outp is None:\n",
    "    raise ValueError(\"Didn't get any output! Did you explicitly return the range?\")\n",
    "\n",
    "assert(outp == 3)\n",
    "assert(calculate_range(np.array([-1, 0, 1, 2])) == 3)\n",
    "assert(calculate_range(np.array([0, 0, 0, 0])) == 0)\n",
    "\n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.6. Numpy: methods vs. attributes?\n",
    "Alright, by now, if you see a variable followed by a word ending with enclosed brackets, e.g. `my_array.mean()`, you'll know that it's a method! But sometimes you might see something similar, but **without** the brackets, such as `my_array.size`. This `.size` is called an **attribute** of the variable `my_array`. Like a method, it's an integral part of an object (such as a numpy ndarray). The attribute may be of any data-type, like a string, integer, tuple, an array itself. Let's look at an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.array([[1, 2, 3],\n",
    "                     [4, 5, 6],\n",
    "                     [7, 8, 9]])\n",
    "\n",
    "print(my_array, '\\n')\n",
    "print('The size (number of element) in the array is:')\n",
    "print(my_array.size, '\\n')\n",
    "print('The .size attribute is of data-type: %s' % type(my_array.size))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alright, so by now you might be wondering what the difference between a method and an attribute is. Superficially, you can recognize a method by the form `object.method()` (note the brackets!), like `my_array.round()`; an attribute is virtually the same **but without brackets**, in the form of `object.attribute`, like `my_array.size`. \n",
    "\n",
    "Conceptually, you may think of methods as things that **do** something with the array, while attributes **say** something about the array.\n",
    "\n",
    "For example, `my_array.size` **does nothing** with the array - it only **says** something about the array (it gives information about its size), while `my_array.mean()` really **does** something (i.e. calculates the mean of the array). \n",
    "\n",
    "Again, you might not use attributes a lot during this course, but you'll definitely see them around in the code of the tutorials. Below, some of the common ndarray attributes are listed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_array = np.array([[1, 2, 3],\n",
    "                     [4, 5, 6],\n",
    "                     [7, 8, 9]])\n",
    "\n",
    "print('Size (number of elements) of array:')\n",
    "print(my_array.size, '\\n') # returns an integer\n",
    "\n",
    "print('Shape of array:')\n",
    "print(my_array.shape, '\\n') # this is a tuple!\n",
    "\n",
    "print('Number of dimensions:')\n",
    "print(my_array.ndim) # this is an integer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (2 points)\n",
    "</div>\n",
    "\n",
    "Let's try another one. Complete the function below, named `compute_one_sample_ttest`. This function takes two input arguments:\n",
    "\n",
    "- arr : a 1D numpy array\n",
    "- h0 : a scalar value (single number) that represents the value representing the null-hypothesis\n",
    "\n",
    "The function should compute the one-sample t-test, which tests whether the mean of an array is significantly different from a given value representing the null-hypothesis. Formally, for any given array $x$ and null-hypothesis $h_{0}$:\n",
    "\n",
    "\\begin{align}\n",
    "t = \\frac{\\bar{x} - h_{0}}{s\\ / \\sqrt{N}}\n",
    "\\end{align}\n",
    "\n",
    "Here: $\\bar{x}$ represents the mean of $x$, $s$ represents the standard deviation of $x$, and $N$ represents the length ('size') of x. So, in slightly less mathematical notation:\n",
    "\n",
    "\\begin{align}\n",
    "t = \\frac{mean(x) - h_{0}}{std(x)\\ / \\sqrt{length(x)}}\n",
    "\\end{align}\n",
    "\n",
    "Make sure to return the t-value! \n",
    "\n",
    "**Hint 1**: to compute $N$, you can use the `.size` attribute of an array ... <br>\n",
    "**Hint 2**: use the function `np.sqrt(some_number)` to calculate the square root ..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "233af474e63a5ad493ea438328d67735",
     "grade": false,
     "grade_id": "cell-88f546129f9923eb",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Complete the function below!\n",
    "def compute_one_sample_ttest(arr, h0):\n",
    "    ''' Computes the one-sample t-test for any array and h0. \n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    arr : a 1D numpy array\n",
    "    h0 : an int or float\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    A single value representing the t-value\n",
    "    '''\n",
    "    \n",
    "    # YOUR CODE HERE\n",
    "    raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "d88a9f8fce180b137d5aaf8d5c519489",
     "grade": true,
     "grade_id": "cell-1c08ea53c4cbb8e4",
     "locked": true,
     "points": 2,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the ToDo above. '''\n",
    "from nb_tests import test_tvalue_computation\n",
    "\n",
    "arr = np.random.randn(100)\n",
    "outp = compute_one_sample_ttest(arr , 0)\n",
    "\n",
    "if outp is None:\n",
    "    raise ValueError(\"Your function didn't return anything! Did you forget the return statement?\")\n",
    "\n",
    "test_tvalue_computation(arr, 0, outp)\n",
    "\n",
    "outp = compute_one_sample_ttest(arr, 5) \n",
    "test_tvalue_computation(arr, 5, outp)\n",
    "\n",
    "outp = compute_one_sample_ttest(arr, -3) \n",
    "test_tvalue_computation(arr, -3, outp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.7. Numpy: array math\n",
    "Now you know all the numpy basics necessary to do neuroimaging analysis! As you'll see in the last section (Working with nifti-images), we'll work with 3D (structural MRI images) or 4D (functional MRI images) numpy arrays a lot. Given that you know how the basics about numpy in general and numpy ndarrays in particular, we can utilize some of numpy's best features: (very fast) array math."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Basic mathematical functions operate elementwise on arrays, which means that the operation (e.g. addition) is applied onto each element in the array.\n",
    "\n",
    "So, let's initialize a 1D array with ten zeros and let's add 1 to it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.zeros(10)\n",
    "print(x, '\\n')\n",
    "x += 1 # remember: this the same as x = x + 1\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Additionally, you can also sum two arrays together in an elementwise manner by simply writing: `array_1 + array_2`, given that these two (or more) arrays are of the same shape! Let's look at an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([[1,2],[3,4]], dtype=np.float64)\n",
    "y = np.array([[5,6],[7,8]], dtype=np.float64)\n",
    "\n",
    "print(\"x: \\n%r\" % x, '\\n')\n",
    "print(\"y: \\n%r\" % y, '\\n')\n",
    "print(\"x+y: \\n%r\" % (x + y), '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Often, there exist function-equivalents of the mathematical operators. For example, `x + y` is the same as `np.add(x, y)`. However, it is recommended to use the operators wherever possible to improve readability of your code. See below for an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(x + y, '\\n')\n",
    "print(np.add(x, y))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next to addition, we can also do elementwise subtraction, multiplication, divison, square root, and exponentiation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Elementwise difference; both produce the array\n",
    "print(x - y, '\\n')\n",
    "print(np.subtract(x, y))  # function-equivalent of above "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Elementwise product; both produce the array\n",
    "print(x * y, '\\n')\n",
    "print(np.multiply(x, y))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Elementwise division; both produce the array\n",
    "# [[ 0.2         0.33333333]\n",
    "#  [ 0.42857143  0.5       ]]\n",
    "print(x / y, '\\n')\n",
    "print(np.divide(x, y))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Elementwise square root; there is no operator-equivalent!\n",
    "print(np.sqrt(x))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Elementwise exponentiation\n",
    "print(x ** y, '\\n')\n",
    "print(np.power(x, y))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Do an elementwise product between the two variables defined below (`arr_A` and `arr_B`) and subsequently add 5 to each element; store the result in a new variable called `result_product_and_sum`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "f67ffc53991515f3a7e9d9779e84baa1",
     "grade": false,
     "grade_id": "cell-d5729a8b40e30062",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Implement the ToDo!\n",
    "arr_A = np.arange(10).reshape((5, 2))\n",
    "arr_B = np.arange(10, 20).reshape((5, 2))\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "15a70e829a0d65ff6bbb28160ed4ffae",
     "grade": true,
     "grade_id": "cell-df866669b921aff9",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "from nb_tests import test_array_product_and_sum\n",
    "\n",
    "if 'result_product_and_sum' not in dir():\n",
    "    raise ValueError(\"The variable 'result_product_and_sum' does not seem to exist!\")\n",
    "\n",
    "test_array_product_and_sum(result_product_and_sum)    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that unlike MATLAB, `*` is elementwise multiplication, not matrix multiplication. We instead use the dot function (or method!) to  compute matrix operations like inner products of vectors, multiplication of a vector by a matrix, and multiplication of two matrices.\n",
    "\n",
    "These matrix operations are quite important in this course, because they are used a lot in neuroimaging methods (such as the General Linear Model, the topic of next week!). You're not expected to fully understand these matrix operations, but you'll see them several times in this course, so make sure you're familiar with its implementation in Python/Numpy.\n",
    "\n",
    "An example of the inner product (\"dot product\") of two vectors in both the function-format and the method-format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "v = np.array([9,10])\n",
    "w = np.array([11, 12])\n",
    "\n",
    "# Inner product of vectors; both produce 219\n",
    "print(v.dot(w))\n",
    "print(np.dot(v, w))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Additionally, in Python3.6 (and above), you can use the `@` character as an operator for matrix multiplication of numpy arrays!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(v @ w)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Probably the most used functions in numpy are the sum() and mean() fuctions (or equivalent methods!). A nice feature is that they can operate on the entire array (this is the default) or they can be applied per dimension (or, in numpy lingo, per \"axis\").\n",
    "\n",
    "Applying functions along axes is very common in scientific computing! Let's look at an example in which we apply the `sum` function/method across rows and columns:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([[1, 2],[3, 4], [5, 6]])\n",
    "\n",
    "print('Original array:')\n",
    "print(x, '\\n')\n",
    "\n",
    "print('Sum over ALL elements of x:')\n",
    "print(np.sum(x), '\\n')\n",
    "\n",
    "print('Sum across rows of x:')\n",
    "print(np.sum(x, axis=0), '\\n')\n",
    "\n",
    "print('Sum across columns of x:')\n",
    "print(x.sum(axis=1)) # this is the method form! Is exactly the same as np.sum(x, axis=1) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Importantly, application of functions across axes is much quicker (and more concise) than writing for-loops! Let's look at the speed difference between a for-loop (implemented as a list comprehension) and the numpy-style application of the `sum` function across axes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "arr = np.random.random((1000, 100))\n",
    "loop_style = %timeit -o [arr[i, :].sum() for i in range(arr.shape[0])]\n",
    "axis_style = %timeit -o arr.sum(axis=1)\n",
    "print(\"Using the axis-argument is %.3f times faster than a for-loop!\" % (loop_style.average / axis_style.average))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This application of functions on entire arrays (in an elementwise manner, like `arr_1 + arr_2`) and application of functions across a certain axis (like `np.sum(arr_1, axis=1)`) is often called **vectorization**. This is an incredibly useful concept and something we'll use a lot in this course! Make sure you understand this. \n",
    "\n",
    "Let's practice this a bit."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Remember the \"range\" function from before? Below, we started writing a function, called `calculate_range_vectorized`, that calculates, for any 2D array, the range of each column (i.e. calculates range **across rows** for each column) in a *vectorized manner* (so without any for loops!).\n",
    "\n",
    "Complete the function, and make sure to return the result, which should be a 1D vector which values represents the ranges for all columns. So, if the input array would be of shape `(100, 10)`, then the shape of your returned array should be `(10,)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "2d0d5c0f938d4aa095c66d0ae7fd5891",
     "grade": false,
     "grade_id": "cell-e5cf94c93d9f9f5a",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "def compute_range_vectorized(arr):\n",
    "    ''' Compute the range across rows for each column in a 2D array. \n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    arr : a 2D numpy array\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    A 1D vector with the ranges for each column\n",
    "    '''\n",
    "    \n",
    "    # YOUR CODE HERE\n",
    "    raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "a73ee82dc153ac5268d81e0b0ee49eda",
     "grade": true,
     "grade_id": "cell-c8726c1e2391c059",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo '''\n",
    "from nb_tests import test_compute_range_vectorized\n",
    "\n",
    "np.random.seed(42)\n",
    "test_arr = np.random.random((100, 10))\n",
    "outp = compute_range_vectorized(test_arr)\n",
    "\n",
    "if outp is None:\n",
    "    raise ValueError(\"Output is None! Did you forget the Return statement in your function?\")\n",
    "\n",
    "test_compute_range_vectorized(test_arr, outp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.8. Broadcasting\n",
    "Broadcasting is a powerful mechanism that allows numpy to work with arrays of different shapes when performing arithmetic operations. Frequently we have a smaller array and a larger array, and we want to use the smaller array multiple times to perform some operation on the larger array.\n",
    "\n",
    "For example, suppose that we want to add a vector to each row of a matrix. We could do it like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We will add the vector v to each row of the matrix x,\n",
    "# storing the result in the matrix y\n",
    "x = np.array([[1,2,3], [4,5,6], [7,8,9], [10, 11, 12]])\n",
    "\n",
    "print('x array is of shape: %r' % (x.shape,))\n",
    "print(x, '\\n')\n",
    "\n",
    "v = np.array([1, 0, 1])\n",
    "print('v vector is of shape: %r (different shape than x!)' % (v.shape,))\n",
    "print(v, '\\n')\n",
    "\n",
    "y = np.zeros(x.shape)   # Create an empty (zeros) matrix with the same shape as x\n",
    "print('Shape of (pre-allocated) y-matrix: %r' % (y.shape,))\n",
    "\n",
    "# Add the vector v to each row of the matrix x with an explicit loop\n",
    "for i in range(x.shape[0]): # see how the shape attributes comes in handy in creating loops?\n",
    "    y[i, :] = x[i, :] + v\n",
    "\n",
    "print('The result of adding v to each row of x, as stored in y:')\n",
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This works; however when the matrix `x` is very large, computing an explicit for-loop in Python could be slow. Note that adding the vector v to each row of the matrix `x` is equivalent to forming a matrix `vv` by stacking multiple copies of `v` vertically, like this `[[1 0 1], [1 0 1], [1 0 1], [1 0 1]]`, and subsequently elementwise addition of `x + vv`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "vv = np.tile(v, (4, 1)) # i.e. expand vector 'v' 4 times along the row dimension (similar to MATLAB's repmat function)\n",
    "y = x + vv  # Add x and vv elementwise\n",
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Numpy **broadcasting** allows us to perform this computation without actually creating multiple copies of v. Consider this version, using broadcasting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We will add the vector v to each row of the matrix x,\n",
    "# storing the result in the matrix y\n",
    "x = np.array([[1,2,3], [4,5,6], [7,8,9], [10, 11, 12]])\n",
    "v = np.array([1, 0, 1])\n",
    "y = x + v  # Add v to each row of x using broadcasting\n",
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The line `y = x + v` works even though `x` has shape `(4, 3)` and `v` has shape `(3,)` due to broadcasting; this line works as if v actually had shape `(4, 3)`, where each row was a copy of `v`, and the sum was performed elementwise.\n",
    "\n",
    "This broadcasting function is really useful, as it prevents us from writing unnessary and by definition slower explicit for-loops. Additionally, it's way easier to read and write than explicit for-loops (which need pre-allocation). Functions that support broadcasting are known as universal functions. You can find the list of all universal functions in the [documentation](http://docs.scipy.org/doc/numpy/reference/ufuncs.html#available-ufuncs).\n",
    "\n",
    "Here are some applications of broadcasting using different functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([[1, 2],[3, 4], [5, 6]], dtype=np.float)\n",
    "x_sum = x.sum(axis=0)\n",
    "\n",
    "print(x / x_sum, '\\n')\n",
    "\n",
    "x_mean = x.mean(axis=0)\n",
    "print(x / x_mean)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (2 points)\n",
    "</div>\n",
    "\n",
    "Below, we started writing a function called `standardize_columns`, which takes a single input-argument - a 2D numpy array - and should subsequently *standardize* each column such that each column has a mean of zero and a standard deviation of 1. In other words, standardization subtracts the mean (across rows) of each column from the values in that column, and then divides those value with the standard deviation of that column. Formally, for each column $j$ in any 2D array, standardization entails:\n",
    "\n",
    "\\begin{align}\n",
    "x_{j}\\ standardized = \\frac{(x_{j} - \\bar{x_{j}})}{std(x_{j})}\n",
    "\\end{align}\n",
    "\n",
    "Standardization, which is also oftend called \"z-transformation\", is often done in statistics. We'll also see this next week.\n",
    "\n",
    "So, in the function below, make sure that it is able to standardize each column in any 2D array. Make sure to use vectorized array computations (i.e, the `np.mean` and `np.std` functions/methods across rows) and broadcasting, so no for-loops! "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "15089bd8c0525019f7b03d4fd82d01b5",
     "grade": false,
     "grade_id": "cell-4935a66842e00087",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "def standardize_columns(arr):\n",
    "    ''' Standardize each column of a 2D input-array. \n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    arr : a 2D numpy array\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    The input-array with standardized columns (should have the same shape as the input-array!)\n",
    "    '''\n",
    "    \n",
    "    # YOUR CODE HERE\n",
    "    raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "84f0ce2fa5bfa4936a3a4fd61814a979",
     "grade": true,
     "grade_id": "cell-2d54b8794bc73398",
     "locked": true,
     "points": 2,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "\n",
    "test_arr = np.random.normal(5, 2, size=(100, 10))\n",
    "outp = standardize_columns(test_arr)\n",
    "\n",
    "if outp is None:\n",
    "    raise ValueError(\"The output from your function is None; did you forget the Return statement?\")\n",
    "\n",
    "try:\n",
    "    np.testing.assert_array_almost_equal(outp.mean(axis=0), np.zeros(test_arr.shape[1]))\n",
    "except AssertionError as e:\n",
    "    print(\"The mean of the columns of your standardized array are not 0!\")\n",
    "    raise(e)\n",
    "\n",
    "try:\n",
    "    np.testing.assert_array_almost_equal(outp.std(axis=0), np.ones(test_arr.shape[1]))\n",
    "except AssertionError as e:\n",
    "    print(\"The std of the columns of your standardized array are not 1!\")\n",
    "    raise(e)\n",
    "    \n",
    "print(\"Well done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, you know the most important numpy concepts and functionality that is necessary to do neuroimaging analysis. Surely, there is a lot more to the numpy package that what we've covered here! But for now, let's continue with plotting using Matplotlib!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Matplotlib\n",
    "Matplotlib is Python's main plotting library. In this section give a brief introduction to the `matplotlib.pyplot` module, which provides a plotting system similar to that of MATLAB."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt # this is how matplotlib.pyplot is usually imported\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By running this special notebook command, we will be displaying plots inline (instead of in a new window; this is only relevant in Jupyter notebooks!):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.1. Basic plotting\n",
    "The most important function in `matplotlib` is **`plot`**, which allows you to plot 1 dimensional data. Here is a simple example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Draw a line with coordinates from vectors x and y\n",
    "x = np.arange(0, 11)  # 0 - 10\n",
    "y = np.arange(0, 11)  # 0 - 10, same as x\n",
    "\n",
    "# Plot the points using matplotlib\n",
    "plt.plot(x, y)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With just a little bit of extra work we can easily plot multiple lines at once, and add a title, legend, and axis labels:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "y2 = np.ones(x.size)  # vector of ones, i.e., straight line\n",
    "\n",
    "# Plot the points using matplotlib\n",
    "plt.plot(x, y)\n",
    "plt.plot(x, y2)\n",
    "plt.xlabel('x axis label')\n",
    "plt.ylabel('y axis label')\n",
    "plt.title('Two lines')\n",
    "plt.legend(['Linear increasing line', 'Constant line'])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.2. Subplots \n",
    "You can plot different subplots in a single figure using the subplot function. Here is an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Compute the x and y coordinates for points on sine and cosine curves\n",
    "x = np.arange(0, 3 * np.pi, 0.1)\n",
    "y_sin = np.sin(x)\n",
    "y_cos = np.cos(x)\n",
    "\n",
    "# Set up a subplot grid that has 2 'rows' and 1 'column',\n",
    "# and set the first such subplot as active.\n",
    "plt.subplot(2, 1, 1)  # the third argument here sets the 'active' plot\n",
    "\n",
    "# Make the first plot\n",
    "plt.plot(x, y_sin)\n",
    "plt.title('Sine')\n",
    "\n",
    "# Set the second subplot as active, and make the second plot.\n",
    "plt.subplot(2, 1, 2)\n",
    "plt.plot(x, y_cos)\n",
    "plt.title('Cosine')\n",
    "\n",
    "# Show the figure.\n",
    "plt.tight_layout() # this prevents plots from overlapping\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And we can add text to plots as such:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.arange(-1, 1, 0.01) # array from -1 to 1 in steps of 0.01\n",
    "\n",
    "# Set up a subplot grid that has 2 'rows' and 1 'column',\n",
    "# and set the first such subplot as active.\n",
    "plt.subplot(2, 1, 1)\n",
    "plt.plot(x, x ** 2)\n",
    "plt.title('x squared')\n",
    "plt.text(-0.5, 0.4, r\"$y=x^2$\", fontsize=20, color=\"blue\")\n",
    "\n",
    "# Set the second subplot as active, and make the second plot.\n",
    "plt.subplot(2, 1, 2)\n",
    "plt.plot(x, x ** 3)\n",
    "plt.title('x cubed')\n",
    "plt.text(-0.5, 0.4, r\"$y=x^3$\", fontsize=20, color=\"green\")\n",
    "\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can read much more about the `subplot` function in the [documentation](http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.subplot)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Below, we initialized a 2D array of shape `(10, 100)` named `arr_2D`. In a figure with two subplots (across two columns), plot in the left subplot the mean across columns (i.e., 10 values) and in the right subplot plot the standard deviation across columns (also 10 values). **Hint**: these values represent the values on the `y-axis`. You can use `x = np.arange(10)` for the `x-axis`.\n",
    "\n",
    "Also, give the subplots labels for the x- and y-axis, and give it a title.\n",
    "\n",
    "Note: this ToDo is manually graded, so there is no test-cell!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "8da3bcada17068ef37565bc86253d323",
     "grade": true,
     "grade_id": "cell-0624cc7a2015ea5b",
     "locked": false,
     "points": 1,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "arr_2D = np.random.normal(0, 1, size=(10, 100))\n",
    "\n",
    "# Make your plot below!\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.3. Histograms\n",
    "Now let's generate some random data using the np.random functionality, and get some histograms of their distributions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rand_uniform = np.random.uniform(size = (1000)) # uniform distribution\n",
    "rand_normal = np.random.normal(size = (1000))   # normal distribution\n",
    "rand_exponential = np.random.exponential(size = (1000)) # exponential distribution"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set up a subplot grid that has rows=2 and columns=3,\n",
    "# and set the first such subplot as active.\n",
    "plt.subplot(1, 3, 1)\n",
    "\n",
    "# Make the first plot\n",
    "plt.hist(rand_uniform, color='g')\n",
    "plt.title('uniform')\n",
    "\n",
    "# Set the second subplot as active, and make the second plot.\n",
    "plt.subplot(1, 3, 2)\n",
    "plt.hist(rand_normal, color='b')\n",
    "\n",
    "plt.title('normal')\n",
    "\n",
    "# Set the second subplot as active, and make the second plot.\n",
    "plt.subplot(1, 3, 3)\n",
    "plt.hist(rand_exponential, color='r')\n",
    "plt.title('exponential')\n",
    "\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.4. Images\n",
    "So far, we've been plotting lines. Matplotlib also has easy functionality for plotting two-dimensional data-arrays, such as pictures. This is done using the command `plt.imshow()`. We'll use this feature a lot, because it allows us to visualize 2D slices of MRI-data as well! (Remember, MRI data is essentially just a 3D \"picture\" of the brain.) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# the scipy module includes some pictures, so we can use those:\n",
    "from scipy import misc\n",
    "bw_photo = misc.face(gray=True)\n",
    "\n",
    "# now we can use the imshow command to plot 2d data:\n",
    "plt.imshow(bw_photo,cmap='gray')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Importanty, photos are just 2D arrays with numbers representing the luminance (in black-and-white pictures) of each pixel. You can see this by printing the loaded image:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Shape of photo object: %r\" % (bw_photo.shape,), '\\n')\n",
    "print(bw_photo)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see that it's actually just a bunch of numbers (one number per pixel), and when we plot colorbar with the original picture, we see that high numbers convert to bright shades, and low numbers convert to dark shades. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.imshow(bw_photo,cmap='gray')\n",
    "plt.colorbar()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the knowledge that black and white images are nothing more than just 2d-arrays of values, we can also generate our own images:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rand_img = np.random.random((200,200)) # Create an array filled with random values\n",
    "print(rand_img, '\\n')\n",
    "plt.imshow(rand_img, cmap='gray')\n",
    "plt.colorbar()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (0 points, no test-cell)\n",
    "</div>\n",
    "\n",
    "Below, we loaded in a 2D array of shape (91, 108) named `mystery_data`. Visualize it using `plt.imshow()` (using the argument `cmap='gray'`) to check out what the data entails!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "5053fa639696f60b44640ed9bc61394a",
     "grade": false,
     "grade_id": "cell-12f52876715a05cd",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "mystery_data = np.load('mystery_data.npy')\n",
    "# Visualize it using plt.imshow!\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that you know some basics of data types, arrays and plotting, it's time to get to work with some fMRI data!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Neuroimaging analysis with Python\n",
    "Before we'll actually analyze data, we need to talk about the format that most (f)MRI data is stored in: \"nifti\" files.\n",
    "\n",
    "### 5.1. What is \"nifti\"?\n",
    "Usually, every scanner manufacturer (Philips, Siemens, GE, etc.) have their own proprietary data format. For example, here at the UvA, we have a Philips scanner and we often export our data as PAR/REC files. However, to streamline the development and use of neuroimaging software packages, the Neuroimaging InFormatics Technology Initiative came up with a new, standardized format, *nifti*, that most neuroimaging packages should support. As such, usually the first step in any (f)MRI preprocessing pipeline is to convert the scanner-specific files (e.g., PAR/RECs) to nifti. This is beyond the scope of this course, but if at one point you need to do this yourself, we highly recommed the [dcm2niix](https://github.com/rordenlab/dcm2niix) package!\n",
    "\n",
    "Throughout these tutorials you'll work with these nifti-files (also called nifti images), which you can recognize by their extension of *.nii* or its compressed version *.nii.gz*. This file-format is supported by most neuroimaging software packages (such as FSL, which you'll use later in this course!). \n",
    "\n",
    "However, we'd like to inspect and analyze nifti images in Python as well! **Nibabel** is an awesome Python package that allows us to read and load nifti images, and convert them to numpy arrays in a straightforward manner."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If you haven't done so already, load some other packages we need\n",
    "import os\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "import nibabel as nib # common way of importing nibabel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll load in an example anatomical MRI scan (`anat.nii.gz`) from the current directory using nibabel below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mri_file = 'anat.nii.gz'\n",
    "img = nib.load(mri_file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note the type of `img`: the `Nifti1Image` class. This is a custom class just like a Numpy array, with its own attributes and methods!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(type(img))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, one attribute of `Nifti1Image` objects is the `shape` (which is similar to the numpy array attribute with the same name):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(img.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the `shape` attribute is telling us that this is a 3D (anatomical) scan and has 240 voxels in the first dimension, 240 voxels in the second dimension, and 220 voxels in the third dimension."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.2. The three parts of nifti images\n",
    "Nifti images can be roughly divided into three \"parts\":\n",
    "1. The header with metadata;\n",
    "2. The image data;\n",
    "3. The affine matrix\n",
    "\n",
    "All three parts are of course represented in nibabel's `Nifti1Image` class. Let's go through them one by one."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 5.2.1. The header\n",
    "The header of nifti files contain metadata about the scan, such as the units of measurement, the voxel size, etc. In `Nifti1Images`, the header is an attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# here, we're storing the header attribute in a new variable, hdr, for easy of use\n",
    "hdr = img.header"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Perhaps confusingly, the header is a custom object (a `Nifti1Header` object) as well, with its own methods and attributes. For example, it has a method called `get_zooms()`, which returns the voxel size (and optionally the sampling rate, if it's a fMRI file):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hdr.get_zooms()  # it's a 1x1x1 mm MRI file!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another useful method is the `get_xyzt_units` which returns the units of the measurements (here: voxel size in millimeter and time in seconds):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hdr.get_xyzt_units()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's also load in a functional MRI file (`func.nii.gz`) to see the difference with an anatomical MRI file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fmri_file = 'func.nii.gz'\n",
    "f_img = nib.load(fmri_file)\n",
    "print(f_img.shape)\n",
    "print(f_img.header.get_zooms())\n",
    "print(f_img.header.get_xyzt_units())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In case of fMRI files, the fourth dimension (almost) always represents the \"time\" dimension. So you can assume that a nifti image of an fMRI file has 4 dimensions, with the first three being the spatial dimensions (similar to the anatomical MRI file: $X \\times Y \\times Z$) and the last (fourth) being the time dimension ($T$).\n",
    "\n",
    "So for the above file, you can assume that it has 50 timepoints and has a sampling rate of 0.7 seconds (i.e., a new volume was scanned every 0.7 seconds).\n",
    "\n",
    "Moreover, you can infer that this file contains data from $80 \\times 80 \\times 44$ voxels with dimensions $2.7 \\times 2.7 \\times 2.97$ (in millimeters). To be honest, in practice, you won't deal a lot with the header (as you are generally aware of the dimensions/units of your data), so let's look at the *actual* data!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 5.2.2. The data\n",
    "When we loaded in the data and created a `Nifti1Image` object, we actually didn't load in the *actual* data (i.e., voxel intensities) in memory yet! This is postponed because it's quite a memory-intensive operation: remember, loading in an fMRI scan with dimensions $80 \\times 80 \\times 44 \\times 50$ is effectively loading in over 14 million numbers (which is, in this case, more than 50MB in size)! By postponing loading the data, you can, for example, peek at the image dimensions without loading all the data in memory.\n",
    "\n",
    "Anyway, to actually load in the data, you can call the `get_data()` method, which will return a numpy array with the same dimensions as the image data. We'll take a look at the anatomical MRI data (`anat.nii.gz`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img_data = img.get_data()\n",
    "print(type(img_data))  # it's a numpy array!\n",
    "print(img_data.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Okay, so `img_data` is a 3D numpy array with ... what exactly? Let's check it out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(img_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's just a bunch of numbers! This is important to remember: **like any image (like your standard png, jpeg, or gif), MRI scans are also just (3D or 4D) arrays of numbers**! The higher the number, the more signal the scanner recorded at that voxel. (It's actually a little more complex than this, but that's beyond the scope of this course!) \n",
    "\n",
    "Often, the absolute value of the signal intensities is not necessarily most or only important thing. The *relative differences* between different voxels in space or within voxels across time is also important. For example, for anatomical scans, apart from a high overall signal intensity, you often want a good *contrast* between white and gray matter (i.e., different signal intensities between voxels in these two tissue types). For functional MRI, apart from a clear tissue contrast and a high overall signal intensity, you often also want little (non-experimentally related) differences in signal intensity within a voxel across time.\n",
    "\n",
    "Anyway, when we printed this 3D array (of $240 \\times 240 \\times 220$), the notebook chose not to display all 12,672,000 numbers but instead truncated it. The reason it only printed zeros is because the first and last couple of numbers in each dimension likely doesn't contain any (signal related to) brain, just empty space!\n",
    "\n",
    "So, let's index a small $3 \\times 3 \\times 3$ patch of voxels in the middle of the brain to check what values these voxels contain:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mid_vox = img_data[118:121, 118:121, 108:111]\n",
    "print(mid_vox)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's better! The exact values are not necessarily directly interpretable, i.e., you cannot say that the value 61978.46 is good (or bad), because the exact *scale* of the signal intensities (whether it goes from 0-100 or from 0-100,000) depends on the specific scanner hardware and specific nifti conversion software.\n",
    "\n",
    "Like any image, (f)MRI scans can be visualized by plotting the numbers and assigning colors to the numbers. Often we visualize brain images in brain and white, with higher signal intensities being brighter and lower signal intensities being darker. Importantly, remember that our data here cannot directly be plotted as a (2D) image, because our data (an anatomical scan) is 3D! However, we *can* just plot a single *slice* of the 3D volume, for example, the middle slice of our first voxel axis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mid_slice_x = img_data[119, :, :]\n",
    "print(mid_slice_x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use matplotlib to plot this slice as an image using the `imshow` function you're seen before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note that the transpose the slice (using the .T attribute).\n",
    "# This is because imshow plots the first dimension on the y-axis and the\n",
    "# second on the x-axis, but we'd like to plot the first on the x-axis and the\n",
    "# second on the y-axis. Also, the origin to \"lower\", as the data was saved in\n",
    "# \"cartesian\" coordinates.\n",
    "plt.imshow(mid_slice_x.T, cmap='gray', origin='lower')\n",
    "plt.xlabel('First axis')\n",
    "plt.ylabel('Second axis')\n",
    "plt.colorbar(label='Signal intensity')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alright, time to practice."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Remember numpy indexing? For this ToDo, extract the second entry from the *last* dimension of `img_data` and store it in a new variable called `second_slice`. Tip: this variable should have a shape of $240 \\times 240$!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "d6d96002275ff3c93990e7f3388cdca9",
     "grade": false,
     "grade_id": "cell-8096e7a1b14b0ade",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "3a074035007a2e90a77d3aedc22fd3bf",
     "grade": true,
     "grade_id": "cell-90deb1fc4d7bf3af",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo '''\n",
    "from nb_tests import test_extract_second_slice\n",
    "test_extract_second_slice(img_data, second_slice)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far, we have only looked at *structural* (3D) MRI data. This course is mainly about analyzing *functional* data, so let's look at the data from an fMRI scan. We'll use the `Nifti1Image` object `func_img` from before. We'll load the memory with the `get_data` method. Note that this takes a little longer than loading in the structural data, because instead of ($240 \\times 240 \\times 220 = $) 12,672,000 datapoints, we're loading in ($80 \\times 80 \\times 44 \\times 347 =$) 97,715,200 datapoints!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f_img_data = f_img.get_data()\n",
    "print(f_img_data.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, you can think about this 4D array as a series of 3D arrays (volumes), in which the fourth dimension represents time (as shown in the image below).\n",
    "<br><br>\n",
    "![img](https://nilearn.github.io/_images/niimgs1.jpg)\n",
    "(Source: [nilearn website](https://nilearn.github.io/_images/niimgs1.jpg))\n",
    "\n",
    "These separate 3D arrays (from the first three dimensions) in fMRI files are often called \"volumes\" or \"dynamics\". So, for example, the first volume refers to the first 3D array that was recorded.\n",
    "\n",
    "Just like the anatomical MRI data, the values in the fMRI data just represent numbers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# printing a small 3x3x3 volume of voxels from the first timepoint\n",
    "print(f_img_data[38:41, 38:41, 20:23, 0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, we can visualize these numbers as images, at least for the first three dimensions, as these represent the spatial dimensions (the fourth dimension represents time). For example, we can visualize a single slice (e.g., $x = 39$) of the first volume ($t = 0$) as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mid_slice_x_fmri = f_img_data[39, :, :, 0]  # x = 39, t = 0\n",
    "print(\"Shape of slice: %s\" % (mid_slice_x_fmri.shape,))\n",
    "\n",
    "plt.imshow(mid_slice_x_fmri.T, cmap='gray', origin='lower')\n",
    "plt.xlabel('First axis')\n",
    "plt.ylabel('Second axis')\n",
    "plt.colorbar(label='Signal intensity')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, we can also look at fMRI data from a different perspective, that is, from the time dimension! For example, we could extract a single voxel's *time series* (i.e., how the signal intensity varies across time) and plot the signal intensity values of that voxel across time. First, let's extract the time series of one particular voxel (e.g., the middle one across all spatial dimensions):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mid_vox_ts = f_img_data[39, 39, 21, :]  # note the \":\", saying: give me ALL the timepoints\n",
    "print(\"Voxel timeseries shape: %s\" % (mid_vox_ts.shape,))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What we effectively did in the previous cell is to extract the signal intensity at the *same* spatial coordinates ($x=39, y=39, z=21$) across all 347 timepoints. We show this visually in the next cell, where the show the coordinates as a red box across 20 timepoints (not all 347, because that would clutter the notebook too much):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from matplotlib import patches\n",
    "\n",
    "fig, axes = plt.subplots(ncols=5, nrows=4, figsize=(20, 10))  # 20 timepoints\n",
    "# Loop over the first 20 volumes/timepoints\n",
    "for t, ax in enumerate(axes.flatten()):    \n",
    "    ax.imshow(f_img_data[39, :, :, t].T, cmap='gray', origin='lower')  # index with t!\n",
    "    rect = patches.Rectangle((38, 20), 2, 2, linewidth=2, edgecolor='r', facecolor='none')\n",
    "    ax.add_patch(rect)\n",
    "    ax.axis('off')\n",
    "    ax.set_title('t = %i' % t, fontsize=20)\n",
    "fig.tight_layout()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that it is *really* hard to spot whether the image of the slice is actually different between different time points! To the naked eye, it just seems like the same image. This is because activity fluctations (over time) in fMRI are **very** small - most of the time just 1-3% compared to baseline (average) activity. That's why it's hard to spot activity differences by looking at the pictures alone (without any scaling).\n",
    "\n",
    "It's actually easier to see these time-by-time fluctuations in signal intensity by plotting the time series directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.figure(figsize=(18, 3))\n",
    "plt.plot(mid_vox_ts, 'o-', ms=4)\n",
    "plt.xlim(-1, mid_vox_ts.size)\n",
    "plt.ylim(38000, 55000)\n",
    "plt.ylabel('Signal intensity', fontsize=15)\n",
    "plt.xlabel('Time (nr. of volumes)', fontsize=15)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the plot above, the blue dots are the signal intensity values (y-axis), plotted across time (x-axis). The blue lines interconnecting the blue dots are just interpolated values in between the different datapoints (the dots) and serve mostly for visualization purposes (it just looks prettier).\n",
    "\n",
    "Time for a ToDo!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "From the the variable `f_img_data`, extract the *odd* timepoints (i.e., 1, 3, 5, etc.) of this 4D nummpy and store it in a new variable called `f_img_data_odd`. This should be of shape $80 \\times 80 \\times 44 \\times 25$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "f512d0b31ff3f7cec4d7f765c71e9527",
     "grade": false,
     "grade_id": "cell-087f4842a17387f7",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "10d46d20ede4eb7c6d3e37387dc15cc5",
     "grade": true,
     "grade_id": "cell-93c449262f025ca4",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo. '''\n",
    "from nb_tests import test_extract_voxel_timeseries\n",
    "if 'f_img_data_odd' not in dir():\n",
    "    raise ValueError(\"Could not find any variable named 'f_img_odd'; did you spell it correctly?\")\n",
    "\n",
    "test_extract_voxel_timeseries(f_img_data, f_img_data_odd)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 5.2.3. The affine\n",
    "Each nifti file contains, in addition to the (meta)data, als an *affine* matrix, which relates the position of the image coordinates to real word coordinates. This may sound vague (it definitely did to us at first!), so let's sketch a scenario in which the image's affine becomes important.\n",
    "\n",
    "Suppose you were given a nifti file by a colleague (we'll pretend that the `img` variable represents this mysterious nifti file). You have no idea whether it's even a brain scan, so you decide to plot three slices - one from each of the three axes. You pick slice 70 (index 69, because Python is zero-based; first axis), 100 (second axis), and again 100 (third axis)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(ncols=3, figsize=(15, 5))\n",
    "\n",
    "ax[0].imshow(img_data[69, :, :].T, origin='lower', cmap='gray')\n",
    "ax[0].set_xlabel('Second dim voxel coords.', fontsize=12)\n",
    "ax[0].set_ylabel('Third dim voxel coords', fontsize=12)\n",
    "ax[0].set_title('First dimension, slice nr. 70', fontsize=15)\n",
    "\n",
    "ax[1].imshow(img_data[:, 99, :].T, origin='lower', cmap='gray')\n",
    "ax[1].set_xlabel('First dim voxel coords.', fontsize=12)\n",
    "ax[1].set_ylabel('Third dim voxel coords', fontsize=12)\n",
    "ax[1].set_title('Second dimension, slice nr. 100', fontsize=15)\n",
    "\n",
    "ax[2].imshow(img_data[:, :, 99].T, origin='lower', cmap='gray')\n",
    "ax[2].set_xlabel('First dim voxel coords.', fontsize=12)\n",
    "ax[2].set_ylabel('Second dim voxel coords', fontsize=12)\n",
    "ax[2].set_title('Third dimension, slice nr. 100', fontsize=15)\n",
    "\n",
    "fig.tight_layout()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alright, so, you figured out it's definitely a (structural) MRI scan.You can clearly see that the first voxel axis represents the sagittal dimension (left &larr;&rarr; right), the second voxel axis represents the coronal dimension (anterior &larr;&rarr; posterior), and the third voxel axis represents the axial dimension (inferior &larr;&rarr; superior).\n",
    "\n",
    "So far, so good!\n",
    "\n",
    "Now, if we were to ask you: \"In the first plot, are we looking at the left or right side of the brain?\" Due to the left-right symmetry of the brain, this is actually impossible to tell! As such, we need a way to tell what is left and right (and anterior/posterior and inferior/superior) in our voxel space - this is what the affine is for! It will tell us, basically, whether \"left\" in our \"voxel space\" is also \"left\" in the \"real world\".\n",
    "\n",
    "Here, the real world space refers to the position of the voxels (in millimeters) *relative to the isocenter of the scanner*. In this world space, the coordinate $(0, 0, 0)$ refers to the isocenter (see image below). Furthermore, nibabel `Nifti1Images` assume that the first axis goes from left to right, the second axis goes posterior to anterior, and the third axis from inferior to superior. A short-hand for this convention is *RAS+*, which basically says that coordinates to the Right, Anterior, and Superior of the isocenter should be positive (+). It follows that coordinates to the left, posterior, and inferior of the isocenter should be negative (-).\n",
    "\n",
    "![img](http://www.grahamwideman.com/gw/brain/fs/coords/FSCoords_RAS01.gif)\n",
    "(Source: Graham Wideman, [link](http://www.grahamwideman.com/gw/brain/fs/coords/fscoords.htm))\n",
    "\n",
    "Alright, but how does the affine help us recover the real word coordinates of our voxels? It turns out you only need a simple matrix operation: for a set of voxel coordinates $(i, j, k)$, appended with a single 1, and an $4 \\times 4$ affine matrix $A$, you can get the real word coordinates (in RAS+) by the dot product (matrix multiplication) of $A$ and $(i, j, k, 1)$:\n",
    "\n",
    "\\begin{align}\n",
    "x, y, z, 1 = A\\begin{bmatrix}\n",
    "           i \\\\\n",
    "           j \\\\\n",
    "           k \\\\\n",
    "           1\n",
    "         \\end{bmatrix}\n",
    "\\end{align}\n",
    "\n",
    "So, our image's affine should be a $4 \\times 4$ matrix. Let's see whether that's the case. The affine of a `Nifti1Image` is an attribute named, well, `affine`, and is a 2D numpy array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.set_printoptions(suppress=True, precision=3)  # suppresses scientific notation\n",
    "A = img.affine\n",
    "print(A)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, suppose that you want to know whether the sagittal slice from the leftmost plot in the previous figure is on the left side or the right side. So we want to know the real world $x$ coordinate for our voxel coordinate $i=69$. Let's pick the middle voxel index for our other two dimensions ($j=119, k=109$) (we're plotting this 3D coordinate below in red)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.patches as patches\n",
    "fig, ax = plt.subplots(ncols=3, figsize=(15, 5))\n",
    "\n",
    "ax[0].imshow(img_data[69, :, :].T, origin='lower', cmap='gray')\n",
    "ax[0].set_xlabel('Second dim voxel coords.', fontsize=12)\n",
    "ax[0].set_ylabel('Third dim voxel coords', fontsize=12)\n",
    "ax[0].set_title('First dimension, slice nr. 70', fontsize=15)\n",
    "rect = patches.Rectangle((119, 109), 3, 3, linewidth=2, edgecolor='r', facecolor='none')\n",
    "ax[0].add_patch(rect)\n",
    "\n",
    "ax[1].imshow(img_data[:, 99, :].T, origin='lower', cmap='gray')\n",
    "ax[1].set_xlabel('First dim voxel coords.', fontsize=12)\n",
    "ax[1].set_ylabel('Third dim voxel coords', fontsize=12)\n",
    "ax[1].set_title('Second dimension, slice nr. 100', fontsize=15)\n",
    "rect = patches.Rectangle((69, 109), 3, 3, linewidth=2, edgecolor='r', facecolor='none')\n",
    "ax[1].add_patch(rect)\n",
    "\n",
    "ax[2].imshow(img_data[:, :, 99].T, origin='lower', cmap='gray')\n",
    "ax[2].set_xlabel('First dim voxel coords.', fontsize=12)\n",
    "ax[2].set_ylabel('Second dim voxel coords', fontsize=12)\n",
    "ax[2].set_title('Third dimension, slice nr. 100', fontsize=15)\n",
    "rect = patches.Rectangle((69, 119), 3, 3, linewidth=2, edgecolor='r', facecolor='none')\n",
    "ax[2].add_patch(rect)\n",
    "\n",
    "fig.tight_layout()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get the real world coordinate, we need to evaluate the following:\n",
    "\\begin{align}\n",
    "x, y, z, 1 = A\\begin{bmatrix}\n",
    "           69 \\\\\n",
    "           119 \\\\\n",
    "           109 \\\\\n",
    "           1\n",
    "         \\end{bmatrix}\n",
    "\\end{align}\n",
    "\n",
    "Let's do that below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "xyz1 = A @ np.array([69, 119, 109, 1])\n",
    "print(xyz1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we see that the real world $x$ coordinate is 48.472, which means that this coordinate is 48.472 millimeters to the *right* of the isocenter (remember *RAS+*!).\n",
    "\n",
    "So, why is this important, you might ask? Well, actually, for your statistical analysis, it doesn't! The general linear model (GLM), which we'll use as our main statistical workhorse in this course, doesn't care whether a voxel is on the left or right side of the brain. But when it comes to visualization and reporting, it does! Suppose that you find unilateral amygdala activity for a particular experimental condition - you want to know whether this is on the left or right side, both for your figures and for your paper that you might write about it!\n",
    "\n",
    "Moreover, the affine will become important when we'll talk about realignment of different fMRI volumes (in motion correction) and registration of the fMRI volumes to the structural MRI volume or standard space (which might be in different orientations!), which is the topic of week 4."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (1 point)\n",
    "</div>\n",
    "\n",
    "Suppose that you want to know whether the how much the middle of the image (i.e., the center in voxel coordinates) deviates from the isocenter of the scanner. In other words, you want to check whether the center of the image was in the isocenter of the scanner.\n",
    "\n",
    "Store these world coordinates in a new array named `xyz_middle`, which should be of size **3** (representing the three coordinates, so make sure to remove the extra `1`). Remember, indexing is Python is *zero-based* (so the first index is 0)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "82c405e5d80a01ed5014c2e4957e9bf2",
     "grade": false,
     "grade_id": "cell-6bdbef7c8b05e4f9",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "0b0c775919ed5e917de29c1d9c44ffc5",
     "grade": true,
     "grade_id": "cell-cecf1217053438e0",
     "locked": true,
     "points": 1,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "''' Tests the above ToDo ''' \n",
    "from nb_tests import test_affine_middle_coords\n",
    "if len(xyz_middle) != 3:\n",
    "    raise ValueError(\"Did you remove the last 1?\")\n",
    "\n",
    "test_affine_middle_coords(A, xyz_middle)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-warning'>\n",
    "<b>ToDo</b> (3 points)\n",
    "</div>\n",
    "\n",
    "Alright, almost done! Let's practice some of the skills that you learned in this tutorial! For this ToDo, you goal is to **plot an histogram of the average activity value across time for all non-zero voxels in the brain** from the `f_img_data` array. So, what you have to do is the following:\n",
    "\n",
    "1. Average the `func_img_data` variable across time (resulting array should by of shape (80, 80, 37)\n",
    "2. Remove all voxels which are zero (use boolean indexing!)\n",
    "3. Make a histogram of all the resulting non-zero voxels (use the argument `bins=50` in `plt.hist`)\n",
    "\n",
    "Do this in the code-cell below. Also, *give the plot sensible labels for the axes*. This is a manually graded ToDo, so there is no test-cell.\n",
    "\n",
    "The resulting histogram should show a \"bimodal distribution\" of average activity values - roughly with a peak around $x = 1$ and a peak round $x = 40,000$. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "289f5e8cca85c6225c0068ce6913fde4",
     "grade": true,
     "grade_id": "cell-00ab5da92a127d0c",
     "locked": false,
     "points": 3,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# Implement to ToDo here\n",
    "\n",
    "# YOUR CODE HERE\n",
    "raise NotImplementedError()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alright, that's it! You finished the notebook of this week! Because this week's notebook was quite extensive (the workload gets less, trust us) and you had to do a lot of ToDos, there is no separate assignment at the end of this notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class='alert alert-success'>\n",
    "    <b>Tip!</b>\n",
    "    Before handing in your notebooks, we recommend restarting your kernel (Kernel: Restart & Clear Ouput) and running all your cells again (manually, or by Cell: Run all). By running all your cells one by one (from \"top\" to \"bottom\" of the notebook), you may spot potential errors that are caused by accidentally overwriting your variables or running your cells out of order (e.g., defining the variable 'x' in cell 28 which you then use in cell 15). If you fix this before handing in your notebook, you prevent your ToDos from being graded as incorrect due to these unfortunate errors (because we grade your notebook from \"top\" to \"bottom\" as well).\n",
    "</div>\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}