{bookdown}を利用してRで本を作成

この記事は,R Advent Calendar 2016の第22日目の記事です。

R Markdownとは

Rでドキュメント生成

Rは一般にデータ解析や可視化で利用されることが多いですが,Rでドキュメントを生成することが可能です。多くの場合,R Markdownを利用して作成され,その便利さ,将来性に注目が集まっています。以降,R Markdownを念頭に話を進めます。

Rでやるメリット

R(R Markdown)でドキュメントを生成するメリットは数多くありますが,以下のようなものが挙げられます:

• 分析からレポート生成までが完結
  • WordもExcelも(そしてぱわぽも)いらない
  • コピペ汚染からの開放
• 再現性の確保
  • 同一の内容をそのまま再現できる
• 再利用、配布が簡単
  • コードを簡単に再利用可能
  • テキストデータなので運用が簡単
• 作るのが簡単
  • ドキュメント部分は基本Markdown

基本的な考え方

R Markdownでドキュメントを生成するには,以下のような流れとなります:

1. R Markdownファイルを準備
2. 中身を記述
3. レンダリングして出力を確認
4. 2と3を繰り返す
5. 完成

R Markdownの参考資料

R Markdownのそもそもの使い方について説明していると本題に辿りつけないので,ここでは参考資料を紹介するのみとさせていただきます:

• R Markdown
  本家のサイト。ここに始まりここに終わります。チュートリアルが最強。
• R Markdownで楽々レポートづくり
  日本語でR Markdownがどういうものなのかを解説してあります。
• R Markdown入門
  スライドで要点を簡単にまとめています。

Rで本を作りたい

ドキュメントをまとめたい

R Markdownを使うようになって慣れてくると,だいぶドキュメントが溜まってくるようになります。またRのテキストや分析のまとまったドキュメントをR Markdownで作ってみたくなったり,書籍の形式でまとめてみたくなったりします。

R MarkdownではRStudioと連動して,Webサイトをbuildしたりすることも可能ですが,できればepub形式やgitbook,あるいはpdf形式でまとめたいと思うところでしょう。{rmarkdown}パッケージだけではこれを実現することは難しいです…でも,{bookdown}パッケージならそれが可能となります。

bookdownパッケージ

{bookdown}パッケージは,knitrなどの開発で知られるYihuiが中心となって開発した,R Markdownで書籍を作成するためのパッケージです。これは,複数のRmdファイル(とその他諸々)を束ねて一冊の書籍ファイルを出力してくれます。いくつかの特徴を挙げると…

• gitbook形式, ePub形式, pdf形式
• 本を通じての図表番号割り振り
• 表紙画像もおk
• citationも対応

など,書籍,特に電子書籍を自作するにあたって最低限必要となる機能は盛り込まれています。なお試しに私の方で作ってみた,ggplot2逆引き本をみてもらうと伝わるかと思います。

基本的な仕組み

要するに,複数のRmdファイルをいい感じにまとめてしまい,それをKnit(チャンクを評価)して,出来上がったmdファイルをPandocで各種出力形式で吐き出す,という感じです:

このRmdをまとめあげる時のルールや設定,あるいは各種出力形式での設定などを設定ファイルに記述していくことになります。

前準備

{bookdown}パッケージで書籍を作るための前準備として,以下のものが必要となってきます。

• bookdownパッケージ(必須)
  install.packages("bookdown")でOK
• RStudio(できれば)
  v1.0以上で。
• tex環境
  pdf出力に必須。ただしいつものpdf_document以上に罠多し。
• ePubビューワ
  ePub出力結果の確認に必要。

作り方

基本的な構成

以下の要素は基本必要です:

• _bookdown.yml
• _output.yml
• *.Rmd
• *.Rmd ...

_bookdown.yml

書籍全体に関する設定を記述します:

book_filename: "R usui book"  # 書籍名(ファイル名になる)
chapter_name: "ch: "          # この場合 ch: 1 と自動で振られる
output_dir: "docs"            # 出力先の指定(デフォは"_book")
rmd_files:                    # 使用するRmdファイルを指定
  - kosaki.Rmd                  # この順番に束ねます
  - Rmds/sweet.Rmd              # デフォではファイル名昇順

