最近のR Markdown関連のお話

Hijiyama.R #5

前田和寛(@kazutan)

2016/10/15

はじめに

今回の内容

R Markdownの最新の機能
R notebook
flexdashboardとその活用例
pkgdownパッケージ
その他テンプレート

注意事項

以下の事項を前提としています:

RStudio Preview版(ver1.0.39で動作確認)
rmarkdown最新版(ver1.1以降)
その他紹介するパッケージはCRAN最新版，あるいはGithub版

session info

devtools::session_info()$platform

##  setting  value                       
##  version  R version 3.3.1 (2016-06-21)
##  system   x86_64, linux-gnu           
##  ui       X11                         
##  language (EN)                        
##  collate  en_US.UTF-8                 
##  tz       <NA>                        
##  date     2016-10-15

devtools::session_info()$packages

##  package    * version    date       source                            
##  assertthat   0.1        2013-12-06 CRAN (R 3.3.0)                    
##  devtools     1.12.0     2016-06-24 CRAN (R 3.3.1)                    
##  digest       0.6.10     2016-08-02 cran (@0.6.10)                    
##  evaluate     0.10       2016-10-11 cran (@0.10)                      
##  formatR      1.4        2016-05-09 CRAN (R 3.3.0)                    
##  htmltools    0.3.5      2016-03-21 CRAN (R 3.3.0)                    
##  knitr        1.14       2016-08-13 CRAN (R 3.3.1)                    
##  magrittr     1.5        2014-11-22 CRAN (R 3.3.0)                    
##  memoise      1.0.0      2016-01-29 CRAN (R 3.3.0)                    
##  Rcpp         0.12.7     2016-09-05 cran (@0.12.7)                    
##  revealjs     0.7        2016-08-01 CRAN (R 3.3.1)                    
##  rmarkdown    1.1        2016-10-14 Github (rstudio/rmarkdown@3ec6dd6)
##  rstudioapi   0.6        2016-06-27 cran (@0.6)                       
##  stringi      1.1.2      2016-10-01 cran (@1.1.2)                     
##  stringr      1.1.0.9000 2016-10-14 Github (hadley/stringr@3fa6840)   
##  tibble       1.2        2016-08-26 cran (@1.2)                       
##  withr        1.0.1      2016-02-04 CRAN (R 3.3.0)                    
##  yaml         2.1.13     2014-06-12 CRAN (R 3.3.0)

R Markdownの最新機能

GUIまわりが進化

初期の頃と比較するとかなり充実
- ざっくりと把握したいならR Markdownのチートシート参照

数式がインラインで表示

数式がいちいちレンダリングせずに結果が表示されるように
- インラインでもOK

画像をインラインで表示

mdで画像を差し込むと自動的に表示
- いちいち表示されるかどうかレンダリングしなくてすむ

パラメータ機能に対応

yaml部分に以下のように記述
```
params:
  hoge: 100
  fuga: "kosaki"
```
設定した値はparams$(パラメータ名)という読み込み専用listに格納
- 同一ドキュメント内で自由に使用可能
- render("aaa.Rmd", params=list(hoge=15, fuga="good"))と渡すことも可能
詳細は本家サイトの解説を参照

多言語に対応

R言語以外でも,チャンクで処理することが可能
- Python
- SQL
- Bash
- Rcpp
- Stan etc…

以下のように記述

```{bash}
cat flights1.csv flights2.csv flights3.csv > flights.csv
```

こんなことも可能です

```{stan, output.var="ex1"}
parameters {
  real y[2]; 
} 
model {
  y[1] ~ normal(0, 1);
  y[2] ~ double_exponential(0, 2);
}
```

```{r}
library(rstan)
fit <- sampling(ex1) 
print(fit)
```

注意点

それぞれの実行環境が必要
- PythonだったりSQLとか
- またそれぞれでうまく行かない場合もあり
以下のドキュメントを一読してからお試しを
- knitr Language Engines
- Language engines: Use other languages in knitr

R Notebook

R Notebookとは

