R for UX Researchers Series: Article #12

Tutorial: Creating Reports with RMarkdown

Summary: Learn how to create updateable and interactive HTML reports using RMarkdown. This method efficiently tracks longitudinal data, ensuring your reports are consistently updated with minimal effort. This tutorial covers setting up your environment, knitting RMarkdown into HTML, and customizing reports for stakeholder needs.

---

What You’ll Be Doing

At the end of the tutorial, you will have created this report. Take a look at each section below, and then let’s start deconstructing this thing!

What is RMarkdown and Why Use It?

RMarkdown is a tool for creating reports in R. Imagine being able to blend your R code seamlessly with narrative text and explanatory images. That's what RMarkdown does, making it perfect for generating reports that include both analysis and context.

One of RMarkdown’s best features is its ability to create reproducible reports. If you're working with longitudinal data, tracking information over time, RMarkdown is incredibly efficient.

Instead of creating one-off reports for each data update, you can simply run your RMarkdown script again, and it will generate a fresh report with the latest data.

Another great advantage is how RMarkdown lets you combine various types of content in a single document. You can include different R analyses, create multiple plots, and even add non-R content like images, links, and custom text. This flexibility makes it a powerful tool for compiling all your insights into one stakeholder-friendly report.

RMarkdown also facilitates sharing. It produces an HTML file, which is easy to share and view on any web browser. Plus, updating your report is as simple as re-running the script, making it great for ongoing projects and collaborations.

Now that you understand the value of RMarkdown, let’s get into it, shall we?

Prerequisites

Before starting the tutorial, ensure you have completed the basic setup for R and RStudio as described in the "Getting Started with R & RStudio Tutorial." Additionally, if you are using Windows, you will need to install Rtools.

Step 1: Install RMarkdown

Install the RMarkdown package by running the following command in your RStudio Console:

install.packages("rmarkdown")

You’ll know you have done this correctly if your Console pane looks something like this.

Step 2: Creating a RMarkdown File

1. Go to File > New File > RMarkdown....

   

2. A dialog box will appear. Fill in the details:

   • Title: "RMarkdown Tutorial"

   • Author: "UX Researcher"

   • Document type: Select "HTML"

   • Click OK.

✏️ NOTE: Your new RMarkdown file will have a YAML header at the top that looks like this:

3. Place your cursor below the YAML header, select everything below the YAML header and delete it. Your RMarkdown pane will look something like this:

If done correctly, a RMarkdown pane will appear above the Console pane.

Step 3: Setting Up Your Environment

Add a Setup Code Chunk:

1. Place your cursor below the YAML header in the RMarkdown pane.

2. Click the Insert button in the toolbar and select R to add a new R chunk.

   

   💡 Keyboard Shortcut Pro Tip: Creating an R code chunk

   • Windows/Linux: Ctrl + Alt + I

   • Mac: Cmd + Option + I

