07_layouts.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "775f9b1e-8921-4517-8feb-5fcb5e69d57a",
   "metadata": {},
   "source": [
    "## Dashboard Layout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d62ce64-3f56-4ac4-8d8b-1eeb94f22c1e",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| default_exp main"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91f96da3-1429-4c17-a340-2a6c9fedb1b1",
   "metadata": {},
   "source": [
    "Let's start by importing all the widgets we created last time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "88e92874-4371-4342-9658-41fdaa1ecfe6",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "# %answer key/dashboard/widgets.py 3\n",
    "\n",
    "import ipywidgets as widgets\n",
    "# import year_range, poly_order, window_size, plot_output, selected_data_output"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64130f3f-8784-4566-9229-41eb40dab3b1",
   "metadata": {},
   "source": [
    "We can even display them to make sure they still work as expected.\n",
    "> **Issues?** If they don't work as expected, change the beginning of the import statement above to `from dashboard.widgets` to `from dashboard_key.widgets`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a8e4e832-31e3-4531-8340-d2196d5c0514",
   "metadata": {},
   "outputs": [],
   "source": [
    "year_range"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "deb5a7f0-62f1-42dc-8db1-da929da9f893",
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_output"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1a05a0b-fdae-465c-8a58-54ce3a719a4a",
   "metadata": {},
   "source": [
    "Okay, that all looks really good! We successfully used nbdev to export certain cells to a python file. That's going to be a big deal as our dashboard grows into an app, but it's even useful now since our last notebook got really long. This way we can develop in steps but still maintain digestible notebooks. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4619801c-bf74-4ba8-b01d-2918265221c3",
   "metadata": {},
   "source": [
    "## Styling"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4b4736b-bea5-48f4-b5ba-42f42a5bf899",
   "metadata": {},
   "source": [
    "The style attribute is used to expose non-layout related styling attributes of widgets. Many helpful CSS properties are exposed through the style attribute. Others are made available for particular widgets, such as the `handle_color` property of the many types of Sliders."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c5acd726-7575-4bbb-b480-d2c0e17f0823",
   "metadata": {},
   "outputs": [],
   "source": [
    "window_size"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b697d130-4f26-4166-8e50-c9999b54cf62",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "window_size.style.handle_color = 'orange'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c7e4f40-f707-483b-9363-a502423d0adc",
   "metadata": {},
   "source": [
    "Description width has a very convenient option called \"initial\" that makes the description just as wide as it needs to be so none of the letters are hidden."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "07a733cc-645e-4f76-8163-c37785d4cb78",
   "metadata": {},
   "outputs": [],
   "source": [
    "year_range"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3d0a4a53-18a0-43e4-9b64-bebaff52d716",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "year_range.style.handle_color = 'orange'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "acec0efb-613c-4626-9995-4bb79220db3e",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "year_range.style.description_width = 'initial'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dad59186-2c3f-4614-9051-01349bbd3ffd",
   "metadata": {},
   "source": [
    "## Layout\n",
    "\n",
    "Jupyter interactive widgets have a layout attribute exposing a number of CSS properties that impact how widgets are laid out."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8dcf81e9-3915-450f-9af1-86a47be83a70",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "year_range.layout.width = '500px'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "525b4740-91b8-4390-9431-856eb6424b3d",
   "metadata": {},
   "outputs": [],
   "source": [
    "poly_order"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8cdacd40-9e98-4b03-a51d-0a589523191b",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "poly_order.layout.width = '140px'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6803f84a-0970-4b4e-a0cd-c0cb534adc13",
   "metadata": {},
   "source": [
    "## Container Widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa693f7e-930c-46aa-87ea-320ad4bc4195",
   "metadata": {},
   "source": [
    "We an use container widgets for any number of reasons. Later on in this tutorial, we will use the Tab widget to create multistep web applications. Below, we will nest the `selected_data_output` widget inside the Accordion widget to give the user the option to hide it away and make it smaller. Let's see what it looks like on it's own first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "80a85fa7-44c5-49ca-a279-72d3ae16a39e",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "selected_data_accordion = widgets.Accordion(titles=('Selected Data',))\n",
    "selected_data_accordion"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90de6211-60bb-4bce-b753-79c412263254",
   "metadata": {},
   "source": [
    "Not a whole lot going on here. Why? Because we haven't given the Accordion a \"child\" widget to hold just yet. Let's go ahead and **\"Create New View for Output\"**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3384730c-d52d-499e-922d-ed40deacc814",
   "metadata": {},
   "source": [
    "### Tuples\n",
    "\n",
    "The data type of the children trait expected by Container widgets is a tuple. If you haven't encountered them before, tuples are similar to lists but they are immutable, meaning that their contents can't be change once you've created them. The syntax for a tuple with multiple elements is `('one', 'two', 'three')`. Just like a list but with parentheses. There is one execption to that analogy which we will cover soon."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "986e41ed-ffee-4d95-87ad-04b34bda8212",
   "metadata": {},
   "source": [
    "Okay, so let's try and add the selected_data_output widget to the accordion. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "521494d8-7115-441b-94f8-f66e5d44bf56",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%exception\n",
    "\n",
    "selected_data_accordion.children = (selected_data_output)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19b48ec4-796b-4efd-9381-7c41b6cd7d68",
   "metadata": {},
   "source": [
    "That's a lot of text in one error message. What happened here? Our error is telling us that the 'children' trait expected a tuple, and not an Output widget. Do you remember when I said the syntax of a tuple looks the same as a list but with parenthases? Well this is the grand exception (lol). Tuples with one element are written a little differently: as if you were creating a tuple with two elements, but then you removed the second one. That is, the comma and the closing bracket stay, but the \"name of the second element\" is removed. Go ahead and try that on your own below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "331f412e-833b-4f14-91aa-5b5686b28fb6",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "# %answer key/dashboard/widgets.py 28\n",
    "\n",
    "# selected_data_accordion.children = (selected_data_output) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07099cb4-cf07-4f76-99eb-fa69cf720fbe",
   "metadata": {},
   "source": [
    "It seems that by default, the data isn't showing. The accordion apprears to be closed. We can change this using the `selected_index` trait of the accordion. Let's see what it's set to now."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c8f5b91-014e-433c-b703-e243a6d99c33",
   "metadata": {},
   "outputs": [],
   "source": [
    "selected_data_accordion.selected_index"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81cbe9cb-d944-4692-aaa3-ff827135086c",
   "metadata": {},
   "source": [
    "If your accordion is closed, selected_index will be `None` and won't appear to return anything at all. We can open the accordion programatically by setting the selected_index to the index of the accordion we want to open. In this case there is only one. Go ahead and try to open the accordion programmatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "35b6b8f5-acd9-4ad8-8987-f1d7050a8061",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "# %answer key/dashboard/widgets.py 32\n",
    "\n",
    "selected_data_accordion.selected_index"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee491de4-e373-4460-b576-4b4d323b6fad",
   "metadata": {},
   "source": [
    "We like this trick, because our users are probably more interested in our plot than the raw data anyways, so this keeps the raw data from being in the way."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ccc1ed5-c59c-4853-a959-6a9160d5a4c2",
   "metadata": {},
   "source": [
    "## Add an intro with links\n",
    "\n",
    "Before we put everything together, let's add some widgets that provide a little information about the dashboard."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee3f3e71-2120-4415-81e1-ff9f36ef6204",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "INTRO_TEXT = '''\n",
    "<p><b>Curve Smoothing</b>\n",
    "This tool is for smoothing and selecting land-ocean temperature data for visualization. Start by selecting a date\n",
    "range, and then select the smoothing algorithm you want to use. Then click through to the next step, where you will change properies\n",
    "of the curve smoothing algorithm you selected and visualize the data. \n",
    "</p>\n",
    "'''\n",
    "SOURCES_TEXT = '''\n",
    "<p>\n",
    "<b>About Land-Ocean Temperature Data</b>\n",
    "<a href=\"https://climate.nasa.gov/vital-signs/global-temperature/\"\n",
    "target=\"_blank\">Global Temperature (NASA)</a>\n",
    ",\n",
    "<a href=\"https://data.giss.nasa.gov/gistemp/\"\n",
    "target=\"_blank\">GISS Surface Temperature Analysis (NASA)</a>\n",
    "</p><p>\n",
    "This site is based on data downloaded from the following site on 2020-07-14:\n",
    "<a href=\"https://data.giss.nasa.gov/gistemp/graphs/graph_data/Global_Mean_Estimates_based_on_Land_and_Ocean_Data/graph.txt\"  # noqa\n",
    "target=\"_blank\">Global Mean Estimates based on Land and Ocean Data (NASA)</a>\n",
    "'''"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9d46022-ef0a-4d0b-bb46-033cd9f8330b",
   "metadata": {},
   "source": [
    "### Layout object\n",
    "\n",
    "We can use the Layout object to set the layout on initialization."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "187d1f8a-7514-4c09-b019-233b7829acef",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export    \n",
    "intro_text = widgets.HTML(value = INTRO_TEXT, layout = widgets.Layout(max_width = '500px'))\n",
    "data_source_text = widgets.HTML(value = SOURCES_TEXT, layout = widgets.Layout(max_width = '500px'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4c89d351-c9a5-44df-8c12-3669f5c047df",
   "metadata": {},
   "outputs": [],
   "source": [
    "intro_text"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0395d883-2a40-4b0f-83b1-b634869cd59c",
   "metadata": {},
   "outputs": [],
   "source": [
    "data_source_text"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a2ddda7-6828-492a-ba97-59b1110227a1",
   "metadata": {},
   "source": [
    "## Arranging Widgets with HBox and VBox"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a7000ff3-0754-4df4-bb2d-b8f12b15280b",
   "metadata": {},
   "source": [
    "The arrangment where every widget is stacked one on top of the other isn't ideal for a data dashboard that we expect users to access from a desktop. ipywidgets has several container widgets to arrange widgets in various ways. Perhaps two of the most handy are the `HBox` and `VBox` widgets, which arrange widgets horizontally and vertically, respectively. If you are familiar with FlexBox, those properties are available under the hood, but we will not cover them here. Let's use a HBox to put the curve parameter widgets side by side."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9076da82-ae76-4153-9834-848209206c59",
   "metadata": {},
   "outputs": [],
   "source": [
    "window_size"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b0f5d9a8-5f28-4f76-816e-9f6bd65fe1f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "poly_order"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d08aeaf6-4e37-4c2f-9c01-fe8217b7063f",
   "metadata": {},
   "outputs": [],
   "source": [
    "year_range"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea31ebaf-455b-43a4-b532-ca6be562d0e6",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "curve_parameter_widgets = widgets.HBox(children = (window_size, poly_order))\n",
    "curve_parameter_widgets.layout.width = '500px'\n",
    "curve_parameter_widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4298ab7e-b49d-46ba-855d-b78bc4bdb598",
   "metadata": {},
   "source": [
    "Nice! This looks good because this HBox is about as wide as our `year_range` widget is.  Notice that we can pass in the children as a parameter to the widget, or change the children trait after the widget has already been instantiated. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed9eb9fb-4693-4474-b95a-36422a98af4c",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "# %answer key/dashboard/widgets.py 47\n",
    "\n",
    "left_vbox = widgets.VBox()\n",
    "# add children intro_text, data_source_text, year_range, curve_parameter_widgets\n",
    "left_vbox"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db8c12e5-6013-4e92-bf0f-dc3304f2b41d",
   "metadata": {},
   "source": [
    "This look okay, I guess, but we could really use some more padding in between the widgets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "708d637b-24ab-4fae-a242-5a66a072c946",
   "metadata": {},
   "outputs": [],
   "source": [
    "left_vbox.layout.margin = '15px 0 15px 0'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb1dd1b0-7930-465d-8598-65f32b2a7539",
   "metadata": {},
   "source": [
    "Hmmm... that seemed to add a little padding, but only to the ourside f the box. Can you guess how we might add padding to each of the widgets? Try it below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5ac1fc6e-4f35-4fbd-b71f-b8fa7cae169c",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "# %answer key/dashboard/widgets.py 51\n",
    "\n",
    "# how might we add padding to each of the widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4c883a10-3dbd-4c66-af69-12961ff62d09",
   "metadata": {},
   "source": [
    "That looks a lot better! Now lets take care of the right side of our dashboard."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "55438ef3-d32b-4362-9aa5-7cfe2f555c1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "right_vbox = widgets.VBox(children = (selected_data_accordion, plot_output)) # add the selected_data_accordion and the plot_output to a VBox widget\n",
    "right_vbox"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24e051f8-5671-4311-bbe7-423f0cb9b540",
   "metadata": {},
   "source": [
    "Okay! Lets put the left and the right-hand boxes side by side to create the final form of our dashboard!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "48c69c26-7755-4bdf-b980-6a520b04e8d6",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "main_widget = widgets.HBox(children = (left_vbox, right_vbox))\n",
    "main_widget"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06b94b84-e5b3-4df4-ba08-28d9b11a6d10",
   "metadata": {},
   "source": [
    "That is awefully squished together! Let's change a few more settings to clean things up."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f73a7fee-6d94-421d-b391-55d8dd36a43c",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "right_vbox.layout.margin = '0 0 0 30px'\n",
    "right_vbox.layout.align_items = 'flex-end'\n",
    "selected_data_accordion.layout.width = '88%'\n",
    "left_vbox.layout.min_width = '500px'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dcd61361-b84d-4665-88d0-c0e42c3e8dc0",
   "metadata": {},
   "source": [
    "Wow that looks really good! I think it's time to pubish a dashboard. Remember that our main contains all the children widgets, so we should be able to simply import main in another notebook to see the final product."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aa9e694b-a2ab-4da1-b984-85f062f5e9d1",
   "metadata": {},
   "outputs": [],
   "source": [
    "from nbdev.export import nb_export\n",
    "\n",
    "nb_export('07_layout.ipynb', 'dashboard')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "acf3367a-cb57-4a79-961f-f41bea0f2437",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}