R ユーザー以外も知るべき R Markdown 入門/Introduction-to-R-markdown-for-Everyone

Tokyor.R #91 「R Markdown 入門」

ハイパーリンクが含まれているため, PDF をダウンロードしてご覧ください

補足資料 -> こちらにもチュートリアル的な内容を追加しました
https://rpubs.com/ktgrstsh/755893

環境設定&資料のソースコード
https://github.com/Gedevan-Aleksizde/tokyor-91-rmd

Transcript

1. R ユーザー以外も知るべき R Markdown 入門 2021 年版 Katagiri, Satoshi 2021/04/17, Tokyo.R #91 1
2. アジェンダ
3. このスライドの想定読者 1. R を始めたばかりの 初心者 • そもそも R Markdown (RMD) って何? という人 2. R Markdown を試したけどうまくできなかった人 • 出力がおかしい/エラーが出る 3. R ユーザーで技術文書や論文を効率的に書きたい人 4. R 以外の言語でそれをやりたい人 • 特に Python と Julia で計算している人 • L A TEX で論文/レポート書のが難しいという人 • Jupyter でレポーティングはやりづらいと感じている人 2
4. (自己紹介) この登壇しているオジサンはそんなに詳しいの? • fontregisterer 作成者 • “R Markdown Cookbook” 翻訳者 3
5. 今回触れる内容 • R Markdown とは • R Markdown でなにができるの • RStudio での設定方法 • Markdown の記法 • コードチャンクの説明 • HTML/PDF/WORD への出力 • その他発展的話題 • 時間がなかったら中断します 4
6. 逆に触れない内容 • R Markdown や knitr の内部処理の詳解 • 個別の事例 • XX 学会の論文フォーマットを作りたい • 細かすぎるテクニック • 脱線したらツッコミ入れてください • これらは最後に参考文献の紹介するのみ 5
7. R Markdown とは
8. こんな経験はありませんか? (1/2) 1. 実験結果からグラフ画像を作成し Word/LaTeX 原稿に貼り 付け 2. 修正が必要になったので再作成して貼り付け 3. とおもったら原稿に反映し忘れ 4. そして……死 6
9. こんな経験はありませんか? (2/2) 1. 数字を L A TEX のかっこいい表にしたい 2. L A TEX 構文が複雑過ぎる 3. そして……死 7
10. R Markdown の機能概要 • 文字通り R + Markdown • 簡単な構文でリッチテキスト文書を作成するツール • Web サイト, 発表スライド, PDF 形式の文書, レポート等 • R プログラムの埋め込み • R が生成したグラフ・表・計算結果などを文書に直接掲載 • 手動コピペ不要 • rmarkdown パッケージとして提供されている • 機能拡張パッケージも多数 • 内部処理の技術的な話は以下参照 • R Markdown Cookbook 2 章 • kazutan のスライド (これも RMD 製のはず) 8
11. R Markdown でなにができるの
12. R Markdown なんて面倒くさいだけでしょ? • Q.: Word やパワポ/Keynote みたいに操作できないんで しょ? • WYSYWIG じゃないとわからない • Q.: Overleaf とか LyX 使ってるからいいや • 熟練の LaTeX 使い • Q.: Jupyter で十分じゃないの? • 注: Jupyter は R とかも一応使える 9
13. Q.: Word やパワポ/Keynote みたいにできないんでしょ? A.: ビジュアルエディタモードあるよ 10
14. Q: Overleaf とか LyX 使ってるからいいや A.: 毎回使う LaTeX コマンドは数式だけでしょ? 11
15. Q: Jupyter で十分じゃないの? • A: RMD にも類似した Notebook という機能あり • むしろ Jupyter はワードプロセッサ機能が弱い • 例: コードが長すぎてスライドで見切れる 12
16. RMD で何ができるの? => スライドを作成できる • 今見ているスライド (PDF) も全て R Markdown で作成 • L A TEX の beamer を経由 • HTML 形式も可 • xaringan, reveals など 13
17. RMD で何ができるの? => 本を出版できる •『R Markdown クックブック』 • 翻訳版も R Markdown 製 • 商業出版の例 • Hadley et al. “R for Data Science” (『R で始めるデータサイ エンス』) • Hearly “Data Visualization” (『データ可視化入門』) •「技術同人誌」 • https://bookdown.org/ はクローリングサイト 14
18. RMD で何ができるの? => 料理書が書ける 15
19. R Markdown のハンズオン風チュー トリアル
20. • 以降はチュートリアル風に進行 • 徐々に高度な機能を使いこなせるようになりましょう 16
21. 最初に用意するもの • OS: Windows 10 or Ubuntu 20.04 or macOS Catalina • 最新の R (>= 4.0.5)1 • 最新の RStudio (> 1.4.11)2 • rocker で統一してもいいが自分が面倒がって使ってないの でマルチプラットフォームで 1Windows 以外はあまり気にしなくていい 2Windows かつ Python 使う人は daily builds 17
22. 必要パッケージ • rmarkdown, bookdown, remotes, rmdja パッケージ • Python を使うなら reticulate も必要 install.packages(c("rmarkdown", "bookdown", "remotes")) ↪ remotes::install_github( ⌋ "Gedevan-Aleksidze/rmdja") ↪ • LaTeX (PDF が必要な場合) • 実インストールなら tinytex パッケージ 18
23. パッケージ等のダウンロード • ここに補足資料を上げました. • ここにソースがあります. • rmd-setup.R を参考にしてください. 19
24. R Markdown の新規作成 (1/3) 1. R Markdown… を選ぶ 20
25. R Markdown の新規作成 (2/3) 2. HTML を選ぶ 21
26. R Markdown の新規作成 (3/3) 3. title:, author: を書き換える 4. 適当なファイル名で保存 5. 上の “Knit” ボタンでコンパイル 22
27. できた! 23
28. Markdown
29. Markdown の基本 • Markdown は「マークアップ言語」 • HTML タグとか, テキストを装飾し, 「見出し」 「段落」など 意味を与える • シンプルなので視覚的に分かりやすい • HTML のようにタグがゴチャゴチャしてない • メモ帳と同じ感覚で使える • 方言が多い点に注意 • 例 GitHub, Slack 24
30. Markdown の代表的な構文: 行内要素 • 文のスタイルを部分的に変更する 1. 文字のスタイル •「** 太字 **」-> 「太字」 •「* 斜体/イタリック Itacic*」-> 「斜体/イタリック Itacic」3 • **/* の代わりに __/_ も可 • 1 + 1 (バッククオート) でタイプライタ体 1 + 1 •「~~ 打ち消し線 ~~」-> 「打ち消し線」 3日本語は対応してないこともある 25
31. Markdown の代表的な構文: 行内数式 2. LaTeX 数式 •「$f(x)$」-> 「𝑓(𝑥)」 3. 独立行なら $$ で囲む • または, align など直接 LaTeX を書く 26
32. Markdown の代表的な構文: ブロック要素 (1/2) • テキストのまとまりを定義する 1. 行頭に「#」で見出し # 第 1 章: 序 • # を増やすと階層が深くなる • このスライドのタイトルは ## 2. 行頭に「*」で箇条書き • 直後のスペース必須 • インデントで階層化可能 • インデントは tab 2 個 (スペース 4 つ) 以上4 3.「1.」or 「a.」で番号付き箇条書き a. これもインデント可 b. 番号を書かなくても自動で調整 4RStudio のデフォルト設定のため 27
33. Markdown の代表的な構文: ブロック要素 (2/2) 4. コメントアウトは HTML 方式 <!-- ここは出力されない --> 5. 見出しブロック (Beamer のみ) これは警告です これは alertblock 環境 • 表を記述することもできるが省略 • わかりにくかったらこのスライドの Rmd ファイルで 見てね 28
34. Visual Markdown Editor • どうしても苦手なら Word のような編集モードあり • 右上のコンパスマークをクリック 29
35. R コードの埋め込み
36. コードチャンクと行内コード • R コードの埋め込みは 2 種類 • 独立したブロックとしてのコードチャンク • 表やグラフの埋め込み • ソースコードの掲載 • その他複雑な処理 • 他のプログラミング言語も使用可能 • 簡単な 1 文だけのコードの行内埋め込み • 1 + 1 = 2 のように Markdown 内に出力を埋め込める •「2」の部分は実際には `r 1 + 1` と書いている 30
37. 行内コード • `r <R コード >` • 複雑なコードは書けない • 単文でできることのみ • 原則文字の出力のみ • グラフや表は想定されていない • よくある使い方 • 表紙の日付を自動更新 • date: 2021-04-17 31
38. コードチャンク (1/2) • より複雑なプログラムを書き, 図表を出力できる ```{r, LABEL, echo=T} 1 + 1 summary(mtcars) ``` • LABEL は自由な名前を付けてよい • 省略してもよい • それ以降は「チャンクオプション」 • 出力結果などを制御する • R の引数と同じように書ける 32
39. コードチャンク (2/2) • 作業中の実行も可能 • 右の矢印をクリック • R notebook を使うのもあり 33
40. よく使うチャンクオプション • echo: コードを表示するかどうか • スライドでは邪魔なのでよく非表示にする • eval=F: コードを実行しない • コードだけ見せたい時に • fig.cap="": 図のキャプション • 詳細は ここ とか参照 34
41. HTML/PDF/DOCX/PPTX への変換
42. HTML/PDF/DOCX/PPTX への変換 • HTML はすでにやった通り • ドキュメントの出力をかえるには YAML メタデータを書き 換える • PDF/DOCX (Word)/PPTX (パワポ) はちょっと複雑 • というか異なるフォーマットの同時出力が複雑 35
43. 出力フォーマット関数 • 出力フォーマットが主に文書の体裁を決める • output: html_document の部分で指定 • rmarkdown にいくつも用意されている • しかし実際には他のパッケージのほうが便利 ファイル形式 デフォルト おすすめ PDF pdf_document rmdja::pdf_document2_ja HTML html_document bookdown::html_document2 Word (DOCX) word_document officedown::rdocx_document スライド (PDF) beamer_presentation rmdja::beamer_presentation_ja スライド (HTML) slidy_presentation ? スライド (PPTX) powerpoint_presentation officedown::rpptx_document 36
44. PDF の設定 最小限の設定はこうだが… output: pdf_document: latex_engine: lualatex documentclass: ltjsarticle classoption: haranoaji 37
45. まずうまくいかない • 実際に使うといろいろとボロが出ます • 打ち消し線を使うとエラー • 参考文献リストが変 • 存在しないフォントは使えない 38
46. PDF は rmdja を使え (1/3) • PDF が難しい理由 1. デフォルト設定が日本語を想定していないため 2. LaTeX の設定も意識する必要 3. HTML と比べるとデフォルトの見た目が寂しい 4. そもそも用途が HTML と違う • PDF を HTML と両立して日本語出力するため rmdja を 作った • インストール方法は参考資料の通り 39
47. PDF は rmdja を使え (2/3) • まずはインストール • テンプレートから選ぶ 40
48. PDF は rmdja を使え (3/3) • もともとはスライド作成用だった • 現在は HTML/PDF の出力を両立できること目指す • 現在は以下の 4 種類の PDF フォーマット 1. 書籍 2. 論文 3. スライド 4. 縦書き 41
49. Word への出力 (1/2) • 最低限の設定 output: word_document 42
50. Word への出力 (2/2) • おすすめ • (たまにうまく行かないことがある) output: officedown::rdocx_document: base_format: bookdown::word_document2 toc: true tables: caption: pre: " 表" plots: style: aling: center caption: pre: " 図" 43
51. Word への出力 (3/2) • (余計なお世話?) 本当に Word を使う必要がある? • 提出物は HTML や PDF じゃダメ? • 共著者が Word しか使えない? • RMD は PDF を直接作れます 44
52. パワーポイントへの出力 (PPTX) • あんまり使ってないけどたぶんいける output: powerpoint_presentation output: officedown::rpptx_presentation 45
53. スライドへの出力 (PDF) • 最も簡単な方法 • rmdja パッケージのほうが便利です (たぶん) output: beamer_presentation: latex_engine: lualatex mainfont: haranoaji 46
54. Q.: スライドからはみ出すんだけど? • A.: 慣れましょう • 詰め込み過ぎは良くないです • この発表みたいになります 47
55. YAML について • title:, author, output: は YAML メタデータと呼ばれ る • カスタマイズに重要 • 細かい話になるので冒頭の資料を見てください 48
56. ちょっと発展的な話
57. 相互参照 • 図・表・セクション見出し, 数式, 引用文献を参照したい •「図 1 が分析結果である」 「2 章を見よ」など文書内の参照 • 番号やハイパーリンクを自分で書くと後で修正するのが大 変 • bookdown 系のフォーマットで実現 • rmarkdown 単体では不可 • 末尾に 2 と付くフォーマット 49
58. 図・画像への相互参照 • コードチャンクへ参照する形で実現 • 画像ファイルは knitr::include_graphics() 1. コードチャンクのラベルを書く 2. fig.cap=" キャプション" オプションでキャプションを 書く 3. \@ref(fig: チャンクラベル) で参照 50
59. 画像への相互参照の実例 • 図1 を見よ! • ggplot2 ももちろん掲載できる {r, image1, fig.cap=" 図への相互参照"} knitr::include_graphics("img/logo.png") 図 1: 図への相互参照 51
60. 表への相互参照 • データフレームをそのまま表にできる • チャンクラベルを指定 • knitr::kable(df, caption="...") が表のスタイル を自動生成 • チャンクオプションではないことに注意 • \@ref(tab: チャンクラベル) というふうに指定 52
61. 表への相互参照の実例 • kableExtra による表1を見よ!! ```{r, table1} knitr::kable(head(mtcars, 4), caption="表 へ の 相 互 参 照")` ``` 表 1: 表への相互参照 mpg cyl disp hp drat wt qsec vs am gear carb Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 53
62. 相互参照のさらなる応用 • 複数の図表を 1 つにまとめることも可能 • 詳細は Cookbook • 引用文献のスタイル変更 • PDF は BibLaTeX (.bbx) • HTML は CSL (.csl) • (u)pBibTeX (.bst) はちょっとややこしい • 論文フォーマットは LaTeX に依存している事が多いので一 般化は難しい 54
63. R 以外の言語 • コードチャンクには R 以外の言語も使える • r を別の言語に書き換える • stan コードを直接書くことも可能 • Python, Julia も同様に使える • それ以外は別のチャンクに設定・変数を持ち越せない • チャンクごとにプログラムを呼び出しているため • Python 使用例: 例のスライド • 新規登録も可能 • 詳細はクックブック 15 章 55
64. Python のコードチャンク • reticulate パッケージで使用可能 • RStudio 1.4 からかなり使いやすくなった • コードチャンクの r の部分を python に import numpy as np np.array([1, 1]) array([1, 1]) 56
65. Julia のコードチャンク • JuliaCall パッケージで使用可能 • https://julialang.org/downloads/ • まだ不安定なところが多い • 古いバージョンにする必要 • Gadfly が使えない? • 画像の保存は手動にしたほうが安定? • 参考: Remark.jl という Julia パッケージあり • remark.js ベース 57
66. Julia 使用例 (失敗!!) • 要 Julia 本体 & JuliaCall & 環境設定 using Plots gr() Plots.GRBackend() plot(Plots.fakedata(50,5),w=3) Plot{Plots.GRBackend() n=5} 58
67. PDF/LaTeX 関係の応用
68. PDF/LaTeX 周りの予備知識 • PDF は LaTeX を使用して生成 • いくつかのエンジンがある • 文書全体のスタイルは主に LaTeX の文書クラスファイル で定義 • bxjsarticle, ltjsarticle, beamer, etc. 59
69. どの LaTeX エンジンを使うべきか • latex_engine でエンジンを変更できる • 結論: 詳しくない人は xelatex (XƎL A TEX)/lualatex (LuaL A TEX) 2 択 • XƎL A TEX: 禁則処理に一部難あり, 速い • スライドだと気にならない? • LuaL A TEX: 使用者が多い, 遅い • pdfL A TEX: 日本語メインなら使わない • 欧文ジャーナルでは現役 • pL A TEX, upL A TEX-> Rmd のサポート外 • 後述 60
70. 以降は詳しい人 or 詳しくなることを強いられている人向け 61
71. Rmd のサポート外の処理 • 以下を要求する国内学会公式フォーマット • (u)pL A TEX 前提の .cls/.sty • (u)pBIBTEX 前提の .bst • いずれもデフォルトの Rmd では非対応 • 日本独自開発の処理系のため • 要 tinytex のエミュレーション無効化 • 以下をチャンクのどこかに書く options(tinytex.latexmk.emulation = F) • LaTeX エラーのデバッグが少しやりづらくなる 62
72. 論文フォーマットは決まってるけど LaTeX テンプレがない場合 は? A.: Good Luck! • .cls, .bbx の自作 • jpaRmd を参考に全部 R で処理 63
73. 自力でトラブルシュート • 慣れないうちはエラーの原因がわかりにくい • どれが原因で起こったエラーか順に試す 1. R または他言語のコーディングミス 2. RStudio の不具合 3. Rmd の不具合 • Rmd でのエラーのほとんどは LaTeX (個人的経験則) • R の一部パッケージ, R 以外の言語と相性悪い場合も • コンパイルは R コードで実行できる (render()) • 意図したスタイルにならない -> YAML の競合かも (大雑把 な解説) 64
74. こだわりの強い人へ • 以下も「技術的には可能です」 • Rmd は任意の LaTeX 文書クラスとスタイルを読み込み化 • JLREQ で商業出版レベルの厳格な組版 • 縦書き文書 • 漢文 65
75. LaTeX/HTML の互換性 • 用途が違うので完全一致はナンセンス • 文構造の維持を基準に考える • 互換性のない機能もある • 索引, 用語集 • 詳細はクックブック [4] 6, 7, 9 章 66
76. それから先の話
77. Q.: これだけ知っていれば無敵か? A.: いいえ • これは基本的な操作のみ • デザインにこだわりたい場合もっといろいろなテクニック がある •「入門」は門の場所だけでなく, くぐった後でどこに行けば よいのか示さねばならない • (個人の感想です) 67
78. 便利なテンプレートを提供するパッケージ群: 分野特化系 • bookdown 本来は書籍作成用 • bookdownplus テンプレートの種類拡張 • 楽譜とかも書けるらしい • rticles 欧文の主要学術誌のフォーマットを用意 • jpaRmd 国内の心理学論文フォーマットに対応 • oxforddown オックスフォード大の学位論文用フォーマッ ト (らしい) 68
79. 便利なテンプレートを提供するパッケージ群: HTML 系 • blogdown, rmdformats, govdown • pagedown: いわゆる「CSS 組版」 • flexdashboard: shiny ダッシュボード • distill, tufte: 論文風 Web ページ作成 • gm 楽譜の表示と再生 • xaringan (写輪眼): スライド作成用 HTML 系はあまり詳しくない/ atusy/kazutan/yutanihilation さ んあたりに聞いて 69
80. Rmd 編集に便利な機能を提供するパッケージ • ymlthis YAML の設定をダイアログボックスで • citr 更新してない? • bookdown フォーマットだけでなくアドインも提供 https://gegznav.github.io/addins.rmd/ https://github.com/daattali/addinslist#readme 70
81. Further Readings: 基本 •『再現可能性のすゝめ』[7] • 今回の話が難しかったらこれに沿ってやってみて • Yihui 氏が Naruto の大ファンであることが初めて明か される • R Markdown クックブック [4] •「あれがやりたい!」系の話題はだいたい書いてある • “R Markdown: The Definitive Guide”[3] • より網羅的なマニュアル • “bookdown: Authoring Books and …”[1] • bookdown の使い方 71
82. Further Readings: 特定のトピック特化 • https://rmarkdown.rstudio.com/authoring_pandoc_mar kdown.html • “Dynamic Documents with R and knitr” [2] • または Yihui 氏の web 上のドキュメント (私の翻訳) •『ドキュメント・プレゼンテーション生成』[6] • これはちょっと古いかも (未読) • “Officeverse” 72
83. Further Readings: 応用的 •『自然科学研究のための R 入門』[5] • Rmd を使ってレポートを作るチュートリアル (未読) •『R Markdown 入門』 • rmdja パッケージのドキュメント • 今後大幅修正される可能性大 • 実質個人的なメモ •『今日からできる再現可能な論文執筆』 • 共著研究を想定したワークフローの提案 https://rmarkdown.rstudio.com/authoring_pandoc_markdow n.html#Smart_punctuation 73
84. 最後に: R Markdown で凝ったことをしたい人へ • rmdja が提供するのは「使いやすい初期設定」のみ • 究極的にはバックグラウンドのプログラム理解が必要 •『kazutan の解説スライド』 • PDF: LaTeX • HTML: CSS, JavaScript • 参考文献リストの体裁: BibLaTeX/BibTeX/CSL • pandoc の仕様の理解も必要 • 地道に Pandoc のドキュメントを読む • 地道に Pandoc のテンプレートファイルを解読する •「技術的には可能です」というやつ • もちろん R-wakalang で質問するのもあり 74
85. 参考文献
86. [1] Xie, Yihui (2017).”Bookdown: Authoring Books and Technical Publications with R Markdown”. CRC Press. ISBN: 978-1-138-70010-9. URL: here . [2] Xie, Yihui (2015).”Dynamic Documents with R and Knitr”. CRC Press/Taylor & Francis. ISBN: 978-1-4987-1696-3 . [3] Xie, Yihui, J. J. Allaire, Garrett Grolemund (2019).”R Markdown: The Definitive Guide”. CRC Press, Taylor and Francis Group. ISBN: 978-0-429-78296-1. URL: here . [4] Xie, Yihui, Christophe Dervieux, Emily Riederer (2020).”R Markdown Cookbook”. Taylor and Francis, CRC Press. ISBN: 978-0-367-56383-7 978-0-367-56382-0. URL: here. 翻訳版: https://gedevan-aleksizde.github.io/rmarkdown-cookbook/ . [5] 江口 哲史 (2018).『自然科学研究のための R 入門』 . 共立出版. ISBN: 978-4-320-11244-5 . [6] 金 明哲・高橋 康介 (2014).『ドキュメント・プレゼンテーション生成』 . 共立出版. ISBN: 978-4-320-12372-4 75
87. . [7] 高橋 康介 (2018).『再現可能性のすゝめ RStudio によるデータ解析とレ ポート作成』 . 共立出版. ISBN: 978-4-320-11243-8 76