Introduction to R Markdown

background-image: linear-gradient(to bottom, rgba(0,0,0,0.2) 30%, rgba(0,0,0,0.2) 100%), url(https://liao961120.github.io/slides/img/bg/coffee-blur.jpg)
background-position: center
background-size: cover

### .s[A Tool Enabling You to Create, Write, & Share Ideas]

<hr />
.little-larger[
April 22, 2019  
廖永賦  
[bit.ly/fju-rmd](http://bit.ly/fju-rmd)
]
]

???
(提醒大家**投影片連結**)

我今天要介紹的是 R Markdown。

但在正式進入 R Markdown 的介紹前，我想先扯比較遠，從我自己的一些個人經驗以及我對於 R Markdown 的一些想法開始。

---

???
我從小到大花了很多時間在「讀書」上，從基測、學測到大一大二都是如此。但有時候我會感到很焦慮，可能是因為年紀大了所以開始會有些就業壓力。我常常會問自己，「我花了這麼多時間在學習上，但我真的有學『到』什麼嗎？今天如果我去申請研究所或是求職面試，我有真正**屬於自己的東西或能力**可以拿出來說嘴嗎？」

我發現沒有

我也發現我沒有真正學到東西的原因是因為，我從小到大的學習都只是在「被動餵食」，但我卻沒有學到一項真正重要的能力，那就是**創造**新事物的能力。簡單來說，我是個只會考試，但沒有任何創造力的人。

這裡先偏題一下，「創造力」其實是一種複雜的東西，它在心理學裡面有很多人在研究，但心理學家對於「創造力」是什麼還在爭論不休。但有一點很確定的是，「創造力」不像智力或是運動天賦這種一出生就決定大半的**個人能力**。「創造力」是在一個系統中，很多因素長期彼此配合，逐漸**被孕育**出來的現象。

就我自己所體悟到的，為何我自己在 21 歲之前是個沒什麼創造力的人，我發現只有一個關鍵的原因，那就是我**沒有動機去創造東西**。而且很微妙的一點是，這種**沒有動機**是沒辦法被直接解決的。因為它是一整個，孕育創造力的系統，的問題。  
而且事實上，我當初甚至沒有意識到有這個問題需要被解決，我完全是在誤打誤撞之下，轉對了一個正確的旋鈕，讓這個所謂孕育創造力的系統能開始運行。

這個系統在今天的脈絡下，大概能用這張圖表示：

`--`

---

???
我覺得創造力的動機來源就是這張圖的左下角，也就是渴望將自己的想法或創造的事物分享給其他人的動機。

這個動機是推動創造力產生的燃料，但這個動機不會自發產生，而最根本的原因是我們沒有工具以及能力，能輕鬆的達成這件事。

就舉一個比較貼近學生生活的例子，像是學校的的期末報告。  在我們完成的期末報告當中，有多少是在學期末 報告當天之後，就塵封在電腦裡或是雲端硬碟的某處，再也沒人看過？

因為我們長久下來的習慣是用 PDF 和 Powerpoint 的方式呈現期末報告成果，報告所能觸及的就是報告當天在場的那群人。所以基本上，有時我們在做期末報告會敷衍了事是很正常的，畢竟我們為什麼要花這麼多力氣在一個馬上就會被世界所遺忘的事情上呢？

但是..想想看  
今天如果我們能夠使用 「**網頁**」 去呈現我們的報告成果，那我們能觸及的就不只是報告當天的那群人，而是全世界。我們做的報告也會在報告當天結束後，繼續「活在網路上」。你不會確定有誰會去看它，但你很可能會意外的啟發 看了你的報告的人。

我覺得這就是，推動我去創造的動力來源。而這個動力之所以能這麼順暢地推動我，是因為我能夠隨心所欲的使用工具來幫助自己達成目標 -- 也就是能透過自己架設的網頁，將想法分享其他人。

我今天要介紹的，就是這個幫助我輕鬆地在網頁上呈現自己的創作和想法的工具。這個工具就是 R Markdown。

---

### 透過 R Markdown 分享至網路

???
這邊這兩個網頁就是給大家一個 「R Markdown 能做到什麼事情」的概念。這兩個網頁百分之百使用 R Markdown 做成的，網頁裡面的圖則都是用 R 語言的繪圖函數畫成的。

---

# Part Ⅰ
# .larger[R Markdown Basics]

???
接下來，我要正式進入 R Markdown 的介紹了。透過今天對 R Markdown 的介紹，我希望能達成兩個目標：

---

## Objectives

1. Rmd ➜ PDF
]

???
1. 第一，大家在今天結束前能夠透過 R Markdown 輸出網頁，並透過網址分享給別人。
1. 第二，大家有能力以 R Markdown 取代 Word。換句話說，你可以將 R Markdown 輸出成 PDF 檔，用來繳交學校作業或報告。

---

# What is Markdown?

???
所以 R Markdown 是什麼？

基本上，R Markdown 就是一套寫作的工具，你可以用它來寫筆記、寫書、寫論文，甚至，像剛剛提到的，你可以用 R Markdown 製作網頁。事實上，現在大家看到的投影片，也是用 R Markdown 做出來的。當然，這些比較 fancy 的 R Markdown 功能不是今天的重點，今天的重點是最基礎的 R Markdown。

那在了解 R Markdown 是什麼之前，我們需要先知道 Markdown 是什麼。所以我就先從一點點，Markdown 發展的脈絡以及，「人類寫作工具」的歷史開始。

---

## 兩種媒介：紙本 vs. 網頁

.pull-left[
![:scale 70%](https://upload.wikimedia.org/wikipedia/commons/4/45/A_Specimen_by_William_Caslon.jpg)
]

???
寫作的目的有一部分是要給人看的，因此排版自然而然就成為作者的工作之一。

在文字普及後的絕大多數時間，排版僅需要考慮紙本印刷物。但今天，我們生活在一個網路的時代，網路已成為最主流的資訊傳播管道。因此，網頁變成和紙本同等 (甚至更加) 重要的文字承載媒介。

這件事情對文字工作者造成了新的負擔，因為兩種不同的文字承載媒介 – 紙本與網頁，在歷史上各自衍生出兩種目的十分迥異的排版系統，  
一種是為了輸出印刷物而生的排版系統，另一種是為了輸出網頁而生的排版系統。  
但這兩種系統彼此是無法輕易互相轉換的。

譬如說，我們無法輕易地將網頁轉換成紙本印刷物，因為網頁頁面是連續的，不像書本是用一頁當作顯示單位。  
另外，顯示網頁的螢幕大小也不是固定的，不像紙張有固定尺寸。

這件事情對文字工作者帶來了麻煩，因為在開始寫作之前，他必須先決定未來要以哪一種媒介呈現自己的作品。一旦決定之後，作品就永遠只能活在那個媒介上，除非作者另外再花力氣將內容複製到另一種媒介上。

換句話說，寫作者面臨的是一個「紙本與網頁的矛盾」。

---

## 兩種排版方式：標記式語言 vs. 圖形化界面

### 標記式語言

```html
這是<b>粗體字</b>

這是<i>斜體字</i>
```
]

這是<b>粗體字</b>

這是<i>斜體字</i>
]

???
除了承載文字的媒介，這世界上也存在兩種排版文字的方式。其中一種是以圖形化界面為基礎的排版系統，像是 Word；

