はじめに
サンプル
rmarkdownパッケージのインストール
rmarkdownの特徴
rmarkdownの使い方
YAMLによるメタデータ指定
render()の解説
rmarkdown用のRマークダウンの書き方
rmarkdown用のRスクリプトの書き方
Windowsで日本語
更新履歴
さいごに

はじめに

シリーズ Useful R 9 「ドキュメント・プレゼンテーション生成」では、 knitrパッケージを使ってRマークダウンファイルをマークダウンファイルやHTMLファイルに変換する方法を解説しています。

2014年以降、RStudio開発チームはrmarkdownという新しいマークダウン処理用のパッケージ開発を進めています。かなりガチで進めています。ここではrmarkdownパッケージの特徴や使い方を解説します。

rmarkdownパッケージではrender()という関数でドキュメントを生成します。ですが、大雑把に言うとrender()はknitr::knit()でRマークダウンからマークダウンに変換して、Pandocを使ってマークダウンをHTMLやPDFなどに変換します。ですので、実際にできることは、ピュアknitrとそう変わりはありません。

なおknitrパッケージのknit2html()はknitr::knit()でRマークダウンからマークダウンに変換して、markdown::markdownToHTML()でHTMLに変換しています。マークダウンから他のフォーマットへの変換にはPandocを利用することもできます。詳細は解説ページを参考にして下さい。

ついでに付け加えておくと、rmarkdown::render()は内部でknitr::knit()を呼び出しているので「ドキュメント・プレゼンテーション生成」の3章で解説したknitrパッケージのチャンクオプションやフックなどはそのまま利用することができます。ですので、knitrユーザは簡単にrmarkdownに移行することができます。

サンプル

とりあえずサンプルです。

Rマークダウンファイル

このRマークダウンファイルに対して、render()します。なお、PDFで必要なプリアンブルです。

library(rmarkdown)
render("rm-sample.Rmd", "html_document") # HTMLレポート
render("rm-sample.Rmd", "pdf_document") # PDFレポート
render("rm-sample.Rmd", "word_document") # MS Wordレポート
render("rm-sample.Rmd", "revealjs_presentation", "rm-sample-reveal.html") # revealjs ウェブスライド
render("rm-sample.Rmd", "ioslides_presentation", "rm-sample-io2012.html") # io2012 ウェブスライド
render("rm-sample.Rmd", "beamer_presentation", "rm-sample-beamer.pdf") # beamer スライド

出力結果を置いておきます。

