R パッケージ | R Markdown：データレポート生成の利器

R パッケージ | R Markdown：データレポート生成の強力なツール#

R Markdown は knitr と Pandoc の肩の上に立っており、前者は文書内に埋め込まれたコンピュータコードを実行し、R Markdown を Markdown に変換します；後者は Markdown を希望する出力形式（PDF、HTML、Word など）で表示します。

R Markdown

この記事は謝益輝の新書《R Markdown: The Definitive Guide》の最初の三章を翻訳したもので、内容は一部省略されています。主に R Markdown の関連構造と文法規則について紹介しています。より詳細な内容を知りたい方は原書を読むことをお勧めします。

インストール#

ここでは、すでに R (https://www.r-project.org) と RStudio IDE (https://www.rstudio.com) がインストールされていると仮定します。RStudio は必須ではありませんが、インストールすることで R Markdown をより簡単に使用できます。RStudio IDE をインストールしていない場合は、Pandoc（ http://pandoc.org ）をインストールする必要がありますが、RStudio をインストールすると Pandoc がバンドルされているため、別途インストールする必要はありません。次に、R で rmarkdown パッケージをインストールできます：

# CRAN からインストール
install.packages('rmarkdown')

# または、開発版をテストしたい場合は、
# GitHub からインストール
if (!requireNamespace("devtools"))
  install.packages('devtools')
devtools::install_github('rstudio/rmarkdown')

PDF タイプの文書出力を生成したい場合は、LaTeX をインストールする必要があります。以前に LaTeX をインストールしたことがない R Markdown ユーザーには、TinyTeX（https://yihui./tinytex/）のインストールをお勧めします：

install.packages("tinytex")
tinytex::install_tinytex()  # TinyTeX をインストール

TinyTeX は軽量でクロスプラットフォーム、メンテナンスが容易な LaTeX です。LaTeX または R Markdown 文書を PDF にコンパイルする際に、tinytex は必要な関連 R パッケージを自動的にインストールするのを助け、すべての交差参照の問題を解決するために LaTeX 文書が正しい回数コンパイルされることを保証します。これらの 2 つのことが何を意味するのかわからない場合は、TinyTeX をインストールすることをお勧めします。これらの詳細は、あなたが時間と労力を費やす価値がないことが多いからです。

rmarkdown パッケージ、RStudio/Pandoc、LaTeX を使用すれば、ほとんどの R Markdown 文書をコンパイルできるはずです。場合によっては、他のパッケージが必要になることがありますが、必要に応じてそれらについて言及します。

参考文献

R Core Team. 2018. R: A Language and Environment for Statistical Computing. ウィーン、オーストリア: R Foundation for Statistical Computing. https://www.R-project.org/.

Xie, Yihui. 2018f. Tinytex: Helper Functions to Install and Maintain Tex Live, and Compile Latex Documents. https://github.com/yihui/tinytex.

基礎知識#

R Markdown はデータサイエンスのための創作フレームワークを提供します。R Markdown は以下の 2 つのタスクをこなすことができます：

コードを保存し実行する；
共有可能な高品質のレポートを生成する。

R Markdown の設計目的は、報告内容の再現性をより容易に実現することです。これは、計算コードと叙述が同じ文書内にあり、結果がソースコードから自動的に生成されるためです。また、R Markdown は数十種類の静的および動的 / インタラクティブな出力形式をサポートしています。

動画で学ぶことを好む方には、https://rmarkdown.rstudio.com のウェブサイトをチェックし、「Get Started」で R Markdown の基礎知識を含む動画を視聴することをお勧めします。

文書構造#

以下は非常に簡単な R Markdown 文書で、.Rmd 拡張子を持つプレーンテキスト文書です。

---
title: "Hello R Markdown"
author: "Awesome Me"
date: "2018-02-14"
output: html_document
---

This is a paragraph in an R Markdown document.

Below is a code chunk:

```{r}
fit = lm(dist ~ speed, data = cars)
b   = coef(fit)
plot(cars)
abline(fit)
```

The slope of the regression is `r b[1]`.

```

```

任意のテキストエディタ（RStudio を含むがこれに限定されない）を使用して、このようなテキスト文書を作成できます。RStudio を使用する場合は、File -> New File -> R Markdown から新しい Rmd 文書を作成できます。

R Markdown 文書は、メタデータ、テキスト、コードの 3 つの基本的な構成要素を持っています。メタデータは 3 つのハイフン --- の間の内容です。メタデータの構文は YAML（ YAML はマークアップ言語ではない）であるため、時には YAML メタデータまたは YAML フロントマターとも呼ばれます。注意すべき点は、YAML ではインデントが非常に重要であり、これを無視すると大きな代償を払うことになります。YAML 構文の簡単な例については、謝益輝の著書『bookdown』（2016 年）の付録 b.2 を参照してください。

文書の本文はメタデータの書き方のルールに従います。テキストの構文は Markdown であり、第 2.5 節で紹介されます。計算コードには 2 種類あり、第 2.6 節で詳しく説明されています：

コードブロック：3 つのバックティックと使用する言語で始まり、r は使用するプログラミング言語を示し、3 つのバックティックで終了します。ブロックオプション（例：図の高さを 5 インチに設定する：{r, fig.height=5}）を中括弧内に記入できます。
インラインコード： `code` で始まり、単一のバックティックで終了します。

文書コンパイル#

最も簡単な方法は、RStudio で Knit ボタンをクリックすることです。対応するショートカットキーは Ctrl + Shift + K （macOS では Cmd + Shift + K）です。もちろん、直接コード rmarkdown::render を実行してレンダリングコンパイルすることもできます。例えば：

rmarkdown::render('foo.Rmd', 'pdf_document')

複数の文書をコンパイルする場合、関数を使用する方が便利です。なぜなら、ループを使用して直接レンダリングコンパイルできるからです。

参考カード#

RStudio は大量の参考カードを作成しており、これらは https://www.rstudio.com/resources/cheatsheets/ で無料で入手できます。

出力形式#

出力形式には 2 種類あります：文書とプレゼンテーション。利用可能なすべての形式は以下の通りです：

beamer_presentation
github_document
html_document
ioslides_presentation
latex_document
md_document
odt_document
pdf_document
powerpoint_presentation
rtf_document
slidy_presentation
word_document

第 3 章と第 4 章では、これらの出力形式について詳しく説明します。他の拡張パッケージでは、さらに多くの出力形式が提供されています（第 5 章から）。Rmd ファイルの YAML メタデータ内の出力形式名が拡張パッケージからのものである場合、パッケージ名を含める必要があります（rmarkdown パッケージからの形式の場合、rmarkdown:: プレフィックスは不要です）。例えば：

output: tufte::tufte_html

各出力形式には通常、複数の形式オプションがあります。これらのオプションはすべて R パッケージのヘルプページに記録されています。例えば、R で ?rmarkdown:: と入力すると html_document 形式に関するヘルプページが開きます。特定のオプションを使用したい場合は、これらの値を R から YAML に変換する必要があります。例えば：

html_document(toc = TRUE, toc_depth = 2, dev = 'svg')

YAML では次のように書くことができます：

output:
  html_document:
    toc: true
    toc_depth: 2
    dev: "svg"

YAML の文字列は通常、引用符を必要としません（``dev：“svg”とdevは同じです）、特別な文字（コロン： など）が含まれている場合を除きます。文字列を引用すべきかどうか不明な場合は、yaml` パッケージを使用してテストできます。例えば：

cat(yaml::as.yaml(list(
  title = 'A Wonderful Day',
  subtitle = 'hygge: a quality of coziness'
)))

## title: A Wonderful Day
## subtitle: 'hygge: a quality of coziness'

上記の例では、サブタイトルはコロンのためにシングルクォートで引用されています。

あるオプションにサブオプションがある場合（これはそのオプションの値が R のリストであることを意味します）、サブオプションはさらにインデントする必要があります。例えば：

output:
  html_document:
    toc: true
    includes:
      in_header: header.html
      before_body: before.html

いくつかのオプションは knitr に渡されます。例えば、dev、fig_width、fig_height などです。これらのオプションの詳細なドキュメントは knitr ドキュメントページで見つけることができます。実際の knitr オプション名は異なる場合があります。特に、knitr は名前に . を使用しますが、rmarkdown は _ を使用します。例えば、rmarkdown では fig_width は knitr では fig.width に対応します。

いくつかのオプションは Pandoc に渡されます。例えば、toc、toc_depth、number_sections などです。疑問がある場合は、Pandoc ドキュメントを参照するべきです。R Markdown 出力形式関数には通常、pandoc_args パラメータがあり、これは Pandoc に渡されるパラメータの文字ベクトルであるべきです。出力形式パラメータで表されていない Pandoc の機能がある場合は、この最終的な引数を使用できます。例えば：

output:
  pdf_document:
    toc: true
    pandoc_args: ["--wrap=none", "--top-level-division=chapter"]

Markdown 構文#

インライン形式#

イタリック ：_text_ または *text*
太字：**text**
下付き文字：H~3~PO~4~ は $H_3PO_4$ にレンダリングされます。
上付き文字：Cu^2+^ は $Cu^{2+}$ にレンダリングされます。
脚注： ^[This is a footnote.]
インラインコード：`code` , n+1 個のバックティックを使用して n 個のバックティックを含むコードブロックを出力できます。
ハイパーリンク：[text](link)
画像リンク： ![alt text or image title](path/to/image)

引用：

@Manual{R-base,
  title = {R: A Language and Environment for Statistical
    Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2017},
  url = {https://www.R-project.org/},
}

ブロックレベル要素#

タイトル
```
# First-level header

## Second-level header

### Third-level header
```
特定のタイトルを番号付けしたくない場合は、タイトルの後に {-} または {.unnumbered} を追加できます。例えば：
```
# Preface {-}
```

無秩序リスト

- one item
- one item
- one item
  - one more item
  - one more item
  - one more item

秩序リスト

1. the first item
2. the second item
3. the third item
  - one unordered item
  - one unordered item

引用

> "I thoroughly disapprove of duels. If a man should challenge me,
  I would take him kindly and forgivingly by the hand and lead him
  to a quiet place and kill him."
>
>                                                 --- Mark Twain

"I thoroughly disapprove of duels. If a man should challenge me,
I would take him kindly and forgivingly by the hand and lead him
to a quiet place and kill him."

--- Mark Twain

コードブロック

```
This text is displayed verbatim / preformatted
```

Or indent by four spaces:

    This text is displayed verbatim / preformatted

数学表現#

$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$ : $f(k) = {n \choose k} p^{k} (1-p)^{n-k}$

$$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$$ :

f(k) = {n \choose k} p^{k} (1-p)^{n-k}

コードブロックオプション#

Insert ボタンをクリックするか、ショートカットキー Ctrl + Alt + I （macOS：Cmd + Option + I）を使用します。

https://yihui.name/knitr/options には多くのコードブロックオプションがあり、ここでは一般的なものをいくつか紹介します：

eval=TRUE ：現在のコードブロックを実行します；

```{r}
# 指定された日以降の日付の場合にコードを実行
do_it = Sys.Date() > '2018-02-14'
```

```{r, eval=do_it}
x = rnorm(100)
```

echo=TRUE ：ソースコードを出力します；
result ：'hide' に設定すると、テキスト出力が隠されます；'asis' に設定すると、テキスト出力が「そのまま」書かれます。
collapse=TRUE ：テキスト出力とソースコードを 1 つのコードブロック出力に統合し、よりコンパクトにします；
warning, message, error ：出力文書に警告、メッセージ、エラーを表示するかどうか；
include=FALSE ：現在のコードを実行し、ソースコードと出力結果を表示しません；
cache ：キャッシュを有効にするかどうか。キャッシュが有効になっている場合、次回文書をコンパイルする際に同じコードブロックは評価されません（コードブロックが変更されていない場合）、これにより時間を節約できます；
fig.width、fig.height ：（グラフィックデバイス）ブロックのサイズ（インチ）。注意：fig.dim = c(6, 4) は fig.width = 6 および fig.height = 4 を意味します；
out.width、 out.height ：出力文書内の R 画像の出力サイズ。パーセンテージを使用できます。例えば、out.width = '80%' はページ幅の 80% を示します；
fig.align ：画像の配置方法；
dev ：グラフィックデバイスが R 画像を保存する形式。例：'pdf', 'png', 'svg', 'jpeg'；
fig.cap ：画像のキャプション；
child ：主文書に子文書を含めることができます。このオプションは外部ファイルへのパスを選択します。

特定のオプションが複数のコードブロックで頻繁に設定される必要がある場合は、文書の最初のコードブロックでグローバルに設定することを検討できます：

```{r, setup, include=FALSE}
knitr::opts_chunk$set(fig.width = 8, collapse = TRUE)
```

画像#

ローカル画像もコードブロックオプションを使用して調整できます。例えば：

```{r, out.width='25%', fig.align='center', fig.cap='...'}
knitr::include_graphics('images/hex-rmarkdown.png')
```

R コードによって生成されていないグラフィックを淡入させたい場合は、knitr::include_graphics() 関数を使用すると、![alt text or image title](path/to/image) のような Markdown 構文よりも画像の属性をよりよく制御できます。

表#

knitr::kable() 関数を使用すると、簡単に表を作成できます。表のタイトルは caption で設定できます。例えば：

```{r tables-mtcars}
knitr::kable(iris[1:5, ], caption = 'A caption')
```

より高度な表スタイルの制御を探している場合は、kableExtra パッケージを使用することをお勧めします。これは PDF および HTML 表の外観をカスタマイズする機能を提供します。第 12.3 節では、bookdown パッケージが rmarkdown の機能を拡張し、テキスト内で数字や表を簡単に相互参照できる方法を説明しています。

参考文献

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. ボカラトン、フロリダ：チャプマン；ホール / CRC. https://yihui.name/knitr/.

出力文書#

HTML 文書#

HTML 文書を出力するには、まず YAML メタデータに output: html_document と書きます：

---
title: Habits
author: John Doe
date: March 22, 2005
output: html_document
---

目次（Table of contents）#

---
title: "Habits"
output:
  html_document:
    toc: true
    toc_depth: 2
    toc_float:
      collapsed: false
      smooth_scroll: false
---

toc: true ：目次を出力します；
toc_depth ：出力されるタイトルの最小レベル；
toc_float: true ：目次が内容の左側に浮かび、常に表示されます；
collapsed （デフォルトは TRUE）：初期状態ではトップレベルのタイトルのみが表示され、内容がスクロールすると目次が段階的に展開されます；
smooth_scroll （デフォルトは TRUE）：目次のタイトルをクリックすると指定された内容にナビゲートします。

セクション番号付け (Section numbering)#

---
title: "Habits"
output:
  html_document:
    toc: true
    number_sections: true
---

注意：文書に 1 階層のタイトルがない場合、2 階層のタイトルは 0.1, 0.2 … と命名されます。

タブ付きセクション (Tabbed sections)#

## Quarterly Results {.tabset .tabset-fade .tabset-pills}

### By Product

(tab content)

### By Region

(tab content)

Tabbed sections

.tabset ：主タイトルのすべての子タイトルが .tabset 属性と共にタブに表示され、独立した部分として表示されません；
.tabset-fade ：タブの切り替え時に淡入淡出します；
.tabset-pills ：タブの外観を変更し、「薬丸」のようにします。

外観とスタイル#

---
title: "Habits"
output:
  html_document:
    theme: united
    highlight: tango
---

theme ：テーマは Bootswatch テーマライブラリから取得され、利用可能なテーマには default, cerulean, journal, flatly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, および yeti が含まれます。
highlight ：コードハイライトモード。サポートされているスタイルには default, tango, pygments, kate, monochrome, espresso, zenburn, haddock および textmate が含まれます。

画像オプション#

---
title: "Habits"
output:
  html_document:
    fig_width: 7
    fig_height: 6
    fig_caption: true
---

fig_width と fig_height ：画像の幅と高さ；
fig_caption ：画像にキャプションを含めるかどうか；
dev ：画像のレンダリング形式、デフォルトは png です。

表の印刷#

デフォルトの表出力形式は：

Option	Description
default	Call the `print.data.frame` generic method
kable	Use the `knitr::kable` function
tibble	Use the `tibble::print.tbl_df` function
paged	Use `rmarkdown::print.paged_df` to create a pageable table

paged 形式に設定すると出力形式は：

---
title: "Motor Trend Car Road Tests"
output:
  html_document:
    df_print: paged
---
``` {r, rows.print=5}
mtcars
```

mtcars

TABLE 3.2: ページ付き HTML テーブルのオプション。

Option	Description
max.print	印刷する行の数。
max.print	印刷する行の数。
cols.print	表示する列の数。
cols.min.print	表示する最小列数。
pages.print	ページナビゲーションの下で表示するページ数。
pages.print	ページナビゲーションの下で表示するページ数。
rownames.print	`FALSE` に設定すると行名をオフにします。

コード折りたたみ#

---
title: "Habits"
output:
  html_document:
    code_folding: hide
---

code_folding: hide ：初期状態ではコードを表示せず、視聴者がクリックして表示できます；
code_folding: show ：初期状態でコードを表示し、視聴者がクリックして非表示にできます；

高度なカスタマイズ#

Markdown ファイルの保持#

R Markdown ファイル（*.Rmd）を実行すると、Markdown ファイル（*.md）が作成され、そのファイルが Pandoc によって HTML ファイルに変換されます。Markdown ファイルを保持したい場合は、keep_md オプションを使用します：

---
title: "Habits"
output:
  html_document:
    keep_md: true
---

ローカル HTML 文書の追加#

追加の HTML コンテンツを追加するか、コア Pandoc テンプレートを完全に置き換えることで、より高度な出力カスタマイズを行うことができます。文書のヘッダーや本文の前後にコンテンツを含めるには、次のオプションを使用します：

---
title: "Habits"
output:
  html_document:
    includes:
      in_header: header.html
      before_body: doc_prefix.html
      after_body: doc_suffix.html
---

カスタムテンプレート#

---
title: "Habits"
output:
  html_document:
    template: quarterly_report.html
---

テンプレートに関するその他の詳細については、Pandoc テンプレートのドキュメントを参照してください。また、デフォルトの HTML テンプレート default.html5 を調査することもできます。

他のタイプの文書形式の制御方法は類似しており、詳細については原作を参照してください。