R Markdownのoutputのひとつ
- 2016年夏にRStudioのPreview版に実装
- 公式ドキュメントは以下のリンク:
  http://rmarkdown.rstudio.com/r_notebooks.html
Rmd編集ウィンドウで出力が表示可能
.nb.htmlという形式で出力

こんな感じです:

R Notebook

使ってみよう

RStudioのPreview版を準備
{rmarkdown}の最新版を入れる
“File - R Notebook”を選択
Rmdを編集し、チャンクのコードを実行

基本はRmd

中身の作り方はRmdと同一
- 基本html_documentで考えてください
- 冒頭のyamlで設定できる項目については、?rmarkdown::html_notebookを参照
注意点は後述

出力は`.nb.html`形式

R Notebook HTML Formatという形式とのこと
一見はいつものRmd出力のhtmlと同一だけど…
- 内部はかなり違う
- 詳しくは以下のドキュメント参照
  http://rmarkdown.rstudio.com/r_notebook_format.html
- この中にRmdの内容が組み込まれている

特色

チャンクコードを実行すると、Consoleに送られる
- その内容を現在の環境で実行して、チャンクの下に出してくる感じ
もちろんPlotsも同じ
- 編集ウィンドウに出てくるときは、自動的に黄金比で出てくる
- ウィンドウの横幅が変化すると、そのたびに再度(実行してるの全て)出力してくる

R Notebook Tips 1

ショートカットキー

Ctrl(Cmd) + Shift + Enter
- 今いるチャンク内のコードを実行
- 多分これは必須ショートカット
Ctrl(Cmd) + Alt + I
- Rチャンクを挿入
- 事前に選択してショートカットすると、そこが独立してRチャンクに
Ctrl(Cmd) + Shift + K
- Preview(Knit)を実行
- ドキュメント内のチャンクはすべて再度実行される

R Notebook Tips 2

出力の全消去・折りたたみ・展開

出力の全消去
1. 編集ウィンドウの上にある歯車ボタンをクリック
2. “Clear All Output”でクリア
出力の全折りたたみ
1. 編集ウィンドウの上にある歯車ボタンをクリック
2. “Collapse All Output”で全部折りたたみ
出力の全展開
1. 編集ウィンドウの上にある歯車ボタン
2. “Expand All Output”で全部展開

R Notebook Tips 3

Rmdファイルの復元

.nb.htmlファイルには.Rmdが組み込まれている
もしRmdファイルがなくても復元可能
1. ファイルウィンドウで.nb.htmlをクリック
2. “Open in Editor”を選択
3. 該当RmdがなくてもRmdファイルが作成され開く!!

注意点

`self_contained: FALSE`はNG

いろいろ試したのですが、うまくいきません
- helpには「やらんでね」と名言はなかったけどそういう趣旨の文言があった
- というより、この機能の趣旨にあいません

“Rmd Download”の罠

.nb.htmlで出したドキュメントの右側に“Code”というボタンが
- 全コードの表示・非表示を選択可能
- この中にDownload RmdをクリックするとDLできる
日本語がうまくいかない
- これできたら最高なので、誰か助けてください

中途半端な実行

“Ctrl + Enter”で一行ごとで実行可能
でも、中途飯場に実行してると想定外のことになるかも
- Rチャンクの右上に“Run All Chunks Above”というボタンを!

結局、使いどころは?

メモを取りながら作業するとき
- まだカチッとしたドキュメントを作る段階じゃない、でもある程度は…
- outputを他のに切り替えれば、すぐに他の形式に出せるしね
Rmdをtear(別ウインドウで切り離す)して単体で作業
- 画面半分くらいで十分なので、の垢離半分は別の作業できる
Rmdファイルもセットで配布させたい時
- .nb.htmlのファイルさえあれば復元可能なので

参考資料

flexdashboardパッケージ

ダッシュボードとは?

色々な情報をぱっと見で理解できるように集約したもの
- 車の運転席のダッシュボードをイメージしてもらえれば
- グラフや表，文字などをわかりやすく配置
データを集約して表示するのに便利
- あるトピックについて，様々な角度から可視化
- 相手に情報を伝えやすい!

flexdashboardパッケージ

