No matter what work you do, it’s important to be able to create documents that help you communicate about your work and its results. If you use R, you might try to create communicative documents by copying and pasting your code and analyses into other tools like Microsoft Word. But the process of copying and pasting can be time-consuming, and it can be very hard to preserve the formatting you want. That’s why there’s an R package called R Markdown. With R Markdown, you can write code that not only performs the calculations that are part of your R workflow, but also directly creates beautiful documents that can make communication easier.

To get started with the R Markdown package, you can run the following code to install it and load it into your R session:

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

Next, you should create a file where you will write all of your R Markdown code. This file should have a “.Rmd” file extension. For example, you can call your new file rmdexample.Rmd. This file will contain R code and markdown code and will make it easy for you to create a report.

The first part of every R Markdown file is called the header, and it contains important information about the title, author, and format of your report. The header begins and ends with three dash characters together (“—”). Here is an example header:

---
title: "TPS Report"
author: Lawrence
date: April 7, 2023
output: html_document
---

Now that you have a header, you’re already ready to create, or “render”, your report. You can render it with the following command:

rmarkdown::render("rmdexample.Rmd")

After you run this command, you’ll see (in whatever directory you’re using to run R) that there’s a new file called “rmdexample.html”. This is the report that you’ve created with your R Markdown code, and you’ll see that it looks like this:

TPS Report
Lawrence
April 7, 2023

It’s nothing more than a title, author, and date, because that’s the only content in your Rmd file (remember, the only thing in your file is the header). It has been output as an HTML file because that’s the type of output you specified in your header.

Now that you can create a header for your report, you will want to add content. Try to add the following text below the header in your Rmd file:

# Useful R Markdown Information
Here are some characters you should know about:
*You can use the "#" character to create a section title.
*You can use the "*" character to create a bullet point.

Let’s look at how the report appears if we render the document again by running rmarkdown::render(“rmdexample.Rmd”):

TPS Report
Lawrence
April 7, 2023
Useful R Markdown Information
Here are some characters your should know about:

  • You can use the “#” character to create a section title.
  • You can use the “*” character to create a bullet point.

You can see that the “#” character, when used at the beginning of a line, creates larger text that can be used for a section title. Also, the “*” character, when used at the beginning of a line, creates a bullet point.

The best thing about R Markdown is that we can add R code to reports in addition to simple text. For example, if we want to create and describe a data frame in the report, we can add displayable R code for it by adding the following to the end of the Rmd file:

```{r}
names <- c("peter", "milton", "michael", "samir")
red_staplers <- c(0, 1, 0, 0)
dataframe <- data.frame(names, red_staplers)
print(dataframe)
```

Here, the “`{r} text indicates that a section of pure R code is beginning, and the “` characters indicate that the pure R section is ending. In between, we’ve defined and printed a simple data frame. If you render the report now, you’ll see that it looks like this:

TPS Report
Lawrence
April 7, 2023
Useful R Markdown Information
Here are some characters your should know about:

  • You can use the “#” character to create a section title.
  • You can use the “*” character to create a bullet point.

names <- c("peter", "milton", "michael", "samir")
red_staplers <- c(0, 1, 0, 0)
dataframe <- data.frame(names, red_staplers)
print(dataframe)

## names red_staplers
## 1 peter 0
## 2 milton 1
## 3 michael 0
## 4 samir 0

You can see that with R Markdown, we can combine both descriptive text and code, in a readable style, in common file formats like HTML.

As you learn more about R Markdown, you’ll learn to add other beautiful text and code to your reports. For example, you can add math, such as the following text, to your report:

# Math Section

$E = m \cdot c^{2}$

Here, the “$” character indicates the beginning of text that should be formatted as a mathematical expression. The “\cdot” is a shortcut referring to a dot that  indicates multiplication. If you render this in your report, you’ll see that it looks like this:

Math Section
E = m*c2

Congratulations, you can create beautiful, readable, code-based reports using R Markdown. If you’d like to know more about R Markdown, or other topics related to using R for data science, you should explore Udacity’s Programming for Data Science with R Nanodegree.