Various bits of cleanup to widgets (saving work in progress).

Author: JuanCab

02b_widgets.ipynb

@@ -9,9 +9,11 @@
     "\n",
     "## TODO LIST\n",
     "- [ ] Add a better pandas dataframe display using `ipydatagrid`\n",
-    "- [ ] Need to fix `%%exception` magic as it is not working.\n",
-    "- [ ] Get to the point where a first version of the dashboard package is created, but note the complexity in the handling of all the settings since we require observer functions to handle all the individual settings (since they are separate widgets).  Do we mention the need to code up validation of the settings (e.g. - We need to ensure the degree of the fit was reasonable given the number of data points, etc.)?\n",
-    "- [x] Revise all references to answers to the new cell numbers in the final version of this notebook.\n"
+    "- [x] Need to fix `%%exception` magic as it is not working.\n",
+    "- [x] Revise all references to answers to the new cell numbers in the final version of this notebook.\n",
+    "- [ ] Remove all the exported answers from the notebook\n",
+    "- [ ] Once main has been rebuilt, uncomment the code to display it.\n",
+    "- [ ] Get to the point where a first version of the dashboard package is created, but note the complexity in the handling of all the settings since we require observer functions to handle all the individual settings (since they are separate widgets).  Do we mention the need to code up validation of the settings (e.g. - We need to ensure the degree of the fit was reasonable given the number of data points, etc.)?\n"
    ]
   },
   {
@@ -56,7 +58,9 @@
    "id": "8bbdd068",
    "metadata": {},
    "source": [
-    "We will be developing the `widgets.py` module in this notebook, so we start by declaring that module to be our intended export target in `nbdev`."
+    "## Building the Widgets Module of our Package\n",
+    "\n",
+    "We will be developing the `widgets.py` module in this notebook, so we start by declaring that module to be our intended export target in `nbdev`. Notice that as we work through this notebook, we will export only those cells necessary to create the `widgets.py` module, leaving other cells which provide examples our testing or development process intact."
    ]
   },
   {
@@ -84,9 +88,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from key.dashboard.main import main_widget\n",
+    "# from key.dashboard.main import main_widget\n",
     "\n",
-    "main_widget"
+    "# main_widget"
    ]
   },
   {
@@ -109,14 +113,14 @@
    "outputs": [],
    "source": [
     "#| export\n",
-    "# %answer key/dashboard/widgets.py 6\n",
+    "\n",
+    "# %answer key/dashboard/widgets.py 8\n",
     "\n",
     "import pandas as pd\n",
     "import os\n",
     "from matplotlib import pyplot as plt\n",
     "from scipy.signal import savgol_filter\n",
-    "# add import statement for Jupyter widgets\n",
-    "import ipywidgets as widgets"
+    "import ipywidgets as widgets  # add import statement for Jupyter widgets"
    ]
   },
   {
@@ -131,7 +135,9 @@
     "\n",
     "Execute the next cell create a browser of the available elements. To see some example code for implementing any of the elements click on its title. It will be easier to view both this overview and [the code examples](reference/complete-ipywidgets-widget-list.ipynb) if you have them open in separate tabs.\n",
     "\n",
-    "Additional Resource: [Jupyter widgets documentation site](https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html)."
+    "Additional Resources:\n",
+    "- [nicole-brewer/awesome-jupyter-widgets](https://github.com/nicole-brewer/awesome-jupyter-widgets) lists many packages taking advantage of Jupyter widgets\n",
+    "- [Jupyter widgets documentation site](https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html)."
    ]
   },
   {
@@ -275,6 +281,8 @@
    "id": "a838e4c9-0ab3-4bd5-abe7-02215b6a4488",
    "metadata": {},
    "source": [
+    "Now go up and look at the slider widget...\n",
+    "\n",
     "Okay that looks a lot better, but how to we actually get the value of the range from the widget? Generally, most widgets have a `value` attribute, but since there are actually two values in a range, I'm not sure what to expect. Let's see what happens when we try and poll the value attribute. What data type is it?"
    ]
   },
@@ -333,7 +341,7 @@
     "#| export\n",
     "# %answer key/dashboard/widgets.py 27\n",
     "\n",
