ipywidgets-tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Ipywidgets with matplotlib\n",
    "\n",
    "This tutorial gives a brief introduction into using ipywidgets in jupyter notebooks. Ipywidgets provide a set of building blocks for graphical user interfaces that are powerful, yet easy to use. \n",
    "\n",
    "A simple use case could be, adding some basic controls to a plot for interactive data exploration. On the other side of the spectrum, we can combine widgets together to build full-fledged graphical user interfaces.\n",
    "\n",
    "Here, we first introduce the `interact` function, which is a convenient way to quickly create suitable widgets to control functions. Second, we look into specific widgets, and stack them together to build a basic gui application. \n",
    "\n",
    "\n",
    "## Requirements\n",
    "\n",
    "The notebook used for this tutorial is available on [github](https://github.com/Kapernikov/ipywidgets-tutorial), together with a link to a live version on [binder](https://mybinder.org/).\n",
    "\n",
    "To run the notebook locally, the very first requirement is a working jupyter environment. Setting up an installation lies outside the scope of the tutorial, but can be found in the official [docs](https://jupyter.readthedocs.io/en/latest/install.html). Note that for this tutorial all libraries were installed using pip, or the pacman package manager. Anaconda (at least on windows 10) currently has a matplotlib issue that gives some problems. Therefore, if you have problems displaying plots correctly, try using pip only, or linux. The examples were tested on Windows 10 and Arch Linux.\n",
    "\n",
    "The versions of packages explicitly used to create the examples are:\n",
    " * python 3.8.1\n",
    " * matplotlib 3.1.3\n",
    " * numpy 1.18.1\n",
    " * ipywidgets 7.5.1\n",
    " * ipympl 0.4.1\n",
    "\n",
    "To get started we set the ipympl backend, which makes matplotlib plots interactive. We do this using a [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html), starting with %.  We also import some libraries: [matplotlib](https://matplotlib.org/) for plotting, [numpy](https://numpy.org/) to generate data, and [ipywidgets](https://ipywidgets.readthedocs.io/en/latest/) for obvious reasons."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib widget\n",
    "import ipywidgets as widgets\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interact\n",
    "Widgets can be created directly, or through the `interact` function. We explore `interact` first, as it is a convenient for quick use. `interact` takes a function as its first argument, followed by the function arguments with their possible values. This creates a widgets that allows selecting those values, calling the callback with the current value for every selection. This may sound a bit abstract, but an example will hopefully clear it up. \n",
    "\n",
    "The `say_my_name` function, below, prints the text 'my name is {name}'. We pass `say_my_name` into `interact`, together with a list of names. This creates a dropdown filled with the names in the list. Every time we pick a name, `say_my_name` is called with the currently selected name and the printed message gets updated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def say_my_name(name):\n",
    "    \"\"\"\n",
    "    Print the current widget value in short sentence\n",
    "    \"\"\"\n",
    "    print(f'My name is {name}')\n",
    "    \n",
    "widgets.interact(say_my_name, name=[\"Jim\", \"Emma\", \"Bond\"]);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You might wonder how `interact` decided to create a dropdown list. It turns out this choice is based on the input options. In the example above these were given as a list of values, resulting in a dropdown list. \n",
    "\n",
    "We could also create a slider by passing a tuple of the form (start, stop, step), where the values are numerical. If all values are integers this creates an IntSlider, if floats are present (no surprise) a FloatSlider. Alternatively we could construct a checkbox by simply passing a boolean (i.e. True or False). \n",
    "\n",
    "The next cell shows this behaviour by reusing a single function with different input options to  create different kinds of widgets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def say_something(x):\n",
    "    \"\"\"\n",
    "    Print the current widget value in short sentence\n",
    "    \"\"\"\n",
    "    print(f'Widget says: {x}')\n",
    "\n",
    "widgets.interact(say_something, x=[0, 1, 2, 3])\n",
    "widgets.interact(say_something, x=(0, 10, 1))\n",
    "widgets.interact(say_something, x=(0, 10, .5))\n",
    "_ = widgets.interact(say_something, x=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`interact` is not limited to single argument functions. We can pass multiple arguments to create multiple widgets, following the same rules as above. Below, we use a `three` function with three arguments to create three different widgets. Whenever one of the values is changed `three` is called with the current values of the three widgets as its arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def three(x, y, z):\n",
    "    return (x, y, z)\n",
    "\n",
    "_ = widgets.interact(\n",
    "    three, \n",
    "    x=(0, 10, 1), \n",
    "    y=True, \n",
    "    z=['a', 'b', 'c']\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes, not all arguments need to be linked to the widget. We can fix those using the `fixed` function. For example, fixing the `z` argument in `three` results in widgets for `x` and `y` only."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "_ = widgets.interact(\n",
    "    three, \n",
    "    x=(0, 10, 1), \n",
    "    y=True, \n",
    "    z=widgets.fixed('I am fixed')\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also use decorator syntax to create widgets with `interact`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@widgets.interact(x=(0, 10, 1))\n",
    "def foo(x):\n",
    "    \"\"\"\n",
    "    Print the current widget value in short sentence\n",
    "    \"\"\"\n",
    "    print(f'Slider says: {x}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Putting widgets to use\n",
    "Making widgets and printing stuff is all good and well, but let's do something 'slightly' more useful and create a perfectly fake oscilloscope. For this, we use matplotlib to create a plot with a fixed vertical scale and a grid. Next, we generate some `x` values between 0 and 2pi and define a function to return the sine of `x` for some frequency `w`, amplitude `amp` and phase angle `phi`. \n",
    "\n",
    "Finally, we define an update function that takes three arguments: `w`, `amp` and `phi`, corresponding with the parameters controlling our sine. This function clears all existing lines from the ax object (if any) and then plots a our sine wave. Adding the interact decorator completes our beautiful interactive plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set up plot\n",
    "fig, ax = plt.subplots(figsize=(6, 4))\n",
    "ax.set_ylim([-4, 4])\n",
    "ax.grid(True)\n",
    "\n",
    "# generate x values\n",
    "x = np.linspace(0, 2 * np.pi, 100)\n",
    "\n",
    "\n",
    "def my_sine(x, w, amp, phi):\n",
    "    \"\"\"\n",
    "    Return a sine for x with angular frequeny w and amplitude amp.\n",
    "    \"\"\"\n",
    "    return amp*np.sin(w * (x-phi))\n",
    "\n",
    "\n",
    "@widgets.interact(w=(0, 10, 1), amp=(0, 4, .1), phi=(0, 2*np.pi+0.01, 0.01))\n",
    "def update(w = 1.0, amp=1, phi=0):\n",
    "    \"\"\"Remove old lines from plot and plot new one\"\"\"\n",
    "    [l.remove() for l in ax.lines]\n",
    "    ax.plot(x, my_sine(x, w, amp, phi), color='C0')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more information on using `interact`, check the official [documentation](https://ipywidgets.readthedocs.io/en/latest/examples/Using%20Interact.html). In the next bit we'll use the widgets directly and stack them together to build larger apps."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Widgets\n",
    "Often we will want to create widgets manually, for example to build larger interfaces with interconnected components. There are many widgets to choose from. The next cell shows a quick and dirty listing of all classes defined in the ipywidgets module. Not all of these are meant for everyday use, (e.g. DOMWidget and CoreWidgets), but most of them are immediately useful. The official list can be found [here](https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widgets.Textarea(\n",
    "    '\\n'.join([w for w in dir(widgets) if not w.islower()]),\n",
    "    layout=widgets.Layout(height='200px')\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A few widget examples\n",
    "### Text\n",
    "The `Label` widget shows the value text as uneditable text. If more formatting is required, one can use an `HTML` widget. As the name implies this widget renders an html string. For editable text, there are the `Text` and `Textarea` widgets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "label = widgets.Label(\n",
    "    value='A label')\n",
    "\n",
    "html = widgets.HTML(\n",
    "    value='<b>Formatted</b> <font color=\"red\">html</font>', \n",
    "    description=''\n",
    ")\n",
    "\n",
    "text = widgets.Text(\n",
    "    value='A text field', \n",
    "    description='text field'\n",
    ")\n",
    "\n",
    "textarea = widgets.Textarea(\n",
    "    value='A text area for longer texts', \n",
    "    description='text area'\n",
    ")\n",
    "\n",
    "# show the three together in a VBox (vertical box container)\n",
    "widgets.VBox([label, html, text, textarea])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selections\n",
    "The cell below shows a few common selection widgets, some of which we met before. The IntRangeSlider is like an IntSlider but as the name implies it allows the selection of an lower and upper bound of a range. RadioButtons allow the selection of single value from a list of options, similar to the dropdown list. Checkboxes are displayed a little different with their description on the right, but still indented. The indent can be removed by passing the argument `indent`=False\n",
    "\n",
    "A personal favourite is the combobox at the end, which starts showing a list of matching possibilities as one starts typing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "int_slider = widgets.IntSlider(\n",
    "    value=5, \n",
    "    min=0, max=10, step=1, \n",
    "    description='slider'\n",
    ")\n",
    "\n",
    "int_range_slider = widgets.IntRangeSlider(\n",
    "    value=(20, 40), \n",
    "    min=0, max=100, step=2, \n",
    "    description='range slider'\n",
    ")\n",
    "\n",
    "dropdown = widgets.Dropdown(\n",
    "    value='feb', \n",
    "    options=['jan', 'feb', 'mar', 'apr'], \n",
    "    description='dropdown'\n",
    ")\n",
    "\n",
    "radiobuttons = widgets.RadioButtons(\n",
    "    value='feb', \n",
    "    options=['jan', 'feb', 'mar', 'apr'], \n",
    "    description='radio buttons'\n",
    ")\n",
    "\n",
    "combobox = widgets.Combobox(\n",
    "    placeholder='start typing... (e.g. L or o)',\n",
    "    options=['Amsterdam', 'Athens', 'Lisbon', 'London', 'Ljubljana'], \n",
    "    description='combo box'\n",
    ")\n",
    "\n",
    "checkbox = widgets.Checkbox(\n",
    "    description='checkbox',\n",
    "    value=True\n",
    ")\n",
    "\n",
    "\n",
    "# a VBox container to pack widgets vertically\n",
    "widgets.VBox(\n",
    "    [\n",
    "        int_slider, \n",
    "        int_range_slider, \n",
    "        dropdown, \n",
    "        radiobuttons,\n",
    "        checkbox,\n",
    "        combobox,\n",
    "    ]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before, making and displaying widgets is great but putting them to work is awesome. Below, an example is shown of a similar application as above, a sine and a slider (just the one this time). This example shows how we can use the `observe` method to connect a function to a widget trait. `Traits` are special properties that come from a parent class called `HasTraits`. To look more into this, check out the [`traitlets`](https://traitlets.readthedocs.io/en/stable/) library.\n",
    "\n",
    "The `value` property of a widget is such a `trait`, meaning we can use `observe` to connect a callback function, which will get called every time `value` changes. The next cell shows an example, where the frequency of a sine is connected to a slider. \n",
    "Note the `continuous_update` option when creating the IntSlider. This option, also available in other widgets, makes sure the callback is only called when making changes is done (e.g. mousebutton release, enter), and not on every value traversed along the way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.linspace(0, 2 * np.pi, 100)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "line, = ax.plot(x, np.sin(x))\n",
    "ax.grid(True)\n",
    "\n",
    "def update(change):\n",
    "    line.set_ydata(np.sin(change.new * x))\n",
    "    fig.canvas.draw()\n",
    "    \n",
    "int_slider = widgets.IntSlider(\n",
    "    value=1, \n",
    "    min=0, max=10, step=1,\n",
    "    description='$\\omega$',\n",
    "    continuous_update=False\n",
    ")\n",
    "int_slider.observe(update, 'value')\n",
    "int_slider"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the value of the slider changes, the callback function is called with a single argument, change. The next cell shows a slider with a callback that only prints its input argument. As you can see, change is a dictionary-like object with several items:  \n",
    "    \n",
    "    'name': the name of the trait  \n",
    "    'old': the previous value of the trait  \n",
    "    'new': the current value of the trait  \n",
    "    'owner': the widget owning the trait (here, int_slider)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def show_change(change):\n",
    "    display(change)\n",
    "\n",
    "int_slider = widgets.IntSlider(value=7, min=0, max=10)\n",
    "int_slider.observe(show_change, 'value')\n",
    "int_slider.value = 6"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Linking\n",
    "\n",
    "Widgets can also be linked together using the `link` function. This function takes two tuples of the form (widget, trait) and links the given traits of the given widgets. In the example below, `value` on the first slider is connected to `min` on the second. In this way when we change the value of the first, the minimum value of the second is updated correspondingly. There are also a `dlink` and `jslink` function doing a similar thing. `dlink` works one direction only, i.e. updating slider 1 would update slider 2 two, but not the other way around. `jslink` only works in the front-end, in javascript, and does not need a live ipykernel to work. ([docs](https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20Events.html#Linking-Widgets))\n",
    "\n",
    "Below the two sliders are initialised with the same `min` and `max` values. However, after linking them together, updating the `value` of the first to 5, automatically updates `min` for the second as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sl1 = widgets.IntSlider(description='slider 1', min=0, max=10)\n",
    "sl2 = widgets.IntSlider(description='slider 2', min=0, max=10)\n",
    "\n",
    "link = widgets.link(\n",
    "    (sl1, 'value'), \n",
    "    (sl2, 'min')\n",
    ")\n",
    "\n",
    "sl1.value = 5\n",
    "widgets.VBox([sl1, sl2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "links can be removed using the unlink method on the link object, `link.unlink()`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Layout widgets\n",
    "There are various ways organise widgets in an interface. We can use boxes, tabs, accordion, or a templated layout. Here, we will only look at boxes, to see the other options, please check [here](https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html#Container/Layout-widgets) and [here](https://ipywidgets.readthedocs.io/en/latest/examples/Layout%20Templates.html#). \n",
    "\n",
    "First, we create some buttons to play with."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b1 = widgets.Button(description='button 1')\n",
    "b2 = widgets.Button(description='button 2')\n",
    "b3 = widgets.Button(description='button 3')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `HBox` and `VBox` widgets we can easily present our buttons in a row or column layout."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widgets.HBox([b1, b2, b3])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widgets.VBox([b1, b2, b3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These boxes can also be nested to create more complicated layouts. Below, we create two VBoxes. One containing buttons and another containing a dropdown and some radiobuttons. Then we put the VBoxes themselves into an HBox to lay them out next to one another. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def make_boxes():\n",
    "    vbox1 = widgets.VBox([widgets.Label('Left'), b1, b2])\n",
    "    vbox2 = widgets.VBox([widgets.Label('Right'), dropdown, radiobuttons])\n",
    "    return vbox1, vbox2\n",
    "\n",
    "vbox1, vbox2 = make_boxes()\n",
    "\n",
    "widgets.HBox([vbox1, vbox2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make the left and right boxes more visible we add some layout through the `Layout` widget. Note that the syntax for setting layout parameters resembles css. For our box layout we add a solid, 1px thick red border. In addition we add some space in te form of a margin (spacing to other widgets) and padding (spacing between border and widgets inside). Instead of having a margin-top, margin-left and so on, the margin and padding are given as a single string with the values in the order of top, right, bottom & left. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "box_layout = widgets.Layout(\n",
    "        border='solid 1px red',\n",
    "        margin='0px 10px 10px 0px',\n",
    "        padding='5px 5px 5px 5px')\n",
    "\n",
    "vbox1, vbox2 = make_boxes()\n",
    "\n",
    "vbox1.layout = box_layout\n",
    "vbox2.layout = box_layout\n",
    "\n",
    "widgets.HBox([vbox1, vbox2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This code can have some suprising behaviour. The `Layout` object is mutable and two boxes share a single instance. Hence, making changes to the layout of box1 will also be reflected in box2. For example, see what happens when we change the width and colour of vbox1. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "box_layout = widgets.Layout(\n",
    "        border='solid 1px red',\n",
    "        margin='0px 10px 10px 0px',\n",
    "        padding='5px 5px 5px 5px')\n",
    "\n",
    "vbox1, vbox2 = make_boxes()\n",
    "\n",
    "vbox1.layout = box_layout\n",
    "vbox2.layout = box_layout\n",
    "\n",
    "# change vbox1 only?\n",
    "vbox1.layout.width = '400px'\n",
    "vbox1.layout.border = 'solid 2px green'\n",
    "\n",
    "widgets.HBox([vbox1, vbox2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A simple workaround is to put the layout in a function that returns a freshly created instance so that every widget gets its very own layout object. Then, when making changes to vbox1, vbox2 will not change. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def make_box_layout():\n",
    "     return widgets.Layout(\n",
    "        border='solid 1px red',\n",
    "        margin='0px 10px 10px 0px',\n",
    "        padding='5px 5px 5px 5px'\n",
    "     )\n",
    "    \n",
    "vbox1, vbox2 = make_boxes()\n",
    "\n",
    "vbox1.layout = make_box_layout()\n",
    "vbox2.layout = make_box_layout()\n",
    "\n",
    "# really change vbox1 only\n",
    "vbox1.layout.width = '400px'\n",
    "vbox1.layout.border = 'solid 2px green'\n",
    "\n",
    "widgets.HBox([vbox1, vbox2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As mentioned at the start of this section, there are other options to design more advanced applications. An interesting alternative is the `AppLayout` widget, which facilitates building a classic application layout using a column layout sandwiched between a header and footer. Head over to the offical ([docs](https://ipywidgets.readthedocs.io/en/latest/examples/Layout%20Templates.html#AppLayout)) for some examples.."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Putting widgets to use\n",
    "In the next bit we put it all together and build a simple application. We will create a matplotlib figure again, but this time inside an `Output` widget. `Output` can take all kinds of input and display the notebook. By creating the figure inside the output context it will not be drawn until the output widget is used. We can also display the same figure in multiple places, which is sometimes useful in larger applications."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output = widgets.Output()\n",
    "\n",
    "# create some x data\n",
    "x = np.linspace(0, 2 * np.pi, 100)\n",
    "\n",
    "# default line color\n",
    "initial_color = '#FF00DD'\n",
    "\n",
    "with output:\n",
    "    fig, ax = plt.subplots(constrained_layout=True, figsize=(6, 4))\n",
    "    \n",
    "# move the toolbar to the bottom\n",
    "fig.canvas.toolbar_position = 'bottom'\n",
    "ax.grid(True)    \n",
    "line, = ax.plot(x, np.sin(x), initial_color)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "No figure is shown yet, until we use the output widget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we used the `constrained_layout`, when creating the figure. This is similar to the figure's `tight_layout` method, and makes space for the axis labels. However, `constrained_layout` is more convenient in combination with the widget matplotlib backend, as it can be applied before the figure is rendered. With tight_layout we would first have to show the figure and then call the method to make everything fit. It is an experimental feature though, so use with care ['constrained_layout'](https://matplotlib.org/3.1.1/tutorials/intermediate/constrainedlayout_guide.html)\n",
    "\n",
    "Next, we create control widgets with their callback functions and connect them. After getting the callbacks in place we set the default values for the labels through their corresponding widgets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# create some control elements\n",
    "int_slider = widgets.IntSlider(value=1, min=0, max=10, step=1, description='freq')\n",
    "color_picker = widgets.ColorPicker(value=initial_color, description='pick a color')\n",
    "text_xlabel = widgets.Text(value='', description='xlabel', continuous_update=False)\n",
    "text_ylabel = widgets.Text(value='', description='ylabel', continuous_update=False)\n",
    "\n",
    "# callback functions\n",
    "def update(change):\n",
    "    \"\"\"redraw line (update plot)\"\"\"\n",
    "    line.set_ydata(np.sin(change.new * x))\n",
    "    fig.canvas.draw()\n",
    "    \n",
    "def line_color(change):\n",
    "    \"\"\"set line color\"\"\"\n",
    "    line.set_color(change.new)\n",
    "    \n",
    "def update_xlabel(change):\n",
    "    ax.set_xlabel(change.new)\n",
    "    \n",
    "def update_ylabel(change):\n",
    "    ax.set_ylabel(change.new)\n",
    "\n",
    "# connect callbacks and traits\n",
    "int_slider.observe(update, 'value')\n",
    "color_picker.observe(line_color, 'value')\n",
    "text_xlabel.observe(update_xlabel, 'value')\n",
    "text_ylabel.observe(update_ylabel, 'value')\n",
    "\n",
    "text_xlabel.value = 'x'\n",
    "text_ylabel.value = 'y'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we box everything up and display evertyhing together."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "controls = widgets.VBox([int_slider, color_picker, text_xlabel, text_ylabel])\n",
    "widgets.HBox([controls, output])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Packing components in a class\n",
    "To create more high level components, we can also subclass a container and build up our gui from within. Containers have a `children` property to which we can assign a list of widgets that should be displayed. Although, we can assign a list, this is turned into a tuple and cannot be modified afterwards.\n",
    "To remove or add a widget at runtime, the children tuple can be turned back into a list, followed by an insert or deletion and finalised by reassigning to the children property. Since it can be easy to make mistakes when going by index, I tend to add a placeholder box in which I only place the 'dynamic' widget.\n",
    "\n",
    "The example below, packs the entire oscilliscope 'dashboard' in a single component by subclassing `VBox`. All the required widgets are defined in the Sines class and added as its `children`. The callbacks are defined as instance methods. It may not be a masterpiece in object oriented programming, but hopefully it shows the idea of constructing larger reusable components. Note that, we need to call `super().__init__()` from `__init__` to properly initialise the parent class. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def make_box_layout():\n",
    "     return widgets.Layout(\n",
    "        border='solid 1px black',\n",
    "        margin='0px 10px 10px 0px',\n",
    "        padding='5px 5px 5px 5px'\n",
    "     )\n",
    "\n",
    "class Sines(widgets.HBox):\n",
    "    \n",
    "    def __init__(self):\n",
    "        super().__init__()\n",
    "        output = widgets.Output()\n",
    "\n",
    "        self.x = np.linspace(0, 2 * np.pi, 100)\n",
    "        initial_color = '#FF00DD'\n",
    "\n",
    "        with output:\n",
    "            self.fig, self.ax = plt.subplots(constrained_layout=True, figsize=(5, 3.5))\n",
    "        self.line, = self.ax.plot(self.x, np.sin(self.x), initial_color)\n",
    "        \n",
    "        self.fig.canvas.toolbar_position = 'bottom'\n",
    "        self.ax.grid(True)\n",
    "\n",
    "        # define widgets\n",
    "        int_slider = widgets.IntSlider(\n",
    "            value=1, \n",
    "            min=0, \n",
    "            max=10, \n",
    "            step=1, \n",
    "            description='freq'\n",
    "        )\n",
    "        color_picker = widgets.ColorPicker(\n",
    "            value=initial_color, \n",
    "            description='pick a color'\n",
    "        )\n",
    "        text_xlabel = widgets.Text(\n",
    "            value='', \n",
    "            description='xlabel', \n",
    "            continuous_update=False\n",
    "        )\n",
    "        text_ylabel = widgets.Text(\n",
    "            value='', \n",
    "            description='ylabel', \n",
    "            continuous_update=False\n",
    "        )\n",
    "\n",
    "        controls = widgets.VBox([\n",
    "            int_slider, \n",
    "            color_picker, \n",
    "            text_xlabel, \n",
    "            text_ylabel\n",
    "        ])\n",
    "        controls.layout = make_box_layout()\n",
    "        \n",
    "        out_box = widgets.Box([output])\n",
    "        output.layout = make_box_layout()\n",
    "\n",
    "        # observe stuff\n",
    "        int_slider.observe(self.update, 'value')\n",
    "        color_picker.observe(self.line_color, 'value')\n",
    "        text_xlabel.observe(self.update_xlabel, 'value')\n",
    "        text_ylabel.observe(self.update_ylabel, 'value')\n",
    "        \n",
    "        text_xlabel.value = 'x'\n",
    "        text_ylabel.value = 'y'\n",
    "        \n",
    "\n",
    "        # add to children\n",
    "        self.children = [controls, output]\n",
    "    \n",
    "    def update(self, change):\n",
    "        \"\"\"Draw line in plot\"\"\"\n",
    "        self.line.set_ydata(np.sin(change.new * self.x))\n",
    "        self.fig.canvas.draw()\n",
    "\n",
    "    def line_color(self, change):\n",
    "        self.line.set_color(change.new)\n",
    "\n",
    "    def update_xlabel(self, change):\n",
    "        self.ax.set_xlabel(change.new)\n",
    "\n",
    "    def update_ylabel(self, change):\n",
    "        self.ax.set_ylabel(change.new)\n",
    "        \n",
    "        \n",
    "Sines()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is a lot more to ipywidgets than was presented here. A good first start are the official [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) and [traitlets](https://traitlets.readthedocs.io/en/stable/) docs. There is a lot of active development, so it is always interesting to check for updates. There is also a lot of ongoing work on `ipympl`, so staying up to date is a good idea when using it.\n",
    "\n",
    "Two other project that I would like to mention are Voila and ipyvuetify. The [Voila](https://github.com/voila-dashboards/voila) project makes it possible to present a notebook as an interactive web application with a live kernel. [Ipyvuetify](https://github.com/mariobuikhuizen/ipyvuetify) provides a great set of widgets based on vuetify (example in [binder](https://mybinder.org/v2/gh/mariobuikhuizen/ipyvuetify/master?filepath=examples%2FExamples%20template.ipynb))."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}