knitr によるレポートの作成

概要

講義: 60 分
演習: 15 分

質問

• ソフトウェアとレポートはどのように統合すればよいですか?

目標

• 再現可能なレポートの意義

• Markdown の基礎

• R コードのチャンク

• チャンクのオプション

• 文中の R コード

• 他の出力フォーマット

データ分析報告

データ分析家は、協力者や、将来参照する文章として、分析及び結果を記した 報告を数多く書く傾向にあります。

私が始めたばかりの頃は、全ての仕事についてRスクリプトを書いて、 結果を説明し、様々なグラフを添付したメールを協力者に送信していました。 結果を議論する際、どのグラフについて話しているのか混乱してしまうことがよくありました。

WordやLaTeXで正式な報告を書く様になったのですが、図を正しく表示 するためにかなり多くの時間を費やしました。大抵の場合、ページ分けで つまずきました。

今では、ウェブページ（htmlファイル）を作るようになり全てが楽になりました。 ひとつの長いページなるので、普通ではひとつのページに収まらないような高さの図 でもはみ出さずに入れることができます。「スクロールは友達」ですね。

読み書きできるプログラミング

分析報告書のようなものは、再現できる 文書であることが理想です。つまり、 エラーが見つかった場合や、データに追加があった場合など、単に報告書を 再コンパイルすることで、新しい、または正しい結果が得られるという形です （再現できない文書の場合、図を再作成し、Word文書に貼り付け、更に手作業で 様々な詳細結果に手を加えなえればなりません）。

Rでカギとなるツールは knitr です。これは、 コードと文章が混ざった文書を作成してくれるものです。 文書がknitrで処理される際にRコードが実行され、 グラフや他の結果が文書に挿入されます。

こういうものを「読み書きできるプログラミング（literate programming）」と呼びます。

knitrは、基本的にどんなテキストやコードでも組み合わせられるのですが、 RにMarkdownを合体させた、R Markdownがお勧めです。 Markdownは、ウェブページを作るための軽量なマークアップ言語です。

R Markdownファイルの作成

R Studioで、File → New File → R Markdown をクリックしましょう。 すると、次のようなダイアログボックスが出ます：

デフォルト（HTML output）のままでよいので、タイトルを付けましょう。

R Markdownの基本構成要素

最初のテキストの塊は、Rへの説明となります。つまり、 タイトル、著者者、日付といったものを書き込み、 html（つまりウェブページを）出力したいということを伝えましょう。

---
title: "Initial R Markdown document"
author: "Karl Broman"
date: "April 23, 2015"
output: html_document
---

入れたくなければ、これらのフィールドのいずれも消すことができます。 二重引用符は、厳密には 必須 ではありません。 大抵は、タイトルにコロンを含めたいときに使います。

RStudioは、始めやすいように、例がいくつか入れられてある文書を作成します。 以下のような「チャンク（chunk）」がすでにあるかと思います：

```{r}
summary(cars)
```

これらはRコードの「チャンク」（塊）で、knitrによってコードが実行され、結果に置き換えられます。 また後ほど、詳しくお伝えします。

**Knit** の中にある、二重アスタリスクとかぎ括弧（ < > ）の間に置かれているウェブアドレスが あるのが分かるでしょうか。これが、Markdownなのです。

Markdown

Markdownは、メールを書くような感覚でテキストに印をつけていきながら、htmlコードを使わずに ウェブページを書くための言語です。印がつけられた（marked-up） テキストは、マークが指し示す正しいhtmlコードに置き換えられながら、htmlに 変換 されます。

とりあえず、ここにあるものを全部消して、少しMarkdownを書いてみましょう。

二重アスタリスクを使って、 太字 に（例 **bold**）、 下線を使って、 斜体 にすることができます（例 _italics_）。

ハイフンやアスタリスクを使って、箇条書きを書くこともできます。例えば：

* 太字は、二重アスタリスクで
* 斜体は、下線で
* コードタイプのフォントは括弧で

または、このように：

- 太字は、二重アスタリスクで
- 斜体は、下線で
- コードタイプのフォントは括弧で

それぞれ、以下の形で表示されます：

• 太字は、二重アスタリスクで
• 斜体は、下線で
• コードタイプのフォントは括弧で

（私はハイフンよりもアスタリスクの方が好きですが）

数字を使って番号付きリストを作ることもできます。 同じ番号を何度でも好きなだけ使えます：

1. 太字は、二重アスタリスクで
1. 斜体は、下線で
1. コードタイプのフォントは括弧で

これは、次のように表示されます：

1. 太字は、二重アスタリスクで
2. 斜体は、下線で
3. コードタイプのフォントは括弧で

行の頭に # 印を好きな数つけることで、色々なサイズの文節の題名を作ることができます：

# タイトル
## 主文節
### 副文節
#### 更なる副文節

左上にある「Knit HTML」をクリックすることで、R Markdown文書をhtml ウェブサイトへ コンパイル する ことができます。その隣に、小さな疑問符があるのが分かると思います。その疑問符をクリックしてみると、 R MarkdownについてのRStudio文書と、「Markdown Quick Reference」（Markdownのシンタックス付き） が出てきます。

チャレンジ1

新しいR Markdown文書を作りましょう。Rコードのチャンクを全て消して、 Markdown（いくつかの文節、斜体テキスト、箇条書き） を書いてみましょう。

この文書をウェブサイトにしてみましょう。

