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

Slide 1

Slide 1 text

R ユーザー以外も知るべき R Markdown 入門 2021 年版 Katagiri, Satoshi 2021/04/17, Tokyo.R #91 1

Slide 2

Slide 2 text

アジェンダ

Slide 3

Slide 3 text

このスライドの想定読者 1. R を始めたばかりの初心者 • そもそも R Markdown (RMD) って何? という人 2. R Markdown を試したけどうまくできなかった人 • 出力がおかしい/エラーが出る 3. R ユーザーで技術文書や論文を効率的に書きたい人 4. R 以外の言語でそれをやりたい人 • 特に Python と Julia で計算している人 • L A TEX で論文/レポート書のが難しいという人 • Jupyter でレポーティングはやりづらいと感じている人 2

Slide 4

Slide 4 text

(自己紹介) この登壇しているオジサンはそんなに詳しいの? • fontregisterer 作成者 • “R Markdown Cookbook” 翻訳者 3

Slide 5

Slide 5 text

今回触れる内容 • R Markdown とは • R Markdown でなにができるの • RStudio での設定方法 • Markdown の記法 • コードチャンクの説明 • HTML/PDF/WORD への出力 • その他発展的話題 • 時間がなかったら中断します 4

Slide 6

Slide 6 text

逆に触れない内容 • R Markdown や knitr の内部処理の詳解 • 個別の事例 • XX 学会の論文フォーマットを作りたい • 細かすぎるテクニック • 脱線したらツッコミ入れてください • これらは最後に参考文献の紹介するのみ 5

Slide 7

Slide 7 text

R Markdown とは

Slide 8

Slide 8 text

こんな経験はありませんか? (1/2) 1. 実験結果からグラフ画像を作成し Word/LaTeX 原稿に貼り付け 2. 修正が必要になったので再作成して貼り付け 3. とおもったら原稿に反映し忘れ 4. そして……死 6

Slide 9

Slide 9 text

こんな経験はありませんか? (2/2) 1. 数字を L A TEX のかっこいい表にしたい 2. L A TEX 構文が複雑過ぎる 3. そして……死 7

Slide 10

Slide 10 text

R Markdown の機能概要 • 文字通り R + Markdown • 簡単な構文でリッチテキスト文書を作成するツール • Web サイト, 発表スライド, PDF 形式の文書, レポート等 • R プログラムの埋め込み • R が生成したグラフ・表・計算結果などを文書に直接掲載 • 手動コピペ不要 • rmarkdown パッケージとして提供されている • 機能拡張パッケージも多数 • 内部処理の技術的な話は以下参照 • R Markdown Cookbook 2 章 • kazutan のスライド (これも RMD 製のはず) 8

Slide 11

Slide 11 text

R Markdown でなにができるの

Slide 12

Slide 12 text

R Markdown なんて面倒くさいだけでしょ? • Q.: Word やパワポ/Keynote みたいに操作できないんでしょ? • WYSYWIG じゃないとわからない • Q.: Overleaf とか LyX 使ってるからいいや • 熟練の LaTeX 使い • Q.: Jupyter で十分じゃないの? • 注: Jupyter は R とかも一応使える 9

Slide 13

Slide 13 text

Q.: Word やパワポ/Keynote みたいにできないんでしょ? A.: ビジュアルエディタモードあるよ 10

Slide 14

Slide 14 text

Q: Overleaf とか LyX 使ってるからいいや A.: 毎回使う LaTeX コマンドは数式だけでしょ? 11

Slide 15

Slide 15 text

Q: Jupyter で十分じゃないの? • A: RMD にも類似した Notebook という機能あり • むしろ Jupyter はワードプロセッサ機能が弱い • 例: コードが長すぎてスライドで見切れる 12

Slide 16

Slide 16 text

RMD で何ができるの? => スライドを作成できる • 今見ているスライド (PDF) も全て R Markdown で作成 • L A TEX の beamer を経由 • HTML 形式も可 • xaringan, reveals など 13

Slide 17

Slide 17 text

RMD で何ができるの? => 本を出版できる •『R Markdown クックブック』 • 翻訳版も R Markdown 製 • 商業出版の例 • Hadley et al. “R for Data Science” (『R で始めるデータサイエンス』) • Hearly “Data Visualization” (『データ可視化入門』) •「技術同人誌」 • https://bookdown.org/ はクローリングサイト 14

