{
 "metadata": {
  "name": "",
  "signature": "sha256:6023dd53d77901bc3cf149fca6da68595b6a6424645d97927bc743a69fcf5189"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Welcome to the Bokeh magic extension tour!"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The Bokeh magic extension for the IPython notebook simplifies some common tasks and offers some different operating modes for using Bokeh. \n",
      "\n",
      "First, you need to load the extension!\n",
      "\n",
      "**Note**: This extension is fully featured if you are using IPython 2.0 or above, thanks to a new callback system. The functionality is somewhat limited in IPython 1.x: you can not use the `--figure` mode, and the `--hold` mode can not be disabled without restarting the kernel."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import bokeh.bokeh_magic"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Executing this import will enable %bokeh magic, and if necessar, will take care of the installation step too...\n",
      "\n",
      "**Note**: You can also install the extension and load it in the *canonical* IPython-way:\n",
      "\n",
      "`%install_ext https://raw.github.com/ContinuumIO/bokeh/master/extensions/bokeh_magic.py`\n",
      "\n",
      "`%load_ext bokeh_magic`\n",
      "\n",
      "However, we suggest you just call `import bokeh.bokeh_magic` at the top of your notebooks, and you will always be ready to go.\n",
      "\n",
      "Now, we need to activate the Bokeh notebook environment, you can easily do it just calling the --notebook argument of the bokeh magic:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%bokeh --notebook"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Every Bokeh magic argument has shortcuts, so you can use `%bokeh -n` for the previous case too.\n",
      "\n",
      "**Note**: This magic command is equivalent to `output_notebook()`.\n",
      "\n",
      "You can always do `%bokeh?` to see some information about the basic magic functionality.\n",
      "\n",
      "After configuring the environment you have essentially three modes: \n",
      "\n",
      "* `--show`\n",
      "* `--hold`\n",
      "* `--figure`\n",
      "\n",
      "Let's begin with the `--show` mode. This mode add a call to the Bokeh show function after each cell, so you do not have to be aware to call this function to show your plots."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%bokeh --show"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Now the `--show` mode is enable, but you can disable at any time just doing:\n",
      "\n",
      "`%bokeh --show-off`\n",
      "\n",
      "The same goes for the other modes, you can disable them just doing:\n",
      "\n",
      "`%bokeh --hold-off`\n",
      "\n",
      "`%bokeh --figure-off`\n",
      "\n",
      "**Note**: You can call the magic with several arguments in just one line, ie:\n",
      "\n",
      "`%bokeh --show --hold --figure`\n",
      "\n",
      "Now, time to make some plots. We will plot two scatterplots of sine curves."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import numpy as np\n",
      "from bokeh.plotting import scatter\n",
      "\n",
      "N = 100\n",
      "\n",
      "x = np.linspace(0, 4*np.pi, N)\n",
      "y = np.sin(x)\n",
      "\n",
      "scatter(x, y, \n",
      "    color=\"black\",tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"sin(x)\"\n",
      ")\n",
      "scatter(x, 2*y, \n",
      "    color=\"orange\", tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"2*sin(x)\"\n",
      ")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# we will disable the `--show` mode to avoid the render of the last plot in the next code cell\n",
      "%bokeh --show-off"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You probably have noticed that we only have one sine curce and this is the expected behaviour. If we want to see both curves on one plot, we have to activate the `--hold` mode:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%bokeh --hold"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "scatter(x, y, \n",
      "    color=\"black\",tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"sin(x)\"\n",
      ")\n",
      "scatter(x, 2*y, \n",
      "    color=\"orange\", tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"2*sin(x)\"\n",
      ")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%bokeh --show"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "We can also add more sines curves into the plot:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "scatter(x, 3*y, \n",
      "    color=\"green\", tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"3*sin(x)\"\n",
      ")\n",
      "scatter(x, 4*y, \n",
      "    color=\"blue\", tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"4*sin(x)\"\n",
      ")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# we will disable the `--show` mode to avoid the render of the last plot in the next code cell\n",
      "%bokeh --show-off"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "And now, we can introduce the `--figure` mode, which implicitly adds a call to the Bokeh `figure` function at the beginning of each cell:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%bokeh --figure"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%bokeh --show"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "scatter(x, y, \n",
      "    color=\"black\",tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"sin(x)\"\n",
      ")\n",
      "scatter(x, 2*y, \n",
      "    color=\"orange\", tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"2*sin(x)\"\n",
      ")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "But now, because figure is activated, if we added two more sines waves:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "scatter(x, 3*y, \n",
      "    color=\"green\", tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"3*sin(x)\"\n",
      ")\n",
      "scatter(x, 4*y, \n",
      "    color=\"blue\", tools=\"pan,wheel_zoom,box_zoom,reset,previewsave\", \n",
      "    legend=\"4*sin(x)\"\n",
      ")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Only the two last sine curves will be displayed because we now have a new *figure*.\n",
      "\n",
      "OK, this notebook is just a short introduction, so play with %bokeh magic and have fun!\n",
      "\n",
      "The Bokeh team."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}