はじめに

シリーズ 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マークダウンファイルに対して、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パッケージのインストール

rmarkdownの特徴

などなどです。

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_documentpdf_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"))

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

入力フォーマット

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

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

出力フォーマット

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

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: ltjarticlelatex_engine: lualatexを指定しています。

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

Windowsで日本語

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

更新履歴

さいごに

Enjoy!!



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