01-dash-crash-course.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# A Crash Course in Dash"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why Dash and what is Dash?\n",
    "`Dash` is a framework for quickly building data driven web applications. It's data handling capability makes the ease of construction of data driven apps easier over a more general purpose framework such as `React` or `Angular`.\n",
    "\n",
    "`Dash` in fact uses `React` for the front end and React components can be converted to `Dash` components. It is built upon `Flask` where the underlying `Flask` server is accessible for adding additional capabilities such as authentication or additional routes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dash Basics\n",
    "\n",
    "A `Dash` app is simply collection of _components_ whose positional relationship is governed by a _layout_ and whose interaction is governed by callbacks. Like `Flask` you specify the app by creating an `app` instance by invoking\n",
    "\n",
    "```app = Dash(__name__)```\n",
    "\n",
    "and like `Flask` the app is run using `run_server` with pretty much the same options as `Flask`\n",
    "\n",
    "```\n",
    "app.run_server(debug=True)\n",
    "```\n",
    "\n",
    "### Useful Dash Libraries\n",
    "\n",
    "`Dash` has component libraries in addition to many supplied by third parties. The most basic is `dash_html_components` often imported as `html`. The next step up are `dash_core_components` often imported as `dcc`. This includes a `Graph` component which makes graphing data easy. For bootstrap fans there is `dash_bootstrap_components` imported often as `dbc`. Finally for our purpose, you'll want to use `dash_leaflet` which will be imported here as `dl`.\n",
    "\n",
    "**Note**: In dash 2.0. `dash_html_components` is replaced by `dash.html` and `dash_core_components` is replaced by `dash.dcc`.\n",
    "\n",
    "### Components\n",
    "\n",
    "A dash component is simply a object on a web page. `Dash` comes with the usual HTML DOMs such as `<div>`, etc, but also can include more complex objects such as graphs and as described later `leaflet` components. In effect any `React` component can be made a dash component. Each component has properties which can be set at the creation of the component and can be modified in a callback. For example, the `html.Div` component has a `children` property which can contain text, another component or a list of components. Other important properties common to most components is the `className` property which specifies the CSS class for the component and the `style` property which specifies inline styles to be applied to the component.\n",
    "\n",
    "### Layout\n",
    "\n",
    "Layouts can be as complicated as any webpage can. Essentially, a layout loosely mirrors the underlying HTML for an app. For example, here is a snippet from the `Dash` documentation:\n",
    "```\n",
    "app.layout = html.Div(children=[\n",
    "    html.H1(children='Hello Dash'),\n",
    "\n",
    "    html.Div(children='''\n",
    "        Dash: A web application framework for your data.\n",
    "    '''),\n",
    "\n",
    "    dcc.Graph(\n",
    "        id='example-graph',\n",
    "        figure=fig\n",
    "    )\n",
    "])\n",
    "```\n",
    "In this example, the app comprises a `div` with a major heading `h1`, another `div` and a `graph`\n",
    "\n",
    "### Callback\n",
    "\n",
    "Callbacks are reactive to changes in a component property and changes a property. The basic anatomy of a callback is to decorate your callback function with the `@app.callback` decorator. The decorator takes as parameters inputs, outputs and optionally state. Each of these are type `Input`, `Output` and `State` respectively of a component property. The callback is executed anytime one of the inputs changes. The result of the callback changes one or more of the outputs. A full example taken from the documentation is here:\n",
    "\n",
    "```\n",
    "import dash\n",
    "import dash_core_components as dcc\n",
    "import dash_html_components as html\n",
    "from dash.dependencies import Input, Output\n",
    "\n",
    "app = dash.Dash(__name__)\n",
    "\n",
    "app.layout = html.Div([\n",
    "    html.H6(\"Change the value in the text box to see callbacks in action!\"),\n",
    "    html.Div([\n",
    "        \"Input: \",\n",
    "        dcc.Input(id='my-input', value='initial value', type='text')\n",
    "    ]),\n",
    "    html.Br(),\n",
    "    html.Div(id='my-output'),\n",
    "\n",
    "])\n",
    "\n",
    "\n",
    "@app.callback(\n",
    "    Output(component_id='my-output', component_property='children'),\n",
    "    Input(component_id='my-input', component_property='value')\n",
    ")\n",
    "def update_output_div(input_value):\n",
    "    return 'Output: {}'.format(input_value)\n",
    "\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    app.run_server(debug=True)\n",
    "```\n",
    "\n",
    "In this example, every time the input box `my-input` changes, the content of the `div` `my-output`. Because the callbacks require inputs, states and outputs to be positional it cam make maintenance difficult. They have recently introduced \"flexible callback signatures\" which make organization easier however, I prefer the plugin `dict_callback`. Available at https://github.com/WestHealth/dash-dict-callback.\n",
    "\n",
    "#### Idiosyncracies\n",
    "\n",
    "Because of the way `Dash` organizes callbacks as graphs, they strive to avoid race conditions in doing so, they only allow each property of each component be the output of one callback. This often creates requires you to create mega callback functions with lots of mega callbacks. Managing this is where `dict_callback` can be useful.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## For this workshop\n",
    "\n",
    "You may run this code separately as a python app. However, since the format of this workshop is in a Jupyter notebook, JupyterDash is used. In order to use it, you will need to install `jupyter_dash`. If you run the notebook in a docker container as I do, you will also need to install `jupyter-server-proxy` which proxies the `Dash` app to use the same port as the notebook.\n",
    "\n",
    "The main two differences between using `JupyterDash` versus `Dash` is you create it using `JupyterDash` rather than `Dash` and the `run_server` method has an extra `mode` paramenter that can be set to `inline`.\n",
    "\n",
    "I also prefer to randomly assign the port to the app so that I can embed many apps in the same notebook or notebook container."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import dash\n",
    "import dash.dcc as dcc\n",
    "import dash.html as html\n",
    "from dash.dependencies import Input, Output\n",
    "from jupyter_dash import JupyterDash\n",
    "import random"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### This next line is a hack. For some reason the JupyterDash.infer_jupyter_proxy_config doesn't necessarily work with this line in a separate cell"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from jupyter_dash.comms import _send_jupyter_config_comm_request\n",
    "_send_jupyter_config_comm_request()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "JupyterDash.infer_jupyter_proxy_config()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "app = JupyterDash(__name__)\n",
    "\n",
    "app.layout = html.Div([\n",
    "    html.H6(\"Change the value in the text box to see callbacks in action!\"),\n",
    "    html.Div([\n",
    "        \"Input: \",\n",
    "        dcc.Input(id='my-input', value='initial value', type='text')\n",
    "    ]),\n",
    "    html.Br(),\n",
    "    html.Div(id='my-output'),\n",
    "])\n",
    "\n",
    "\n",
    "@app.callback(Output(component_id='my-output', component_property='children'),\n",
    "              Input(component_id='my-input', component_property='value'))\n",
    "def update_output_div(input_value):\n",
    "    return 'Output: {}'.format(input_value)\n",
    "\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    app.run_server(mode='inline', port=random.choice(range(2000, 10000)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "NOTEBOOK_PORT = 2000\n",
    "app = JupyterDash(__name__)\n",
    "\n",
    "app.layout = html.Div([\n",
    "    html.H6(\"Change the value in the text box to see callbacks in action!\"),\n",
    "    html.Div([\n",
    "        \"Input: \",\n",
    "        dcc.Input(id='my-input', value='initial value', type='text')\n",
    "    ]),\n",
    "    html.Br(),\n",
    "    html.Div(id='my-output'),\n",
    "])\n",
    "\n",
    "\n",
    "@app.callback(Output(component_id='my-output', component_property='children'),\n",
    "              Input(component_id='my-input', component_property='value'))\n",
    "def update_output_div(input_value):\n",
    "    return 'Output: {}'.format(input_value)\n",
    "\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    app.run_server(mode='inline', port=NOTEBOOK_PORT)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "app._terminate_server_for_port(\"localhost\", NOTEBOOK_PORT)"
   ]
  },
  {
   "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}