1 オプション
チャンクオプションとパッケージオプションについて
オリジナルのページ: https://yihui.org/knitr/options/
オリジナルの更新日: 2020-06-30
このドキュメントでは knitr 全般の機能を紹介しており, Rnw や Rhtml の仕様についても言及しています. R Markdown でも knitr の機能は使われますが, R Markdown 独自の中間処理によって, 最終的な出力がここで説明されているものと異なる可能性がある点に注意してお読みください.
knitr パッケージはソースコード, テキスト, グラフ, チャンクで使用するプログラミング言語といった, コードチャンクのコンポネントのほとんど全部をカスタマイズするための多くのオプションを提供します. knit 処理のカスタマイズをパッケージレベルでカスタマイズするオプションもあります. この章では knitr で使用できる全てのチャンクオプションとパッケージオプションを解説します. 以下のリスト中で, オプションのデフォルト値になっているものはカッコ内に表記しています.
1.1 チャンクオプション一覧
チャンクオプションはチャンクのヘッダに書きます. チャンクヘッダの構文は文書フォーマットがなんであるかに依存します. 例えば .Rnw ファイル (R + LaTeX) であれば, << >>= という記号の中に書きます. .Rmd ならば, チャンクヘッダは ```{r} 内に書きます. 以下の例は主に .Rmd (R Markdown) の場合ですが, ほとんどのチャンクオプションはどのフォーマットでも使用可能です.
チャンクオプションは以下のように タグ名=値 という形式で書きます.
```{r, my-chunk, echo=FALSE, fig.height=4, dev='jpeg'}
```チャンクラベルは特殊なチャンクオプションです (例: 先ほどの例の my-chunk がそれにあたります). これは唯一のタグが不要なチャンクオプションです (つまり, 値のみ書くことになります). もし タグ名=値 の形式で書きたいのならば, チャンクオプション名の label を明示的に使うこともできます.
```{r label="my-chunk"}
```各チャンクのラベルは文書内において一意であることが前提です. 特にキャッシュとグラフのファイル名はチャンクラベルで紐付けているため重要です. ラベルのないチャンクは unnamed-chunk-i という形式でラベル名が割り当てられます. i は順に整数が割り当てられます.
文書全体のチャンクオプションのデフォルト値を変更するために knitr::opts_chunk$set() を使うことができます. 例えば以下のようなチャンクを文書の冒頭に書きます.
```{r, setup, include=FALSE}
knitr::opts_chunk$set(
comment = '', fig.width = 6, fig.height = 6
)
```チャンクオプションの豆知識をいくつか掲載します.
- チャンクヘッダは1行で書かねばなりません. 改行してはいけません.
- チャンクラベルとファイルパスにスペース, ピリオド
., アンダースコア_を使用するのは避けましょう. セパレータが必要ならば, ハイフン-の使用を推奨します. 例えばsetup-optionsはラベル名として望ましいですがsetup.optionsやchunk 1は良くありません.fig.path = 'figures/mcmc-'はパス名として良いですが,fig.path = 'markov chain/monte carlo'は良くありません. - 全てのオプションの値は R の構文として適切でなければなりません. チャンクオプションを関数の引数のように考えると良いでしょう.
- 例えば character 型をとるオプションは引用符で囲まなければなりません. 例:
results = 'asis'やout.width = '\\textwidth'. ただしリテラルのバックスラッシュは二重のバックスラッシュが必要なことを忘れないでください. - 理論上はチャンクラベルもまた引用符で囲む必要がありますが, 利便性のため書かなくとも自動で引用符が追加されます (例:
```{r, 2a}```は```{r, label='2a'}```として扱われます). - R のコードとして有効なものである限り, いくらでも複雑な構文を書くことができます.
コードチャンクの本文に #| の後に続けてチャンクオプションを書くという, 代替的な構文も使用できます.
```{r}
#| my-chunk, echo = FALSE, fig.width = 10,
#| fig.cap = "This is a long long
#| long long caption."
plot(cars)
```この構文では, チャンクオプションはチャンク本文の冒頭で, 連続した行で書く必要があります. つまり, 全てのオプションは, 行頭の特殊なコメント記号 #| から書き始める必要があります. チャンクオプションとコードの間を1行開けるかどうかは任意です. この記法はオプションの改行が許容されます. 好きなだけ改行してオプションを書くことができます. 同じオプションが本文とチャンクヘッダ (```{} の内側) の両方で指定された場合, 前者が後者を上書きします. あるいは, チャンク内では <タグ>: <値> のような YAML 式の記法でオプションを書くこともできます. 通常は, この記法では1行に1つづつオプションを書かねばなりません. 以下がその例です.
```{r}
#| echo: false
#| fig.width: 10
```YAML 記法を選択した場合, 生の R の式ではなく YAML の値として有効なものを書かねばなりません.
以下では オプション: (デフォルト値; 値の型) という形式で, knitr で使えるチャンクオプションのリストを掲載します.
1.1.1 コード評価関連
eval(TRUE;logicalまたはnumeric): コードチャンクを評価するかどうか. どの R の評価式を評価するかを選ぶためにnumericのベクトルを使用することもできます. 例:eval=c(1, 3, 4)ならば1つ目, 3つ目, そして4つ目の評価式を評価し,eval = -(4:5)は 4, 5つ目の式以外の全てを評価します.
1.1.2 テキストの出力関連
echo(TRUE;logicalまたはnumeric): 出力される文書にソースコードを表示するかどうか. 「表示」「隠す」に対応するTRUE/FALSEに加え, どの R の評価式を表示するかを選ぶためにnumericのベクトルを使用することもできます. 例:echo=2:3は 2, 3番めの評価式を表示し,echo = -4は4番目だけを非表示にします.results('markup';character): 実行結果のテキストの部分をどう表示するかを制御します. このオプションは通常のテキスト出力にのみ影響することに注意してください (警告・メッセージ・エラーは適用範囲外です). 取りうる値は次のとおりです.markup: 出力の文書フォーマットに応じて適切な環境でテキスト出力をマークアップします. 例えば R Markdown ならば"[1] 1 2 3"が knitr によって以下のように加工されます. この場合,results='markup'は囲み (```) 付きのコードブロックとして出力されることを意味します.
``` [1] 1 2 3 ```asis: テキスト出力を「そのまま」書き出します. つまり, 生の結果テキストをマークアップ一切なしでそのまま文書に書き出します.
```{r, results='asis'} cat("I'm raw **Markdown** content.\n") ```holdチャンクと flush の全てのテキスト出力をチャンクの末尾に固定します.hide(TRUEまたはFALSE): テキスト出力を表示しません.
collapse(FALSE;logical): 可能であれば, ソースと出力をつなげて1つのブロックにするかどうかです (デフォルトではソースと出力はそれぞれ独立したブロックです). このオプションは Markdown 文書でのみ有効です.warning(TRUE;logical):warning()で出力される警告文を保存するかどうかです.FALSEの場合, 全ての警告文は文書に出力されず, 代わりにコンソールに出力されます. 警告文の一部を選ぶインデックスとして,numeric型のベクトルを指定することもできます. このインデックスは何番目も警告文を表示するかどうかを意味していることに注意してください. 例えば3はこのチャンクから投げられた3番目の警告文を意味するものであって,「何番目の R コードの警告文の出力を許可するか」ではないことに注意してください.error(TRUE;logical):stop()で出力されるエラー文を保持するかどうかです. デフォルトのTRUEでは, コード評価はエラーが出ても停止しません! エラー時点で停止させたい場合はこのオプションをFALSEに指定してください. R Markdown ではこのデフォルト値はFALSEに変更されていることに注意してください. チャンクオプションにinclude=FALSEがある場合, 起こりうるエラーを見落とさないように, knitr はエラー時点で停止するようになります. これらの注意書きを理解した上で, 起こりうるエラーをなおも無視したい場合は,errorにevaluate::evaluate()で定義されている数値を指定してください.0ならば, ターミナル上にコードをペーストしたときのように, エラーが起こった後も評価されます.1ならば, エラーが発生した時点で評価を停止しますが, 正常終了扱いとなります. よって, エラーに対処するには theerrorフック を使用します.2ならば, エラーは通常の信号を発します. つまり, Rの実行が中止されます.
message(TRUE;logical):message()が出力するメッセージ文を (warningオプションと同様に) 表示するかどうかです.include(TRUE;logical): 出力する文書にチャンクの出力を含めるかどうかです.FALSEならばなにも書き出されませんが, コードの評価はなされ, チャンク内にプロット命令があるのならグラフのファイルも生成されます. よってこの図をそれ以降で任意に挿入することもできます.tab.cap(NULL;character): コードチャンク内のkable()関数に対してキャプションを与えます. このオプションを動作させるには, チャンク内で1度だけkable()を呼び出す必要があります.strip.white(TRUE;logical): 出力時にソースコードの冒頭と末尾から空白行を除去するかどうかです.class.output(NULL;character): テキストの出力ブロックに追加するクラス名のベクトル. このオプションは R Markdown で HTML を出力する際にのみ機能します. 例えばclass.output = c('foo', 'bar')はテキスト出力が<pre class="foo bar"></pre>で囲まれたブロックとして書き出されます.class.message/class.warning/class.error(NULL;character):class.outputと同様に, R Markdown においてそれぞれ メッセージ文, 警告文, エラー文のブロックに対してクラス名を与えます.class.sourceもまた同様にソースコードのブロックに対して適用されます. “コードの装飾” のセクションを参照してください.attr.output/attr.message/attr.warning/attr.error(NULL;character): 上記のclass.*オプション群と同様に, Pandoc に対してコードブロックの属性を指定します. つまりclass.*はattr.*の特殊ケースです. 例:class.source = 'numberLines'はattr.source = '.numberLines'と等価ですが,attr.sourceは任意の値を取ることができます. 例えば,attr.source = c('.numberLines', 'startFrom="11"').render(knitr::knit_print;function(x, options, ...)): チャンクで表示される値に対して適用する関数です. 関数の第1引数には (x) はチャンクの各評価式が評価された結果が与えられます. このチャンクのチャンクオプションがリストとして第二引数opstionsに与えられます. この関数は文字列を返すことを想定しています. 詳細は package vignette (vignette('knit_print', package = 'knitr')) を参照してください.split(FALSE;logical): 出力ブロックを分割したファイルに書き出すかどうか. LaTeX ならば\input{}で読み込み, HTML ならば<iframe></iframe>タグで読み込まれます. このオプションは.Rnw,.Rtexそして.Rhtmlでのみ機能します.
1.1.3 コードの装飾関連
tidy(FALSE): R コードを整形するかどうかです. 他の有効な値は次のとおりです.TRUE(tidy = 'formatR'と等価です): 整形のためにformatR::tidy_source()を呼び出します.'styler': コード整形のためにstyler::style_text()を呼び出します.- 整形されたコードを返す,
function(code, ...) {}という形式の任意の関数. - 整形が失敗した場合, 元の R コードは変更されません (警告は表示されます).
tidy.opts: (NULL;list)tidyオプションで指定した関数へのオプション引数のリストです. 例えばtidy.opts = list(blank = FALSE, width.cutoff = 60)はtidy = 'formatR'に対して空白行を削除し各行が60文字におさまるように改行しようとします.prompt(FALSE;logical): R コードにプロンプト記号 (>など) を付けるかどうかです.?base::optionsヘルプページのpromptとcontinueを参照してください. プロンプト記号の追加は, 読者がコードをコピーするのを難しくさせるため,prompt=FALSEのほうが良い選択であることに留意してください. エンジンがR以外の場合, このオプションはうまく機能しないことがあります (issue #1274).comment('##';character): テキスト出力の各行の先頭文字です. デフォルトでは, コメントアウトできるよう##となっているので, 読者は文書から任意の範囲をそのままコピーしても出力部分は無視されるのでそのまま実行することができます.comment = ''を指定することで, デフォルトの##は除去されます.highlight(TRUE;logical): ソースコードをシンタックスハイライトするかどうかです2.class.source(NULL;character): 出力された文書のソースコードブロックのクラス名です. 出力ブロックに対して機能するclass.outputをはじめとするclass.*シリーズと同様です.attr.source(NULL;character): ソースコードブロックの属性です.attr.outputなどのattr.*シリーズと同様です.lang(NULL;character): コードチャンクの言語名です. デフォルトでは言語名はエンジン名と同じです. 例:r. このオプションは主に Markdown ベースの文書出力でシンタックスハイライトするためのものです.
size('normalsize';character):.Rnw使用時のチャンクサイズのフォントサイズです. 指定可能なサイズは overleaf のヘルプページ (英語) を参照してください3.background('#F7F7F7';character):.Rnw使用時のチャンクブロックの背景色です4.indent(character): チャンクの出力で各行に追加する文字です. 典型的には空白と同義です. このオプションは読み込み専用を想定しており, 値は knitr が文書を読み込む際に設定されます. 例えば以下のチャンクでは,indentは空白文字2個です5.```{r indent-example, echo=2} set.seed(42) rnorm(10) ```キャッシュ関連
cache(FALSE;logical): コードチャンクのキャッシュを取るかどうかです. 初回の実行またはキャッシュが存在しない場合は通常通り実行され, 結果がデータセットが保存され (.rdb,.rdxファイルなど), それ以降でコードチャンクが評価されることがあれば, 以前保存されたこれらのファイルからこのチャンクの結果を読み出します. ファイル名がチャンクラベルと R コードの MD5 ハッシュ値で一致する必要があることに注意してください. つまりチャンクになんらかの変更がある度に異なる MD5 ハッシュ値が生成されるため, キャッシュはその度に無効になります. 詳細は キャッシュの解説 を参考にしてください.cache.path('cache/';character): 生成したキャッシュファイルの保存場所を指定します. R Markdown ではデフォルトでは入力ファイルの名前に基づきます. 例えばINPUT.RmdのFOOというラベルのチャンクのキャッシュはINPUT_cache/FOO_*.*というファイルパスに保存されます.cache.vars(NULL;character): キャッシュデータベースに保存される変数名のベクトルを指定します. デフォルトではチャンクで作られた全ての変数が識別され保存されますが, 変数名の自動検出はロバストではないかもしれませんし, 保存したい変数を選別したい場合もあるかもしれないので, 保存したい変数を手動選択することもできます.cache.globals(NULL;character): このチャンクで作成されない変数の名前のベクトルを指定します. このオプションは主にautodep = TRUEオプションをより正確に動作させたいときに使います. チャンクBで使われているグローバル変数が チャンクAのローカル変数として使われているときなど. グローバル変数の自動検出に失敗した際に使う場合, こにオプションを使って手動でグローバル変数の名前を指定してください (具体例として issue #1403 を参照してください). さらに,cache.globals = FALSEは, 変数がグローバルかローカルかにかかわらず, コードチャンク内のすべての変数を検出することを意味します.cache.lazy(TRUE; logical): 遅延読み込みlazyLoad()を使うか, 直接load()でオブジェクトを読み込むかを指定します. 非常に大きなオブジェクトに対しては, 遅延読み込みは機能しないかもしれません. よってこの場合はcache.lazy = FALSEが望ましいかもしれません (issue #572 を参照してください).cache.comments(NULL;logical):FALSEの場合, R コードチャンク内のコメントを書き換えてもキャッシュが無効になりません.cache.rebuild(FALSE;logical):TRUEの場合, キャッシュが有効であってもチャンクのコードの再評価を行います. このオプションはキャッシュの無効化の条件を指定したいときに有用です. 例えばcache.rebuild = !file.exists("some-file")とすればsome-fileが存在しないときにチャンクが評価されキャッシュが再構成されます (issue #238 を参照).dependson(NULL;characterまたはnumeric): このチャンクが依存しているチャンクのラベル名を文字ベクトルで指定します. このオプションはキャッシュされたチャンクでのみ適用されます. キャッシュされたチャンク内のオブジェクトは, 他のキャッシュされたチャンクに依存しているかもしれず, 他のチャンクの変更に合わせてこのチャンクも更新する必要があるかもしれません.dependsonにnumericベクトルを与えた場合, それはチャンクラベルのインデックスを意味します. 例えばdependson = 1ならばこの文書の1番目のチャンクに依存することを意味し,dependson = c(-1, -2)は直前の2つのチャンクを意味します (負のインデックスは現在のチャンクからの相対的な位置を表します).opts_chunk$set()によってグローバルにチャンクオプションを設定した場合, このオプションは機能しません. ローカルなチャンクオプションとして設定しなければなりません.
autodep(FALSE;logical): グローバル変数を検出することでチャンク間の依存関係を分析するかどうかを指定します (あまり信頼できません). よって,dependsonを明示的に指定する必要はありません.
1.1.4 グラフ関連
fig.path('figure/';character): 図の保存ファイルパスを生成する際の接尾語.fig.pathとチャンクラベルを連結したものがフルパスになります.figure/prefix-のようにディレクトリ名が含まれて, それが存在しない場合はディレクトリが作成されます.fig.keep('high';character): グラフをどのように保存するかです. 可能な値は次のとおりです.high: 高水準プロットのみ保存 (低水準の変更は全て高水準プロットに統合されます).none: 全て破棄します.all: 全てのプロットを保存します (低水準プロットでの変更は新しいグラフとして保存されます).first: 最初のプロットのみ保存します.last: 最後のプロットのみ保存します.- 数値ベクトルを指定した場合, その値は保存する低水準プロットのインデックスとなります.
低水準プロットとは
lines()やpoints()などの関数によるグラフ描画のことです.fig.keepについてより理解するには次のようなチャンクを考えてください. 通常はこれで2つのグラフを出力します (fig.keep = 'high'を指定したので).fig.keep = 'none'としたなら, いかなるグラフも保存されません.fig.keep = 'all'ならば, 4 つのグラフとして保存されます.fig.keep = 'first'ならばplot(1)によって作成されたグラフが保存されます.fig.keep = 'last', なら, 最後の10本の垂線を描画したグラフが保存されます.
fig.show('asis';character): グラフをどのように表示し, 配置するかです. 可能な値は次のとおりです.asis: グラフが生成された場所にそのまま出力します (R ターミナルで実行した場合とおなじように).hold: 全てのグラフをまとめてチャンクの最後に出力します.animate: チャンクに複数のグラフがある場合, 連結して1つのアニメーションにします.hide: グラフをファイルに保存しますが, 出力時は隠します.
dev(LaTeX の場合は'pdf'6, HTML/Markdown の場合は'png';character): グラフをファイルに保存する際のグラフィックデバイスです. base R および,Cairo,cairoDevice,svglite,ragg, tikzDevice パッケージの提供するデバイスに対応しています. たとえば,pdf,png,svg,jpeg,tiff,cairo_pdf,CairoJPEG,CairoPNG,Cairo_pdf,Cairo_png,svglite,gridSVG,ragg_png,tikz, などが使用できます. 有効なデバイスの一覧はnames(knitr:::auto_exts)を参照してください. また,function(filename, width, height)という引数を定義した関数名を文字列で与えることでも指定できます. 画像サイズの単位は 常にインチです. ビットマップであってもインチで指定したものがピクセルに変換されます.
チャンクオプション dev, fig.ext, fig.width, fig.height, dpi はベクトルを与えることが可能で, 1つのプロットに対して複数のファイル形式で保存できます. 例えば dev = c('pdf', 'png') は1つのグラフに対して 1つづつ PDF と PNG ファイルを作成します. ベクトルの長さが足りない場合は再利用されます. ファイルが同じ拡張子で作成された場合は, fig.ext でファイルの接尾辞を変更して指定してください. そうでない場合は, 新しく生成されたファイルで上書きされます. 例えば, dev = 'png' と fig.width = c(10, 6) と指定したときに, さらに fig.ext = c('1.png', '2.png') を指定すると, 幅の異なる2つのファイルをそれぞれ異なる名前で保存できます.
dev.args(NULL;list): グラフィックデバイスに与える追加の引数です. 例えばdev.args = list(bg = 'yellow', pointsize = 10)をdev = 'png'に与えられます. 特定のデバイスに依存するオプション (詳細はそれぞれのデバイスのドキュメントを確認してくだささい).devに複数のデバイスが指定されている場合はdev.argsを引数のリストをさらにリストでくくることになるでしょう. それぞれの引数リストが対応するデバイスに与えられます. 例:dev = c('pdf', 'tiff'), dev.args = list(pdf = list(colormodel = 'cmyk', useDingats = TRUE), tiff = list(compression = 'lzw')).fig.ext(NULL;character): 出力するグラフのファイル拡張子です.NULLならばグラフィックデバイスに応じて自動決定されます. 詳細はknitr:::auto_extsを確認してください.dpi(72;numeric). ビットマップデバイスに対する DPI (インチ毎ドット,dpi * inches = pixels) です.fig.width,fig.height(いずれも7;numeric): グラフの幅と高さです. 単位はインチです. グラフィックデバイスに与えられます.fig.asp(NULL;numeric): グラフのアスペクト比, つまり 高さ/幅 の比です.fig.aspが指定された場合, 高さ (fig.height) はfig.width * fig.aspによって自動設定されます.fig.dim(NULL;numeric):fig.widthとfig.heightを指定する長さ2の数値のベクトルです. 例:fig.dim = c(5, 7)はfig.width = 5, fig.height = 7の省略形です.fig.aspとfig.dimが指定された場合,fig.aspは無視されます (警告文が出力されます).out.width,out.height(NULL;character): 出力時の画像の幅と高さです. 実体としての幅と高さであるfig.widthとfig.heightとは異なります. つまりグラフは文書に表示される際にスケールが調整されます. 出力フォーマットに応じて, これら2つのオプションはそれぞれ特殊な値を取ることができます. 例えば LaTeX ならば.8\\linewidth,3in,8cmなどと指定でき, HTML ならば300pxと指定できます..Rnwならばout.widthのデフォルト値は\\maxwidthに変更され, その値は framed のページ で書いたように定義されます. 例えば'40%'のようにパーセンテージで指定もでき, これは LaTeX では0.4\linewidthに置き換えられます.out.extra(NULL;character): 図の表示に関するその他のオプションです. LaTeX で出力する場合は\includegraphics[]に挿入される任意の文字に対応し (例:out.extra = 'angle=90'ならば図の90度回転), HTML なら<img />に挿入されます (例:out.extra = 'style="border:5px solid orange;"').fig.retina(1;numeric): このオプションは HTML で出力する際にのみ適用されます. Retina ディスプレイ に対して画像サイズを調整する比率 (多くの場合は2を指定します) です. チャンクオプションのdpiをdpi * fig.retinaで,out.widthをfig.width * dpi / fig.retinaで計算します. 例えばfig.retina = 2なら, 画像の物理サイズが2倍となり, その表示サイズは半分になります.resize.width,resize.height(NULL;character): LaTeX で出力する際に\resizebox{}{}コマンドで使われます. これら2つのオプションは Tikz グラフィックスをリサイズしたい場合のみ必要になります. それ以外に通常使うことはありません. しかし tikzDevice の開発者によれば, 他の箇所のテキストとの一貫性のため, Tikz グラフィックスはリサイズを想定していません. 値の1つでもNULLならば,!が使用されます (この意味がわからない方は graphicx のドキュメントを読んでください).fig.align('default';character): 出力時の画像の位置揃え (アラインメント) です. 可能な値はdefault,left,right,centerです.defaultは位置について特に何も調整しません.fig.link(NULL;character) 画像に与えるリンク.fig.env('figure';character): 画像に使われる LaTeX 環境. 例えばfig.env = 'marginfigure'ならば\begin{marginfigure}で囲まれます. このオプションの使用はfig.capが指定されいることが条件です.fig.cap(NULL;character): 図のキャプションです.fig.alt(NULL;character) HTML 出力時の図の<img>タグのalt属性に使う代替テキストです. デフォルトでは, 代替テキストが与えられた場合チャンクオプションfig.capには代替テキストが使われます.fig.scap(NULL;character): 図の短縮キャプションです. 出力が LaTeX の場合のみ意味をなします. 短縮キャプションは\caption[]コマンドに挿入され, 大抵の場合は PDF 出力時の「図一覧」で表示される見出しとして使われます.fig.lp('fig:';character).; 図の相互参照に使われるラベル7の接頭語で,\label{}コマンドに挿入されます. 実際のラベルはこの接頭語とチャンクラベルを連結して作られます. 例えば図のラベルが```{r, foo-plot}ならば, デフォルトでは図のラベルはfig:foo-plotになります.\label{}への挿入は, LaTeXとしてレンダリングされるチャンクに依存することに注意してください. 詳細はこの issue を見てください. 8fig.id(NULL; logical):TRUEを指定すると, コードチャンクから生成された画像に, 自動生成されたIDが割り当てられます. つまり, HTML出力の場合は, 画像が<img id="..." />と書かれます. デフォルトでは, IDはfig.lpの値・チャンクラベル ・fig.curの値を連結したものになります. ラテン文字以外の全ての文字は, ダッシュに置き換えられます. 例えば,'fig:hello world 1'は'fig-hello-world-1'になります. IDを生成する関数を定義して与えることも可能です. この関数は, 現在のチャンクのオプションをリスト型の引数として受け取り, 1要素のcharacter型を返すようにしてください. 例えばこのように書きます.fig.id = function(options) { paste0('img-', options$label, options$fig.cur) }.fig.pos('';character): LaTeX の\begin{figure}[]に使われる, 画像の位置調整オプション9を指定します.fig.subcap(NULL): subfigures のためのキャプションです. 複数のグラフが1つのチャンクにあり, かつfig.subcapもfig.capisNULLである場合,\subfloat{}が個別の画像の表示に使われます (この場合はプリアンブルに\usepackage{subfig}と書く必要があります). 具体例は 067-graphics-options.Rnw を参照してください.fig.ncol(NULL;integer). subfigure の数です. 例えばこの issue を見てください (fig.ncolもfig.sepも LaTeX でのみ機能します).fig.sep(NULL;character): subfigures どうしの間に挿入されるセパレータを指定する文字ベクトルです.fig.ncolが指定された場合, デフォルトではfig.sepに N 個ごとに\newlineが挿入されます (Nは列の数です). 例えばfig.ncol = 2ならばデフォルトはfig.sep = c('', '', '\\newline', '', '', '\\newline', '', ...)となります.fig.sepの長さがサブ画像の数より大きい場合を除いて, i番目のセパレータはi番目のサブ画像の後に追加されます. この例外の場合は,fig.sepの1番目の要素が最初のサブ画像の前に追加され, (i+1)番目の要素がi番目の画像の後に追加されます.fig.process(NULL;function): 画像ファイルに対する後処理の関数です. 関数は画像のファイルパスを引数として, 挿入したい新しい画像のファイルを返すものであるべきです. 関数にoptions引数がある場合, この引数にチャンクオプションのリストが与えられます.fig.showtext(NULL;logical):TRUEならばグラフの描画前にshowtext::showtext_begin()が呼ばれます. 詳細はshowtextパッケージのドキュメントを参照してください10.external(TRUE;logical): tikz グラフィックの処理 (PDF 生成時のコンパイル前の処理) を外部化するかどうかです. tikzDevice パッケージのtikz()デバイスを使う場合 (つまりdev='tikz'を指定したとき) のみ使用され, コンパイル時間を短縮することが可能です.sanitize(FALSE;character). tikz グラフィックでサニタイズ (ここでは, LaTeXで特殊な意味を持つ文字のエスケープ処理) するかどうかです. 詳細は tikzDevice パッケージのドキュメントを参照してください.
さらにこの他に, ユーザーが使用することを想定していない隠しオプションが2つあります. fig.cur (複数の図表がある場合の, 現在の図番号/インデックス) と fig.num (チャンク内の図の合計数) です. これら2つのオプションは knitr が複数の図そしてアニメーションを処理するためにあります. 場合によっては手動で保存した画像ファイルを使ってアニメーションを書き出す場合などに役に立つかもしれません (使用例として graphics manual を参照してください).
1.1.5 アニメーション関連
interval(1;numeric): アニメーションの1フレームごとの時間 (単位は秒) です.animation.hook(knitr::hook_ffmpeg_html;functionまたはcharacter). HTML 出力時のアニメーション作成用のフック関数を指定します. デフォルトでは FFmpeg を使って WebM 動画ファイルに変換します.- 別のフック関数として gifski パッケージの
knitr::hook_gifski関数はGIFアニメーションを作ることができます. - このオプションは
'ffmpeg'や'gifski'といった文字列を指定することもできます. これらは対応するフック関数の省略形です. 例:animation.hook = 'gifski'はanimation.hook = knitr::hook_gifskiを意味します.
- 別のフック関数として gifski パッケージの
aniopts('controls,loop';character): アニメーションに対する追加のオプションです. 詳細は LaTeX の animate パッケージのドキュメントを参照してください.ffmpeg.bitrate(1M;character): WebM 動画の質を制御するための FFmpeg の引数-b:vに対応する値を指定できます.ffmpeg.format(webm;character): FFmpeg の出力する動画フォーマットです. つまり, 動画ファイルの拡張子名です.
1.1.6 コードチャンク関連
code(NULL;character): 指定された場合, そのチャンクのコードを上書きします. この機能によって, プログラミング的にコード挿入が可能になります. 例えばcode = readLines('test.R')とすればtest.Rの内容を現在のチャンクで実行します.file(NULL;character): これが指定された場合,codeオプションが, チャンクとして読み込まれた外部ファイルの内容で上書きされます.file = "test.R"というチャンクオプションはcode = xfun::read_all("test.R")を指定しているのと同じことを意味します.ref.label(NULL;character): 現在のチャンクのコードに引き継ぐ, 別のチャンクのラベルの文字列ベクトルを指定します (動作例は チャンク参照 を確認してください).
1.1.8 言語エンジン関連
engine('R';character): コードチャンクの言語名です. 指定可能な名前はnames(knitr::knit_engines$get())で確認できます. 例:python,sql,julia,bash,c, など.knitr::knit_enginesで他の言語を使うためのセットアップが可能です.engine.path(NULL;character): 実行可能なエンジンのパスを指定します. あなたのお使いのシステムの別の実行ファイルを使用するためのオプションです. 例えばpythonはデフォルトでは/usr/bin/pythonを参照しますが, 他のバージョンを使うためengine.path = '~/anaconda/bin/python'などと指定することもできます11.engine.pathもまたパスのリストを与えられます. これによってエンジンごとにそれぞれパスを指定することができます. 以下のコードが例です. リストの名前はエンジン名と一致する必要があります.engine.opts(NULL;character): 言語エンジンに与える追加引数です. チャンクの段階ではオプションを文字列またはリストで指定することができます.```{bash, engine.opts='-l'} echo $PATH ``````{cat, engine.opts = list(file = "my_custom.css")} h2 { color: blue; } ```グローバルレベルでは, 要素名に言語名を与えた文字列のリストが使用できます.
engine.pathと同様に,knitr::opts_chunk$set()で引数のテンプレートを作ると便利です.各エンジンはそれぞれ自身の
engine.optsを持ち, 固有のオプションを定義します. 言語エンジンのドキュメントを調べるべきでしょう. R Markdown クックブックにはcat12,sass/scss13エンジンの例が掲載されています.
1.1.9 オプションテンプレート関連
opts.label(NULL;character): このオプションは, チャンクオプションを他のオプションのテンプレート knitr::opts_templateや, コードチャンクから引き継ぐ機能があります. テンプレートの詳細は?knitr::opts_templateを参照してください. このオプションは, ラベル名の代入されたcharacter型のベクトルを受け取ります. このベクトル内の各要素に対して, **knitr** は最初にknitr::opts_template` にあるラベルを探し出して, 見つかれば, 現在のチャンクにそのオプションテンプレートを適用しようとします. その後で, 文書内の他のチャンクラベルと名前の一致するものを探し出し, 見つかれば, 現在のチャンクに一致したチャンクのオプションを適用します. ここで参照されたコードチャンクは, 「被参照コードチャンク (refferenced code chunk)」と呼ばれます.チャンクオプションの優先順位は, (1) ローカルチャンク (2) 被参照コードチャンク, (3)
knitr::opts_templateのテンプレート, (4)knitr::opts_chunkとなります.チャンクオプション
opts.labelに対し,opts.label = TRUEは特殊な値で,opts.label = ref.labelと同じ意味になります. つまり,ref.labelオプションで指定したコードチャンクからオプションを参照します.ref.labelとopts.labelのいろいろな使用例は #121 in the knitr-examplesrepository を見てください.
1.2 パッケージオプション一覧
パッケージオプションは knitr::opts_knit を使用することで変更できます. knitr::opts_chunk と混同しないでください. 使用例は以下のとおりです.
```{.r .numberLines .lineAnchors}
knitr::opts_knit$set(progress = TRUE, verbose = TRUE)
```別の方法として, R の基本関数である options() を使ってパッケージオプションを設定する場合は ?knitr::opts_knit を参照してください.
可能なオプションは次のとおりです.
aliases(NULL;character): チャンクオプションのエイリアスを指定する名前付きベクトルです. 例えばc(h = 'fig.height', w = 'fig.width')は knitr にhはfig.heightwはfig.widthと同じ意味だと認識させます. このオプションは名前の長いチャンクオプションのタイピング労力を削減できます.base.dir(NULL;character): グラフを生成する際のディレクトリの絶対パスです.base.url(NULL;character): HTML ページに掲載する画像のベースURLです.concordance(FALSE;logical): この機能は RStudio によって実装されている機能で,.Rnwでのみ有効です. 入力ファイルの行番号に対応した行番号を出力ファイルに書き出すかどうかを指定します. これにより, 出力から入力の誘導が可能になり, 特に LaTeX のエラー発生時に役に立ちます.eval.after(c('fig.cap', 'fig.scap', 'fig.alt';character): オプション名の文字ベクトルを指定します. このオプションはチャンクが評価された**後で**評価され, 他の全てのオプションはチャンクが評価される前に評価されます. 例えばeval.after = ‘fig.cap’が指定されているときにfig.cap = paste(‘p-value is’, t.test(x)$p.value)とすると,eval.afterにはチャンクの評価後のx` の値が使用されます.global.par(FALSE;logical):TRUEにすると, それ以前のコードチャンクでのpar()での設定が引き継がれます (もちろん, この設定は R グラフィックスのみで有効です). デフォルトでは knitr はグラフの記録のために新規のグラフィックデバイスを開き, コードの評価後に閉じるため,par()による設定はその都度破棄されます.header(NULL;character): 文書の開始前に挿入するテキストを指定します. (例えば, LaTeX ならば\documentclass{article}の直後, HTML ならば<head>タグの直後). このオプションは LaTeX プリアンブルや HTML ヘッダでコマンドやスタイルの定義をするのに有用です. ドキュメントの開始地点はknitr::knit_patterns$get('document.begin')で知ることができます. このオプションは.Rnwと.Rhtml限定の機能です14.label.prefix: (c(table = 'tab:'); character) ラベルの接頭語を指定します. 現時点ではkable::kable()によって生成される表のラベルに対する接頭語のみサポートしています.latex.options.color,latex.options.graphicx(NULL): それぞれ LaTeX パッケージの color と graphicx に対するオプションを指定します. これらのオプションは.Rnw限定の機能です15.latex.tilde(NULL): .Rnw 文書のシンタックスハイライトされたチャンク出力内でのチルダ文字を表すための, LaTeX コマンドの文字列です (使用例は issue #1992 を見てください).out.format(NULL;character): 可能な値はlatex,sweave,html,markdown,jekyllです. このオプションは入力ファイル名に応じて自動で決定され, 自動設定されるフック関数に影響します. 例えば?knitr::render_latexを参考にしてください. このオプションはknitr::knit()が実行される前に設定する必要があります (文書内で設定しても機能しません).progress(TRUE;logical):knitr::knit()の実行中にプログレスバーを表示するかどうかを指定します.root.dir(NULL;character): コードチャンク評価時のルートディレクトリを指定します.NULLの場合, 入力ファイルと同じ場所が指定されます.self.contained(TRUE;logical): 出力する文書が自己完結的であるべきかどうかを指定します (.texファイルにスタイルを書き出すか,htmlに CSS を書き出すか). このオプションは.Rnwと.Rhtmlでのみ機能します16.unnamed.chunk.label(unnamed-chunk;character): ラベルを設定していないチャンクのラベルの接頭語を指定します.upload.fun(identity;function): ファイルパスを引数にとり, ファイルに対して処理を行い出力フォーマットが HTML または Markdown の場合に文字列を返す関数を指定します. 典型的な使い方として, 画像をアップロードしそのリンクを返す関数を指定します. 例えばknitr::opts_knit$set(upload.fun = knitr::imgur_upload)でファイルを http://imgur.com にアップロードできます (?knitr::imgur_uploadを参照してください).verbose(FALSE;logical): 情報を冗長に詳細するか (例えば各チャンクで実行されたRコードやメッセージログなど), チャンクラベルとオプションのみ表示するかを指定します.
1.3 グローバルRオプション
グローバルRオプションとは, base R でoptions() で設定されるもののことです. 以下は, knitrの挙動に影響するオプションの一覧です.
knitr.bib.prefix(R-;character):knitr::write_bib()で生成される書誌情報のキーの値の接頭辞です.knitr.child.warning(TRUE;logical):childを使用して子文書を読み込んでいるコードチャンクで, コードチャンクが空になっていない場合に警告を発します. このようなコードチャンクに書かれたコードは無視されるためです.FALSEを指定して警告を抑制できます.knitr.digits.signif(FALSE;logical) インラインR式内の数値をフォーマットする方法を指定します.TRUEはformat()を,FALSEはround()を意味します. を指定できます. 前者はグローバルオプションdigitsで有効桁数を指定することを意味します. 後者はdigitsで小数点以下の桁数を指定することを意味します.options(digits =)でグローバルオプションを設定できます.knitr.duplicate.label(NULL):"allow"を指定すると, 同一文書内でのチャンクラベルの重複を許容します.knitr.include.graphics.ext(FALSE;logical): LaTeX出力時に,\includegraphics{}へ出力されるファイルパスにファイル拡張子を含めるかどうかを指定します.knitr.progress.simple(NULL;logical): 出力時に進捗バーを表示するかどうかを指定します.knitr.progress.fun(knitr:::txt_pb;function):function(total, labels) {}という形式の関数を指定します. この関数は, チャンクの数が与えられるtotal引数と, チャンクラベルのベクトルが与えられるlabelsを受け取り, かつ,list(update = function(i) {}, done = function() {})のように2つのメソッドのリストを返す必要があります.update()メソッドは現在のチャンクのインデックスiを引数に取り, 進捗バーの更新を返します.done()メソッドは進捗バーを閉じます. 以下は cli パッケージの進捗バーを使用する場合の例です.function(total, labels) { id = cli::cli_progress_bar(total = total, .auto_close = FALSE) list(update = function(i) { cli::cli_progress_update(id = id) }, done = function() { cli::cli_process_done(id) }) }そして以下は, Windowsのプログレスバーを使用する例です. つまり, Windowsでのみ動作します.
knitr.progress.linenums(FALSE;logical): 進捗バーに行数を表示するかどうかを指定します. デフォルトでは, チャンクラベルのみが表示されます.knitr.progress.output("";characterまたはconnection): knitr のデフォルトのテキスト形式の進捗バーに対して, 進捗バーの出力先を指定できます. デフォルトでは, 進捗バーはstdout()に出力されます. もし代わりにstderrを使うなら,stderr()を使うことになります.knitr.purl.inline(FALSE;logical):knitr::purl()出力にインラインRコードを含めるかどうかを指定します.knitr.svg.object(FALSE;logical):TRUEならば,svg形式のプロットは, self-contained で HTMLを出力する場合は<svg>タグでHTMLに直接埋め込まれ, self-contained でない場合は<object>タグで参照されます.FALSEの場合は,<img>タグが使用されます.
訳注: R Markdown ではさらに, YAML フロントマターで適用するハイライトのテーマ名を指定できます↩︎
訳注:
\normalsize,\Large,\LARGEなど LaTeX で指定できるフォントサイズを表すマクロのことを指しています↩︎訳注: R Markdown では背景色は CSS や
class.outputなどで設定する必要があります. 詳細は R Markdown Cookbook などを参照してください↩︎訳注: R Markdown の場合は knitr 以外の中間処理があるため, 必ずしもこのルールを守りません↩︎
訳注:
pdfは日本語表示に向いていないため,cairo_pdfなどを利用することをおすすめします↩︎訳注: チャンクラベルと混同しないでください↩︎
訳注: この注釈の意図は, knitr や rmarkdown はLaTeX文書の相互参照をサポートしていないことに注意を促すものです. 例えば R Markdown文書で相互参照を使用するには, bookdown パッケージが必要になるため, このオプションを使っただけで相互参照が使用できるわけではありません.↩︎
訳注: LaTeX では通常は図の位置は調整されますが,
fig.pos='H'ならばその位置で固定されます↩︎訳注:
showtextは手っ取り早く日本語を表示できますが, いくつかの制約があります. 詳細は『おまえはもうRのグラフの日本語表示に悩まない (各OS対応)』『Rでのフォントの扱い』などを見てください.↩︎訳注: R Markdown の場合, Python のバージョンは
reticulateパッケージでも制御できます. むしろそちらをつかったほうが便利だと思われます.↩︎翻訳版: https://gedevan-aleksizde.github.io/rmarkdown-cookbook/eng-cat.html↩︎
翻訳版: https://gedevan-aleksizde.github.io/rmarkdown-cookbook/eng-sass.html↩︎
訳注: R Markdown ではヘッダの設定は YAML フロントマターで行います↩︎
訳注: R Markdown ではこの機能もやはり YAML フロントマターが担当しています↩︎
訳注: R Markdown では出力フォーマット関数に同様のオプションが用意されていることが多いです↩︎