R Notebook for dummies: save and share results easily
Prologue
I have confessed my love for R in my previous posts, so I won’t repeat the same here. It is absolutely the best tool for performing statistical analysis of data, but as it is a programming language, it can do so much more. It may not be as complete or powerful as Python, but people in academia love it for the myriad of packages available, and new ones are being developed daily. R also has a fantastic integrated development environment (IDE) called RStudio. Beginners should definitely take advantage of the user-friendly interface to get used to the language faster, but the IDE is equally useful to advanced users. I have tried other IDEs and code editors, but I always come back to using RStudio. One of the primary reason behind this is R notebook.
Markdown
R Notebook, is essentially, a form of markdown. If you have no idea what markdown is, take a look at the GIF below:
Basically markdown is a way of typesetting documents. In the GIF, you see text being typed in the left pane, while the preview of the final render being shown in the right pane. Markdown is a very easy way to format text with minimal commands, and is much easier to use compared to selecting, clicking and formatting of text in word processors. Markdown also lets you export the document in various formats such as HTML, PDF, EPUB, MS Word etc. To know more about markdown, visit this link; and to know more about the various commands and formatting tools available in markdown, visit this one.
R Notebook
You can write markdown in RStudio — but that’s just not it. RStudio markdown interface — known as R notebook, is a fantastic way of saving and sharing results of data analysis. You type your R code inside the notebook, and running the code displays your results inside the notebook, and finally you can export code and results together in a single file. It makes it easy for anyone to understand and reproduce the analysis you have done. Take a look at the GIF below:
After you create a R Notebook file, you insert code chunks in the file — where you write your code. Running the code chunk (as shown in the GIF) gives you the output inside the notebook.
Using R Notebook
I will describe the basics of using R notebook here, along with basic markdown syntaxes that you will need. For a more detailed tutorial, visit this link.
To open a R notebook, either click on the File menu and select R Notebook under New File section; or easier — click on the small arrow beside the small green plus icon and choose R Notebook. A new notebook will open with some example code. You can delete the example code, just do not delete the YAML metadata, which are the instructions written at the beginning between two --- . These two lines contain instructions for the title of the notebook, and the format the notebook will be rendered to. The title can be changed to whatever you like. The format, by default, will be set to HTML, but you can change it to PDF or Word document by clicking on the small arrow beside the Preview button and selecting “Knit to PDF” or “Knit to Word document”.
The most powerful feature of R notebook is that it is interactive. You write code inside the notebook in blocks known as “code chunks”. To write code, you first insert a code chunk by clicking on the small arrow beside the Insert button and selecting R. Then you run the whole chunk, either by clicking on the small green arrow on the right side of the chunk, or by clicking on the small arrow beside the Run button and selecting “Run current chunk”, or if you like using keyboard shortcuts — by pressing Control + Shift + Enter. Once the chunk is run, it will display the output below the chunk.
The best thing about running code chunks is that it makes the whole process of analysis interactive. As I said before, this is the most powerful feature of R Notebook. You build the code step-by-step, exploring and visualizing the data as you go. Granted, you can do the same thing by running code from a script file one at a time; but in R Notebook you can see the output just after a code chunk — making it easier for you as well as anyone else looking at the file to understand which code generated which output.
When you save the notebook file, it is saved as a .Rmd file. This is the raw code file, and does not include any output or formatting. The formatted output file is generated when you knit the file into either HTML, PDF or Word document using the Preview button. You can share the output document as a report of your analysis, or you can share the .Rmd notebook file for someone to reproduce the results and understand the analysis process. Even when someone is using the .Rmd file, they can run the code chunks one by one to get a better understanding of the though process behind the analysis. Of course, if some one chooses to, they can run all of the code chunks at once by selecting the Run All option from the Run menu or by pressing Control + Alt + R.
I have still not talked about the markdown feature of R notebook, which is another of its powerful features. There is no formatting option present for a script file — no headers or bold and italic fonts. The best you can do is putting comments to make others understand what the corresponding code does. R Notebooks can do all of this, and more. You do not only include code and the corresponding results and graphs in the notebook, you also can write whatever you want to make sense of the results when you look at it at a later time, or to make someone understand your analysis better. Like any word processor, you can put headers and incorporate section breaks to structure the notebook into sections, along with using bold and italicized text for emphasis. This is great because you can make the notebook into a full-fledged report rather than just a document with raw analysis. You can save so much time by not having to write a separate report later on — which may require you to go through the whole analysis again to remember what you did in the first place — depending on how much time has passed in between.
The idea of learning new syntaxes just to write a report may be off-putting to some; but trust me on this, markdown syntax is super easy. I am sharing the GIF with the markdown formatting below again for the ease of understanding my point.
Learning LaTeX has a steep curve — it is relatively difficult to grasp all the options and remember all the commands at the beginning. Markdown is nothing like that. Use one or more # symbols at the beginning of your sentence to turn it into header of different sizes. Encapsulate sentences inside one, two or three * to turn them italicized, bold or both, respectively. Use ---- to define a section break. Use single * followed by a space to turn sentences int bullet points. Markdown even has support for nested bullets, for which you just have to indent the sentence by pressing a tab.
You can even put hyperlinks and images in R notebooks using markdown. As shown in the GIF above, to put a hyperlink in the document, you use [Display text](hyperlink), where you put the text that has to be displayed in square brackets, followed by the actual hyperlink inside parentheses. Inserting images also follows an almost similar syntax — , where you put the image description (optional and not displayed, but helpful for cases when the image fails to load) in square brackets, followed by the filename with file extension inside parentheses.
Even though it is very easy to remember and use these syntaxes, if you really do not want to learn them — markdown has even more tricks up its sleeves. If you are familiar with HTML tags, you can directly use them in R Notebooks and do the formatting. So cool, isn’t it? See the image below for an example, where I show the R notebook and the rendered HTML document side by side.
There is one more small but useful feature in R Notebook if you are rendering your documents in HTML format. As always, the code is shown in the rendered document along with the output, but there is small button shown at the top which let’s you hide the code chunks if you want — leaving only the output and the text you have written for display. This is very helpful for making the notebook feel even more like a report, make it tidier, or make it easy to understand to a person who is not familiar with the R language or the commands.
Why is R Notebook superior to saving results in a MS Word file?
Saving your results of an analysis in R to a Word document (or any other word processor) is a lot of extra work. If you are writing a report, you have to copy all the code, results and figures from R workspace to your word document. Then you have to format the text in the report by selecting and clicking on options. R Notebook is so much easier because all the code and output is right there in your document, and you can format the text while you are writing it using simple commands.
Word files are mutable, anything can be overwritten or omitted by mistake (unless it is protected or in read-only mode). You can circumvent this by exporting the word file into other formats such as PDF, but that is just one more extra step. R Notebook gives you the option of rendering a document directly in immutable formats such as PDF or HTML (you can obviously edit these formats using specialized PDF or text editors, but when you are opening them with the default application they can not be modified). If you absolutely need to export in Word format, it gives you that option too!
Then comes the matter of reproducibility. If someone wants to reproduce your results for confirmation, they have to copy the code from the Word document and paste it in R to run it. With R notebooks, if you have shared the .Rmd file, they can just click on Run and the whole analysis will be there, exactly as you did.
Epilogue
I have seen many people, specially my colleagues in academia, who do not know or use R notebooks. Mostly they save results and graphs in Word documents, or in some cases, in text files. I think this stems from the fact that they did not have a proper introduction to the features of R Studio. They started using R Studio as an interface to work with R because someone (either a colleague, a friend, a YouTube tutorial or a blog post) told them to, and never ventured into exploring the power of the tool. I also started the same — by saving my results into Word documents or Powerpoint presentations; but once I came to know about the power and ease of use of markdown documents and R notebook — there was no going back. If you know someone who still does not use R notebooks (given that they are using R for interactive data exploration and analysis), please tell them about its benefits (or give them the link of this post!)
All the best!
