第21章 R Markdown: html

データ分析の再現可能性の必要性は論を俟たないですが、再現可能性を担保するにはレプリケーションデータやコードを公開するだけでなく、それらが理解可能である必要があります。

  • 恐ろしいことに自分が書いたコードでさえ数カ月後に読み返すと意味がわからないことはまれによくあります。

Rスクリプトに#でコメントするのが単純な方法ですが、データ分析においてはしばしば文章とコード、アウトプットを混在させたノートブックを使用することがあります。

  • 詳しくはないですが文芸的プラグラミングと呼ばれるものの一種のような気がします。

更にノートブックからより見やすいファイルを作成することができ、そのファイルおよびシステムをR Markdownと呼びます。 実は、と言うほどではないですが、このブログもR Markdownで書かれています。

21.1 R Markdownファイルの作成

百聞は一見に如かずなので、一まずはR Markdownを使ってみます。 まず、左上のファイルを作成するボタンを押し、R Markdown...を選択します。

  • 初めてR Markdownを使う場合は必要なパッケージをインストールするか聞かれるのでインストールを選択します。

続いて、どのような種類のR Markdownファイルを作成するかを選択するので、（デフォルトのままですが）DocumentのHTMLを選択します。

すると、エディタに以下のようなサンプルのRmdファイルが表示されます。 適当なフォルダに保存し、エディタ上部のKnitをクリックするかShift + Ctrl + kを押すとR Markdownファイルがタイプセットされます。

無事、タイプセットに成功すると以下のような.htmlファイルのプレビューが表示されます。

.Rmdファイルを保存したフォルダに.htmlファイルが生成されているはずです。 .htmlファイルとはウェブサイトを作成するためのファイルで、ウェブブラウザ（例、FirefoxやGoogle Chrome）で開くことできれいに見れます。

21.1.1 参考になるサイト

21.2 Markdown記法

21.2.1 Markdownとは*

R MarkdownとはMarkdownとRスクリプトを合体させたようなものです。 ここではMarkdownについて説明しますが、読み飛ばしても構いません。

Markdownとは計量マークアップ言語と呼ばれているようにマークアップ言語の一種です。 マークアップ言語とは文章の中身と役割・外見を区別して記述する言語です。

逆に、世間で普及しているWordのように文章の中身と役割・外見が混在しているエディターはWYSIWYGと呼びます。

例えば、Wordではセクションの名前などは指定することができますが、見た目はフォントのサイズが大きくなったり、太字になったりします。 一方で、マークアップ言語の一種である.htmlファイルでは

<h1>セクションタイトル</h1>

のように明示的にh1というタグをつけ、h1タグのついている文章に対して.cssファイルで見た目を決定します。 同様に、LaTeXでは\section{セクションタイトル}のようにタグをつけます。

基本的にはWYSIWYGなソフトのほうが直観的な操作が可能で作業が楽ではあるものの、マークアップ言語はテキストで役割や外見も決めるので再現可能性が高いと言えるでしょう。

そこで、より簡便なマークアップ言語として登場したのがMarkdown記法です。 なので、HTML記法を使うこともできます。

21.2.2 セクション

Markdownでは#を使ってセクションのタイトルを記述します。 #が多くなればなるほどより小さな見出しになります。

# レベル1
## レベル2
### レベル3
#### レベル4

21.2.3 パラグラフ

空行を入れると新しいパラグラフになります。

同じパラグラフです。
同じパラグラフです。

同じパラグラフです。 同じパラグラフです。

違うパラグラフです。

違うパラグラフです。

違うパラグラフです。

違うパラグラフです。

  • なので、パラグラフ内でも一文ごとに改行したほうが見やすいと思います。

21.2.4 箇条書き

番号なしの箇条書きの場合は=を、番号付きの箇条書きの場合は1.を入れます。

- 番号なし箇条書き
- 番号なし箇条書き
- 番号なし箇条書き
  • 番号なし箇条書き
  • 番号なし箇条書き
  • 番号なし箇条書き
1. 番号付き箇条書き
1. 番号付き箇条書き
1. 番号付き箇条書き
  1. 番号付き箇条書き
  2. 番号付き箇条書き
  3. 番号付き箇条書き

タブ（半角スペース4つ分）を入れると階層構造をつけることができます。

- レベル1
    - レベル2
- レベル１
  • レベル1
    • レベル2
  • レベル１

21.2.5 文字の強調

*もしくは_で囲むと斜体になり、**もしくは__で囲むと太字になります。

*斜体*と**太字**

斜体と太字

｀で囲むとコードになり、~~で囲むと打ち消されます。

`code`と~~打ち消し~~

codeと打ち消し

  • 日本語のLaTeXでは打ち消しに対応していないので、表示させていません。

21.2.6 引用

>から始めると引用になります。

> 引用文です。

引用文です。

21.2.7 リンク

リンクを貼る場合は[リンク名](リンク先のURL)あるいは<リンク先のURL>とします。

