lecy / rmd-to-jupyter

This project provides an easy R function for translating R Markdown (.rmd) files to Jupyter Notebook (.ipynb) files.

RMD to Jupyter - R Helper Function

This project provides a convenient R function for translating R Markdown (.rmd) files to Jupyter Notebook (.ipynb) files.

The major advantage to using notebook instead of markdown files is the ability to post them on GitHub, where the code is automatically compiled and rendered so that the users can view the full output instead of just the formatted code. For example, here is an R Markdown and a Jypyter notebook file for comparison:

• Example R Markdown
• Example Jupyter Notebook

Notebooks are also a convenient format for collaboration and transparent, reproducible research.

A recent R Revolutions blog explains more details.

One solution to converting files between RMD and IPYNB has been proposed using the ipyrmd script.

Below we present a simple helper function for R to call the Jupyter program and notedown from within the R environment in order to make the conversion easier for R programmers.

Setup

Here are some basic instructions to guide you through the installation of necessary software in order to convert markdown files to notebooks. Windows and Ubuntu scenarios are covered (mac users, you are on your own).

Windows

Running this program requires that you have R, Python, and Jupyter installed you your machine.

1. First install R

2. You need to install the knitr package. From R, type:

   install.packages('knitr', dependencies = TRUE)
   

3. You need to add R_USER to your system profile path. In Windows, look under Control Panel > Advanced System Settings > Environmental Variables > path.

   You will add the path for your R bin folder to this setting. For example, change:

   C:\Program Files\Intel\WiFi\bin\;C:\Program Files\Common Files\Intel\WirelessCommon\

   to:

   C:\R\R-3.2.2\bin;C:\Program Files\Intel\WiFi\bin\;C:\Program Files\Common Files\Intel\WirelessCommon\

   View a screenshot

4. We now need to install Python and the proper Python libraries. To start, you will need to decide which version of Python to install:

   http://jupyter.readthedocs.org/en/latest/install.html

5. Next you need to install the libraries. For pandas from a command prompt try:

   pip install pandas

   You may have trouble with the num

   download binaries here and then try:

   pip install filename.whl

   where filename.whl is replaced with the proper file name from the download above. Then try:

   pip install pandas

6. Next we need to install notedown and other depencies. Using a command prompt:

   pip install notedown 
   pip install pandas 
   pip install ipython[all] 
   pip install ipykernel 
   ipython kernel install 
   

7. To install rpy2 try:

   pip install rpy2

   or download binaries and then try:

   pip install filename.whl

   where filename.whl is replaced with the proper file name from the download above.

Ubuntu

First install pip

sudo apt-get install python3-setuptools

Then install notedown

sudo pip3 install notedown

You need to install R and knitr. Go to https://cran.r-project.org/mirrors.html and choose your mirror. Then click "Download for Linux", after that click "Ubuntu". Then add line to file /etc/apt/sources.list

deb https://<my.favorite.cran.mirror>/bin/linux/ubuntu wily/

Where wily is your Ubuntu version. After that to install R write

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E084DAB9
sudo apt-get update
sudo apt-get install r-base

For install knitr use command on R

install.packages('knitr', dependencies = TRUE)

Now install all depencies.

sudo pip3 install jupyter_client
sudo pip3 install ipykernel
sudo ipython3 kernel install
sudo pip3 install rpy2

Script for R

In order to convert an R Markdown file into a Jupyter Notebook, you can type the following into a command prompt window:

notedown path/example.Rmd  --rmagic --run > path/example.ipynb

where path/ would be replaced with the proper parameters, such as:

notedown C:/Users/YourMom/Documents/example.Rmd  --rmagic --run > C:/Users/YourMom/Documents/example.ipynb

The command will create a new .ipynb file within the specified directory, ready to post on GitHub or share with colleagues.

The following R script is a helper function so this can be implemented from within R.

library(tools)

rmd2jupyter <- function( filename, path=getwd() ) 
{
  path_in <- paste( path, "/", filename, " ", sep="" )
  path_out <- paste(path, "/", file_path_sans_ext(filename), ".ipynb", sep="")
  full_shell <- paste("notedown ", path_in, " --rmagic --run > ", path_out, sep="")
  system(full_shell)
}

# download the example.Rmd file from this repository
# setwd(...) to where the example.Rmd file is located

rmd2jupyter( "example.Rmd" )

Suggestions

Jupyter notebooks provide an interesting way to share interactive R code and output. If you have suggestions for good resources, methods, or scripts to make this process easier please send them (or submit a pull request) and I will add them to this page.

The example code was provided by Ramnath Vaidyanathan

Thanks to Mikhail Mityaev for an initial version of the R script.

rmd-to-jupyter's Issues

Knit replacement function

While I'm admittedly not a fan of ipython/jupyter notbooks, having the ability to generate one from an R markdown file can only be A Very Good Thing for enabling data science folks to work together.

To that end, I added the following function to my markdowntemplates package (which is not on CRAN):

#' "knit" replacement to generate an ipynb with notedown
#'
#' @export
to_jupyter <- function(inputFile, encoding) {

  output_file <-  sprintf("%s.%s", tools::file_path_sans_ext(inputFile), "ipynb")

  tf <- tempfile(fileext=".Rmd")

  tmp <- readLines(inputFile)
  yaml_end <- which(grepl("^---", tmp))[2]
  writeLines(tmp[(yaml_end+1):length(tmp)], tf)

  system2("notedown", args=c(tf, "--rmagic", "--run"), stdout=output_file)

  unlink(tf)

  output_file

}

With that, you can then have this:

---
title: "ggplot2 example"
knit: (markdowntemplates::to_jupyter)
---

## Introduction to ggplot2

This is a short demo on how to convert an R Markdown Notebook into an IPython Notebook using knitr and notedown.

Adding a Python Chunk

```{r engine="python"}
def f(x):
  return x + 2
f(2)
```

This is an introduction to [ggplot2](http://github.com/hadley/ggplot2). You can view the source as an R Markdown document, if you are using an IDE like RStudio, or as an IPython notebook, thanks to [notedown](https://github.com/aaren/notedown).

We need to first make sure that we have `ggplot2` and its dependencies installed, using the `install.packages` function.

Now that we have it installed, we can get started by loading it into our workspace

```{r}
library(ggplot2)
```
... (moar R markdown code)

in an RStudio editor, use the "Knit" keystroke command or hit the "Knit" button and it will call that function (and and not call knitr's render()) and (since I did this in a hurry) output the filename of the rendered ipynb to the R console (you can make it do anything, like open it in a browser).

I also replaced shell(…) with system2(…) as it's cross-platform that way.

The code is totally yours to do with as you like. If you have suggestions for how the rendered ipynb shld be displayed afterwards or what messages you think would be useful during processing, just let me know.

license?

This looks potentially useful, but without an open source license included I will need to look elsewhere for this functionality.

R_USER not defined

Hi there,

I installed everything as indicated, and set up an environment/path to R, yet when running the script I receive a R_USER not defined - any chance of having a ready made fix for this? (Win 7, python 3.7, R3.6)

thx
cyril

+ comparison to notedown in README

I'm curious how this tool compares with the seemingly similar notedown package.
I'm just scratching the surface, but both appear to share goals.
I think a section in the readme discussing pros/cons of this package against the more popular alternative would be beneficial for newbies to this like me.