本書の読み方

本書は R Markdown の基礎を理解している読者におすすめです. R Markdown: The Definitive Guide (Xie, Allaire, and Grolemund 2018) の Chapter 2 は R Markdown の基礎を解説しており, 新規ユーザーが読むのにおすすめです. たとえば, 本書では Markdown の構文はカバーしていませんので, 読者が他の手段でそれを学んでいる想定です. 特に, 最低でも一度は Pandoc の完全なマニュアル2 に目を通すことを強くお薦めします. このマニュアルはかなり長大ですが, 金の鉱脈のようなものでもあります. 全てを覚えなくてもかまいませんが, Markdown の機能をどう応用できるかを知っていればとても役に立つでしょう. 多くの人々が3連続バッククォートを verbatim なコードブロックに書こうとして失敗したり, 子要素を持つリストを作ろうとして失敗したりするのを, 私は数え切れないほど見てきました. マニュアルに書いてある Markdown の構文を全て読まなければ, 「N 連続バッククォートに対して外側に N + 1 連続でバッククォートを書く」「子要素を表現するには適切なインデントをつける」といったことに, きっと気づかないままでしょう.

このクックブックは R Markdown の技術的なリファレンスを網羅することを意図したものではありません. 本書はこれまでにある資料に対する補足となることを目的としています. よって読者は, さらに詳細な情報を知るために以下のような本を参考にすればよいでしょう.

  • R Markdown: The Definitive Guide (Xie, Allaire, and Grolemund 2018) は rmarkdown パッケージやその他いくつかの拡張パッケージでの R Markdown の出力フォーマットに関する技術的資料です.

  • R for Data Science (Wickham and Grolemund 2016b)3 の Part V “Communicate.”: このパートは上記の “Definitive Guide” よりも技術的なことは少ないので, より平易な R Markdown の入門になるでしょう.

  • Dynamic Documents with R and knitr (Xie 2015) は knitr パッケージ (Xie 2021d) の網羅的な入門書です (補足しますと, R Markdown は knitr パッケージのサポートする文書形式の1つにすぎません). 短縮版を読みたい場合, Karl Broman による最小限のチュートリアル “knitr in a knutshell” が役に立つでしょう. 訳注: これらは日本語訳が存在しませんが, Yihui 氏によるドキュメント knitr Elegant, flexible, and fast dynamic report generation with R の日本語訳は既に用意してあります4.

  • bookdown: Authoring Books and Technical Documents with R Markdown (Xie 2016) は bookdown パッケージ (Xie 2021b) の公式ドキュメントとして書かれた小冊子です. bookdown パッケージは長大なフォーマットのドキュメントを R Markdown で簡単に書くために設計されました.

  • blogdown: Creating Websites with R Markdown (Xie, Hill, and Thomas 2017) は blogdown パッケージ (Xie, Dervieux, and Presmanes Hill 2022) によって R Markdown でウェブサイトを作成する方法を紹介してます.

関連性に応じて本書は既存の参考資料を紹介します. それとは別に, R Markdown の公式ウェブサイトにも役立つ情報が多く含まれています: https://rmarkdown.rstudio.com

本書は最初から順に読む必要はありません. 以降の各章はそれより前の章よりも難解になることはありません. 各章と各セクションのうち, 他よりも発展的と思われるものに対しては, タイトルにアスタリスク (*) を付けています. R Markdown でやりたい具体的なタスクがあるとき, あるいは目次に目を通していたら興味のある箇所が見つかった, という使い方が最も効率的な読み方でしょう. いくつかの箇所で相互参照を免れないところがありますが, 用例集を理解するのに必要な予備知識への参照のつもりです.

自分で用例集に挑戦したいならば, 本書の完全なソースコードと用例集は Github の https://github.com/yihui/rmarkdown-cookbook で自由に見ることができます5. 本書の電子書籍版をお読みの場合, 掲載されているコードをお好きなテキストエディタにコピー&ペーストして実行することになるでしょう.

参考文献

———. 2016b. R for Data Science: Import, Tidy, Transform, Visualize, and Model Data. First edition. Sebastopol, CA: O’Reilly. https://r4ds.had.co.nz/.
Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. https://yihui.org/knitr/.
———. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/bookdown.
———. 2021b. Bookdown: Authoring Books and Technical Documents with r Markdown. https://CRAN.R-project.org/package=bookdown.
———. 2021d. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.
Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.
Xie, Yihui, Christophe Dervieux, and Alison Presmanes Hill. 2022. Blogdown: Create Blogs and Websites with r Markdown. https://CRAN.R-project.org/package=blogdown.
Xie, Yihui, Alison Presmanes Hill, and Amber Thomas. 2017. Blogdown: Creating Websites with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/blogdown/.

  1. 訳注: 完全ではありませんが, 日本語訳が公開されています. https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html↩︎

  2. 本書は https://r4ds.had.co.nz/ で無料公開されています. また, 日本語訳『Rではじめるデータサイエンス』というタイトルでオライリー・ジャパンより出版されています.↩︎

  3. https://gedevan-aleksizde.github.io/knitr-doc-ja/↩︎

  4. 訳注: この日本語版のソースコードは https://github.com/Gedevan-Aleksizde/rmarkdown-cookbook で見られます. 用例集はさらに JP/examples ディレクトリを辿ることで見つかります.↩︎