Slide 18

Slide 18 text

RMD で何ができるの? => 料理書が書ける 15

Slide 19

Slide 19 text

R Markdown のハンズオン風チュートリアル

Slide 20

Slide 20 text

• 以降はチュートリアル風に進行 • 徐々に高度な機能を使いこなせるようになりましょう 16

Slide 21

Slide 21 text

最初に用意するもの • 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

Slide 22

Slide 22 text

必要パッケージ • rmarkdown, bookdown, remotes, rmdja パッケージ • Python を使うなら reticulate も必要 install.packages(c("rmarkdown", "bookdown", "remotes")) ↪ remotes::install_github( ⌋ "Gedevan-Aleksidze/rmdja") ↪ • LaTeX (PDF が必要な場合) • 実インストールなら tinytex パッケージ 18

Slide 23

Slide 23 text

パッケージ等のダウンロード • ここに補足資料を上げました. • ここにソースがあります. • rmd-setup.R を参考にしてください. 19

Slide 24

Slide 24 text

R Markdown の新規作成 (1/3) 1. R Markdown… を選ぶ 20

Slide 25

Slide 25 text

R Markdown の新規作成 (2/3) 2. HTML を選ぶ 21

Slide 26

Slide 26 text

R Markdown の新規作成 (3/3) 3. title:, author: を書き換える 4. 適当なファイル名で保存 5. 上の “Knit” ボタンでコンパイル 22

Slide 27

Slide 27 text

できた! 23

Slide 28

Slide 28 text

Markdown

Slide 29

Slide 29 text

Markdown の基本 • Markdown は「マークアップ言語」 • HTML タグとか, テキストを装飾し, 「見出し」「段落」など意味を与える • シンプルなので視覚的に分かりやすい • HTML のようにタグがゴチャゴチャしてない • メモ帳と同じ感覚で使える • 方言が多い点に注意 • 例 GitHub, Slack 24

Slide 30

Slide 30 text

