Sweave ユーザーマニュアル by Friedrich Leisch, R Version 2.0.0

1. はじめに

 Sweave はドキュメントの自動作成のために、テキストと R コードを混在させるための柔軟な枠組を提供する。単一のソースファイルがドキュメントと R コードの双方を含むファイルから

ドキュメントテキストと
R コード、とともに(もしくは)
コードの出力(テキスト、グラフ)

を織り込んだ最終ドキュメントを生成する。これは、入力データが変更された場合レポートを再生成し、レポートを含む同じファイルに、解析手順を再生するコードをドキュメント化する。解析の完全な R コードが noweb 構文(Ramsey, 1998)を用い、LaTeX ドキュメントに埋め込まれる。従って、LaTeX (高品位タイプセッティング)と R (データ解析) のすべての能力を同時に使用することができる。ダイナミックなレポート生成に関する一般的な考察や、他システムについては、Leisch (2002) とそこにあげられた参考文献を参照せよ。
 Sweave は実際の翻訳に異なるドライバーを使うというモジュラー型コンセプトを使う。明らかに,別々のドラ−バーは別々のマークアップ言語(LaTeX、HTML、…)が必要とされる。CRAN のいくつかのパッケージは他の文書処理システムを提供する(付録Aを参照せよ)。

2. Noweb ファイル

 Noweb (Ramsey, 1998) は,プログラムソースコードと対応する文書を一つのファイルにするまとめるための,単純な,可読性の高いプログラミングツールである。noweb ファイルは「チャンク」と呼ばれる,コードと文書のセグメントからなる。

ドキュメントチャンクは最初の文字としてサイン (@) を持ち、その後には空白か改行文字が続く。典型的には、ドキュメントチャンクはLATEX のようなマークアップ言語によるテキストを含むであろう。コードチャンクは、最初の行が <<name >>= で始まり、その行の残りはコメントであり無視される。

最初のチャンクは既定ではドキュメントである。noweb の最も単純な用法では、(オプションの)コードチャンクの名前は、ソースコードファイルの名前を与え、ツール notangle を用いて、noweb ファイルからコードチャンクを抜き出すことができる。複数のコードチャンクが同じ名前を持っても良い。対応するコードチャンクはソースコードが抜き出されるとき、連結される。noweb はコードチャンクの相互参照用の追加機構 (二重鈎括弧演算子等)を持つが、Sweave は現在この機能をサポートしていないので、ここでは解説しない。

脚注:
1 See Becker et al. (1988) and Chambers (1998) for definitions of the S language, and Venables and Ripley (2000) for details on the term S engine and detailed descriptions of differences between various implementations of the S language.
2 R システム:http://www.R-project.org
3 LATEX システム:http://www.ctan.org
4 S-PLUS システム:http://www.insightful.com

3. Sweave ファイル

3.1 簡単な例

Sweave のソースファイルは正規の noweb ファイルであり、最終的な出力への幾つかの追加の制御を許すための幾つかの追加構文を持つ。伝統的な noweb ファイルは拡張子 .nw を持つが、これはまた Sweave ファイルにも有効である( そして完全にサポートされている)。更に、 Sweave は現在、拡張子 .rnw, .Rnw, .snw そして .Snw を持つファイルを Sweave 拡張を持つ noweb ファイルとして認識する。この文章では .Snw で統一する。

Sweave ファイルの一つの最小例を図 1 に示す。これは単純な LATEX ドキュメントに埋め込まれた二つのコードチャンクを持つ。Sweave はこれを図 2,3 に示した LATEX ドキュメントに変換する。example-1.Snw と example-1.tex の最初の違いは LATEX のスタイルファイル Sweave.sty が自動的にロードされる事である。これは S 入力と出力の組版のための環境(LATEX 環境 Sinput と Soutput)を提供する。その他の点では、example-1.Snw から example-1.tex へドキュメントチャンクは一切の変更無しにコピーされる。

図 1: 最小の Sweave ファイル: example-1.Snw
(訳注:<<...>> は空白無しで行の先頭に置かないとまずいらしい)

\documentclass[a4paper]{article}
\title{Sweave Example 1}
\author{Friedrich Leisch}
\begin{document}
\maketitle
この例では \texttt{kruskal.test} のヘルプページからの実行例の一部を \LaTeX{} ドキュメントに
埋め込む:
<<>>=
data(airquality)
library(stats)
kruskal.test(Ozone ~ Month , data = airquality)
@
これはオゾンの分布の位置パラメータが月毎に有意に変化することを示している。最後にデータの箱型図を
取り込む:
\begin{center}
<<fig =TRUE, echo =FALSE>>=
boxplot(Ozone ~ Month , data = airquality)
@
\end{center}
\end{document}

