docs/examples/full-example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Comprehensive Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Enabling the `widget` backend.\n",
    "# This requires jupyter-matplotlib a.k.a. ipympl.\n",
    "# ipympl can be install via pip or conda.\n",
    "%matplotlib widget\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Testing matplotlib interactions with a simple plot\n",
    "fig = plt.figure()\n",
    "plt.plot(np.sin(np.linspace(0, 20, 100)));"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Always hide the toolbar\n",
    "fig.canvas.toolbar_visible = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Put it back to its default\n",
    "fig.canvas.toolbar_visible = 'fade-in-fade-out'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Change the toolbar position\n",
    "fig.canvas.toolbar_position = 'top'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Hide the Figure name at the top of the figure\n",
    "fig.canvas.header_visible = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Hide the footer\n",
    "fig.canvas.footer_visible = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Disable the resizing feature\n",
    "fig.canvas.resizable = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If true then scrolling while the mouse is over the canvas will not move the entire notebook\n",
    "fig.canvas.capture_scroll = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also call `display` on `fig.canvas` to display the interactive plot anywhere in the notebook"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.canvas.toolbar_visible = True\n",
    "display(fig.canvas)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or you can `display(fig)` to embed the current plot as a png"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3D plotting"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mpl_toolkits.mplot3d import axes3d\n",
    "\n",
    "fig = plt.figure()\n",
    "ax = fig.add_subplot(111, projection='3d')\n",
    "\n",
    "# Grab some test data.\n",
    "X, Y, Z = axes3d.get_test_data(0.05)\n",
    "\n",
    "# Plot a basic wireframe.\n",
    "ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Subplots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# A more complex example from the matplotlib gallery\n",
    "np.random.seed(0)\n",
    "\n",
    "n_bins = 10\n",
    "x = np.random.randn(1000, 3)\n",
    "\n",
    "fig, axes = plt.subplots(nrows=2, ncols=2)\n",
    "ax0, ax1, ax2, ax3 = axes.flatten()\n",
    "\n",
    "colors = ['red', 'tan', 'lime']\n",
    "ax0.hist(x, n_bins, density=1, histtype='bar', color=colors, label=colors)\n",
    "ax0.legend(prop={'size': 10})\n",
    "ax0.set_title('bars with legend')\n",
    "\n",
    "ax1.hist(x, n_bins, density=1, histtype='bar', stacked=True)\n",
    "ax1.set_title('stacked bar')\n",
    "\n",
    "ax2.hist(x, n_bins, histtype='step', stacked=True, fill=False)\n",
    "ax2.set_title('stack step (unfilled)')\n",
    "\n",
    "# Make a multiple-histogram of data-sets with different length.\n",
    "x_multi = [np.random.randn(n) for n in [10000, 5000, 2000]]\n",
    "ax3.hist(x_multi, n_bins, histtype='bar')\n",
    "ax3.set_title('different sample sizes')\n",
    "\n",
    "fig.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.canvas.toolbar_position = 'right'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.canvas.toolbar_visible = False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interactions with other widgets and layouting\n",
    "\n",
    "When you want to embed the figure into a layout of other widgets you should call `plt.ioff()` before creating the figure otherwise `plt.figure()` will trigger a display of the canvas automatically and outside of your layout. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Without using `ioff`\n",
    "\n",
    "Here we will end up with the figure being displayed twice. The button won't do anything it just placed as an example of layouting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as widgets\n",
    "\n",
    "# ensure we are interactive mode \n",
    "# this is default but if this notebook is executed out of order it may have been turned off\n",
    "plt.ion()\n",
    "\n",
    "fig = plt.figure()\n",
    "ax = fig.gca()\n",
    "ax.imshow(Z)\n",
    "\n",
    "widgets.AppLayout(\n",
    "    center=fig.canvas,\n",
    "    footer=widgets.Button(icon='check'),\n",
    "    pane_heights=[0, 6, 1]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Fixing the double display with `ioff`\n",
    "\n",
    "If we make sure interactive mode is off when we create the figure then the figure will only display where we want it to.\n",
    "\n",
    "To do this you can use `plt.ioff()` as a context manager."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with plt.ioff():\n",
    "    fig = plt.figure()\n",
    "\n",
    "ax = fig.gca()\n",
    "ax.imshow(Z)\n",
    "\n",
    "widgets.AppLayout(\n",
    "    center=fig.canvas,\n",
    "    footer=widgets.Button(icon='check'),\n",
    "    pane_heights=[0, 6, 1]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interacting with other widgets\n",
    "\n",
    "## Changing a line plot with a slider"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# When using the `widget` backend from ipympl,\n",
    "# fig.canvas is a proper Jupyter interactive widget, which can be embedded in\n",
    "# an ipywidgets layout. See https://ipywidgets.readthedocs.io/en/stable/examples/Layout%20Templates.html\n",
    "\n",
    "# One can bound figure attributes to other widget values.\n",
    "from ipywidgets import AppLayout, FloatSlider\n",
    "\n",
    "plt.ioff()\n",
    "\n",
    "slider = FloatSlider(\n",
    "    orientation='horizontal',\n",
    "    description='Factor:',\n",
    "    value=1.0,\n",
    "    min=0.02,\n",
    "    max=2.0\n",
    ")\n",
    "\n",
    "slider.layout.margin = '0px 30% 0px 30%'\n",
    "slider.layout.width = '40%'\n",
    "\n",
    "fig = plt.figure()\n",
    "fig.canvas.header_visible = False\n",
    "fig.canvas.layout.min_height = '400px'\n",
    "plt.title('Plotting: y=sin({} * x)'.format(slider.value))\n",
    "\n",
    "x = np.linspace(0, 20, 500)\n",
    "\n",
    "lines = plt.plot(x, np.sin(slider.value * x))\n",
    "\n",
    "def update_lines(change):\n",
    "    plt.title('Plotting: y=sin({} * x)'.format(change.new))\n",
    "    lines[0].set_data(x, np.sin(change.new * x))\n",
    "    fig.canvas.draw()\n",
    "    fig.canvas.flush_events()\n",
    "\n",
    "slider.observe(update_lines, names='value')\n",
    "\n",
    "AppLayout(\n",
    "    center=fig.canvas,\n",
    "    footer=slider,\n",
    "    pane_heights=[0, 6, 1]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Update image data in a performant manner\n",
    "\n",
    "Two useful tricks to improve performance when updating an image displayed with matplolib are to:\n",
    "1. Use the `set_data` method instead of calling imshow\n",
    "2. Precompute and then index the array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# precomputing all images\n",
    "x = np.linspace(0,np.pi,200)\n",
    "y = np.linspace(0,10,200)\n",
    "X,Y = np.meshgrid(x,y)\n",
    "parameter = np.linspace(-5,5)\n",
    "example_image_stack = np.sin(X)[None,:,:]+np.exp(np.cos(Y[None,:,:]*parameter[:,None,None]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with plt.ioff():\n",
    "    fig = plt.figure()\n",
    "im = plt.imshow(example_image_stack[0])\n",
    "\n",
    "def update(change):\n",
    "    im.set_data(example_image_stack[change['new']])\n",
    "    fig.canvas.draw_idle()\n",
    "    \n",
    "    \n",
    "slider = widgets.IntSlider(value=0, min=0, max=len(parameter)-1)\n",
    "slider.observe(update, names='value')\n",
    "widgets.VBox([slider, fig.canvas])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Debugging widget updates and matplotlib callbacks\n",
    "\n",
    "If an error is raised in the `update` function then will not always display in the notebook which can make debugging difficult. This same issue is also true for matplotlib callbacks on user events such as mousemovement, for example see [issue](https://github.com/matplotlib/ipympl/issues/116). There are two ways to see the output:\n",
    "1. In jupyterlab the output will show up in the Log Console (View > Show Log Console)\n",
    "2. using `ipywidgets.Output`\n",
    "\n",
    "Here is an example of using an `Output` to capture errors in the update function from the previous example. To induce errors we changed the slider limits so that out of bounds errors will occur:\n",
    "\n",
    "From: `slider = widgets.IntSlider(value=0, min=0, max=len(parameter)-1)`\n",
    "\n",
    "To:   `slider = widgets.IntSlider(value=0, min=0, max=len(parameter)+10)`\n",
    "\n",
    "If you move the slider all the way to the right you should see errors from the Output widget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with plt.ioff():\n",
    "    fig = plt.figure()\n",
    "im = plt.imshow(example_image_stack[0])\n",
    "\n",
    "out = widgets.Output()\n",
    "@out.capture()\n",
    "def update(change):\n",
    "    with out:\n",
    "        if change['name'] == 'value':\n",
    "            im.set_data(example_image_stack[change['new']])\n",
    "            fig.canvas.draw_idle\n",
    "    \n",
    "    \n",
    "slider = widgets.IntSlider(value=0, min=0, max=len(parameter)+10)\n",
    "slider.observe(update)\n",
    "display(widgets.VBox([slider, fig.canvas]))\n",
    "display(out)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.0"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}