knitr

本稿は CC BY-NC-SA 4.0 (クリエイティブ・コモンズ 表示 - 非営利 - 継承 4.0 国際)ライセンス で提供されています. Yihui 氏によるオリジナルは https://yihui.org/knitr/ で読むことができます.

This is an unofficial Japanese translation of Yihui’s knitr documentation, which is licensed under CC BY-NC-SA 4.0. The original documentation by Yihui is here.

訳注: Yihui 氏のサイトの一連のドキュメントはかなり以前から氏のブログ投稿として断続的に更新されてきたものを編纂しているため, 内容の重複した記述がいくつかありますし, RStudio および R Markdown が普及している現在では, やや out-of-date な記述も見られます (現在では Sweave はあまり使いません). そのため, サイドバーの目次から辿れるページ, およびそれらでリンクされているページ以外は重要度が低いと見なし, 翻訳していません. 同様の理由から「用例」も一部を除き翻訳していません (共同翻訳者は常に歓迎します: https://github.com/Gedevan-Aleksizde/knitr-doc-ja).

しかしながら翻訳時の knitr および R Markdown に関する日本語の情報流通を鑑みるに, 非常に有用なドキュメントであると翻訳者は確信しています. それぞれのトピックがどの環境を想定したものなのか, よく確認してご覧ください.

概要

knitr パッケージは R を使用した透明な動的なレポート作成エンジンとしてデザインされ, 長年にわたって存在した Sweave の問題を解決するとともに他のアドオンパッケージの機能を統合しています (knitr ≈ Sweave + cacheSweave + pgfSweave + weaver + animation::saveLatex + R2HTML::RweaveHTML + highlight::HighlightWeaveLatex + 0.2 * brew + 0.1 * SweaveListingUtils + その他).

  • 透明性とはユーザーが入力と出力に完全にアクセスできることを意味します. 例えば R ターミナル上では 1 + 2 は [1] 3 を出力しますが, knitrによってユーザーは 1 + 2 を LaTeX の \begin{verbatim} と \end{verbatim} や, HTML タグ <div class="rsource"> と </div> の間に出力したりできますし, [1] 3 を \begin{Routput} と \end{Routput} の間に出力できたりします. 詳細は 2 章『フック』を参照してください.
  • knitr は R コードを Rターミナル上で実行した場合でもユーザーの意図する結果と一致することを目指しています. 例えば qplot(x, y) でそのままグラフを出力できます (print() は不要です) し, デフォルトでコードチャンク内の全てのプロットが出力されます.
  • pgfSweave や cacheSweave といったパッケージは有用な機能を Sweave に提供しました (高品質な tikz のグラフィックとキャッシュ) が, knitr はこの実装をより簡単にしました.
  • knitr のデザインによってあらゆる言語 (例: R, Python, awk) が入力可能となり, あらゆるマークアップ言語の形式で出力が可能となりました (例: LaTeX, HTML, Markdown, AsciiDoc, reStructuredText).

このパッケージは GitHub 上で開発されており, インストール手順とFAQもここで参照できます. パッケージの README も確認してください. このサイトは knitr の完全なドキュメントとして提供されており, メインマニュアル, グラフィックス, 用例, knitr-examples を閲覧することができます. さらに統合的な参考資料としては, knitr book (邦訳未刊行) をご覧ください.

モチベーション

Sweave の拡張の難しいところは utils パッケージから大量のコードをコピーする必要があることでした (SweaveDrivers.R のコードは700行を超えています). そしてこれは上述の2つのパッケージ両方での作業です. コードをコピーペーストしたら, パッケージ開発者は R の公式バージョンの変更にとても慎重に対応せねばなりません — うんざりする仕事だとは思いませんか. knitr パッケージでは sweave の処理の全行程を小規模な管理しやすい関数群へとモジュール化したため, 喜ばしいことにメンテナンスも機能拡張も容易になりました (例えば簡単に HTML への対応もできるようになりました). その一方で knitr は多くのビルトイン機能を持ちますが, パッケージの機能のコア部分をハックする必要のないようになっています. そして, Sweave のマニュアルの FAQ の項目にあったいくつかの問題は, knitr は直接解決することができます.

旧態依然とした態度をプログラム構造へと変えましょう. 「我々の主な仕事は何をすべきかコンピュータに教えることである」と考えるのをやめ, むしろ「人間に対してコンピュータにさせたかったことを説明する」ように注力することです

— ドナルド E. クヌース 『文芸的プログラミング』, 1984

特徴

本パッケージのアイディアは他のパッケージから借用し, いくつか (キャッシュなど) は異なる形で再実装されています. 以下にパッケージの特徴をいくつか挙げます:

  • 信頼性の高い出力: バックエンドで evaluate を使用することで, knitr においてあらゆるコードは, 結果のプリント, グラフのプロットそして警告・メッセージ・エラーでさえ, R ターミナルでするのと同様に書き出されます. (厳密にプログラミングする場合, これらは無視するべきではありません. 特に警告は).
    • ggplot2 や lattice のようなグリッドベースのグラフィックパッケージでは, ユーザーはしばしば print() を書くのを忘れてしまう, これは些細な問題です. 実際に R ターミナルで出力する時に print() は不要ですから. knitr ではあなたが意図したとおりの結果を得ることができます.
  • キャッシュ機能の組み込み: cacheSweave のようですが, しかし knitr ではキャッシュの保存や遅延読み込みのため base R の関数を直接使い, そして最も顕著な違いはキャッシュされたチャンクは依然として出力もできることです (cacheSweave ではキャッシュされたチャンクは. print() を明示的に書いたとしても何も出力しませんが, knitr はキャッシュされても通常通り出力します).
  • R コードの整形: R コードの自動整形に formatR パッケージが使用されます (長い行の折り返し, スペースとインデントの追加, など). これは keep.source=FALSE としてもコメントが犠牲になることはありません.
  • 20 を超えるグラフィックデバイスを直接サポートしています. チャンクオプションに dev='CairoPNG' と書けば, すぐさま Cairo パッケージの CairoPNG() に切り替えることができますし, dev='tikz' なら tikzDevice パッケージの tikz() に切り替えられます. これ以上簡単にすることなどできないでしょう? これらの組み込みのデバイス (正確に言うならラッパー) は単位にインチを使用しています. ビットマップでもです (ピクセルは dpi オプションに基づいて変換されます. デフォルトは 72 です).
  • グラフィックスにおけるさらなる柔軟性:
    • 出力の幅と高さをさらに指定することが出来ます (fig.width はグラフィックデバイスのオプションで, out.width は文書に出力する際のものです. たとえば LaTeX なら out.width='.8\\textwidth' とします.)
    • グラフの位置も再調整できます. グラフが生成された位置に正確に掲載することも, チャンクとまとめて表示することもできます (fig.show='hold' オプションを使用してください).
    • 最後のグラフだけ欲しいというのでない限り (fig.keep='last' オプションを使用してください), コードチャンクごとに複数のグラフが保存されます.
  • R コードはコードチャンクに直接書くだけでなく, 他の R スクリプトファイルから読み込むこともでき, 文書を書きながらコードを実行するのが簡単になりました (特に LyX で有益です).
  • パワーユーザーのために, さらなるカスタマイズが可能になっています.
    • Rコードをパースする際に正規表現は拒否されます. つまり, <<>>=, @, \Sexpr{} などを使う必要はありません. もしやりたいのなら任意のパターンを使用できます. 例: %% begin.rcode, %% end.rcode.
    • フック (hook) は出力の制御を拒否します. 例えばエラーメッセージを赤い太字で表示したいとしたら, ソースコードをイタリック体で表示したいとしたら, フック機能をコードの実行前および実行語に定義することが出来ます. フック機能はこのパッケージの力を無限に拡大する可能性を持ちます. (例えば, アニメーションとか, rgl 3D プロットとか…)

多くの取り組みが, デフォルトでの美しい出力と可読性の向上をもたらしています. 例えばコードチャンクはシンタックスハイライトされて表示され, LaTeX ではさらに (framed パッケージを使うことで) 薄灰色の背景色がつきます. そのため他のテキストよりやや目立って表示されます. 読書体験はきっと verbatim や Verbatim 環境を使うよりも良いものとなります. プロンプトで表示される先頭の > や + はデフォルトでは出力されません (prompt=TRUE で表示することもできます). このような記号はコードに割り込んでくるので, コードをコピーして自分で実行する際に非常に不便であり, ドキュメントを読む時にまったくもって迷惑していました (訳注: とてもよくわかる).

謝辞

Sweave, pgfSweave, cacheSweave, brew, decumar, R2HTML, tikzDevice, highlight, digest, evaluate, roxygen2, そしてもちろん, R の開発者に対し, 多くのひらめきとツールをもたらしてくれたことに感謝します. 多くのベータテスターによる フィードバック に心から感謝します. 本パッケージは documar のデザインに基づいて始まりました.

FOAS

knitr が Foundation for Open Access Statistics (FOAS) の協力のもとで開発されたことを誇りに思います. FOAS はフリーウェア, オープンアクセス, 統計学における再現可能な研究を推進するという世界規模の課題を持った非営利の公益法人です.

  1. twitter@ill_identified↩︎