17.3 rmarkdown::render() で R Markdown をレンダリングする

RStudio あるいは他の IDE を使用していないなら, 次の事実を知っておくべきでしょう. R Markdown 文書は rmarkdown::render() 関数によってレンダリングされているのです. つまり, あらゆる R スクリプト内でプログラミングによって R Markdown 文書をレンダリングできることを意味します. 例えば, for ループで連続した調査レポートを州ごとにレンダリングできます.

for (state in state.name) {
  rmarkdown::render(
    'input.Rmd', output_file = paste0(state, '.html')
  )
}

出力ファイル名は州ごとに異なります. 州を state 変数にして input.Rmd 文書の中で使うこともできます. これが例です.

---
title: "`r state` に関するレポート"
output: html_document
---

`r state` の面積は `r state.area[state.name == state]` 平方マイルである.

?rmarkdown::render のヘルプを読むと他にも使える引数を知ることができます. ここではそれらのうち clean と envir 引数の2つだけを紹介しようと思います.

前者の clean は Pandoc の変換がうまくいかない時のデバッグに特に役立ちます. rmarkdown::render(..., clean = FALSE) を呼び出すと, .md ファイルを含め, .Rmd ファイルから knit された全ての中間ファイルが維持されます. Pandoc がエラーを発していたらこの .md ファイルからデバッグを始めることもできます..

後者の envir は rmarkdown::render(..., envir = new.env()) を呼び出した時に, 確実に空の新しい環境で文書をレンダリングする方法を提供してくれます. つまりコードチャンク内で作成されたオブジェクトはこの環境内にとどまり, あなたの現在のグローバル環境を汚すことがありません. 一方で, Rmd 文書を新しい R セッションでレンダリングして, いま開いている R セッションのオブジェクトがあなたの Rmd 文書を汚さないようにしたいのであれば, この例のように rmarkdown::render in xfun::Rscript_call() を呼び出せばよいでしょう.

xfun::Rscript_call(
  rmarkdown::render,
  list(input = 'my-file.Rmd', output_format = 'pdf_document')
)

この方法は RStudio で Knit ボタンをクリックする方法と似ています. これも同様に新しい R セッションで Rmd 文書をレンダリングします. Rmd 文書を他の Rmd 文書内でレンダリングする必要がある場合は, コードチャンクで直接 rmarkdown::render() を呼び出すのではなく, 代わりにこちらの方法を使うことを強く勧めます. なぜなら rmarkdown::render() は内部で多くの副産物をもたらし, さらにそれらに依存関係があることから, 同じ R セッションで他の Rmd 文書をレンダリングするのに影響を及ぼすことがあるからです.

xfun::Rscript_call() の第2引数は rmarkdown::render() に渡す引数のリストを取ります. 実は xfun::Rscript_call は汎用的な関数で, 新しい R セッションで任意の R 関数（引数はオプション）を呼び出します. 関心があるならヘルプページをご覧になってください.