Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.
Nächste SlideShare
What to Upload to SlideShare
What to Upload to SlideShare
Wird geladen in …3
×
1 von 87

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

11

Teilen

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

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

×