03-Communication between Plotly and IPython kernel.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 在Plotly图表与运算核之间通信"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "上节介绍的方法所绘制的图表一旦创建就无法再通过Python修改其数据或各种显示属性。本节利用前面两节介绍的方法实现Plotly图表与运算核之间的通信，通过本节介绍的方法，我们可以在图表创建之后：\n",
    "\n",
    "* 动态更新曲线的数据或者图表的任何显示属性。\n",
    "* 将图表上发生的交互事件发送给运算核，例如可以实现数据的点选。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "\n",
       "    require.config({\n",
       "      paths: {\n",
       "        plotly: \"/files/\" + Jupyter.notebook.notebook_path + \"/../\" + \"plotly.min\"\n",
       "      },\n",
       "\n",
       "      shim: {\n",
       "        plotly: {\n",
       "          deps: [],\n",
       "          exports: 'plotly'\n",
       "        }\n",
       "      }\n",
       "    });\n",
       "\n",
       "    require(['plotly'], function(plotly) {\n",
       "        window.Plotly = plotly;\n",
       "        console.log(\"Plotly loaded\");\n",
       "    });\n",
       "    "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from plotlyhelp import init_plotly_offline_mode\n",
    "init_plotly_offline_mode()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "为了实现Plotly图表与运算核之间的通信，我们需要同时编写在客户端运行的Javascript程序和在运算核中运行的Python程序。这两个程序之间通信需要使用事先约定好的频道。\n",
    "\n",
    "下面是生成Javascript的模板，它有如下参数：\n",
    "\n",
    "* `uid`:页面中表示图表的元素的标识，该标识也用于通信的频道名。\n",
    "* `onclick`:是否将图表的点击事件(`plotly_click`)发送给运算核。\n",
    "* `onrelayout`:是否将图表的布局事件(`plotly_relayout`)发送给运算核。该事件在X-Y轴的显示范围改变时触发。\n",
    "\n",
    "当运算核开启`uid`频道的通信时，由`register_target()`注册的回调函数将被运行。在`msg.content.data`中保存着由运算核发来的数据，其中`code`键对应的是需要被运行的代码，而`data`键对应的是数据。这是使用`eval()`动态执行代码，代码中`graph`变量为页面上表示图表的元素，`data`为传递过来的数据。使用这种方法，可以通过发送不同的代码控制图表的各个不同部分的显示。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from jinja2 import Template\n",
    "\n",
    "JsTemplate = Template(\"\"\"\n",
    "<script>\n",
    "(function(){\n",
    "var comm_manager=Jupyter.notebook.kernel.comm_manager;\n",
    "\n",
    "comm_manager.register_target('{{uid}}', function(comm, msg){\n",
    "    console.log(msg);\n",
    "    var data = JSON.parse(msg.content.data.data);\n",
    "    var code = msg.content.data.code;\n",
    "    var graph = document.getElementById(\"{{uid}}\");\n",
    "    eval(code);\n",
    "    Plotly.redraw(graph);\n",
    "});\n",
    "\n",
    "var send = function(msg){\n",
    "    var comm = comm_manager.new_comm(\"{{uid}}\", msg);\n",
    "    comm.close();\n",
    "};\n",
    "\n",
    "require([\"plotly\"], function(Plotly){\n",
    "    var graph = document.getElementById(\"{{uid}}\");\n",
    "    {%if onclick%}\n",
    "    graph.on(\"plotly_click\", function(data){\n",
    "        if(typeof(data) == \"undefined\") return;\n",
    "        if(!data.hasOwnProperty(\"lassoPoints\")){\n",
    "            var points = _.map(data.points, function(p){\n",
    "                return {\n",
    "                  curveNumber:p.curveNumber,\n",
    "                  pointNumber:p.pointNumber,\n",
    "                  x:p.x, y:p.y};\n",
    "            });\n",
    "            var send_data = {\"event\":\"select\", \"data\":{\"select_type\":\"click\", \"points\":points}};\n",
    "            console.log(send_data);\n",
    "            send(send_data);\n",
    "        }\n",
    "    });\n",
    "    {% endif %}\n",
    "\n",
    "    {%if onrelayout %}\n",
    "    graph.on(\"plotly_relayout\", function(data){\n",
    "        var send_data = {\"event\":\"relayout\", \"data\":data};\n",
    "        console.log(send_data);\n",
    "        send(send_data);\n",
    "    });\n",
    "    {% endif %}\n",
    "});\n",
    "\n",
    "})();\n",
    "\n",
    "</script>\n",
    "\"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "下面是运算核部分的Python代码，`PlotlyWidget`从`ipywidgets.HTML`继承。`HTML`类是用于显示任意HTML的控件，只需要在运算核中修改其`value`属性，即可改变页面上该控件所显示的HTML元素。\n",
    "\n",
    "由于Plotly提供的`iplot()`会将直接生成的HTML代码发送给客户端显示，❶因此这里调用其内部生成HTML代码的函数`_plot_html()`将图表转换为HTML代码，并得到与该图表对应的唯一标识`uid`。❷然后将前面的Javascript代码添加到HTML代码之后。❸最后将最终的HTML代码赋值给`value`属性。\n",
    "\n",
    "❹当图表上的事件响应函数中调用`send()`发送数据时，`_on_open()`方法将被调用。这里根据其`event`键判断事件的类型，调用用户设置的回调函数`click_callback`或`relayout_callback`。\n",
    "\n",
    "❺用于发送代码和数据给客户端，这里使用`bokeh.core.json_encoder()`将数据转换为JSON字符串之后再发送。使用`json_encoder()`的好处是它可以针对NumPy的数组进行序列化。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from ipywidgets import HTML\n",
    "from plotly.offline.offline import _plot_html\n",
    "from ipykernel.comm import Comm\n",
    "from bokeh.core import json_encoder\n",
    "\n",
    "class PlotlyWidget(HTML):\n",
    "\n",
    "    def __init__(self, figure, click_callback=None, relayout_callback=None, **kwargs):\n",
    "        super().__init__(**kwargs)\n",
    "        html, uid, _, _ = _plot_html(figure, False, \"\", True, None, None, True) #❶\n",
    "        self.uid = str(uid)\n",
    "        jscode = JsTemplate.render(\n",
    "            uid=self.uid,\n",
    "            onclick=click_callback is not None,\n",
    "            onrelayout=relayout_callback is not None)\n",
    "        html += jscode  #❷\n",
    "        self.value = html  #❸\n",
    "        self.click_callback = click_callback\n",
    "        self.relayout_callback = relayout_callback\n",
    "        self.comm_manager.register_target(self.uid, self._on_open) #❹\n",
    "\n",
    "    @property\n",
    "    def comm_manager(self):\n",
    "        return get_ipython().kernel.comm_manager\n",
    "\n",
    "    def _on_open(self, comm, msg):\n",
    "        data = msg[\"content\"][\"data\"]\n",
    "        event = data[\"event\"]\n",
    "        if event == \"select\" and self.click_callback is not None:\n",
    "            self.click_callback(data[\"data\"])\n",
    "        elif event == \"relayout\" and self.relayout_callback is not None:\n",
    "            self.relayout_callback(data[\"data\"])\n",
    "        self.recv_msg = msg\n",
    "\n",
    "    def send(self, code, data): #❺\n",
    "        comm = Comm(target_name=str(self.uid),\n",
    "                    data={\"code\":code, \"data\":json_encoder.serialize_json(data)})\n",
    "        comm.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "下面让我们使用前面的`PlotlyWidget`编写一个能动态更新图表的例子。首先创建表示图表的字典`fig`："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "x = np.linspace(0, 4*np.pi, 200)\n",
    "\n",
    "def f(x, x0, k):\n",
    "    return np.exp(-k*(x+x0)) * np.sin(4 * x + x0)\n",
    "\n",
    "x0, k = 0, 0.1\n",
    "\n",
    "line = {\"x\":x, \"y\":f(x, x0, k), \"name\":\"sin*exp\", \n",
    "        \"line\":{\"width\":3, \"color\":\"blue\"}}\n",
    "line2 = {\"x\":x, \"y\":f(x, 0, 0), \"name\":\"sin\"}\n",
    "layout = {\"title\": \"Example\", \"width\":600, \"height\":400}\n",
    "fig = {\"data\":[line, line2], \"layout\":layout}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "然后创建两个滑块控件`slider_x0`和`slider_k`，用于修改图表中曲线函数的参数。`selected_info`是一个`HTML`控件，用于显示图表事件响应函数发来的信息："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from ipywidgets import FloatSlider, HTML, VBox, HBox\n",
    "\n",
    "slider_x0 = FloatSlider(value=x0, msg_throttle=1, description=\"x0:\", width=200)\n",
    "slider_k = FloatSlider(value=k, msg_throttle=1, min=0, max=1, description=\"k:\", width=200)\n",
    "selected_info = HTML(description=\"selected:\", width=250, height=300)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "下面创建`PlotlyWidget`对象`plot_widget`，它的第一个参数是表示图表的数据，`click_callback`和`relayout_callback`是响应图表事件的回调函数。这里的回调函数`show_data()`将接收到的数据高亮化之后显示在`selected_info`控件里。\n",
    "\n",
    "* `click_callback`:当图表被点击时该回调函数被调用。\n",
    "* `relayout_callback`:当数据显示范围改变时该回调函数被调用。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import json\n",
    "from pygments import highlight\n",
    "from pygments.lexers import JsonLexer\n",
    "from pygments.formatters import HtmlFormatter   \n",
    "\n",
    "def show_data(data):\n",
    "    code = json.dumps(data, indent=2)\n",
    "    selected_info.value = highlight(code, JsonLexer(), HtmlFormatter(noclasses=True))\n",
    "    \n",
    "plotly_widget = PlotlyWidget(fig, \n",
    "                             click_callback=show_data,\n",
    "                             relayout_callback=show_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "下面为两个滑块控件设置当属性`value`改变时的回调函数`slider_callback()`。在该函数中计算出曲线上各点Y坐标的值之后通过`send()`方法将数据和设置Y轴数据的Javascript的程序`graph.data[0][\"y\"] = data;`发送给客户端。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def slider_callback(name):\n",
    "    y = f(x, slider_x0.value, slider_k.value)\n",
    "    plotly_widget.send('graph.data[0][\"y\"] = data;', y)\n",
    "    \n",
    "slider_x0.observe(slider_callback, names=\"value\")\n",
    "slider_k.observe(slider_callback, names=\"value\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "最后使用`VBox`和`HBox`显示上述控件："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "HBox([VBox([slider_x0, slider_k, selected_info]), plotly_widget])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "下面是界面截图：\n",
    "\n",
    "![Plotly](plotly01.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def show_py_code(fn):\n",
    "    from pygments.lexers import Python3Lexer\n",
    "    from IPython.display import display_html\n",
    "    with open(fn, \"r\") as f:\n",
    "        display_html(highlight(f.read(), Python3Lexer(), HtmlFormatter(noclasses=True)), raw=True)\n",
    "        \n",
    "show_py_code(\"plotlywidget.py\")"
   ]
  }
 ],
 "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.5.1"
  },
  "toc": {
   "toc_cell": false,
   "toc_number_sections": true,
   "toc_threshold": 4,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}