3. In the new chunk, copy and paste the following code to create a setup code chunk:

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, warning = FALSE, message = FALSE)
library(ggplot2)
library(plotly)
```

You’ll know you have done this correctly when you see a new R chunk in gray in the RMarkdown pane.

✏️ NOTE: This setup code chunk sets global options for your R chunks and loads the necessary libraries for creating plots and interactive visualizations. The echo = FALSE, warning = FALSE, and message = FALSE options ensure that the code, warnings, and messages are not displayed in the final HTML document.

4. Knit Your RMarkdown into HTML:

   To convert an RMarkdown document into an HTML file, you’ll need to do a process that RStudio calls “knitting.”

   • Click the Knit button in the toolbar.

💡 Keyboard Shortcut Pro Tip: Knitting the document

• Windows/Linux: Ctrl + Shift + K

• Mac: Cmd + Shift + K.

You did it! You just created, your first report using RMarkdown! Your HTML report should look something like the screenshot below.

Now, let’s add content to this blank report. Woot, woot!

Step 4: Using a Code Chunk to Add Content

Now we will add a standard code chunk to create a static plot.

1. Add a Code Chunk for Data Preparation:

   • Place your cursor below the setup code chunk you created in Step 3.

   • Add a new R chunk by clicking the Insert button in the toolbar and selecting R.

   • Copy and paste the following code:

# Create sample data
set.seed(123)
months <- rep(seq.Date(from = as.Date("2024-01-01"), to = as.Date("2024-12-01"), by = "month"), each = 10)
satisfaction <- rnorm(120, mean = 70, sd = 10)
category <- rep(c("A", "B", "C", "D", "E"), each = 24)
data <- data.frame(months, satisfaction, category)

2. Add a Code Chunk for Static Plot:

   Below the data preparation chunk you just created, insert a new R chunk. When you see the gray code chunk appear, copy and paste the following code:

# Plot user satisfaction over time with categories
ggplot(data, aes(x = months, y = satisfaction, color = category)) +
  geom_line(aes(group = category), size = 1.2) +
  geom_point(size = 3) +
  scale_color_manual(values = c("#648FFF", "#785EF0", "#DC267F", "#FE6100", "#FFB000")) +
  labs(title = "User Satisfaction Over Time: Static Plot",
       x = "Month",
       y = "Satisfaction Score",
       color = "Category") +
  theme_minimal() +
  theme(plot.title = element_text(hjust = 0.5, face = "bold"),
        axis.title = element_text(face = "bold"))

3. Knit These Two Chunks:
   Like before, click the Knit button in the toolbar to add the plot:

Step 5: Adding a Table

Next, we will add a table summarizing the data.

1. Add a Code Chunk for the Table:
   Below the static plot chunk you just created, insert a new R chunk. When you see the gray code chunk appear, copy and paste the following code:

# Create a summary table
summary_table <- data.frame(
  Category = c("A", "B", "C", "D", "E"),
  Count = c(24, 24, 24, 24, 24),
  Mean_Satisfaction = round(c(mean(satisfaction[category == "A"]),
                             mean(satisfaction[category == "B"]),
                             mean(satisfaction[category == "C"]),
                             mean(satisfaction[category == "D"]),
                             mean(satisfaction[category == "E"])), 2)
)
knitr::kable(summary_table, col.names = c("Category", "Count", "Mean Satisfaction"))

2. Knit This Chunk:
   Click the Knit button in the toolbar to add the table:

Pretty simple, right? I hope you're starting to see how versatile code chunks are.

Step 6: Customizing Your Report

You can add all kinds of non-R related content into your RMarkdown reports like images, links, other app’s tables, and custom text. Let’s demonstrate this by adding an image with explanatory text:

1. Add a Header and Body Text Above the Image:
   Below the table code chunk you just created, copy and paste the code below straight into the RMarkdown pane.

🚨 IMPORTANT: Do not create another code chunk. Just simply put it in as regular code.

# Your Image's H1
You can add explanatory text here as well.

✏️ NOTE: Remember to replace "Your Image's H1" with the H1 label you’d like displayed in your report. I’m replacing it with the word "Persona" because that’s the image I want to include in my report.

Also, remember to replace the "You can add explanatory text here as well." with any contextual information you might want to help stakeholders understand the custom content you are including. I’m replacing it with this blurb: “For this study, all respondents were from our 'Collaborator' persona group.”

2. Add a Code Chunk for Including the Image:

   Below the regular Header and Body text code you just added, insert a new R chunk. When you see the gray code chunk appear, copy and paste the following code:

   knitr::include_graphics("path/to/your/image.png")

   ✏️ NOTE: Remember to replace "path/to/your/image.png" with the actual path and file name of the image you’ll be using in this tutorial. I changed mine to "C:/Users/Trevo/Desktop/Example_Persona.png" to reflect my file’s location and name.

   

3. Knit This Chunk:
   Click the Knit button. You should see something like this but with your own Header and Body text and Image.

Step 7: Rendering Interactive Plots

To make the plot interactive, we will use the plotly package. But first, let’s add some context.

1. Add a Header and Body Text Above the Interactive Plot:

   Now that we know how to add contextual Header and Body text from Step 6, let's do that for this last chunk. Copy and paste the following code directly into the RMarkdown pane. It should look like this:

# Interactive Plot
Hover over the points to explore the data further.

🚨 IMPORTANT: Remember, do not create another code chunk. Just simply put it in as regular code.

2. Add a Code Chunk for Interactive Plot:
   Below the add image code chunk you just created, insert a new R chunk. When you see the gray code chunk appear, copy and paste the following code:

# Create interactive plot
p <- ggplot(data, aes(x = months, y = satisfaction, color = category)) +
  geom_line(aes(group = category), size = 1.2) +
  geom_point(size = 3) +
  scale_color_manual(values = c("#648FFF", "#785EF0", "#DC267F", "#FE6100", "#FFB000")) +
  labs(title = "User Satisfaction Over Time: Interactive Plot",
       x = "Month",
       y = "Satisfaction Score",
       color = "Category") +
  theme_minimal() +
  theme(plot.title = element_text(hjust = 0.5, face = "bold"),
        axis.title = element_text(face = "bold"))
ggplotly(p)

3. Knit This Chunk:
   Click the Knit button. You should see something like this:

Conclusion

Congratulations! You've successfully created a report using RMarkdown. Throughout this tutorial, you've learned how to:

1. Set up your RMarkdown environment.

2. Create and customize static and interactive plots.

3. Add tables to summarize your data.

4. Integrate non-R content like images and explanatory text.

I hope this tutorial has demonstrated the versatility and power of RMarkdown. By integrating R code with narrative text and various types of content, you've created a dynamic, reproducible report that can be easily updated with new data.

Imagine sharing this with a stakeholder: they can interact with the visualizations, understand the context, and make data-driven decisions based on your findings.

Updating your report is as simple as re-running the script with your latest data, ensuring your insights are always current and relevant. This approach not only saves time but also ensures consistency and accuracy across your reports. In a tech organization, knowing tools like RMarkdown can transform the way you present data, making your workflow wayyyyyyy more efficient and your reports more impactful.

In my experience, creating reports like these can drive your organization toward becoming more data-driven and user-centric. Now that you have the skills to create these reports, I encourage you to start integrating RMarkdown into your own work. Trust me, your stakeholders will appreciate the clarity, interactivity, and professionalism that RMarkdown reports bring to the table.

Feedback

I hope you found this tutorial helpful. If you have any questions, suggestions, or feedback, please feel free to reach out. Your input is valuable in helping me improve the articles in this series.

Thank you for following along!

---