第 6 章 透過R Markdown來撰寫分析報告

在本節中,我們將會學習如何用R Markdown 將資料的分析結果納入報告的撰寫中。

6.1 傳統撰寫分析結果報告的方式

到目前為止,我們初步學會進行 R 分析,並將結果透過視窗呈現或是輸出成為檔案。至於要撰寫報告,我們通常會利用Word打開一個文件,並將我們分析的結果透過複製與貼上的方式整合到Word的文件中。這樣的過程不只耗時,也容易出錯,R Markdown可以讓我們只透過一個步驟,就能結合撰寫報告並將分析的結果一起輸出到報告內。這樣,任何人只要獲得我們的資料檔只需要按一個鍵,都能產生出完全相同的報告,這樣處理的方式可以稱之為可重複地研究。

6.2 R markdown 的資源

R Markdown: The Definitive Guide (Xie, Allaire, and Grolemund 2021)這本書是關於 R Markdown非常好的參考資源,可詳見[以下的連結] (https://bookdown.org/yihui/rmarkdown/)。

其他參考資源包括R Studio on R MarkdownR markdown cheat sheet

6.3 如何安裝以及運行R Markdown

首先,你需要安裝 rmarkdown 套件,該套件可讓你產出在網際網路瀏覽的 HTML 格式報告。

如果你也想產出 pdf 格式的報告,你需要在 R 環境中用下列兩個指令來安裝 TinyTeX

install.packages('tinytex')
tinytex::install_tinytex()  # 安裝  TinyTeX

此外,我還安裝了 knitr 套件,該套件提供了我需要的功能,尤其是表格輸出。

總而言之,請安裝 rmarkdown 、 tinytex 以及 knitr 套件。 

6.4 初步瞭解 R Markdown 的運作

在 R Studio 的檔案選項中,請開始一個新的R Markdown的介面,程序為File –> New File –> R Markdown。

你可以填寫標題以及作者名稱,暫時讓報表以 HTML 的格式輸出,並設定好輸出檔案的名稱,該名稱不需要任何的副檔名, R 會自動會以 Rmd 做為副檔名,來稱呼所有 R Markdown 的檔案。

在 R Studio 編輯視窗上方有一個 Knit 按鍵,它是一個毛球形狀的圖標,請按此按鍵,它是一個示範檔,會示範在 R Markdown 檔案中如何結合文本以及 R 編碼。

如果你要嘗試編寫一個 R Markdown 檔,你可以刪除該檔案中所有的內容,除了以下這六行,我們稱此為一個標題(header),亦稱為YAML。

-–
title: “Test R Markdown”
author: “MWU”
date: “21/11/2021”
output: html_document
-–

接著在其下開始編寫自己的 R Markdown 檔案。

6.5 撰寫第一個 R Markdown 檔案

先製作標題名稱,請輸入 #s 。請參考 R markdown cheat sheet。所有你輸入的都會呈現在你的報告中,就像是在使用一個文書處理器。

請在一行的結束加上兩個空白鍵,以開始一個新的段落。

我們將分析 TAM 套件所提供的數感資料(numeracy data)。

為此,我們將會執行一些 R 編碼。

要在 R Markdown 中執行 R 指令,我們需要將R指令放在一個 R指令群(R code chunk) 中,而R 指令群是指一組指令,可以直接將分析的結果在報告中呈現,它的開始要用三個反引號 ` ,它的結束是另外三個反引號 ,如下所示:

```{r } 
  請輸入你想要的 R 指令  
``` 

請參考 R markdown cheat sheet 以及 this site 兩份文件中的說明,並確認 R 指令群相關的選項如 echo、 result、 message等。

直接插入的 R 編碼可以使用一個反引號來進行,例如 `r 請輸入你想要的 R 指令 ``` 。綜合而言,我們在 R Markdown 檔案中混合了文本以及R 的編碼,當執行R的編碼時,其結果會直接輸入並呈現在報告中。

以下我們示範一個完整的 R Markdown檔案。

---
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)
```  

## 分析資料集
在這個資料集中,它有 `r mod1$nitems` 個題目,以及 `r mod1$nstud`  個學生,其古典測驗理論的信度係數為 `r IA$alpha`.


以下用列表的方式呈現古典測驗理論的題目分析結果。

```{r echo=FALSE, comment=NA}
kable(IA$itemReport)
```

以下用列表的方式呈現題目反映理論的題目難度資訊。 

```{r echo=FALSE, comment=NA}
kable(mod1$item1)
```  

以下呈現能力與難度對應圖:

```{r echo=FALSE}
p <- wrightMap(mod1$WLE,mod1$xsi,item.side=itemClassic)
```  

以下呈現 TAM 套件的誘答選項分析結果:

```{r echo=FALSE}
kable(tamDistr)
```

以下將繪製出題目反映理論的題目特徵曲線圖。

```{r echo=FALSE, results='hide'}
plot(mod1)
```  

請複製上列幾行編碼,並將它們儲存成 Rmd 檔。將這檔案 Knit 起來,它應該會生成一個 HTML 輸出檔。接著你可以在標題(YAML)中,將”html”改為”pdf”,並重新 Knit 該檔案一次,它將會產生一個 pdf 的輸出檔。同樣地,若將 “pdf” 改成 “word”,就可以另存一個Word的輸出檔。

6.6 Exercise 1 練習1

請將 R Markdown 檔案改成可以讀取 data.sim.rasch 的資料檔,並將該檔案儲存成Rmd 檔,然後再knit一次。

6.7 Exercise 2 練習2

使用 R Markdown 檔案來分析 CTT 套件中的 CTTdata,記得要先將資料檔做評分。然而,當執行 tam.ctt 的功能時,則需要使用原始數據資料檔,而非評分過後的資料檔。例如:

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 練習3

請使用 R Markdown 檔案來分析在5.4節中提到的 Grammar 資料集。

6.9 Homework 回家作業

請使用 R Markdown 檔案來分析在 5.2 節中提到的數感測驗 B1。

References

Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2021. R Markdown: The Definitive Guide. https://bookdown.org/yihui/rmarkdown/.