Sweave の既定動作が使われ、S 命令とその対応する出力が LATEX ファイルに変換され、それぞれ Sinput, Soutput 環境に埋め込まれている。二番目のコードチャンクは noweb 構文への Sweave 拡張の一つを示している。コードチャンク名を用いて最終出力を制御するオプションを Sweave に引き渡すことが出来る。チャンクは図チャンク (fig=TRUE) とマークされ、それにより、Sweave はチャンク中の命令により作られるプロットに対応する EPS と PDF ファイルを生成する。更に、\includegraphics{example-1-002} 命令が LATEX ファイルに埋め込まれる(図のファイル名の選択に関する詳細はこのマニュアルの後の方で述べられる)。オプション echo=FALSE は S 入力を最終ドキュメントに含めない(Sinput 環境無し)事を指示する。

図 2: 命令 Sweave("example-1.Snw") の出力が以下のファイル example-1.tex である。

\documentclass[a4paper]{article}
\title{Sweave Example 1}
\author{Friedrich Leisch}
\usepackage{Sweave}
\begin{document}
\maketitle
この例では \texttt{kruskal.test} のヘルプページからの実行例の一部を \LaTeX{} ドキュメントに
埋め込む:
\begin{Schunk}
\begin{Sinput}
> data(airquality)
> library(stats)
> kruskal.test(Ozone ~ Month , data = airquality)
\end{Sinput}
\begin{Soutput}
Kruskal - Wallis rank sum test
data : Ozone by Month
Kruskal - Wallis chi - squared = 29.2666 , df = 4, p- value = 6.901e -06
\end{Soutput}
\end{Schunk}
これはオゾンの分布の位置パラメータが月毎に有意に変化することを示している。最後にデータの箱型図を
取り込む:
\begin{center}
\includegraphics{example-1-002}
\end{center}
\end{document}
example-1.png

3.2 Sweave のオプション

オプションは、コードチャンクとそれらの出力(テキスト、図)を .Snw ファイルから .tex ファイルにどのように変換するかを制御する。全てのオプションは key=value という形式を持ち、ここで value は数値、文字列、または論理値で良い。複数のオプションを(コンマで区切って)同時に指定することが出来、全てのオプションは値(コンマや等号記号を含んではならない)を持たなければならない。論理値オプションは値、true, false, t, f もしくはその大文字版をとることが出来る。.Snw ファイルでは、オプションは

1. 一つのコードチャンクの先頭におかれた矢印括弧の中(このチャンクに対してだけ有効)
2. ドキュメントチャンクの任意の場所におかれた命令 
   \SweaveOpts{opt1=value1, opt2=value2, ..., optN=valueN}
   (これは、以降のドキュメント全て、つまり、宣言以降の全てのコードチャンク、に対して有効)。

のいずれかによって、指定できる。したがって、ドキュメントの先頭部に置かれた \SweaveOpts? 文は、全てのコードチャンクに対する既定値を設定する。

どのオプションがサポートされているかは使用されるドライバに依存する。全てのドライバは少なくとも以下のオプション(それらは、もしあれば既定動作を持つ)をサポートすべきである:

engine=S:    それぞれのコードチャンクを、どの S エンジンが処理できるかを記述する文字列。可能な値は、
             例えば、S, R, S3 もしくは S4 である。各ドライバは対応可能なコードチャンクだけを処理
             し、それ以外は無視する。
split=FALSE: 論理値。もし TRUE なら、出力は複数のファイルに配分される。もし FALSE なら、
             全ての出力は一つのファイルに書き込まれる。詳細はドライバに依存する。
label:       コードチャンクに対するラベルで、split=TRUE の時、ファイル名の作成に使われる。もし
             ラベルが、label.engine という形式ならば、その拡張子は以後使われる前に取り除かれる
             (例えば、ラベル hello.S は hello に短縮される)。

コードチャンク名中の最初(そして最初だけ)のオプションは名前が無くても良く、その際は、それがラベルとされる。つまり、コードチャンクが

<<hello.S, split=FALSE>>

で始まれば、それは

<<split=FALSE, label=hello.S>>

と同じであるが、しかし

<<split=FALSE, hello.S>>

では構文エラーになる。ラベルに対する名前無しの第一引数は noweb との互換性のために必要となる。もし \SweaveOpts? だけがオプションの設定に使われれば、Sweave ファイルは noweb と完全に互換(コードチャンク名中に、ファイル名だけが登場するので)となるように書くことが出来る。

3.3 テキスト中で数値を使う

