Document your analysis with R MarkDown
What is Markdown?
According to John Gruber, Creator of Markdown
"Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)."
Markdown is a language for writing different kinds of documents, such as PDF or HTML, even word, it doesn't do anything fancy such as change the font type, color or size. All you have control over is how text displayed.
t is not really a language in the same sense that python is It's just a way to take plain text and make it so you can add code and italics, headers, links without as much effort as coding it in HTML directly or something similar. You can say it’s a more powerful and easy plain-text formatting syntax.
Why should you use Markdown instead of HTML?
1. Easy to read and type
“The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible,” John Gruber, Creator of Markdown.
For instance, HTML syntax or tags add lots of in-line noise they make a document hard to read for e.g. this is how you can make text appear italics inside a title:
HTML
<h1>This <i>Baianat</i> Blog</h1>
Markdown
#This *Baianat* Blog
2. Easy to learn
Not only Markdown is easier to type and read but also, it’s accessible to someone who doesn’t know anything about HTML language, in addition to that, Markdown characters are easier to remember.
Markdown Syntax has a very gentle learning curve, you can download any Markdown text editor or use Gruber’s browser-based dingus and start writing.
What is R Markdown?
R Markdown is the integration of R code with markdown, the characteristics of R Markdown file:
- R code is evaluated as part of the processing of the markdown.
- Results and plots from R code are inserted into markdown document.
You can use an R Markdown file to:
- Embed and execute code in a markdown document for more reproducible analyses.
- Generate high-quality reports that can be shared with an audience.
- Communicating your code with other researchers.
R Markdown is a great way in documenting your analysis and share it with others. Also, R Markdown documents are fully reproducible.
The Most Common Markdown Editor
- Typora
- StackEdit
- Haroopad
- Markdown Edit (a.k.a. Markdown)
- Smartdown
- MarkdownPad
- Markable.in
- Mou
- Writemonkey
In addition to all of that, any basic text editor can be used to create a markdown document but, in this post, we will use RStudio which it's already comes with a text editor.
To get R Markdown working in RStudio, the first thing you need is the rmarkdown package, which you can get from CRAN by running the following commands in RStudio:
install.packages("rmarkdown")
library(rmarkdown)
Create an R Markdown file
You can create a new R Markdown file from the drop-down menu: File -> New File -> R Markdown in RStudio.
If R Markdown package is not installed RStudio well ask you to download the package and install it.
After you select R Markdown it well ask you to choose the output format and put the title and the author name, for now, we will focus on an HTML Format, which can be easily converted to other file types later.
We’ll talk about the rest of the options especially Shiny later.
After writing the title and author name and pressing OK you will see the following screen of the created .Rmd file that comes with basic instructions.
Notice that the file contains different types of content:
1. YAML header surrounded by ---
2. R code chunks surrounded by```
3. Text mixed with simple formatting
Generating the HTML file
Once you have finished from your.Rmd file and want to convert it to the desired output, click on the Knit button at the top left (It’s a particularly cute little button, with a ball of yarn and a knitting needle).
For the first time, RStudio will ask you to select a directory to save your.Rmd file and the resulting .html file.
Click that, another window will open and you’ll see knitr in action, executing each code chunk and each bit of in-line code to compile the R Markdown to a Markdown document. This will then be converted to HTML, with a preview of the result.
You can click “Open in browser” to open the document in your browser, or “Publish” to publish the document to the web.
How Does It Work?
1. When you press on Knit, R Markdown feeds .Rmd file to knitr, which executes all of the code chunks and creates a new markdown .md document which includes the code and it’s results.
2. The .md file generated by knitr is then processed by pandoc ( it’s a library used to convert documents to other formats ) which is responsible for creating the finished format or document type.
Markdown Syntax
As we discussed before, each newly created .Rmd file comes with basic instructions, but we want to create our own R Markdown file, so go ahead and delete everything in the example file.
We will demonstrate the main syntactical elements used by most developers which will make you immediately begin writing your own Markdown file.
Heading
To write heading in R Markdown you should add a # symbol at the start of the line.
The number of hashes indicates the level of the heading there are a total of 5 levels which you can make use of but for most writing, you’ll rarely ever need more than 3.
#Heading 1
##heading 2
###heading 3
####heading4
#####heading5
Bold Text
Write the texts between double asterisks** ** or double underscore__ __:
**Your text here to appear in bold**
__Your text here to appear in bold__
Italic Text
Write the text between single asterisks * *or underscore _ _:
*Your text here to appear in italics*
_Your text here to appear in italics_
Strikethrough
Write the text between double tilde ~~ ~~:
~~Strikethrough Text~~
Escaping
Escaping Markdown characters with a backslash \ allows you to use any characters which might be getting accidentally converted into HTML.
\*Show My Text\*
Quotation
Prefixing the line with a > converts it into a block-quote:
>Our goal is to help you learn the material as thoroughly and quickly as possible.
Horizontal Rule
You can draw a horizontal line with three or more of the following symbols:
Hyphens----- or Underscores____
Lists
1. Unordered List
To make an unordered list you can use either *, - or + symbols to mark your bullet points and space then your text.
* element1
- element2
+ element3
2. Ordered List
Simply use a number with a dot1. to make an ordered list instead of *, - or +.
1. Element1
2. Element2
3. Element3
You can also create nested lists; just indent a line with 4 spaces and it will be nested under the line above.
* element1
* sub-element
+ element3
* sub-element
Links
1. Inline-style
Write your text in brackets [] and your link in Parentheses ()
[This Our website press to log in](www.dataquest.io)
2. Reference-style
I started using [DataQuest][1] over a year ago now and they offer 4 [subscription][2] plans: Free, Basic, and Premium.
[1]: https://www.dataquest.io/ "DataQuest"
[2]: https://www.dataquest.io/subscribe "subscription"
3. Automatic Links
New Lines
Newlines require a double space after the end of a line.
New line
second line
Tables
You can create tables by assembling a list of words and dividing them with hyphens– and then separate each column with a pipe |.
The :-----: tells markdown that the line above should be treated as a header and the lines below should be treated as the body of the table.
| Col 1 | Col 2 | Col 3 |
|:------|:-----:|-------:|
| A | 1 | 100 |
| B | 2 | 200 |
| C | 3 | 300 |
Text alignment of the columns is set by the position of:
:----: Centre
:-----Left
-----: Right
------ Auto
Images
1. Inline-style
Write your text in brackets ![] and your direct link with the extension in Parentheses ()
2. Reference-style
![DataQuest Logo][Logo]
[Logo]: https://image.ibb.co/bVCXzn/JRXeuzQO.jpg
Code Chunks in R Markdown
The most amazing part is the ability to embed R code and its output in the same markdown file. In order to do that we need to use the ```{r} your code``` syntax.
```{r}
print("Welcome to Data-Quest !")
```
This is how the embedded code works in your document. One box shows what you’ve typed in your code and the box below it shows your output:
We can tweak many things about your output using different options that we can include inside curly brackets; the most common options are:
- Eval means to evaluate or execute that code ( Default are set to true).
- Echo means show what you’ve typed in your code ( Default are set to true).
- Comment change or remove double hash symbol comments.( Default are set to ##).
- Warning Are warning messages displayed? ( Default are set to true).
- Error Are warning messages displayed? ( Default are set to true). fig.align fig.align ="left" "right" "center" ( Default are set to left).
- Fig.width What width and height are the plots? (in inches) ( Default are set to fig.width = 7).
- The following are some examples using some of these options:
- R code Chunk with echo=false
- R code Chunk with eval=false
- R code Chunk with comment="//"
Try the following code by yourself, to see the result just press the knit button:
```{r }
summary(mtcars)
```
```{r fig.align="Right"}
plot(mtcars)
```
```{r }
num_1 <- 120
cat("This my test number", num_1)
```
In addition to executing R code chunks, you can also execute chunks in a variety of other languages.
You can find some of the available language engines when you press on Insert button:
Or simply use the name of the engine such as Python in place of R in your chunk:
```{python}
text_h = "welcome python"
print("we say=", text_h)
```
In addition to that, you have other run options from the run drop-down menu, for instance, you can run an individual chunk of code at any time by placing your cursor inside the code chunk and selecting Run >> Run Current Chunk.
Output Formats & Options
The RStudio IDE knit button renders a file to the first format listed in its drop-down menu.
You can render to other formats by clicking the drop-down menu beside the knit button:
At the very top of your .Rmd file you can, optionally, include YAML header. In this header, you can change the type of the output document, add some metadata such as title, author.
YAML header has the key:value pairs. As you can seehtml_document is a value of output key (you can find more about html_document value here), the output can have other values such as pdf_document, word_document.
Conclusion
Markdown
It's a very simple markup language with plain text formatting syntax it is planned with the goal that it can be changed over to HTML which provides methods for creating documents with headers, images, links etc. from plain text files while keeping the original plain text file easy to read.
R Markdown
It uses markdown syntax to presents your code alongside its output with conventional text to explain it.
R Markdown supports dozens of static and dynamic output formats including HTML, PDF, MS Word, Beamer, HTML5 slides, Tufte-style handouts, books, dashboards, shiny applications, scientific articles, websites, and more.
From a reproducible analysis perspective, we want the others to easily understand what we did in our analysis and verify the findings and build upon us. so, you could use R markdown to make a reproducible record of your analysis as it allows you to create reproducible research documents in PDF, HTML, and Microsoft Word formats.
You might choose to create an R Markdown document as an appendix to your paper or even upload it to an online repository such as GitHub, GitLab, bitbucket.