- [RStudio](https://www.rstudio.com/)
- <https://www.rstudio.com/>

21.2.8 画像、表

画像を埋め込む場合は![画像名](画像のパス)とします。

![Rlogo](figures/Rlogo.png)

Rlogo

表を埋め込む際には次のように書きます。

| 項目1 | 項目2 | 項目3 |
|-------|-------|-------|
| りんご| 100   | 赤    |
| みかん| 80    | オレンジ |
項目1 項目2 項目3
りんご 100 赤
みかん 80 オレンジ

21.2.9 数式

LaTeX記法による数式を記述できます。 インラインの場合は$で囲み、ディスプレイの場合は$$で囲みます。

  • .htmlの場合、mathjaxによって数式を表示するのでオフラインでは表示できません。
確率変数$X_i$は平均$\mu$、分散$\sigma^2$の正規分布に従う。

確率変数\(X_i\)は平均\(\mu\)、分散\(\sigma^2\)の正規分布に従う。

$$
  X_i \sim \mathcal{N}(\mu,\sigma^2)
$$

\[ X_i \sim \mathcal{N}(\mu,\sigma^2) \]

21.3 Rチャンク

R Markdown内でRコードを記述する際にはRチャンクと呼ばれるものの中で行います。 Rチャンクは次のような形をしています。 Ctrl + Alt + IでRチャンクを挿入することができます。

まず、この部分は後述するチャンクオプションを指定する場所になります。 ここではRコードであること、チャンク名をcarsと指定しています。

R MrkdownにおいてもRスクリプトと同様にCtrl + Enterでコードを実行することができます。 あるいはRチャンクの右上のボタンをクリックしても実行できます。 実行されたコードはチャンクの直下に表示されます。

右上から二番目のボタンはこのRチャンクの直前のRチャンクまでのコードを全て実行するボタンになります。

21.3.1 チャンクオプション

チャンクオプションを指定することでコードとそのアウトプットをどのように出力するかを制御することができます。 主なものをまとめておきます。

  • eval=FALSEとするとコードは表示されるが実行されない。
  • echo=FALSEとするとコードは実行されるが表示されない。
  • include=FALSEとするとコードは実行されるがコードも実行結果も表示されない。
  • warning=FALSEやerror=FALSE、message=FALSEとすると警告やエラー、メッセージが表示されない。

例えば、{r, echo=FALSE}のように書きます。

デフォルトを変更したい場合は冒頭でknitr::opts_chunk$set(echo=TRUE)のように設定します。

21.4 yamlヘッダー

yamlヘッダーとは.Rmdファイルの冒頭で---によって囲まれた箇所で、ページ全体の設定を行います。 初期状態では

---
title: "Untitled"
author: "Shohei Doi"
date: "4/9/2019"
output: html_document
---

となっていますが、titleやauthor、dateでタイトル、著者、日付を設定できます。

21.4.1 output

outputによって出力形式を決定します。 これによってyamlヘッダーにおいてどのような項目を設定できるのかも決まります。

どのような出力形式が利用可能であるかは後述するとして、以下ではhtml_documentにおける主なyamlヘッダーの設定を紹介します。

  • 前田先生のページが参考になります。

21.4.2 目次

目次を出力するには次のように書きます。

output:
  html_document:
    toc: TRUE

目次の設定には次のようなものがあります。

output:
  html_document:
    toc: TRUE
    toc_depth: 2
    toc_gloat: TRUE
    number_sections: TRUE
  • toc_depthによってどの階層の見出しまで表示するかを決めます。
  • toc_floatをTRUEにすると目次がスクロールしてもついてきます。
  • number_sectionsをTRUEにすると見出しに通し番号がつきます。

21.4.3 テーマ

テーマを決める場合はthemeで指定します。 テーマ一覧はこちらになります。

output:
  html_document:
    theme: "paper"

21.4.4 htmlとcss

cssによってカスタム.cssファイルを指定できます。 includeによって.htmlファイルの挿入ができます。

デフォルトでは.cssファイルは画像データなどは全て.htmlファイルに含まれてスタンドアロンな形で見ることができます。 しかし、self_containedをFALSEとすると付属ファイルは別フォルダに作成され、.htmlファイル自体が見やすくなります。

21.5 その他のテンプレート

outputを変更することで、いくつかのテンプレートを使用することができます。 ここでは.htmlファイルが出力されるいくつかのテンプレートを紹介しておきます。

21.5.1 Distill

Distillはウェブで公開することを念頭に置いた専門的な記事を書くためのテンプレートになっています。 インストールは以下のように行います。

devtools::install_github("rstudio/distill")
  • RStudioのバージョンは1.2以上であることが求められています。

インストールに成功するとR Markdown...の中のFrom TemplateにDistill Articleが追加されているはずです。

21.5.2 Tufte Handout

Tufte Handoutというテンプレートもあります。

Tufte Handout

tufteというパッケージをインストールするとテンプレートに追加されます。

21.5.3 rmdformats

rmdformatsというテンプレートもあります。 同様に、rmdformatsというパッケージをインストールします。

material

readthedown

html_clean

html_docco

21.5.4 スライド

R Markdownから作成できる.htmlファイルのスライドにはioslidesとslidyというものがあります。

ioslides

ioslides

slidy

slidy

これらはデフォルトで入っています。

また、reveal.jsという.htmlスライドを作ることもできます。 revealjsというパッケージをインストールするとテンプレートが追加されます。

  • Presentationの方ではない点に注意。

reveal.js

reveal.js

同様にしてxaringanというNARUTOという忍者マンガにインスパイアされたテンプレートを使用することもできます。

xaringan

xaringan

21.5.5 ダッシュボード

flexdashboardというパッケージを使うとダッシュボードを作ることができます。 パッケージをインストールするとFlex Dashboardというテンプレートが追加されます。

flexdashboard

21.5.6 Microsoft Office

R MarkdownからMicrosoft OfficeのWordやPowerPointの形式のファイルを作成することも可能です。