輕量級標記式語言

If you can’t explain it simply, you don’t understand it well enough.

Albert Einstein

經過如何獲取資料、如何掌控資料、如何探索資料以及如何預測資料,我們已經掌握將資料導入 Python 與 R 的分析環境,利用撰寫程式整理成符合分析所需的樣式,通過視覺化探索資料的特徵,還有使用機器學習對未知資料進行數值或分類標籤的預測等技巧。接下來資料科學專案僅剩下最後一哩路,也就是向其他團隊的成員解釋專案中的發現,如果能夠有效地向合作部門(像是產品、行銷與管理團隊等)精準地傳達分析結果,將能顯著為資料科學專案的成果加值,提升資料科學團隊在組織內的價值。

如何溝通資料的篇章主要探討能協助團隊傳達資料科學分析專案的技術以及工具,如何透過它們幫助一個對於專案毫無涉獵的人,快速且輕鬆地了解專案發現了哪些有趣且有價值的事情。

Markdown 簡介

從 GitHub 上的讀我檔案(README.md)、Jupyter Notebook 的文字儲存格、RMarkdown 的文字區塊到靜態網站產生器(Static Site Generator)的文字檔案,Markdown 逐漸成為現代軟體開發者以及資料科學團隊必備的輕量標記語言,透過 Markdown 語法讓我們能夠撰寫易於閱讀、撰寫的純文字,並透過像是 pandoc 的轉換器選擇性地輸出多樣格式(如 HTML、Word 或者 PDF。)

現代資料科學團隊大量使用 Jupyter Notebook 與 RMarkdown 作為整合文字敘述、程式碼、執行結果與視覺化的工具,其文字敘述的部分就是以 Markdown 語法為主。團隊內部的溝通常以筆記本模式進行,而與合作部門的決策者溝通時則採用報告模式。我們只需維護一個 .ipynb(Jupyter Notebook 文件的副檔名,意即 Interactive Python Notebook)或一個 .Rmd(RMarkdown 文件的副檔名),並透過調整終端機輸出指令或者 YAML 格式,就可以將純文字檔案轉換為筆記本模式以及報告模式。

常用的 Markdown 語法

Visual Studio Code 是學習 Markdown 語法的利器,它針對副檔名為 .md 的檔案支援即時預覽功能(Open Preview to the Side),在編輯文件的時候 Windows 使用者可以按下 Ctrl +K + V、Mac 使用者可以按下 Command + K + V 在側邊開啟即時預覽的視窗。

啟動即時預覽之前

啟動即時預覽之後

Markdown 語法使用井字號 # 建立標題文字,不同數量的 # 會顯示出不同階層的 HTML 標題,可以產出 <h1></h1><h6></h6> 的 HTML 標籤。

# 標題階層一

## 標題階層二

### 標題階層三

#### 標題階層四

##### 標題階層五

###### 標題階層六
1
2
3
4
5
6
7
8
9
10
11

不同數量的 # 會顯示出不同階層的 HTML 標題

產出  到  的標籤

Markdown 語法使用 *+- 製作無順序的標點清單列表,可以產出 <ul><li></li></ul> 的標籤;使用 1.2.3. 製作有順序的數字清單列表,則能夠產出 <ol><li></li></ol> 的 HTML 標籤。

## 清單

### 無順序的標點清單列表

* 第 1 點
    * 第 1-1 點
    - 第 1-2 點
    + 第 1-3 點
- 第 2 點
+ 第 3 點

### 有順序的數字清單列表

1. 第 1 點
2. 第 2 點
3. 第 3 點
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

無順序的標點清單列表與有順序的數字清單列表

產出  或  的標籤

Markdown 語法使用 <LINK>[LINK TEXT](LINK) 嵌入連結,能夠產出 <a href></a> 的 HTML 標籤。

## 連結

<https://www.datainpoint.com>

