3.3 R スクリプトをレポートにレンダリングする

長らく RMarkdown を使っていても, 別の選択肢があることを見落としていることがあります. Dean Attali はこれを“knitr の秘宝と読んでいます. 純粋な R スクリプトを直接レンダリングできるということです. RStudio IDE をお使いなら, R スクリプトをレンダリングするキーボードショートカットは Rmd 文書を knit するときと同じ (Ctrl / Cmd + Shift + K) です.

R スクリプトをレポートにレンダリングすると, まず knitr::spin() 関数が呼ばれスクリプトが Rmd ファイルに変換されます. この関数こそ Dean Attali が「knitrの秘宝」と呼んでいるものです. レポートには全てのテキストとグラフィックの出力が掲載されます.

レポートの要素を細かく管理したいなら, 以下のような構文が役に立ちます.

  • Roxygen コメントはテキストとして扱われます. roxygen コメントは #' で始まる R のコメントで, レポートにナラティブを書くのに役立ちます. コメント内ではあらゆる Markdown 構文を使うことができます.

  • #+ で始まるコメントは knitr のチャンクヘッダとして扱われます. 例えば, knitr::spin() は #+ label, fig.width=5 というコメントを, R Markdown の ```{r label, fig.width=5} というチャンクヘッダへ翻訳します.

  • {{ code }} で囲まれた R コードは R Markdown のインライン R コードへ翻訳されます. {{ code }} は1行で書かなければならないことに注意してください.

  • YAML フロントマターも, R スクリプトの冒頭の roxigen コメント内に書くことができます. YAML フィールドのインデントには, 特に気をつけてください. これはとても大事なところです. YAML のインデントを省くとYAMLに記述したデータ構造は別の正しくないものになります. 例えば keep_tex: true というフィールドは, 後の例のように pdf_document 以下に2つ以上のスペースでインデントするべきです.

  • /* と */ の間の任意のテキストは無視されます (つまり, 完全にコメントとして扱われます)

上記のルールの全ての例を表現したのが以下です.

#' ---
#' title: "純粋な R script から生成したレポート"
#' output:
#'   pdf_document:
#'     keep_tex: true
#' ---
#'
#' これは `knitr::spin()` によって生成されたレポートです.
#'
#' **knitr** オプションをいくつか試してみましょう:

#+ echo=FALSE, fig.width=7
#  これは通常の R コメント文です.
plot(cars)

#' ここにインラインの値を書きましょう. $\pi$ の値は
{{ pi }}
#' であると知られています.
#'
#' 最後に, 全ての roxygen コメントは任意だということを書いておきます.
#' プロットの大きさなど出力要素をコントロールしようと思わない限り
#' チャンクオプションも必要でありません

# /* C 言語のコメントのように /* と */ の間にコメントを書きましょう:
Sys.sleep(60)
# */

このスクリプトがレポートにレンダリングされた時, knitr::spin() はこれを R Markdown へと変換します.

---
title: "純粋な R script から生成したレポート"
output:
  pdf_document:
    keep_tex: true
---

これは `knitr::spin()` によって生成されたレポートです.

**knitr** オプションをいくつか試してみましょう:

```{r echo=FALSE, fig.width=7}
#  これは通常の R コメント文です.
plot(cars)
```

ここにインラインの値を書きましょう. $\pi$ の値は
``r  pi  ``
であると知られています.

最後に, 全ての roxygen コメントは任意だということを書いておきます.
プロットの大きさなど出力要素をコントロールしようと思わない限り
チャンクオプションも必要でありません

このレポート生成方法は, 主に R スクリプトを使って作業していて多くのナラティブを必要としないときに, 特に役立つでしょう. レポートの中でテキストの割合が高いなら, 全てのテキストを roxygen コメントに入れなくてもいい R Markdown がより良い選択でしょう.