bokeh and Emacs org-mode

I am using

1. bokeh 0.12.10
2. org 9.1.2
3. emacs 25.3.50.2
4. ob-ipython @ 1642a74

I define a function export_bokeh to do the actual heavy lifting. This function could be moved to your ipython startup.py file so that it is defined for every ipython session.

def export_bokeh(plot, outPNG, outJS, outHTML, bkjs='inline'):
    from bokeh.io import export_png
    from bokeh.embed import autoload_static, file_html
    import bokeh.resources

    if bkjs is 'local':
        # use local installed bokeh scripts
        wherebokeh = bokeh.resources.Resources(mode='absolute')

    if bkjs is 'remote' or bkjs is 'CDN':
        # use CDN bokeh scripts
        wherebokeh = bokeh.resources.CDN

    if bkjs is 'relative':
        # bkjs is a relative path to the locally installed bokeh files
        wherebokeh = bokeh.resources.Resources(mode='relative', root_dir='./')

    if bkjs is 'inline':
        wherebokeh = bokeh.resources.INLINE

    # save the png file
    export_png(plot, filename=outPNG)

    # save the html file
    html = file_html(plot, wherebokeh, None)
    with open(outHTML, 'w') as file:
        file.write(html)

    js, script = autoload_static(plot, wherebokeh, outJS)

    # save the .js file
    with open(outJS, "w") as writer:
        writer.write(js)

    # embed in the org-exported HTML file
    print('''#+BEGIN_EXPORT html\n{script}\n#+END_EXPORT'''.format(script=script.lstrip()))

Embedding the figure is then quite easy once you

1. tell ob-ipython to capture stdout and put it in a drawer so that it’s replaced everytime to rerun the source block.
2. provide a custom filename for export (fname below).

I use this header line:

#+BEGIN_SRC ipython :session :results output drawer :exports both :var fname="my-image" :var titlestr="Demonstrating bokeh"

This will export a png image, an HTML file and a Javascript file. That way there are both static and dynamic versions that are easy to share as well as an emebeddable version.

from bokeh.plotting import figure
from bokeh.layouts import gridplot
from bokeh.models import ColumnDataSource, HoverTool, WheelZoomTool

tools='box_select, reset'

# create "subplots"
p1 = figure(tools=tools)
p1.background_fill_alpha = 0.0
p1.border_fill_alpha = 0.0

p2 = figure(tools=tools, x_range=p1.x_range, y_range=p1.y_range)
p2.background_fill_alpha = 0.0
p2.border_fill_alpha = 0.0

# generate data
x = np.random.randn(200)
y0 = x**3 - 100
y1 = x**2 - 100

# generate random letters
import string
import random
label = [random.choice(string.ascii_letters) for aa in range(200)]

# needed for linked selection
source = ColumnDataSource(data={'x': x, 'y0': y0, 'y1': y1,
                                'label': label})

# plot the data
p1.circle('x', 'y0', source=source)
p2.scatter('x', 'y1', source=source)

p1.title.text = titlestr

wheel = WheelZoomTool()
# add some tooltips
hover = HoverTool()
hover.tooltips = [
    ("(x,y)", "($x, $y)"),  # '$' for co-ordinates
    ("label", "@label")  # note '@' for column lookup
]
p1.add_tools(hover, wheel)
p2.add_tools(hover, wheel)

p1.toolbar.active_scroll = wheel
p2.toolbar.active_scroll = wheel

# layout the subplots
pg = gridplot([[p1, p2]], plot_width=400, plot_height=400)

export_bokeh(pg,
             '../static/'+fname+'.png',
             '../static/js/'+fname+'.js',
             '../static/html/'+fname+'.html')

The above figure is a rendering of the RESULTS block:

#+RESULTS:
:RESULTS:
#+BEGIN_EXPORT html
<script
    src="../static/js/my-image.js"
    id="f1c145ed-260c-411c-8c26-f71b52427218"
    data-bokeh-model-id="5f0145de-1c4e-4ee2-9a64-f38f255c81ff"
    data-bokeh-doc-id="20261111-dbef-4dd0-b40c-d8c04db088bd"
></script>
#+END_EXPORT
:END:

Things I would like:

• Automatically run the HTML export when running the code block.
  • Can I add-hook to org-babel-execute-maybe?
• The ability to auto-hide the javascript in the RESULTS drawer but show the exported png file.
  • Ideally, I would see the png in the org file and the javascript in the HTML file. The other should be hidden. Seems too complicated.
  • A nice solution would be to insert a link to the png file in the image caption.
• Are actual captions (#+CAPTION) possible with bokeh figures?
• Avoid the explicit export_bokeh call if possible.
  • Ideally, ob-ipython would be able to tell that this is a bokeh block; use the fname var to pass the figure handle p and fname to export_bokeh and do everything. This would be close to jupyter notebook workflow.
  • This might be possible using IPython formatters as suggested by the ob-ipython README.
    • Could we then define export_bokeh in imports.py and call that when the returned object is a bokeh figure handle?
• Can we get holoviews to work with this? Optionally tell it to use either matplotlib or bokeh backends

A simplified version of the one on ob-ipython. This autogenerates a random filename.

#+BEGIN_SRC ipython :session :results output drawer :exports both :var fname=${1:`(make-temp-name "img")`}
from bokeh.plotting import figure
from bokeh.layouts import gridplot
from bokeh.models import ColumnDataSource, HoverTool, WheelZoomTool

tools='box_select, reset'

# create "subplots"
hf = figure(tools=tools)
hf.background_fill_alpha = 0.0
hf.border_fill_alpha = 0.0

hf.$0

export_bokeh(hf, 'images/'+fname+'.png', 'images/js/'+fname+'.js', bkjs='inline')
#+END_SRC

Looks like exporting to PNG requires

conda install phantomjs selenium

1. Either include a css file or add a style tag to HTML_HEAD at the top of your org file.

      HTML_HEAD: <style> add-stuff-here </style>
   

2. Targeting the css class bk-plot-layout lets you center the image. bk-grid-column does it for gridplot

      .bk-plot-layout .bk-grid-column { max-width: 100%; margin: auto;}
   

Here is org-mode source for this page.