Jupyter Notebooks are a popular format for data science and reproducible research. This article provides a guide to how to write, and collaborate on, a reproducible research article using Jupyter Notebooks and Stencila.
There are many resources available for how to use Jupyter Notebooks for reproducible research including:
If you are getting started with Jupyter Notebook please consult these and other resources. In the rest of this document, we are only going to cover the slightly more advanced topics of how to turn your notebook into a properly structured executable research article suitable for publication.
Most Jupyter notebooks have two types of cells: Markdown cells and code cells. Markdown cells are for static content that is not generated from code (e.g. narrative prose, tables, static images). There are a few extensions to Markdown that you can use make you document more structured and suitable for publication.
Markdown does not have good support for table or figure labels and captions. Often authors will just merge the label and the caption togther in a bolded paragraph. For more structured captions, having a title and paragraph as is often found in academic journals, we suggest that you use a
table block to wrap your image or Markdown table. e.g.
These will be converted by Stencila to the correct structures for publication in other formats such as JATS XML and HTML.
As with static figures and tables, Stencila also supports more structured labels and captions for dynamic figures and tables generated by code.
To add a label and/or caption to a code cell in a Jupyter Notebook you need to add it to the cell's metadata. To do that, within the notebook interface's menu select View > Cell Toolbar > Edit Metadata:
This should result in the Edit Metadata button showing in the top-right corner of each code cell:
You can then add
id (so that you can link to the figure from elsewhere in the document),
caption properties of the code cell. The
caption property can be Markdown in which case, Stencila will parse into a structured caption. For example, Figure 2 of this executable article: