Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

S-Katagiri

April 17, 2021
Tweet

More Decks by S-Katagiri

Other Decks in Programming

Transcript

  1. このスライドの想定読者 1. R を始めたばかりの 初心者 • そもそも R Markdown (RMD)

    って何? という人 2. R Markdown を試したけどうまくできなかった人 • 出力がおかしい/エラーが出る 3. R ユーザーで技術文書や論文を効率的に書きたい人 4. R 以外の言語でそれをやりたい人 • 特に Python と Julia で計算している人 • L A TEX で論文/レポート書のが難しいという人 • Jupyter でレポーティングはやりづらいと感じている人 2
  2. 今回触れる内容 • R Markdown とは • R Markdown でなにができるの •

    RStudio での設定方法 • Markdown の記法 • コードチャンクの説明 • HTML/PDF/WORD への出力 • その他発展的話題 • 時間がなかったら中断します 4
  3. 逆に触れない内容 • R Markdown や knitr の内部処理の詳解 • 個別の事例 •

    XX 学会の論文フォーマットを作りたい • 細かすぎるテクニック • 脱線したらツッコミ入れてください • これらは最後に参考文献の紹介するのみ 5
  4. R Markdown の機能概要 • 文字通り R + Markdown • 簡単な構文でリッチテキスト文書を作成するツール

    • Web サイト, 発表スライド, PDF 形式の文書, レポート等 • R プログラムの埋め込み • R が生成したグラフ・表・計算結果などを文書に直接掲載 • 手動コピペ不要 • rmarkdown パッケージとして提供されている • 機能拡張パッケージも多数 • 内部処理の技術的な話は以下参照 • R Markdown Cookbook 2 章 • kazutan のスライド (これも RMD 製のはず) 8
  5. R Markdown なんて面倒くさいだけでしょ? • Q.: Word やパワポ/Keynote みたいに操作できないんで しょ? •

    WYSYWIG じゃないとわからない • Q.: Overleaf とか LyX 使ってるからいいや • 熟練の LaTeX 使い • Q.: Jupyter で十分じゃないの? • 注: Jupyter は R とかも一応使える 9
  6. Q: Jupyter で十分じゃないの? • A: RMD にも類似した Notebook という機能あり •

    むしろ Jupyter はワードプロセッサ機能が弱い • 例: コードが長すぎてスライドで見切れる 12
  7. RMD で何ができるの? => スライドを作成できる • 今見ているスライド (PDF) も全て R Markdown

    で作成 • L A TEX の beamer を経由 • HTML 形式も可 • xaringan, reveals など 13
  8. RMD で何ができるの? => 本を出版できる •『R Markdown クックブック』 • 翻訳版も R

    Markdown 製 • 商業出版の例 • Hadley et al. “R for Data Science” (『R で始めるデータサイ エンス』) • Hearly “Data Visualization” (『データ可視化入門』) •「技術同人誌」 • https://bookdown.org/ はクローリングサイト 14
  9. 最初に用意するもの • 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
  10. 必要パッケージ • rmarkdown, bookdown, remotes, rmdja パッケージ • Python を使うなら

    reticulate も必要 install.packages(c("rmarkdown", "bookdown", "remotes")) ↪ remotes::install_github( ⌋ "Gedevan-Aleksidze/rmdja") ↪ • LaTeX (PDF が必要な場合) • 実インストールなら tinytex パッケージ 18
  11. Markdown の基本 • Markdown は「マークアップ言語」 • HTML タグとか, テキストを装飾し, 「見出し」

    「段落」など 意味を与える • シンプルなので視覚的に分かりやすい • HTML のようにタグがゴチャゴチャしてない • メモ帳と同じ感覚で使える • 方言が多い点に注意 • 例 GitHub, Slack 24
  12. Markdown の代表的な構文: 行内要素 • 文のスタイルを部分的に変更する 1. 文字のスタイル •「** 太字 **」->

    「太字」 •「* 斜体/イタリック Itacic*」-> 「斜体/イタリック Itacic」3 • **/* の代わりに __/_ も可 • 1 + 1 (バッククオート) でタイプライタ体 1 + 1 •「~~ 打ち消し線 ~~」-> 「打ち消し線」 3日本語は対応してないこともある 25
  13. Markdown の代表的な構文: ブロック要素 (1/2) • テキストのまとまりを定義する 1. 行頭に「#」で見出し # 第

    1 章: 序 • # を増やすと階層が深くなる • このスライドのタイトルは ## 2. 行頭に「*」で箇条書き • 直後のスペース必須 • インデントで階層化可能 • インデントは tab 2 個 (スペース 4 つ) 以上4 3.「1.」or 「a.」で番号付き箇条書き a. これもインデント可 b. 番号を書かなくても自動で調整 4RStudio のデフォルト設定のため 27
  14. Markdown の代表的な構文: ブロック要素 (2/2) 4. コメントアウトは HTML 方式 <!-- ここは出力されない

    --> 5. 見出しブロック (Beamer のみ) これは警告です これは alertblock 環境 • 表を記述することもできるが省略 • わかりにくかったらこのスライドの Rmd ファイルで 見てね 28
  15. コードチャンクと行内コード • R コードの埋め込みは 2 種類 • 独立したブロックとしてのコードチャンク • 表やグラフの埋め込み

    • ソースコードの掲載 • その他複雑な処理 • 他のプログラミング言語も使用可能 • 簡単な 1 文だけのコードの行内埋め込み • 1 + 1 = 2 のように Markdown 内に出力を埋め込める •「2」の部分は実際には `r 1 + 1` と書いている 30
  16. 行内コード • `r <R コード >` • 複雑なコードは書けない • 単文でできることのみ

    • 原則文字の出力のみ • グラフや表は想定されていない • よくある使い方 • 表紙の日付を自動更新 • date: 2021-04-17 31
  17. コードチャンク (1/2) • より複雑なプログラムを書き, 図表を出力できる ```{r, LABEL, echo=T} 1 +

    1 summary(mtcars) ``` • LABEL は自由な名前を付けてよい • 省略してもよい • それ以降は「チャンクオプション」 • 出力結果などを制御する • R の引数と同じように書ける 32
  18. HTML/PDF/DOCX/PPTX への変換 • HTML はすでにやった通り • ドキュメントの出力をかえるには YAML メタデータを書き 換える

    • PDF/DOCX (Word)/PPTX (パワポ) はちょっと複雑 • というか異なるフォーマットの同時出力が複雑 35
  19. 出力フォーマット関数 • 出力フォーマットが主に文書の体裁を決める • 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
  20. PDF は rmdja を使え (1/3) • PDF が難しい理由 1. デフォルト設定が日本語を想定していないため

    2. LaTeX の設定も意識する必要 3. HTML と比べるとデフォルトの見た目が寂しい 4. そもそも用途が HTML と違う • PDF を HTML と両立して日本語出力するため rmdja を 作った • インストール方法は参考資料の通り 39
  21. PDF は rmdja を使え (3/3) • もともとはスライド作成用だった • 現在は HTML/PDF

    の出力を両立できること目指す • 現在は以下の 4 種類の PDF フォーマット 1. 書籍 2. 論文 3. スライド 4. 縦書き 41
  22. Word への出力 (2/2) • おすすめ • (たまにうまく行かないことがある) output: officedown::rdocx_document: base_format:

    bookdown::word_document2 toc: true tables: caption: pre: " 表" plots: style: aling: center caption: pre: " 図" 43
  23. Word への出力 (3/2) • (余計なお世話?) 本当に Word を使う必要がある? • 提出物は

    HTML や PDF じゃダメ? • 共著者が Word しか使えない? • RMD は PDF を直接作れます 44
  24. YAML について • title:, author, output: は YAML メタデータと呼ばれ る

    • カスタマイズに重要 • 細かい話になるので冒頭の資料を見てください 48
  25. 相互参照 • 図・表・セクション見出し, 数式, 引用文献を参照したい •「図 1 が分析結果である」 「2 章を見よ」など文書内の参照

    • 番号やハイパーリンクを自分で書くと後で修正するのが大 変 • bookdown 系のフォーマットで実現 • rmarkdown 単体では不可 • 末尾に 2 と付くフォーマット 49
  26. 画像への相互参照の実例 • 図1 を見よ! • ggplot2 ももちろん掲載できる {r, image1, fig.cap="

    図への相互参照"} knitr::include_graphics("img/logo.png") 図 1: 図への相互参照 51
  27. 表への相互参照 • データフレームをそのまま表にできる • チャンクラベルを指定 • knitr::kable(df, caption="...") が表のスタイル を自動生成

    • チャンクオプションではないことに注意 • \@ref(tab: チャンクラベル) というふうに指定 52
  28. 表への相互参照の実例 • 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
  29. 相互参照のさらなる応用 • 複数の図表を 1 つにまとめることも可能 • 詳細は Cookbook • 引用文献のスタイル変更

    • PDF は BibLaTeX (.bbx) • HTML は CSL (.csl) • (u)pBibTeX (.bst) はちょっとややこしい • 論文フォーマットは LaTeX に依存している事が多いので一 般化は難しい 54
  30. R 以外の言語 • コードチャンクには R 以外の言語も使える • r を別の言語に書き換える •

    stan コードを直接書くことも可能 • Python, Julia も同様に使える • それ以外は別のチャンクに設定・変数を持ち越せない • チャンクごとにプログラムを呼び出しているため • Python 使用例: 例のスライド • 新規登録も可能 • 詳細はクックブック 15 章 55
  31. Python のコードチャンク • reticulate パッケージで使用可能 • RStudio 1.4 からかなり使いやすくなった •

    コードチャンクの r の部分を python に import numpy as np np.array([1, 1]) array([1, 1]) 56
  32. Julia のコードチャンク • JuliaCall パッケージで使用可能 • https://julialang.org/downloads/ • まだ不安定なところが多い •

    古いバージョンにする必要 • Gadfly が使えない? • 画像の保存は手動にしたほうが安定? • 参考: Remark.jl という Julia パッケージあり • remark.js ベース 57
  33. Julia 使用例 (失敗!!) • 要 Julia 本体 & JuliaCall &

    環境設定 using Plots gr() Plots.GRBackend() plot(Plots.fakedata(50,5),w=3) Plot{Plots.GRBackend() n=5} 58
  34. PDF/LaTeX 周りの予備知識 • PDF は LaTeX を使用して生成 • いくつかのエンジンがある •

    文書全体のスタイルは主に LaTeX の文書クラスファイル で定義 • bxjsarticle, ltjsarticle, beamer, etc. 59
  35. どの 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
  36. Rmd のサポート外の処理 • 以下を要求する国内学会公式フォーマット • (u)pL A TEX 前提の .cls/.sty

    • (u)pBIBTEX 前提の .bst • いずれもデフォルトの Rmd では非対応 • 日本独自開発の処理系のため • 要 tinytex のエミュレーション無効化 • 以下をチャンクのどこかに書く options(tinytex.latexmk.emulation = F) • LaTeX エラーのデバッグが少しやりづらくなる 62
  37. 自力でトラブルシュート • 慣れないうちはエラーの原因がわかりにくい • どれが原因で起こったエラーか順に試す 1. R または他言語のコーディングミス 2. RStudio

    の不具合 3. Rmd の不具合 • Rmd でのエラーのほとんどは LaTeX (個人的経験則) • R の一部パッケージ, R 以外の言語と相性悪い場合も • コンパイルは R コードで実行できる (render()) • 意図したスタイルにならない -> YAML の競合かも (大雑把 な解説) 64
  38. 便利なテンプレートを提供するパッケージ群: 分野特化系 • bookdown 本来は書籍作成用 • bookdownplus テンプレートの種類拡張 • 楽譜とかも書けるらしい

    • rticles 欧文の主要学術誌のフォーマットを用意 • jpaRmd 国内の心理学論文フォーマットに対応 • oxforddown オックスフォード大の学位論文用フォーマッ ト (らしい) 68
  39. 便利なテンプレートを提供するパッケージ群: HTML 系 • blogdown, rmdformats, govdown • pagedown: いわゆる「CSS

    組版」 • flexdashboard: shiny ダッシュボード • distill, tufte: 論文風 Web ページ作成 • gm 楽譜の表示と再生 • xaringan (写輪眼): スライド作成用 HTML 系はあまり詳しくない/ atusy/kazutan/yutanihilation さ んあたりに聞いて 69
  40. Rmd 編集に便利な機能を提供するパッケージ • ymlthis YAML の設定をダイアログボックスで • citr 更新してない? •

    bookdown フォーマットだけでなくアドインも提供 https://gegznav.github.io/addins.rmd/ https://github.com/daattali/addinslist#readme 70
  41. Further Readings: 基本 •『再現可能性のすゝめ』[7] • 今回の話が難しかったらこれに沿ってやってみて • Yihui 氏が Naruto

    の大ファンであることが初めて明か される • R Markdown クックブック [4] •「あれがやりたい!」系の話題はだいたい書いてある • “R Markdown: The Definitive Guide”[3] • より網羅的なマニュアル • “bookdown: Authoring Books and …”[1] • bookdown の使い方 71
  42. Further Readings: 特定のトピック特化 • https://rmarkdown.rstudio.com/authoring_pandoc_mar kdown.html • “Dynamic Documents with

    R and knitr” [2] • または Yihui 氏の web 上のドキュメント (私の翻訳) •『ドキュメント・プレゼンテーション生成』[6] • これはちょっと古いかも (未読) • “Officeverse” 72
  43. Further Readings: 応用的 •『自然科学研究のための R 入門』[5] • Rmd を使ってレポートを作るチュートリアル (未読)

    •『R Markdown 入門』 • rmdja パッケージのドキュメント • 今後大幅修正される可能性大 • 実質個人的なメモ •『今日からできる再現可能な論文執筆』 • 共著研究を想定したワークフローの提案 https://rmarkdown.rstudio.com/authoring_pandoc_markdow n.html#Smart_punctuation 73
  44. 最後に: R Markdown で凝ったことをしたい人へ • rmdja が提供するのは「使いやすい初期設定」のみ • 究極的にはバックグラウンドのプログラム理解が必要 •『kazutan

    の解説スライド』 • PDF: LaTeX • HTML: CSS, JavaScript • 参考文献リストの体裁: BibLaTeX/BibTeX/CSL • pandoc の仕様の理解も必要 • 地道に Pandoc のドキュメントを読む • 地道に Pandoc のテンプレートファイルを解読する •「技術的には可能です」というやつ • もちろん R-wakalang で質問するのもあり 74
  45. [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