另一種是以純文字檔案為基礎的標記式語言排版系統，像是 HTML 或是 LaTeX。大家可能對標記式語言是什麼不太清楚。簡單來說，標記式語言是一套用來告訴電腦說，「你要如何顯示這串文字的語法」。

例如這張投影片的左邊是 HTML 的純文字。瀏覽器在讀取這段文字的時候，在看到某些關鍵字，像是在這邊看到的，包裹**粗體字**和*斜體字*的特殊標記，它就會將這些包裹在特殊標記裡面的文字，顯示成這些標記所要求的格式。

所以用 b tag 包裹的字就會以粗體顯示  
用 i tag 包裹的字就會以斜體顯示

---

## 兩種排版方式：標記式語言 vs. 圖形化界面

### 圖形化界面

<img src="img/medium_edit.gif" width="100%" style="display: block; margin: auto;" />
]

<img src="img/medium_post.png" width="100%" style="display: block; margin: auto;" />
]

???
至於圖形化界面的排版方式，就是大家比較熟悉的那種。

像是，Word 或是，「投影片裡面的 medium 部落格平台」。

這種排版方式的特色，是讓使用者在編輯的過程中就可以直接看到文件發表之後的樣子。

---

## 圖形化界面 vs. 標記式語言

|    | 圖形化界面 | 標記式語言 |
| -- | --- | --- |
| 優點 | 易學易用 | 排版方式固定<br>檔案管理容易 |
| 缺點 | 檔案合併困難<br>檔案管理不便 | 語法過於複雜， <br>難以專心寫作 |

???
圖形界面和標記式語言的排版方式各自有自己的優缺點。

使用圖形化界面排版的好處是，它使用上非常**直覺**，使用者不需要經過什麼學習就能快速上手。但它有兩個比較嚴重的缺點。

`--`

]

???
第一個是**檔案合併**的問題。  
這邊有個問題想要問大家，就是你們在使用 Word 的時候，如果要為段落新增標題，你們會透過下面這張圖中「紅色框框」裡面的**樣式**去選擇「標題1」或「標題2」之類的嗎？  
還是會將「要作為標題的文字」反白，粗體和調整字體大小，讓它「**看起來**」像是標題就好？

(我過去是直接使用後面那種方法)

基本上你使用哪種方式並沒有什麼關係，但是當你要將不同的 Word 檔合併成一份的時候，(譬如說，小組報告時，每個人各自負責撰寫一部分的報告) ，這時候如果每份 Word 檔使用的是不同的方式，那你就必須手動把格式調整成一致

`--`

> Q: 請在這 200 份**文件**中，找出所有內文含有「三年五班 王小明」的文件

- 純文字檔
    ```bash
    grep -r '三年五班 王小明' *.md
    ```
]

???
圖形化界面排版的另一個缺點比較不明顯，但是當你有很多文件檔案就會比較明顯。  
舉例來說，如果你想在好幾百份 Word 檔中找出內文有特定關鍵字的文件。  
這件事會很困難，因為 Word 的檔案格式並非純文字檔，換句話說，這類的檔案只有使用特定軟體才能閱讀。

但相反的，如果文件格式不是 Word 而是以標記式語言寫成的純文字檔，  
那這個問題就變得很簡單，只要使用一條電腦內建的指令，就能找到這些檔案。

---
background-image: url("https://liao961120.github.io/slides/img/emo/boredom-small.png")
background-size: 100px
background-position: 90% 8%

## 標記式語言：太複雜了

???
至於標記式語言的缺點只有一個，(Next Page: GIF)

它太複雜了

(Back to this page)

像是「這張投影片的左邊」是用來產生「右邊網頁的 HTML 語法」

---

