Jupyter from/to R markdown notebooks
Project description
Jupyter notebooks as R markdown, Python or R scripts
This package offers a representation of Jupyter notebooks as Python scripts, R scripts, or R markdown notebooks.
These alternative representations allow to
- edit notebooks in both Jupyter and your favorite IDE, and refactor them
- extract executable scripts from your notebooks
- get meaningfull diffs for notebooks under version control, and easily merge contributions
- edit the same notebook in both Jupyter and Rstudio, and use RStudio's advanced rendering of notebooks to PDF, HTML or HTML slides.
Scripts and R markdown notebooks only store the source of the notebook, and work in pair with the original .ipynb
file. Jupyter saves notebooks to both the classical .ipynb
form, and to the text-only representation. When a text-only notebook is loaded in Jupyter, inputs are taken there, and outputs are taken from the .ipynb
file, if present.
Can I have a demo?
Sure. Try our package on binder. Notice that every .py
, .R
and .Rmd
file now opens as a Jupyter notebook. I suggest you open the matplotlib demo there: filled_step.py
, run it and save it, close notebook and reopen, to observe persistence of outputs.
The other examples demo how to edit the script and reload the notebook (preserving the kernel variables), and how to edit in Jupyter an interactive ioslide presentation.
How does the Python script look like?
Python notebook in Jupyter | Python script |
---|---|
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! A few hundreds of tests help to guarantee this.
- Script to Jupyter notebook, to script again is identity. If you associate a Jupyter kernel to your notebook, that information will go to a yaml header at the top of your script.
- R markdown to Jupyter notebook, to R markdown again is identity.
- Jupyter to script, and Jupyter again preserves source and metadata.
- Jupyter to R markdown, and Jupyter again preserves source and metadata. In some occasions (consecutive blank lines in markdown cells), markdown cells may be splitted into smaller ones.
How do I activate the companion scripts or R markdown notebooks in Jupyter?
The nbrmd
package offers a ContentsManager
for Jupyter that recognizes
.py
, .R
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 the below:
c.NotebookApp.contents_manager_class = "nbrmd.RmdFileContentsManager"
c.ContentsManager.default_nbrmd_formats = "ipynb,py" # or "ipynb,nb.py" # or "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 .py
(.nb.py
, or .Rmd
) notebook. And every .py
(.nb.py
, or .Rmd
) notebook will have a companion .ipynb
notebook.
Per notebook configuration
If you prefer that the companion 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,py"
}
Accepted formats should have these extensions: 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.
Learn more on the possible values for nbrmd_formats
here.
Command line conversion
The package provides two nbrmd
and nbsrc
scripts that convert Jupyter notebooks to R markdown notebooks and scripts, and vice-versa.
Use them 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
nbsrc jupyter.ipynb # this prints the `.py` or `.R` alternative
nbsrc jupyter.ipynb -i # this creates a jupyter.py or jupyter.R file
nbsrc jupyter.py -i # and this, a jupyter.ipynb file
nbsrc jupyter.py -i -p # update the jupyter.ipynb file and preserve outputs that correspond to unchanged inputs
Alternatively, the nbrmd
package provides a few nbconvert
exporters:
nbconvert jupyter.ipynb --to rmarkdown
nbconvert jupyter.ipynb --to pynotebook
nbconvert jupyter.ipynb --to rnotebook
Usefull cell metadata
- Set
"active": "ipynb,py"
if you want that cell to be active only in the Jupyter notebook, and the Python script representation. Use"active": "ipynb"
if you want that cell to be active only in Jupyter. - Code cells that contain two consecutive blank lines use an explicit end-of-cell marker
"endofcell"
in the script representation. - R markdown's cell options
echo
andinclude
are mapped to the opposite of Jupyter cell metadatahide_input
andhide_output
.
Jupyter magics
Jupyter magics are escaped in the script and R markdown representations so that scripts can actually be executed. Comment a magic with #noescape
on the same line to avoid escaping. Non-standard magics can be escaped with #escape
.
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.