03b_ipyautoui.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to ipyautoui\n",
    "\n",
    "### Goal in this notebook\n",
    "\n",
    "In this notebook we will further explore \n",
    "[`ipyautoui`](https://github.com/maxfordham/ipyautoui), a Python package that provides a simple way to create interactive user interfaces in Jupyter notebooks. It is built on top of Jupyter widgets and Pydantic and provides a higher-level API for creating interactive widgets.  It is particularly well suited for creating settings panels.\n",
    "\n",
    "### Steps you will take in this notebook\n",
    "\n",
    "1. Make a widget from a simple Pydantic model using ipyautoui.\n",
    "2. Learn some of the differences between an ipyautoui-created widget and one you make yourself.\n",
    "3. Implement the data selector for the dashboard, suppressing display of unnecessary elements.\n",
    "4. Address handling constraints for user interface elements."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We begin nearby importing the dashboard for the answer magic."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import dashboard"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| default_exp widgets_autoui"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview of making a widget with ipyautoui\n",
    "\n",
    "Most of the work involved in making a widget using ipyautoui is done in making the Pydantic model. The steps are:\n",
    "\n",
    "1. Define a pydantic model (or write a json schema)\n",
    "2. Feed the model to AutoUi\n",
    "3. You get back a widget! With a value! Whose value is easy to save! Or to observe!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Make a pydantic model\n",
    "\n",
    "#### Exercise: Write the model\n",
    "\n",
    "In the cell below, create a pydantic model called `SimpleModel` with one field, called `window_size`, that is an integer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %answer key/03b/01.py\n",
    "\n",
    "from pydantic import BaseModel\n",
    "\n",
    "# create model called SimpleModel\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Make the UI"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make a widget from this, start by importing `AutoUi` from `ipyautoui`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "\n",
    "from ipyautoui import AutoUi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`AutoUi` takes in the pydantic model and turns it into a widget. Note that it is the class itself, not an instance of the class, that is the argument to `AutoUi`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui = AutoUi(SimpleModel)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run the cell below to display the widget and try changing its value. Note that you can only type numbers (with out decimals) into the box. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Attributes and methods of an AutoUi generated widget\n",
    "\n",
    "A couple of attributes of the auto-generated widget are particularly useful to know about. \n",
    "\n",
    "1. `di_widgets` -- dictionary of widgets, one widget for each pydantic field.\n",
    "2. `value` -- dictionary of values, one key and value for each pydantic field.\n",
    "\n",
    "Though one could use `di_widgets` to display the widget for a field outside the auto-generated widget, that is rarely useful. It is sometimes handy, though, to explore the properties of that widget, or to change its properties."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui.di_widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, `AutoUi` is representing the `int` in our model with an `IntText` widget. That kind of widget only allows integer values to be typed in it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `value` for an `AutoUi`-generated widget is a dictionary. The keys are the fields defined in the pydantic model and the values are the current value of that field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can set the value, like with any other widget, but make sure that the value is a dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui.value = {\"window_size\": 11}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The value can also be observed, though there is a twist -- it is `_value` that you observe, not `value`. The observer below simply prints the value of the widget.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This observer function just prints to the screen\n",
    "def print_value(change):\n",
    "    print(f\"{change['new']=}\")\n",
    "    \n",
    "# NOTE that we are observing changes in _value rather than value\n",
    "ui.observe(print_value, \"_value\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "\n",
    "Change the value of `ui` in the cell below and confirm that you get the message you expect."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %answer key/03b/03.py\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding constraints to the model can affect the generated widget"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, let's add constraints to window size, one constraint at a time, to see how they affect the widget that is generated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Annotated\n",
    "from pydantic import Field\n",
    "\n",
    "class SimpleModel2(BaseModel):\n",
    "    window_size : Annotated[int, Field(ge=2)]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui2 = AutoUi(SimpleModel2)\n",
    "ui2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Oh my! Apparently you can set individual fields to values that are invalid. Since we didn't provide a default value, pydantic assumes it was 0, which violates our constraint.\n",
    "\n",
    "While there is a clear indication of what the error is, it might be nice to set up the interface so that the user cannot enter invalid values.\n",
    "\n",
    "Let's check to see what kind of widget ipyautoui made for us:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui2.di_widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`IntText` doesn't incorporate limits so `BoundedIntText` might be a better representation of this field. We can tell ipyautoui to use that widget via a dictionary passed into the `json_schema_extra` argument. The dictionary key that specifies the widget is `autoui`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SimpleModel3(BaseModel):\n",
    "    window_size : Annotated[\n",
    "        int, \n",
    "        Field(\n",
    "            ge=2, \n",
    "            json_schema_extra=dict(autoui='ipywidgets.BoundedIntText')\n",
    "        )\n",
    "    ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui3 = AutoUi(SimpleModel3)\n",
    "ui3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nice, now the user cannot set the value below 2! As you can see below, that is because the `min` attribute of the `BoundedIntText` is set to 2."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui3.di_widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we add the constraint that the window size must be less than or equal to 100. We also use the `description` argument to `Field` to add a brief description of the field to the user interface."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SimpleModel4(BaseModel):\n",
    "    window_size: Annotated[int, Field(ge=2, le=100, description=\"Size of smoothing window\")]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ui4 = AutoUi(SimpleModel4)\n",
    "ui4"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we have also let `ipyautoui` choose the widget -- with both an upper and lower limit provided it makes a slider."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The data selector"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selector from the pydantic notebook "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's import the pydantic model we finished up the last notebook with. If you get an error here, make sure you ran every cell from the last notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "\n",
    "from dashboard_pydantic.pydantic_model import DataSelectorModel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we create a UI for the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "controls = AutoUi(DataSelectorModel)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*We recommend that you make a new view for this output so that you can see the effect of changes we make later.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise: make an invalid combination of `window_size` and `polynomial_order`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Controlling the display of `AutoUi` elements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many of the user interface elements that `AutoUi` generates can be hidden. The attributes that control the display typically begin with `show_` followed by `iypautoui`'s name for the element.\n",
    "\n",
    "The image below shows a couple of those elements.\n",
    "\n",
    "![Image of ipyautoui widget with save button bar and validation labeled](static/savebutton_bar_and_validation.png)\n",
    "\n",
    "In the cell below we hide both of those elements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "controls.show_savebuttonbar = False\n",
    "controls.show_validation = False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that even after you hide the details of validation there is still a valid/invalid mark."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the cell below make the controls show the validation again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %answer key/03b/05.py\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enforcing the `window_size`/`polynomial_order` constraints."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It would be nice to set up the user interface so that the user cannot set invalid values.\n",
    "\n",
    "There are a few options here:\n",
    "\n",
    "1. Change one or both of the ranges of `window_size` and `polynomial_order`\n",
    "    1. When window size is being changed and a conflict arises, either\n",
    "        1. update the maximum value of the polynomial order to be consistent with window size, with the side effect that the value will be updated to.\n",
    "        1. update the value of `polynomial_order` but not its maximum.\n",
    "    1. When the polynomial order is changed, either\n",
    "        1. update the minimum allowed window size, or\n",
    "        1. update the value of the window size.\n",
    "1. reset the controls to a valid value and display a warning to the user.\n",
    "\n",
    "It does not matter so much which of these you choose, but you do need to choose one."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the first version of the dashboard we did choice 1.A.a -- when `window_size` changed the `polynomial_order` was set to the smaller of 10 and `window_size - 1`.\n",
    "\n",
    "Here we will implement 2 because it is a little different than what we did in the first round of the dashboard. It also places the responsibility of deciding the correct course of action (increase `window_size` or decrease `polynomial-order`) on the user. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our approach is to observe the `_value` of the widget, try to make a valid model out of it, and if that fails set the widget to the old value. `ipyautoui` will take care of displaying an appropriate error message for us.\n",
    "\n",
    "The observe below is created using a [*closure*](https://en.wikipedia.org/wiki/Closure_(computer_programming)), which is a function that is created inside of another function where the inner function uses some of the variables from the outer function. Here we do that instead of treating `ui` as a global variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "\n",
    "from pydantic import ValidationError"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "\n",
    "def make_enforcer(ui):\n",
    "    \"\"\"\n",
    "    Make a function that can be used to observe changes on a \n",
    "    user interface element.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "\n",
    "    ui: an AutoUi widget\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "\n",
    "    callable\n",
    "        A function that can be used as the observer of a traitlets event.\n",
    "    \"\"\"\n",
    "    def constraint_enforcer(change):\n",
    "        \"\"\"\n",
    "        Reset widget to the most recent valid value if the new\n",
    "        value results in an invalid value.\n",
    "        \"\"\"\n",
    "        try:\n",
    "            # Every AutoUi widget has a copy of the model class\n",
    "            # We'll try validating the value in change[\"new\"] and see if it works.\n",
    "            # If the model is valid, we do not need to do anything. The case where the \n",
    "            # model is invalid, which means we need to reset the UI to the last valid\n",
    "            # settings, is handled in the except clause below.\n",
    "            ui.model.model_validate(change[\"new\"])\n",
    "        except ValidationError:\n",
    "            # ⚠️ This is what resets the value of the widget if the user has entered an\n",
    "            #    invalid combination of values.\n",
    "            # That failed, so reset the ui to the old value\n",
    "            ui.value = change[\"old\"]\n",
    "\n",
    "    return constraint_enforcer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run the cell below to add the observer and manipulate the controls to see the effect that the obserer has."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "controls.observe(make_enforcer(controls), \"_value\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save the module with nbdev"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nbdev.export import nb_export\n",
    "\n",
    "nb_export('03b_ipyautoui.ipynb', 'dashboard_pydantic')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}