ここでは一つの、そして唯一のRマークダウンファイルから全てのフォーマットを生成してるので、デザインとかはあまり気にしてません。例えばセクションヘッダはレベル2(## ...)にしてますが(ウェブスライドのため)、PDFの場合はレベル1(# ...)の方が良いでしょう。通常はいずれかのフォーマットを選択すると思いますので、そのフォーマットに合わせて下さい。

それと、BeamerとPDFレポートの両方に出力するため、YAMLフロントマターのdocumentclassの指定をややこしい方法で行っています。 PDFレポートだけならトップレベルにdocumentclass: ltjarticleで大丈夫です。

rmarkdownパッケージのインストール

RStudio Preview Releaseをインストールするとついてきます。Pandocもついてきます。
パッケージのみをインストールするには、
```
install.packages("devtools")
devtools::install_github("rstudio/rmarkdown")
```
とします。Pandocのインストールも必要です。

rmarkdownの特徴

マークダウンファイルを(Pandocの力で)様々なフォーマットに変換できます。
- 現在のところ、公式にはHTML, PDF, MS Word, Beamer, ioslides, reveal.jsに変換できます。
表や文献情報をサポートする拡張マークダウン記法
フックによるHTMLやPDF出力のカスタマイズ
- CSSやヘッダ、フッタなどを指定できます。
PDF出力用にマークダウンの中にLaTeXを入れちゃうことができます。
RスクリプトからもHTML、PDF、MS Wordなどのフォーマットのドキュメントを生成できます(ﾒﾁｬｸﾁｬﾍﾞﾝﾘﾀﾞﾖｰ)。
拡張性があります。独自のテンプレートを利用したり、新しい出力フォーマットを定義したりできちゃいます。
Rマークダウンの中にShinyを入れちゃうことができます。

などなどです。

rmarkdownの使い方

Rマークダウンファイル(.Rmd)またはRスクリプトファイル(.R)を用意して、

library(rmarkdown)
render("path-to.Rmd")

以上。

RStudioの場合、エディタパネルの上に[Knit HTML]というボタンがあるので、これをクリックします。以上。

YAMLによるメタデータ指定

rmarkdownの特徴として、Rマークダウンファイルの中でYAML(ヤムル)によりドキュメント生成のためのメタデータを仕込めることが挙げられます。以下の様な感じです。

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
  pdf_document:
    toc: true
    highlight: zenburn  
---

YAMLでは、インデントが超重要です。そう、パイソンみたいにね。

上の例では、タイトルと出力フォーマットを指定しています。

出力フォーマットはhtml_documentとpdf_documentの2種類指定していて、それぞれのフォーマット用に更にオプションが指定されています。例えばtoc: trueは目次を自動的に生成する、ということです。

タイトルや著者(author)などは、出力フォーマットによって使われたり使われなかったりします。例えばPDF出力の時の\maketitleに使われたりします。ココらへんは、まあ適当に試してみてください。

render()の解説

render()の定義を見てみます。

render(input, output_format = NULL, output_file = NULL, output_dir = NULL, output_options = NULL,
  intermediates_dir = NULL,    runtime = c("auto", "static", "shiny"), clean = TRUE, envir = parent.frame(),
  quiet = FALSE, encoding = getOption("encoding"))

とりあえず重要なのは、inputとoutput_formatです。

入力フォーマット

inputには処理するマークダウンファイル(.md)、Rマークダウンファイル(.Rmd)またはRスクリプト(.R)のファイル名を与えます。

マークダウンが与えられた場合にはknit()による処理は行われず、単純にPandocにより出力フォーマットに変換されます。
- .md - (Pandoc) - HTML/PDF/etc.
Rマークダウンが与えられた場合には、knit()によりRコードチャンクが評価されて、マークダウンに変換されて、Pandocにより出力フォーマットに変換されます。
- .Rmd - (knitr::knit()) - .md - (Pandoc) - HTML/PDF/etc.
Rスクリプトの場合には、最初にspin()でRからRmdへ変換されます。その後にknit()による処理とPandocによる変換が行われます。
- .R - (knitr::spin()) - .Rmd - (knitr::knit()) - .md - (Pandoc) - HTML/PDF/etc.

入力ファイルのフォーマット問わず、とりあえずrender()すれば上手くやってくれるということです。

出力フォーマット

output_formatでは出力フォーマットを指定します。

"all"を指定すると、入力ファイルのYAMLで定義されたフォーマット(output:の中の項目)が全て出力されます。
フォーマット名を文字列(例えば"html_document"など。ベクトル指定可)で指定すると、入力ファイルのYAML中の該当するフォーマット(output:の中の項目)が出力されます。
フォーマットオブジェクト(例えばhtml_document())で指定すると、そのフォーマットが出力されます。
NULLの場合は、入力ファイルのYAML中の最初のフォーマットが出力されます。入力ファイルの中で指定がなければHTMLが出力されます。

rmarkdownの組み込み出力フォーマット

rmarkdownパッケージでは出力フォーマットを独自に作成することもできてしまうんですが、ここでは既定の組み込みフォーマットを紹介します。通常はこれで事足りるでしょう。

フォーマット	説明
html_document	みんな大好きHTML出力です。
pdf_document	LaTeXer大好きPDF出力です。
beamer_presentation	LaTeXer大好きBeamerです。
revealjs_presentation	revealjsというウェブスライドに出力します。
ioslides_presentation	GoogleのI/O 2014スライドというウェブスライドに出力します。
md_document	色々な種類の拡張マークダウンへの出力を行います。
word_document	なんと!!MS Word出力です(.docx)。

例えばhtml_document(toc = TRUE, theme = "journal")などとしてフォーマットオブジェクトを作成してrender()関数に渡します。

render("path-to.Rmd", html_document(toc = TRUE, theme = "journal"))

という感じです。有効なオプションはそれぞれ?html_document、?pdf_documentなどとして確認して下さい。

なお、以下のようにRマークダウンのYAMLフロントマターで出力フォーマットやそのオプションを指定することもできます。

---
output:
  html_document:
    toc: true
    theme: journal
---

render()の引数

render()の引数のリストです。

引数名	意味
input	入力ファイル名(説明済み)
output_format	出力フォーマット(説明済み)
output_options	出力オプションをリストで指定します。YAMLメタデータのオプションを上書きします。この引数ではYAMLでの指定を上書きしますが、`output_format`引数で渡された出力フォーマットオブジェクトのオプションは変更しません。
output_file	出力ファイル名。`NULL`なら入力ファイル名ベースで自動的につけられます。
output_dir	出力フォルダ。`NULL`なら入力ファイルのフォルダに出力ファイルが作成されます。
intermediates_dir	中間ファイルのフォルダ。
runtime	出力ファイルの再生環境。`static`は通常の状況。`shiny`はShiny用にレンダリングを行います。既定値(`auto`)ならYAMLで指定された再生環境になります。指定がなければ`static`です。
clean	`TRUE`なら中間ファイルを削除します。
envir	`knit()`でコードを評価する環境。
quiet	`TRUE`ならPandocコマンドを表示しません。
encoding	入力ファイルのエンコード。

rmarkdown用のRマークダウンの書き方

YAMLフロントマターの件以外は、従来のknitrの場合と同じです。「ドキュメント・プレゼンテーション生成」を参考にして下さい(#ｽﾃﾏ)。

rmarkdown用のRスクリプトの書き方

rmarkdownパッケージではRスクリプト(.R)からドキュメントを生成できます。 rmarkdown的には「ノートブック」と呼んでいますが、これがメチャクチャ便利なんですよ。特に軽量の分析レポートには最適です。

従来のknitrではspin()で同じ処理が可能でした(「ドキュメント・プレゼンテーション生成」2章)。 rmarkdownでも内部的にはspin()でRスクリプトからRマークダウンに変換する前処理を入れているだけなので、やってることは一緒です。

Rスクリプトの書き方は以下を参考にして下さい。 #'で始まる行はRマークダウンファイルでのテキスト行に読み替えられます。 #+で始まる行はRマークダウンファイルでのチャンクヘッダに読み替えられます。

#' ---
#' title: "Sample Document"
#' documentclass: ltjarticle
#' output:
#'   html_document:
#'     toc: true
#'     theme: united
#'   pdf_document:
#'     toc: true
#'     highlight: zenburn
#'     latex_engine: lualatex
#' ---

#' # carsのプロット
#'
#' carsをプロットします。

#+ echo = FALSE
# 通常のコメントはコメントとして解釈されます。
plot(cars)

#' # インラインコードの書き方です。
#' carsのサイズは
{{dim(cars)}}
#' です。

これをrender()に食わせます。

render("path-to.R", "all")

これで、HTMLレポートとPDFレポートが作成されます。なお日本語混じりのレポートのためYAMLフロントマターでdocumentclass: ltjarticleとlatex_engine: lualatexを指定しています。

RStuidoではRスクリプト編集中に[Compile Notebook]というアイコンをクリックするとHTML形式のノートブックが作成されます。

Windowsで日本語

これから試します。試した人は情報下さい。

更新履歴

2014/6/4 サンプルを追加。
2014/6/4 word_document()を忘れていたので追加。
2014/6/3 作成しました。

さいごに

Enjoy!!

コンタクトは takahashi.kohske@gmail.com またはTwitter @kohskeまで。本業はこちら。

rmarkdownパッケージで楽々ドキュメント生成