3/ Markdown文法の基礎

Quartoを使った研究成果と分析プロセスの共有

宋財泫(関西大学)

1 はじめてのQuarto

とりあえずレンダー(1)

  1. File > New File > Quarto Document

とりあえずレンダー(2)

  1. 「Editor: User visual markdown editor」のチェックを外す

とりあえずレンダー(3)

  1. Sourceペイン上段の「Render」をクリック

とりあえずレンダー(4)

  1. ソースコードとViewerペインの出力物の対応関係を確認

Quartoファイルの構造

---
YAMLヘッダー
---

テキスト1

```{r}
チャンク
```

テキスト2
  • YAMLヘッダー:文書のメタ情報や見た目などに関する設定。YAML文法で記述
  • 本文
    • テキスト:そのまま出力される。Markdown文法で記述
    • チャンク:チャンク内のRコードは評価され、出力される。

2 Markdown文法

様々なMarkdown記法

QuartoのMarkdown記法は以下の記法をほとんど内包し、+ \(\alpha\)の機能も多い。

  • CommonMark
    • John Gruber(とAaron Swartz)が考案したMarkdown記法の標準化
  • GitHub Flavored Markdown(GFM)
    • CommonMarkに表、自動リンク、取り消し線などを追加した記法
  • Markdown Extra、MultiMarkdown、Markua、…
    • 脚注、数式、引用、相互参照、…

改行と強調

  • 改行は必ず2回改行すること(1回改行は同じ行として認識される)

Input:

文章1
文章2

文章3

Output:

文章1 文章2

文章3

  • イタリックは*、太字は**、取り消しは~~で囲む1

Input:

*Italic*

**太字**

~~取り消し~~

Output:

Italic

太字

取り消し

