nbrmd 0.2.5

Jupyter from/to R markdown notebooks

From Jupyter notebooks to R markdown, and back

This is a utility that allows to open and run R markdown notebooks in Jupyter, and save Jupyter notebooks as R markdown.

You will be interested in this if

• you want to version your notebooks and occasionally have to merge versions
• you want to use RStudio's advanced rendering of notebooks to PDF, HTML or HTML slides
• or, you have a collection of markdown or R markdown notebooks and you want to open them in Jupyter

What is R markdown?

R markdown (extension .Rmd) is a well established markdown notebook format. As the name states, R markdown was designed in the R community, but it actually support many languages. A few months back, the support for python significantly improved with the arrival of the reticulate package.

R markdown is almost identical to markdown export of Jupyter notebooks. For reference, Jupyter notebooks are exported to markdown using either

• Download as Markdown (.md) in Jupyter's interface,
• or nbconvert notebook.ipynb --to markdown.

Major difference is that code chunks can be evaluated. While markdown's standard syntax start a python code paragraph with

```python

R markdown starts an active code chunks with

```{python}

A smaller difference is the common presence of a YAML header, that describes the notebook title, author, and desired output (HTML, slides, PDF...).

Look at nbrmd/tests/ioslides.Rmd for a sample R markdown file (that, actually, only includes python cells).

How do I open R markdown notebooks in Jupyter?

The nbrmd package offers a ContentsManager for Jupyter that recognizes .md and .Rmd files as notebooks. To use it,

• generate a jupyter config, if you don't have one yet, with jupyter notebook --generate-config
• edit the config and include this:

c.NotebookApp.contents_manager_class = 'nbrmd.RmdFileContentsManager'

Then, make sure you have the nbrmd package installed, and re-start jupyter, i.e. run

pip install nbrmd
jupyter notebook

Now you can open your .md and .Rmd files as notebooks in Jupyter, and save your jupyter notebooks in R markdown format.

Rmd notebook in jupyter	Rmd notebook as text

When a file with an identical name and a .ipynb extension is found, nbrmd loads the outputs from that file. This way, you can put the .Rmd file under version control, and preserve the outputs that match unchanged inputs.

Can I save my Jupyter notebook as both R markdown and ipynb?

Yes. That's useful if you want to preserve the outputs locally, or if you want to share the .ipynb version. We offer both per-notebook, and global configuration.

Per-notebook configuration

The R markdown content manager includes a pre-save hook that will keep up-to date versions of your notebook under the file extensions specified in the nbrmd_formats metadata. Edit the notebook metadata in Jupyter and append a list for the desired format, like this:

{
  "kernelspec": {
    "name": "python3",
    (...)
  },
  "language_info": {
    (...)
  },
  "nbrmd_formats": [".ipynb", ".Rmd"]
}

Accepted formats are: .ipynb, .Rmd and .md.

Global configuration

If you want every notebook to be saved as both .Rmd and .ipynb files, then change your jupyter config to

c.NotebookApp.contents_manager_class = 'nbrmd.RmdFileContentsManager'
c.ContentsManager.pre_save_hook = 'nbrmd.update_rmd_and_ipynb'

If you prefer to update just one of .Rmd or .ipynb files, then change the above to nbrmd.update_rmd or nbrmd.update_ipynb as the pre_save_hook (and yes, you're free to use the pre_save_hook with the default ContentsManager).

:warning: Be careful not to open twice a notebook with two distinct extensions! You should shutdown the notebooks with the extension you are not currently editing (list your open notebooks with the running tab in Jupyter).

Recommendations for version control

I recommend that you only add the R markdown file to version control. When you integrate a change on that file that was not done through your Jupyter editor, you should be careful to re-open the .Rmd file, not the .ipynb one. As mentionned above, outputs that corresponds to unchanged inputs will be loaded from the .ipynb file.

How do I use the converter?

The package also provides a nbrmd script that converts Jupyter notebooks to R markdown notebooks, and vice-versa.

Use it as:

nbrmd jupyter.ipynb         # this prints the Rmarkdown alternative
nbrmd jupyter.ipynb -i      # this creates a jupyter.Rmd file
nbrmd jupyter.Rmd   -i      # and this, a jupyter.ipynb file
nbrmd jupyter.Rmd   -i -p   # update the jupyter.ipynb file and preserve outputs that correspond to unchanged inputs

Alternatively, the nbrmd package provides a nbconvert rmarkdown exporter that you can use with

nbconvert jupyter.ipynb --to rmarkdown

And if I convert twice?

Round trip conversion of R markdown is identity.
Round trip conversion of Jupyter notebooks preserves the source, not outputs.