RMarkdown

R Markdownとは、RとMarkdownが結合されたもので、文章の表示とRの実行が同時にできる事が魅力の1つ。

R Markdownでは文章の中にコマンドを同梱できるため、ファイルが複数に散逸せず、整理しやすいという利点がある。

また、rmdファイルを送った相手に、解析内容を詳細に伝えられ、また相手側で簡単に再現できるという、

共同研究を行う上で最重要項目の1つ、「データを正しく共有」という面で大いに力を発揮する。

R Markdownの利点
  • 研究ノートが散逸しにくい
  • 結果をレポートに貼り付ける際のコピペミスを防げる
  • コマンドも一緒にかかれているので、どのように分析したかが相手にもわかる
  • 分析の再実行・部分変更が容易
  • データファイルとR Markdownを同じフォルダに入れられる
  • Markdownで書いたテキストは、HTML,Word, Tex, , ePUB, 画像などに変換可能
  • 階層的な構造を書く文章に向いている。レイアウトに気を取られる事がないため、階層構造に集中して執筆ができる

R Markdown作成の流れ

RStudioをインストールしていれば普通にR Markdownが使える。

試しに、

library(rmarkdow)
pandoc_available()

と入力してみて、コンソールに下記表示が出ればOK。

R Markdown作成の流れとしては、

  1. R Markdownの新規作成
  2. 内容を記述
  3. Knit してレンダリング
  4. ドキュメントを確認
  5. 2-4を繰り返す

という感じ。

R Markdownの新規作成

File > New File > R Markdown...

で新規作成。

  • Documentを選択
  • Title: ドキュメントのタイトル
  • Author: 作成者の名前(自分)
  • Default Outut Format: html

に設定してOKを押す(基本、HTML)。

デフォルトで、ヘッダやチャンクの例が現れる。

内容を記述

YAMLヘッダ (YAML metadata section)

YAMLヘッダ (YAML metadata section) はファイルの書式。

新規作成時に入力した、

  • 文書のタイトル (Title:)
  • 作成者名 (Author:)
  • 日付 (date:)
  • 出力形式 (Output:)

が記入済みの状態になっている。

---
title: "mom-neuroscience"
author: "mom-Dr"
date: "1/1/2021"
output: html_document
---

YAMLヘッダで設定できるオプションは十数個以上ある。

以下は私個人の設定の備忘録 ▼

日付を「現在の日付」に設定 (date:)

Sys.Date()

で作業現在の日付に変更できる。

---
title: "mom-neuroscience"
author: "mom-Dr"
date: '`r format(Sys.Date(), "%B %d, %Y")`'
output: html_document
---

設定内容の詳細は

「【R Markdown】現在の日時を記入:Sys.Date(), Sys.time()

に別途記載。

アウトプット形式 (output:)

アウトプット形式については、後ほどまとめて記載(アウトプット形式へジャンプ)。

その他

  • highlight
    : コードシンタックスのハイライト法(eg. zenburn)
  • md_extensions
    : 日本語で書く場合(eg. -ascii_identifiers)
  • self_contained
    : TRUE で、js, CSS, 画像データなどを html ファイルに埋め込む
  • lightbox
    : TRUE で、画像をクリックしたらポップアップさせる

チャンク(Chunk)

チャンク(Chunk)とは、実行コマンドを書き込む部分のこと。

```{r}

```

で囲む。

最初の

