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

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

View Slide

アジェンダ

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

R Markdown とは

View Slide

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

View Slide

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

View Slide

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

View Slide

R Markdown でなにができるの

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

2. HTML を選ぶ
21

View Slide

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

View Slide

できた!
23

View Slide

Markdown

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

R コードの埋め込み

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

HTML/PDF/DOCX/PPTX への変換

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

• まずはインストール
• テンプレートから選ぶ
40

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

ちょっと発展的な話

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

PDF/LaTeX 関係の応用

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

それから先の話

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

参考文献

View Slide

[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

View Slide

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

View Slide

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

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

S-Katagiri

More Decks by S-Katagiri

Other Decks in Programming

Featured

Transcript