Notebooks¶

  • Useful for writing reports about our research
  • Can make PDF, HTML, markdown, or JavaScript output from them
  • Can execute code within the notebook!

Let's add some code!¶

Jupyter stuff is "for" Python by default. (More on that later)

In [1]:
from IPython.display import SVG
import msprime
ts = msprime.simulate(5, random_seed=42, recombination_rate=0.5)
SVG(ts.draw_svg())
Out[1]:
4236701894203567190.000.751.00

Literate programming¶

  • This document is "right" because all the figures, etc., have known provenance (code).
  • You can also have numbers in the document generated via code.

Types of notebooks¶

  • Jupyter (this).
  • RMarkdown, often via R Studio.
  • mdbook, for folks using the rust programming language. Not as mature, but off to a good start.
  • These are all modern takes on earlier efforts such as Sweave, Rweave, etc..

You can write math.¶

In markdown, you use $\LaTeX$ notation to write math. Display math is in double dollar signs. For example, $$e=mc^2.$$

Limitations of Jupyter¶

  • Hard (impossible?) to mix > 1 language in same notebook.
  • Browser interface makes it hard to do remote work. Need annoying SSH tunneling tricks to get this to work. You can find them on my website.
  • Hard to write long documents--books, etc..
  • The notebook file is a binary "blob", and therefore very github/git-unfriendly. There are workarounds (you can Google for them), but they are imperfect/a bit hack-ish.
  • The notebook files get pretty big.

RMarkdown¶

  • Plain text! Therefore git-friendly. (Smaller, too.)
  • Can run multiple languages in the same document.
  • More "ergonomic". You do not have to write them in RStudio. I write my documents in neovim using pandoc plugins. (Some others are required, too--ask me if you vim.)
  • More document flavors are supported. Books are possible via bookdown, which is an R package. My lab site has several template repos.
  • Can be used as a template for auto-generated reports b/c plain text.

Recommendations¶

  • Use RMarkdown most of the time. Even Python users!!
  • Jupyter works great, too, but is not very git/github compatible.

Converting Jupyter notebooks to other formats.¶

Use nbconvert. For example:

jupyter nbconvert --to slides NotebookSlides.ipynb