nbrmd 0.4.0

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

Note that if you prefer to save notebooks as python scripts, this is also possible. In that case, have a look at the nbsrc package.

What is R markdown?

R markdown (extension .Rmd) is a source only format for notebooks. As the name states, R markdown was designed in the R community, and is the reference notebook format there. The format actually supports [many languages](https://yihui .name/knitr/demo/engines/).

R markdown is almost like plain markdown. There are only two differences:

• R markdown has a specific syntax for active code cells: language, and optional cell options are enclosed into a pair of curly brackets:

  ```{python}
  
  

• 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).

Why R markdown and not filtered .ipynb under version control?

The common practice for having Jupyter notebooks under version control is to remove outputs with a pre-commit hook. That works well and this will indeed get you a clean commit history.

However, you may run into trouble when you try to merge two .ipynb notebooks in a simple text editor. Merging text notebooks, like the .Rmd ones that this package provides, is much simpler.

How do I open R markdown notebooks in Jupyter?

The nbrmd package offers a ContentsManager for Jupyter that recognizes .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 .Rmd files as notebooks in Jupyter, and save your jupyter notebooks in R markdown format (see below).

Rmd notebook in jupyter	Rmd notebook as text

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

Yes. That's even the recommended setting for the notebooks you want to set under version control.

You need to choose whever to configure this per notebook, or globally.

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 select the desired formats, like this:

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

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.default_nbrmd_formats = 'ipynb,Rmd'

If you prefer to update just .Rmd, change the above accordingly (you will still be able to open regular .ipynb notebooks).

Recommendations for version control

I recommend that you set nbrmd_formats to "ipynb,Rmd", either in the default configuration, or in the notebook metadata (see above).

When you save your notebook, two files are generated, with .Rmd and .ipynb extensions. Then, when you reopen either one or the other,

• cell input are taken from the source only format, here .Rmd file
• cell outputs are taken from .ipynb file.

This way, you can set the .Rmd file under version control, and still have the commodity of having cell output stored in the .ipynb file. When the .Rmd file is updated outside of Jupyter, then you simply reload the notebook, and benefit of the updates.

: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).

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.