demo_matrix_addition.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table align=\"left\" width=\"700\" height=\"144\" style=\"border: none;\">\n",
    "<tbody>\n",
    "<tr>\n",
    "<td width=\"120\"><img width=\"100\" src=\"https://static1.squarespace.com/static/5992c2c7a803bb8283297efe/t/59c803110abd04d34ca9a1f0/1530629279239/\" /></td>\n",
    "<td style=\"width: 600px; height: 67px;\">\n",
    "<h1 style=\"text-align: left;\">Matrix Addition Exercise</h1>\n",
    "<p><a href=\"https://colab.research.google.com/github/KenzieAcademy/python-notebooks/blob/master/demo_matrix_addition.ipynb\"> <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\" align=\"left\" width=\"188\" height=\"32\" /> </a></p>\n",
    "</td>\n",
    "</tr>\n",
    "</tbody>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adapted from _Python Morsels_ by Trey Hunner https://www.pythonmorsels.com/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook introduces some concepts that you might not yet be familiar with:\n",
    " - Python built-in Unit Test framework\n",
    " - Python built-in `zip` function\n",
    " - Python built-in `sum` function\n",
    " - The variable argument splat `*` operator\n",
    " - Python built-in `any` function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instructions\n",
    "Without using any third-party libraries such as `pandas`, write a function that will accept at least two input matrices and add them together mathematically.  Here is a refresher on matrix addition:\n",
    "\n",
    "<img align=\"left\" width=\"300\" src=\"https://cdn.kastatic.org/googleusercontent/1zwnERArTuwdXjBNj_s0PNa1oE58dMWqy_NTPUW2o0a2FtFbk1SAYRdHRTiLAR5FjEaN9-pdCqZscJ0qkPYiW8rk\" /><br clear=\"left\">\n",
    "\n",
    "Each matrix above is represented as a list of lists, and the returned matrix sum is also represented as a list of lists with the same dimensions (shape):\n",
    "```python\n",
    ">>> m1 = [[4, 8], [3, 7]]\n",
    ">>> m2 = [[1, 0], [5, 2]]\n",
    ">>> matrix_add(m1, m2)\n",
    "[[5, 8], [8, 9]]\n",
    "```\n",
    "\n",
    "```python\n",
    ">>> m1 = [[1, -2, 3], [-4, 5, -6], [7, -8, 9]]\n",
    ">>> m2 = [[1, 1, 0], [1, -2, 3], [-2, 2, -2]]\n",
    ">>> matrix_add(m1, m2)\n",
    "[[2, -1, 3], [-3, 3, -3], [5, -6, 7]]\n",
    "```\n",
    "\n",
    "If the input lists are not the same shape, the function should raise a `ValueError` exception:\n",
    "```python\n",
    ">>> matrix_add([[1, 9], [7, 3]], [[1, 2], [3]])\n",
    "Traceback (most recent call last):\n",
    "  File \"<stdin>\", line 1, in <module>\n",
    "  File \"matrix_add.py\", line 10, in matrix_add\n",
    "    raise ValueError(\"Given matrices are not the same size.\")\n",
    "ValueError: Given matrices are not the same size.\n",
    "```\n",
    "\n",
    "The function should be able to accept an arbitrary number of matrices and add them together:\n",
    "\n",
    "```python\n",
    ">>> matrix_add([[1, 9], [7, 3]], [[5, -4], [3, 3]], [[2, 3], [-3, 1]])\n",
    "[[8, 8], [7, 7]]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The `matrix_add` function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def matrix_add(m1, m2):\n",
    "    \"\"\"Add corresponding numbers in given 2-D matrices.\"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Test it!\n",
    "Unit testing is not normally something we would do from a Jupyter Notebook.  However, with a couple of tweaks it actually does work.\n",
    "\n",
    "The reason is that `unittest.main` looks at the first parameter of `sys.argv` by default, which is what started IPython or Jupyter. It will raise an error about the kernel connection file not being a valid attribute. Passing an explicit list to unittest.main will prevent IPython and Jupyter from inspecting the `sys.argv` list. Passing `exit=False` will prevent unittest.main from closing the kernel process."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from copy import deepcopy\n",
    "import unittest\n",
    "\n",
    "class MatrixAddTests(unittest.TestCase):\n",
    "\n",
    "    \"\"\"Tests for matrix_add.\"\"\"\n",
    "\n",
    "    def test_single_items(self):\n",
    "        self.assertEqual(matrix_add([[5]], [[-2]]), [[3]])\n",
    "\n",
    "    def test_two_by_two_matrixes(self):\n",
    "        m1 = [[6, 6], [3, 1]]\n",
    "        m2 = [[1, 2], [3, 4]]\n",
    "        m3 = [[7, 8], [6, 5]]\n",
    "        self.assertEqual(matrix_add(m1, m2), m3)\n",
    "\n",
    "    def test_two_by_three_matrixes(self):\n",
    "        m1 = [[1, 2, 3], [4, 5, 6]]\n",
    "        m2 = [[-1, -2, -3], [-4, -5, -6]]\n",
    "        m3 = [[0, 0, 0], [0, 0, 0]]\n",
    "        self.assertEqual(matrix_add(m1, m2), m3)\n",
    "\n",
    "    def test_input_unchanged(self):\n",
    "        m1 = [[6, 6], [3, 1]]\n",
    "        m2 = [[1, 2], [3, 4]]\n",
    "        m1_original = deepcopy(m1)\n",
    "        m2_original = deepcopy(m2)\n",
    "        matrix_add(m1, m2)\n",
    "        self.assertEqual(m1, m1_original)\n",
    "        self.assertEqual(m2, m2_original)\n",
    "\n",
    "    # Comment out this line after refactoring function for arbitrary input matrices\n",
    "    @unittest.expectedFailure\n",
    "    def test_any_number_of_matrixes(self):\n",
    "        m1 = [[6, 6], [3, 1]]\n",
    "        m2 = [[1, 2], [3, 4]]\n",
    "        m3 = [[2, 1], [3, 4]]\n",
    "        m4 = [[9, 9], [9, 9]]\n",
    "        m5 = [[31, 32], [27, 24]]\n",
    "        self.assertEqual(matrix_add(m1, m2, m3), m4)\n",
    "        self.assertEqual(matrix_add(m2, m3, m1, m1, m2, m4, m1), m5)\n",
    "\n",
    "    # Comment out this line after refactoring for misshapen input matrices\n",
    "    @unittest.expectedFailure\n",
    "    def test_different_matrix_size(self):\n",
    "        m1 = [[6, 6], [3, 1]]\n",
    "        m2 = [[1, 2], [3, 4], [5, 6]]\n",
    "        m3 = [[6, 6], [3, 1, 2]]\n",
    "        with self.assertRaises(ValueError):\n",
    "            matrix_add(m1, m2)\n",
    "        with self.assertRaises(ValueError):\n",
    "            matrix_add(m1, m3)\n",
    "        with self.assertRaises(ValueError):\n",
    "            matrix_add(m1, m1, m1, m3, m1, m1)\n",
    "        with self.assertRaises(ValueError):\n",
    "            matrix_add(m1, m1, m1, m2, m1, m1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note this trick for running unit tests from within Jupyter Notebooks!\n",
    "def run_test():\n",
    "    unittest.main(argv=['first-arg-is-ignored'], exit=False, verbosity=2)\n",
    "    \n",
    "run_test()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Credits: \"Python Morsels\" by Trey Hunner https://www.pythonmorsels.com/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Solutions below this cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution 1 - First cut."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This implementation works, but it can be improved.\n",
    "# Looping over iterables using indexes is ... tedious.\n",
    "def matrix_add(m1, m2):\n",
    "    \"\"\"Add corresponding numbers in given 2-D matrices.\"\"\"\n",
    "    combined = []\n",
    "    for i in range(len(m1)):\n",
    "        row = []\n",
    "        for j in range(len(m1[i])):\n",
    "            row.append(m1[i][j] + m2[i][j])\n",
    "        combined.append(row)\n",
    "    return combined"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run_test()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution 2 -- Let's try `zip` instead of indexes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Using zip twice because we need to loop over two lists\n",
    "# at once for both the outer lists and the inner lists.\n",
    "def matrix_add(m1, m2):\n",
    "    \"\"\"Add corresponding numbers in given 2-D matrices.\"\"\"\n",
    "    combined = []\n",
    "    for rows in zip(m1, m2):\n",
    "        row = []\n",
    "        for items in zip(rows[0], rows[1]):\n",
    "            row.append(items[0] + items[1])\n",
    "        combined.append(row)\n",
    "    return combined\n",
    "\n",
    "# Can this be refactored to use unpacking/multiple assignment instead of hard indexing?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run_test()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution 3 -- List comprehension\n",
    "\n",
    "If you've been doing Python for a little while you might spot a bit of code that we could rewrite here. We're making an new empty list, looping over an old list, and appending to the new list each time we loop like this:\n",
    "\n",
    "```python\n",
    "row = []\n",
    "for n, m in zip(row1, row2):\n",
    "    row.append(n + m)\n",
    "```\n",
    "\n",
    "Whenever you see code written like this, you could copy-paste this into a list comprehension. Like this:\n",
    "\n",
    "```python\n",
    "new_row = [n+m for n, m in zip(row1, row2)]\n",
    "```\n",
    "\n",
    "Or even:\n",
    "\n",
    "```python\n",
    "row = [\n",
    "    n + m\n",
    "    for n, m in zip(row1, row2)\n",
    "]\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Refactored as a list comprehension\n",
    "def matrix_add(m1, m2):\n",
    "    \"\"\"Add corresponding numbers in given 2-D matrices.\"\"\"\n",
    "    combined = []\n",
    "    for row1, row2 in zip(m1, m2):\n",
    "        row = [\n",
    "            n + m\n",
    "            for n, m in zip(row1, row2)\n",
    "        ]\n",
    "        combined.append(row)\n",
    "    return combined\n",
    "\n",
    "# Do we even need the `combined` list? or the `row` intermediate list?\n",
    "# Can we get to the proverbial one-liner from here?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run_test()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What about more than 2 matrices?\n",
    "We will need to change the function signature to accept a variable number of arguments.  We can use the splat `*` operator for this.\n",
    "To do this, let's go back to the longhand for-loop version of the function that we started with, because we also need to add in a totalizer to find the sum of all matrix elements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Trying for variable number of input matrices using splat *\n",
    "# Don't forget to comment out the expected test failure in the Unittest class above\n",
    "def matrix_add(*matrices):\n",
    "    \"\"\"Add corresponding numbers in given 2-D matrices.\"\"\"\n",
    "    combined = []\n",
    "    for rows in zip(*matrices):\n",
    "        row = []\n",
    "        for values in zip(*rows):  # Note the zip function also accepts a variable arg list\n",
    "            total = 0\n",
    "            for n in values:\n",
    "                total += n\n",
    "            row.append(total)\n",
    "        combined.append(row)\n",
    "    return combined\n",
    "\n",
    "# Is there a python built-in function that could help with totalizing (summing) the values?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run_test()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Testing for incorrect matrix shape\n",
    "When adding or subtracting matrices, they must be the same shape:  That means they must have the same number of rows and columns.\n",
    "Our function should check the shape of each input matrix and raise a `ValueError` exception if there are any shape differences between the input matrices.\n",
    "\n",
    "If we use tuples instead of lists, we could use a set for this:\n",
    "\n",
    "```python\n",
    "def matrix_add(*matrices):\n",
    "    \"\"\"Add corresponding numbers in given 2-D matrices.\"\"\"\n",
    "    matrix_shapes = {\n",
    "        tuple(len(r) for r in matrix)\n",
    "        for matrix in matrices\n",
    "    }\n",
    "    if len(matrix_shapes) > 1:\n",
    "        raise ValueError(\"Given matrices are not the same size.\")\n",
    "    return [\n",
    "        [sum(values) for values in zip(*rows)]\n",
    "        for rows in zip(*matrices)\n",
    "    ]\n",
    "```\n",
    "However, this is complex. The `set` is being used because it guarantees uniqueness across all items.  If we end up with more than one item in the set, it indicates that some shapes are not equal to other shapes.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Don't forget to uncomment the `test_different_matrix_size` test in the test cases ..\n",
    "# Let's define a helper function to resolve the shape of a matrix\n",
    "def get_shape(matrix):\n",
    "    return [len(r) for r in matrix]\n",
    "\n",
    "# Check the shape first, then use the list-comprehension version from\n",
    "# our original implementation\n",
    "def matrix_add(*matrices):\n",
    "    \"\"\"Add corresponding numbers in given 2-D matrices.\"\"\"\n",
    "    shape_of_matrix = get_shape(matrices[0])\n",
    "    if any(get_shape(m) != shape_of_matrix for m in matrices):\n",
    "        raise ValueError(\"Given matrices are not the same size.\")\n",
    "    return [\n",
    "        [sum(values) for values in zip(*rows)]\n",
    "        for rows in zip(*matrices)\n",
    "    ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run_test()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}