Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

R Markdownによるドキュメント生成と バージョン管理入門

677 views

Published on

第3回CAPS統計セミナーにおける発表資料です

Published in: Data & Analytics

R Markdownによるドキュメント生成と バージョン管理入門

  1. 1. R Markdownによるドキュメント⽣成と バージョン管理⼊⾨ ⚔ 第3回CAPS統計ワークショップ 紀ノ定 保礼 2018/8/23 (updated: 2018-08-24)
  2. 2. ⾃⼰紹介 所属 静岡理工科大学 情報学部 講師 研究領域 主に認知 + 社会心理学の観点から、交通行動を 研究しています 人間工学 2 / 87
  3. 3. 最近、本が出ました(4章:ggplot2による可視化を担当) RユーザのためのRStudio[実践]入門 http://gihyo.jp/book/2018/978-4-7741-9853-8 3 / 87
  4. 4. 本⽇の流れ 1. R Markdownとは 2. R Markdownによるレポーティングの利点 3. R Markdownによるレポーティングの手続き 4. R Markdownの実習と質疑応答 5. GitHub Desktopを用いたバージョン管理入門 4 / 87
  5. 5. 参考図書 5 / 87
  6. 6. 特にR Markdown: The Definitive Guideは必読! https://bookdown.org/yihui/rmarkdown/ 6 / 87
  7. 7. 1. R Markdownとは 7 / 87
  8. 8. Markdownの記法を用いて、R上でドキュメントを 生成するシステム ドキュメント構造を記述する、軽量マークアップ言語 例えば上記の文章は、以下のような記法を使用 <u>**Markdown**</u>の記法を用いて、R上でドキュメントを #←行末に半角スペース2つ 生成するシステム - ドキュメント構造を記述する、軽量マークアップ言語 HTMLなら、記述量が増える <u><em>Markdown</em></u>の記法を用いて、R上でドキュメントを<br>生成するシステム <ul><li>ドキュメント構造を記述する、軽量マークアップ言語</li></ul> 8 / 87
  9. 9. ドキュメント例 9 / 87
  10. 10. Markdownには色々と種類があるが、 R Markdownで用いられているのはPandocのMarkdown 詳細はこちらから https://pandoc.org/MANUAL.html#pandocs-markdown 10 / 87
  11. 11. PandocのMarkdown記法の例 R Markdownチートシートより 11 / 87
  12. 12. ドキュメント⽣成の流れ 1. .Rmdファイルを準備 2. 文章(Markdown記法で)や、Rチャンク(後述)を書く 3. Knitしてレンダリング(後述) 4. 出力されたドキュメントを確認し、必要に応じて2~4をループ R Markdownチートシートより https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf 12 / 87
  13. 13. ドキュメント⼀覧 R Markdownチートシートより https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf 13 / 87
  14. 14. PDF化する際の注意点 PDF化したい場合は、TeX環境が必要(日本語を含む場合は、特に面倒) そんなときはtinytex 参考:TinyTeXを使って10分で(R向けの)LaTeX環境を整える https://qiita.com/nozma/items/1c6b000b674225fd40d7 14 / 87
  15. 15. プレゼンテーション⽤ドキュメント 本セミナーでは割愛するが、デフォルトで以下の形式が 用意されている ioslides: あらゆるブラウザで閲覧可能なHTML形式 Slidy: あらゆるブラウザで閲覧可能なHTML形式 Beamer: PDF形式(TeXによる) その他、xaringanパッケージにより、拡張性の高い プレゼンテーション用ドキュメント作成も可能 https://github.com/yihui/xaringan 本資料もxaringanで(初めて)作成 15 / 87
  16. 16. 2. R Markdownによる レポーティングの利点 16 / 87
  17. 17. R Markdownがないとき 数値や図表を手作業でレポートへ反映させる → 入力ミス、違う図表の挿入など、 ヒューマンエラーが入り込むかもしれない 17 / 87
  18. 18. R Markdownがあるとき 日本社会心理学会 第5回春の方法論セミナー https://kazutan.github.io/JSSP2018_spring/ .Rmdファイルに記述した内容が自動的にレポートになる 仮にミスがあっても、その場所を特定・修正できる バージョン管理していれば、時期も特定可能 18 / 87
  19. 19. 参考映像:a reproducible workflow https://youtu.be/s3JldKoA0zw 19 / 87
  20. 20. Shinyによる、インタラクティブな レポーティング library(tidyverse); library(plotly) g <- ggplot(data = mtcars, mapping = aes(x = factor(cyl), y = wt)) + stat_summary(fun.y = "mean", geom = "bar", alpha = 0.3) + geom_point() ggplotly(g) 4 6 8 0 2 4 factor(cyl) wt 20 / 87
  21. 21. (番外編)Markdown記法を活⽤できる場所1 GitHub上でのやり取りも 21 / 87
  22. 22. (番外編)Markdown記法を活⽤できる場所2 はてなブログ等の記事の執筆も 22 / 87
  23. 23. 3. R Markdownによる レポーティングの⼿続き 23 / 87
  24. 24. とりあえずチートシートを手元に置きましょう 24 / 87
  25. 25. 準備 新規.Rmdファイルを用意 ドキュメントの出力形式を選ぶ(後から変更可能) 25 / 87
  26. 26. パッケージをインストールしているなら、様々なテンプレート を使用可能 → ある程度「初期設定」が整っているので便利 26 / 87
  27. 27. 論文も書けちゃう {papaja}パッケージ APAスタイルに特化したテンプレート {rticles}パッケージ Elsevier, Springer, PNASなど、主要な出版社・雑誌に対応 詳しくは、アカデミアのためのRSTUDIOを参照 https://ytake2.github.io/create.manuscript/RStudio_for_Academia.html 27 / 87
  28. 28. readthedownテンプレートの場合(rmdformatsパッケージ) HTMLフォーマット 28 / 87
  29. 29. フロントマター(YAMLヘッド項⽬) フロントマターに、ドキュメントに掲載する情報や (例:日付、製作者)、出力形式の設定を書く 29 / 87
  30. 30. 個⼈的によく使うYAMLヘッダ項⽬ --- title: "CAPS_RMarkdown" subtitle: "hogehoge" author: "Yasunori Kinosada" date: "2018-08-24" #自動で本日の日付を取得するなら、`r Sys.Date()` output: rmdformats::readthedown: highlight: zenburn #コードシンタックスのハイライト方法 md_extensions: -ascii_identifiers #日本語で書いている場合はおまじない self_contained: true #jsやcss,画像データなどをhtmlファイルに埋め込む lightbox: true #画像をクリックしたらポップアップさせる toc: true #メニュー(toc: table of contents)を設ける toc_float: true #tocを設けた場合に、ページ冒頭ではなく、サイドメニュー化 toc_depth: 3 #tocに反映させる見出しの階層数 --- もちろん他にもたくさんある 30 / 87
  31. 31. YAMLヘッダ項⽬⼀覧 多すぎるので全容は@kazutanの記事を参照 R Markdownのhtml_documentで指定できるyamlヘッダ項目について https://qiita.com/kazutan/items/726e03dfcef1615ae999 31 / 87
  32. 32. PandocのMarkdown記法で地の⽂を書く 32 / 87
  33. 33. コードチャンク 地の文ではないコード部分は、まとまり単位でチャンクの 中に書き、チャンクオプションを併用することで、挙動を操作 33 / 87
  34. 34. 新しいチャンクの準備 書きたい言語と対応するチャンクを選ぶ → チャンク冒頭に、各言語の名前が必要(Rチャンクなら{r}) 34 / 87
  35. 35. {knitr}パッケージがサポートしている ⾔語エンジン⼀覧 names(knitr::knit_engines$get()) ## [1] "awk" "bash" "coffee" "gawk" "groovy" ## [6] "haskell" "lein" "mysql" "node" "octave" ## [11] "perl" "psql" "Rscript" "ruby" "sas" ## [16] "scala" "sed" "sh" "stata" "zsh" ## [21] "highlight" "Rcpp" "tikz" "dot" "c" ## [26] "fortran" "fortran95" "asy" "cat" "asis" ## [31] "stan" "block" "block2" "js" "css" ## [36] "sql" "go" "python" "julia" 35 / 87
  36. 36. チャンク⽣成のショートカット 36 / 87
  37. 37. {r チャンクラベル(省略可), チャンクオプション1, チャンクオプション2, ...} なおチャンクラベルには、アルファベット、数字、ダッシュ-のみ使用推奨 同一.Rmdファイル内で、同じチャンクラベルは使用不可 37 / 87
  38. 38. チャンクオプション⼀覧 R Markdownチートシートより https://www.rstudio.com/wp-content/uploads/2016/11/Rmarkdown-cheatsheet-2.0_ja.pdf 38 / 87
  39. 39. 各チャンクで指定するのが面倒なら、グローバルな設定も可 ↓ readthedownテンプレートのデフォルトの設定 library(knitr) library(rmdformats) ## Global options options(max.print = "75") opts_chunk$set(echo = FALSE, cache = TRUE, prompt = FALSE, tidy = TRUE, comment = NA, message = FALSE, warning = FALSE) opts_knit$set(width = 75) 自分の場合は、echo = TRUEに変更して、この設定を使います 39 / 87
  40. 40. GUIでチャンクオプションを設定可能 ? Chunk optionsを押すと、Webページが開いて詳細を確認可 40 / 87
  41. 41. チャンク単位で実⾏可能 41 / 87
  42. 42. 実行時やレンダリング時の設定は変更可能 42 / 87
  43. 43. ⾒出し 見出し(#の数で階層化可能)やチャンク名を付けると、 メニューが生成される 43 / 87
  44. 44. 見出し(#の数で階層化可能)一覧も表示可能 44 / 87
  45. 45. 画像の挿⼊ Rコード(ggplot2パッケージ等)で画像を生成するのではなく、 既存の画像を挿入する場合 方法1:Markdown記法(コードチャンク外に書く) ![alt text or image title](path/to/image) ![alt text or image title][hogehoge] [hogehoge]: path/to/image もちろんHTMLも可↓ <img src = "path/to/image" alt = "hogehoge" title="fugafuga" width="200" height="300"> 45 / 87
  46. 46. 方法2:knitrパッケージのinclude_graphics() knitr::include_graphics("img/uchuhon.png") Rコードなので、コードチャンク内に書く 画像のプロパティを、チャンクオプションで様々に操作可 46 / 87
  47. 47. 表の⽣成 方法1:knitr::kable()(とりあえずこれでいい) knitr::kable(x = head(mtcars, 2), format = "html", digits = 2, align = "c", caption = "two rows of mtcars dataset") two rows of mtcars dataset mpg cyl disp hp drat wt qsec vs am gear carb Mazda RX4 21 6 160 110 3.9 2.62 16.46 0 1 4 4 Mazda RX4 Wag 21 6 160 110 3.9 2.88 17.02 0 1 4 4 47 / 87
  48. 48. 方法2:自力で書く knitr::kable()を、Markdown形式でコンソールに 出力させると... 実はこれが、表のMarkdown記法 :----- 左揃え :----: 中央揃え -----: 右揃え 48 / 87
  49. 49. Data.frameの表⽰ 行数が少なければknitr::kable()でよいが、多いと場所をとる → フロントマターで、df_printを"paged"に変更 49 / 87
  50. 50. ⾏が多すぎて省略される場合でも... 50 / 87
  51. 51. クラスをdata.frameにしてしまえば、 df_print: "paged"で全行表示可 ※broom::tidy()は出力をdata.frameにする関数 51 / 87
  52. 52. インラインコード・数式の表⽰ 値を書き写す手間・必要が一切不要 TeXと同じ記法で数式を書ける 52 / 87
  53. 53. 書きあがったらKnit(レンダリング) outputのフォーマットに応じて出力される 53 / 87
  54. 54. どんっ! 54 / 87
  55. 55. 5. Gitによるバージョン管理 55 / 87
  56. 56. バージョン管理の重要性 R Markdownを使いさえすれば再現可能性が担保される... わけではない どっちのファイルだっけ... 最終更新日時は分かるけど、どこを書き換えたんだっけ... 56 / 87
  57. 57. Gitによるバージョン管理 http://journals.sagepub.com/doi/abs/10.1177/2515245918754826 57 / 87
  58. 58. ⽤語の整理 Git : バージョン管理システム リポジトリでの変更履歴を記録するツール GitHub : リモートリポジトリ Web上のサービス リポジトリ : バージョン管理する「場所」 ローカルリポジトリ : クライアントPC内のリポジトリ リモートリポジトリ : GitHubなど、サーバ上のリポジトリ Publicリポジトリ : 誰にでも公開 Privateリポジトリ : 許可されたユーザのみアクセス可能 58 / 87
  59. 59. GitHubのアカウントを取得 GitHubアカウントを取得(Publicリポジトリで良いならこれだけで良い) GitHub Educationに申請するなら、研究者・教育者・学生などは 職場や学校のメールアドレスを登録するとよい GitHub Educationの利用申請(Privateリポジトリを作成したいなら) 研究・教育目的など、Privateリポジトリが必要な理由を申請 https://qiita.com/mtfum/items/d8c06c9a28ce04d3043a 59 / 87
  60. 60. Gitのインストール & 個⼈情報を設定 WindowsとMacではインストール後の手続きが異なるので注意 初心者でもWindowsやMacでできる、Gitのインストールと基本的な使い方 http://www.atmarkit.co.jp/ait/articles/1603/31/news026.html 60 / 87
  61. 61. 本セミナーではGitHub Desktopを紹介 https://desktop.github.com/ 最低限の機能に制限されているが、そのぶん初心者向き あわせてGit環境も自動的にインストールされる 61 / 87
  62. 62. GitHub上で、新しいリポジトリを作成 注意 : 一度publicにしたリポジトリは、privateにできない 62 / 87
  63. 63. そこに新しいリポジトリがあるじゃろ 63 / 87
  64. 64. それをローカルにクローンしてくる 64 / 87
  65. 65. 確かに一致! 65 / 87
  66. 66. もちろん他人が作った(public)リポジトリでも 方法1:パスをコピーして、任意のローカルリポジトリに紐づける 方法2:Download ZIPを押して、全ファイルをZIPフォルダで一括DL 66 / 87
  67. 67. 方法1:パスをコピーした場合 クローニング元としてURLを入力するだけ 67 / 87
  68. 68. ファイルの変更 仮にこういうファイルを追加したら... 新しい記述は緑の枠で表示される 68 / 87
  69. 69. 仮にファイルに変更があったとしたら... 問題が無ければ、更新内容の概要をメッセージに書いて commit 69 / 87
  70. 70. そしてpush! → commitしたローカルの変更内容を、リモートリポジトリ (GitHub等)に反映させる もし別のPC等でも作業していて、リモートリポジトリが更新されていたら 最初にpullして、ローカルリポジトリを最新の状態にすることを忘れずに (もっとも、GitHub Desktopなら自ずとその手順になる) 70 / 87
  71. 71. push前なら、Undoでcommitを取り消しできる 71 / 87
  72. 72. push後に、GitHub上で確認してみよう 72 / 87
  73. 73. いつ何を変更したか分かるから、安心 73 / 87
  74. 74. push後に特定の時点のcommitに戻りたい!という場合は... GitHub Desktop上で、当該commitを右クリック → revertで時を遡る 74 / 87
  75. 75. branch 大きな更新をいきなりpushするのは不安... 他者と共同作業している場合、勝手に更新されるのは困る etc... ならパラレルワールドを作って、そこで更新してみて、 その更新で良さそうなら反映させたらいいじゃない → それがbranch(枝)という発想 75 / 87
  76. 76. 最初はmaster branchという大樹の幹で仕事している 76 / 87
  77. 77. パラレルワールドを作り、大樹に迷惑をかけずに好き勝手する 77 / 87
  78. 78. 新しいbranchでファイル(practice2.R)を追加したとする 78 / 87
  79. 79. でもmaster branchは無傷! (practice2.Rというファイルが無い) 79 / 87
  80. 80. Pull request 現在のbranchでのcommitが良さそうなら、 master branchと合体して大樹に戻りたい! 「このbranchを吸収(pull)しておくれ」とmasterに要請 →pull request 80 / 87
  81. 81. 更新内容に問題なければ、Create pull request 81 / 87
  82. 82. Merge pull requestを受けた側は、当該branchでの更新内容に 異存なければ、「よかろう、取り込んでやろう」 → Merge 82 / 87
  83. 83. この場合は、branchからmasterへmergeしたので、 masterにpractice2.Rファイルが無事追加されている 83 / 87
  84. 84. Gitによるバージョン管理の⼿続き︓まとめ 1. 最新の状態をリモートからローカルにpull 2. branchを作って、パラレルワールドを創出 3. ローカルで作業して更新内容をcommit 4. pushしてリモートリポジトリに更新を反映 (commitを取り消したければrevert) 5. 枝(branch)がある程度育ったら、大樹(master)に 吸収を要請(pull request) 6. 大樹(master)は、吸収の要請(pull request)を 承認したら、統合(merge) GitHub Desktopでは機能制限されているが、 Gitなら他にも、もっともっとコマンドがある 84 / 87
  85. 85. 総括 85 / 87
  86. 86. 今回の企画趣旨 「分析」と「レポート作成」のパッケージ化 RMarkdownの活用 再現可能性の確保 RMarkdownの活用 + Git等によるバージョン管理 86 / 87
  87. 87. Enjoy! ご質問等があれば、遠慮なくご連絡ください 87 / 87

×