```

の行は チャンクYAMLヘッダ(Chunk header)。

このチャンク内では、パッケージやデータの読み込み、オブジェクトの生成、データハンドリング、可視化など、Rと同じ事ができる。

  • チャンク内にR
  • チャンク外にMarkdown

というイメージ。

コマンドを部分的に実行

各チャンク内のコマンドは、チャンク左上の再生ボタンをクリックして確認できる。

チャンクラベル

チャンクラベルは

{r チャンクラベル}

で指定し、

r

チャンクラベル

の間には

,

は入らない。

チャンクラベルは、cache オプションを付ける場合に重要となる。

また、あとからRmdファイルを読む際にわかりやすくなるため、極力つけたほうがよい。

ただし、チャンクラベルはドキュメントで同一のものがないように気をつける。

※ cache オプションについては、【R Markdown】 cache オプションに別途記載。

チャンクのオプション

チャンクの

{r}

の箇所に、

{r チャンクラベル, オプション1, オプション2, ...}

といった感じでオプションを追加できる。

チャンクオプションの種類は数十種類……。

色々なチャンクオプション

オプション デフォルト 内容
eval TRUE チャンク内のコードを評価するかどうかを指定
echo TRUE チャンク内のコードをドキュメントに表示させるかどうかを指定
include TRUE 実行後にチャンクの内容をドキュメントに含めるかどうかを指定
result markup 実行結果をどう出力するかを指定。
  • markup: マークアップ処理
  • asis: そのまま出力holdはチャンク内の実行後、その結果をまとめて出力
  • hide: 結果を出力しない
cache FALSE 実行した結果をキャッシュするかどうかを指定。キャッシュすると、次回以降コード内容に変化がなければ実行をスキップしてキャッシュを利用する。dependsonと併用したほうがよい。
error FALSE R コードの実行時のエラーをどうするか指定。
  • TRUE: エラーメッセージをドキュメントに表示
  • FALSE: レンダリングを停止
warning TRUE R コードを実行した際の warning (警告) をドキュメントに表示させるかどうかを指定。
message TRUE コードを実行した際の message をドキュメントに表示させるかどうかを指定。
tidy FALSE
tidy = TRUE
を加えると、自動的にコードを読みやすい形に整形してくれる。
tidy

オプションを使うためには、予め

formatR

パッケージを読み込んでおく必要がある。

install.packages("formatR", repos = "http://cran.rstudio.com")
# or development version
options(repos = c(yihui = "https://yihui.r-universe.dev", CRAN = "https://cloud.r-project.org"))
install.packages("formatR")

#読み込み
library(formatR)

でも、tidyオプションなしでも見やすい記述をできるだけ心がけたい。

チャンクオプション:プロット(plot)

R Markdown は作図の結果も出力できる。

その際、オプションに情報を追加して、図のサイズや解像度を指定可能。

  • fig.height
    : 図の高さ。単位はインチ。デフォルトは7
  • fig.width
    : 図の幅。単位はインチ。デフォルトは7
  • fig.align
    : 図の位置。デフォルトは
    "left"
    "right"
    で右揃え、
    "center"
    で中央揃えになる。
  • fig.cap
    : 図のキャプション
  • dpi
    : 図の解像度。デフォルトは72。論文では300必要

チャンクオプションを予め設定しておく

ドキュメントの最初に、チャンクオプションを予め全部設定しておくと便利。

knitr::opts_chunk$set(echo = FALSE, include = FALSE, message = FALSE, warning = FALSE, error = FALSE, comment = NA, cache = TRUE, R.options = list(width=220), fig.align = 'center', out.width = '75%', fig.asp = .75)

この設定は、セットアップチャンクなど RMarkdwon の最初の方に記述しておき、デフォルトとしておく。

そして、設定を変更したいチャンクがあれば、そこのチャンクだけ個別に設定すると良い。

必要なパッケージをインストールして読み込む

必要なパッケージは、

install.packages ("○○")

でインストールする。

e.g.
install.packages("tidyverse", dependencies = TRUE)
install.packages("rmarkdown", dependencies = TRUE)
install.packages("knitr", dependencies = TRUE)
install.packages("systemfonts")
install.packages("remotes")
remotes::install_github("Gedevan-Aleksizde/fontregisterer", repos = NULL, type = "source")
install.packages("tidyverse")
install.packages("devtools")
install.packages("data.table")
install.packages("sf")

インストール済みのパッケージは、画面右下ペインの "Packages" で確認できる。

各パッケージの名前の左にある □ にチェックを入れると、読み込みしてくれる。

もしくは、スクリプト or コンソールに

library()

と入力する。

 

必要なものはだいたいインストール済みなので、新規ドキュメントを開いたら、デフォルトで読み込んでおく。

library(tidyverse); library(ggbeeswarm); library(readxl); library(lmerTest); library(Hmisc); library(corrplot); library(ggsci); library(RColorBrewer)

Markdown文法

HTMLの知識があると、覚えやすい。

見出し

見出しには

#

を使う。

# の数が見出しの深さになる。

  • #: h1
  • ##: h2
  • ###: h3
  • ####: h4
# 見出し1
## 見出し2
### 見出し3
#### 見出し4 

改行

Markdownにおける改行は、「2回改行する」。

1回だと改行として認識されない。

文章1

文章2
Output:

文章1
文章2

文字の装飾

  • 太字:
    ** **
  • 斜体:
    * *
  • 取り消し線:
    ~~ ~~
  • 下線:
    <u> </u>
  • 上付き:
    ^ ^
  • 下付き:
    ~ ~
  • 文字色:
    <span style="color: 色を指定;">   </span>

    ※ 文字色はマークダウンがないので、普通に html で指定する。
**太字**
*斜体*
~~取り消し線~~
<u>アンダーライン</u>
<span style="color: blue; ">青文字</span>
Output:
太字
斜体
取り消し線
アンダーライン
青文字

箇条書き

番号なしの場合は、

*

または

-

の後に半角スペースを1字入れる。

2文字以上の字下げで下位項目を追加。

*

-

が混ざっていても影響しない。

- 項目1
  - 項目1-1
  - 項目1-2
    - 項目1-2-1
      - 項目1-2-1-1
      - 項目1-2-2-2
- 項目2
- 項目3

番号ありの場合は、

*

-

の代わりに数字とドット(eg. 1.)を入れる。

1. 項目1
  1. 項目1-1
  2. 項目1-2
    1. 項目1-2-1
    2. 項目1-2-2
2. 項目2
3. 項目3

コード

基本、上記のチャンク

```{r}

