以 R Markdown 輕鬆編輯資料分析報告(上)

一位好的資料科學家除了要能掌握資料分析的方法,也要懂得將分析結果清楚的傳遞給其他人。依據不同的角色對象,資料科學家必須採取不同的溝通策略,通常愈是在管理上層的人,所需要知道的技術細節就愈少,只需要將分析方法簡要說明,溝通應該要著重在會影響決策的關鍵結果和發佈這個結果可能帶來的利弊。而也有時,其他團隊成員須要了解特定環節的技術細節,這時候,程式碼的可再現性 (reproducibility) 就非常重要,且需要添加適當的註解來幫助讀的人能更容易理解程式的內容。

透過 R 進行資料分析,可以使用 R Markdown 一次達到程式碼的可再現性及添加文字說明的兩個目的。剛接觸 R Markdown 時有種相見恨晚的感覺,以前交作業報告,都得把程式碼複製到 word 去編輯,為了增加易讀性,還得花上好些時間來設定標題、內容和程式碼的格式。編輯 R Markdown 可以直接在 R Studio 當中進行,一邊寫 R code 一邊編輯分析報告時,也不需要在不同的軟體中進行切換,且上手時間相當短,特別是有 markdown 基礎的人要學起來會更加容易。

來看看 R Markdown 長什麼樣:

09

本篇會先進行基本的 setup、操作和編輯方法,並且生成一個 html/ docx 形式的分析報告。稍稍進階的內容,包括轉存成 pdf 檔、插入數學公式等,會在以 R Markdown 輕鬆編輯資料分析報告(下)當中整理給各位。那麼,就開始吧!

環境設定


install.packages("rmarkdown")
install.packages("knitr")

試著開啟一個 Markdown 檔案,若 rmarkdownknitr 尚未安裝,它會指示你進行安裝。若安裝失敗,可能與 dependency 的其他 package 沒有正確安裝有關,只需要手動安裝並更新這些 package 即可。

01

開始一個 R Markdown 專案

R Markdown 除了可以製作文件形式,也可以做成簡報形式,在此我們先選擇 Document 文件形式。

02

開啟檔案會看到範例內容:

03

生成基本的HTML 報告形式

這時點選 Knit HTML,系統會存檔並進行 knit 的動作(類似於 compile),在工作目錄中生成 .html 及 .Rmd檔。在下圖的 HTML 預覽畫面中,可以看到清楚的標題、 R code、results、圖表等,這樣就完成一個基本的 HTML 形式的 R markdown。

04

將報告存為 Word 檔

rmarkdown 也內建可以存取為 word 檔的功能,只要點選 knit 鍵旁邊的向下三角形就會看到選單。雖然選單中也有 knit PDF 的選項,但目前 rmarkdown 本身其實是做不到的,需要搭配其他的 package 才能做到。

學習如何編輯 R Markdown

那麼,我們就開始編輯 R Markdown 吧!一份完整的分析報告主要可以分為程式碼與非程式碼(文字段落)兩部分。由於文字段落的部分和一般 markdown 相同,我們只會簡單介紹,已經會使用 markdown 的讀者可以跳過,所以我想先來談談程式碼的部分。

報告中嵌入一個 chunk – 程式碼以及 output

前面截圖的綠框中,就是範例內容的程式碼部分,如果要插入一段程式碼,可點選右上角的 Chunks → Insert Chunk (推薦使用快捷鍵 Ctrl + Alt + I)。將會出現下面的 code,再兩行 back ticks 之間插入你要的 R code 即可,在此每段獨立呈現的 R code 稱為一個 chunk 。


```{r}

seq(10)

```

R Studio 還很貼心的將每一個 chunk 打上不一樣的底色,以便和文字做區隔,因此如果不小心少打了一個 back tick `,也很容易發現錯誤。

knit HTML 後產生之結果如下:

05

隱藏程式碼或是 output

R Markdown 預設為同時顯示程式碼與所有回傳到 console 上的訊息 (output),如果不需要將這些訊息呈現給讀者,可以在r後方加上 include = FALSE (不顯示程式碼及 output)、echo = FALSE (僅顯示output,不顯示程式碼)或 results = "hide" (僅顯示程式碼,不顯示 output)的參數。例如,include = FALSE 常用於載入 packages 時,我們不需要呈現這些載入封包的訊息在分析報告中。


```{r echo = FALSE}
seq(10)
```

產生之結果如下:

06

如果通篇報告的 chunk 呈現方式類似,我們也可以設定 global chunk,概念類似於投影片母片,不必對每個 chunk 一一重新設定,但在此我們先不介紹,這些進階的參數設定會在以 R Markdown 輕鬆編輯資料分析報告(下)當中說明。

載入封包和資料檔

需要注意的是,R Markdown 檔案是一個獨立的檔案,也就是說,報告中所需要呈現的內容,都必須要是這個檔案可以獨立生成的內容。如果分析方法使用到某些 packages 或是必須載入某些資料檔,都必須要在 Markdown 檔案中寫入這些載入封包或資料的程式碼。

載入 package 可以使用 require(),不清楚為何標準作法的 library() 在此無法使用。

載入資料檔的路徑可以使用相對路徑或絕對路徑,若使用相對路徑,為相對於目前工作目錄的路徑。如果要設定工作目錄可以使用 setwd() 或是透過 R Studio 的 Session → Set Working Directory → Choose Directory 選擇目錄。

混寫文字與程式碼在同一段落中 (In line code)

如果不想讓程式碼換行單獨呈現,而是要夾在文字段落中,使用一組單個 back tick 就可以做到。這種寫法適用於單行的程式碼,或是在文字中提到變數名稱時,能讓讀者一眼就分辨出這是變數的名稱而非段落文字的一部分。

 We want to create a sequence using `seq()` function 

產生之結果如下:

07

測試 chunk 中的程式碼

在編輯 R Markdown 的過程中,我們會需要確認每段 chunk 是否成功產出我們預期中的結果,但如果每一次都要 knit,會花費太多不必要的時間和系統資源的浪費,我們可以將游標點選在想要測試的 chunk 中任何一個位置,再到 Chunks 選單中,點選 Run Current Chunk (推薦使用 Ctrl + Alt + C),程式運作的結果就會顯示到console 中。這個方式就很像編輯 R的時候將一個段落丟進 console 裡(或按 Ctrl + C)一樣。

報告中的文字段落

這其實是最簡單的部分,和一般的 markdown 編寫方式並無二致,以下舉例說明常用的 markdown,想知道更多的讀者,R Studio 中的「Markdown Quick Reference」有清楚的說明,或是自行 google markdown 這個關鍵字,會有很多的相關資料可以學習。


# Markdown 範例

Markdown 讓你用 **最簡便的方式** 來編輯 _清楚整齊的文件_。

你可以條列文字內容:

- 像這樣是第一點
- 然後是第二點

也可以加上數字來條列

1. 這樣是不是更清楚了呢?
2. 這是第二點

也可以顯示連結[R Markdown](http://rmarkdown.rstudio.com)。是不是非常簡單呢?

產生之結果如下:

08

有了這些,讀者現在應該可以自行做出一份簡單但完整的 HTML/ docx 形式的 R markdown 分析報告了!快動手試試看吧!

發表迴響

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com 標誌

您的留言將使用 WordPress.com 帳號。 登出 /  變更 )

Google photo

您的留言將使用 Google 帳號。 登出 /  變更 )

Twitter picture

您的留言將使用 Twitter 帳號。 登出 /  變更 )

Facebook照片

您的留言將使用 Facebook 帳號。 登出 /  變更 )

連結到 %s