what yaml shoud i use to get .md file from .rmd

---

Tutorial Aims:

1. Understand what RMarkdown is and why you lot should use it
2. Learn how to construct an RMarkdown file
3. Export an RMarkdown file into many file formats

Steps:

1. What is RMarkdown
2. Download RMarkdown
3. Create an RMarkdown (.Rmd) file
4. YAML header fabric
5. Markdown syntax
6. Insert lawmaking from an R script into a .Rmd file
7. Create a .pdf file from your .Rmd file
8. R Notebooks (the time to come of reproducible code? Maybe?)

1. What is R Markdown?

R Markdown allows you to create documents that serve as a swell record of your analysis. In the world of reproducible research, we desire other researchers to hands empathize what we did in our analysis, otherwise nobody tin be certain that you analysed your data properly. Yous might choose to create an RMarkdown document as an appendix to a paper or project consignment that you lot are doing, upload it to an online repository such as Github, or just to keep as a personal record then you can quickly look back at your code and see what you lot did. RMarkdown presents your code alongside its output (graphs, tables, etc.) with conventional text to explain it, a scrap like a notebook.

RMarkdown makes use of Markdown syntax. Markdown is a very simple 'markup' language which provides methods for creating documents with headers, images, links etc. from plain text files, while keeping the original obviously text file easy to read. You tin can catechumen Markdown documents to many other file types similar .html or .pdf to display the headers, images etc..

When yous create an RMarkdown file (.Rmd), yous use conventional Markdown syntax alongside chunks of code written in R (or other programming languages!). When you lot knit the RMarkdown file, the Markdown formatting and the R code are evaluated, and an output file (HTML, PDF, etc) is produced.

To see what RMarkdown is capable of, have a look at this undergraduate dissertation, which gives a concise log of their statistical analysis, or the completed demo RMarkdown file for this tutorial.

All the resources for this tutorial, including some helpful cheatsheets can exist downloaded from this repository. Download by clicking on Code -> Download Nothing, then unzipping the archive in a folder you will employ for this tutorial.

Read through this tutorial and use the information you learn along the mode to convert the tutorial R script (RMarkdown_Tutorial.R), which you can find in the repo, into a well commented, logically structured R Markdown (.Rmd) document. Afterwards, there are some challenge scripts that y'all tin convert to .Rmd documents. If yous want, y'all could likewise try converting ane of your own R scripts.

Haven't used R or RStudio before? No worries! Check out our Intro to R and RStudio tutorial, then come up back here to master RMarkdown!

2. Download R Markdown

To get RMarkdown working in RStudio, the first matter you need is the rmarkdown package, which you can get from CRAN past running the following commands in R or RStudio:

                          install.packages              (              "rmarkdown"              )                                          library              (              rmarkdown              )                                                  

three. Create an RMarkdown file

To create a new RMarkdown file (.Rmd), select File -> New File -> R Markdown..._ in RStudio, and then choose the file type you want to create. For now we will focus on a .html Document, which can be easily converted to other file types later.

The newly created .Rmd file comes with basic instructions, just we want to create our own RMarkdown script, then go ahead and delete everything in the example file.

Now save the .Rmd file to the repository you lot downloaded earlier from Github.

Now open up the RMarkdown_Tutorial.R do script from the repository you downloaded earlier in another tab in RStudio and use the instructions beneath to help you convert this script into a coherent RMarkdown document, flake by fleck.

If y'all accept whatsoever of your own R scripts that you would like to make into an R Markdown document, you lot tin besides utilise those!

4. The YAML Header

At the superlative of any RMarkdown script is a YAML header section enclosed by ---. By default this includes a championship, author, date and the file blazon you desire to output to. Many other options are available for unlike functions and formatting, run into hither for .html options and hither for .pdf options. Rules in the header section will modify the whole certificate. Have a motion-picture show through rapidly to familiarise yourself with the sorts of things you can alter past adding an option to the YAML header.