もうちょっとMarkdownについて

次のような、ハイパーリンクを作ることができます： [表示するテキスト](http://the-web-page.com).

このようなイメージを含めることもできます：![caption](http://url/for/file)

下付き文字 （例 F~2~）は F~2 で、上付き文字（例 F^2^）は F^2^ でできます。

LaTeXの等式の書き方を知っていれば、 $ $ と $$ $$ で数式を挿入することができます。 例えば、 $E = mc^2$ や、

$$y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon$$

Rコードの「チャンク（塊）」

Markdownは役に立つし、興味深くもあるのですが、一番重要な機能は、RコードとMarkdownを組み合わせられることなのです。 それが、R Markdownです。処理すると、Rコードが実行され、図が作られ、最終的な文書に挿入されます。

メインのコードチャンクは、こんな感じです：

```{r load_data}
gapminder <- read.csv("~/Desktop/gapminder.csv")
```

つまり、Rコードを```{r chunk_name} と```の間に置くことでコードの「チャンク（chunk・塊）」を作ります。それぞれのチャンクに重複しない名前を付けておくといいでしょう。 そうすると、エラーを修正するときに役立ちますし、グラフのファイル名は、生成されたコードのチャンクの名前に基づいて付けられるからです。

チャレンジ1

以下を行うコードチャンクを加えましょう

• ggplot2 パッケージの読み込み
• gapminder データの読み込み
• プロットの作成

どうコンパイルされるか

「Knit HTML」ボタンを押すと、R Markdown文書はknitr によって処理され、単純なMarkdown文書が（一連の図のファイルと共に）生成されます。 Rコードは実行され、入力と出力に置き換えられます。図が生成された場合、 これらの図へのリンクが挿入されます。

Markdownと図の文書は、pandoc というツールで処理され、 Markdownファイルは、図の埋め込まれたhtmlファイルに変換されます。

チャンクのオプション

コードのチャンクがどう扱われるかは、様々なオプションによって決められます。

• コード自体を見せないためには、 echo=FALSE を使います
• 結果を表示しないためには、 results="hide" を使います
• コードを演算せず表示するためには、 eval=FALSE を使います
• 警告やメッセージを隠す場合は、 warning=FALSE と message=FALSE を使います
• 生成される図の大きさを（インチで）管理するためには、 fig.height と fig.width を使います

なので、書くとすれば：

```{r load_libraries, echo=FALSE, message=FALSE}
library("dplyr")
library("ggplot2")
```

使いたいオプションを別のチャンクでも使いたい場合は、 global_options を使います。例えば：

```{r global_options, echo=FALSE}
knitr::opts_chunk$set(fig.path="Figs/", message=FALSE, warning=FALSE,
                      echo=FALSE, results="hide", fig.width=11)
```

fig.path オプションは、図のファイルがどこに保存されるかを定義します。 ここでの / はとても重要で、もしこれがなければ、図は標準的な場所に 保存されますが、 Figs で始まる名前のファイルだけになります。

共有ディレクトリにR Markdownファイルが複数ある場合は、 fig.path を図のファイル名と異なる接頭語を付けるために使うといいかもしれません。 例えば、fig.path="Figs/cleaning-" と fig.path="Figs/analysis-" とすれば、 それぞれ "cleaning-" と "analysis-" で始まる図のファイルが "Figs/" ディレクトリに保存されます。

チャレンジ1

図の大きさを管理し、コードを隠すチャンクのオプションを使ってみましょう。

文中のRコード

報告書にある、全て の数を再現可能なものにすることができます。 `r と ` を文中のコードのチャンクに入れてみましょう。 例えば、 `r round(some_value, 2)`。このコードはコンパイル時に 実行され、結果の 値 に置き換えられます。

この文中のチャンクを、複数の行に分けて入れないようにしましょう。

こういう場合は、パラグラフの前にinclude=FALSE （ echo=FALSE と results="hide" の組み合わせと同じ）のオプションを設定した、 定義や演算を行うコードチャンクを作っておきましょう。

私は四捨五入に関しては、神経質になりがちです。 2.0 が欲しくても、round(2.03, 1) ではただの 2 が出てきてしまいます。

R/bromanパッケージにある、 myround関数が、 この問題に対処してくれます。

チャレンジ1

文中のRコードを少し試してみましょう。

その他の出力オプション

R MarkdownをPDFやWord文書に変換することもできます。 ドロップダウンメニューを表示させるために、「Knit HTML」の横にある小さい三角をクリックしましょう。 または、 pdf_document や word_document をファイルの最初のヘッダー（header）に入れておくこともできます。

ヒント：PDFドキュメントの作成

.pdf 文書を作成するためには、いくつかソフトウェアをインストールしなければいけないかもしれません。 これらのソフトが必要な場合は、エラーメッセージの中に詳細が述べられています。

• Windows向けのTeXインストーラー.
• macOS向けのTeXインストーラー.

資料

• Knitr in a knutshell tutorial
• Dynamic Documents with R and knitr (book)
• R Markdown documentation
• R Markdown cheat sheet
• Getting started with R Markdown
• Reproducible Reporting
• The Ecosystem of R Markdown
• Introducing Bookdown

まとめ

• R のマークダウンと R で作成されたソフトウェアが混在するレポート

• フォーマット制御のために　Specify chunk オプションを指定する。

• knitr を使用してドキュメントを PDF およびほかのフォーマットに出来る。