examples/overviews/Overview.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Overview\n",
    "\n",
    "This notebook introduces the ipyplotly visualization library and demonstrates some of its features.\n",
    "\n",
    "## What is ipyplotly?\n",
    "ipyplotly wraps the excellent Plotly.js JavaScript plotting library for interactive use as an ipywidget inside the Jupyter Notebook.\n",
    "\n",
    "## Features\n",
    "\n",
    " - Traces can be added and updated interactively by simply assigning to properties\n",
    " - The full Traces and Layout API is generated from the plotly schema to provide a great experience for interactive use in the notebook\n",
    " - Data validation covering the full API with clear, informative error messages\n",
    " - Jupyter friendly docstrings on constructor params and properties\n",
    " - Support for setting array properties as numpy arrays. When numpy arrays are used, ipywidgets binary serialization protocol is used to avoid converting these to JSON strings.\n",
    " - Context manager API for animation\n",
    " - Export figures to standalone html\n",
    " - Programmatic export of figures to static SVG, PNG, or PDF images"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ipyplotly\n",
    "from ipyplotly.datatypes import FigureWidget\n",
    "from ipyplotly.callbacks import Points, InputState\n",
    "\n",
    "# pandas\n",
    "import pandas as pd\n",
    "\n",
    "# numpy\n",
    "import numpy as np\n",
    "\n",
    "# scikit learn\n",
    "from sklearn import datasets\n",
    "\n",
    "# ipywidgets\n",
    "from ipywidgets import HBox, VBox, Button\n",
    "\n",
    "# functools\n",
    "from functools import partial"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load iris dataset\n",
    "iris_data = datasets.load_iris()\n",
    "feature_names = [name.replace(' (cm)', '').replace(' ', '_') for name in iris_data.feature_names]\n",
    "iris_df = pd.DataFrame(iris_data.data, columns=feature_names)\n",
    "iris_class = iris_data.target + 1\n",
    "iris_df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create and display an empty ipyplotly Figure\n",
    "f1 = FigureWidget()\n",
    "f1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tab completion \n",
    "Entering ``f1.add_<tab>`` displays add methods for all of the supported trace types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# f1.add_scatter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Entering ``f1.add_scatter(<tab>)`` displays the names of all of the top-level properties for the scatter trace type\n",
    "\n",
    "Entering ``f1.add_scatter(<shift+tab>)`` displays the signature pop-up. Expanding this pop-up reveals the method doc string which contains the descriptions of all of the top level properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# f1.add_scatter("
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Add scatter trace"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scatt1 = f1.add_scatter(x=iris_df.sepal_length.values, y=iris_df.petal_width.values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scatt1.mode?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# That's not what we wanted, change the mode to 'markers'\n",
    "scatt1.mode = 'markers'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set size to 8\n",
    "scatt1.marker.size = 8"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Color markers by iris class\n",
    "scatt1.marker.color = iris_class"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Change colorscale\n",
    "scatt1.marker.cmin = 0.5\n",
    "scatt1.marker.cmax = 3.5\n",
    "scatt1.marker.colorscale = [[0, 'red'], [0.33, 'red'], \n",
    "                            [0.33, 'green'], [0.67, 'green'], \n",
    "                            [0.67, 'blue'], [1.0, 'blue']]\n",
    "\n",
    "scatt1.marker.showscale = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Fix up colorscale ticks\n",
    "scatt1.marker.colorbar.ticks = 'outside'\n",
    "scatt1.marker.colorbar.tickvals = [1, 2, 3]\n",
    "scatt1.marker.colorbar.ticktext = iris_data.target_names.tolist()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set colorscale title\n",
    "scatt1.marker.colorbar.title = 'Species'\n",
    "scatt1.marker.colorbar.titlefont.size = 16\n",
    "scatt1.marker.colorbar.titlefont.family = 'Rockwell'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add axis labels\n",
    "f1.layout.xaxis.title = 'sepal_length'\n",
    "f1.layout.yaxis.title = 'petal_width'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Hover info\n",
    "scatt1.text = iris_data.target_names[iris_data.target]\n",
    "scatt1.hoverinfo = 'text+x+y'\n",
    "f1.layout.hovermode = 'closest'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Animate marker size change"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set marker size based on petal_length\n",
    "with f1.batch_animate(duration=1000):\n",
    "    scatt1.marker.size = np.sqrt(iris_df.petal_length.values * 50)\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Restore constant marker size\n",
    "with f1.batch_animate(duration=1000):\n",
    "    scatt1.marker.size = 8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set drag mode property callback\n",
    "Make points more transparent when `dragmode` is `select` or `lasso`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def set_opacity(marker, layout, dragmode):\n",
    "    if dragmode in ['select', 'lasso']:\n",
    "        marker.opacity = 0.5\n",
    "    else:\n",
    "        marker.opacity = 1.0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f1.layout.on_change(partial(set_opacity, scatt1.marker), 'dragmode')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configure colorscale for brushing"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scatt1.marker.colorbar = None\n",
    "scatt1.marker.colorscale = [[0, 'lightgray'], [0.5, 'lightgray'], [0.5, 'red'], [1, 'red']]\n",
    "scatt1.marker.cmin = -0.5\n",
    "scatt1.marker.cmax = 1.5\n",
    "scatt1.marker.colorbar.ticks = 'outside'\n",
    "scatt1.marker.colorbar.tickvals = [0, 1]\n",
    "scatt1.marker.colorbar.ticktext = ['unselected', 'selected']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Reset colors to zeros (unselected)\n",
    "scatt1.marker.color = np.zeros(iris_class.size)\n",
    "selected = np.zeros(iris_class.size)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configure brushing callback"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Completion helpers\n",
    "trace, points, state = scatt1, Points(), InputState()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def brush(trace, points, state):\n",
    "    inds = np.array(points.point_inds)\n",
    "    if inds.size:\n",
    "        selected[inds] = 1\n",
    "        trace.marker.color = selected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scatt1.on_selected(brush)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now box or lasso select points on the figure and see them turn red"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Reset brush\n",
    "selected = np.zeros(iris_class.size)\n",
    "scatt1.marker.color = selected"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create second plot with different features"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "f2 = FigureWidget(data=[{'type': 'scatter',\n",
    "                     'x': iris_df.petal_length.values, \n",
    "                     'y': iris_df.sepal_width.values,\n",
    "                    'mode': 'markers'}])\n",
    "f2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set axis titles\n",
    "f2.layout.xaxis.title = 'petal_length'\n",
    "f2.layout.yaxis.title = 'sepal_width'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Grab trace reference\n",
    "scatt2 = f2.data[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# Set marker styles / colorbars to match between figures\n",
    "scatt2.marker = scatt1.marker"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Configure brush on both plots to update both plots\n",
    "def brush(trace, points, state):\n",
    "    inds = np.array(points.point_inds)\n",
    "    if inds.size:\n",
    "        selected = scatt1.marker.color.copy()\n",
    "        selected[inds] = 1\n",
    "        scatt1.marker.color = selected\n",
    "        scatt2.marker.color = selected    \n",
    "    \n",
    "scatt1.on_selected(brush)\n",
    "scatt2.on_selected(brush)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f2.layout.on_change(partial(set_opacity, scatt2.marker), 'dragmode')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Reset brush\n",
    "def reset_brush(btn):\n",
    "    selected = np.zeros(iris_class.size)\n",
    "    scatt1.marker.color = selected\n",
    "    scatt2.marker.color = selected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create reset button\n",
    "button = Button(description=\"clear\")\n",
    "button.on_click(reset_brush)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Hide colorbar for figure 1\n",
    "scatt1.marker.showscale = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set dragmode to lasso for both plots\n",
    "f1.layout.dragmode = 'lasso'\n",
    "f2.layout.dragmode = 'lasso'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Display two figures and the reset button\n",
    "f1.layout.width = 600\n",
    "f2.layout.width = 600"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "VBox([HBox([f1, f2]), button])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save figure 2 to a png image in the exports directory\n",
    "#f2.save_image('exports/f2.png')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save figure 1 to a pdf in the exports directory\n",
    "#f1.save_image('exports/f1.pdf')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [default]",
   "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.6.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}