テキストチャンク中で S オブジェクトの値を使うための限られた機能がある。\Sexpr{expr} という表現は、表現式 expr を文字ベクトルに変換することにより得られる文字列で置き換えられるが、この ベクトルの最初の要素だけが使われる。例えば \Sexpr{sqrt(9)} は(引用符無しの)文字列 ’3’に置き換えられる。表現式はコードチャンクと同一の環境で評価されるので、式が登場する前に登場したコードチャンク中で定義された、全てのオブジェクトにアクセス可能である。表現式は任意の適正な S コードを含んで良く、波括弧だけが許されない。これは実際には制限にはなら無い。なぜなら、より複雑な計算は隠されたコードチャンク中で容易に済ませておくことが出来、それからその結果を \Sexpr 中に使えば良いからである。

3.4 コードチャンクの再利用

名前付きのコードチャンクは、ドキュメント中で後に現れた他のコードチャンク 中で再利用出来る。次の簡単な例

<<a>>=
x <- 10
@
<<b>>=
x + y
@
<<c>>=
<<a>>
y <- 20
<<b>>
@

を考えよう。これは、最後のコードチャンクを次のように定義するのと同値である:

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

チャンク参照演算子 <<>> は他の追加の Sweave オプション無しの、チャンク名だけを引数に取る。

3.5 構文の定義

これまでは(既定の) noweb 構文だけを使った Sweave ファイルの事だけを話してきた。しかしながら、Sweave は、テキスト中の数値の利用や、コードチャンクの再利用により、ユーザがドキュメントやコードチャンクをマーキングする構文を再定義することを許す。図 4 は SweaveSyntaxLatex? 定義を用いた図 1 の例を示す。コードチャンクは、ここではS コード環境中に含められ、S コード ref{chunkname} を用いて、コードチャンクが再利用される。他の全ての演算子は noweb スタイルの構文と同じである。ドキュメントにどの構文を使うかは、入力ファイルの拡張子で決まる。拡張子 .Rtex や .Stex を持つファイルはLATEX 風の構文を持つと仮定される。または、構文は任意の箇所で、ドキュメントチャンク中の最初の行に置かれた命令

\SweaveSyntax{SweaveSyntaxLatex}

もしくは

\SweaveSyntax{SweaveSyntaxNoweb}

で変更できる。構文定義は幾つかの Sweave 命令に対する正規表現の単純なリストである。例の最初にあげられた二つの定義を見よ。(より詳細な使い方は API が安定した後で提供されるであろう。)

4 Tangling (縺れ)と weaving (編みあげ)