Markdown の代表的な構文: 行内要素 • 文のスタイルを部分的に変更する 1. 文字のスタイル •「** 太字 **」-> 「太字」 •「* 斜体/イタリック Itacic*」-> 「斜体/イタリック Itacic」3 • **/* の代わりに __/_ も可 • 1 + 1 (バッククオート) でタイプライタ体 1 + 1 •「~~ 打ち消し線 ~~」-> 「打ち消し線」 3日本語は対応してないこともある 25

Slide 31

Slide 31 text

Markdown の代表的な構文: 行内数式 2. LaTeX 数式 •「$f(x)$」-> 「𝑓(𝑥)」 3. 独立行なら $$ で囲む • または, align など直接 LaTeX を書く 26

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

Markdown の代表的な構文: ブロック要素 (2/2) 4. コメントアウトは HTML 方式 5. 見出しブロック (Beamer のみ) これは警告ですこれは alertblock 環境 • 表を記述することもできるが省略 • わかりにくかったらこのスライドの Rmd ファイルで見てね 28

Slide 34

Slide 34 text

Visual Markdown Editor • どうしても苦手なら Word のような編集モードあり • 右上のコンパスマークをクリック 29

Slide 35

Slide 35 text

R コードの埋め込み

Slide 36

Slide 36 text

コードチャンクと行内コード • R コードの埋め込みは 2 種類 • 独立したブロックとしてのコードチャンク • 表やグラフの埋め込み • ソースコードの掲載 • その他複雑な処理 • 他のプログラミング言語も使用可能 • 簡単な 1 文だけのコードの行内埋め込み • 1 + 1 = 2 のように Markdown 内に出力を埋め込める •「2」の部分は実際には `r 1 + 1` と書いている 30

Slide 37

Slide 37 text

行内コード • `r ` • 複雑なコードは書けない • 単文でできることのみ • 原則文字の出力のみ • グラフや表は想定されていない • よくある使い方 • 表紙の日付を自動更新 • date: 2021-04-17 31

Slide 38

Slide 38 text

コードチャンク (1/2) • より複雑なプログラムを書き, 図表を出力できる ```{r, LABEL, echo=T} 1 + 1 summary(mtcars) ``` • LABEL は自由な名前を付けてよい • 省略してもよい • それ以降は「チャンクオプション」 • 出力結果などを制御する • R の引数と同じように書ける 32

Slide 39

Slide 39 text

コードチャンク (2/2) • 作業中の実行も可能 • 右の矢印をクリック • R notebook を使うのもあり 33

Slide 40

Slide 40 text

よく使うチャンクオプション • echo: コードを表示するかどうか • スライドでは邪魔なのでよく非表示にする • eval=F: コードを実行しない • コードだけ見せたい時に • fig.cap="": 図のキャプション • 詳細はこことか参照 34

Slide 41

Slide 41 text

HTML/PDF/DOCX/PPTX への変換

Slide 42

Slide 42 text

HTML/PDF/DOCX/PPTX への変換 • HTML はすでにやった通り • ドキュメントの出力をかえるには YAML メタデータを書き換える • PDF/DOCX (Word)/PPTX (パワポ) はちょっと複雑 • というか異なるフォーマットの同時出力が複雑 35

Slide 43

Slide 43 text

出力フォーマット関数 • 出力フォーマットが主に文書の体裁を決める • 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

Slide 44

Slide 44 text

PDF の設定最小限の設定はこうだが… output: pdf_document: latex_engine: lualatex documentclass: ltjsarticle classoption: haranoaji 37

Slide 45

Slide 45 text

まずうまくいかない • 実際に使うといろいろとボロが出ます • 打ち消し線を使うとエラー • 参考文献リストが変 • 存在しないフォントは使えない 38

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

PDF は rmdja を使え (2/3) • まずはインストール • テンプレートから選ぶ 40

Slide 48

Slide 48 text

PDF は rmdja を使え (3/3) • もともとはスライド作成用だった • 現在は HTML/PDF の出力を両立できること目指す • 現在は以下の 4 種類の PDF フォーマット 1. 書籍 2. 論文 3. スライド 4. 縦書き 41

Slide 49

Slide 49 text

Word への出力 (1/2) • 最低限の設定 output: word_document 42

Slide 50

Slide 50 text

Word への出力 (2/2) • おすすめ • (たまにうまく行かないことがある) output: officedown::rdocx_document: base_format: bookdown::word_document2 toc: true tables: caption: pre: " 表" plots: style: aling: center caption: pre: " 図" 43

Slide 51

Slide 51 text

Word への出力 (3/2) • (余計なお世話?) 本当に Word を使う必要がある? • 提出物は HTML や PDF じゃダメ? • 共著者が Word しか使えない? • RMD は PDF を直接作れます 44

Slide 52

Slide 52 text

パワーポイントへの出力 (PPTX) • あんまり使ってないけどたぶんいける output: powerpoint_presentation output: officedown::rpptx_presentation 45

Slide 53

Slide 53 text

スライドへの出力 (PDF) • 最も簡単な方法 • rmdja パッケージのほうが便利です (たぶん) output: beamer_presentation: latex_engine: lualatex mainfont: haranoaji 46

Slide 54

Slide 54 text

Q.: スライドからはみ出すんだけど? • A.: 慣れましょう • 詰め込み過ぎは良くないです • この発表みたいになります 47

Slide 55

Slide 55 text

YAML について • title:, author, output: は YAML メタデータと呼ばれる • カスタマイズに重要 • 細かい話になるので冒頭の資料を見てください 48

Slide 56

Slide 56 text

ちょっと発展的な話

Slide 57

Slide 57 text

相互参照 • 図・表・セクション見出し, 数式, 引用文献を参照したい •「図 1 が分析結果である」「2 章を見よ」など文書内の参照 • 番号やハイパーリンクを自分で書くと後で修正するのが大変 • bookdown 系のフォーマットで実現 • rmarkdown 単体では不可 • 末尾に 2 と付くフォーマット 49

Slide 58

Slide 58 text

図・画像への相互参照 • コードチャンクへ参照する形で実現 • 画像ファイルは knitr::include_graphics() 1. コードチャンクのラベルを書く 2. fig.cap=" キャプション" オプションでキャプションを書く 3. \@ref(fig: チャンクラベル) で参照 50

Slide 59

Slide 59 text

画像への相互参照の実例 • 図1 を見よ! • ggplot2 ももちろん掲載できる {r, image1, fig.cap=" 図への相互参照"} knitr::include_graphics("img/logo.png") 図 1: 図への相互参照 51

Slide 60

Slide 60 text

表への相互参照 • データフレームをそのまま表にできる • チャンクラベルを指定 • knitr::kable(df, caption="...") が表のスタイルを自動生成 • チャンクオプションではないことに注意 • \@ref(tab: チャンクラベル) というふうに指定 52

Slide 61

Slide 61 text

表への相互参照の実例 • 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

Slide 62

Slide 62 text

相互参照のさらなる応用 • 複数の図表を 1 つにまとめることも可能 • 詳細は Cookbook • 引用文献のスタイル変更 • PDF は BibLaTeX (.bbx) • HTML は CSL (.csl) • (u)pBibTeX (.bst) はちょっとややこしい • 論文フォーマットは LaTeX に依存している事が多いので一般化は難しい 54

Slide 63

Slide 63 text

R 以外の言語 • コードチャンクには R 以外の言語も使える • r を別の言語に書き換える • stan コードを直接書くことも可能 • Python, Julia も同様に使える • それ以外は別のチャンクに設定・変数を持ち越せない • チャンクごとにプログラムを呼び出しているため • Python 使用例: 例のスライド • 新規登録も可能 • 詳細はクックブック 15 章 55

Slide 64

Slide 64 text

Python のコードチャンク • reticulate パッケージで使用可能 • RStudio 1.4 からかなり使いやすくなった • コードチャンクの r の部分を python に import numpy as np np.array([1, 1]) array([1, 1]) 56

Slide 65

Slide 65 text

Julia のコードチャンク • JuliaCall パッケージで使用可能 • https://julialang.org/downloads/ • まだ不安定なところが多い • 古いバージョンにする必要 • Gadfly が使えない? • 画像の保存は手動にしたほうが安定? • 参考: Remark.jl という Julia パッケージあり • remark.js ベース 57

Slide 66

Slide 66 text

Julia 使用例 (失敗!!) • 要 Julia 本体 & JuliaCall & 環境設定 using Plots gr() Plots.GRBackend() plot(Plots.fakedata(50,5),w=3) Plot{Plots.GRBackend() n=5} 58

Slide 67

Slide 67 text

PDF/LaTeX 関係の応用

Slide 68

Slide 68 text

PDF/LaTeX 周りの予備知識 • PDF は LaTeX を使用して生成 • いくつかのエンジンがある • 文書全体のスタイルは主に LaTeX の文書クラスファイルで定義 • bxjsarticle, ltjsarticle, beamer, etc. 59

Slide 69

Slide 69 text

どの 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

Slide 70

Slide 70 text

以降は詳しい人 or 詳しくなることを強いられている人向け 61

Slide 71

Slide 71 text

Rmd のサポート外の処理 • 以下を要求する国内学会公式フォーマット • (u)pL A TEX 前提の .cls/.sty • (u)pBIBTEX 前提の .bst • いずれもデフォルトの Rmd では非対応 • 日本独自開発の処理系のため • 要 tinytex のエミュレーション無効化 • 以下をチャンクのどこかに書く options(tinytex.latexmk.emulation = F) • LaTeX エラーのデバッグが少しやりづらくなる 62

Slide 72

Slide 72 text

論文フォーマットは決まってるけど LaTeX テンプレがない場合は? A.: Good Luck! • .cls, .bbx の自作 • jpaRmd を参考に全部 R で処理 63

Slide 73

Slide 73 text

自力でトラブルシュート • 慣れないうちはエラーの原因がわかりにくい • どれが原因で起こったエラーか順に試す 1. R または他言語のコーディングミス 2. RStudio の不具合 3. Rmd の不具合 • Rmd でのエラーのほとんどは LaTeX (個人的経験則) • R の一部パッケージ, R 以外の言語と相性悪い場合も • コンパイルは R コードで実行できる (render()) • 意図したスタイルにならない -> YAML の競合かも (大雑把な解説) 64

Slide 74

Slide 74 text

こだわりの強い人へ • 以下も「技術的には可能です」 • Rmd は任意の LaTeX 文書クラスとスタイルを読み込み化 • JLREQ で商業出版レベルの厳格な組版 • 縦書き文書 • 漢文 65

Slide 75

Slide 75 text

LaTeX/HTML の互換性 • 用途が違うので完全一致はナンセンス • 文構造の維持を基準に考える • 互換性のない機能もある • 索引, 用語集 • 詳細はクックブック [4] 6, 7, 9 章 66

Slide 76

Slide 76 text

それから先の話

Slide 77

Slide 77 text

Q.: これだけ知っていれば無敵か? A.: いいえ • これは基本的な操作のみ • デザインにこだわりたい場合もっといろいろなテクニックがある •「入門」は門の場所だけでなく, くぐった後でどこに行けばよいのか示さねばならない • (個人の感想です) 67

Slide 78

Slide 78 text

便利なテンプレートを提供するパッケージ群: 分野特化系 • bookdown 本来は書籍作成用 • bookdownplus テンプレートの種類拡張 • 楽譜とかも書けるらしい • rticles 欧文の主要学術誌のフォーマットを用意 • jpaRmd 国内の心理学論文フォーマットに対応 • oxforddown オックスフォード大の学位論文用フォーマット (らしい) 68

Slide 79

Slide 79 text

便利なテンプレートを提供するパッケージ群: HTML 系 • blogdown, rmdformats, govdown • pagedown: いわゆる「CSS 組版」 • flexdashboard: shiny ダッシュボード • distill, tufte: 論文風 Web ページ作成 • gm 楽譜の表示と再生 • xaringan (写輪眼): スライド作成用 HTML 系はあまり詳しくない/ atusy/kazutan/yutanihilation さんあたりに聞いて 69

Slide 80

Slide 80 text

Rmd 編集に便利な機能を提供するパッケージ • ymlthis YAML の設定をダイアログボックスで • citr 更新してない? • bookdown フォーマットだけでなくアドインも提供 https://gegznav.github.io/addins.rmd/ https://github.com/daattali/addinslist#readme 70

Slide 81

Slide 81 text

Further Readings: 基本 •『再現可能性のすゝめ』[7] • 今回の話が難しかったらこれに沿ってやってみて • Yihui 氏が Naruto の大ファンであることが初めて明かされる • R Markdown クックブック [4] •「あれがやりたい!」系の話題はだいたい書いてある • “R Markdown: The Definitive Guide”[3] • より網羅的なマニュアル • “bookdown: Authoring Books and …”[1] • bookdown の使い方 71

Slide 82

Slide 82 text

Further Readings: 特定のトピック特化 • https://rmarkdown.rstudio.com/authoring_pandoc_mar kdown.html • “Dynamic Documents with R and knitr” [2] • または Yihui 氏の web 上のドキュメント (私の翻訳) •『ドキュメント・プレゼンテーション生成』[6] • これはちょっと古いかも (未読) • “Officeverse” 72

Slide 83

Slide 83 text

Further Readings: 応用的 •『自然科学研究のための R 入門』[5] • Rmd を使ってレポートを作るチュートリアル (未読) •『R Markdown 入門』 • rmdja パッケージのドキュメント • 今後大幅修正される可能性大 • 実質個人的なメモ •『今日からできる再現可能な論文執筆』 • 共著研究を想定したワークフローの提案 https://rmarkdown.rstudio.com/authoring_pandoc_markdow n.html#Smart_punctuation 73

Slide 84

Slide 84 text

最後に: R Markdown で凝ったことをしたい人へ • rmdja が提供するのは「使いやすい初期設定」のみ • 究極的にはバックグラウンドのプログラム理解が必要 •『kazutan の解説スライド』 • PDF: LaTeX • HTML: CSS, JavaScript • 参考文献リストの体裁: BibLaTeX/BibTeX/CSL • pandoc の仕様の理解も必要 • 地道に Pandoc のドキュメントを読む • 地道に Pandoc のテンプレートファイルを解読する •「技術的には可能です」というやつ • もちろん R-wakalang で質問するのもあり 74

Slide 85

Slide 85 text

参考文献

Slide 86

Slide 86 text

[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

Slide 87

Slide 87 text

. [7] 高橋康介 (2018).『再現可能性のすゝめ RStudio によるデータ解析とレポート作成』 . 共立出版. ISBN: 978-4-320-11243-8 76