01_getting_started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "00b54325-2a3f-4c98-921b-d8d6ff920a58",
   "metadata": {},
   "source": [
    "# Getting Started"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3ff399a5-1145-40e3-88b6-f433c3726aa7",
   "metadata": {},
   "outputs": [],
   "source": [
    "import dashboard"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27a9e5a7-f601-4d1e-93db-196ecc270885",
   "metadata": {},
   "source": [
    "## Benefits of Developing in Jupyter Notebooks\n",
    "\n",
    "1. Exploratory (iterative) programming (removes the need for debuggers)\n",
    "2. Literate programming (Knuth)\n",
    "3. Already familiar to scientists and data scientists\n",
    "4. **Ideal for visual outputs and widgets**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "306f2c0c-be3b-4d76-ac29-ba05961e202b",
   "metadata": {},
   "source": [
    "## Benefits of JupyterLab\n",
    "\n",
    "From the [Project Jupyter website](https://jupyter.org/)...\n",
    "> JupyterLab is the latest web-based interactive development environment for notebooks, code, and data. A modular design invites extensions to expand and enrich functionality.\n",
    "\n",
    "1. File browser\n",
    "2. Output views\n",
    "3. Click-and-drag windows\n",
    "3. IDE-like extensions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d7fbc8d-40da-4c89-a434-14a02880298d",
   "metadata": {},
   "source": [
    "## Getting Started with JupyterLab and ipywidgets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4895f487-d61c-49ee-805f-ed3041fb1651",
   "metadata": {},
   "source": [
    "### File Browser\n",
    "\n",
    "Familiar with the classic Jupyter Notebook interface? JupyterLab has a lot more features. For example you can **show or collapse** the file browser. This way, we don't have to work in multiple web browser tabs."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e19f6a9c-a672-4e5d-8a57-981e5786ff7a",
   "metadata": {},
   "source": [
    "### Use shift+enter to run the cell below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e3b78f51-e8a2-4dde-bd2f-b846681e8119",
   "metadata": {},
   "outputs": [],
   "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": "d1ec732b-06e4-48d1-8211-85000a4e19bf",
   "metadata": {},
   "source": [
    "## Jupyter Widgets (ipywidgets)\n",
    "\n",
    "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": "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": null,
   "id": "f7edffb8-f41f-4872-8fd9-67a71eb06984",
   "metadata": {},
   "outputs": [],
   "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": null,
   "id": "1b82ac14-2604-4491-aa13-c3538a3e4236",
   "metadata": {},
   "outputs": [],
   "source": [
    "slider.value = 46"
   ]
  },
  {
   "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": null,
   "id": "08875434-e875-4cf1-bee2-44b4a036786d",
   "metadata": {},
   "outputs": [],
   "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": null,
   "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": null,
   "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": null,
   "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": null,
   "id": "a96c106f-9ce9-44b7-898b-042dbd0674fa",
   "metadata": {},
   "outputs": [],
   "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": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}