R Markdownの拡張パッケージ
- Rmdファイル単体でダッシュボードを作成可能
レイアウトが簡単
- row(行)とcolumn(列)によるレイアウトシステム
- モバイル対応(フレキシブルデザイン)
レイアウト設定以外は通常のRmd
- 動的なコンテンツ(htmlwidgets系)も作成可能
- shinyもOK

使ってみよう

CRANから

install.packages("flexdashboard")

GitHub版から

devtools::install_github("rstudio/flexdashboard")

R Markdownを新規作成
“From Template”を選択
“Flex Dashboard”を選択
OKをクリック

こんなRmdができます:

そのままknitするとこうなります:

冒頭のyamlについて

title: "Untitled"
output: 
  flexdashboard::flex_dashboard:
    orientation: columns
    vertical_layout: fill

title: ページのタイトル(navbarにあるやつ)
orientation: 列方向(columns)で区切るか行方向(rows)で区切るか
- 見出し要素Lv2の方向を決定します
vertical_layout: グラフを範囲内に収める(“fill”)かスクロール(“scroll”)するか
social: 要するに“共有”ボタンをつけるかどうか

他にもありますが，?flexdashboard::flex_dashboardでヘルプを参照してください

レイアウトと見出しレベルについて

見出しレベル1: ページ区切り

見出しレベル1(h1)があると，ページ区切りとして機能
- 公式やサンプルでは====を使った方法で解説
```
ページタイトル
====
```
- でもいつもの#でもOK
```
# ページタイトル
```
この文字は表示されません
- 識別用に利用されます

見出しレベル2: 親ブロックの区切り

見出しレベル2(h2)があると，その数だけページ内を区切ります
- 公式やサンプルでは----を使った方法で解説
```
ブロック
----
```
- でもいつもの##でもOK
```
## ブロック
```
この文字は表示されません
- 識別用に利用されます

見出しレベル3: 親ブロック内の子ブロック

見出しレベル3(h3)があると，その親ブロック内で子ブロックを作成します
- いつも通り###で作ります
```
### ちゃーと
```
- この中にRチャンクを挿入して中身を作成
- 親ブロック内に子ブロックが複数あると親と逆の方向で区切ります
この文字は表示されます

タブセットの利用

親ブロック(見出しレベル2)内でタブを設定可能

子ブロック要素が各タブの内容となります

## 親ブロック {.tabset}

### 子ブロック1
(ここにRチャンクなど)

### 子ブロック2
(ここにRチャンクなど)

その他のレイアウト関連

他にも色んなパターンができます
- 区切り幅(高さ)の調整
- サイドバーを表示
- ストーリボード
詳しくは，以下の本家のサイトを参照してください
- Sample flexdashboard Layouts

Components

ValueBoxes: 単一の値をシンプルに示したい時に
gauge: ゲージをさっくりと作ることも可能
詳細およびその他の要素は本家のサイトを参照
- Using flexdashboard#components

活用例: グルメマップ

学会に参加できなかったから作りました
- 実際のダッシュボードはこちら
- Rmdのコードはこちら (データはありません)

活用例: 台風プロット

気付いたら作るようになってた
- 実際のダッシュボードはこちら
- Rmdのコードはこちら (データはありません)

活用例: 個人別ダッシュボード

「あるデータセットから，個人別のダッシュボードをまとめて作りたい」
- R Markdownのパラメータ機能をうまく利用すれば可能
- 詳細は以下を参照
  R Markdownのparams機能を利用してflexdashboard作成

参考資料

flexdashboard: Easy interactive dashboards for R
- 本家のWebサイト
- たぶんまともな情報はここくらいにしかない
- あとはソースコードとヘルプを読むくらいしか…
flexdashboard Examples
- サンプルがギャラリーになってます
- ソースコードも(いくつかは)確認できます
  - 各ギャラリーをクリックして表示
  - 画面右上の“</>Source Code”をクリック
- Pokemonすげぇ

pkgdownパッケージ

パッケージ用のWebサイト作り

