Part 09: Making a report

Instructions on this page are general to use of R and apply to R used on local computer or to users of R in Google CoLab.

Learning objectives

• Create reproducible PDF reports using Markdown and RMarkdown.
• Edit and customize report content within a markdown document.
• Render and export reports efficiently from R, R Commander, or Google CoLab.

What’s on this page?

1. Reports and RMarkdown
2. How to generate a report
3. Some basic Markdown
4. Generate the report
5. To do on your own
6. Quiz

What to do

Work through the examples to learn how create and generate reports for your homework within R Commander. Although you can copy/paste to a word document, insert images, edit, then save to a pdf, this is an inefficient and error-prone process. Far better to struggle a bit to learn RMarkdown, the benefits later with more challenging homework, will be worth the effort.

For those of you working with Google CoLab, generating a report is straightforward. You’ve already learned how to start and enter code via the + Code button; for text, simply click + Code button in the CoLab toolbar and add your notes or responses to homework questions.

How to do it

For these exercises, you may work

• within the Rcmdr script window
• RStudio
• Google CoLab

Choose one way. The quickest way is to just work with R Commander, but RMarkdown was designed to work with RStudio.

Markdown and Jupyter Notebooks, like those used in Google CoLab, work well together.

Let’s begin.

1. Reports and RMarkdown

An important component of your work in this class is to make reports. Homework will be submitted as pdf reports. PDF files have the advantage that they maintain formatting so that documents appear the same on any device. Moreover, pdf documents are harder to manipulate compared to Word documents, which maintains the integrity of homework. Thus, it is an important skill to learn, how to generate pdf reports from your work in statistics. Although it is simple enough to copy and paste your work from R into a word document, then generate a pdf — and you have likely done this many times before — I want you to learn the advantages of Markdown when creating technical reports.

R Commander (and RStudio) use RMarkdown, which does a great job of capturing and presenting your work with a minimum of effort. RMarkdown is a version of Markdown, a markup language to help you create formatted text using a plain-text editor (see Wikipedia).

Markdown is a hugely important innovation. While you can copy and paste your work from R output to Word document — which is something we used to do — the advantage of RMarkdown is it preserves your code. In practice then, you can run code from a Markdown Report — an advantage for producing reproducible code. RMarkdown helps us avoid this copy/paste step to a different app, and does much better at preserving the work we do in R, as you will quickly learn if you try and rely on the copy/paste route!

CoLab, skip this step. In R Commander, once you are ready to generate a report, click on the R Markdown tab (blue arrow) to bring up the Markdown text window (Fig 1).

Figure 1. R Markdown text window

2. How to generate a report

CoLab, skip this step. Good practice tip: When you first open R Commander, click on the R Markdown tab and replace title: and author: with a descriptive title for your report and your name (leave the quotes) (Fig 1).

----
title: "My report"
author: "Mike Dohm"

Then, click on the R Script tab and proceed with work on your R project.

At the conclusion of your work, click on the R Markdown tab and scroll through your text. You can delete or add text as you please. To retain R commands and output, just don’t edit anywhere between ```{r} and ```

```{r}
[some R command]
```

making changes to the markdown template (e.g., adding additional text to answer questions, etc.), then click Generate report (Fig. 1, red arrow)

3. Some basic Markdown

While you can copy/paste from R output to Google Doc or MS Word, I want you to use RMarkdown to craft your responses to homework. RMarkdown captures your script and R output in one form; it is simple to insert your own text. The result is a single organized document. I do expect you to remove “mistakes” (incorrect function calls because of typos, etc.,) from your R Markdown text before you generate a report. Your work will look better if you apply a bit of Markdown syntax. Alternatively, you can use html syntax — Markdown is just simple text. While you can do all of the edits you need within the Rcmdr editor, many useful Markdown editors available (e.g., PanWriter, MarkText), which makes working with Markdown files simple once you get used to looking at the markdown language.

Really, to make an elegant report, all the “markdown” you need is how to include headings. In html-CSS, headings are coded with tags (Table 1).

Table 1. html-css tags with markdown equivalents

the basics you need to know are

• code blocks
• headings
• insert image
• lists (ordered and numbered)

We’ll improve with markdown as the semester unfolds, but I recommend you start with one of many free online tutorials, e.g., https://www.markdowntutorial.com/

Here, I’ll step you through a mock homework. The mock homework questions

CoLab, skip this step. Question 1. When you exit R and Rcmdr, you are prompted to save a number of files. Make two lists: files exit from Rcmdr, files exit from R.

CoLab, skip this step. Question 2. Which file(s) capture all of your work, including mistakes?

Hint: See Part 10: Exiting R and Rcmdr

Question 3. Load the dataset DNase (package dataset) and make a scatterplot of density by conc, include by groups.

Here’s my markdown script. Text I entered into the markdown script file marked in yellow.

---
title: "Part 09: Making a report"
author: "Mike Dohm"
date: "`r Sys.Date()`" # Uses current date
---


```{r echo=FALSE, message=FALSE}
# include this code chunk as-is to set options
knitr::opts_chunk$set(comment=NA, prompt=TRUE)
library(Rcmdr)
library(car)
library(RcmdrMisc)
```


```{r echo=FALSE}
# include this code chunk as-is to enable 3D graphs
library(rgl)
knitr::knit_hooks$set(webgl = hook_webgl)
```

### Question 1

#### Exit Rcmdr only

1. script file
2. R Markdown file
3. Output file

#### Exit R
1. Workspace image

### Question 2

Workspace image. Available in .Rhistory

### Question 3

```{r}
data(DNase, package="datasets")
```

```{r}
scatterplot(density~conc | Run, regLine=FALSE, smooth=FALSE, boxplots=FALSE,
by.groups=TRUE, data=DNase)
```

### End of report

The rendered document from this markdown script is shown in Figure 3. Note I used html (<h3>, <p>) and Markdown (ordered list). Note the simple way to hide R function calls, just a little markdown code

```{r echo=FALSE}

above the command hides the command, whereas

```{r}

ensures that the commands are printed.

I do encourage you to explore Markdown — it’s really handy and simple to learn. You can use the editor included in Rcmdr (or RStudio, which is really nice for generating markdown reports), or you can copy the script into your favorite text editor (e.g., Notepad, TextEdit), make your changes, then copy back to Rcmdr before rendering. See https://en.wikipedia.org/wiki/Markdown#Example for some suggestions. A nice tutorial is available at https://www.markdowntutorial.com/.

4. Generate the report

Submit homework in BI311 as pdf files. The expectation is that you work with RMarkdown.

For full function, pandoc and LaTeX installed on your computer is recommended. Check by clicking on Rcmdr: Tools > and look for a submenu choice: Install other software (if you don’t see this option it means you already have pandoc and LaTeX available on your computer).

Figure 2. Screenshot of format options available for a computer with working LaTex and pandoc.

Figure 3. Screenshot of rendered RMarkdown script for the mock homework.

5. To do on your own

Repeat my mock homework to confirm you can generate a markdown file that looks like mine.

Select work done from any one (or more) of the lessons on R and R Commander, make an R Markdown report, and export as a pdf file.

Part 03. Explore use of R

Part 04. Create functions in R

Part 05. R packages: Making R do more

Part 06. Work with an included dataset

Part 07. Working with your own data

Part 08. Data exploration

6. Page quiz

draft, more questions soon

Reports

Five questions from this page

Start Quiz

Question

Your answer:

Correct answer:

Next

Please wait..

↺

You got {{SCORE_CORRECT}} out of {{SCORE_TOTAL}}

Your Answers