R では関数の使い方がわからない時は ? または help によって、その関数のリファレンスを呼び出すことができる。この関数のリファレンスの他に、R では vignette と呼ばれるマニュアルが存在する。リファレンスは 1 つの関数について、その使い方やオプションの説明などが書かれているのに対して、vignette はパッケージ全体の説明や各関数をどのように組合せて使うべきかなどをまとめた詳細ドキュメントとなっている。

? または help 関数で呼び出される関数のリファレンスは必ず存在するに対して、vignette は存在しない場合もある。vignette が存在する場合は、以下のように呼び出すことができる。

library(TCC)
vignette("TCC")

パッケージの中に vignette を付ける場合、「package-dir/inst/doc/package-name.Rnw」に .Rnw ファイルを置く。このファイルを記述するための記法は TeX と似ている。以下に、いくつかの例を示す。

レイアウト

vignette を作成するにあたって、以下の様なレイアウトを利用する。例えば、TCC パッケージの vignette を作る場合は、以下のようにする。

%\VignetteIndexEntry{TCC}
%\VignettePackage{TCC}

\documentclass[a4paper]{article}

\title{Analysis for ...}
\author{Authors, ...}

\begin{document}

\maketitle

\section{Introduction}

The is the vignette sample of TCC package.
The figure can insert with following commands.

To plot the histgram, run the 'hist' function.

<<fig = FALSE>>=
x <- rnorm(1000)
hist(x)
@

The histgram can be made as:

\begin{center}
<<fig = TRUE>>=
hist(x)
@
\end{center}

\end{document}

vignette 中のコードを実行

vignette の内容において、<<>>= と @ の間に R のコードを書くと、vignette を作成するときに実行される。plot 関数などを用いた場合、画像の出力も制御できる。

<<echo = false, result = hide>>=
x <- 20
@

実行されるが非表示のコードの書き方

次のように echo、result オプションを利用することで、そのブロック内に書かれるコードは実行されるが、vignette の方には表示されない方法。

<<echo = false, result = hide>>=
set.seed(100)
@

実行結果を表示させないコードの書き方

ブロック内に書かれるコードを実行させるが、その実行結果を vignette に表示させない方法。

<<result = hide>>=
rnorm(100)
@

実行されないコードの書き方

eval = FLASE を指定することで、ブロックに書かれるコードが実行されなくなる。

<<eval = FALSE>>=
plot(x, y)
@

画像を作成するコードの書き方

vignette にグラフ画像を載せたい場合、描画関数を一度実行させ、その結果を該当位置に挿入することでできる。

With following command,

<<fig = FALSE>>=
plot(x, y)
@

we can plot the scatter plot of x and y.

\begin{center}
\begin{figure}
<<fig = TRUE, echo = FALSE, eps = TRUE>>=
plot(x, y)
@
\end{figure}
\end{center}

実行結果の利用

\Sexpr{ } を利用することで、変数の中身を展開させることができる。

<<>>=
x <- 10
y <- 20
z <- x + y
@

Such as the previous calculation,
$x + y$ equals to \Sexpr{z}.