17.4 パラメータ化されたレポート

17.3節では for ループ内で一連のレポートをレンダリングする方法を1つ紹介しました. 実際には rmarkdown::render() はこのタスクのために設計された params という名前の引数を持っています. この引数を通じてレポートをパラメータ化することができます. レポート用のパラメータを指定した時は, レポート内でparams 変数が使えます. 例えば, 以下を呼び出したとします.

for (state in state.name) {
  rmarkdown::render('input.Rmd', params = list(state = state))
}

それから input.Rmd 内部では, オブジェクト params が state 変数を持つリストになります.

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

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

レポートに対してパラメータを指定する別の方法として, YAML フィールドで params を使うという手もあります. 例えばこのように.

---
title: パラメータ化されたレポート
output: html_document
params:
  state: ネブラスカ州
  year: 2019
  midwest: true
---

YAML の params フィールドまたは rmarkdown::render() の params 引数には, いくつでもパラメータを含められることに注目してください. YAML のフィールドと rmarkdown::render() の引数とが両方あるときには, render() の引数の値が対応する YAML フィールドの値を上書きしてしまいます. 例えば先ほどの params フィールドを使った例で rmarkdown::render(..., params = list(state = 'アイオワ州', year = 2018) を呼び出した場合は, R Markdown 文書上の params$state は ネブラスカ州 の代わりに アイオワ州 に, params$year は 2019 の代わりに 2018 になります.

同じ R Markdown 文書を一連のレポート群へとレンダリングする時は, 各レポートのファイル名が一意になるように rmarkdown::render() の output_file 引数を調整する必要があります. そうでないと, うっかりレポートファイルを上書きしてしまいます. 例えば, 各州の各年ごとにレポートを生成できる関数を書きます.

render_one <- function(state, year) {
  # input.Rmd の出力フォーマットが PDF と仮定
  rmarkdown::render(
    'input.Rmd',
    output_file = paste0(state, '-', year, '.pdf'),
    params = list(state = state, year = year),
    envir = parent.frame()
  )
}

そして for ループをネストして全てのレポートを生成します.

for (state in state.name) {
  for (year in 2000:2020) {
    render_one(state, year)
  }
}

最終的に, アラバマ州-2000.pdf, アラバマ州-2001.pdf, …, ワイオミング州-2019.pdf, and ワイオミング州-2020.pdf のように一連のレポートを得られます.

パラメータ化されたレポートであれば, Shiny で作成されたグラフィカルユーザーインターフェイス (GUI) を通して対話的にパラメータを入力することも可能です. これは YAML に params フィールドを与えることが必要ですが, 各パラメータに対応する適切な入力ウィジェットを用いた GUI を rmarkdown が自動的に作成してくれます. 例えばチェックボックスはブーリアン型のパラメータに対して用意されます.

RStudio を使用していないなら, rmarkdown::render() 呼び出して params = 'ask' を渡せば GUI を開始できます.

rmarkdown::render("input.Rmd", params = "ask")

RStudio を使用しているなら, メニューの Knit ボタンの中にある Knit with Parameters をクリックすることが可能です. 図17.1はパラメータに対する GUI の例を示しています.

図 17.1: GUI から入力できるパラメータで R Markdown を knit する

パラメータ化されたレポートの詳細については, R Markdown Definitive Guide (Xie, Allaire, and Grolemund 2018) の Chapter 15 を読むとよいでしょう.

参考文献

Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.