[DataInPoint](https://www.datainpoint.com)
1
2
3
4
5

嵌入連結

產出  的的 HTML 標籤

Markdown 語法使用 ![IMG TEXT](IMG) 在文字敘述中嵌入圖片,能夠產出 <img src> 的 HTML 標籤。

## 圖片

![Nick Young](https://i.imgur.com/Gr8dqt5.jpg)
1
2
3

嵌入圖片

產出  的 HTML 標籤

Markdown 語法使用 > 製作引用區塊,能夠產出 <blockquote></blockquote> 的 HTML 標籤。

## 引用

> Life was like a box of chocolates. You never know what you're gonna get.
1
2
3

引用

產出  的 HTML 標籤

Markdown 語法使用 $$$$$$ 嵌入數學方程式,能夠產出能夠被 MathJax 框架解讀的 <script></script> HTML 標籤。

## 數學方程式

### 行內方程式

這是行內方程式 $S(x) = ^1/_{1+e^{-x}}$

### 方程式區塊

這是方程式區塊:

$$S(x) = \frac{1}{1+e^{-x}}$$
1
2
3
4
5
6
7
8
9
10
11

數學方程式

產出能夠被 MathJax 框架解讀的  HTML 標籤

Markdown 語法使用 ***---___ 製作水平分隔線,能夠產出 <hr> 的 HTML 標籤。

## 水平分隔線

第一個水平分隔線:

***

第二個水平分隔線:

---

第三個水平分隔線:

___
1
2
3
4
5
6
7
8
9
10
11
12
13

水平分隔線

產出  的 HTML 標籤

Markdown 語法使用 |-: 製作表格,能夠產出 <table></table><thead></thead><tr></tr><th></th><tbody></tbody> 的 HTML 標籤。

## 表格

|預設|靠右對齊|靠左對齊|置中對齊|
|---|------:|:-----|:-----:|
|12 |12     |12    |12     |
|123|123    |123   |123    |
|1  |1      |1     |1      |
1
2
3
4
5
6
7

表格

產出表格相關的 HTML 標籤

Markdown 語法使用 *文字* 或者 _文字_ 製作斜體、使用 **文字** 或者 __文字__ 製作粗體,能夠分別產出 <em></em><strong></strong> 的 HTML 標籤。

## 強調

### 斜體

Let's put aside the fact that you "*accidentally*" picked up my grand mother's ring and you "_accidentally_" proposed to Rachel.

### 粗體

Let's put aside the fact that you "**accidentally**" picked up my grand mother's ring and you "__accidentally__" proposed to Rachel.
1
2
3
4
5
6
7
8
9

斜體與粗體

產出  、  的 HTML 標籤

Markdown 語法使用 ~~文字~~ 製作刪除線,能夠產出 <del></del> 的 HTML 標籤。

## 刪除線

這是一段~~具有刪除線的~~文字敘述。
1
2
3

刪除線

產出  的 HTML 標籤

在這個段落我們涵蓋常見的 Markdown 語法,如果對於其他撰寫文章時會使用到的進階語法,如引用參照、文字上標、文字下標與不同風格(包含 GitHub、pandoc 風格等)有興趣的讀者,可參考延伸閱讀。

輸出 Jupyter Notebook

副檔名為 .ipynb 的 Jupyter Notebook 在筆記本模式下已經是資料科學團隊成員溝通的標準格式之一,然而因應不同的場合與對象,還有其他常見的格式可以透過終端機利用 jupyter nbconvert 的指令輸出像是常見的網頁(HTML)、文件(PDF)與投影片格式(Reveal JS),在 jupyter nbconvert 的官方文件可以看到它所支援不同的輸出格式:

  • HTML
  • PDF
  • Reveal JS
  • Markdown(.md)
  • ReStructured Text(.rst)
  • Executable script

在 Jupyter Notebook 中要使用 Markdown 語法時要注意更換儲存格格式:

更換儲存格格式為 Markdown

如果是在 Google Colab 使用則加入一個文字儲存格:

加入一個文字儲存格

接著我們在 Jupyter Notebook 中輸入了一些內容、程式與圖形輸出:

https://github.com/yaojenkuo/datainpoint/blob/master/communication/demo.ipynb

在 Jupyter Notebook 中輸入了一些內容、程式與圖形輸出

回到終端機,使用 jupyter nbconvert 指令將 Jupyter Notebook 輸出為網頁格式(HTML)。

# Command line
jupyter nbconvert --to html demo.ipynb
open demo.html
1
2
3

將 Jupyter Notebook 輸出為網頁格式

將 Jupyter Notebook 輸出為網頁格式

回到終端機,使用 jupyter nbconvert 指令將 Jupyter Notebook 輸出為文件格式(PDF)。

# Command line
jupyter nbconvert --to pdf demo.ipynb
open demo.pdf
1
2
3

將 Jupyter Notebook 輸出為 PDF 格式

將 Jupyter Notebook 輸出為 PDF 格式

將 Jupyter Notebook 輸出為 PDF 格式

如果希望製作為投影片,在編輯 Jupyter Notebook 時應該要先加入投影片的分頁點。

加入投影片的分頁點

加完分頁點之後,回到終端機在資料夾中加入 Reveal JS 模板並以 jupyter nbconvert 指令將 Jupyter Notebook 輸出為投影片格式(Reveal JS)。

# Command line
git clone https://github.com/hakimel/reveal.js.git
jupyter nbconvert demo.ipynb --to slides --reveal-prefix reveal.js
open demo.slides.html
1
2
3
4

將 Jupyter Notebook 輸出為投影片格式(Reveal JS)

將 Jupyter Notebook 輸出為投影片格式(Reveal JS)

輸出 RMarkdown

副檔名為 .Rmd 的 RMarkdown 亦是資料科學團隊成員溝通的標準格式之一,因應不同的場合與對象,還有其他常見的格式可以透過更改 .Rmd 的 YAML 區塊設定,輸出成常見的網頁(HTML)、文件(PDF)與投影片格式(Reveal JS),在 RMarkdown 的官方文件可以看到它所支援不同的輸出格式:

  • HTML
  • PDF
  • MS Word
  • Beamer
  • HTML5 slides
  • Tufte-style handouts
  • books
  • dashboards
  • shiny applications
  • scientific articles
  • websites

我們在 RMarkdown 文件中輸入了一些內容、程式與圖形輸出:

https://github.com/yaojenkuo/datainpoint/blob/master/communication/rmd_demo.Rmd

在 RMarkdown 文件中輸入了一些內容、程式與圖形輸出

在 RStudio 的頁面中編輯 .Rmd 檔案的 YAML 區塊,將 output 參數設定為 html_document,然後按下 Knit 將 .Rmd 輸出為網頁格式(HTML)。

將 .Rmd 輸出為網頁格式(HTML)

將 .Rmd 輸出為網頁格式(HTML)

在 RStudio 的頁面中編輯 .Rmd 檔案的 YAML 區塊,將 output 參數設定為 pdf_document,然後按下 Knit 將 .Rmd 輸出為文件格式(PDF)。

將 .Rmd 輸出為文件格式(PDF)

將 .Rmd 輸出為文件格式(PDF)

在 RStudio 的頁面中編輯 .Rmd 檔案的 YAML 區塊,將 output 參數設定為 revealjs::revealjs_presentation,然後按下 Knit 將 .Rmd 輸出為投影片格式(Reveal JS),必須先安裝套件 install.pacakges("revealjs", type = "source") 才能成功輸出。

將 .Rmd 輸出為投影片格式(Reveal JS)

將 .Rmd 輸出為投影片格式(Reveal JS)

將 .Rmd 輸出為投影片格式(Reveal JS)

將 Jupyter Notebook 上傳至 GitHub/GitLab

GitHub 與 GitLab 皆是透過 Git 進行版本控制的原始碼代管網路服務,這兩個服務不僅預設使用 README.md 作為讀我檔案的格式,也支援 Markdown 文件以及 Jupyter Notebook 直接預覽的功能,這使得資料科學團隊不需要額外將 Jupyter Notebook 輸出成網頁格式,就能透過專案的 GitHub 與 GitLab 連結以筆記本模式分享、溝通與協作。對 Git 終端機指令、GitHub 與 GitLab 設定等詳細資訊有興趣的讀者,可以參考延伸閱讀。

GitHub

# Command line
git add demo.ipynb
git commit -m "first commit"
git push -u github master
1
2
3
4

將 Jupyter Notebook 上傳至 GitHub

從 GitHub 專案直接瀏覽 Jupyter Notebook:

https://github.com/yaojenkuo/datainpoint/blob/master/communication/demo.ipynb

GitLab

# Command line
git add demo.ipynb
git commit -m "first commit"
git push -u gitlab master
1
2
3
4

將 Jupyter Notebook 上傳至 GitLab

從 GitLab 專案直接瀏覽 Jupyter Notebook:

https://gitlab.com/datainpoint/datainpoint.gitlab.io/blob/master/demo.ipynb

將 RMarkdown 上傳至 GitHub/GitLab

目前 GitHub 或 GitLab 都沒有支援直接預覽 .Rmd,不過 GitHub 與 GitLab 都有靜態網頁的架站功能,只需要啟動寄存服務(hosting service)就可以將輸出為 HTML 的 RMarkdown 用一個網址以網頁模式分享與溝通。

GitHub

GitHub 的靜態網頁服務稱為 GitHub Pages,點選 Repository 的設定(Settings),並移動至 GitHub Pages 的區段選擇一個主題(theme),接著送出 Commit 就可以完成。

啟動 GitHub Pages

啟動 GitHub Pages

啟動 GitHub Pages

將 RMarkdown 輸出的 HTML 檔案加入專案:

# Command line
git add rmd_demo.html
git commit -m "first commit"
git push -u github master
1
2
3
4

從 GitHub Pages 瀏覽 HTML:

https://yaojenkuo.io/datainpoint/communication/rmd_demo

從 GitHub Pages 瀏覽 HTML

GitLab

GitLab 的靜態網頁服務稱為 GitLab Pages,對初學者最容易的設定方法為 fork 一個靜態網頁產生器(Static Site Generator, SSG)的模板,我推薦選擇 Hugo、Hexo 或者 Jekyll,GitLab 提供的這些靜態產生器模板可以在此連結執行 fork:https://gitlab.com/pages。Fork 之後首先前往設定將關係移除(Remove Fork Relationship),因為我們並沒有要對原本的專案做出貢獻。

將 Fork 關係移除

接著可以將 RMarkdown 輸出的 HTML 檔案加入專案:

# Command line
git add rmd_demo.html
git commit -m "first commit"
git push -u gitlab master
1
2
3
4

這個動作會引發建立(Trigger Build),稍微等待之後就可以在 Pages 頁面看到連結。

GitLab Pages 連結

從 GitLab Pages 瀏覽 HTML:

https://datainpoint.gitlab.io/rmd_demo.html

從 GitLab Pages 瀏覽 HTML

小結

在這個小節中我們涵蓋 Markdown 簡介、常用的 Markdown 語法、如何結合 Markdown 文字、程式與圖形於 Jupyter Notebook 和 RMarkdown 之間、應用 GitHub 與 GitLab 分享呈現 Jupyter Notebook 以及應用 GitHub Pages 與 GitLab Pages 分享呈現 RMarkdown 所輸出的 HTML 格式。

延伸閱讀