nbrmd 0.4.6

Jupyter from/to R markdown notebooks

Jupyter notebooks from/to R markdown

This package is an implementation of the standard R markdown notebook format for Jupyter. R markdown notebooks are source only notebooks, and they are great companion files for the standard .ipynb notebooks.

Use the nbrmd package if

• you prefer to have simple text files under version control
• if 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.

Only the source of your notebook is represented in R markdown. When a pair of .Rmd, .ipynb notebooks with identical names are opened in Jupyter, inputs are taken from the .Rmd file, and outputs, when they match the input, are taken from the .ipynb file. This allows you to edit the R markdown version in your favorite text editor, and reload the notebook in Jupyter with the convenience of preserving outputs when possible.

Can I have a demo?

Sure. Try our package on binder and open our python-oriented R markdown notebook! As you will see there, the package also offers opening and saving notebooks as python or R scripts. Go to nbsrc for a specific documentation on this.

How does R markdown look like?

Rmd notebook in jupyter	Rmd notebook as text

Have you tested round-trip conversion?

Round trip conversion is safe! And backed by hundreds of tests.

• R markdown to Jupyter notebook, to R markdown again is identity. If you associate a Jupyter kernel to your notebook, that information will go to the yaml header of your notebook.
• Jupyter to R markdown, and Jupyter again preserves source and metadata. In some occasions (consecutive blank lines in markdown cells), cells may be splitted into smaller ones.

How do I activate 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 the below:

c.NotebookApp.contents_manager_class = 'nbrmd.RmdFileContentsManager'
c.ContentsManager.default_nbrmd_formats = 'ipynb,Rmd'

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

pip install nbrmd --upgrade
jupyter notebook

With the above configuration, every Jupyter notebook will have a companion .Rmd notebook. And every .Rmd notebook will have a companion .ipynb notebook.

If you prefer the .ipynb notebook not to be created by Jupyter when a .Rmd notebook is edited, set

c.ContentsManager.default_nbrmd_formats = ''

(as the default value is ipynb). Outputs for R markdown notebooks, however, will not be saved any more.

Per notebook configuration

If you prefer that the companion R markdown notebook be generated only for selected notebooks, remove the c.ContentsManager.default_nbrmd_formats line from Jupyter's configuration, and instead edit the notebook metadata as follows:

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

Accepted formats are: ipynb, Rmd, py and R.

In case you want both py and Rmd, please note that the order matters: the first non-ipynb extension is the one used as the reference source for notebook inputs when you open the ipynb file.

Command line conversion

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