learning_aid.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Panel/Holoviews Learning Aid\n",
    "## Building a Web App with Panel and Holoviews"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import holoviews as hv\n",
    "\n",
    "from mortgage_calculator.layout import layout as mortgage_app\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sample App"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try out the app below.  It's a mortgage calculator app allowing you to see your mortgage payment, amortization schedule, and principal paid over time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "Note: For the app below to work in JupyterLab, you'll need to run <b>jupyter labextension install @pyviz/jupyterlab_pyviz</b> in the terminal to install the needed labextension.  This is not needed if running in a Jupyter notebook outside of JupyterLab.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mortgage_app"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The app above was built with Python, and without directly writing any css or javascript.  Panel and Holoviews are a great way for data scientist or others to build a web app.  This learning aid is designed to demonstrate some common usage, and encourage you to build your own app from there.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Learning Aid"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Several sections follow below demonstrating key knowledge used to build the app above.\n",
    "1. Background\n",
    "2. Building the App Backbone\n",
    "3. HoloViews Plots\n",
    "4. Closing Notes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Background"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Prototyping in Jupyter\n",
    "Panel and Holoviews are nice because they integrate well with Jupyter notebooks and Jupyterlab.  You can build your app and display it interactively in Jupyterlab to speed up development.  For this to work however, make sure to:\n",
    "1. If running in JupyterLab, run `jupyter labextension install @pyviz/jupyterlab_pyviz` in the terminal to install the needed labextension if you didn't above.  This is not needed if running in a Jupyter notebook outside of JupyterLab.\n",
    "2. Run `import panel as pn` and `pn.extension()` at the top of the notebook.\n",
    "\n",
    "After doing so, you should be all set to prototype the app within jupyterlab."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Panel Basics\n",
    "\n",
    "Panel has 3 main components: panes, widgets, and panels.\n",
    "\n",
    "- **Panes** wrap external viewable items, like markdown, plots, gifs, and even video.\n",
    "- **Widgets** are used to manipulate your app - think sliders, file selectors, password inputs, etc.\n",
    "- **Panels** are used to arrange panes and widgets.  The 4 main types of panels are Row, Column, Tabs, and GridSpec.\n",
    "\n",
    "Take a look at more examples of panes, widgets, and panels (layouts) at [https://panel.holoviz.org/reference/index.html](https://panel.holoviz.org/reference/index.html).  You can also learn about what parameters each widget supports by clicking on a particular widget from there."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Building the App Backbone"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, let's make a widget by running the code below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "radio_button = pn.widgets.RadioButtonGroup(options=['a','b','c'], value='a', name='radio_buttons')\n",
    "radio_button"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When choosing a widget for your app, try to choose a widget made for the applicable datatype (string, float, int, set, etc.).  This will greatly reduce the amount of custom input validation you'll need to do.  Also notice that you can manipulate widgets in the UI or in code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "radio_button.value = 'b'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Making a sample Layout"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We combine a widget and some markdown panes with a Column panel in the next cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Markdown Pane\n",
    "radio_button_display = pn.pane.Markdown(f'Radio Button Value: {radio_button.value}')\n",
    "\n",
    "# Combine Panes and Widget in the Column panel\n",
    "layout = pn.Column('## My Radio Button App', radio_button, radio_button_display)\n",
    "layout"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You'll notice the display doesn't update when a different radio button is pressed. To update we need to make a function to call when a specific widget's value is modified."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "Note: Panel has four different API's.  This learning aid uses the callback API, which is the lowest level of the four, and gives the most control.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Defines the function to call when Radio Box is updated.\n",
    "def update(event):\n",
    "    if event.obj is radio_button:\n",
    "        radio_button_display.object = f'Radio Button Value: {radio_button.value}'\n",
    "\n",
    "# Run the update function when the \"value\" parameter of radio_button widget changes.\n",
    "radio_button.param.watch(update, \"value\")\n",
    "\n",
    "# Now the display updates when the button is pressed.\n",
    "layout"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "Be careful about running the above cell multiple times.  Doing so will attach multiple function callbacks to the radio button, and the app may not behave as expected.  Restarting the kernel, and rerunning the cells will fix this.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may be wondering why the if statement in the update function is needed.  In this simple example, it's not.  However, as we add more widgets I've found it's nice to have a single `update` function for all widgets in order to more precisely specify the order in which pane updates need to happen as well as share intermediate results computed during the update function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Holoviews Plots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The app above could serve as the start of many, many apps, but how exactly do we update plots based on widgets instead of just some text?  It's pretty simple, we just replace the Markdown pane with a HoloViews pane.  The panel HoloViews pane is a wrapper around Holoviews plots.  Other plotting libraries (matplotlib, plotly, etc.) are supported as well, but I'll be demonstrating with Holoviews plots."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define some sample data and import holoviews\n",
    "from bokeh.sampledata.autompg import autompg\n",
    "import holoviews as hv\n",
    "\n",
    "# show data sample\n",
    "autompg.sample(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A complete tutorial of plotting in Holoviews is beyond the scope of this learning aid. For this example, just know that `hv.Scatter(dataframe, kdims='x_column', vdims='y_column')` will produce a scatter plot.\n",
    "The documentation [https://holoviews.org/getting_started/Introduction.html](https://holoviews.org/getting_started/Introduction.html) can be consulted for additional specifics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.Scatter(data=autompg, kdims='mpg', vdims='weight').opts(tools=['hover'], size=6, title='Example Scatter Plot')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's make an app which toggles the axes of the plot.  First we'll make the radio buttons to toggle the axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "radio_opts = [col for col in autompg.columns if col not in {'origin', 'name'}]\n",
    "auto_mpg_radio_x = pn.widgets.RadioButtonGroup(options=radio_opts, value='mpg')\n",
    "auto_mpg_radio_y = pn.widgets.RadioButtonGroup(options=radio_opts, value='mpg')\n",
    "auto_mpg_radio_x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's set up the layout of the plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "auto_plot = pn.pane.HoloViews(object=None, sizing_mode='stretch_width') # empty plot initially\n",
    "\n",
    "layout = pn.Column(\n",
    "            '## Auto MPG App',\n",
    "            pn.Row('#### x-axis:', auto_mpg_radio_x),\n",
    "            pn.Row('#### y-axis:', auto_mpg_radio_y),\n",
    "            auto_plot,\n",
    "            sizing_mode='stretch_width')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next let's configure the plot to update when the widget values are changed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def autompg_plot(x_axis, y_axis):\n",
    "    return hv.Scatter(data=autompg, kdims=x_axis, vdims=y_axis).opts(tools=['hover'], size=6, max_width=750)\n",
    "\n",
    "def auto_mpg_update(event):\n",
    "    if event.obj is auto_mpg_radio_x:\n",
    "        auto_plot.object = autompg_plot(auto_mpg_radio_x.value, auto_mpg_radio_y.value)\n",
    "    if event.obj is auto_mpg_radio_y:\n",
    "        auto_plot.object = autompg_plot(auto_mpg_radio_x.value, auto_mpg_radio_y.value)\n",
    "\n",
    "# Run the update function when the \"value\" parameter of radio_button widget changes.\n",
    "for widget in [auto_mpg_radio_x, auto_mpg_radio_y]:\n",
    "    widget.param.watch(auto_mpg_update, \"value\")\n",
    "\n",
    "# trigger initial plot update\n",
    "auto_mpg_radio_y.value = 'cyl'\n",
    "\n",
    "layout"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "Be careful about running the above cell multiple times.  Doing so will attach multiple function callbacks to the radio button, and the app may not behave as expected.  Restarting the kernel, and rerunning the cells will fix this.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Closing Notes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After you build an app, you'll want to deploy the app so others can view it.  Deployment is beyond the scope of this learning aid, but the documentation [https://panel.holoviz.org/user_guide/Server_Deployment.html](https://panel.holoviz.org/user_guide/Server_Deployment.html) covers a variety of deployment scenarios.  MyBinder is useful for apps that are for demonstration purposes only.  If you want to see how your app would look deployed by itself, then you can run `app.show()` in the notebook, and a new browser tab will open up with the app served on it.  Run the cell below to see it in action."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layout.show()  # You won't be able to view this from binder, but will be able to if running locally."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that you have a simple app to start from, keep going and build your own!"
   ]
  }
 ],
 "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.9.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}