How To Use R Markdown (part One) - R-bloggers

Home » Code Snippets R Markdown » How To Use R Markdown (part One) - R-bloggers

Maybe your like

[This article was first published on R on R (for ecology), and kindly contributed to R-bloggers]. (You can report issue about the content on this page here) Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

ShareTweet

Today I’m excited to share a blog post on how to use R Markdown. R Markdown is a dynamic file format that allows you to make documents containing normal text alongside chunks of embedded R code. In fact, all of my blog posts are written using R Markdown, which is how I’m able to write text like this, write code, and even insert a chunk of code

like_this <- c("isn't", "this", "neat?") Image saying 'How to use R Markdown Part 1', with an arrow pointing from the R Markdown logo to the HTML logo. The background is a person knitting, and below the arrow it says 'KNIT!'

R Markdown is useful for several reasons:

  • It’s great for reproducibility, where you can explain your analyses alongside your code and output so someone can follow along and replicate your work

  • It helps with accountability, because all your code and the exact corresponding outputs are knit together into the final document

  • It allows you to make tutorials like this one

  • Finally, you can use it for learning R by helping you keep track of your notes and thinking process all while creating a custom reference document (more on this in part two!)

This tutorial is the first post of a two-part series on R Markdown. Here, you’ll learn how to create R Markdown documents with different types of content, and in part two I’ll go into how you can use it for learning R.

You can also follow along with this blog post in video format if you click on the image below. This post covers material in the video up to 35:35. I’ll cover the rest of the video in part two next week.

Image of Youtube play button on top of a tutorial for R Markdown created by R for Ecology

Getting set up with R Markdown

To use R Markdown, you’ll need to have R and RStudio already installed. If you need help with that, you can check out my blog post and lessons one, two, and three of my online course. These resources show you how to get started with R and RStudio.

You’ll also have to install two packages: rmarkdown and knitr. To do that you can run install.packages("rmarkdown") and install.packages("knitr"). You’ll only need to do this once for your computer (at least until the next time you update R).

install.packages("rmarkdown") install.packages("knitr")

Now that you have the basic software and packages installed, you can get started with using R Markdown!

The first thing you’ll do after opening RStudio is go to File » New File » R Markdown.

Image showing cursor hovering over File, New File, and R Markdown

Then a new window will pop up where you can fill out the title of your new document, the author (um, your name? 😉), and the output format. You can choose between HTML, PDF, and Word. We’re going to choose HTML for now, since that’s the simplest option and all you really need. Then hit OK.

Image showing window where the title is “R Markdown Tutorial”, the author is “Luka Negoita”, and HTML is selected as the output

You’ll now have a new document that is filled in with a bunch of example content. At the top, in between the boundary lines (---), you’ll see a list of document parameters that should reflect what you entered in the previous window (title, author, output). You don’t need to change anything there. We’ll come back to this header section later.

Image showing new R Markdown document that was created, with a bunch of example text

The next section shows a code chunk that says “r setup”. This sets a bunch of code chunk parameters for the rest of the document. There’s no real need to include this, so we’ll delete it for now.

Image showing code chunk in R with global parameters

What you see now is the raw R Markdown content, which contains chunks of R code between chunks of regular text with Markdown formatting. But the true power of R Markdown is when you transform that text and code into a stand-alone document.

So how do we get from an R Markdown document in RStudio to the HTML document? You click on the “Knit” button (no need to click on the dropdown arrow). The lingo here is that the R Markdown document “knits” itself into an HTML document.

Highlighting the Knit button in the RStudio toolbar at the top of the screen

If you haven’t saved your document yet, you’ll be prompted to save it when you click “Knit”. You’ll notice that R Markdown files are saved as a .Rmd file instead of a .R file. Now that you’ve saved your document somewhere, it will automatically save itself every time you press “Knit” from now on.

The final HTML file will automatically display in the ‘Viewer’ panel (usually on the right).

Side by side comparison of R Markdown code with the HTML output

If you explore the document a little, you can see that R Markdown really lets you do a lot. You can include different types of text formats, links, code chunks, and even plots.

