01_getting_started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "00b54325-2a3f-4c98-921b-d8d6ff920a58",
   "metadata": {},
   "source": [
    "# Getting Started"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d7fbc8d-40da-4c89-a434-14a02880298d",
   "metadata": {},
   "source": [
    "## Getting Started with ipywidgets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1ec732b-06e4-48d1-8211-85000a4e19bf",
   "metadata": {},
   "source": [
    "### What are ipywidgets?! \n",
    "Description - User-interface components that can be linked to your code...add in more. Like the ones below. \n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "357edd49-54c9-49d2-bbf0-5eb838eb5412",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "e71d289bdfa7456cba9ae7edbf7d1abb",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Tab(children=(GridBox(children=(GridBox(children=(Output(layout=Layout(padding='10px'), outputs=({'output_type…"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "## Shout to Matt Greg who created a widget of all widgets available! \n",
    "\n",
    "from widget_org import organized_widgets, list_overview_widget\n",
    "\n",
    "groups = organized_widgets(organize_by='ui')\n",
    "help_url_base='reference/complete-ipywidgets-widget-list.ipynb'\n",
    "list_overview_widget(groups, columns=2, min_width_single_widget=200, help_url_base=help_url_base)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7e4762a-075c-441d-9b89-ee146be76b3f",
   "metadata": {},
   "source": [
    "### Benefits and Limitations\n",
    "interactive, dynamic, build in the existing workflow on the same tools....\n",
    "\n",
    "### How it works - Controls that are displayed in browser. They are JavaScript under the hood, but we will interact with them entirely in python.\n",
    "\n",
    "Go to [nicole-brewer/awesome-jupyter-widgets](https://github.com/nicole-brewer/awesome-jupyter-widgets) and look for...\n",
    "- ipywidgets (classic Jupyter widgets)\n",
    "- other widgets in the Jupyter widget ecosystem"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04e9217c-8199-4bd1-b5d5-6466a18cc744",
   "metadata": {},
   "source": [
    "## Getting started with JupyterLab layout"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dfc8a8c7-0531-47cf-b217-a9f48758192f",
   "metadata": {},
   "source": [
    "Description here: we'll be using slider first to show...."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "e3b78f51-e8a2-4dde-bd2f-b846681e8119",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "0649a71e75bb4ae78ae89b2f1e188fc8",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "IntSlider(value=0)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from ipywidgets import IntSlider\n",
    "\n",
    "slider = IntSlider()\n",
    "slider"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0c28f808-c92e-4dba-b841-9134e7017b46",
   "metadata": {},
   "source": [
    "### Output View\n",
    "\n",
    "Right click on the widget above and select \"Create New View for Output\"."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8606f8ef-dbf2-4a28-854c-121868d47154",
   "metadata": {},
   "source": [
    "### Click-and-drag windows\n",
    "\n",
    "Try it out with the Output View"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e79e3f42-4b87-45b2-95e1-bd54dfa83b86",
   "metadata": {},
   "source": [
    "### Bi-directional communication\n",
    "\n",
    "Notice that the widgets are two views of the same underlying model. You can change either one and changes will be reflected in the other."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3334a53f-ee50-45b2-99f1-201a315093e4",
   "metadata": {},
   "source": [
    "## For our class, we'll use dashboard file\n",
    "\n",
    "Nbdev exports a pyfile...."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "3ff399a5-1145-40e3-88b6-f433c3726aa7",
   "metadata": {},
   "outputs": [],
   "source": [
    "import dashboard"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c76bfd51-14d8-450b-9f58-d4df00e1ed3d",
   "metadata": {},
   "source": [
    "## All about Traits!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a385d2a-8958-4d2e-88d9-19f18c28f345",
   "metadata": {},
   "source": [
    "### Widgets have traits\n",
    "\n",
    "Traits loook and behave a lot like attributes. You can use dot notation to access the value of the trait, just like you would a regular attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "f7edffb8-f41f-4872-8fd9-67a71eb06984",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "slider.value"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4c4843a-7f65-4591-a806-c1167b737dfc",
   "metadata": {},
   "source": [
    "This trait returned an `int`, but under the hood, traits are actually objects that do so much more than regular attributes. For our purposes, there are two key benefits to using traits:\n",
    "\n",
    "1. Traits are validated when set, including type checking\n",
    "2. We can observe changes to a trait"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f19864f-c312-49ad-926f-715bffd67be0",
   "metadata": {},
   "source": [
    "Go ahead and set the value as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "68cbb21b-4e4b-4826-8e69-2687452db49a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "0649a71e75bb4ae78ae89b2f1e188fc8",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "IntSlider(value=0)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "slider"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "1b82ac14-2604-4491-aa13-c3538a3e4236",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider.value = 46 ## ADD in slider view here below"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa1c926a-f39a-4627-a757-d1f88fdf901c",
   "metadata": {},
   "source": [
    "Observe how the change to the trait is reflected in the widget. That means that there's more going on here that meets the eye. So how do traits work under the hood?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0fbeb9eb-3a78-46f9-8c85-5295f2fec433",
   "metadata": {},
   "source": [
    "### Trait Validation\n",
    "\n",
    "One of these benefits is that traits offer robust validation methods. First, let's try setting the value to something that doesn't make a whole lot of sense to see what happens."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "08875434-e875-4cf1-bee2-44b4a036786d",
   "metadata": {},
   "outputs": [
    {
     "ename": "TraitError",
     "evalue": "The 'value' trait of an IntSlider instance expected an int, not the str 'hi'.",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31mTraitError\u001b[0m\u001b[0;31m:\u001b[0m The 'value' trait of an IntSlider instance expected an int, not the str 'hi'.\n"
     ]
    }
   ],
   "source": [
    "%%exception \n",
    "\n",
    "slider.value = 'hi'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3aa4552a-0fe6-476e-b2b0-8d1b39959bad",
   "metadata": {},
   "source": [
    "Okay cool! This definitively shows us that `slider.value` is not just an object attribute. It is a trait. Every time the trait is updated, it runs through a series of validation functions."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d92304ab-95e6-4643-9d11-1aa00fe57eb2",
   "metadata": {},
   "source": [
    "Now let's try to set the slider value to a float. What do you think will happen?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13f56986-ef99-40b9-9438-c423d72640e3",
   "metadata": {},
   "source": [
    "This is kind of a trick questions, so let's walk through it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "41a68c03-443e-43cd-ae47-0592dd1c54b8",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider.value = 4.23238"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1d14bdd-664f-447c-bbed-32a9868ccbd0",
   "metadata": {},
   "source": [
    "What happened? We might have expected to get another error saying that IntSlider expected an int. Instead, the value was silently **casted** into an int. Why? Let's visit the traitlets documentation..."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0430cd74-3cdb-415b-911c-6b4c62c5931f",
   "metadata": {},
   "source": [
    "![image](img/cint_traitlets_documentation.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc268bca-3b8c-4300-936a-ed27347d76ea",
   "metadata": {},
   "source": [
    "Okay, so given that the `value` trait of an `ipywidgets.SliderWidget` inherits `traitlets.CInt`, what do you expect to happen when we run the next line..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "5c69c86f-c22d-4553-89ab-9b1806203b03",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider.value = '10'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54c06c70-8aec-4f64-8607-336c66d0db96",
   "metadata": {},
   "source": [
    "Right. The string is cast, so instead of an error, the value will indeed update to be 10."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46441dcf-695c-4ef2-bee7-1f727fe9fb24",
   "metadata": {},
   "source": [
    "### Observing Trait Changes\n",
    "\n",
    "Okay cool. But what if we want to do something in response the change of the `value` trait? How do we observe the change?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1e3044e-1c48-469a-bfe9-47d76cc34b47",
   "metadata": {},
   "source": [
    "The code below observes changes made to `slider` and prints the change object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "4ce68cef-eb1a-4bf7-934e-45a75ec1dd58",
   "metadata": {},
   "outputs": [],
   "source": [
    "def on_value_change(change):\n",
    "    print(change)\n",
    "\n",
    "slider.observe(on_value_change) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "a96c106f-9ce9-44b7-898b-042dbd0674fa",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "0649a71e75bb4ae78ae89b2f1e188fc8",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "IntSlider(value=45)"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "slider"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "78b13d06-f940-4cf1-9345-ba99b6c25ecd",
   "metadata": {},
   "source": [
    "If you change the value of `slider`, you will get a messsage to the log. It might be hiding, but you can pull it up by clicking the log icon at the bottom of the screen.\n",
    "\n",
    "![img](img/log.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0eb65c04-c7e8-41e6-98fc-0a01199c63a1",
   "metadata": {},
   "source": [
    "You should see a whole bunch of change dictionaries. That's not exactly what we want. `slider` has a lot of traits other than value that change when we interact with the slider. Right now, we are seeing them all. Let's re-write the above code to improve the messages made to the log.\n",
    "1. Let's also print a more informative message: \"Value was \\<old_value> and is now \\<new_value>\"\n",
    "2. Let's update the call to filter out all the other updates we aren't interested in"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84f1e291-c060-4802-91a0-a96a7b0659f8",
   "metadata": {},
   "outputs": [],
   "source": [
    "# %answer key/01/01.py\n",
    "\n",
    "# update this print statement to be more informative \n",
    "# something is missing here"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c982be50-d870-4b55-a296-2ba03b2680b7",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider.value = 20"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3476ea6d-c175-4b10-a91f-327e459b1410",
   "metadata": {},
   "source": [
    "3. Now use the widget to change the value of `slider`\n",
    "\n",
    "What do we see? The new observe function seems to work, but it looks like the old one is still being called too. Let's clear all the observe functions attached to `slider` and then call `observe` again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "932ff263-0380-47a5-9ed6-3cf6a0704eb9",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider.unobserve_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5db167e0-61c7-4776-9a0f-c71401e928b6",
   "metadata": {},
   "source": [
    "Let's verify that worked. Do we get any messages to out log when we change the slider?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "52ac8d37-3634-4bf0-bc62-c17c66d9c29b",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider.value = 30"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a160599a-bc5e-4dc8-a5ae-2ccdd0f44073",
   "metadata": {},
   "source": [
    "Okay and let's set up a callback to the the second iteration of `on_value_change` again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b6d43a64-3bdd-4673-8bdf-bffac68f6b95",
   "metadata": {},
   "outputs": [],
   "source": [
    "# %answer key/01/02.py\n",
    "\n",
    "# Call on_value_change every time value changes"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29445628-8221-4a1a-900e-7ef720c12181",
   "metadata": {},
   "source": [
    "Change the value of `slider` one more time. Did it work? Is it printing out the message as you expect it to?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5efcbb78-8c9b-44f4-9101-2b468d39d8ad",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "415ec323-f766-486a-961f-945b5f662935",
   "metadata": {},
   "source": [
    "## Congrats\n",
    "\n",
    "Great job! We made it to the end of our introduction. Next we will take a look at an actual scientific workflow, and then we will start using what we learned about ipywidgets to create a data dashboard. But first, let's preview the end product!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4faef101-3b7f-4b20-b48e-7d33968612a5",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "03df72b4-918b-4d68-b129-a3c2737bf108",
   "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}