Chapter 6 R Markdown for reporting
In this session, we will learn how to use R Markdown to incorporate report writing and data analysis.
6.1 Conventional ways of reporting analysis results
So far, we have run R analyses and produced results either in the console window, or as exported files. To write a report, we would typically start with a Word processing document, and incorporate our results through copying and pasting into our report document. Such a process is not only time-consuming, but also error-prone. R markdwon enables us to combine the process of writing a report and incorporating the analysis results in the report, in one single step. In this way, anyone who has our data files can produce exactly the same report with the press of one button. This is called reproducible research.
6.2 Resources on R markdown
An excellent resource for R markdown is the the book R Markdown: The Definitive Guide (Xie, Allaire, and Grolemund 2021). Here is the online link.
Another resource is from R Studio on R Markdown, as well as the R markdown cheat sheet.
6.3 What you need to install for running R markdown
First, you need to install the rmarkdown package. This enables you to produce your report in HTML format which can be viewed in an internet browser.
If you also want to produce a pdf version of the report, you will need to install TinyTeX through using the following two commands in R:
install.packages('tinytex')
tinytex::install_tinytex() # install TinyTeXI have also installed the knitr package to use some functions provided, particularly for table outputs.
In summary, install rmarkdown, tinytex and knitr.
6.4 Getting started with R markdown
In R Studio, under the File menu, start a new R Markdown file. File –> New File –> R Markdown
You can fill in the title and the author’s name. Let’s leave the output as HTML. Save the file by giving it a name (without extension). R will automatically give the file name an extension of Rmd, for R markdown files.
Just above the editing window in R Studio, there is a Knit button with an icon of a ball of wool with a knitting needle. Press this button. This is a demonstration file. It shows how you can mix texts and R code in a R markdown document.
To write our own R markdown file, you can delete everything in this file except for the header (known as YAML)
-–
title: “Test R Markdown”
author: “MWU”
date: “21/11/2021”
output: html_document
-–
and start to write our own R markdown document.
6.5 Write our first R markdown document
To make a heading, type #s. Check out R markdown cheat sheet. Everything you type here will be displayed in your report, just like a word processor.
End a line with two spaces to start a new paragraph.
We will analyse the numeracy data provided by the R package TAM.
To do that we will need to run some R code.
To run R code in R markdown, we need to enclose the R code inside a R code chunk starting and ending with three back-ticks `.
```{r }
some R code here
``` Check R code chunk options such as echo, result, message etc on the R markdown cheat sheet, and also at this site.
Inline R code can be enclosed by a single back-tick such as `r some R code here `. In summary, we mix texts and R code in a R markdown document. The R code will be evaluated when the report is produced.
The following is our first R markdown file.
---
title: "Test R Markdown"
author: "MWU"
date: "21/11/2021"
output: html_document
---
```{r echo=FALSE, results='hide', warning=FALSE, message=FALSE}
rm(list=ls())
library(TAM)
library(CTT)
library(WrightMap)
library(knitr)
data(data.numeracy)
resp <- data.numeracy$scored
IA <- itemAnalysis(resp)
mod1 <- tam.jml(resp)
tamDistr <- tam.ctt(resp,mod1$WLE)
```
## Analysis of data set
In this data set, there are `r mod1$nitems` items and `r mod1$nstud` students.
The CTT test reliability is `r IA$alpha`.
The following is a table of CTT item analysis.
```{r echo=FALSE, comment=NA}
kable(IA$itemReport)
```
The following is a table of IRT item difficulties.
```{r echo=FALSE, comment=NA}
kable(mod1$item1)
```
The Wright Map is shown below.
```{r echo=FALSE}
p <- wrightMap(mod1$WLE,mod1$xsi,item.side=itemClassic)
```
The TAM distractor analysis is shown below
```{r echo=FALSE}
kable(tamDistr)
```
The IRT item characteristic curves are plotted below.
```{r echo=FALSE, results='hide'}
plot(mod1)
``` Copy the above lines and save them as a Rmd file. Knit the file. An HTML output file should be produced. In the header (YAML), change the word “html” to “pdf” and re-knit the file. A pdf file should be produced. Similarly, change “pdf” to “word.” A Word document should be produced.
6.6 Exercise 1
Change the R markdown file to read in the data file data.sim.rasch, and knit the Rmd file.
6.7 Exercise 2
Use the R markdown file to analyse the CTTdata provided by the CTT package. Remember to score the data file. When running the tam.ctt function, use the raw data file instead of the scored data file. For example,
data(CTTdata)
data(CTTkey)
s <- score(CTTdata,CTTkey, output.scored = TRUE)
resp <- s$scored
IA <- itemAnalysis(resp)
mod1 <- tam.jml(resp)
tamDistr <- tam.ctt(CTTdata, mod1$WLE)6.8 Exercise 3
Use the R markdown file to analyse the Grammar data set in section 5.4
6.9 Homework
Use the R markdown file to analyse the numeracy test B1 in Section 5.2.