```

でコードを挿入するが、チャンクじゃなくてもコードを入れることができる。

 

文章中にコードを入れたい場合は、

`

`

ではさむ。

これを「インラインチャンク」と呼ぶ。

文章中の コードは`r format(Sys.Date())` という感じ。

複数行のコードを記述する場合は、

```

```

ではさむ。

```
x <- "abc"
print(x)
```

区切り線

区切り線には

---

または

***

を使う。

---
Output:

表は Markdown でも作れるが、手間だし、R で作成した内容を簡単に表にできるので、そちらを利用した方がよい。

 

念の為、Markdown での作り方を書き留めておく。

Markdown で表を作る際、行は改行で、列は

|

で区切られる。

表の第1行はYAMLヘッダ扱いとなり、YAMLヘッダと内容の区分は

|---|

で区切る。

|ID |Age |Sex |Score|
|:--:|---:|---|----:|
|120 |76 |M |29 |
|214 |81 |F |28 |
|356 |64 |F |21 |
|489 |55 |M |18 |

1行目はYAMLヘッダ扱いとなり、太字で中央揃えになる。

2行目以降はデフォルトで左揃えになる。

  • |--|
    デフォルト。左揃え。
  • |:--|
    左揃え
  • |--:|
    右揃え
  • |:--:|
    中央揃え
---

は、1個以上であれば何個でもOK。

画像

画像は、

[代替テキスト](ファイル名)

と入力する。

画像を html 内に埋め込みたい場合は、[代替テキスト] の前に「!」をつけて、

![代替テキスト](ファイル名)

と入力すればOK。

ワーキングディレクトリに画像があれば、ファイル名だけでOKだが、別の場所にある場合はパスを指定する。

![机の上にある本](https://reading-log.mom-neuroscience.com/wp-content/uploads/2021/03/210311-book.jpg)
Output:

本 机の上にある本

画像のサイズ変更

画像のサイズを変更したい場合は、

![代替テキスト](ファイル名) 

の後に

{width=" "}

でサイズを追加する。

width だけ追加すると、縦横比を保ったままサイズが変更される。

widht=" " hight=" " で両方指定もできる。

![机の上にある本](https://reading-log.mom-neuroscience.com/wp-content/uploads/2021/03/210311-book.jpg){width="300"}
Output:

本 机の上にある本

ハイパーリンク

ハイパーリンクは、

[テキスト](URL)

という形式で入力する。

私の読書ログへの[リンク](https://reading-log.mom-neuroscience.com/)
Output:私の読書ログへのリンク

脚注

脚注は

  • 文末脚注を入れる箇所に
    [^固有識別子]
    を挿入
  • 実際の脚注の内容を
    [^固有識別子]: 内容
    のように入力
脚注を入れる[^1]。

[^1]: 脚注の説明。
Output:

脚注を入れる1

1脚注の説明。

数式

数式は、

$数式$

という形で埋め込む。

したがって、$x=0.98$ となる

文章中ではなく、まとまった数式ブロックとして挿入したい場合は、

$$

という形で記述する。

したがって、下記公式が成り立つ。

$$
a + b = e
c + d = e
なら
a + b + c + d = 2e
$$

引用

引用を入れる場合は、文章の最初に

>

を入れる。

>

の後には半角スペースを1つ入れる。

> 引用する文章を記述。

> 複数行にまたがる場合は、
> それぞれの行頭に > を入れる。

コメント

R Markdown のコメントは、

  • タイトル部分:
    #コメント
  • Markdown内:
    <!--コメント-->
  • チャンク内:
    #コメント

とする。

出力(レンダリング)

  • html
  • pdf
  • word

などにレンダリング(Knit)できる。

その際、output 形式を色々指定しておくことが可能。

output 形式は、YAMLヘッダの

output:

で指定する。

よく使う output 形式は後述。

HTMLでレンダリング

研究ノートとして保存したり、誰かにプレゼンしたりするときには、HTMLが最適。

Knit > Knit to HTMLでレンダリングする。

ファイル名を入れて、任意の場所に保存する。

HTML形式でレンダリングされる。

YAMLヘッダに目次を入れて追尾にしておくと、左側に追尾目次が作成される。

output: html_documentの個人設定と解説は後述。

Word でレンダリング

Word でのレンダリングが求められるのは、主に論文作成やレポート提出のとき。

私は、論文作成のときはまだ他のソフトを併用しているが、将来的に R Markdown で完結できたらいいなと思う。

レンダリングの方法は、Knit > Knit to Word

output: word_documentの個人設定と解説は後述。

論文作成に必要なパッケージや手順については、別途記載予定。

PDFでレンダリング

PDF化の場合、TeX環境が必要となる。

"tinytex" をインストールする。

install.packages(c("tinytex","rmarkdown'))
tinytex::install_tinytex()

日本語が含まれている文書をレンダリングする場合は、エラーが表示される。

それを回避するためには、日本語TeX環境を整え、YAMLヘッダを修正する。

参考サイト ▼

グラフに日本語が含まれる場合 ▼

アウトプット形式の色々

色々なアウトプット形式が選択できる。

出力形式 ファイル形式 特徴
html_document *.html html形式のドキュメントを生成。Webブラウザで閲覧でき、CSSによるスタイル設定やjavaScriptを活用した動的なコンテンツも活用できる。
pdf_document *.pdf pdf形式のドキュメントを生成。pdfファイルへ出力するには、実行するマシンに Tex 環境を入れておく必要がある。
word_document *.docx Microsoft Word の docx 形式のぢ球面とを生成。生成された docx ファイルは Word で開いて編集できる。
odt_document *.odt Open Document フォーマットのドキュメントを生成。生成された odt ファイルは LibreOffice などのアプリケーションで開いて編集/閲覧できる。
rtf_document *.ftf Rich Text フォーマットのドキュメントを生成。
md_document *.md Markdown 形式のドキュメントをせいせ。生成された md ファイルは各種エディタやビューワソフトで編集/閲覧できる。
github_document *.md Github compatible markdown
ioslides_presentation *.html ioslides という javaScript ライブラリを利用した html 形式スライドを生成。html ファイルで出力され、ブラウザでスライドを表示できる。
slidy_presentation *.html slidy という javaScript ライブラリを利用した html 形式スライドを生成。html ファイルで出力され、ブラウザでスライドを表示できる。
beamer_presentation *.pdf TeX の beamer クラスを利用した pdf 形式スライドを生成。pdf ファイルで出力される。生成には実行するマシンに TeX 環境が必要。

 

以下、使用頻度の高い下記3つについての個人用テンプレート。

  1. html_document:
  2. word_document:
  3. ioslides_presentation:
---
title: "Project Title"
author: "My name"
date: '`r format(Sys.Date(), "%B %d, %Y")`'
output:
  html_document:
    number_sections: yes
    theme: cerulean
    toc: yes
    toc_float: yes
    toc_depth: 3
    df_print: kable
  word_document:
    toc_depth: 3
    number_sections: yes
    reference_docx: ../フォルダ名/ファイル名.docx
    always_allow_html: yes
    bibliography: ../Data/references.bib
    csl: ../Data/brain.csl
  ioslides_presentation:
    widescreen: yes
    smaller: yes
---

"○○_document" は output: の下位項目なので、字下げを行う。

"それ以下の項目" は、"html_document" の下位項目なので、更に字下げする。

使わないアウトプットは、

#

でコメントにしている。

e.g. 共著者に word document を送りたいだけのとき ▼

---
title: "プロジェクト名"
author: "私の名前"
date: '`r format(Sys.Date(), "%B %d, %Y")`'
output:
#  html_document:
#    number_sections: yes
#    theme: cerulean
#    toc: yes
#    toc_float: yes
#    toc_depth: 3
#    df_print: kable
  word_document:
    toc_depth: 3
    number_sections: yes
    reference_docx: ../フォルダ名/ファイル名.docx
    always_allow_html: yes
    bibliography: ../フォルダ名/ファイル名.bib
    csl: ../フォルダ名/ファイル名.csl
#  ioslides_presentation:
#    widescreen: yes
#    smaller: yes
---

1. html_document

---
title: "Setting for html_document"
author: "mom-doc"
date: '`r format(Sys.Date(), "%B %d, %Y")`'
output:
  html_document:
    number_sections: yes
    theme: cerulean
    toc: yes
    toc_depth: 3
    toc_float: yes
    df_print: kable
---
通し番号をつける (number_sections:)
number_sections

: 見出しに通し番号をつけるかどうか

    デフォルトは FALSE。これを TRUE にすると、見出しに通し番号が付く。後述の目次をTRUEにすると、その目次内でも通し番号が出力される。
テーマを指定する (theme:)

R Markdown にはいろいろなテーマが用意されている。

デフォルト (default) でも良いが、私は ceruleanを使用。

テーマのデザインはこちらのHPを参照 ▼。

目次をつける (toc:)

後述の方法で、# を使って文章に見出しをつけていくと、自動的に目次が生成される。

  • # : 章
  • ## : 節

目次のコードは

toc

(table of contentsの意味)。

  • toc
    : 目次の出力有無
      デフォルトは FALSE。これを TRUE にするとを出力する。
  • toc_depth
    : 目次の深さを指定
      デフォルトは 3。これは h3 まで見出しに含む、という意味。この数字を変更して、どの深さの見出しまでに含むかを指定。
  • toc_float
    : 目次のフローティング
      デフォルトは FALSE。これを TRUE にすると、目次が文書の左側に位置し、文書をスクロールしても目次が追尾するようになる。
データフレームの表示 (df_print:)

HTML系フォーマットには

df_print

というオプションがある。

df_print

オプションは "Data Frame Print" の略で、データフレーム型のデータを表示する方法を指定するためのオプション。

df_print

で指定できる値は4種類。

出力形式
default Rでdata.frameを表示した時に使われるテキスト表形式
kable シンプルな表形式
paged ページ区切りのついたインタラクティブな表形式。列数が多いと自動的にスクロール表示になる。
tibble tibbleクラスを用いた簡易なテキスト表形式

上記のうち、表と呼べるのは、kable と paged の実質2種類。

私は kable に設定(内容が長い場合は paged)。

その他、追加パッケージで、凝った表も作成可能。

2. Word_document

---
title: "title"
author: "mom-doc"
date: '`r format(Sys.Date(), "%B %d, %Y")`'
output:
  word_document:
    number_sections: yes
    toc_depth: 3
    always_allow_html: yes
    reference_docx: ../フォルダ名/ファイル名.docx
    bibliography: ../フォルダ名/ファイル名.bib
    csl: ../フォルダ名/ファイル名.csl
---
tnumber_sections

toc_depth:3

については前述の通り。

always_allow_html

を TRUE にしておく。

reference_docx, bibliography, cslに指示を与える。

また、下記3点は、同じフォルダ (eg. "RmdData") に1つにまとめておく。

  • docx スタイル
  • bib ファイル
  • cls ファイル

呼び出すときは、

reference_docx: "D:/R/R directory/Ref_Styles/Style_Manuscript.docx"
bibliography: ../RmdData/References.bib
csl: ../RmdData/Lancet.csl

のような感じ。

"./" で、「同じフォルダ内」という意味。

一つ上の階層だったら "../" と書く。

reference_docx の場合は、相対パスではなく絶対パスを使う。

wordの書式スタイルを指定 (reference_docs:)

wordの書式スタイルの参考先を記述する。

reference_docs: ../フォルダ名/ファイル名.docx

書式スタイルの作り方は以下が効率的。

効率的なWord書式スタイルの作り方
  1. Markdown の構成要素や図表を出力するRチャンクを含んだ Rmd ファイルを準備
  2. その Rmd ファイルを word_document でレンダリング
  3. 生成された docx ファイルを Word で開き、Word 上でスタイルを設定
  4. 設定した docx ファイルを名前をつけて保存 (e.g. "word-styles")
  5. .Rmd ファイルで、
    reference_dox:
    で、保存した docx を指定 (e.g.
    reference_docx: ../フォルダ名/ファイル名.docx
    )
作成したword書式の参照の仕方

参照したいwordファイルが同じフォルダ内にある場合:

reference_docx: ファイル名.docx

参照したいwordファイルが一つ上の階級にある別のフォルダにある場合(相対パス):

reference_docx: ../フォルダ名/ファイル名.docx

参照したいwordファイルを絶対パスで指定する場合(例はDドライブ内のR/Rディレクトリ内のフォルダを参照)

reference_docx: D:/R/R directory/フォルダ名/ファイル名.docx 

参考文献を挿入: bib データ (bibliography:)

bib データは、載せたい文献の情報が書かれたファイル。

bib データは、pubmed や Google Scholar から入手可能 (入手方法は別途記載予定。)

最終的に原稿に載せる論文をひとつの bib データとしてまとめる。

 

私は、文献管理に ReadCube を使用しており、

必要な論文をまとめて bib ファイルとしてエクスポートしている。

.Rmd ファイルで、

bibliography:

で、保存した bib を指定 (e.g.

bibliography: ../RmdData/References.bib

)

参考文献を挿入: csl データ (csl:)

csl データは、投稿先のジャーナルの形式の情報が書かれたファイル。

下記から入手 ▼

.Rmd ファイルで、

csl:

で、保存した csl を指定 (e.g.

csl: ../RmdData/the-lancet-neurology.csl

)

3. ioslides_presetation

---
title:"title"
author: "mom-doc"
date: '`r format(Sys.Date(), "%B %d, %Y")`'
output:
  ioslides_presentation:
    widescreen: yes
    smaller: yes
---

R Markdownのプレゼンテーション形式は3種類。

  • ioslides形式: 出力ファイルは.html
  • slidy形式: 出力ファイルは.html
  • beamer形式: 出力ファイルは.pdf

作り方については、下記参照 ▼

私は、

wdescreen

smaller

のみ設定。

ディスプレイモード (widescreen:)

ディスプレイモードは、下記5つ。

  • 'f' : フルスクリーン・モード
  • 'w' : ワイドスクリーン・モード
  • 'o' : オーバービュー・モード
  • 'h' : コードハイライト・モード
  • 'p' : プレゼンター・ノート
文字の大きさ (smaller:)

TRUE にすると、プレゼンテーションの文字サイズを小さくできる。

References