voila/magic_callbacks.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Magic callbacks\n",
    "\n",
    "**Goal: Keep the analysis easy to read while also providing an input form that waits for a button click**\n",
    "\n",
    "What that means:\n",
    "\n",
    "  * Sequential logic that we can read top to bottom\n",
    "  * Variables at global scope (easy to inspect/debug)\n",
    "  * Multiple cells with intermediate outputs\n",
    "  \n",
    "But we also want:\n",
    "\n",
    "  * User-friendly input form with widgets\n",
    "  * \"Run all friendliness\" such that we can **wait** until the user clicks Run.  That enables us to do input validation before running the analysis.\n",
    "  \n",
    "Alternative solutions for executing cells programmatically:\n",
    "\n",
    "  * The Jupyter Javascript API can do this ([discussion](https://github.com/jupyter/notebook/issues/2660)) but you have to know the cell number (fragile) and it doesn't work in Voila.  Example at the bottom of this notebook.\n",
    "  * If you hardcode the notebook filename, you can use nbformat (etc.) to open it and run cells (again, knowing which ones you want to run).\n",
    "  \n",
    "Note: [callable_cells.ipynb](callable_cells.ipynb) in this directory is probably a better/cleaner way to implement the magics."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The magic parts\n",
    "\n",
    "This stuff would be wrapped up into a library..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.core.magic import register_cell_magic\n",
    "\n",
    "# Dictionary of cells that we want to be able to run as callbacks\n",
    "callbacks = {}\n",
    "\n",
    "# Return a function that runs the code in one or more cells\n",
    "def run_callbacks(*names):\n",
    "    def the_callback(w):\n",
    "        output.clear_output()\n",
    "        with output:\n",
    "            for name in names:\n",
    "                exec(callbacks[name], globals(), globals())\n",
    "    return the_callback\n",
    "\n",
    "# Register a cell as being able to run as a callback\n",
    "@register_cell_magic\n",
    "def callback(line, cell):\n",
    "    # Store the cell's code\n",
    "    callbacks[line] = cell\n",
    "    # Also run the code now, unless it has a special name\n",
    "    if line != 'inputs':\n",
    "        exec(cell, globals(), globals())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## My awesome scientific analysis\n",
    "\n",
    "Sequential logic, global scope, intermediate outputs, easy to debug.\n",
    "\n",
    "Cells that we want to run from the dashboard's input form are annotated with `%%callback` names.  Ideally the dashboard would suppress outputs from this section the first time it runs (see [voila issue #171](https://github.com/QuantStack/voila/issues/171))."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set an initial value while I'm doing exploratory analysis\n",
    "\n",
    "x = 4"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%callback square\n",
    "\n",
    "print(f\"square = {x*x}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Extra stuff I don't want in the final dashboard, so no %%callback annotation\n",
    "\n",
    "print(f\"x is {'odd' if x % 2 else 'even'}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%callback sqrt\n",
    "\n",
    "import math\n",
    "print(f\"root = {math.sqrt(x)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Widget input form\n",
    "\n",
    "After user enters parameters and clicks Run, validate inputs, then execute the analysis above.\n",
    "\n",
    "All outputs from executing the code above get redirected into an Output widget below the Button.\n",
    "\n",
    "If I'm still in Jupyter notebook (not dashboard), and I get an error, it's easy to debug because everything is still global -- I can just add a new cell and print things out."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as widgets\n",
    "\n",
    "text = widgets.Text(description='x: ')\n",
    "button = widgets.Button(description='Run')\n",
    "button.on_click(run_callbacks('inputs', 'square', 'sqrt'))\n",
    "output = widgets.Output()\n",
    "widgets.VBox([text, button, output])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%callback inputs\n",
    "\n",
    "if text.value:\n",
    "    x = int(text.value)\n",
    "else:\n",
    "    raise RuntimeError('must set x!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Javascript version\n",
    "\n",
    "For reference.  Not ideal + doesn't work in voila."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import display, Javascript\n",
    "button2 = widgets.Button(description='JS Run')\n",
    "def run_cells(w):\n",
    "    with output2:\n",
    "        display(Javascript('IPython.notebook.execute_cells([5, 7])'))\n",
    "button2.on_click(run_cells)\n",
    "output2 = widgets.Output()\n",
    "widgets.VBox([button2, output2])"
   ]
  },
  {
   "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
}