-    "selected_df = original_df[(original_df['Year'] >= year_range.value[0]) & (original_df['Year'] <= year_range.value[1])] # selected_df = original_df[(original_df['Year'] >= from_year) & (original_df['Year'] <= to_year)]\n"
+    "selected_df = original_df[(original_df['Year'] >= year_range.value[0]) & (original_df['Year'] <= year_range.value[1])] # selected_df = original_df[(original_df['Year'] >= from_year) & (original_df['Year'] <= to_year)]"
    ]
   },
   {
@@ -367,7 +375,7 @@
     "\n",
     "### Observing trait changes\n",
     "\n",
-    "Widgets are built on the `traitlets` library, which we will learn more about later on. Attributes of objects that inherit the `HasTraits` class, such as widgets do, are called **traits**. Any trait can be \"observed\" for changes. This means we can observe the \"value\" trait of the slider for changes."
+    "Widgets are built on the `traitlets` library, which we will learn more about later on. Attributes of objects that inherit the `HasTraits` class, such as widgets do, are called **traits**.  Jupyter widgets have an `observe` method that lets you register a handler function that is called when a trait changes."
    ]
   },
   {
@@ -389,17 +397,19 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Attach the above function to the 'value' attribute of the widget so that\n",
-    "# it gets called whenever a trait of the widget changes.\n",
-    "year_range.observe(on_range_change, 'value')"
+    "# Attach the above 'handler' function to the widget so that it gets called whenever a\n",
+    "# trait of the widget changes.\n",
+    "year_range.observe(on_range_change)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "82011a05-8e12-4150-a0f0-fa90fe1fd7bd",
    "metadata": {},
    "source": [
-    "So if we change the value of the slider, our observe function will print the `change`. But what type of data is `change`? Let's find out by changing the value of the slider programmatically."
+    "So if we change the value of the slider, our handler function (`on_range_change`) will print the variable `change`. Apparently the `observe` method of a widget passes some variable to the handler function (the variable we are assigning the name `change`).\n",
+    "\n",
+    "But what is contained in `change`? Let's find out by changing the value of the slider programmatically and thus triggering the handler function.."
    ]
   },
   {
@@ -409,15 +419,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "year_range.value = (1880, 2000)"
+    "year_range.value = (1880, 2002)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "a4ee768e-6d90-4444-a325-1f4276fda768",
    "metadata": {},
    "source": [
-    "So there are a lot of things going on here. Now we know that `change` is a dictionary. There are a lot of key/value pairs here, but the most important one's for us right now are the \"old\" and \"new\" keys. We can use them to see what the widget's traits used to be, and what they were updated to."
+    "It's clear that `change` is a dictionary. There are a lot of key/value pairs here, but the most important ones for us right now are the `old` and `new` keys. We can use their associated values to see what the widget's traits used to be, and what they were updated to."
    ]
   },
   {
@@ -442,11 +452,13 @@
     "# years selected by the user using the year_range widget\n",
     "def on_range_change(change):\n",
     "    global selected_df\n",
-    "    selected_df = original_df[(original_df['Year'] >= year_range.value[0]) & (original_df['Year'] <= year_range.value[1])] \n",
-    "\n",
-    "# Attach the above function to the 'value' attribute of the widget so that\n",
-    "# it gets called whenever a trait of the widget changes.\n",
-    "year_range.observe(on_range_change, 'value')"
+    "    selected_df = original_df[(original_df['Year'] >= change['new'][0])\n",
+    "                              & (original_df['Year'] <= change['new'][1])]\n",
+    "    # NOTE: You could also use:\n",
+    "    #  selected_df = original_df[(original_df['Year'] >= year_range.value[0])\n",
+    "    #                             & (original_df['Year'] <= year_range.value[1])]\n",
+    "    # but it is better to use the 'change' object passed to the function because it is\n",
+    "    # not dependent on the name of the widget."
    ]
   },
   {
@@ -456,16 +468,24 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "year_range.value = (1990, 1993)"
+    "# The second (optional) argument to the observe method is the name of the trait\n",
+    "# to watch for changes. The default is 'All' which watches all traits.\n",
+    "# This particular widget only has a value trait, so asking to observe the 'value'\n",
+    "# trait is redundant... however, it is good practice to be explicit.\n",
+    "year_range.observe(on_range_change, 'value')"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "bcf1ccfe-704d-44fc-915d-837214bb7053",
+   "id": "4f6be451",
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Programmatically set the value of the widget\n",
+    "year_range.value = (1990, 1993)\n",
+    "\n",
+    "# Confirm the selected dataframe changed\n",
     "selected_df"
    ]
   },
