logo

1 R-Markdown 簡介

       Markdown 是現代軟體開發者以及資料科學團隊必備的輕量型標記式語言，其創始人為 John Gruber。透過 Markdown，研究者可以撰寫出易於閱讀與記錄的純文字檔 (副檔名為 .md)，並透過 pandoc 將其輸出成常見的靜態或動態檔案格式。而 R-Markdown 為 RStudio 軟體工程式謝益輝 (Yihui Xie) 依據 Markdown 所發展出的標記式語言 (副檔名為 .Rmd)，除了具備 Markdown 的特性外，還可以執行 R 代碼區塊 (R chunks)。因此，研究者只要維護一個 R-Markdown 檔案就能透過 knitr 套件將文字、R 代碼與 R 的執行結果轉換成不同檔案格式 (如 PDF、Word、HTML、Beamer、Shiny 等)，以達到重複性研究 (reproducible research) 的目的。本節的主要是簡介 R-Markdown 的基本語法，所有的操作過程與原始碼均會在課堂中加以說明。


2 R-Markdown 架構

       R-Markdown 的架構主要有以下幾個部份:

  1. YAML: YAML 原意為 Yet Another Markup Language，是用來表達資料序列化的格式語法。

  2. Markdown 語法: 主要是用來呈現文字的排版內容。

  3. R 代碼: 主要是執行 R 程式結果。

  4. 其它指令: 如交叉引用等。

以下我們分別描述之。

2.1 YAML 格式

       本文所採用的 YAML 格式如下:

---
output:
  bookdown::html_document2:
    number_sections: yes
    toc: yes
    toc_depth: 3
    toc_float:
      colapsed: yes
      smooth_scrool: yes
    fig_width: 5
    fig_height: 4
  bookdown::pdf_document2:
    toc: yes
    toc_depth: '3'
  bookdown::word_document2:
    toc: yes
    toc_depth: '3'
---

其中 html_document2, pdf_document2 與 word_document2 分別表示 HTML、PDF 與 Word 的輸出格式，而 toc 指的是目錄 (table of contents)，目前設定為 yes，並且呈現 3 層滑動的目錄形式。有興趣的讀者可以 Google 搜尋相關文章加以修改。