パッケージを作成して公開したとして…
- Helpとかドキュメントは整備した
- できればWebサイトとか準備したい
- でも超めんどくさい
- 自動的に作ってくれないの?
pkgdownパッケージを使ってみよう

pkgdownパッケージとは

R Markdownをベースにした，パッケージ用Webサイト作成に特化したもの
- パッケージのリポジトリ(R Project)から自動的にWebサイトに必要なファイルを作成
- bootstrap3ベースデザイン
- Webサイト構成についても柔軟にカスタマイズ可能
  - R MarkdownでWebサイトをbuildするのに近い
  - たぶん同じ要領
詳細は以下の本家サイトを参照
- http://hadley.github.io/pkgdown/

こんな感じです:

pkgdownの仕組み

デフォルトでは以下のような感じです:

生成物は./docsに格納される
- README.mdからindex.htmlを生成
- ./manからreferenceを作成
  - .Rdから各関数のページを作成
  - Function referenceの一覧ページも
- ./vignetteからArticleを生成
  - .Rmdから各ドキュメントを作成
  - もちろん一覧ページも
- 生成されたものに合わせてnavbarを生成
  - _site.yamlで詳細設定も可能

インストールと実行

インストール

GitHubから。

devtools::install_github("hadley/pkgdown")

実行

以下のコマンドを実行するだけでOK

pkgdown::build_site()

たったこれだけ!

注意点

{devtools}での開発を念頭においてるっぽい
- だって開発者は…
元のドキュメントがないとスッカスカ
- 逆に言うとヘルプドキュメント部分をちゃんと記述すれば超楽になる
- 特にvignetteの恩恵が大きい
  - vignette用のRmdには，output: rmarkdown::html_vignetteがおすすめ
  - R Markdownのテンプレートに標準ではいってます

参考資料

Home. pkgdown
- 本家のWebサイト。もちろんpkgdownでbuildしてます
Hadley/pkgdown
- 本家のGithubリポジトリ。
hoxo-m/githubinstall
- githubinstallのWebサイト。pkgdownで作成しています
  (もしかしたら今すぐは404かも)

さいごに

紹介を見送った内容

bookdownパッケージ
- R Markdownで本を作るパッケージ
  - GitHub, 本家サイト
  - 図表の通し番号もちゃんとやってくれる
  - Webサイト，pdf，epubに対応
  - いつかこれで薄い本作ろう…
rmdshowerパッケージ
- Rmdスライドを作成するパッケージ
  - GitHub
  - テストしてみた(code/完成例)
  - おもしろいけど，色々面倒な点があった

Enjoy!

https://github.com/kazutan/HijiyamaR5

最近のR Markdown関連のお話

Hijiyama.R #5

前田和寛(@kazutan)

2016/10/15

はじめに

今回の内容

注意事項

session info

R Markdownの最新機能

GUIまわりが進化

数式がインラインで表示

画像をインラインで表示

パラメータ機能に対応

多言語に対応

注意点

R Notebook

R Notebookとは

使ってみよう

基本はRmd

出力は.nb.html形式

特色

R Notebook Tips 1

ショートカットキー

R Notebook Tips 2

出力の全消去・折りたたみ・展開

R Notebook Tips 3

Rmdファイルの復元

注意点

self_contained: FALSEはNG

“Rmd Download”の罠

中途半端な実行

結局、使いどころは?

参考資料

flexdashboardパッケージ

ダッシュボードとは?

flexdashboardパッケージ

使ってみよう

冒頭のyamlについて

レイアウトと見出しレベルについて

見出しレベル1: ページ区切り

見出しレベル2: 親ブロックの区切り

見出しレベル3: 親ブロック内の子ブロック

タブセットの利用

その他のレイアウト関連

Components

活用例: グルメマップ

活用例: 台風プロット

活用例: 個人別ダッシュボード

参考資料

pkgdownパッケージ

パッケージ用のWebサイト作り

pkgdownパッケージとは

pkgdownの仕組み

インストールと実行

インストール

実行

注意点

参考資料

さいごに

紹介を見送った内容

Enjoy!

出力は`.nb.html`形式

`self_contained: FALSE`はNG