その他は本家ドキュメントの4.4とかを参照。

_output.yml

output設定を記述します:

bookdown::epub_book: default
bookdown::gitbook:
  css: style.css
  split_by: "rmd"
  config:
    toc:
      before: |
        <li><a href="./">book title.</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
bookdown::pdf_book:
  keep_tex: yes

その他は本家ドキュメントの3とかを参照。

.Rmdファイル

通常通り作成してください。ただ,いつもの冒頭のyamlは設置しないようにしてください。これは無視されます。

ですが,扉(入り口)となるようなファイル(index.Rmdなど)を準備し,そこに冒頭yamlで設定をきっちり記述するのはOKです。詳しくは,さきほど紹介したggplot2逆引き本のGitHubリポジトリ内にあるindex.Rmdを参照してもらえればと思います。

レンダリング

RStudioを利用しているならば,Buildパネルから,Build
Bookをクリックし,出力したい形式を選択すればOKです。

もし,yamlヘッダーを(ちゃんと)作りこんだRmdファイル(ここではindex.Rmdとします)があるなら,以下のような感じでレンダリングを実行できます:

• gitbook形式:

  bookdown::render_book("index.Rmd", output_format = "bookdown::gitbook")
  

• epub形式:

  bookdown::render_book("index.Rmd", output_format = "bookdown::epub_book")
  

• pdf形式:

  bookdown::render_book("index.Rmd", output_format = "bookdown::pdf_book")
  

生成物を確認してみて,うまくいっているか確認してみましょう。

注意点

文字コード

bookdownがサポートしているのはUTF-8のみです:

All R Markdown files must be encoded in UTF-8, especially when they
contain multi-byte characters such as Chinese, Japanese, and Korean.

--- Yihui Xie

注意してください。

日本語見出しについて

{bookdown}は日本語にもちろん対応しています。ただし,R Markdownいつもの日本語見出し問題は健在です。これについては,以下の記事を参照してください:

第4回　レポつく自由自在 ～R Markdownにまつわるエトセトラ～：R Markdownで楽々レポートづくり｜gihyo.jp 技術評論社

ここにあるpandoc_argsの設定は,_output.ymlに記述してください。よくわからない場合は聞いてください。

pdf & ggplot2 & 日本語の罠

pdf出力するにはTex環境が必要で,これまでのRmdと同様のことがすべて当てはまります。さらに,bookdownでダルトラブルとしては,pdf_book出力形式でggplot2で作成した図に日本語を使用すると文字化け(もしくはエラー)が出てくるというのがあります。

pdf_book(正確にはpdf_document)の場合，Rチャンクの出力はdev=pdf()がデフォルトに設定してあり,これが日本語を含むggplot2出力でひっかかってしまうためです。

これについて,回避策(暫定的)なものとしては…

• dev=png()に変更させる
  • 画質調整しないとpdfで汚くなる
• dev=cairo_pfd()の利用
  • でも全体に設定するとhtmlやepubでコケる
  • トリックはあるけど…(検証中)

他にもいくつかあるんですが,あまり検証する余裕がないので見送ってます。どうしても必要なんじゃあという方がいましたらご連絡ください。

Merge-KnitかKnit-Mergeか

この記事の前の方で,「Rmdファイルをまとめて(Merge)してからKnitする」と説明しましたが,以下のような流れでも処理させることは可能です:

このように処理させたい場合は,_bookdown.ymlにnew_session: trueと追記してください。これら処理フローの違いについては,詳しくは本家ドキュメントの1.4を参照してください。

さいごに

bookdownの参考資料など

実際作るとなると,いろいろわからないことがあるかと思います。この記事だけでは不十分なので,以下を参考にしてみてください:

• まずは本家ドキュメントを読んでね
• 日本語向けに調整した，最小構成のリポジトリをGitHubに作ってました
  • kazutan/bookdown_ja_template
• いろいろ設定しましたが，以下のリポジトリも参考になるかと
  • kazutan/ggplot2-gyakubiki-book
• 本家が準備しているデモ用リポジトリも
  • rstudio/bookdown-demo
• r-wakalangの#rmarkdown，@kazutan，#おねがいぞうさん

Enjoy!