A Rmarkdown to SoS Notebook converter
Project description
sos-rmarkdown
The RMarkdown format is a markdown format with embedded R expressions and code blocks, and is extremely popular for R users. The sos-rmarkdown
module provides converters to convert Rmarkdown files to SoS notebooks using the sos
converter mechanism.
Installation
You can install sos-rmarkdown
and related tools (sos-notebook
, papermill
, sos-papermill
etc) with command
pip install sos-rmarkdown
or
conda -c conda-forge sos-rmarkdown
if you are using a conda environment.
Basic Usage
You can convert a Rmd file with command
sos convert input.Rmd output.ipynb
and optionally execute the resulting notebook with option --execute
sos convert input.Rmd output.ipynb --execute
If you would like to further convert the Jupyter notebooks to HTML format, you can use commands
sos convert output.ipynb output.html --template sos-report-toc-v2
You can combine the two steps with commands such as
sos convert input.rmd output.html --execute --template sos-report-toc-v2
Features
Although there are already a number of Rmd to Jupyter converters (e.g. notedown, RMD-to-Jupyter (uses rpy2)), they lack support for some of the Rmakdown features due to limitations of the Jupyter notebook platform. Fortunately, SoS Notebook, especially its Jupyter Lab extension addresses most of the limitations and offers an almost perfect conversion from R markdown to Jupyter notebook.
The first Rmarkdown feature that is difficult to convert is its inline expressions, which are R expressions embedded in markdown texts. Jupyter cannot handle embedded expressions in its markdown cells because markdown cells are handled in its frontend and does not interact with the computing kernel. SoS Notebook addresses this problem with the use of a markdown kernel, which is essentially a markdown kernel
For example, the following Rmarkdown text
I counted `r sum(c(1,2,3))` blue cars on the highway.
is converted to a markdown cell that is evaluated in a R kernel as follows
The second Rmarkdown feature is its support for multiple languages, which allows it to have code blocks in a number of langauges. A Jupyter notebook with an ir
kernel can only evaluate R scripts, but a SoS Notebook is able to include multiple kernels in one notebook.
For example, code blocks such as
def f(x):
return x + 2
f(2)
and
def f(x):
return x + 2
f(2)
are converted to cells with approprivate kernels such as
in a separate Python3
kernel.
The last feature that is not properly supported are options such as echo=FALSE
and include=FALSE
for Rmarkdown code blocks. There were no corresponding features for classic Jupyter Notebook but Jupyter Lab supports hiding of input and/or output of cells. Using these features, code blocks such as the following are converted as collapsed input and/or outputs,
arr <- rnorm(5)
cat(arr)
A related problem is that jupyter nbconvert
does not respect the collasping status of cells and renders input and output of all cells. SoS Notebook addresses this problem by providing templates that honor the show/hide status of cells. For example, template sos-report-toc-v2
outputs all cells but hides collapsed inputs and outputs by default. The hidden content could be displayed by selecting a dropdown box to the top right corner of the document.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sos_rmarkdown-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | be93703cfcd64d3b30ba4591b091f712afca9d2ab6952f901f69d6d5eb67d334 |
|
MD5 | c44e4573db5d88ceadf8493fb44cd4fd |
|
BLAKE2b-256 | 52d4980c57f08d5814eb0cacb9de91198ae56c55cedf8bd4b4030cd973a2b3c9 |