Jupyter UI wrangling

1 Presentations using Jupyter

$ jupyter nbconvert --to slides some_notebook.ipynb  --post serve

jupyter nbconvert Presentation.ipynb  \
    --to slides --reveal-prefix ../../reveal.js \
    --post serve --SlidesExporter.reveal_theme=league

pip install hide_code
jupyter nbextension install --py hide_code
jupyter nbextension enable --py hide_code
jupyter serverextension enable --py hide_code

conda install -c conda-forge hide_code

2 Rich display

Various objects support rich display of Python objects, e.g., IPython.display.Image

from IPython.display import Image
Image(filename='img/test.png')

or you can use markdown for local image display

![title](img/test.png)

If you want to make your own objects display, uh, richly, you can implement the appropriate magical methods:

class Shout(object):
    def __init__(self, text):
        self.text = text

    def _repr_html_(self):
        return "<h1>" + self.text + "</h1>"

I leveraged this to make a LaTeX renderer called latex_fragment which you should totally check out for rendering inline algorithms or for emitting SVG equations.

Alternatively, one can use the inbuilt Jupyter LaTeX renderer:

#%%
from IPython.display import Latex
Latex('''The mass-energy equivalence is described by the famous equation

$$E=mc^2$$

discovered in 1905 by Albert Einstein.
In natural units ($c$ = 1), the formula expresses the identity

\\begin{equation}
E=m
\\end{equation}''')

3 Graphs

Set up inline plots:

%matplotlib inline

inline SVG:

%config InlineBackend.figure_format = 'svg'

Graph sizes are controlled by matplotlib. Here’s how to make big graphs:

import matplotlib as mpl
mpl.rcParams['figure.figsize'] = (10.0, 8.0)

Interesting-looking other graphing options:

• asymptote vector plotting plugin
• Graphviz renders in Jupyter.

Jupyter lab includes such nifty features as a diagram editor which you can install using jupyter labextension install jupyterlab-drawio

4 Citations and other academic writing in Jupyter

I did this for

1. my blog — using simple Zotero markdown citation export, which is not great for inline citations but fine for bibliographies, and easy and robust.

2. my papers — abandoning Jupyter in favour of Pweave+pandoc, which works amazingly for everything if you use pandoc tricks for your citations.

I couldn’t find a unified approach for these two different use cases which didn’t sound like more work than it was worth. At least, many academics seem to have way more tedious and error-prone workflows than this, so I’m just being a fancypants if I try to tweak it further.

More recently, there has appeared jupyterbook which enables notebook-based blog rendering, including citations. This is built using the ruby site generator jekyll-scholar so is heavy in dependencies but it seems to work. A hyped example of this in action is You Only Write Thrice.

Chris Sewell has produced a script called ipypublish that eases some pain points in producing articles. It’s an impressive piece of work.

My own latex_fragment allows you to insert one-off LaTeX fragments into Jupyter and Pweave (e.g. algorithmic environments or some weird TikZ thing.)

Jean-François Bercher’s jupyter_latex_envs reimplements various LaTeX markup as native Jupyter including \cite.

Sylvain Deville recommends treating Jupyter as a glorified markdown editor and then using pandoc, which is an OK workflow if you are producing a once-off paper, but not for a repeatedly updated blog.

nbconvert has built-in citation support but only for LaTeX output. Citations look like this in markup:

<cite data-cite="granger2013">(Granger, 2013)</cite>

or even

<strong data-cite="granger2013">(Granger, 2013)</strong>

The template defines the bibliography source and looks like:

((*- extends 'article.tplx' -*))

((* block bibliography *))j
((( super () )))
\bibliographystyle{unsrt}
\bibliography{refs}
((* endblock bibliography *))

And building looks like:

jupyter nbconvert --to latex --template=print.tplx mynotebook.ipynb

As above, it helps to know how the document templates work.

Note that even in the best case you don’t have access to BibTeX-style citation, so auto-year citation styles will look funky.

Speaking of custom templates, the nbconvert setup is customisable for more than LaTeX.

{% extends 'full.tpl'%}
{% block any_cell %}
    <div style="border:thin solid red">
        {{ super() }}
    </div>
{% endblock any_cell %}

But how about for online? cite2c seems to do this by live inserting citations from Zotero, including author-year stuff. (Requires Jupyter notebook 4.2 or better which might require a pip install --upgrade notebook)

Julius Schulz gives a comprehensive config for this and everything else.

This workflow is smooth for directed citing, but note that there is no way to include a bibliography except by citation, so you have to namecheck every article; and the citation keys it uses are Zotero citation keys which are nothing like your BibTeX keys so can’t really be manually edited.

If you are customising the output of Jupyter’s nbconvert, you should be aware that the {% block output_prompt %} override doesn’t actually do anything in the templates I use. (Slides, HTML, LaTeX). Instead, you need to use a config option:

$ jupyter nbconvert --to slides some_notebook.ipynb \
   --TemplateExporter.exclude_output_prompt=True \
    --post serve

I had to use the source to discover this.

ipyBibtex.ipynb? Looks like this:

%%cite
Lorem ipsum dolor sit amet
__\citep{hansen1982,crealkoopmanlucas2013}__,
consectetuer adipiscing elit,
sed diam nonummy nibh euismod tincidunt
ut laoreet dolore magna aliquam erat volutpat.

So it supports author-year citations! But it’s a small, unmaintained package so is risky.

🏗 Work out how Mark Masden got citations working?

5 Interacting

Jupyter allows interactions! For certain special cases with backing by a major firm or dev team such as dashboards, this can be an easy way of interacting with Python.

In the general case, not so much. For a while, I thought building widgets in Jupyter might be a useful or convenient thing to do, but many days of effort later I must conclude that not only were my early experiments not convenient, but also that the API changes are so frequent that it would need to be effortless to be viable to maintain a UI in an ongoing way. These days, I regard using Jupyter for interactions as a way of adding extra failure points to an app which would be better without Jupyter.

from IPython.display import clear_output
## Run code

for i in range(10):
    clear_output(True)
    plt.plot(x, y)
    plt.show()

pip install ipywidgets
jupyter nbextension enable --py widgetsnbextension

from ipywidgets import widget
widget.Widget.widget_types

from ipywidgets import interact, IntSlider

pip install pixiedust
jupyter pixiedust install

from zmq.eventloop import ioloop
ioloop.install()