見出し

  • 部、章、節、項、…の見出し(#の数が多いほど文字が小さくなる)
    • #は6つまで
  • 章の見出しを##にするなら節は###、小節(または項)は####、…

Input:

# 見出し1

## 見出し2

### 見出し3

#### 見出し3

Output:

見出し1

見出し2

見出し3

見出し4

リンク

[リンク文](URL)[]で囲まれた文章をクリックすると()内で指定したURLへ移動

  • {target="_blank"}を付けると新しいタブで開くようになる(Quarto仕様)1

Input:

[宋のHP](https://www.jaysong.net)

[関大のHP](https://www.kansai-u.ac.jp/){target="_blank"}

Output:

宋のHP

関大のHP

脚注

  • 脚注の入れ方:^[脚注の内容]
  • 内容が長い場合、[^識別子]で脚注の位置だけ指定し、別の箇所に[^識別子]: 脚注の内容

Input:

家系ラーメン^[横浜]が食べたい。

ラーメン二郎[^jiro]も食べたい。

[^jiro]: 港区(東京)

Output:

家系ラーメン1が食べたい。

ラーメン二郎2も食べたい。

コメント

出力に影響されないコメントを入れる場合

  • HTMLのコメント機能を使用:<!---->内に囲む
    • <!---->の間の文章は出力されない
  • 自分用のメモ、とりあえず出力させない内容などに使用

Input:

これは文章1です。

<!--
これはコメントです。
-->

これは文章2です。

Output:

これは文章1です。

これは文章2です。

箇条書き(順序なし)

  • - + 半角スペース + 内容
    • 入れ子型の箇条書きは半角スペース2つ以上の字下げ
    • -の代わりに*も可

Input:

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

Output:

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

箇条書き(順序あり)

  • 1. + 半角スペース + 内容
    • 番号は自動的に振られるが、1.の代わりに2.を使うと2からスタート
    • 1.2.3.、…の書き方も可(非推奨)

Input:

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

Output:

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

箇条書き(チェックリスト)

  • - + 半角スペース + [x] + 半角スペース + テキスト:checked item
    • xを半角スペースにするとunchecked item

Input:

買い物リスト(キムチチゲ)

- 食材
   - [x] キムチ
   - [ ] 玉ねぎ
   - [x] 豚肉(肩ロース)
- 調味料
   - [ ] 醤油
   - [ ] 砂糖
   - [x] 味の素

Output:

買い物リスト(キムチチゲ)

  • 食材
  • 調味料

  • 行は改行(1回) + 列は|で表記
  • ただし、1行目(ヘッダー)と2行目(ボディー)の間には-を1つ以上入れる
    • :-は左揃え、-:は右揃え、:-:は中央揃え(-のみは左揃え)

Input:

|ID   |Name |Height|Favorite|
|:---:|-----|-----:|:-------|
|1    |SONG |176   |Ramen   |
|2    |Yanai|230   |Cat food|

Output:

ID Name Height Favorite
1 SONG 176 Ramen
2 Yanai 230 Cat food

Input:

|ID|Name|Height|Favorite|
|:-:|-|-:|:-|
|1|SONG|176|Ramen|
|2|Yanai|230|Cat food|

Output:

ID Name Height Favorite
1 SONG 176 Ramen
2 Yanai 230 Cat food

  • ![代替テキスト](画像のパス/URL)
    • 代替テキストはキャプションとしても機能する

Input:

![R Cat](https://www.jaysong.net/imgs/favicon.png)

Output:

R Cat

図の位置

  • {fig-align=位置}を追加(Quarto限定)
    • 例)"left"(左)、"center"(中央)、"right"(右)

Input:

![](画像URL or パス){fig-align="left"}

Output:

Input:

![](画像URL or パス){fig-align="center"}

Output:

Input:

![](画像URL or パス){fig-align="right"}

Output:

図の大きさ

  • {width=図の幅}を追加(Quarto限定)
    • 例)300px(300ピクセル; pxは省略可)1in(1インチ)25%(画面の25%)

Input:

![Tiny cat](画像URL){width=30}

![Big cat](画像URL){width=100}

Output:

Tiny cat

Big cat

数式

文中数式は$数式$、独立した行の数式は$$で囲む。

Input:

文中の数式:$e = mc^2$

Output:

文中の数式:\(e = mc^2\)

Input:

$$
F(x; \mu, b) =
\begin{cases}
   0.5 \exp(\frac{x - \mu}{b})       & \text{if} \quad x < \mu \\
   1 - 0.5 \exp(- \frac{x - \mu}{b}) & \text{if} \quad x \geq \mu
\end{cases}
$$

Output: \[ F(x; \mu, b) = \begin{cases} 0.5 \exp(\frac{x - \mu}{b}) & \text{if} \quad x < \mu \\ 1 - 0.5 \exp(- \frac{x - \mu}{b}) & \text{if} \quad x \geq \mu \end{cases} \]

複数の図表の配置

::: {layout-*=}:::の間に図表を入れる(layout-ncol、またはlayout-nrow

Input:

::: {layout-ncol=4}
![零号機](画像1のURL or パス)

![初号機](画像2のURL or パス)

![弐号機](画像3のURL or パス)

![量産機](画像4のURL or パス)
:::

Output:

零号機

初号機

弐号機

量産機

Input:

::: {layout-ncol=2}
|ID   |Name |Favorite|
|:---:|-----|:-------|
|1    |SONG |Ramen   |

|ID   |Name |Favorite|
|:---:|-----|:-------|
|2    |Yanai|Cat food|
:::

Output:

ID Name Favorite
1 SONG Ramen
ID Name Favorite
2 Yanai Cat food

3 Rコードとの統合

Rコードの入れ方

チャンク(chunk)内で記述されたRコードは評価(evaluation)される。

  • チャンクは```{r}で始まり、```で終わる1
  • ショートカットキー:Cmd + Option + I(macOS)、Ctrl + Alt + I(その他のOS)

Input:

以下のRコードは評価されない

sum(1:100)

```{r}
# 以下はRコードは評価される
sum(1:100)
```

Output:

以下のRコードは評価されない

sum(1:100)

# 以下はRコードは評価される
sum(1:100)
[1] 5050

インラインコード

インラインコード(inline code):チャンク外(=文章内)に挿入するRコード

  • チャンク内のRコードはRコードと評価結果、両方出力されるが、インラインコードは評価結果のみ出力される。
  • `r`の間にコードを記述(rを省略するとコードのみ出力)
    • チャンク内のオブジェクトを参照することも可能

Input:

1〜100の総和:`r sum(1:100)`

```{r}
x <- c(1, 2, 3, 5, 7)
```

`sum(x)`の実行結果:`r sum(x)`

Output:

1〜100の総和:5050

x <- c(1, 2, 3, 5, 7)

sum(x)の実行結果:18

4 チャンクオプション

チャンクオプション

チャンクの最上段で指定(コードより後ろのオプションは無視される)

  • #| + 半角スペース + オプション名: + 半角スペース +
  • 1つのチャンクに複数のオプションも可
  • 論理型の値はTRUE/FALSEでなく、true/false
```{r}
#| オプション1: 値
#| オプション2: 値
Rコード
```

代表的なチャンクオプション

  • labelcahcedependson
  • echoevalincludecollapse
  • errormessagewarning
  • 図に関連するオプション
    • fig-widthfig-heightout-widthout-heightfig-dpidevなど
  • レイアウト、キャプション、サブキャプション

label:チャンクのラベル

  • チャンクにラベル(名前)を付ける理由
    • レンダー時エラーが発生した際、どのチャンクが問題かが分かる。
    • 図表番号の相互参照(後述)
    • 他チャンクとの依存関係の指定(後述)
  • 付け方:#| label: ラベル名
    • 図(表)を生成するチャンクは接頭詞としてfig-tab-)を付ける。
  • ラベル指定によって処理結果や見た目が変わることはない

Input:

```{r}
#| label: my-chunk
x <- 1:10
sum(x)
```

Output:

x <- 1:10
sum(x)
[1] 55

cache:処理結果の保存

  • チャンク内コードの実行時間が非常に長い場合
    • #| cache: true:処理結果を最初のレンダー時に別途保存し、チャンク内コードに変更がない限り、その結果を参照
  • 注意:当該チャンクが別のチャンクに依存していても、当該チャンクのコードの変更がなければ処理結果は変わらない

Input:

```{r}
x <- 1:10
```

```{r}
#| cache: true
sum(x)
```

Output:

x <- 1:10
sum(x)
[1] 55
  • しかし、1番目のコードがx <- 1:100になっても、2番目のコードは変わっていないため、sum(x)の結果は55のまま

dependson:チャンク間の依存関係

  • 依存されるチャンクにラベルを指定し、依存するチャンクにはdependsonオプションを追加

Example:

```{r}
#| label: my-chunk-01
#| cache: true
x <- 1:10
```

```{r}
#| cache: true
#| dependson: my-chunk-01
sum(x)
```

注意点

  • 依存される・・・側のチャンクにも|# cache: trueを付ける
    • 依存するチャンク、されるチャンク、両方をキャッシング(caching)したいとdependsonは機能しない

echo、eval:コード、評価結果の出力

  • いずれも既定値はtrue
    • #| echo: false:コードを出力しない(評価はする)
    • #| eval: false:評価しない(コードは出力する)

Input(1):

```{r}
#| echo: false
sum(1:100)
```

Output(1):

[1] "Hi!"

Input(2):

```{r}
#| eval: false
sum(1:100)
```

Output(2):

print("Hi!")

参考)評価されないチャンクの作り方

{r}の代わりに{.r}rを使用

  • markdownyamlcssなどのチャンクにも使用可

Input:

```r
print("Hi"!)
```

Output:

print("Hi"!)

Input:

```{.r}
print("Hi"!)
```

Output:

print("Hi"!)

include:評価のみ行う

  • #| include: false:コード、評価結果いずれも出力しない
    • しかし、コードの評価は行う
    • echo: falseeval: falseはコードを評価しない

Input:

```{r}
#| include: false
hidden_x <- 1:10
```

```{r}
sum(hidden_x)
```

Output:

sum(hidden_x)
[1] 55

collapse:コードと評価結果をまとめる

コードと評価結果を同一ブロックにまとめる(既定値はfalse

Input(1):

```{r}
print("Hi!")
sum(1:100)
```

Output(1):

print("Hi!")
[1] "Hi!"
sum(1:100)
[1] 5050

Input(2):

```{r}
#| collapse: true
print("Hi!")
sum(1:100)
```

Output(2):

print("Hi!")
## [1] "Hi!"
sum(1:100)
## [1] 5050

各種メッセージの出力

  • 警告メッセージ(warning)、通常のメッセージ(message)のON/OFF
    • 既定値はtrue
    • {tidyverse}の読み込み、read_csv()によるファイルの読込時に表示されるメッセージが鬱陶しいなら#| message:false
  • error:エラーメッセージの出力
    • 既定値(false)のままだと、レンダーが中止される
    • #| error: trueの場合、レンダーは中止されず最後のチャンクまで評価される。エラーメッセージは出力物に出力される。

図の大きさ

  • 図そのものの大きさ:fig-widthfig-height
    • 単位はインチ
  • 出力物上での大きさ:out-widthout-height
    • 単位はインチ3in、センチ8cm、px500px、割合75%
  • 図の解像度:fig-dpi
    • 既定値は96だが、PDF出力や印刷をする場合、最低でも300は必要
    • 解像度が高いほどファイルのサイズが大きくなることに注意
  • 作図エンジン:dev
    • dev: ragg_pngにしておけば、とりあえず文字化けの心配はない({ragg}が必要)
    • すべてのチャンクに指定することは非効率的なので、YAMLヘッダーで指定することを推奨(後述)

図表のキャプション

  • fig-cap(図)とtbl-cap(表):ラベルと組み合わせると「図1. …」
    • 注意:図(表)を生成するチャンクのラベルはfig-tbl-)で始める

Input:

```{r}
#| tbl-cap: "表のキャプション"
gt(iris[1:3,])
```

Output:

gt(iris[1:3,])

表のキャプション

Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa
4.7 3.2 1.3 0.2 setosa

Input(2):

```{r}
#| echo: false
#| label: fig-myfig-01
#| fig-cap: "図のキャプション"
plot(rnorm(100), type = "l")
```

Output(2):

図 1: 図のキャプション

複数の図表の配置(1)

  • #| layout-ncol: 2にするとチャンク内の図は2列構成で配置される
    • Rコードで生成される表({gt}など)も可

Input:

```{r}
#| layout-ncol: 2
plot(1:10)

plot(rnorm(10), type = "l")
```

Output:

plot(1:10)
plot(rnorm(10), type = "l")

複数の図表の配置(2)

  • #| layoutでカスタムレイアウト           

Input:

```{r}
#| layout: [[50, 50], [100]]
plot(1:10)

plot(rnorm(10))

plot(rnorm(10), type = "l")
```
  • 2行構成で1行目は図2枚を50%、50%の割合、2行目は1枚を配置した例
    • [49, -2, 49]にすると、49% + 2%の余白 + 49%

Output:

plot(1:10)
plot(rnorm(10))
plot(rnorm(10), type = "l")

複数の図表のキャプション(1)

  • #| fig-cap:tbl-cap)後に改行し、#| + 半角スペース3個 + - キャプション
    • ラベルは共有するが、個別のプロットを参照する場合はfig-two-plots-1(左)とfig-two-plots-2(右)

Input:

```{r}
#| label: fig-two-plots
#| layout-ncol: 2
#| fig-cap: 
#|   - "左の図"
#|   - "右の図"
plot(cars)
plot(pressure)
```

Output:

図 2: 左の図
図 3: 右の図

複数の図表のキャプション(2)

  • tbl-cap(共通キャプション)とtbl-subcap(サブキャプション)を指定
    • 個別の図表を参照する方法は前頁と同じ

Input:

```{r}
#| label: tbl-three-tables
#| layout-ncol: 3
#| tbl-cap: irisデータセット
#| tbl-subcap: 
#|   - "setosa"
#|   - "versicolor"
#|   - "virginica"
gt(iris[1:5, 1:2])
gt(iris[51:55, 1:2])
gt(iris[101:105, 1:2])
```

Output:

gt(iris[1:5, 1:2])
gt(iris[51:55, 1:2])
gt(iris[101:105, 1:2])
表 1: irisデータセット
(a) setosa
Sepal.Length Sepal.Width
5.1 3.5
4.9 3.0
4.7 3.2
4.6 3.1
5.0 3.6
(b) versicolor
Sepal.Length Sepal.Width
7.0 3.2
6.4 3.2
6.9 3.1
5.5 2.3
6.5 2.8
(c) virginica
Sepal.Length Sepal.Width
6.3 3.3
5.8 2.7
7.1 3.0
6.3 2.9
6.5 3.0

YAMLヘッダー内のチャンクオプション

YAMLヘッダー内で指定したチャンクオプションはすべてのチャンクに適用される

  • knitr > opts_chunk内に指定
  • 一部のオプション名に注意
    • 例)fig-widthfig.widthfig-dpidpiなど
  • 例)すべてのチャンクにdpi: 300dev: ragg_pngオプションを付けたい場合
---
title: タイトル
author: 作成者名
knitr:
  opts_chunk: 
    dpi: 300
    dev: ragg_png
---

その他のオプション

Quartoの公式ホームページかknitrエンジンのマニュアルを参照