Insert something like this at the summit of your new .Rmd script:

            --- title: "Edinburgh Biodiversity" writer: John Doe date: 22/Oct/2016 output: html_document ---                      

Past default, the title, author, date and output format are printed at the acme of your .html document. This is the minimum you should put in your header section.

Now that nosotros have our first piece of content, nosotros can exam the .Rmd file by compiling information technology to .html. To compile your .Rmd file into a .html certificate, you should press the Knit button in the taskbar:

By default, RStudio opens a separate preview window to display the output of your .Rmd file. If you want the output to be displayed in the Viewer window in RStudio (the same window where you would see plotted figures / packages / file paths), select "View in Pane" from the drop down menu that appears when you click on the Knit button in the taskbar, or in the Settings gear icon drop down card next to the Knit button.

A preview appears, and a .html file is as well saved to the aforementioned folder where you saved your .Rmd file.

4. Markdown syntax

You tin can apply regular markdown rules in your R Markdown certificate. One time y'all knit your document, the output will display text formatted co-ordinate to the following simple rules.

Formatting Text

Here are a few common formatting commands:

*Italic*

Italic

---

**Assuming**

Bold

---

This is `lawmaking` in text

This is code in text

---

# Header 1

---

## Header ii

Notation that when a # symbol is placed inside a lawmaking chunk it acts equally a normal R comment, but when placed in text it controls the header size.

---

* Unordered listing particular

Unordered list detail

---

1. Ordered listing particular

1. Ordered listing item

---