background-image: url(https://imgy.netlify.com/gif/too-complicated.gif)
background-size: cover
count: false

???
(Back to previous slide)

---

## Markdown: 極簡的標記式語言

???
這就是 Markdown 出現的原因。  
Markdown 與 HTML 一樣是一種標記式語言。它當初被發明的目的，就是為了解決 HTML 語法過於複雜的問題。

簡單來說，Markdown 提供了一種更簡單的方式來撰寫網頁。它運作的方式就像這張圖片：

寫作者能用非常簡略的 Markdown 語法撰寫文件。接著再透過特殊的工具，將 Markdown 翻譯成 HTML，如此就能透過瀏覽器顯示這份文件。

---

## 玩玩看 Markdown

Copy Markdown example [here](https://raw.githubusercontent.com/liao961120/2019-fju-rmd-talk/master/md_syntax.txt)

???
那 Markdown 語法真的很簡單，可以馬上學會。  
這邊可以請大家點擊這張圖片，進入一個線上的 Markdown 編輯器。  
然後，大家可以點進上方的連結去將 Markdown 語法複製貼上到這個線上編輯器。  
可以實際的去修改或新增這些 Markdown 語法，應該就能很快的掌握 Markdown 的邏輯了。

---

.footnote[.s[
[Markdown Practice](https://raw.githubusercontent.com/liao961120/2019-fju-rmd-talk/master/md_prac.txt)
]]

???
那大家在手動玩過 Markdown 之後，這邊有個挑戰要給大家。

這邊給大家 5 分鐘的時間去用 Markdown 寫出和這張圖片一樣的結果

[md_prac_answer.txt](https://github.com/liao961120/2019-fju-rmd-talk/blob/master/md_prac_answer.txt)

---

## Markdown: Too simplified?

### Two Solutions

1. Markdown + HTML Syntax

1. Markdown Extensions

- 優缺點？

???

#### Two Solutions
剛剛試用過 Markdown 的語法之後，大家可能會覺得 Markdown 太過於簡略，導致它無法應付更細緻的排版需求。Markdown 本身的語法確實無法應付這種情況，但有兩種方式可以解決這個問題。

1. 第一就是 Markdown 可以與 HTML 的語法混用。這是完全沒有問題的，因為要在網頁上顯示 Markdown，本來就會先將它轉換成 HTML 語法。

1. 第二就是擴充 Markdown 本身的語法。事實上，已經有很多人在做這件事了，所以市面上其實有很多種 Markdown 語法在流通。這些 Markdown 之間語法上會有些微的差距。

- 優缺點

這兩種解決 Markdown 語法過於簡略的方式，其實有各自的優缺點。第二項的缺點很明顯，就是，當一個東西有各種不同版本時，會造成使用上的麻煩。簡單來說，你無法用一致的 Markdown 語法，橫行於各個平台之上。

至於第一項，在撰寫網頁的脈絡下，並沒有什麼缺點。但是如果回到前面所說的，關於「紙本與網頁」之間的矛盾這件事上，將 Markdown 與 HTML 混用基本上就是，放棄了「紙本」而選擇了「網頁」作為發表作品的媒介。

Markdown 作為一種極簡約的標記式語言，這點讓它有潛力解決紙本與網頁之間的矛盾，因為簡單的標記式語言，可以被轉換成更複雜的標記式語言，但是反之不然。  
所以 Markdown 可以轉換成比較複雜、以**網頁呈現為目的**的 HTML；  
那既然可以轉換成 HTML，為什麼不把 Markdown 轉換成**以紙本印刷為目的**的標記式語言呢？

這就是 Pandoc 這個工具出現的原因

`--`

### Pandoc Markdown

- **Pandoc**: A Tool for conversion between multiple document formats
  
  - [pandoc.org/try](https://pandoc.org/try/)

- **Pandoc Markdown**: Markdown extensions by Pandoc

???

#### Pandoc Markdown
Pandoc 是一個用於「在各種標記式語言和文件格式之間」轉換的工具。  
譬如說，它可以將 Markdown 轉換成 HTML, LaTeX 和 Word 文件。Pandoc 也可以將這些格式逆向轉換成 Markdown，但就像前面所說的，這種轉換並不完美，因為複雜的標記式語言要轉換成比較簡單的標記式語言，勢必要丟掉很多無法被轉換的資訊。

至於 Pandoc Markdown 則是 Pandoc 自己定義的 Markdown 語法。它大幅的擴充 Markdown 語法，讓 Markdown 可用於撰寫排版更加精緻的文件。

---

background-image: url("img/pandoc.png")
background-size: 280px
background-position: 93% 5%

## Pandoc Markdown<br>.smaller[.much-smaller[.g[解決「紙本 vs. 網頁」的衝突]]]

|     | 圖形化界面  | 標記式語言  |
|-----|----------|----------|
| **紙本** | MS Word | `$\LaTeX$`,<br>Markdown (近年目標)  |
| **網頁** | 部落格文章撰寫後台<br>(e.g. WordPress, Medium) | HTML,<br>Markdown (初創目的) |

???
更重要的是，Pandoc Markdown 多數的語法能夠同時完美地轉換成 HTML 和 LaTeX 這兩種標記式語言。

LaTeX 是另一種標記式語言。它是以生成 PDF 為目標的標記式語言。

這基本上解決了「紙本與網頁的矛盾」，因為寫作者可以只用 Pandoc Markdown 撰寫文件，需要**發布在網路**上時就將文件輸出成 HTML，需要**列印**時就將文件輸出成 LaTeX 再生成 PDF。

這個表格比較了幾種常見的排版工具的特性。我這邊總結一下。我認為 Markdown 是這些工具之中最好的排版工具，原因有兩點：

1. 第一，做為一種標記式語言，Markdown 沒有其它圖形化界面排版工具的缺點。同時，由於 Markdown 是非常簡約的標記式語言，它不像過去惡名昭彰的標記式語言擁有太過複雜的語法，干擾人們寫作的過程。
1. 第二，使用 Markdown，或更精確的說 是 Pandoc Markdown， 可以解決紙本和網頁的矛盾

---

## Markdown Extentions by Pandoc .ms[(Partial)]

- Footnotes

- [Bibliographies and Citations](https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html)
    - [Citation Style Language (`.csl`)](https://citationstyles.org)

- Math Expressions:
  
  - 
  ```latex
  e^{ \frac{ -(x - \mu)^2 }{2 \sigma^2} }
  ```
  
  - Wrap LaTeX math code in a pair of `$` or `$$`:
  
      - `output: `$e^{ \frac{ -(x - \mu)^2 }{2 \sigma^2} }$``  
      - output: `$e^{ \frac{ -(x - \mu)^2 }{2 \sigma^2} }$`

.footnote[
[1]: [R Markdown's Markdown Syntax](https://bookdown.org/yihui/rmarkdown/markdown-syntax.html) (Pandoc Markdown)
]

???

那這邊列出了一小部份 Pandoc Markdown 所提供的語法，  
譬如說，它提供了「註解」的語法、  
自動插入引用文獻的語法 (那這個功能對於學術報告的撰寫很重要)、  
另外，它也提供了撰寫數學公式的語法

這邊之所以會提到 Pandoc Markdown 的原因是因為，  
R Markdown 所使用的 Markdown 語法其實就是 Pandoc Markdown。  
那投影片下方的第一個連結是 R Markdown 的 Markdown 語法簡介。

---

# Components of R Markdown

???
介紹完 Markdown 之後，接著就要正式進入 R Markdown 的介紹了。

前面介紹的是 Markdown 在歷史上發展的脈絡。那 R Markdown 它其實自己也有另一個發展的脈絡。

大家都知道 R 是一個為了統計計算而生的程式語言，所以 R Markdown 也是在這個脈絡裡發展出來的。事實上，R Markdown 之所以會誕生，是因為有個統計學的博士生，他為了減輕自己寫統計學作業的負擔而創造了一個 R 套件。而這個套件就是 R Markdown 誕生的關鍵。

---

## What is R Markdown?

- **`knitr`**: A tool for embedding R code & execution results into a Markdown document.

???
R Markdown 顧名思義就是 R 加上 Markdown。  
更精確的說，這邊 R 指的是 knitr 這個套件。knitr 這個套件讓「可以被執行的 R 語言」能夠直接嵌入在 Markdown 文件當中。

這讓每次在輸出 R Markdown 的時候，R 語言執行的結果，像是圖表或數值，能自動的被插入生成的文件中。

<br>

1. 統計分析 → SPSS, SAS, Excel

1. 報告撰寫 → Word

1. .s[啊！我發現統計分析時，用錯資料了...  
→ .r[重複步驟 1, 2]]

1. 輸出報告
]

1. 統計分析 + 報告撰寫 → R Markdown

1. .s[啊！我發現統計分析時，用錯資料了...  
→ .r[修改資料輸入指令]]

1. 輸出報告
]

???
**結合「寫作」與「分析」**

這讓 R Markdown 可以結合「寫作」和「分析」這兩種「原本在傳統的 統計報告準備流程中」是分開的兩件事。

傳統的報告準備流程中，我們必須先在統計軟體裡面跑出分析結果，再手動的將這些結果複製進 Word 裡。  
那這邊會造成一個問題是，如果我們在報告寫到一半的時候，發現我們之前分析階段出了問題，那我們就必須重新跑一次統計再手動將新的圖表和數值更新在 Word 中。

但如果使用 R Markdown，因為統計分析的結果是自動插入文件的，我們只需要修改造成分析錯誤的 R 指令就好，並不需要再額外更新文件內容。

---

## Structure of an R Markdown Document

<br>

???
這張圖是一個 R Markdown 文件的結構。其實，R Markdown 基本上就像 Markdown 文件一樣，

差別只在於，
除了 Markdown 的內文之外，R Markdown 還多出了**控制輸出文件外觀的 YAML** 以及 
讓 R Markdown 可以自動嵌入 R 語言執行結果的 knitr code chunk。

---

## Structure of an R Markdown Document

<br>

???
那這張圖和上一張幾乎是一樣的，只是更詳細的將 YAML 和 knitr code chunk 的組成畫進圖裡，讓大家能有個比較好的概念連結。

---

## Structure of an R Markdown Document

.right-column[
````md
*---
*title: A minimal R Markdown Document
*author: John Doe
*output: bookdown::html_document2
*---

# Markdown

I'm writing with *Markdown syntax*.

```{r}
today <- Sys.Date()
paste('Using R Markdown on', today)
```

## Inline R Code

Variables computed in code chunks can be placed inline: `r today`
````
]

???
這邊大家看到的就是一份完整的 R Markdown 文件的內容。

文件的最上方就是剛剛講到的 YAML frontmatter。這邊主要是控制 R Markdown 輸出文件的樣式以及外觀的一些設定。

---

## Structure of an R Markdown Document

.left-column[
### .little-smaller[YAML Frontmatter<br>(Metadata)]
### Markdown <br>.ls[(Static Content)]
]

.right-column[
````md
---
title: A minimal R Markdown Document
author: John Doe
output: bookdown::html_document2
---

*# Markdown
*
*I'm writing with *Markdown syntax*.

```{r}
today <- Sys.Date()
paste('Using R Markdown on', today)
```

*## Inline R Code
*
*Variables computed in code chunks can be placed inline: `r today`
````
]

???
第二個部份則是用 Markdown 撰寫的內文。

---

## Structure of an R Markdown Document

.left-column[
### .little-smaller[YAML Frontmatter<br>(Metadata)]
### Markdown <br>.ls[(Static Content)]
### .little-smaller[knitr Code Chunks<br>(Executable)]
]

<pre><code class="md hljs markdown remark-code">---
title: A minimal R Markdown Document
author: John Doe
output: bookdown::html_document2
---

# Markdown

I'm writing with *Markdown syntax*.

<div class="remark-code-line remark-code-line-highlighted">```{r}</div>
<div class="remark-code-line remark-code-line-highlighted">today <- Sys.Date()</div>
<div class="remark-code-line remark-code-line-highlighted">paste('Using R Markdown on', today)</div>
<div class="remark-code-line remark-code-line-highlighted">```</div>

<div class="remark-code-line"><span class="hljs-section">## Inline R Code</span></div>

<div class="remark-code-line">Variables computed in code chunks can be placed inline: <span class="remark-code-span-highlighted">`r today`</span></div>
</code></pre>
]

???
第三個部份就是 R Markdown 可以執行 R 語言的部份。要在 R Markdown 裡面插入這種內容，可以使用兩種方式。

第一種是右邊比較暗的黃色螢光標記的部份，這邊的語法與 Markdown 的 code chunk 語法類似，但與 Markdown 不同的是，這些 code chunk 在 3 個反引號之後，使用大括號將 r 包覆起來。

第二種語法則是用來將 R 計算出來的數值直接插入在一行當中的某處。

---

## 3 種 Code Chunks

???
所以，R Markdown 其實有 3 種 Code chunk。

- Markdown (不會執行)
  ````Rmd
*```r
print("This will NOT be printed!")
```
````

???
**第一種**就是前面在介紹 Markdown 時，提到的 Markdown code chunk。這種 code chunk 就是 Markdown 語法的一部分，它本身並不會執行，多半是用來 highlight 文件當中的程式碼語法

- knitr Code Chunk (Executable)
  ````Rmd
*```{r}
print("This will be printed!")
```
````

???
**第二種**就是類似 Markdown code chunk，但是 是可以執行的程式碼區塊。這種 code chunk 會是 R Markdown 裡面最常出現的一種，也會是等一下介紹的重點。那我之後就把這種 code chunk 叫做 knitr code chunk。

- Inline R Code Chunk (Executable)
  
  ````Rmd
```{r}
ttest <- t.test(1:10, y = c(7:20))
pval <- ttest[["p.value"]]
```
````
  
  <code class='hljs'>
  T 檢定所得之 p 值為 &#96;r pval&#96;
  </code>

???
**第三種**是用來在行內插入數值的語法。這種 code chunk 很實用。舉例來說，你可以在前面的 knitr code chunk 先計算出統計檢定的 p-value ，並將這個 p-value 儲存在某個變項裡面，然後再用這個語法將 p-value 插入 Markdown 內文中的某處。

---

## knitr Code Chunk

````Rmd
```{r chunk-label, echo=FALSE, dev="png"}
x <- 1 + 1
```
````

- `echo`: show R source code?

- `eval`: Run code chunk?

- `include`: include the chunk output in the final output document?

- `out.width='90%'`: 輸出圖片佔 90% 頁面寬度

]

???
接下來，我要比較詳細的介紹 knitr code chunk

knitr code chunk 有一個很重要的特徵是，它有許多選項可以進行設定。例如，你有時候想讓讀者看到跑出結果的程式碼但有時候不想，這時候，你就可以透過 knitr 的 chunk options 進行這些設定。

那這些選項是設定在 knitr code chunk 第一行的大括弧之內。那這大括弧之內的結構大致是這樣：

(手動反白操作)
第一個 r 標明這個 code chunk 是個 R code chunk。  
那事實上，除了 R 你也可以把它換成其它程式語言，例如 Python 和 bash。那前提是你的電腦已有安裝這些程式語言。

第二個出現的是這個 code chunk 的 ID，那這個 ID 是 optional 的，可以不用寫。

code chunk ID 之後出現的一律都是 knitr 的 code chunk options。這些 options 之間以逗點分隔。

我這邊列出了幾個最常用的 knitr chunk options。至於完整的選項，大家可以在下方的 knitr 說明文件裡面看到。

---

## knitr Code Chunk

#### Global Chunk options

````Rmd
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)
```
````
      
<img src="img/global_chunk_opts.gif" width="95%" style="display: block; margin: auto;" />

]

???
剛剛講的是，一個單獨的 knitr code chunk 的選項設定。  
但有時候，你不想每次都為新的 code chunk 重複設定一樣的選項。這個時候，你就可以設定 global chunk options。

global chunk option 是在 R Markdown 裡面的第一個 code chunk 進行設定。RStudio 也提供了方便的圖形化界面，讓你不用去記下這語法也能進行設定。

---

## knitr Code Chunk

輸出**統計圖**，並

1. 隱藏原始碼: `echo=FALSE`
1. 調整圖片寬度：`out.width="35%"`
1. 調整圖片比例 (寬:高 = 6:4)：`fig.dim=c(6, 4)`

````Rmd
```{r iris-plot, echo=FALSE, out.width="35%", fig.dim=c(6, 4)}
library(ggplot2)
ggplot(data = iris) +
  geom_point(aes(Sepal.Length, Petal.Width, color = Species))
```
````
]

???
接下來，我這邊提供大家 3 個使用 knitr code chunk 的實例。

第一個例子是用 knitr code chunk 在 R Markdown 裡面直接繪製統計圖。那這邊的 data 是使用 R 內建的 iris data 為例。實務上，你們會需要先在前面進行資料的前處理。

那在這個例子當中，我希望能夠輸出統計圖，並且在輸出的文件裡...

1. 不要顯示繪製這張圖的 R 程式碼，  
所以我就用了 `echo=FALSE` 這個選項。
2. 統計圖的寬度是文件寬度的 35%，  
所以我就用了 `out.width="35%"` 這個選項。
3. 我希望圖片的**寬高比**是 **6:4**，  
所以我就用了 `fig.dim` 這個選項。那 `fig.dim` 吃的是一個 **numeric vector**，這個 vector 的第一個數值是寬高比中的寬，第二個是寬高比中的高。

`--`

<img src="index_files/figure-html/unnamed-chunk-24-1.png" width="35%" style="display: block; margin: auto;" />
]

---

## knitr Code Chunk

````Rmd
```{r echo=FALSE}
data <- iris[1:4, 1:3]
knitr::kable(data, align = "c", caption = "表格說明文字")
```
````
]

???
第二個例子是用 knitr code chunk，將 `data.frame` 以表格的形式 顯示於輸出文件。

R Markdown 做到這點的方式是依靠 `knitr 套件` 所提供的 `kable 函數`。那在 kable 函數裡面，你甚至可以丟給它一個叫做 `caption` 的參數，讓輸出的表格會有說明文字。

`--`

<table>
<caption>表格說明文字</caption>
 <thead>
  <tr>
   <th style="text-align:center;"> Sepal.Length </th>
   <th style="text-align:center;"> Sepal.Width </th>
   <th style="text-align:center;"> Petal.Length </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:center;"> 5.1 </td>
   <td style="text-align:center;"> 3.5 </td>
   <td style="text-align:center;"> 1.4 </td>
  </tr>
  <tr>
   <td style="text-align:center;"> 4.9 </td>
   <td style="text-align:center;"> 3.0 </td>
   <td style="text-align:center;"> 1.4 </td>
  </tr>
  <tr>
   <td style="text-align:center;"> 4.7 </td>
   <td style="text-align:center;"> 3.2 </td>
   <td style="text-align:center;"> 1.3 </td>
  </tr>
  <tr>
   <td style="text-align:center;"> 4.6 </td>
   <td style="text-align:center;"> 3.1 </td>
   <td style="text-align:center;"> 1.5 </td>
  </tr>
</tbody>
</table>

]

---

## knitr Code Chunk

.left-column[
### Chunk Options
### .little-smaller[例: 統計圖]
### .little-smaller[例: 表格]
### .little-smaller[例: 外部圖片]
]

使用**外部**，而非 R 所產生之圖片

````Rmd
```{r world, echo=TRUE, out.width="38%", fig.cap="圖片說明文字"}
knitr::include_graphics("img/world_night.jpg")
```
````
]

???
最後一個例子，有時候你需要使用外部的圖片，而不是 R 自動生成的圖片。

那剛剛在練習 Markdown 時，比較仔細的人可能會發現可以直接使用 Markdown 語法插入圖片。  
但我這邊要介紹的是 knitr 的 `include_graphics()` 這個函數，原因是 Markdown 插入圖片的語法功能比較受限，譬如說，你不容易去控制圖片的大小和說明文字。

如果使用的是 `include_graphics()` 這個函數，就能夠透過 knitr chunk options 去控制這些事情。例如，我這邊就用 `fig.cap` 這個 chunk option 幫圖片加入說明文字。另外，我這邊也把 `echo` 設為 `TRUE`

`--`

```r
knitr::include_graphics('img/world_night.jpg')
```

<div class="figure" style="text-align: center">
<img src="img/world_night.jpg" alt="圖片說明文字" width="38%" />
<p class="caption">圖片說明文字</p>
</div>

]

???
所以文件的輸出也會同時顯示插入這張圖片的 R 程式碼。

---

## knitr Code Chunk

.left-column[
### Chunk Options
### .little-smaller[例: 統計圖]
### .little-smaller[例: 表格]
### .little-smaller[例: 外部圖片]
]

- Current Working Directory：**`.Rmd` 所在的資料夾**

- **盡量使用相對路徑**：外部檔案路徑都是.r[**相對 `.Rmd` 而言**]

```yml
    my-folder/    # slide.Rmd 所在之資料夾
    │
    ├── doc.Rmd
    *├── cover.jpg
    └── img/
    *    └── foo.jpg
    ```
    
    ```r
    include_graphics('cover.jpg')              # Good
    include_graphics('img/foo.jpg')            # Good
    ```
]

???
在使用外部檔案的時候，必須要知道的一個概念是相對路徑和絕對路徑。  
(這邊老師有講過嗎？)

「相對路徑」指的是相對於某個檔案的路徑。所以，在 R Markdown 裡面使用相對路徑，就是使用相對於這份 `Rmd 檔` 的路徑。

那因為時間上的關係，我這邊沒辦法很詳細的解釋絕對路徑和相對路徑的概念。所以我就用一個比較具體的例子說明如何使用相對路徑。

那大家可以看到投影片裡面，這個「檔案結構」的樹狀圖。這個例子是用一個叫做 `my-folder` 的資料夾。這個資料夾裡面有 1 個 `Rmd 檔` (doc.Rmd)、1 個 `jpg 檔` (cover.jpg) 和一個資料夾 `img`。而 `img` 這個資料夾裡面還有另一個 `jpg 檔` (foo.jpg)。

那今天，如果我想在 `doc.Rmd` 裡面插入 `cover.jpg` 和 `img` 資料夾中的 `foo.jpg` 這張圖片。那與 `doc.Rmd` 在同一層結構的 `cover.jpg`，它的相對路徑就是它的檔名，也就是 `cover.jpg`。`img` 資料夾裡的 `foo.jpg`，它相對於 `doc.Rmd` 的路徑就是 `img/foo.jpg`。

`--`

.right-column[.ms[
```r
# Bad Practices !!!
include_graphics('img\\fig.jpg')           # Works only on Windows
include_graphics('C:/.../img/foo.jpg')     # Works only on YOUR Windows
include_graphics('C:\\...\\img\\foo.jpg')  # Works only on YOUR Windows
```
]]

???
至於最下方的程式碼，是「不好的檔案路徑使用例子」。

簡單來說，不要在檔案路徑裡面使用 反斜線，因為這只對 Windows 的電腦有用。

也不要使用絕對路徑，因為其它人的電腦，檔案結構一定和你的不一樣。所以如過你使用絕對路徑，其它人的電腦就一定會找不到檔案。

---

## knitr Code Chunk

.left-column[
### Chunk Options
### .little-smaller[例: 統計圖]
### .little-smaller[例: 表格]
### .little-smaller[例: 外部圖片]
### Your Turn
]

#### .larger[練習時間]

1. 下載 [`code_chunk_prac.zip`](https://liao961120.github.io/2019-fju-rmd-talk/code_chunk_prac.zip)

1. 修改 `code_chunk_prac.Rmd` 中的內容，  
使輸出<sup>\*</sup>結果與[此網頁](https://bit.ly/2FUQPvP)相同

1. 參考答案寫在 [`code_chunk_prac_solution.Rmd`](https://github.com/liao961120/2019-fju-rmd-talk/blob/master/code_chunk_prac/code_chunk_prac_solution.Rmd)

]

.footnote[
[\*]: 以 RStudio 開啟 `.Rmd` ➜ 點擊 <img src='img/knitr.png' style='display:inline;height:1em;'> (`Knit`) or  
`rmarkdown::render('path/to/code_chunk_prac.Rmd')`
]

???
好，那接下來就換大家實際進行操作了

大家可以點進連結下載這個壓縮檔。壓縮檔裡面有兩個 `Rmd 檔`，以 `_solution` 結尾的是參考答案，大家先不要打開這個檔案，

先用另一個檔案練習，看看能不能依照裡面的指示修改 knitr code chunk ，讓輸出後的文件 跟投影片中的網頁長的一模一樣。

(示範 RStudio Knit)  
前面還沒講過如何在 RStudio 裡面將 R Markdown 輸出。我這邊先示範一下。

---

## YAML Frontmatter

```yml
title: 'A title'
date: '`r Sys.Date()`'  # ➛ '2019-04-25'
author: 'Somebody'
bibliography: ref.bib
csl: apa.csl
```

<br>

- 不同格式 (模板)，可供設定之變項不盡相同
    - `geometry`, `linestretch` 僅對於 PDF 輸出的文件有效果

- 可用**動態變項** (inline R Code) 作為輸入
    - 今天是 &#96;<code>r Sys.Date()</code>&#96;  
    今天是 2019-04-25
]

???
最後，這裡要告訴大家 YAML Frontmatter 的設定。

YAML 是控制 R Markdown 輸出文件外觀的地方。那 R Markdown 輸出的外觀是由預先寫好的 pandoc 模板所決定，而不同的輸出格式會套用不同的模板。

所以，YAML 裡面的變項會依據所選擇的輸出格式而有些微的不同。當然，多設了模板所沒有提供的變項，並不會導致輸出錯誤，只會被直接忽略。

`--`

.pull-right[
#### 輸出格式
    
```yml
output:
  bookdown::html_document2:
    toc: yes
    number_sections: no
  bookdown::pdf_document2:
    toc: yes
    number_sections: no
```

- **.r[縮排]**結構必須一致: 每層皆使用 **2 格空白**

- 可同時設定多個輸出格式  
![:scale 75%](img/knit_multiple.gif)
]

???
那這邊只有一個重點要提醒，就是在設定 YAML 時，有時候會有巢狀結構的出現，例如，投影片右邊的輸出格式。

在撰寫有階層結構的 YAML 時，每個階層之間的縮排間隔要固定。我是建議使用**兩格空白**作為縮排的固定距離。當然你也可以用 1 個 tab 或是 4 格空白。但一定要確定整個 YAML 都是使用同樣縮排，輸出文件時會出錯。

---

## YAML 好複雜？

<br>

- 輸出 HTML 文件 ([檢視](https://github.com/liao961120/2019-fju-rmd-talk/blob/master/minimal_html), [下載](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/liao961120/2019-fju-rmd-talk/tree/master/minimal_html))

- 輸出 PDF 文件 ([檢視](https://github.com/liao961120/2019-fju-rmd-talk/tree/master/minimal_pdf), [下載](https://liao961120.github.io/2019-fju-rmd-talk/minimal_pdf.zip))

???
YAML 是個有點麻煩的東西，因為它的選項太多了，基本上沒有人會記得。

所以，只要用複製貼上的就好，  
或是更好的方式，是使用 Rstudio 直接匯入 R Markdown 模板。那這部份我等一下會講到。

---

# Hosting HTML Files on Web

---

<br>

![:scale 100%](img/server_model.png)

???
大家剛剛已經學會將 R Markdown 輸出成 HTML 的文件了。那現在有了 HTML，我們需要一個方式讓我們分享這個 HTML 檔。

如果直接把 HTML 檔傳給別人會很奇怪，想想看自己有收到過 HTML 檔嗎？  
我們當然希望能夠直接給人家一個網址，讓他點進去就可以看到我們用 R Markdown 輸出的 HTML。

那要做到這件事，我們需要一個 24 小時持續運作的伺服器，幫我們儲存 HTML 檔，讓知道網址的人可以閱讀我們放在伺服器上的 HTML。

---

## Updog

#### 註冊 Updog

1. Visit [updog.co](https://updog.co/)
1. `Get Started`
1. `Sign in with Google / Dropbox`
1. 輸入 `site name`

#### R Markdown ➜ HTML ➜ Updog 網頁

1. 使用剛剛的 `code_chunk_prac.Rmd`

1. 將 `code_chunk_prac.html` 上傳至  
雲端硬碟的 `Updog/<site-name>`

1. 等 30 秒左右，就可以在  
.s[[https://`<site-name>`.updog.co/code_chunk_prac.html]()]  
看到輸出的 HTML 了

???
Updog 就是一個提供靜態網頁伺服器的服務。它讓使用者能把雲端硬碟當成伺服器使用。

換句話說，你只要將 HTML 上傳到雲端硬碟裡的某個資料夾，那你之後就可以透過網址瀏覽這個 HTML 所形成的網頁。

(使用 liao961120)
這邊大家可以用 Dropbox 或是 Google drive 的帳號直接註冊 Updog。我在這邊實際示範一次從註冊 Updog 到上傳 HTML 檔。

---

## [GitHub](https://github.com) <img src='img/GitHub-Mark.png' style='display:inline;width:0.7em;'> .s[(A Better Option)]

- <s>世界最大男性社交網站</s>

- 原始碼[版本控制](https://zh.wikipedia.org/zh-tw/版本控制) (備份)、專案規劃與管理、合作開發

- 許多軟體開發相關的實用、免費服務

- 架設網站

- 轉個彎之後 ...  
  .ms[[寫論文](https://github.com/sih4sing5hong5/huan1-ik8_lun7-bun5)、[課程管理](https://happygitwithr.com/classroom-overview.html)]

.footnote[.ms[
快速上手：[透過 GitHub 架設靜態網頁](https://liao961120.github.io/2018/04/20/gsheet_survey.html#靜態網頁-設置)

學習資源：
  - https://lab.github.com
  - [Happy Git and GitHub for the useR](https://happygitwithr.com)
]]

???
剛剛介紹的 Updog 是個能快速上手的服務。

但是日後，如果你們還有持續使用 R 或是 R Markdown，你們電腦裡的檔案數量應該會開始倍增。這種情況下，檔案管理和備份就開始變得很重要。而雲端硬碟並不是一個適合檔案管理的工具。

我這邊要推薦 GitHub 這套服務。那有個笑話是說，GitHub 是號稱全世界最大的男性社交網站，因為上面的使用者很大比例都是從事軟體開發相關工作的男性。

**所以 GitHub 到底是什麼呢？**  
其實 GitHub 是一個提供軟體開發時，程式碼版本控制的服務。那版本控制是什麼？這一時說不清楚，但你們可以把它想像成一種非常可靠的備份程式碼的方式。

那除了備份程式碼，GitHub 也提供了軟體開發過程中 會用到的其它服務，**包含網站的架設**。簡單來說，GitHub 就是一個減輕軟體開發負擔的綜合服務。

那因為 GitHub 的服務是免費的，而且它也沒規定你一定要把它用在軟體開發。  
所以轉個彎之後，我們可以把 GitHub 拿來做很多事情。譬如說，很多研究人員，是使用 GitHub 來管理自己的研究的。更不用說，有很多碩博士生是使用 GitHub 來管理他的論文的。GitHub 甚至可以用在課程教學上。

]

---

# 輸出 PDF 文件

???
接下來，要進入第一部份的最後一個主題，也就是用 R Markdown 輸出成 PDF 文件。

這個部份是今天的**大魔王**。

---

background-color: black
background-image: url("img/thanos.gif"), linear-gradient(to bottom, rgba(0,0,0, 1) 100%, rgba(0,0,0, 1) 100%)
background-size: contain, 100% 100%, cover

---

## 一條崎嶇的道路

???
那為什麼用 R Markdown 輸出 PDF 是大魔王呢？

大家可以看到這張 R Markdown 輸出文件的流程圖。上面那一排是 R Markdown 輸出 HTML 的過程。而下面那排是 R Markdown 輸出 PDF 的過程。

輸出 PDF 的過程，比起 HTML 多出了兩個兩個過程。而這兩個過程會造成輸出 PDF 非常容易出錯，因為過程中會使用到 LaTeX 這個工具。

前面有講到，LaTeX 是一個標記式語言。同時它也是一個用來將這種標記式語言生成 PDF 的工具。LaTeX 非常的複雜，而且它的要求非常嚴苛，所以在生成 PDF 的過程中常常會噴錯。

`--`

- 麻煩的中文字 (xelatex, 字體檔)

- 安裝 `$\LaTeX$`: 2018 之後的人生比較輕鬆

???
再加上我們比較衰，我們寫的是中文不是英文。而中文字因為有編碼的問題，在用 R Markdown 輸出 PDF 之前，需要一些額外的步驟。

不過好事情是，去年有一個 R 套件叫做 `tinytex`，它的出現讓我們在 R Markdown 裡面輸出 PDF 變得容易很多。

那接下來，我們就一起走過這條崎嶇的道路。

---

## 安裝 tinytex (TinyTeX)

#### **Windows 7/8/10**

1. 下載並解壓縮 TinyTeX:  
.s[[TinyTeX-win10.7z](https://www.space.ntu.edu.tw/navigate/s/58982B896253450A8BC2D87B26174229QQY) (72 MB) 或   
[TinyTeX-win10.zip](https://www.space.ntu.edu.tw/navigate/s/C8CCDD374E474DAC8DB8782B0A1B264CQQY) (108 MB)]

2. 
```r
install.packages('tinytex')
tinytex::use_tinytex()
```

3. 選取解壓縮後的 `TinyTeX` 資料夾<sup>＊</sup>

4. .s[(多試幾次)] 關閉再重新打開 RStudio，輸入

```r
  tinytex:::tinytex_root()
  #> if failed, i.e returning: [1] ""
  #> then try again
  ```
]

#### **Mac** .ms[or] 步驟 4. 失敗

1. 直接安裝 TinyTeX
  
  ```r
  install.packages('tinytex')
  tinytex::install_tinytex()
  ```

- 這種方式比較耗費時間

- 參考 .s[[Using TinyTeX from a Flash Drive](https://yihui.name/en/2018/08/tinytex-flash-drive)] 打包 TinyTeX
.s[(左欄方式)]

]

???
我這邊先講投影片右邊，比較簡單，但是安裝過程中需要等待相當久的方式。如果你的電腦是 Mac 或是你比較不喜歡冒險的話，那你可以先用這種方式。

左邊那種方式，只有 Windows 的電腦可以使用。 那我只在 Windows 7 和 10 上測試過，所以並不保證一定能成功。當然失敗也沒關係，只要再用右邊那種方式就好。

### Mac

那右邊這種方式非常簡單，只要把那兩行指令複製貼上到你的 Rstudio 裡面就好。那過程中應該會跳出一些警告的視窗，那這些視窗並不會影響安裝，只要按確定就好。

### Windows 7/8/10

那左邊這種方式，大家需要先下載步驟 1 的壓縮檔。那如果你的電腦可以解壓縮 `.7z 壓縮檔` 就下載第一個，那如果不行就請下載 `.zip 檔`。

---

## 小心設定 .s[(因為中文字)]

#### YAML Frontmatter

```yaml
title: "YAML for PDF Document"
author: "廖永賦\\thanks{作者資訊}"
documentclass: article
geometry: a4paper
linestretch: 1.35
links-as-notes: true
output:
  bookdown::pdf_document2:
*   latex_engine: xelatex
    number_sections: no
    toc: no
*   includes:
*     in_header: header.tex
```
]

???
這張投影片是給大家看看輸出中文 PDF 需要的額外步驟。

首先，在 R Markdown 的 YAML frontmatter 中，我們一定要加上黃色螢光標記的這 3 行，否則一定會出錯。

那大家可以看到最後一行有個 `header.tex` 的檔案，這個檔案就是額外設定 LaTeX 中文相關選項的地方。

`--`

```tex
*\usepackage{fontspec}
*\usepackage{xeCJK}
\usepackage{float}
\usepackage[fontsize=12pt]{scrextend}
\setlength{\parskip}{0.35cm}

*\setCJKmainfont{標楷體}
*\setCJKmonofont{Noto Sans Mono CJK TC}
*\XeTeXlinebreaklocale "zh"
*\XeTeXlinebreakskip = 0pt plus 1pt

\renewcommand{\figurename}{圖}
\renewcommand{\tablename}{表}
\renewcommand{\contentsname}{目錄}
\renewcommand{\listfigurename}{圖目錄}
\renewcommand{\listtablename}{表目錄}
\renewcommand{\appendixname}{附錄}
\renewcommand{\abstractname}{摘要}

\renewcommand{\textfraction}{0.05}
\renewcommand{\topfraction}{0.8}
\renewcommand{\bottomfraction}{0.8}
\renewcommand{\floatpagefraction}{0.75}
```
]

???
右邊這個就是部份 `header.tex` 的內容。那大家不用擔心，這裡可以不用去管它。那告訴大家這個東西，只是讓大家知道有時候，如果你想要輸出的 PDF 有特定的外觀，必須要去修改 `header.tex` 的內容。

---

## 更簡單的方式：.s[R Markdown .s[模板]]

```r
install.packages('remotes')
remotes::install_github('liao961120/rmdtk')
rmdtk::download_fonts()
```

#### 2. 匯入模板

- 指令

```r
  rmarkdown::draft('my_new_doc', template = 'CJKdocument', package = 'rmdtk')
  ```

- RStuido GUI .ms[(見右)]:
  
  .ms[File → New File → R Markdown → From Template →  
  **Portable CJK Document for HTML & PDF**]

]

???
那事實上，RStudio 提供了一個方常方便的功能。你可以透過 Rstudio 匯入 R Markdown 的模板。那這些模板是由 R 套件所提供的。

為了減少我自己以及大家在設定時的麻煩，我快速寫了一個 R Markdown 模板。這個模板幫使用者預先設定好了一些選項，也幫使用者解決 LaTeX 常會遇到的字體問題。所以基本上，你只要下載這個模板之後，就可以直接將 R Markdown 輸出成 PDF，而不用擔心額外的設定。

(記得提醒：能同時輸出 **2 種**格式)  
那我這邊示範一次給大家看看

---

background-image: linear-gradient(to bottom, rgba(255,255,255,0.4) 0%, rgba(255,255,255,0.4) 100%), url("https://bit.ly/2VCakjd")
background-position: center
background-size: contain, 100% 100%, cover

---

## Part Ⅰ: Wrap Up

![:scale 100%](img/part1_wrapup_lr.png)

???
這張流程圖是把剛剛講過的重點整理在一起。

如果你之後什麼都忘記了，至少要看得懂這張流程圖。看得懂這張流程圖，就代表你會使用 R Markdown。

---

# Advanced Topic: <br>.s[Bibliographies & Citations]

---

background-image: url(https://imgy.netlify.com/bg/road-straight.jpg)
background-position: center
background-size: cover
class: center, ml, inverse, bottom

自行閱讀: [Zotero + R Markdown Tutorial](https://ikashnitsky.github.io/2019/zotero)

???
關於如何在 R Markdown 插入文獻引用，因為設定和使用上比較複雜，也不見得每個人都有使用需求，所以這部份我今天不講。

如果你有使用上的需求，我建議你可以閱讀這張投影片連結裡的文章。閱讀完這篇文章之後，下面兩張投影片你就能看懂了。

---

## Bibliographies & Citations

#### .l[Prerequisites]

1. BibTeX: `ref.bib` .ms[(1 entry)]

<pre><code class='bib hljs nix remark-code'>@article{<span class="remark-code-span-highlighted">leung2008</span>,
      title = {Multicultural Experience Enhances Creativity},
      year = {2008},
      journal = {American Psychologist},
      author = {Leung, Angela Ka-yee and Maddux, William W.},
    }
    </code></pre>

1. 文獻引用格式: `apa.csl`

.s[下載：[Official CSL Repo](https://github.com/citation-style-language/styles), [Zotero Style Repo](https://www.zotero.org/styles)]
]

#### .l[Workflow]

1. **書目管理軟體**整理文獻  
.s[
(推薦 [Zotero](https://www.zotero.org) + [Better BibTeX extension](https://retorque.re/zotero-better-bibtex)<sup>＊</sup>)
]

1. 透過**書目管理軟體**匯出 `.bib` 檔

1. 使用 [Citation Syntax](https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html#citation_syntax) 插入引用文獻  
(or 使用 [`citr` 套件](https://github.com/crsh/citr) 幫助你)
    
  <pre><code class='md hljs markdown remark-code'>Leung says blah blah <span class="remark-code-span-highlighted">[-@leung2008]</span>.
  </code></pre>

.footnote[.s[
[.s[＊]]: .s[(就我所知)] Zotero 是目前唯二[可控制 `.bib` 檔之 citekey pattern](https://retorque.re/zotero-better-bibtex/citation-keys) 的免費書目管理軟體。
]]

]

---

## Bibliographies & Citations .ms[(Cont.)]

### Two Systems

- Support: HTML & PDF (LaTeX)

- YAML Frontmatter

```yml
*bibliography: ref.bib
*csl: apa.csl
output: bookdown::html_document2
```
]

- Support: PDF (LaTeX) only

- YAML Frontmatter

```yml
*bibliography: ref.bib
output:
  bookdown::pdf_document2:
*   citation_package: natbib
```

]

---

# Part Ⅱ
# .l[Applications]

???
接下來要進入今天的尾聲了。

這部份不會有實際的操作，大家就輕鬆的聽聽就好。  
它的目的只是提供一些學習資源，讓想要更深入學習 R Markdown 的人，知道要從哪裡開始。

---

background-image: url(https://pbs.twimg.com/media/DDzY0_BXcAA1xQw.png)
background-position: 50% 65%
background-size: 80%

## Ecosystem of R Packages

???
這張圖是 R 套件所組成的一個網絡圖。從這張圖，你大概可以看出來 R 套件形成了一個個的子領域，

譬如說最中間、最大的那個就是「資料前處理」的相關套件，在「資料前處理」的正下方，是以 ggplot2 為主而形成的「資料視覺化」的相關套件。

那大家可以看到這邊還有非常多的子領域，而每個人有興趣的領域可能會不一樣。像我自己就很喜歡 R Markdown，所以我就一直在這領域裡面打滾、把 R Markdown 相關的套件都玩的很熟。這在不知不覺中，大幅的提昇了我 R 語言的功力。

我這邊想要鼓勵大家去探索 R 套件的生態圈。  
在這個過程中你可能會發現一個你很感興趣的套件，那這個套件就會是你的好夥伴，它會讓你在學習 R 語言上變得非常有動力。隨著你越來越熟悉這個套件，你也會開始認識到周圍的、其它相關的套件。這些套件或許會更有趣，那你可能就會更進一步的去探索這些套件。

這個反覆的過程能夠讓你很快樂的學習 R 語言，同時也會讓你 R 語言的功力快速成長。

---

background-image: url(https://imgy.netlify.com/gif/jump-off.gif)
background-position: center
background-size: 100%
background-color: black
count: false

???
那在探索未知的套件的時候，你常常會需要接觸完全陌生的東西。這看起來還蠻困難的，有時候你甚至會不敢去嘗試。但是常常在你真正踏出第一步 去嘗試過後，你才會發現其實並沒有像想像中的那麼困難。

有時候，我們就是需要一個開頭、一個引子，好讓我們知道要如何跨出第一步。那我這邊，就提供一些，我覺得相當不錯的學習資源給大家參考。

---

## bookdown.org .ms[.ms[(https://bookdown.org)]]

### R Basics

- [Hands-On Programming with R](https://rstudio-education.github.io/hopr)

- [R for Data Science](https://r4ds.had.co.nz)

### Special Domain

- [Text Mining with R](https://www.tidytextmining.com)

- [Geocomputation with R](https://geocompr.robinlovelace.net/)

???
bookdown 是一個 R Markdown 生態圈裡的套件，它讓 R Markdown 可以用來寫書。bookdown.org 是一個收錄這些使用 bookdown 套件撰寫的書籍。你可以在這個網站裡，看到很多 R 語言相關的書籍，這當中有不少相當不錯的書。

我這邊列出的四本是我看過，而且我覺得寫得相當好的書。前面兩本是關於 R 語言本身的介紹。後面兩本就是特殊的領域，像這邊是文字探勘還有地理資訊的領域。

---

# R Markdown Ecosystem

???
剛剛是比較 general 的 R 套件生態圈的學習資源。如果你的興趣和我一樣都是 R Markdown 的話，我這裡可以提供一些關於 R Markdown 的建議。

---

![:scale 100%](img/rmd_eco.svg)

???
前面講過，R Markdown 能夠輸出成很多種格式。依據不同的目的，你會需要使用不同的套件。

1. 如果使用 R Markdown 的目的就和今天介紹的主軸一樣，也就是，你希望用 R Markdown 寫筆記、寫文件或是寫作業這類比較「傳統」的文書處理，那你應該探索的是 bookdown 這個套件。

2. 如果你對網頁比較有興趣，而且想架設一個個人網站，那你可以從 blogdown 這個套件開始探索。

3. 最後，是 R Markdown Websites。這個不是一個套件，它是 rmarkdown 所提供的一種輸出格式。它跟 blogdown 不同的地方在於， R Markdown Websites 適合做的是比較簡單的網站，像是只有一個頁面的那種網站。所以，譬如說，你可以用 R Markdown Websites 來呈現資料視覺化專案的成果。

之後的幾張投影片就是這些 R Markdown 相關套件的學習資源。大家可以依據自己的興趣和需求，去更深入的了解這些套件。

---

background-image: url(https://bookdown.org/yihui/bookdown/images/cover.jpg)
background-size: 20%
background-position: 85% 40%

## 書籍撰寫 (bookdown)

- [bookdown book](https://bookdown.org/yihui/bookdown) ([PDF](https://bookdown.org/yihui/bookdown/bookdown.pdf)): 學習 R Markdown 的好資源

- 同時輸出 [GitBook](https://www.gitbook.com) 與 PDF Book
    - 可以拿來[寫論文](https://github.com/liao961120/ntuthesis)

<br>

![:scale 60%](img/gitbook.png)
---

background-image: url(img/twlangsurvey.gif)
background-size: 65%
background-position: 91% 88%

## 網站: [R Markdown Websites](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html)

- 適合製作**簡單**網站

- 單頁 .s[or] 少量頁面

---

background-image: url(https://bookdown.org/yihui/blogdown/images/logo.png)
background-position: 85% 75%

## 部落格 (blogdown)

- [blogdown book](https://bookdown.org/yihui/blogdown) ([PDF](https://bookdown.org/yihui/blogdown/blogdown.pdf))

- [Why start a blog?](http://varianceexplained.org/r/start-blog)

- 架站太難？

???
Why Start a blog?
- 整理、記錄自己做過什麼
- 從寫作當中學習

---

background-image: url(https://liao961120.github.io/slides/img/pictures/cabin.jpg)
background-position: center
background-size: cover

# .l[Thank You]

---

background-image: url(https://liao961120.github.io/slides/img/pictures/cabin.jpg)
background-position: center
background-size: cover

---

background-image: linear-gradient(to bottom, rgba(255,255,255,0.8) 0%, rgba(255,255,255,0.8) 100%), url(https://liao961120.github.io/slides/img/pictures/cabin.jpg)
background-position: center
background-size: cover

# Contact Info

### Yongfu Liao
.l[
- <https://liao961120.github.io>

- ![:scale 1em](img/GitHub-Mark.png) [liao961120](https://github.com/liao961120)

]

- File an issue at [![:scale 1em](img/GitHub-Mark.png) liao961120/2019-fju-rmd-talk](https://github.com/liao961120/2019-fju-rmd-talk/blob/master/README.md) (Preferred)

- Email

]