Sweave システムに対するユーザフロントエンドは二つの S 関数 Stangle() と Sweave() であり、ともに R の基本パッケージ utils に含まれる (http://www.R-project.org)。Stangle は .Snw ファイルからコードチャンクだけを取り出すし、一つもしくは複数のファイルに書き出すのに使える。

Figure 4: LATEX 構文を用いた Sweave ファイル例: example-1.Stex.
\documentclass[a4paper]{article}
\title{Sweave Example 1}
\author{Friedrich Leisch }
\begin{document }
\maketitle
この例では \texttt{kruskal.test} のヘルプページ中の例の
一部を \LaTeX{} 文章に埋め込む:
\begin{Scode}
  data(airquality)
  library(ctest)
  kruskal.test(Ozone ~ Month , data = airquality)
\end{Scode}
これはオゾンの分布の位置パラメータが月毎に有意に変動する
ことを示す。次に、データのボックスプロットを含める:
\begin{center}
  \begin{Scode}{fig=TRUE , echo = FALSE}
    boxplot(Ozone ~ Month , data = airquality)
  \end{Scode}
\end{center}
\end{document}

Sweave は S エンジンを用いてコードチャンクを実行し、それらを対応する入力 and/or 出力に置き換える。Stangle は実際は Sweave に対する単なるラッパ関数であり、既定で tangling ドライバを weaving ドライバの代わりに使う。

Sweave レポートの自動作成

説明
Sweave はレポートの自動作成のためにテキストと S コードを混在させるための
柔軟な枠組を提供する。基本的なアイデアは、S コードをその出力で置き換え、
最終的な文章がテキストと統計解析結果だけを含むようにすることである。

用法
Sweave(file, driver = RweaveLatex(), syntax = getOption("SweaveSyntax"), ...)
Stangle(file, driver = Rtangle(), syntax = getOption("SweaveSyntax"), ...)

引数
file     Sweave ソースファイル名
driver   実際に使われるドライバ、以下の詳細を見よ
syntax   クラス SweaveSyntax のオブジェクトか、その名前を持つ文字列
         既定のインストールでは SweaveSyntaxNoweb と SweaveSyntaxLatex が提供される
...      ドライバの設定関数に引き渡される追加引数

詳細
(latex のような)文章作成マークアップと S コードを一体化することにより、レポートを自動
作成する。最終的なマークアップファイルでは S コードはその出力で置き換えられる。これは、
もし入力データが変わってもレポートを再生成し、レポートを生成したのと同じファイルに、行っ
た解析を再現するコードをドキュメント化する。Sweave は文章とコードチャンク(もしくはその
出力を)を一つのファイルにまとめる。Stangle は Sweave ファイルから真正の S ソースファイル
をつくり出すコードだけを取り出す(そして、それを source  関数で実行できる)。
\Sexpr{} 文中のコードは S tangle により無視される。Stangle は既定では簡単なドライバを使う
Sweave へのフロントエンドであり、文章部分を取り去り、使用中の S エンジンが理解する全ての
コードチャンクを連結する。

フック関数
各コードチャンクが評価される前に、幾つかのフック関数を実行できる。もし getOption("SweaveHooks") 
が設定されていれば、それはフック関数の集まりとされる。一つのコードチャンク (echo, print, . . . )
の各論理オプション毎に一つのフック関数を指定することができ、それは対応するオプションが TRUE 
の時、そしてその時だけ実行される。フックは  getOption("SweaveHooks") が返すリストの名前付き
成分でなければならず、引数を持たない関数でなければならない。つまり、もしオプション "SweaveHooks" 
が list(fig = foo) と定義されており、foo が関数なら、それは各図チャンク中のコードの前に実行
されるであろう。これは一連の図チャンク中の作図パラメータに対する既定値を設定するのに便利である。
ユーザは新しい Sweave オプションと、それらに関連する任意のフック関数を自由に定義できることを
注意しよう。例えば、大局的環境中の全てのオブジェクトを取り除くオプション clean に対するフック
関数を定義できる。すると clean=TRUE である全てのコードチャンクは空の作業スペースで始められる
ことになるであろう。


構文上の定義
Sweave は,ドキュメントとテキストチャンクを記述するのに非常に柔軟な構文の枠組を許す.
デフォルトはnowebスタイルの構文であるが,代わりにlatexスタイルの構文を使うこともできる.
詳しくはユーザーマニュアルを参照.

Author(s)
Friedrich Leisch
References
Friedrich Leisch: Sweave User Manual, 2002
http://www.ci.tuwien.ac.at/~leisch/Sweave
Friedrich Leisch: Dynamic generation of statistical reports using literate data analysis. In W.
Hrdle and B. Rnz, editors, Compstat 2002 - Proceedings in Computational Statistics, pages
575-580. Physika Verlag, Heidelberg, Germany, 2002. ISBN 3-7908-1517-9.

See Also
RweaveLatex, Rtangle

Examples
testfile <- system.file("Sweave", "Sweave-test-1.Rnw", package = "utils")
## create a LaTeX file
Sweave(testfile)
## create an S source file from the code chunks
Stangle(testfile)
## which can be simply sourced
source("Sweave-test-1.R")

4.1 RweaveLatex? ドライバー

このドライバーは, LaTeX ドキュメントのチャンクと R コードチャンクをもった .Snw ファイルを 適切なLaTeXファイル (通常のlatex と pdflatex でタイプセットするための)へと変換する.

 RweaveLatex R/LaTeX Driver for Sweave
 
 説明
 LaTeX ファイルの中で Rコードチャンクを変換する Sweave のためのドライバー
 
 使用法
   RweaveLatex()
   RweaveLatexSetup(file, syntax, output = NULL, quiet = FALSE,
     debug = FALSE, echo = TRUE, eval = TRUE,
     split = FALSE, stylepath = TRUE,
     pdf = TRUE, eps = TRUE)
 
 引数
   file Name of Sweave source file.
   syntax An object of class SweaveSyntax.
   output Name of output file, default is to remove extension ‘.nw’, ‘.Rnw’ or 
     ‘.Snw’
     and to add extension ‘.tex’. Any directory names in file are also removed
     such that the output is created in the current working directory.
   quiet If TRUE all progress messages are suppressed.
   debug If TRUE, input and output of all code chunks is copied to the console.
   stylepath If TRUE, a hard path to the file ‘Sweave.sty’ installed with this package is
     set, if FALSE, only \usepackage{Sweave} is written. The hard path makes
     the TeX file less portable, but avoids the problem of installing the current
     version of ‘Sweave.sty’ to some place in your TeX input path. The argument
     is ignored if a \usepackage{Sweave} is already present in the Sweave source
     file.
   echo set default for option echo, see details below.
   eval set default for option eval, see details below.
   split set default for option split, see details below.
   pdf set default for option pdf, see details below.
   eps set default for option eps, see details below.
 
 サポートされているオプション
   RweaveLatex supports the following options for code chunks (the values in parentheses show
   the default values):
 
   echo: logical (TRUE). Include S code in the output file?
   eval: logical (TRUE). If FALSE, the code chunk is not evaluated, and hence no text or graphical
     output produced.
   results: character string (verbatim). If verbatim, the output of S commands is included in
     the verbatim-like Soutput environment. If tex, the output is taken to be already proper
     latex markup and included as is. If hide then all output is completely suppressed (but
     the code executed during the weave).
   print: logical (FALSE) If TRUE, each expression in the code chunk is wrapped into a print()
     statement before evaluation, such that the values of all expressions become visible.
   term: logical (TRUE). If TRUE, visibility of values emulates an interactive R session: values of
     assignments are not printed, values of single objects are printed. If FALSE, output comes
     only from explicit print or cat statements.
   split: logical (FALSE). If TRUE, text output is written to separate files for each code chunk.
   strip.white: logical (TRUE). If TRUE, blank lines at the beginning and end of output are
     removed.
 
   prefix: logical (TRUE). If TRUE generated filenames of figures and output have a common
     prefix.
   prefix.string: a character string, default is the name of the ‘.Snw’ source file.
   include: logical (TRUE), indicating whether input statements for text output and includegraphics
     statements for figures should be auto-generated. Use include = FALSE if the
     output should appear in a different place than the code chunk (by placing the input line
     manually).
   fig: logical (FALSE), indicating whether the code chunk produces graphical output. Note that
     only one figure per code chunk can be processed this way.
   eps: logical (TRUE), indicating whether EPS figures shall be generated. Ignored if fig =
     FALSE.
   pdf: logical (TRUE), indicating whether PDF figures shall be generated. Ignored if fig =
     FALSE.
   width: numeric (6), width of figures in inch.
   height: numeric (6), height of figures in inch.
 
 Author(s)
   Friedrich Leisch
 
 References
   Friedrich Leisch: Sweave User Manual, 2002
   http://www.ci.tuwien.ac.at/~leisch/Sweave
 
 See Also
   Sweave, Rtangle

4.1.1 分離されたファイルへの書き込み

もしも,splitが真にセットされると,コードチャンクに対応するすべてのテキスト(Sinput,Soutput環境)は分離された別のファイルに書き込まれる.ファイル名は,prefix.string-label.tex の形式となる.もしも複数のコードチャンクが同じラベルをもっていると,その出力は連結される.もしもコードチャンクがラベルをもたなければ,かわりにチャンクの番号が使われる.同じ命名のスキームが図にも適用される.

4.1.2 LaTeX のスタイルファイルと図のサイズ

もしも Sweave ソースファイルに \usepackage{Sweave.sty} が見付からなければ,ドライバーは自動的に,最終的な LaTeX ファイルの \begin{document} 宣言の前の最後の行に \usepackage{.../Sweave.sty} を挿入する.このスタイルファイルは,コードチャンクのタイプセットのために Sinput,Soutput 環境を定義する.

もしも,たとえばあなたが自分で,別の場所にSinput,Soutput環境を定義しているといったようなことで標準的なスタイルファイルを使いたくないときには,LaTeXファイルのプリアンブルに% \usepackage{Sweave}といったようなコメント行を挿入するだけで,自動的に行を挿入することを抑止できる.
Sweave.sty は,既定の LaTeX の図の幅をセットする(これは生成された EPS と PDF ファイルのサイズとは独立である).

現在の既定値は,

\setkeys{Gin}{width=0.8\textwidth}

であり,図について,Sweaveが自動的に生成してインクルードするものとはちがう他の幅を使いたいときには,\begin{document}のあとに,上のものと同じ行を付け加えるだけでよい.

それぞれのフィギュアチャンク(option fig=TRUE)ごとに,新しいグラフィックデバイスがオープンされるので,par() コマンドのすべてのグラフィカルパラメータはひとつひとつのフィギュアチャンクでセットする必要があり,それぞれのチャンクのあとでは忘れ去られる(なぜならチャンクからはなれるときにはデバイスはクローズされるので).

注意:R グラフィックデバイスのパラメータ width/height はLaTeX の\includegraphics コマンドの対応する引数と混乱しやすい.

Sweave の widthとheight オプションは,R のグラフィックデバイスに渡され,したがって作成される EPS と PDF ファイルの既定サイズに影響をあたえる.

そしてそれは,ドキュメントの中の図のサイズには影響せず,既定値では常に現在のテキスト幅の80%である. 図のサイズを変更するには,\setkeys{Gin} を使用するか,Sweave のオプション include=FALSEと組み合わせて明示的に\includegraphicsコマンドを使う.

4.1.3 プロンプト記号とテキストの幅

R バージョン1.6.0 と同じように,ドライバーは入力行と継続行に使われるプロンプトを,R の options() の設定から得ている.options(prompt="MyR> ", continue="...")といったような新しいプロンプトを設定するには,詳細はhelp(options)で見ること.同じく,テキストの幅も option "width" で制御されている.

4.2 Rtangle ドライバー

このドライバーは,.SnwファイルからSとRのコードを抽出するために使うことができる.コードチャンクはひとつの大きなファイルへ書き込むことも,分離されたファイルへ書き込むこともできる(それぞれのラベルについてひとつづつ).split, prefix, prefix.string, engine のオプションは,RweaveLatex?? ドライバーと同じ既定値と動作をもつ.もしもRやSコードではないチャンクを抽出すべきときは,通常のnowebコマンドラインツールであるnotangleを使うこと.

Rtangle R Driver for Stangle

説明
  A driver for Stangle that extracts R code chunks.

使用法
  Rtangle()
  RtangleSetup(file, syntax, output = NULL, annotate = TRUE,
    split = FALSE, prefix = TRUE, quiet = FALSE)

引数
  file Name of Sweave source file.
  syntax An object of class SweaveSyntax.
  output Name of output file, default is to remove extension ‘.nw’, ‘.Rnw’ or ‘.Snw’
    and to add extension ‘.R’. Any directory names in file are also removed
    such that the output is created in the current working directory.
    annotate By default, code chunks are seperated by comment lines specifying the names
    and numbers of the code chunks. If FALSE, only the code chunks without
    any decorating comments are extracted.
  split Split output in single files per code chunk?
  prefix If split = TRUE, prefix the chunk labels by the basename of the input file
    to get output file names?
  quiet If TRUE all progress messages are suppressed.

Author(s)
  Friedrich Leisch

References
  Friedrich Leisch: Sweave User Manual, 2002
  http://www.ci.tuwien.ac.at/~leisch/Sweave

See Also
  Sweave, RweaveLatex

Acknowledgements
  The author wants to thank Vince Carey, Robert Gentleman, Kurt Hornik, Markus J¨antti, Brian
  Ripley, Anthony Rossini, and Dietrich Trenkler for providing valuable comments and ideas, testing
  development versions of the software or fixing bugs.

FAQ: しばしば聞かれる質問

A.1 どこでSweaveのマニュアルやその他の情報を入手できますか?

最新のSweaveのマニュアルはいつもSweaveホームページで見付けることができます.また,そこには使用例のファイルやFAQに関するlispやシェルの小さなコードがあります.さらに,CompStat?の論文やR Newsからミニシリーズの2編の論文(第2/3と第2/3)といったいくつかの論文もあります.

A.2 どのようにしたら Emacs に,Sweave フォーマットのファイルを自動的に認識させられますか?

あなたの .emacs ファイルに,つぎのようなコードをいれましょう.

(defun Rnw-mode ()
  (require 'ess-noweb)
  (noweb-mode)
  (if (fboundp 'R-mode)
      (setq noweb-default-code-mode 'R-mode)))
(add-to-list 'auto-mode-alist '("\\.Rnw\\'" . Rnw-mode))
(add-to-list 'auto-mode-alist '("\\.Snw\\'" . Rnw-mode))
(setq reftex-file-extensions
     '(("Snw" "Rnw" "nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
(setq TeX-file-extensions
     '("Snw" "Rnw" "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))

コマンドの最初のブロックは拡張子が .Rnwと .Snw のファイルについてemacs にnoweb モードの ESS バージョンを自動的にロードさせるものです(既定のコードモードは R モード).最後の2行は,RefTex? が noweb ファイル上で動くようにするためのものです.コードはhttp://www.ci.tuwien.ac.at/~leisch/Sweave/sweave-site.elでダウンロードできます.

A.3 Sweave をシェルから直接走らせることはできますか?

例えば,makefile を書くなどすると,手動で R を起動してから Sweave を走らせるよりはSweave をシェルから直接走らせるのに便利でしょう.数行の簡単なシェルスクリプトを使うことによって,より簡単にできます.

#!/bin/sh
echo "library(tools); Sweave(\"$1\")" | R --no-save --no-restore

A.4 なぜLaTeXはEPSとPDFファイルがファイル名にドットをふくんでいるときにファイルを見つけてくれないのですか?

Sweave は,グラフィックファイルを扱うために,標準の LaTeX パッケージである graphicx を使います.それは,もしも入力ファイルの名前が拡張子をもたなければ,つまりドットをふくまなければ,標準の LaTeX には EPS ファイルを,PDFLATEX には PDF ファイルを自動的に使います.したがって,Sweave ファイルの名前が余分なドットをふくんでいた場合,グラフィックスの取扱いの際にトラブルに見舞われることになります.~'foo.Rnw' は大丈夫だが,'foo.bar.Rnw' はダメです.

A.5 なぜ Sweave は既定値では EPS と PDF のグラフィックファイルの両方を作成するのですか?

LaTeX のパッケージ graphicx は素の LaTeX のためには EPS ファイルを必要とするが,PDFLATEX のためには PDF を必要とします(後者は PNG と JPEG ファイルも扱うことができます).Sweave は,利用者が最終的なドキュメントで必要に応じてlatex か pdflatex のいずれかを自由に走らせることができるよう,EPS と PDF フォーマットのグラフィクスを自動的に作ります.

A.6 R lattice グラフィックスがなぜ動かないのですか?

lattice パッケージでのコマンドは標準の plot コマンドとはちがうふるまいをします.lattice コマンドは "trellis" クラスのオブジェクトを返し,このクラスでの実際の図の作成は print メソッドで行われます.lattice 関数を print() 宣言の中にくるんで呼び出すことがコツです.つまり,

<<fig=TRUE>>=
  library(lattice)
  print(bwplot(1:10))
@

これでうまくいきます.Sweave の将来のバージョンでは trellis グラフィクスを取り扱うためのもっと自動化された方法が取り入れられるでしょう.

A.7 どうすれば白黒の lattice グラフィックスを使えますか?

lattice を Sweave で使うときに,分割されたパネルが透明の背景と白黒のグラフをもつように指定するもっともエレガントな方法などんなものでしょう.わたしは複数のプロットに影響をもちつづけるグローバルオプションが好きです.Deepayan Sarkar 氏の答は,初期化のどこかでこのようなことをしています.

<<...>>
  library(lattice)
  ltheme <- canonical.theme(color = FALSE) ## in-built B&W theme
  ltheme$strip.background$col <- "transparent" ## change strip bg
  lattice.options(default.theme = ltheme) ## set as default
@

A.8 ひとつのフィギュアチャンクからいくつかの図を作りたいのだが,できない

つぎのようなループの中でいくつかの図を作りたいとしましょう.

<<fig=TRUE>>
for (i in 1:4) plot(rnorm(100)+i)
@

現在のところこれはまだうまくいきません.というのは,Sweave はひとつのフィギュアチャンクあたりひとつのグラフしか通さないからです.Sweave はコードを実行する前にポストスクリプトデバイスを開いて,あとでそれを閉じるから,というのがその簡単な理由です.もしもループの中でプロットすることが必要ならば,つぎのようにプログラムするとよいでしょう.

<<results=tex,echo=FALSE>>=
for(i in 1:4){
file=paste("myfile", i, ".eps", sep="")
postscript(file=file, paper="special", width=6, height=6)
plot(rnorm(100)+i)
dev.off()
cat("\\includegraphics{", file, "}\n\n", sep="")
}
@

A.9 どうしたら自動的に生成されたグラフィクスファイルを Sweave ファイルと同じではなく別のサブディレクトリに置くことができますか?

まず,

\SweaveOpts{prefix.string=foo/bar}

という風にすると,Sweave はすべての図をfoo というサブディレクトリに置き,その名前は bar で始まります(Sweave ファイルの名前ではなく).サブディレクトリ foo は Sweave が起動される前に存在していなければなりません.

A.10 どうすればフィギュアチャンクに par() の既定値をセットできますか?

EPS も PDF ファイルも新しいデバイスを開くので,par() を使ってもその効果はそれが使われたフィギュアチャンクの中でしかありません.同じ設定をいくつもの図に使いたいときには,hook 関数を使う方が,同じ par() 宣言をそれぞれのフィギュアチャンクの中で何度も使うよりも簡単でしょう.

options(SweaveHooks=list(fig=function() par(bg="red", fg="blue")))

の効果はすぐわかるでしょう.すべての Sweave ファイルにたいして全域的なオプションとして使いたいのでなければ,Sweave ファイルの最後でフックを外すのを忘れないようにしましょう.

A.11 Windows で latex ファイルを走らせる

R の中で Sweave() を走らせることで '.tex' ファイルを作ったとしても,'.tex' ファイルを '.dvi' や '.pdf' ファイルに変換できないとしたら,それは R をインストールしたパスの場所の問題であることが多いでしょう.もしも R をインストールしたパスが空白文字をふくんでいると(Windows の英語バージョンのように既定値は "\Program Files\..."),tex や latex のようなプログラムはパスの中の空白文字を適切に取り扱うことができないので,問題を引き起こすでしょう. ふたつの解決方法があります.
1: R を,空白文字のふくまれていないパスにインストールする,
2: 'Sweave.sty' を tex のパスか Sweave ファイルをふくんでいるディレクトリにコピーし,Sweave ファイルのプリアンブルに\usepackage{Sweave} を書き込む.

A.12 どうすれば S インプットとアウトプットのチャンクのフォーマットを変えられますか?

Sweave はすべての S コードの出力のフォーマットをするためにfancyvrb パッケージを使っています.fancyvrb は verbatim 環境でのテキストのレイアウトを細かく調整できるとてもパワフルで柔軟なパッケージです.もしも既定のレイアウトを変えたければ,ただ fancyvrb のドキュメントを読んで,'Sweave.sty' のなかのSinput と Soutput 環境の定義をそれぞれ変更すればよいだけです.

A.13 どうすれば S インプットとアウトプットの1行の長さを変えられますか?

Sweave は,S における,望みの行の長さを指定する通常のやりかた,つまり option(width) を尊重します.例えば,option(width=40) のあとでは,行は最大で 40 文字であるように(可能であれば)フォーマットされます.

A.14 eval=FALSE をふくむチャンクはなぜ R CMD チェックによって実行されるのですか?

これは仕様であってバグではありません."Writing R Extensions"マニュアルによれば,inst/doc ディレクトリにふくまれる小さなパッケージは,コードとドキュメントの整合性を確かめるためにすべての R コードチャンクを実行することによってR CMD チェックによってチェックされます.eval=FALSEのオプションを持つコードチャンクがテストされても,テストされたくないコードの部分があれば,それは通常の LaTeX の verbatim 環境へ移すべきであることに注意が必要です.この考え方の理由は,コードの例が,そのコード断片が見える通りに実行可能であることを保証することが出来るようにするためです.

A.15 Sweave を HTML ファイルに使えますか?

R2HTML パッケージは,LaTeX ではなく HTML との組合せで Sweave を使えるようにするドライバーを提供します.

A.16 R2HTML パッケージをロードすると Sweave がちゃんと走りません!

R2HTML パッケージはHTML ファイルのための Sweave ドライバーを登録し,すると,サーチリストのなかで HTML の文法が既定の文法の前に入ります.

options(SweaveSyntax="SweaveSyntaxNoweb")

または,Sweave をつぎのように呼ぶことで,R2HTML をロードしたあとでも既定の文法がちゃんと使えるようになります.

Sweave(..., syntax="SweaveSyntaxNoweb")

文献

Richard A. Becker, John M. Chambers, and Allan R. Wilks. The New S Language.
  Chapman & Hall, London, UK, 1988.
John M. Chambers. Programming with data: A guide to the S language. 
  Springer Verlag, Berlin, Germany, 1998.
Friedrich Leisch. Sweave: Dynamic generation of statistical reports using 
  literate data analysis.
  In Wolfgang Hrdle and Bernd Rnz, editors, Compstat 2002 \u2014 Proceedings in 
  Computational Statistics, pages 575\u2013580. Physika Verlag, Heidelberg, 
  Germany, 2002. URL http://www.ci.tuwien.ac.at/~leisch/Sweave. 
  ISBN 3-7908-1517-9.
R Development Core Team. R: A language and environment for statistical 
  computing, 2002. URL http://www.R-project.org. version 1.6.1.
Norman Ramsey. Noweb man page. University of Virginia, USA, 1998. URL 
  http://www.cs.virginia.edu/~nr/noweb. version 2.9a.
Anthony J. Rossini, Richard M. Heiberger, Rodney Sparapani, Martin M¨achler, 
  and Kurt Hornik.
  Emacs speaks statistics: A multi-platform, multi-package development 
  environment for statistical analysis. 
  Journal of Computational and Graphical Statistics, 2003. 
  (Accepted for publication).
Richard M. Stallman. The Emacs Editor. Free Software Foundation, 
  Boston, MA, USA, 1999. URL http://www.gnu.org. version 20.7.
William N. Venables and Brian D. Ripley. S Programming. Springer, 2000.

添付ファイル: fileexample-1.png 1767件 [詳細]

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Google
WWW を検索 OKADAJP.ORG を検索
Last-modified: 2015-03-01 (日) 01:15:59 (1727d)