Working on your own R Markdown document

Cool. Now let’s get started on creating our own R Markdown document. First let’s start with a blank slate. Go ahead and delete everything in the sample document so that all you have left is the parameter header. It’s important that you leave that in!

Blank R Markdown document except for the header

Try to type some text, whatever you want. If you press “Knit”, it should then show up in a knitted document, and your .Rmd file should be automatically saved. Anything you type will show up in the knitted document! Neat.

Typing some text in the R Markdown document that says Hi everyone!

Learning R Markdown text formats

Now let’s explore different types of text formatting in R Markdown. To organize different sections of your report, you’ll want to add section headings or titles. You can write headings of different sizes by writing different numbers of pound signs (#) + a space + your text, like this:

Typing example headings of several sizes

As you can see, the more pound signs you add, the smaller the headings get.

You can also add bold and italicized text by surrounding text with asterisks (*). Using one asterisk gives you italicized text, using two gives you bold text, and using three gives you bold italicized text.

Typing example italicized, bold, and bold italicized text

You can create numbered lists just using 1. 2. 3. (…) in front of your text.

An example list in R Markdown that says this is a list!

And you can create bulleted lists using either hyphens (-) or asterisks (*) before your text.

Example bullet points using hyphens and asterisks. They look the same in the knitted document.

You can add links by putting square brackets [these] around the word or phrase that you want to hyperlink, and then immediately put the link (with the https://) in parentheses after the square brackets, like this:

Example of putting a hyperlink in your document. The text says here is a link to my website, with a link attached to the word here

Lastly, if you’re already an HTML wiz, you can also add any kind of HTML code to your document since the final document is HTML anyway, but I’m going to keep this tutorial simple and let you experiment with HTML on your own.

RStudio has an excellent cheat sheet that you can check out if you’re interested in learning more about what you can do with R Markdown. I just wanted to cover the essential features here, which is all you really need to know for creating most reports.

Learning how to embed code in R Markdown

Now that we’ve talked about how to format the text, let’s move on to embedding code!

You can add a code chunk by clicking on this button in the toolbar at the top of your screen:

Image showing circled button with a C on it at the top of the screen

That will add a code chunk, which looks like this:

Image showing a code chunk

You could also type out the code chunk boundaries yourself instead of pressing the button at the top, if you want. Those single quotes aren’t normal quotes—they’re the quote symbol ( ` ) that’s located under the escape key on a standard U.S. keyboard, usually paired with the tilde (~).

Image showing the quote symbol above the left tab and before the one key

You can also use these quotes to casually embed code in your text by using them like normal quotation marks, like this. This will turn text into a little code snippet in the middle of your sentence.

Image of the words like this surrounded by specialized single quotes

Back to the code chunk. If you type within the code chunk, whatever you type will appear as if you are typing it in a normal R script. Then your output will look like a normal output in your console or plot viewer. I wrote a comment in my code chunk in the image below, but the cool thing about R Markdown is that you can put most of the commentary in your R Markdown text, so there’s no need to clutter the actual code with long explanation comments.

Example code with a comment saying “You can add comments by using the pound sign in R, which is good for commentary or text but not code

I’m going to embed some code now in the current R Markdown document (the one that I’m writing this blog post with). I created a variable called “answer” and loaded a data set called “cars” that comes with R. R actually comes with a whole bunch of premade data sets that you can look at if you type data() into the console.

# I'm writing some code here: answer <- 2 + 4 # View the answer answer ## [1] 6 # Let's load some data my_data <- cars # View the first few rows of my data head(my_data, 3) ## speed dist ## 1 4 2 ## 2 4 10 ## 3 7 4

You’ll notice that R Markdown has split up the code chunk into different boxes each time there’s a piece of code that prints an output. The code is contained within light grey boxes, and the output is printed in white boxes. This just helps keep things organized so you can see what output goes with what code.

Let’s briefly explore another, related element of R Markdown: displaying plots. We’ll plot car speed as a function of distance (Y as a function of X).

# Plotting speed vs. distance from the cars data set plot(my_data$speed ~ my_data$dist)

Awesome! We can see our code and our plot output.

Running code in R Markdown

I’ve been pressing the “Knit” button to see the output of my code, but you can also run your code in RStudio as if you’re doing it in a normal R script. You can just put your cursor wherever you want and then press command + return on a Mac, or control + Enter on a PC.

As you run the code in R Markdown, the output will appear below your code chunk:

Code output appearing below the code chunk in RStudio

Running your code within the code chunk first (instead of knitting it) is especially useful if you want to work through any errors, since the error messages will be easier to understand.

Note: if you’re running code directly within code chunks, it’s important to note that like a normal R script, you have to run all of the code in the correct order. This will ensure that all your variables and packages are loaded when you need them later on in your code.

For example, we refer to a variable called my_data in our plot code. If we’re running our code manually and try to run the plot code without creating the my_data variable first, we’re going to get an error. We have to run my_data <- cars before we run plot(my_data$speed ~ my_data$dist) for the code to work. Luckily, you don’t have to worry about this when you’re knitting your document because knitting runs all of the code in order for you.

There’s also a neat trick you can use to make sure you’ve run all the necessary code and prevent errors. Pressing the button in the image below will run all of the code up to the chunk that you’re on, so you don’t have to manually go line by line or chunk by chunk.

Image showing down arrow button that will run all chunks above the current one

Changing your R Markdown theme

One last thing you can do to make your document look nice is to change the theme. You can click on the gear icon in the toolbar at the top, and select “Output Options…”

Image showing dropdown list from the gear icon, with output options highlighted

A window will open up, from which you can do things like change the theme of your HTML document. If you go to “Apply theme” and select the dropdown menu, you’re given a list of different themes to choose from. Changing the theme will do things like change the fonts and colors that are displayed. You can play around with the themes to see what you prefer, just remember to press “Knit” to process the theme change.

window showing different options for changing the look of your final R Markdown document, like theme and table of contents

If you’re interested in HTML and CSS, you can also apply your own CSS file to change the style of the document. Again, we’re going to keep it simple in this blog post—you can explore CSS on your own but please comment down below if you have any cool style sheets/themes for your R Markdown documents.

In the same way that you can change the theme of your document, you can also change the syntax highlighting. That changes how your code looks when it’s embedded in the document. For example, the image below shows the “zenburn” option.

Image showing embedded code with a brown background and green commented text, different from the usual black text on light grey background

Now it’s time for what I think is the most useful addition. The “Output Options” window also allows you to include an interactive, clickable table of contents for your document. This is especially useful for larger documents with multiple sections. The table of contents in your document will be based off of the different headings that you use, with smaller heading sizes nested within larger ones.

Image showing that a table of contents has been added, where each level is a link to the section.

You’ll notice that headings 4, 5, and 6 aren’t included in the table of contents. You can change this if you want in the “Output Options” window, where it says “depth of headers for table of contents”. If you set the depth of the headings to 6, then the table of contents will display headings all the way up to heading level 6.

Once you make these changes, you’ll notice that these changes have also been added to the heading section of your document. This means that once you familiarize yourself with the themes, you can type this information into the heading yourself. I showed you how to do it via “Output Options” because we didn’t know what the different themes were called, nor what our options were.

Text has been added to the output section of the header, showing that my theme is called readable, and my highlight is called zenburn

One quick pointer for creating an R Markdown document is to end your document with the code sessionInfo(). This will show the information about your current R session, including the version of R you’re using, the operating system, and the packages you have loaded up. The reason this is important is because packages and software get updated over time and things can change. Certain aspects of your code might not work in the same way in the future, depending on what versions of software and packages you’re using. Having that information in the future can help you track down the issues. If you know the version information for how the code was originally run, then there are ways to download older versions of R and associated packages, or at least know where the error stems from (and how to fix it in the code). In essence, including your session info can help ensure reproducibility in the future.

sessionInfo() ## R version 4.1.2 (2021-11-01) ## Platform: x86_64-apple-darwin17.0 (64-bit) ## Running under: macOS Big Sur 10.16 ## ## Matrix products: default ## BLAS: /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRblas.0.dylib ## LAPACK: /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRlapack.dylib ## ## locale: ## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8 ## ## attached base packages: ## [1] stats graphics grDevices utils datasets methods base ## ## loaded via a namespace (and not attached): ## [1] bookdown_0.24 digest_0.6.29 R6_2.5.1 jsonlite_1.7.2 ## [5] magrittr_2.0.1 evaluate_0.14 highr_0.9 blogdown_1.7 ## [9] stringi_1.7.6 rlang_0.4.12 jquerylib_0.1.4 bslib_0.3.1 ## [13] rmarkdown_2.11 tools_4.1.2 stringr_1.4.0 xfun_0.29 ## [17] yaml_2.2.1 fastmap_1.1.0 compiler_4.1.2 htmltools_0.5.2 ## [21] knitr_1.37 sass_0.4.0

And that’s it for our basic R Markdown tutorial! You learned how to create an R Markdown document, how to apply different types of text formats, how to embed code inline or in code chunks, and how to stylize your final R Markdown document. Our next blog post will be about how to use R Markdown to learn R, so keep your eyes peeled for a Part Two.

Have any cool R Markdown documents you’ve created? Share links in the comments below! 👇

If you liked this post and want to learn more, then check out my online course on the complete basics of R for ecology:
  • Start learning now

Also be sure to check out R-bloggers for other great tutorials on learning R

Related

ShareTweet

To leave a comment for the author, please follow the link and comment on their blog: R on R (for ecology). R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job. Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

← Previous post Next post →
R bloggers Facebook page

Most viewed posts (weekly)

  • Which data science skills are important ($50,000 increase in salary in 6-months)
  • PCA vs Autoencoders for Dimensionality Reduction
  • 5 Ways to Subset a Data Frame in R
  • Best Way to Upgrade to R 4.1.3 with RStudio Desktop Mac/Windows/Linux in 2022
  • How to Use R and Python Together? Try These 2 Packages
  • 5 New books added to Big Book of R
  • How to write the first for loop in R

Sponsors

Recent Posts

  • Short course and keynote on statistical methods at Ghent Summer School on Methods in Language Sciences
  • Summer School on Statistical Methods for Linguistics and Psychology, Sept. 12-16, 2022 (applications close April 1)
  • Select Columns by Index Using dplyr
  • How to Use do.call in R with examples
  • Developer diary for {ggshakeR} 0.1.2 (a package for soccer analytics viz): Implementing Github Actions CI tools (codecov, lintr, etc.) into the workflow!
  • Searching and browsing the R universe
  • How to Use R and Python Together? Try These 2 Packages
  • paste & paste0 Functions in R to Concatenate Strings
  • How long would you live if you were immortal?
  • Creating APIs for Data Science With plumber
  • Safeguards and Backups for GitHub Organizations
  • Shiny: Fast Data Loading with fst
  • Data Science on Blockchain with R. Part III: Helium based IoT is taking the world
  • R Summary Statistics Table
  • Best Way to Upgrade to R 4.1.3 with RStudio Desktop Mac/Windows/Linux in 2022

RSS Jobs for R-users

  • Junior Data Scientist / Quantitative economist
  • Senior Quantitative Analyst
  • R programmer
  • Data Scientist – CGIAR Excellence in Agronomy (Ref No: DDG-R4D/DS/1/CG/EA/06/20)
  • Data Analytics Auditor, Future of Audit Lead @ London or Newcastle

RSS python-bloggers.com (python/data-science news)

  • Explaining a Keras _neural_ network predictions with the-teller
  • Object Oriented Programming in Python – What and Why?
  • Dunn Index for K-Means Clustering Evaluation
  • Installing Python and Tensorflow with Jupyter Notebook Configurations
  • How to Get Twitter Data using Python
  • Visualizations with Altair
  • Spelling Corrector Program in Python
Full list of contributing R-bloggers

Archives

Archives Select Month March 2022 (103) February 2022 (152) January 2022 (155) December 2021 (172) November 2021 (145) October 2021 (199) September 2021 (204) August 2021 (153) July 2021 (173) June 2021 (195) May 2021 (197) April 2021 (183) March 2021 (224) February 2021 (226) January 2021 (252) December 2020 (295) November 2020 (267) October 2020 (276) September 2020 (249) August 2020 (227) July 2020 (269) June 2020 (231) May 2020 (334) April 2020 (326) March 2020 (279) February 2020 (259) January 2020 (250) December 2019 (241) November 2019 (214) October 2019 (230) September 2019 (227) August 2019 (270) July 2019 (258) June 2019 (242) May 2019 (272) April 2019 (289) March 2019 (302) February 2019 (259) January 2019 (282) December 2018 (257) November 2018 (285) October 2018 (298) September 2018 (285) August 2018 (266) July 2018 (327) June 2018 (296) May 2018 (315) April 2018 (296) March 2018 (287) February 2018 (239) January 2018 (328) December 2017 (260) November 2017 (265) October 2017 (287) September 2017 (287) August 2017 (328) July 2017 (279) June 2017 (312) May 2017 (341) April 2017 (319) March 2017 (364) February 2017 (312) January 2017 (364) December 2016 (345) November 2016 (288) October 2016 (298) September 2016 (249) August 2016 (280) July 2016 (322) June 2016 (259) May 2016 (288) April 2016 (258) March 2016 (295) February 2016 (261) January 2016 (334) December 2015 (300) November 2015 (234) October 2015 (255) September 2015 (232) August 2015 (261) July 2015 (240) June 2015 (205) May 2015 (228) April 2015 (203) March 2015 (256) February 2015 (207) January 2015 (237) December 2014 (230) November 2014 (219) October 2014 (212) September 2014 (253) August 2014 (214) July 2014 (226) June 2014 (234) May 2014 (238) April 2014 (256) March 2014 (286) February 2014 (266) January 2014 (260) December 2013 (261) November 2013 (237) October 2013 (233) September 2013 (214) August 2013 (223) July 2013 (254) June 2013 (271) May 2013 (260) April 2013 (278) March 2013 (277) February 2013 (293) January 2013 (340) December 2012 (306) November 2012 (274) October 2012 (304) September 2012 (268) August 2012 (262) July 2012 (247) June 2012 (297) May 2012 (283) April 2012 (295) March 2012 (304) February 2012 (264) January 2012 (278) December 2011 (251) November 2011 (261) October 2011 (280) September 2011 (187) August 2011 (258) July 2011 (219) June 2011 (224) May 2011 (239) April 2011 (267) March 2011 (249) February 2011 (203) January 2011 (209) December 2010 (188) November 2010 (172) October 2010 (219) September 2010 (185) August 2010 (203) July 2010 (175) June 2010 (167) May 2010 (164) April 2010 (152) March 2010 (165) February 2010 (135) January 2010 (121) December 2009 (126) November 2009 (66) October 2009 (87) September 2009 (65) August 2009 (56) July 2009 (64) June 2009 (54) May 2009 (35) April 2009 (38) March 2009 (40) February 2009 (33) January 2009 (42) December 2008 (16) November 2008 (14) October 2008 (10) September 2008 (8) August 2008 (11) July 2008 (7) June 2008 (8) May 2008 (8) April 2008 (4) March 2008 (5) February 2008 (6) January 2008 (10) December 2007 (3) November 2007 (5) October 2007 (9) September 2007 (7) August 2007 (21) July 2007 (9) June 2007 (3) May 2007 (3) April 2007 (1) March 2007 (5) February 2007 (4) November 2006 (1) October 2006 (2) August 2006 (3) July 2006 (1) June 2006 (1) May 2006 (3) April 2006 (1) March 2006 (1) February 2006 (5) January 2006 (1) October 2005 (1) September 2005 (3) May 2005 (1)

Other sites

  • Jobs for R-users
  • SAS blogs

Copyright © 2022 | MH Corporate basic by MH Themes

Never miss an update! Subscribe to R-bloggers to receive e-mails with the latest R posts. (You will not see this message again.) Submit Click here to close (This popup will not appear again)

Tag » Code Snippets R Markdown