16.7 R パッケージのビネット
R パッケージの開発を経験したか, プロジェクトで自作関数の明瞭なドキュメントや厳格なテストが要求されたなら, プロジェクトを R パッケージと結びつけてみてはどうでしょうか. R パッケージの作り方が分からないなら, RStudio IDE でメニューバーの File -> New Project をクリックし, プロジェクトの種類に R パッケージを選ぶことで簡単に始めることができます.
プロジェクトの管理に R パッケージを使うことには多くの利益があります. 例えば data/ フォルダにデータを置き, R/ に R コードを書き, 例えば roxygen2 パッケージ (Wickham, Danenberg, et al. 2021) を使用して, ドキュメントを man/ に生成し, test/ には単体テストを追加できます. R Markdown のレポートなら vignette/ にパッケージのビネットとして書くことができます. ビネット内ではデータセットを読み込みパッケージ内の関数を呼び出せます. (R CMD build コマンドか RStudio で) パッケージをビルドする時に, ビネットは自動でコンパイルされます.
R Markdown でパッケージのビネットを作成するのに最も簡単な方法は, RStudio のメニュー File -> New File -> R Markdown -> From Templateを経由するものです (図16.4参照). それから rmarkdown パッケージから “Package Vignette” を選択すると, ビネットのテンプレートが得られます. テンプレートの, タイトル・著者・その他のメタデータを変更したら, レポートの本文を書き始めましょう.
図 16.4: RStudio でパッケージのビネットを作成する
他の方法としては, usethis (Wickham, Bryan, and Barrett 2021) をインストールし usethis::use_vignette() 関数を使ってビネットのスケルトンを作成できます. 以下はパッケージのビネットの YAML フロントマターの典型的な姿です.
---
title: "ビネットのタイトル"
author: "ビネットの著者"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{ビネットのタイトル}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---title フィールドと \VignetteIndexEntry{} コマンドの両方で, ビネットのタイトルを変更しなければならないことに注意してください. 上記のビネット情報の他にも, パッケージの DESCRIPTION ファイルにさらに2つすべきことがあります.
DESCRIPTIONファイルにVignetteBuilder: knitrを指定する.DESCRIPTIONファイルにSuggests: knitr, rmarkdownを追加する.
ビネット出力フォーマットは HTML でなくてもかまいません. PDF でも可能なので, output: pdf_document も使えます. 他の出力フォーマットでも beamer_presentation や tufte::tufte_html のような, HTML か PDF を作成するものであればどれも大丈夫です. ただし, 現時点では R は HTML と PDF のビネットのみを認識します.