[Link](https://world wide web.google.com)

Link

---

$A = \pi \times r^{2}$

The $ symbols tells R markdown to use LaTeX equation syntax.

To practice this, try writing some formatted text in your .Rmd document and producing a .html page using the "Knit" button.

5. Code Chunks

Below the YAML header is the space where you will write your code, accompanying caption and any outputs. Lawmaking that is included in your .Rmd document should be enclosed past three backwards apostrophes ``` (grave accents!). These are known as lawmaking chunks and look similar this:

            ```{r} norm <- rnorm(100, mean = 0, sd = 1) ```                      

Y'all can speedily insert a lawmaking chunk in RStudio using a push in the toolbar:

Inside the curly brackets is a space where you can assign rules for that code chunk. The lawmaking chunk above says that the code is R lawmaking. We'll get onto some other curly caryatid rules later.

Take a become at grabbing some lawmaking from the instance R script and inserting information technology into a lawmaking chunk in your .Rmd certificate.

You lot tin run an private clamper of code at whatever time past clicking on the small greenish arrow:

The output of the code volition appear only below the code clamper.

More on Code Chunks

It's of import to call back when yous are creating an RMarkdown file that if y'all desire to run lawmaking that refers to an object, for example:

            ```{r} print(dataframe) ```                      

yous must include instructions showing what dataframe is, only like in a normal R script. For example:

            ```{r} A <- c("a", "a", "b", "b") B <- c(v, 10, 15, 20) dataframe <- information.frame(A, B) print(dataframe) ```                      

Or if you are loading a dataframe from a .csv file, you must include the code in the .Rmd:

            ```{r} dataframe <- read.csv("~/Desktop/Lawmaking/dataframe.csv") ```                      

Similarly, if y'all are using any packages in your analysis, you volition have to load them in the .Rmd file using library() as in a normal R script.

            ```{r} library(dplyr) ```                      

If you don't want the code of a particular code chunk to announced in the final certificate, but still want to show the output (e.g. a plot), and so you lot can include echo = FALSE in the code clamper instructions.

            ```{r, echo = Simulated} A <- c("a", "a", "b", "b") B <- c(5, 10, fifteen, 20) dataframe <- information.frame(A, B) print(dataframe) ```                      

Similarly, you lot might want to create an object, but non include both the code and the output in the final .html file. To do this you tin can employ, include = FALSE. Be aware though, when making reproducible research information technology's often not a good idea to completely hide some part of your analysis:

            ```{r, include = FALSE} richness <-   edidiv %>%     group_by(taxonGroup) %>%     summarise(Species_richness = n_distinct(taxonName)) ```                      

In some cases, when you load packages into RStudio, various alert messages such as "Warning: package 'dplyr' was built under R version iii.four.four" might appear. If yous do not want these alarm messages to appear, you tin use warning = Imitation.

            ```{r, warning = FALSE} library(dplyr) ```                      

REMEMBER: R Markdown doesn't pay attention to annihilation you have loaded in other R scripts, you lot MUST load all objects and packages in the R Markdown script.

More Lawmaking Clamper Instructions

Dominion	Example (default)	Function
eval	eval=True	Is the lawmaking run and the results included in the output?
include	include=TRUE	Are the code and the results included in the output?
repeat	echo=Truthful	Is the code displayed aslope the results?
warning	warning=TRUE	Are warning letters displayed?
fault	error=Simulated	Are fault letters displayed?
message	message=True	Are messages displayed?
tidy	tidy=FALSE	Is the code reformatted to get in look "tidy"?
results	results="markup"	How are results treated? "hide" = no results "asis" = results without formatting "hold" = results only compiled at terminate of chunk (utilize if many commands human activity on one object)
cache	cache=FALSE	Are the results cached for futurity renders?
comment	comment="##"	What character are comments prefaced with?
fig.width, fig.tiptop	fig.width=vii	What width/height (in inches) are the plots?
fig.align	fig.align="left"	"left" "right" "center"

Inserting Figures

Inserting a graph into RMarkdown is piece of cake, the more energy-demanding aspect might be adjusting the formatting.

By default, RMarkdown will place graphs by maximising their top, while keeping them inside the margins of the page and maintaining attribute ratio. If yous have a particularly tall effigy, this can hateful a actually huge graph. In the following example we modify the dimensions of the effigy we created higher up. To manually set up the effigy dimensions, you can insert an instruction into the curly braces:

            ```{r, fig.width = 4, fig.meridian = 3} A <- c("a", "a", "b", "b") B <- c(5, ten, 15, 20) dataframe <- data.frame(A, B) print(dataframe) boxplot(B~A,data=dataframe) ```                      

Inserting Tables

Standard R Markdown

While R Markdown can print the contents of a data frame easily by enclosing the name of the data frame in a code clamper:

this can look a bit messy, especially with data frames with a lot of columns. Including a formal tabular array requires more than effort.

kable() function from knitr bundle

The most aesthetically pleasing and uncomplicated table formatting function I take found is kable() in the knitr packet. The beginning argument tells kable to make a table out of the object dataframe and that numbers should take ii significant figures. Retrieve to load the knitr package in your .Rmd file too.

            ```{r} library(knitr) kable(dataframe, digits = 2) ```                      

pander function from pander bundle

If you desire a flake more control over the content of your tabular array y'all tin use pander() in the brownnose packet. Imagine I want the 3rd cavalcade to appear in italics:

            ```{r} library(brownnose) plant <- c("a", "b", "c") temperature <- c(xx, 20, 20) growth <- c(0.65, 0.95, 0.xv) dataframe <- data.frame(plant, temperature, growth) emphasize.italics.cols(three)   # Make the 3rd column italics pander(dataframe)           # Create the table ```                      

Observe more info on pander here.

Manually creating tables using markdown syntax

Yous can also manually create minor tables using markdown syntax. This should be put outside of any code chunks.

For instance:

            | Plant | Temp. | Growth | |:------|:-----:|-------:| | A     | 20    | 0.65   | | B     | 20    | 0.95   | | C     | twenty    | 0.fifteen   |                      

will create something that looks like this:

Found	Temp.	Growth
A	twenty	0.65
B	20	0.95
C	20	0.fifteen

The :-----: tells markdown that the line to a higher place should exist treated as a header and the lines below should exist treated every bit the trunk of the table. Text alignment of the columns is set by the position of ::

Syntax	Alignment
`:----:`	Eye
`:-----`	Left
`-----:`	Right
`------`	Car

Creating tables from model outputs

Using tidy() from the packet broom, we are able to create tables of our model outputs, and insert these tables into our markdown file. The case below shows a simple example linear model, where the summary output table tin exist saved as a new R object and and then added into the markdown file.

            ```{r warning=Faux} library(broom) library(brownnose) A <- c(xx, 15, ten) B <- c(1, 2, 3)  lm_test <- lm(A ~ B)            # Creating linear model  table_obj <- tidy(lm_test)      # Using tidy() to create a new R object called tabular array  pander(table_obj, digits = 3)   # Using pander() to view the created tabular array, with 3 sig figs  ```                      

By using warning=False as an statement, any warnings produced will be outputted in the panel when knitting simply will not announced in the produced certificate.

7. Creating .pdf files in Rmarkdown

Creating .pdf documents for printing in A4 requires a bit more fiddling around. RStudio uses another document compiling system chosen LaTeX to brand .pdf documents.

The easiest way to use LaTeX is to install the TinyTex distribution from within RStudio. Beginning, restart your R session (Session -> Restart R), then run these line in the console:

                          install.packages              (              "tinytex"              )                                          tinytex              ::              install_tinytex              ()                                                  

Condign familiar with LaTeX will requite you lot a lot more options to brand your R Markdown .pdf look pretty, every bit LaTeX commands are mostly compatible with R Markdown, though some googling is often required.

To compile a .pdf instead of a .html document, change output: from html_document to pdf_document, or apply the dropdown menu from the "Knit" button:

Common problems when compiling a .pdf

• Text is running off the folio

Add a global_options argument at the start of your .Rmd file:

            ```{r global_options, include = FALSE} knitr::opts_chunk$set(message=Imitation, tidy.opts=listing(width.cutoff=60)) ```                      

This code chunk won't be displayed in the final document due to the include = FALSE telephone call and should be placed immediately later on the YAML header to impact everything below that.

tidy.opts = list(width.cutoff = 60) defines the margin cutoff point and wraps text to the next line. Play with the value to get it right.

---

• I lose my syntax highlighting

Apply the xelatex engine to compile your .pdf:

            --- writer: John Doe output:    pdf_document:     latex_engine: xelatex ---                      

By default, R markdown uses the base LaTeX engine to compile pdfs, but this may limit certain options when information technology comes to formatting. There are lots of other engines to play around with equally well.

---

• My page margins are too big/small

Add a geometry argument to the YAML header

            --- title: "R Markdown Tutorial Demo" author: "John Godlee" date: "30/11/2016" output:    pdf_document:     latex_engine: xelatex geometry: left = 0.5cm, right = 1cm, elevation = 1cm, bottom = 1cm ---                      

geometry is a LaTeX control.

---

• My plot/tabular array/code is carve up over ii pages

Add a page interruption before the dodgy chemical element:

            \pagebreak ```{r} Codey codey lawmaking code ```                      

---

• I want to change the font

Add a font argument to your header section

            --- title: "R Markdown Tutorial Demo" author: "John Godlee" engagement: "30/11/2016" output:   pdf_document:     latex_engine: xelatex mainfont: Arial ---                      

mainfont is a LaTeX command.

Have a go yourself

At this point, if you haven't been post-obit through already, have a go at converting the tutorial R script (RMarkdown_Tutorial.R) into a .Rmd certificate using the information above as a guide.

Remember that a skillful R markdown document should provide a reproducible log of your code, properly commented, with subtitles, comments and code relevant output so the reader knows what is going on.

8. R Notebooks

RMarkdown outputs to a not-interactive file format like .html or .pdf. When presenting your code, this means you have to make a choice, do you lot want interactive simply messy looking code (.Rmd) or non-interactive but neat looking code (.html, .pdf)? R notebooks provide a file format that combines the interactivity of a .Rmd file with the attractiveness of .html output.

R notebooks output to the imaginatively named .nb.html format. .nb.html files can be loaded into a spider web browser to see the output, or loaded into a code editor like RStudio to see the lawmaking. Y'all are able to interactively select which lawmaking chunks to hide or show code chunks.

Notebooks employ the aforementioned syntax as .Rmd files so it is easy to re-create and paste the script from a .Rmd into a Notebook. To create a new R Notebook file, select File -> New File -> R Notebook. Create a notebook from your newly created .Rmd file by copying and pasting the script. If you lot cull to copy and paste the script, make sure that under your YAML header, output: html_notebook instead of output: html_document.

Alternatively, to plow any existing .Rmd file into an R notebook, add together html_notebook: default nether the output: statement in the YAML header. If you have more than 1 output document blazon, the "Knit" push button will only produce the offset type. You can apply the dropdown menu form the Knit button to produce 1 of the other types.

            --- title: "R Markdown Tutorial Demo" writer: "John Godlee" date: "xxx/11/2016" output:   html_notebook: default   pdf_document:     latex_engine: xelatex mainfont: Arial ---                      

To output to .nb.html, starting time make sure all your code chunks take been run:

and then click Preview:

Find that with R Notebooks you tin still output to .html or .pdf, the same as a .Rmd file.

R notebooks have merely been around for most a couple of years and then they're not perfect yet, but may supervene upon R markdown in the future for many applications.

Departure between RMarkdown and RNotebooks

R Markdown documents are 'knitted', while R Notebooks are 'previewed'.

Although the notebook preview looks similar to the knitted markdown certificate, the notebook preview does not execute whatever code chunks, merely just shows you a rendered copy of the Markdown output of your document along with the most recent clamper output. The preview is also generated automatically whenever the notebook is saved. This would be specially useful if we have the preview showing in the Viewer window next to the console. This means that in R Notebooks, we are able to visually assess the output as nosotros develop the document without having to knit the whole certificate again.

For instance, with the following lawmaking chunk case (from the RMarkdown_Tutorial.R practice script), we are creating a tabular array of species richness for each taxonomic group.

            ```{r} richness <-   edidiv %>%   group_by(taxonGroup) %>%   summarise(Species_richness = n_distinct(taxonName)) ```                      

To bring up the tabular array output, we tin add richness, brownnose(richness), kable(richness) to the cease of that code chunk. If we had initially forgotten to add in either ane of those functions, the table would not take been produced in both the knitted markdown document and the notebook preview. Imagine that we are now editing the R Markdown document / R Notebook document to include this function to bring up the table in the outputted document.

For RMarkdown: we would type in pander(richness), run that specific lawmaking chunk, and so have to click the Knit button in the taskbar to knit the whole document once again.

For R Notebooks, we blazon in pander(richness), run that specific code chunk, and salvage the document, and the preview in the Viewer window would exist updated on its own - there is no need to click the Preview button in the taskbar and run the code for the whole certificate.

Note: R Markdown Notebooks are merely bachelor in RStudio 1.0 or higher.

Bonus task!

Either in a minor group or on your own, convert one of the three demo R scripts into a well commented and easy to follow R Markdown document, or R Markdown Notebook. The files (RMarkdown_Demo_1.R, RMarkdown_Demo_2.R, RMarkdown_Demo_3.R) can be found in the repo you downloaded earlier.

Tutorial Outcomes:

1. You are familiar with the Markdown syntax and code clamper rules.
2. You can include figures and tables in your Markdown reports.
3. You tin can create RMarkdown files and export them to pdf or html files.

Doing this tutorial as role of our Data Scientific discipline for Ecologists and Environmental Scientists online class?

This tutorial is role of the Stats from Scratch stream from our online form. Go to the stream folio to find out almost the other tutorials part of this stream!

If yous have already signed up for our grade and you are ready to take the quiz, go to our quiz centre. Annotation that you need to sign up first before you can take the quiz. If you haven't heard about the course before and want to learn more than about it, bank check out the form page.

beasleyvien1978.blogspot.com

Source: https://ourcodingclub.github.io/tutorials/rmarkdown/

Share this post