{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<style>div.container { width: 100% }</style>\n",
    "<img style=\"float:left;  vertical-align:text-bottom;\" height=\"65\" width=\"172\" src=\"../assets/holoviz-logo-unstacked.svg\" />\n",
    "<div style=\"float:right; vertical-align:text-bottom;\"><h2>Tutorial 8: Custom Dashboards</h2></div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pathlib\n",
    "import panel as pn\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the previous section we learned the very basics of working with Panel's API. In this section we will learn how to link widgets to outputs \"manually\" rather than using `.interactive`.\n",
    "\n",
    "In this section we will once again make use of the earthquake dataset we loaded previously and compute some statistics:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "df = pd.read_parquet(pathlib.Path('../data/earthquakes-projected.parq'), columns=['time', 'place', 'mag'])\n",
    "df['time'] = df.time.dt.strftime('%m/%d/%Y %H:%M:%S') \n",
    "df = df.reset_index(drop=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Widgets and reactive components\n",
    "\n",
    "Widgets are built on Parameters provided by the [Param](https://param.holoviz.org) library. E.g., consider a `RangeSlider`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mag_filter = pn.widgets.RangeSlider(name='Magnitude', start=0, end=df.mag.max())\n",
    "\n",
    "mag_filter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here the widget `value` is a Parameter that is set to a tuple of the selected upper and lower bound. Parameters are an extended type of Python attribute that declare their type, range, etc. so that other code can interact with them in a consistent way. When we change the range using the widget the ``value`` parameter updates, and vice versa if you change the value parameter manually:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mag_filter.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we will declare a second widget:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "place_filter = pn.widgets.TextInput(placeholder='Enter a placename')\n",
    "\n",
    "place_filter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to the fully automated `.interactive()` interface in hvPlot, Panel offers a very concise, powerful approach of declaring dependencies between the parameters of a object and the arguments to a function. In practice, this middle ground provides enough control for nearly any app, without the complexity of explicit chains of callbacks that would otherwise be required when customizing the behavior.\n",
    "\n",
    "Here we will create a little function that can filter the dataframe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def filter_df(mag_range, place):\n",
    "    lower = df.mag>mag_range[0]\n",
    "    upper = df.mag<mag_range[1]\n",
    "    dffilter = lower & upper\n",
    "    if place:\n",
    "        dffilter &= df.place.str.contains(place)\n",
    "    return df[dffilter].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we can bind the the widgets we created to the inputs of this function using ``pn.bind`` and lay out the widget and the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "filtered_view = pn.Row(\n",
    "    pn.Column(mag_filter, place_filter),\n",
    "    pn.panel(pn.bind(filter_df, mag_range=mag_filter, place=place_filter), width=400))\n",
    "\n",
    "filtered_view"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whenever one of the widgets is changed, the `filter_df` function will be triggered and the DataFrame pane will update with the updated data.\n",
    "\n",
    "Let us also take a look at the repr():"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(filtered_view)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `ParamFunction` pane is what listens to changes in the parameters on the widgets and updates the displayed output."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "\n",
    "Declare two ``IntInput`` widgets with an initial value of 1, then declare a function that depends on the values of both widgets and adds them together. Finally lay out the two widgets and the function in a Panel:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<details><summary>Solution</summary><br>\n",
    "\n",
    "```python\n",
    "w1 = pn.widgets.IntInput(value=1, width=60)\n",
    "w2 = pn.widgets.IntInput(value=1, width=60)\n",
    "\n",
    "def adder(v1, v2):\n",
    "    return pn.panel(v1 + v2, width=50)\n",
    "\n",
    "pn.Row(w1, '+', w2, '=', pn.bind(adder, v1=w1, v2=w2))\n",
    "```\n",
    "    \n",
    "</details>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Callbacks\n",
    "\n",
    "The `pn.bind` function is still a very high level way of declaring interactive components. Panel also supports the more low-level approach of writing explicit callbacks that are executed in response to changes in some parameter, e.g. the ``value`` of a widget. All parameters can be watched using the ``.param.watch`` API, which will call the provided callback with an event object containing the old and new value of the widget."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that it is loaded we will create a slider which we will eventually use to select the row of the dataframe that we want to display:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "row_slider = pn.widgets.IntSlider(value=0, start=0, end=len(df)-1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we create a Pane to display the current row of the dataframe with times formatted nicely:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "row_pane = pn.panel(df.loc[row_slider.value])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have defined both the widget and the object we want to update, we can declare a callback to link the two. As we learned in the previous section, assigning a new value to the ``object`` of a pane will update the display. In the callback we select the row of the dataframe and then assign it to the ``pane.object``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def df_callback(event):\n",
    "    row_pane.object = df.loc[event.new]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lastly we actually have to register this callback. To do so we provide the callback and the parameter we want to trigger the event on the slider's ``.param.watch`` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "row_slider.param.watch(df_callback, 'value')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that everything is connected up, we can put both the widget and the pane in a panel and display them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.Column(row_slider, row_pane, width=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, this process is slightly more laborious than `.interactive()` or even `pn.bind`, but doing it in this way should help you see how everything fits together and can be useful to more precisely control callbacks that update particular parameters or the contents of a larger layout."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Moving onwards\n",
    "\n",
    "Now that we have learned low-level ways to link parameters between displayed objects and build interactive components, we can start building more highly customized apps and dashboards. Before we move on to plotting and visualization let us quickly use what we have learned by adding interactivity to [the dashboard we built in the previous exercise](./exercises/Building_a_Dashboard.ipynb)."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}