@@ -476,7 +496,9 @@
    "source": [
     "That worked really well! But we are still printing the value of `change`. I thought we redefined the function!\n",
     "\n",
-    "As it turns out, both versions of the function have copies that are called when there is a change."
+    "As it turns out, both versions of the function have copies that are called when there is a change in `year_range`.  This is an illustration that we can attach MULTIPLE handler functions to a single widget.  That said, it is a bit confusing to have two functions with the same name attached to this widget.\n",
+    "\n",
+    "**Note**: This happened because functions are treated by Python as immutable objects, so when we redefined the function, we were actually creating a new function object and assigning it to the same name.  The old function object was still attached to the widget."
    ]
   },
   {
@@ -508,8 +530,8 @@
    "source": [
     "%%exception\n",
     "\n",
-    "year_range.observe(on_range_change)\n",
-    "year_range.value = (1993, 1996)"
+    "year_range.observe()\n",
+    "year_range.value = (1987, 1991)"
    ]
   },
   {
@@ -540,7 +562,7 @@
     "#| export\n",
     "# %answer key/dashboard/widgets.py  46\n",
     "\n",
-    "year_range.observe(on_range_change, 'value')"
+    "year_range.observe(on_range_change, 'value') # year_range.observe()"
    ]
   },
   {
@@ -631,15 +653,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "#| export\n",
-    "\n",
-    "# Create a function that will display the selected dataframe\n",
+    "# Create a handler function that will display the selected dataframe\n",
     "def display_selected_dataframe(change):\n",
     "    selected_dataframe_output.clear_output(wait=True)\n",
     "    with selected_dataframe_output:\n",
     "        display(selected_df)\n",
     "\n",
-    "# Start by displaying nothing\n",
+    "# Call the function (since called outside observe method, use None as argument)\n",
     "display_selected_dataframe(None)"
    ]
   },
@@ -808,7 +828,8 @@
     "def on_window_size_change(change):\n",
     "    # Remember to access the global variables\n",
     "    # original_df['Savitzky-Golay'] = savgol_filter(original_df['Temperature'], window_size, poly_order)\n",
-    "    selected_df = original_df[(original_df['Year'] >= year_range.value[0]) & (original_df['Year'] <= year_range.value[1])]"
+    "    selected_df = original_df[(original_df['Year'] >= change['new'][0])\n",
+    "                              & (original_df['Year'] <= change['new'][1])]"
    ]
   },
   {
@@ -860,8 +881,8 @@
     "\n",
     "def on_poly_order_change(change):\n",
     "    global original_df, selected_df\n",
-    "    # original_df['Savitzky-Golay'] = savgol_filter(original_df['Temperature'], window_size, poly_order)\n",
-    "    selected_df = original_df[(original_df['Year'] >= year_range.value[0]) & (original_df['Year'] <= year_range.value[1])]\n"
+    "    original_df['Savitzky-Golay'] = savgol_filter(original_df['Temperature'], window_size.value, change['new']) # original_df['Savitzky-Golay'] = savgol_filter(original_df['Temperature'], window_size, poly_order)\n",
+    "    selected_df = original_df[(original_df['Year'] >= year_range.value[0]) & (original_df['Year'] <= year_range.value[1])]"
    ]
   },
   {

key/dashboard/widgets.py

@@ -6,14 +6,13 @@
            'on_window_size_change', 'display_plot']
 
 # %% ../02b_widgets.ipynb 8
-# %answer key/dashboard/widgets.py 6
+# %answer key/dashboard/widgets.py 8
 
 import pandas as pd
 import os
 from matplotlib import pyplot as plt
 from scipy.signal import savgol_filter
-# add import statement for Jupyter widgets
-import ipywidgets as widgets
+import ipywidgets as widgets  # add import statement for Jupyter widgets
 
 # %% ../02b_widgets.ipynb 12
 # Load data into memory from file
@@ -42,16 +41,12 @@
 # years selected by the user using the year_range widget
 def on_range_change(change):
     global selected_df
-    selected_df = original_df[(original_df['Year'] >= year_range.value[0]) & (original_df['Year'] <= year_range.value[1])] 
-
-# Attach the above function to the 'value' attribute of the widget so that
-# it gets called whenever a trait of the widget changes.
-year_range.observe(on_range_change, 'value')
+    selected_df = original_df[(original_df['Year'] >= change['new'][0]) & (original_df['Year'] <= change['new'][1])]
 
 # %% ../02b_widgets.ipynb 46
 # %answer key/dashboard/widgets.py  46
 
-year_range.observe(on_range_change, 'value')
+year_range.observe(on_range_change, 'value') # year_range.observe()
 
 # %% ../02b_widgets.ipynb 50
 # Create an Output widget to display the selected data