Jupyter from/to R markdown notebooks
Project description
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.