{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interactive data visualizations\n",
    "\n",
    "Jupyter Notebook has support for many kinds of interactive outputs, including\n",
    "the ipywidgets ecosystem as well as many interactive visualization libraries.\n",
    "These are supported in Jupyter Book, with the right configuration.\n",
    "This page has a few common examples.\n",
    "\n",
    "First off, we'll download a little bit of data\n",
    "and show its structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import plotly.express as px\n",
    "data = px.data.iris()\n",
    "data.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Altair\n",
    "\n",
    "Interactive outputs will work under the assumption that the outputs they produce have\n",
    "self-contained HTML that works without requiring any external dependencies to load.\n",
    "See the [`Altair` installation instructions](https://altair-viz.github.io/getting_started/installation.html#installation)\n",
    "to get set up with Altair. Below is some example output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import altair as alt\n",
    "alt.Chart(data=data).mark_point().encode(\n",
    "    x=\"sepal_width\",\n",
    "    y=\"sepal_length\",\n",
    "    color=\"species\",\n",
    "    size='sepal_length'\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotly\n",
    "\n",
    "Plotly is another interactive plotting library that provides a high-level API for\n",
    "visualization. See the [Plotly JupyterLab documentation](https://plotly.com/python/getting-started/#JupyterLab-Support-(Python-3.5+))\n",
    "to get started with Plotly in the notebook.\n",
    "\n",
    "```{margin}\n",
    "Plotly uses [renderers to output different kinds of information](https://plotly.com/python/renderers/)\n",
    "when you display a plot. Experiment with renderers to get the output you want.\n",
    "```\n",
    "\n",
    "Below is some example output.\n",
    "\n",
    ":::{important}\n",
    "For these plots to show, it may be necessary to load `require.js`, in your `_config.yml`:\n",
    "\n",
    "```yaml\n",
    "sphinx:\n",
    "  config:\n",
    "    html_js_files:\n",
    "    - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js\n",
    "```\n",
    ":::\n",
    "\n",
    "\n",
    ":::{important}\n",
    "Including plotly plots in a Jupyter Book page is [currently not compatible](https://github.com/executablebooks/jupyter-book/issues/1528) with the dollarmath syntax extension (mathematical notation written between two \"$\" characters). If you are trying to include both plotly plots and mathematical notation within the same page, and finding that plotly plots are not being rendered, this may be the cause. Try removing all use of the dollarmath syntax within the page and rebuilding the book.\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import plotly.io as pio\n",
    "import plotly.express as px\n",
    "import plotly.offline as py\n",
    "\n",
    "df = px.data.iris()\n",
    "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\", color=\"species\", size=\"sepal_length\")\n",
    "fig"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{important}\n",
    "Since jupyter-book version 0.14, showing plotly figures will generate a warning when building the book. You can suppress this warning by adding the following to your `_config.yml`:\n",
    "\n",
    "```yaml\n",
    "sphinx:\n",
    "  config:\n",
    "    suppress_warnings: [\"mystnb.unknown_mime_type\"]\n",
    "```\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Bokeh\n",
    "\n",
    "Bokeh provides several options for interactive visualizations, and is part of the PyViz ecosystem. See\n",
    "[the Bokeh with Jupyter documentation](https://docs.bokeh.org/en/latest/docs/user_guide/jupyter.html#userguide-jupyter) to\n",
    "get started.\n",
    "\n",
    "Below is some example output. First we'll initialized Bokeh with `output_notebook()`.\n",
    "This needs to be in a separate cell to give the JavaScript time to load."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bokeh.plotting import figure, show, output_notebook\n",
    "output_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we'll make our plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "p = figure()\n",
    "p.circle(data[\"sepal_width\"], data[\"sepal_length\"], fill_color=data[\"species\"], size=data[\"sepal_length\"])\n",
    "show(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ipywidgets\n",
    "\n",
    "You may also run code for Jupyter Widgets in your document, and the interactive HTML\n",
    "outputs will embed themselves in your site. See [the ipywidgets documentation](https://ipywidgets.readthedocs.io/en/latest/user_install.html)\n",
    "for how to get set up in your own environment.\n",
    "\n",
    "```{admonition} Widgets often need a kernel\n",
    "Note that `ipywidgets` tend to behave differently from other interactive visualization libraries. They\n",
    "interact both with Javascript, and with Python. Some functionality in `ipywidgets` may not\n",
    "work in default Jupyter Book pages (because no Python kernel is running). You may be able to\n",
    "get around this with [tools for remote kernels, like thebe](https://thebelab.readthedocs.org).\n",
    "```\n",
    "\n",
    "Here are some simple widget elements rendered below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as widgets\n",
    "widgets.IntSlider(\n",
    "    value=7,\n",
    "    min=0,\n",
    "    max=10,\n",
    "    step=1,\n",
    "    description='Test:',\n",
    "    disabled=False,\n",
    "    continuous_update=False,\n",
    "    orientation='horizontal',\n",
    "    readout=True,\n",
    "    readout_format='d'\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tab_contents = ['P0', 'P1', 'P2', 'P3', 'P4']\n",
    "children = [widgets.Text(description=name) for name in tab_contents]\n",
    "tab = widgets.Tab()\n",
    "tab.children = children\n",
    "for ii in range(len(children)):\n",
    "    tab.set_title(ii, f\"tab_{ii}\")\n",
    "tab"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can find [a list of existing Jupyter Widgets](https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html)\n",
    "in the jupyter-widgets documentation."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.0"
  },
  "vscode": {
   "interpreter": {
    "hash": "7983682d8fc0c3c395069480bceea9d75cae47dba6ba56620eaa7b53995d4444"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}