2.2 Markdown 指令

       Markdown 語法相當簡單，主要是以換行 (blank lines)、空格 (spaces)、縮編 (indent) 與特殊符號 (如 #) 等方式來排版文字內容。此節旨在用最簡潔的語法呈現最多元的文字形態，並介紹標題、段落以及文字與條列等三種形式的語法。首先標題可透過符號 # 來定義，其中

   #   第一級標題 (first level header)
   ##  第二級標題 (second level header)
   ### 第三級標題 (third level header)

最多可以至六級標題。

    接著我們介紹如何分段落以及強制分行。若要分段，可在兩段的文字或代碼之間空一行，其輸出結果會顯示合適的間距，以下為範例:

   分段分段分段分段分段分段分段分段分段分段

   分段分段分段分段分段分段分段分段分段分段

其輸出結果為:

   分段分段分段分段分段分段分段分段分段分段

   分段分段分段分段分段分段分段分段分段分段

若想強制換行，則在代碼的結尾添加兩個空格，

   強制換行強制換行強制換行強制換行強制換行A (兩個空格)
   強制換行強制換行強制換行強制換行強制換行B

其輸出結果為:

強制換行強制換行強制換行強制換行強制換行A
強制換行強制換行強制換行強制換行強制換行B

其中強制換行A後面有二個空格，才有強制換行的效果。分段與強制換行的差異在於前者的間距比後者大。若只是在文字中換行並且結尾沒有多加二個空格時，則輸出結果不會分段也不會換行，但會多一個空格。

   換行換行換行換行換行換行換行換行換行A (無空格)
   換行換行換行換行換行換行換行換行換行B

其輸出結果為:

換行換行換行換行換行換行換行A 換行換行換行換行換行換行換行換行換行B

至於段落開頭的文字縮排，因 Markdown 無對應的語法，所以需要透過 HTML 指令   或是   來執行結果，例如:

      
   接著我們介紹如何分段落以及強制分行。若要分段落，需要在兩段的文字或代碼之間空一行，...

其輸出結果即為本段開頭的文字格式。

    而 Markdown 常用的文字排版可透過 * 或 ~ 等符號進行格式的變化，以下為一些範例:

   斜體: *Italics*。
   加粗: **Bold**。 
   粗斜體: ***Bold-Italics***。
   刪除線:~~text~~。 
   下標: H~2~O 與 CO~2~。
   上標: E=MC^2^。
   <span style="font-family:標楷體;">標楷體。</span>
   <span style="font-family:Times New Roman;">This is a book.</span>
   <span style="font-size:13px;">16px.</span>

其輸出結果為:

斜體: Italics。加粗: Bold。粗斜體: Bold-Italics。刪除線:text。下標: H2O 與 CO2。上標: E=MC2。 標楷體。This is a book.16px.

若配合 LaTeX 語法，也可呈現非常漂亮的數學式。例如:

    LaTeX 行文數學: $y_{t} = \alpha + \beta x_{t}^{2}+\varepsilon_t$。
    LaTeX 換行數學: $$y_{t} = \alpha + \beta x_{t}^{2}+\varepsilon_t.$$

其輸出結果為:

LaTeX 行文數學: \(y_{t} = \alpha + \beta x_{t}^{2}+\varepsilon_t\)。
LaTeX 換行數學: \[y_{t} = \alpha + \beta x_{t}^{2}+\varepsilon_t.\]

文中也可以利用數字與點或是符號 *來顯示有序或無序條例 (enumerate or itemize)，其中條例內文會以縮排方式呈現，以下是一些範例:

    1. 第一條有序條例
    2. 第二條有序條例
    *  第一條無序條例
    *  第二條無序條例

該範例的輸出結果為:

  1. 第一條有序條例
  2. 第二條有序條例
  • 第一條無序條例
  • 第二條無序條例

2.3 執行 R 指令

    R-Markdown 可以透過 knitr 套件將文字、R 代碼與其執行結果轉換成常見的靜態或動態檔案格式，並且只要修改 R 的內容並執行程式，即可呈現修改後的結果。此外，透過 HTML 檔的輸出方式，研究者可馬上觀察 R 的執行結果。更具體來說，R-Markdown 有二種方式來執行 R 並且呈現其輸出結果，分別是 inline R code 以及 R chunks。首先，inline R code 是在文中直接以斜引號 (鍵盤上斜引號與 ~ 同一個鍵) 再加上代碼 r 來執行 R 函數，並在文中輸出其結果。例如:

   `r Sys.time()`

即透過函數 Sys.time() 來呈現執行此檔的時間 2024-01-21 05:30:52。而 R chunks 則是透過區塊參數 (option) 來控制 R 的執行結果與其呈現方式，以下便是一個簡單的範例:

   ```{r echo = TRUE}
      x = 1 
      y = 2
      z = exp(x+y)
      print(z)
   ```

其中第一行與最後一行的三個斜引號為 R chunks 的範圍，範圍內可以執行任何符合語法的 R 程式，而 echo = TRUE 為參數，代表程式會執行，文中也會顯示代碼與執行結果。此範例的輸出結果為:

    x = 1
    y = 2
    z = exp(x+y)
    print(z)
## [1] 20.08554

在 R chunks 中的參數選項很多，以下僅列一些參數供大家參考:

  1. echo= FALSE，會執行程式，不顯示代碼，會顯示輸出結果。

  2. echo= TRUE ，會執行程式，會顯示代碼，會顯示輸出結果。

  3. results=‘hide’，會執行程式，會顯示代碼，不顯示輸出結果。

此外，如同程式語言的邏輯，在後續內文中可以呼叫已執行過的變數。例如若我們在文中輸入 `r log(z) ` 則其結果為 3。同樣地， 我們也可以透過 R 來呈現圖形結果，例如我們可以嘗試以下指令:

   ```{r g-plot, fig.align = "center", fig.cap = "Pressure and Temperature."}
      par(mar = c(4, 4, 0.1, 0.1))
      plot(pressure, pch = 19, type = "b")
   ```

其中參數前面的 g-plot 為此 R chunks 的自訂標籤 (label)，而其呈現的圖形為

Pressure and Temperature.

Figure 2.1: Pressure and Temperature.


3 R-Markdown 應用

    R-Markdown 的應用方式很多，例如交叉引用、呈現動態圖表、鑲入網頁或是撰寫論文等。以下我們只簡單介紹這些應用方式，不一定會深入探討代碼內容。

3.1 交叉引用

    在文章中我們常會透過交叉引用 (cross-reference) 方式來快速連結其它網站或查詢文中內容。常用的引用方式包括連結其它網站資訊，引用內文的章節、圖表與 R code chunk 以及引用其它檔案等，以下只介紹其中幾種方式。首先是連結網站資訊，例如我們想連結 MFB 財務金融碩士專班，在文中的 R-Markdown 指令為:

   ...想連結 [MFB 財務金融碩士專班](https://mfb.site.nthu.edu.tw/)...

其概念為[呈現的文字](網址)，此時只要點擊 MFB 財務金融碩士專班即可連結至專班網站。其次，若我們想快速查詢第 2.2 節 Markdown 語法的內容，則必需在該節文字中加入

    ## Markdown 語法  {#command}

表示該節的標籤是 {#command}。若要引用此標籤，則指令為:

    ...查詢第 \@ref(command) 節 Markdown 語法...

因此只要點擊 2.2 即可快速查詢文中內容。同樣的概念，我們也可以透過以下指令

    \@ref(fig:g-plot)

來點擊並引用圖形 2.1。

3.2 動態圖表

    透過 {.tabset} 指令可以呈現不同的分頁結果；例如點擊下面不同的分頁來呈現動態表格與圖形。

3.2.1 動態表格

    以下為還原股價後的日收盤價結果。

3.2.2 動態圖形

    以下為還原股價後台積電的日收盤價圖形，可以移動最下方的時間軸呈現對應的結果。



3.3 鑲入網頁

    我們可以將其它網頁鑲入 (embeded) R-Markdown 文件中，且不限於靜態網頁。下圖可以點擊各國圖形，會呈現不同的動畫結果。


4 結論與建議

    本文主要目的是簡介 R-Markdown 語法，希望能有拋磚引玉的效果，讓我們在撰寫報告時可以更具效率。綜合而言，研究者只要維護一個 R-Markdown 檔案就能將文字、R 代碼與 R 的執行結果轉換成不同檔案格式。若輸出成 HTML 格式，還可以在讓使用者透過瀏覽器立即觀察執行結果。R-Markdown 實為一有用的工具，有興趣的讀者可以透過網路搜尋相關指令與文件，以豐富 R-Markdown 的內容。