Appendix G — Quarto [文書]

本項目は執筆途中です！

本章は完成後、既存のR MarkdownとQuartoの内容の一部を代替しますが、現時点では参考程度にしてください。

G.1 出力フォーマット

　前章の例ではrender後の出力フォーマットはHTML形式のドキュメントだったが、Quartoは様々なフォーマットに対応しており、Microsoft WordフォーマットやPDFフォーマット出力も可能だ。フォーマットはYAMLヘッダー内で指定するため、具体的な内容は次節で紹介するとし、ここではPDFフォーマット出力のための準備だけ紹介しておこう。もし、PDF出力を使う予定がなければ本節は読み飛ばしても良い。

G.1.1 PDF出力の準備

　まず、{tinytex}パッケージをインストールする。この作業はすぐ終わる。

install.packages("tinytex")

　続いて、{tinytex}パッケージのinstall_tinytex()関数を実行する。これは自分のPCに\(\LaTeX\)の最低限の環境をインストールする関数である。通常の\(\LaTeX\)環境ならサイズが非常に大きく、ダウンロードを含め、1時間以上かかる。しかし、{tinytex}はQuarto/R Markdownに必要な最低限の機能のみ¹を提供するため比較的にすぐ終わる。すぐ終わると言っても、数分はかかるだろう。

tinytex::install_tinytex()

　ただし、以下のようなメッセージ（/Library/TeX/texbin/tlmgrの箇所は自分の環境によって異なるだろう）が出力されたら既に\(\LaTeX\)環境がインストールされていることを意味するため、コンソールに「N」を入力し、Enter / Returnを押す。

Found '/Library/TeX/texbin/tlmgr', which indicates a LaTeX distribution may have existed in the system.
Continue the installation anyway? (Y/N)

G.2 YAMLヘッダー

　YAMLヘッダーでは文書のタイトル、作成者、作成日のようなメタ情報に加え、出力フォーマット（HTML、PDF、Microsoft Word）、出力タイプ（文書、本、ウェブサイト、ダッシュボードなど）、チャンクオプションの指定ができる。YAMLヘッダーはYAML（YAML Ain’t Markup Language）という言語の表記法に則って書く必要がある。

　YAMLヘッダーは.qmd文書最上段の---と---間の領域内に指定するが²、順番は関係ない。しかし、多くの場合、メタ情報、フォーマット、タイプ³、チャンクオプションの順になることが多い。ここではよく使う機能を中心にYAMLヘッダーの書き方を紹介する。

G.2.1 メタ情報

　まずはメタ情報について解説する。最低限のものとしてはタイトル（title）、作成者（author）、作成日（date）があるが⁴、なるべく多くの内容を解説したいので、適当なQuarto文書を作成し、YAMLヘッダーを以下の内容に置き換え、renderしてみよう。

メタ情報指定の例

---
title: なぜ私がヘルムシュテット大学に...?
subtitle: 2083年では数学落ちこぼれだった私が1777年に生まれ変わり数学天才と称えられた件について
author: 
  - name: カール・フリードリヒ・ガウス
    affiliation: ヘルムシュテット大学
    email: gauss@herumushutetto-u.ac.jp
    url: https://www.jaysong.net/
    attributes:
      corresponding: true
  - name: ベルンハルト・リーマン
    affiliation: ゲッティンゲン大学
    email: reimann@gettingen-u.ac.jp
    url: https://yukiyanai.github.io/
date: 1855/2/23
date-modified: today
lang: ja
abstract: |
   算数すらまともにできなかった私が1777年のドイツに生まれ変わり、
   適当なこと喋ったら、なぜかみんな私のことを天才と称え始めた。
   マジで訳わからんわ。なんか、私の名前をちなんだソフトもあるらしいね。
format: html
---

　まず、タイトルはtitle、サブタイトルはsubtitleで指定する。:の後ろには必ず半角スペースを入れること。タイトルは文字列なので"で囲んでも良いが、YAML文法の場合、囲まなくても良い。

　作成者名は作成者が一人、かつ氏名のみ出力するだけならauthor: 作成者名だけでよい。しかし、作成者が二人以上の場合、以下のように書く必要がある（author以外の箇所は全て省略）。

author:
  - name: 作成者1
  - name: 作成者2

　以上のようにauthor:後に改行し、2文字以上半角スペースで字下げを入れた上で、- name: 作成者名と書く。-の後ろにも半角スペースを忘れないこと。Markdownにおける箇条書き（順序なし）と同じだと考えても良いだろう。また、authorには作成者に関する様々な情報を与えることができる。たとえば、作成者の所属機関、ホームページアドレス、メールアドレス、責任著者の有無などがある。最初に見せた例は二人の所属機関（affiliation）、メールアドレス（email）、ホームページ（url）を追加し、更にガウスには責任著者（attributes > corresponding）という情報を追加した（全員の貢献度が同じである場合、attributes内にequal-contributorも指定できる。）。

　dateは文書の作成日であり、date-modifiedは文書の修正（更新）日である。2024/06/04のような表記法で良い。もし、render日を自動的に入れたい場合はtodayにすれば良い。これはdate-modifiedと相性が良い。

　langは文書の言語である。これによって文書が大きく変わることは内が、自動生成される内容、なとえば「References」が自動的に「参考文献」に変わったりする。デフォルトは英語（lang: en）であるが、日本語にしたい場合はlang: jaに変更しよう。

　最後にabstractは文書の概要である。ここで注目したいのはabstract:の後に内容が来るのではなく、|が入り、内容は次の行になっている点だ。YAMLの場合、値が長くなりそうだと、|の次の行に書くことが多い。この中では普通のMarkdown文法が使用可能である。たとえば、**を使った強調はむろん、二行改行を入れることで概要内の改行もできる。|でなく、>を使うケースもあるが、この場合は概要内において改行が適用されない。

G.2.2 フォーマット

　先ほどの「メタ情報指定の例」の最後を見るとformat: htmlと書かれた行がある。ここが出力フォーマットを指定する箇所であり、よく使われるフォーマットはHTML（format: html）とPDF（format: pdf）、そして次章で解説するreveal.jsのスライド（format: revealjs）などがある。他にもあまり推奨はしないが、Microsoft Word（format:docx）もある。

　RStudioから.qmd文書を作成すると、既定値はformat: htmlになっているが、ここを適当にpdfやdocxに変えると別フォーマットとして出力されるため、非常に便利だ。もし、一つの.qmdファイルをHTMLとPDF版、両方用意する場合、その都度format:をいじるのは面倒だろう。実はこのformat:は複数のフォーマットを指定することもできる。たとえば、HTMLとPDFなら以下のように指定する。

format: 
  html: default
  pdf: default

　この状態でrenderを行うとHTML版で出力されるが、出力フォーマットを変更したい場合は、renderボタンの右にある小さい三角（▼）をクリックし、「Render PDF」を選択しよう。これ以降、ショートカットキーやrenderボタンを押すとPDFが出力される。HTMLに戻したい場合は、renderボタンの右にある小さい三角（▼）をもう一度選択してみよう。

　それでは細かい設定について紹介する。量が膨大になるため、HTMLに限定し、以下では筆者（宋）がよくいじる箇所のみ紹介する。詳細はQuartoの公式ホームページを参照されたい。PDFについては本章後半にて簡単に解説する。

フォーマット指定の例

format: 
  html:
    grid: 
      body-width: 1024px
    theme: lumen
    highlight-style: a11y
    toc: true
    toc-location: right
    toc-depth: 3
    number-sections: true
    embed-resources: false
    code-fold: false

　gridではサイドバー（sidebar-width）、本文（body-width）、右側の余白（margin-width）の幅が指定できる。それぞれ既定値は250、800、250であるが（単位はピクセル）、本文の幅が800だとやや窮屈に感じるので、1024くらいが良いかも知れない。また、サイドバーと本文、右側の余白の間の空間はガター（gutter）と呼ばれ、gutter-widthで指定できる。既定値はデフォルトのフォントサイズの1.5倍（1.5em）となっている。

　つづくthemeとhighlight-styleは文書の見た目と関係する。themeは文書全体、highlight-styleはコードのハイライトに関わる。Quartoは10種類以上のテーマとコードハイライトを提供するので、色々試しながら好みのテーマを見つけてみよう。

　つづいて、文書内目次に関連するtoc、toc-location、toc-depthについてた。tocは文書内目次の有無、toc-locationは目次の位置（既定値は右側）、toc-depthは目次の深度（既定値は3）だ。既定値のままが最もスタンダードがフォーマットとなるので、そもそもこちらは省略するケースも多い。

　他にもよく使うものとしてはnumber-sectionsがある。これは章・節の見出し（##や###など）の前に番号を付けるかを指定するものであり、既定値はfalseになっている。embed-resourcesは図、JavaScriptライブラリー、CSSなどHTMLファイル外のファイルを結果物のHTMLファイル内にすべて埋め込むものである。既定値はfalseだが、他人にHTMLファイルを共有するためにはtrueにしておくことを推奨する。しかし、様々なファイルがHTML内に埋め込まれるのでファイルのサイズが劇的に大きくなる。図表多めのHTMLファイルなら数十MBも普通にあるくらいだ。ただ、embed-resources: falseでも埋め込まれないJavaScriptライブラリーがある。数式のレンダリングを担当するMathJaxなどのライブラリーは非常に重いので、これをHTML内に埋め込みたい場合はself-contained-math: trueを別途指定する必要がある。最後にcode-foldはコードが多めであるものの、「コードよりも文章と結果がメインとなる文書、しかしコードを無くしたくはない」場合に有用なオプションだ。以下の例を見れば違いが分かるだろう。

Input：

`code-fold: false`の場合

```{r}
1 + 1
```

`code-fold: true`の場合

```{r}
#| code-fold: true
1 + 1
```

Output：

code-fold: falseの場合

1 + 1

[1] 2

code-fold: trueの場合

Code

1 + 1

[1] 2

　YAMLヘッダー内にcode-fold: tureを指定すると、全チャンクにcode-fold: trueが適用されることになる。

G.2.3 チャンクオプション

　前章で説明した通り、チャンク内には#| オプション名: 値でオプションの指定ができる。もし、全て（ほとんど）のチャンクに共通するオプションがあれば、個別のチャンクに指定することは非効率的だろう。全てのチャンクに適用されるオプションknitr: > opts_chunk:で指定できる。ここではチャンクオプションであれば何でも使えると思っても良い。たとえば以下の例を見てみよう。

チャンクオプション指定の例

knitr: 
  opts_chunk: 
    dev: ragg_png
    fig-align: center
    dpi: 144
    message: false

　以上の例だと、図の文字化けを未然に防ぐために図のエンジンは{ragg}のPNG（dev: "ragg_png"）、図は中央揃え（fig-align: center）、図の解像度は144DPI（dpi: 144）、コード実行から表示されるメッセージの非表示（message: false）を指定している。他にも様々なオプションが指定できる。たとえば、エラーが生じても強制的にレンダリングを続行させるためにerror: trueを指定することもできる。

G.2.4 YAML文法

　以上の内容だけでも大体のことはできるだろう。しかし、YAMLヘッダーで指定可能な内容はこれまで紹介してきた内容の数十倍だ（もしかしたら数百倍かも知れない）。詳細はQuarto公式ホームページのReferenceを参照されたい。ただし、公式ホームページには指定可能なオプションと取りうる値、その役割について記載されているだけである。これで足りるかも知れないが、YAMLの文法が分からない人はこの場合、戸惑うかも知れないので、これから紹介するYAMLの書き方を知っておくと良い。

　YAMLの基本的な書き方はキー: 値だ。format: htmlの場合、キー（key）がformat、値（value）がhtml（または"html"）となる。YAMLの場合、値が文字列でも"が強制されない。また、階層構造を示すためには字下げを使うことも覚えておこう。決まった基準はないが、半角スペース2〜3個が無難だろう。

　一つのキーに対し、値が2つ以上の場合、[]で囲み、,で区切る。たとえば、authorの値がJaehyunとYukiならauthor: ["Jaehyun", "Yuki"]となる。リストのもう一つの書き方は-である。author:の後に改行し、2〜3文字字下げをした上で各要素の前に-を付ける。つまり、以下のYAMLはauthor: ["Jaehyun", "Yuki"]と同じ内容だ。

author:
  - "Jaehyun"
  - "Yuki"

　YAMLの場合、値としてキー: 値を使うこともできる。つまり、authorの値としてname: "Jaehyun"を与えることもできる。しかしauthor: name: "Jaehyun"の書き方は通常ない。値の中にキーがあるということは、キーが複数ある時が一般的だろう。つまり、authorの値としてname: "Jaehyun"とaffiliation: "Kansai University"両方を与えることが多いだろう。このように2つ以上のプロパティ: 値をブロックとしてまとめる場合は以下のように{}を使用する。

author: {name: "Jaeyun", affiliation: "Kansai University"}

　もし、著者が二人以上であれば、これらを更に[]でまとめれば良い。

author: [{name: "Jaeyun", affiliation: "Kansai University"}, {name: "Yuki", affiliation: "Kochi University of Technology"}]

　しかし、一行が非常に長くなるので、-で改行しても良いだろう。

author: 
  - {name: "Jaeyun", affiliation: "Kansai University"}
  - {name: "Yuki", affiliation: "Kochi University of Technology"}

　また、{}内の要素も改行することができる。複数のキー: 値ペアをブロックとして扱う場合は、同じ階層で字下げをすれば良い。

author: 
  - name: "Jaeyun"
    affiliation: "Kansai University"
  - name: "Yuki"
    affiliation: "Kochi University of Technology"

　この[]と{}、改行と字下げを組み合わせることで構造化されたメタ情報を記述できる。

　以上の内容だけでも、YAMLヘッダーは書けるが、いくつか便利な機能も紹介しよう。まず、値が長い時には|か>を使用する。この2つは似たような役割を果たすが、微妙に異なる。

key1: >
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Quisque dictum lorem a tempor feugiat. Cras sit amet semper mi.

    Phasellus dignissim lobortis nisl, id varius metus.
key2: |
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Quisque dictum lorem a tempor feugiat. Cras sit amet semper mi.

    Phasellus dignissim lobortis nisl, id varius metus.

　key1には>が、key2には|が使われているが、>を使用する場合、全ての改行が無視され、一行扱いとなる。一方、|を使用する場合、改行も全て認識される。

　また、YAMLの場合、#を用いたコメント機能が付いている。メタ情報記述のためにも幅広く使われてきたJSON形式の致命的なデメリットがコメント機能の不在だったが、YAMLには以下のように#で説明を付けたり、コメントアウトができる。

author: 
  # 第一著者が夜逃げしたので、著者から消す
  #- name: "Jaeyun"
  #  affiliation: "Kansai University"
  - name: "Yuki"                                  # 土佐の猛猫
    affiliation: "Kochi University of Technology" # a.k.a KUT

G.3 QuartoにおけるMarkdown

　前章で紹介したMarkdownの文法は現存する多くのMarkdown文法の最大公約数であるGFM（GitHub Flavored Markdown）である。ただし、QuartoのMarkdownにはより多くの機能が備わっている。以下ではQuartoのMarkdownで出来る様々な便利なものを紹介する。

G.3.1 相互参照ついて

　図表の相互参照には@を使用する。たとえば、チャンクのラベルがfig-scatter1という図がある場合、@fig-scatter1だけで十分である。以下の例を見てみよう。

Input:

以下の @fig-scatter1 は萼片の長さと幅を品種ごとに分けて示した散布図である。

```{r}
#| label: fig-scatter1
#| echo: false
#| fig-cap: "萼片の長さと幅の関係（品種別）"
iris |>
  mutate(Species2 = recode(Species,
                           "setosa"     = "セトナ",
                           "versicolor" = "バーシクル",
                           "virginica"  = "バージニカ")) |>
  ggplot() +
  geom_point(aes(x = Sepal.Length, y = Sepal.Width, color = Species2)) +
  labs(x = "萼片の長さ (cm)", y = "萼片の幅 (cm)", color = "品種")
```

Output:

　以下の図 G.1 は萼片の長さと幅を品種ごとに分けて示した散布図である。

　図だけでなく、表や章でも同じやり方で相互参照ができる。ただし、一点注意が必要である。相互参照に使うチャンクのラベルに制約があることだ。相互参照の対象となるチャンクのラベルはsec-（章・節など）、fig-（図）、tbl-（表）、eq-（数式）で始まる必要がある。図表はチャンクラベルで指定できるが、章や節などの見出しの場合、以下のようにラベルを指定する。この書き方はチャンク以外の図表にラベルを付ける時も同様だ（後述）。

## Rの素晴らしさについて {#sec-aboutR}

　また、Quartoの既定値のままだと「Figure X」と出力される。これを「図 X」の形式にしたい場合はYAMLヘッダーにlang: jaを追加するか、language:で別途指定する必要がある⁵。

　続いて、Markdownで挿入した図（![]()）や表のラベルの付け方については後ほど解説する。

G.3.2 コールアウト

　Quartoでは5種類のコールアウト（callout）が提供される。以下はコールアウト作成のコードとその結果である。:::{.callout-*}と:::間の内容が一つのブロック（コールアウト）となり、##でブロックのタイトルを指定する。また、{}内の*の箇所にはブロックの見た目を指定し、現在、note、warning、important、tip、cautionの5種類がある。

Input:

:::{.callout-note}
## Rはみんなの友達!

末永くよろしくね!
:::

Output:

Rはみんなの友達!

末永くよろしくね!

Input:

:::{.callout-warning}
## Rはみんなの友達!

末永くよろしくね!
:::

Output:

Rはみんなの友達!

末永くよろしくね!

Input:

:::{.callout-important}
## Rはみんなの友達!

末永くよろしくね!
:::

Output:

Rはみんなの友達!

末永くよろしくね!

Input:

:::{.callout-tip}
## Rはみんなの友達!

末永くよろしくね!
:::

Output:

Rはみんなの友達!

末永くよろしくね!

Input:

:::{.callout-caution}
## Rはみんなの友達!

末永くよろしくね!
:::

Output:

Rはみんなの友達!

末永くよろしくね!

　.callout-*の後にcollapse="true"を付けるとコールアウトの本文を隠すことができる（見出しをクリックすると本文が表示される）。

Input:

:::{.callout-note collapse="true"}
## Rはみんなの友達!（クリック）

末永くよろしくね!
:::

Output:

Rはみんなの友達!（クリック）

末永くよろしくね!

　また、.callout-*の後にicon="false"を付けると見出しの左にあるアイコンを消すことができる。

Input:

:::{.callout-warning icon="false"}
## Rはみんなの友達!

末永くよろしくね!
:::

Output:

Rはみんなの友達!

末永くよろしくね!

G.3.3 段組み

　Quartoの段組みは非常に簡単だ。::::{.columns}と::::で囲まれた領域内の内容が段組みの対象となり、:::{.column}と:::で囲まれた領域が一つ一つの段となる。また、.columnの次にwidth引数を追加することで、段の幅を指定することもできる。以下はコードのその結果を2段構成で示した例だ。

Input:

::::{.columns}
:::{.column width=56%}
**コード:**

```{r}
#| eval: false
x <- c(1, 2, 3, 1, 2)
y <- c("A", "A", "A", "B", "B")

paste0(x, y)
```
:::

:::{.column width=2%}
:::

:::{.column width=42%}
**結果:**

```{r}
#| echo: false
x <- c(1, 2, 3, 1, 2)
y <- c("A", "A", "A", "B", "B")

paste0(x, y)
```
:::
::::

Output:

コード

x <- c(1, 2, 3, 1, 2)
y <- c("A", "A", "A", "B", "B")

paste0(x, y)

結果

[1] "1A" "2A" "3A" "1B" "2B"

G.3.4 パネル

　パネルは段組みのように複数の内容を同じ行に出力する機能であるが、段組みは左右に並べる一方、パネルが異なるページへ出力する。たとえば、データセットの作成と、そのデータを使った作図のコードを示す場合、2つのチャンクを横に並べるには幅が狭いかも知れない。この場合、使えるのがパネル機能だ。使い方は段組みより簡単で、:::{.panel-tabset}と:::間に入力された内容がパネル内容になる。各パネルのタイトルは##見出しで指定でき、これが各パネルの区切りにもなる。

Input:

:::{.panel-tabset}
## データ

```{r}
library(tidyverse)

my_data <- tibble(City = c("東京", "北京", "ソウル"),
                  Pop  = c(1396, 2154, 978))

my_data
```

## プロット

```{r}
#| fig-width: 8
#| fig-height: 4
my_data |>
  mutate(City = fct_inorder(City)) |>
  ggplot(aes(x = City, y = Pop)) +
  geom_col() + # geom_bar(stat = "identity") もOK
  labs(x = "都市", y = "人口（万人）") +
  theme_bw(base_size = 14)
```

:::

Output:

データ
プロット

library(tidyverse)

my_data <- tibble(City = c("東京", "北京", "ソウル"),
                  Pop  = c(1396, 2154, 978))

my_data

# A tibble: 3 × 2
  City     Pop
  <chr>  <dbl>
1 東京    1396
2 北京    2154
3 ソウル   978

my_data |>
  mutate(City = fct_inorder(City)) |>
  ggplot(aes(x = City, y = Pop)) +
  geom_col() + # geom_bar(stat = "identity") もOK
  labs(x = "都市", y = "人口（万人）") +
  theme_bw(base_size = 14)

G.3.5 図表について

　多くの図は{ggplot2}、{lattice}、Base Rなどで作成され、表は{knitr} + {kableExtra}、{gt}などで作成される。しかし、通常のMarkdown文法で表を作ったり、図を挿入したりするケースも多いだろう。QuartoはMarkdown文法の作成/挿入された図表のカスタマイズもより柔軟だ。

　たとえば、図の大きさは![]()の後ろに{}を付け、widthやheight引数を指定することで修正できる。たとえば、図の幅を100ピクセルにする場合はwidth=100pxで良い。サイズの指定方法はピクセル（px; 省略可）以外にも画面の幅に対する割合（例：50%）、インチ（例：4in）もできる。

サイズ調整前
サイズ調整後

Input:

![『私たちのR』ロゴ](http://www.jaysong.net/RBook/Figs/favicon.png)

Output:

『私たちのR』ロゴ

Input:

![『私たちのR』ロゴ](http://www.jaysong.net/RBook/Figs/favicon.png){width=100px}

Output:

『私たちのR』ロゴ

　他にも、![Alt Text](Image Path)で挿入される図の場合、R Markdownでは大きさの調整や中央揃えが面倒だ。しかし、Quartoの場合、後ろに{}を入れることでいくつかの修正ができる。

Input:

![『私たちのR』ロゴ（左揃え）](http://www.jaysong.net/RBook/Figs/favicon.png){fig-align="left"}

Output:

『私たちのR』ロゴ（左揃え）

Input:

![『私たちのR』ロゴ（中央揃え）](http://www.jaysong.net/RBook/Figs/favicon.png){fig-align="center"}

Output:

『私たちのR』ロゴ（中央揃え）

Input:

![『私たちのR』ロゴ（右揃え）](http://www.jaysong.net/RBook/Figs/favicon.png){fig-align="right"}

Output:

『私たちのR』ロゴ（右揃え）

　他にも複数のグラフを並べることもR Markdownに比べ、簡単にできる。横に並べるなら段組みでもよいが、:::{layout-ncol}がより楽だ。ncolの代わりにnrowも指定できる。以下のコードは図を3列配置する例だ（モバイルデバイスの場合、縦に並ぶように表示される）。

Input:

:::{layout-ncol=3}
![左の猫](http://www.jaysong.net/RBook/Figs/favicon.png)

![中央の猫](http://www.jaysong.net/RBook/Figs/favicon.png)

![右の猫](http://www.jaysong.net/RBook/Figs/favicon.png)
:::

Output:

左の猫

中央の猫

右の猫

　図の相互参照とためのラベルは![]()の後ろの{}内に#fig-で指定できる。並べた図にラベルを付けることもできる。

Input:

* 複数の図の相互参照: @fig-three-cats
* 個別の図の相互参照: @fig-cat1

:::{#fig-three-cats layout-ncol=3}
![左の猫](http://www.jaysong.net/RBook/Figs/favicon.png){#fig-cat1}

![中央の猫](http://www.jaysong.net/RBook/Figs/favicon.png){#fig-cat2}

![右の猫](http://www.jaysong.net/RBook/Figs/favicon.png){#fig-cat3}

3匹の猫
:::

Output:

複数の図の相互参照: 図 G.3
個別の図の相互参照: 図 G.3 (a)

(a) 左の猫

(b) 中央の猫

図 G.3: 3匹の猫

　:::{layout-ncol}を使えば、複数の表を並べることもできる。相互参照についても同じだが、ラベル名は#fig-の代わりに#tbl-を使う必要がある。

Input:

　@tbl-two-tables は、東アジアとヨーロッパ主要都市の人口、面積、人口密度の一覧である。ただし、 @tbl-east-asia の東京は23区でなく、東京都全域であることに注意されたい。

::: {#tbl-two-tables layout-ncol=2}
| Name    | Pop.  | Area   | Density |
|:--------|------:|-------:|--------:|
| Tokyo   | 1,403 |  2,194 |  6,397  |
| Beijing | 2,170 | 16,410 |  1,323  |
| Seoul   |   949 |    605 | 15,688  |

: East Asia {#tbl-east-asia}

| Name   | Pop.  | Area  | Density |
|:-------|------:|------:|--------:|
| London | 943   | 1,569 |  5,354  |
| Berlin | 367   |   892 |  4,114  |
| Paris  | 215   |   105 | 20,382  |

: Europe {#tbl-europe}

首都の人口（万人）、面積（km<sup>2</sup>）、人口密度（人/km<sup>2</sup>）
:::

Output:

　表 G.1 は、東アジアとヨーロッパ主要都市の人口、面積、人口密度の一覧である。ただし、表 G.1 (a) の東京は23区でなく、東京都全域であることに注意されたい。

表 G.1: 首都の人口（万人）、面積（km²）、人口密度（人/km²）

(a) East Asia

Name	Pop.	Area	Density
Tokyo	1,403	2,194	6,397
Beijing	2,170	16,410	1,323
Seoul	949	605	15,688

(b) Europe

Name	Pop.	Area	Density
London	943	1,569	5,354
Berlin	367	892	4,114
Paris	215	105	20,382

　また、この機能はチャンクで生成された図についても使用可能だ。チャンクオプションに#| layout-ncol: 2を追加すると、2つの図が横に並ぶことになる。ただし、相互参照の際、個別の図のラベルはこちら側では指定できず、自動生成される。たとえば、プロット群のラベルがfig-two-plotsなら1つ目の図のラベルはfig-two-plots-1、2つ目はfig-two-plots-2となる。

Input:

　@fig-two-plots は2つの散布図であり、 @fig-two-plots-1 は速度と停止距離との関係、 @fig-two-plots-2 は気温と気圧の関係を示す。

```{r}
#| label: fig-two-plots
#| echo: false
#| layout-ncol: 2
#| fig-cap: "散布図の例"
#| fig-subcap: 
#|   - "速度と停止距離"
#|   - "気温と気圧"
cars |>
  ggplot(aes(x = speed, y = dist)) +
  geom_point() +
  labs(x = "Speed (mph)", y = "Stopping distance (ft)")

pressure |>
  ggplot(aes(x = temperature, y = pressure)) +
  geom_point() +
  labs(x = "Temperature (Celsious)", y = "Pressure (mm)")
```

Output:

　図 G.4 は2つの散布図であり、図 G.4 (a) は速度と停止距離との関係、図 G.4 (b) は気温と気圧の関係を示す。

G.3.6 数式のラベル

Input：

　ポアソン分布の確率密度関数（@eq-poisson）は美しいぞ。

$$
p(x) = \frac{e^{-\lambda} \lambda^{x}}{x !}
$$ {#eq-poisson}

Output：

　ポアソン分布の確率密度関数（式 G.1）は美しいぞ。

\[ p(x) = \frac{e^{-\lambda} \lambda^{x}}{x !} \tag{G.1}\]

G.3.7 ハイパーリンクのターゲット

　Markdownのハイパーリンクは以下のように書く。

[ここ](https://www.jaysong.net)をクリックすると宋のホームページへ移動します。

　「ここ」の文字をクリックすると宋のホームページへ飛ばされるコードだが、デフォルト状態では、既存のウィンドウ/タブを使うことになる。これを新しいウィンドウ/タブで開かせるためには、[]()の後ろに{target="_blank"}を付ければ良い。

[ここ](https://www.jaysong.net){target="_blank"}をクリックすると宋のホームページへ移動します。

G.3.8 参考文献

　「宋・矢内（2020）」のように参考文献を「著者名（年）」で出力し、その書誌情報を文末にまとめるためには2つを準備する必要がある。1つ目は書誌情報が記録されているファイルを作成することであり、2つ目はYAMLヘッダーの修正だ。書誌情報は.bib拡張子のファイルで管理される。たとえば、reference.bibという名のファイルが.qmdファイルと同じフォルダーに位置し、reference.bibの中身は以下の通りであるとする。

references.bibの中身

@book{Grolemund_Wickham:2016,
  title     = {R for Data Science},
  author    = {Grolemund, Garrett and Wickham, Hadley},
  year      = {2016},
  publisher = {O'Reilly}
}

@article{Wickham:2014,
  title     = {Tidy Data},
  author    = {Wickham, Hadley},
  year      = {2014},
  journal   = {Journal of Statistical Software},
  volume    = {59},
  issue     = {10},
  pages     = {1-23}
}

　\(\LaTeX\)ユーザーなら以上の書き方に違和感はないだろうが、初めての方はGoogle等で「bibtex 書き方」で検索してみよう。ちなみに{の直後に出る文字列（ここではGrolemund_Wickham:2016とWickham:2014）がラベルであり、当該文献を呼び出す時のキーとなる。

　.bibファイルの準備ができたら、.qmdファイルのYAMLヘッダーを修正する必要がある。書き方は簡単であり、bibliographyフィールドに書誌情報が格納されている.bibファイルのパスを書けば良い。reference.bibファイルが.qmdファイルが同じフォルダーに保存されているなら、bibliography: references.bibで良い。もし、bib_folderという下位フォルダーに保存されているなら、bibliography: bib_folder/references.bibのように書く。

---
title: なぜ私がヘルムシュテット大学に...?
author: カール・フリードリヒ・ガウス
date: 1855/2/23
format: html
bibliography: references.bib
---

　これで参考文献の挿入の準備はできた。後は「著者名（年）」を入れる箇所に@ラベルを入れるだけだ。たとえば、@Grolemund_Wickham:2016は「Grolemund and Wickham (2016)」のように出力される。他にも以下のような書き方もあり、[@ラベル]のような書き方や[@ラベル1; @ラベル2]はよく使うことになるだろう。

Input

@Grolemund_Wickham:2016

[@Grolemund_Wickham:2016]

[@Grolemund_Wickham:2016; @Wickham:2014]

[see @Wickham:2014, pp. 11-12]

Output

Grolemund and Wickham (2016)

(Grolemund and Wickham 2016)

(Grolemund and Wickham 2016; Wickham 2014)

(see Wickham 2014, 11–12)

　ちなみに、lang: jaにすると、「Grolemund and Wickham 2016」が「GrolemundとWickham 2016」になる。余計な翻訳だが、これが気になる場合はYAMLヘッダーからlang:jaを駆逐しよう。

G.4 日本語が含まれたPDF

G.4.1 日本語PDFの生成

　Quartoで文書を作成する際、出力フォーマットはHTMLかPDFだろう。いずれもYAMLヘッダーのformat:をhtmlかpdfにすることで簡単に出力フォーマットが指定できるが、日本語が含まれたPDFの場合、文字化けが生じる可能性が高い。

　PDFで出力する場合、{tinytex}パッケージとtinytex::install_tinytex()で\(\LaTeX\)環境はインストール済みであろう。日本語が含まれたPDFを作成する場合、以上の作業に加え、日本語フォントもインストールする必要がある⁶。\(\LaTeX\)デフォルトの和文フォントである原ノ味（Haranoaji）をインストールする。ここでも数分かかる可能性がある⁷。

tinytex::tlmgr_install("haranoaji")

　以上の作業はRの再インストール、またはメジャーアップデートをしない限り、1回だけで良い。つまり、通常のパッケージ同様、別のプロジェクトであっても以上の作業は不要だ。これで日本語PDFの準備はバッチリだ。.qmdファイルのYAMLヘッダーを以下のように修正してみよう。

---
title: "私たちのR"
subtitle: "ベストプラクティスの探求"
author: "土佐の猛猫"
date: today
# PDF設定
format:
  pdf:
    pdf-engine: lualatex
    documentclass: ltjsarticle
# チャンクのオプション
knitr: 
  opts_chunk: 
    dev: ragg_png
---

　デフォルト設定との違いはPDFエンジンがLuaLaTeXであること、そしてドキュメントクラスがltjsarticleであることだ。pLaTeXやupLaTeXを使ってきた読者ならお馴染みのjsarticleのLuaLaTeXバージョンがltjsarticleである。一つ注意事項としては日本語文書であってもlang: jaは指定しないこと。これを指定する場合、hyphen-japaneseという名のLaTeXパッケージをインストールしようとするが、この名前のパッケージはCTANに存在しないため、エラーが発生する。

　以上のオプション2つだけでの日本語の出力は問題ないが、図が含まれる場合、図内の日本語が文字化けする可能性もある。簡単な解決方法は画像エンジンをAGGにし、PNGフォーマットにすることだ。knitr: > opts_chunk: > dev: ragg_pngにすると図の文字化けの悩みから開放される。ただし、印刷する時に解像度が気になるので、解像度（dpi）に高めにすることをおすすめする。最低でも300は欲しいが、筆者（宋）の推奨は450だ（dpi: 450）。

　以下の例は筆者（宋）がよく使うYAMLヘッダーのベースである。

---
title: "私たちのR"
subtitle: "ベストプラクティスの探求"
author:
  - name: 宋財泫
    url: https://www.jaysong.net
    affiliation: 関西大学
  - name: 矢内勇生
    url: https://yukiyanai.github.io/
    affiliation: 高知工科大学
    attributes:
      corresponding: true
date: today
# PDF設定
format:
  pdf:
    pdf-engine: lualatex
    documentclass: ltjsarticle
    classoption:
      - a4paper
      - 10pt
    toc: false
    toc-depth: 3
    number-sections: true
knitr: 
  opts_chunk: 
    dev: ragg_png     # 文字化け防止
    dpi: 450          # 高解像度の図を使用（サイズ大きめ）
    fig-align: center # 図は中央揃え
    warning: false    # 警告メッセージを消す
    message: false    # 通常メッセージを消す
---

　以上の例ではLuaLaTeXとltjsarticleクラスを組み合わせた紹介したが、ltjsbookなどのクラスも使用可能であり、エンジンもまたLuaLaTeX以外のエンジンを使用しても良い。日本語PDFを作成する際、よく使われるエンジンとしてLuaLaTeX以外にもXeLaTeX（xelatex）、Latexmk（latexmk）などがある。ただ、こちらはLuaLaTeXよりもやや面倒であるため、LaTeXの知識があまりない読者であれば、本章で紹介したLuaLaTeXで十分だろう。

　.qmdファイル内にはMarkdown文法だけでなく、\(\LaTeX\)文法も使える。たとえば、文字をイタリックにするために*Italic*でも、\emph{italic}でも良い。\(\LaTeX\)の方がMarkdownよりも機能が豊富なので、Markdownで対応されない機能は\(\LaTeX\)を使えば良いだろう。

　この場合、いくつかの\(\LaTeX\)パッケージが必要になるかも知れない。\(\LaTeX\)の場合、.texファイルのヘッダーの方に\usepackage{パッケージ名}と書く必要があるが、これをYAMLヘッダー内で指定するためにはinclude-in-header:キーを使う必要がある。ここにはパッケージの読み込みだけでなく、ヘッダーに入れておきたいあらゆる\(\LaTeX\)コードが使える。

format:
  pdf:
    pdf-engine: lualatex
    documentclass: ltjsarticle
    classoption:[a4paper, 10pt]
    include-in-header:
      - text: |
          \usepackage{luatexja-fontspec}
          \usepackage[ipa]{luatexja-preset}
          \setmainfont[Ligatures=TeX]{Times New Roman}
    keep-tex: true

　もし、|以降の内容が長い場合、別途の.texファイルにパッケージ読み込みの内容を記録して保存し、- text: | ...の代わりに、- file: ファイル名.texを使った方が良いだろう。

G.4.2 参考文献の話

　\(\LaTeX\)で文書を作成する際、参考文献の管理・挿入はBibTeXを使うケースがほとんどだろう。.bibファイルに各種文献の書誌情報が構造化された形で記録されており、自動的に文末に参考文献一覧を作成してくれるすぐれものだ。また、スタイルファイル（.bst）を変更すれば様々なジャーナルに適した形式の参考文献目録に変換される。

　日本語の参考文献の場合、日本語の参考文献に適したスタイルファイルを使用する必要があるが、社会科学における定番がjecon.bst（経済学用のBibTeX style file）というスタイルである。しかし、Quartoにおいてこのjecon.bstがうまく動かないため、裏技を使う必要がある。以下の内容は（1）.latexmkrcの修正ができ、かつ（2）これまでjecon.bstを使ったことがある読者のための内容である。

　以下はYAMLヘッダーのformat箇所の中でjecon.bstの仕様に関わる箇所のみ抜粋した例である。

format: 
  pdf:
    pdf-engine: latexmk
    latex-auto-mk: false
    pdf-engine-opts: 
      - -lualatex
      - -outdir=
      - -jobname=output
    documentclass: ltjsarticle
    cite-method: natbib
    biblio-style: jecon.bst
bibliography: references.bib

　まず、pdf-engine: latexmk：使用するエンジンをLatexmkにする。しかし、デフォルトの設定ではQuarto側（厳密にはTinyTeX側）が自動的にLatexmkの設定を行う。これをQuartoに任せず、予め自分が設定したLatexmkを使わせるためにはlatex-auto-mk: falseを指定する必要がある。Latexmkの設定は.latexmkrcファイルに記載されているが、以下は筆者（宋）の.latexmkrcである。

宋の.latexmkrc

#!/usr/bin/env perl
if ($^O eq 'MSWin32') {
  $latex = 'uplatex %O -kanji=utf8 -no-guess-input-enc -synctex=1 %S';
  $pdflatex = 'pdflatex %O -synctex=1 %S';
  $lualatex = 'lualatex %O -synctex=1 %S';
  $xelatex = 'xelatex %O -synctex=1 %S';
  $biber = 'biber %O --bblencoding=utf8 -u -U --output_safechars %B';
  $bibtex = 'upbibtex %O %B';
  $makeindex = 'upmendex %O -o %D %S';
  $dvipdf = 'dvipdfmx %O -o %D %S';
  $dvips = 'dvips %O -z -f %S | convbkmk -u > %D';
  $ps2pdf = 'ps2pdf.exe %O %S %D';
  $pdf_mode = 3;
  if (-f 'C:/Program Files/SumatraPDF/SumatraPDF.exe') {
    $pdf_previewer = '"C:/Program Files/SumatraPDF/SumatraPDF.exe" -reuse-instance';
  } elsif (-f 'C:/Program Files (x86)/SumatraPDF/SumatraPDF.exe') {
    $pdf_previewer = '"C:/Program Files (x86)/SumatraPDF/SumatraPDF.exe" -reuse-instance';
  } else {
    $pdf_previewer = 'texworks';
  }
} else {
  $texoption = ' %O -interaction=nonstopmode -file-line-error -synctex=1 %S';
  $latex = 'uplatex'.$texoption;
  $pdflatex = 'pdflatex'.$texoption;
  $lualatex = 'lualatex %O -synctex=1 %S';
  $lualatex = 'lualatex'.$texoption;
  $xelatex = 'xelatex'.$texoption;
  $biber = 'biber %O --bblencoding=utf8 -u -U --output_safechars %B';
  $bibtex = 'upbibtex %O %B';
  $makeindex = 'upmendex %O -o %D %S';
  $dvipdf = 'dvipdfmx %O -o %D %S';
  $dvips = 'dvips %O -z -f %S | convbkmk -u > %D';
  $ps2pdf = 'ps2pdf %O %S %D';
  $max_repeat = 5;
  $pvc_view_file_via_temporary = 0;
  $pdf_mode = 1;
  $pvc_view_file_via_temporary = 0;
  if ($^O eq 'darwin') {
    $pvc_view_file_via_temporary = 0;
    $pdf_previewer = 'open -ga /Applications/Preview.app';
  } else {
    $pdf_previewer = 'xdg-open';
  }
}

　つづいて、pdf-engine-optsでLatexmkのオプションを設定する。使用エンジンをLuaLaTeXにし（-lualatex）、生成されたPDFを.qmdファイルと同じ箇所に保存する（-outdir=）ように設定した。-outdir=outなどにすると、outというフォルダーにPDFが保存される。それでは.qmdと同じ箇所に保存するならそもそも-outdir=が不要なのではないかと思うかも知れないが、これを省略するとPDFファイルが生成されない（理由は不明）。最後に-jobname=outputは、生成されるPDF名をoutput.pdfという意味だ。好きな名前を付けよう。もし、-jobname=を省略した場合、input.pdfという名のPDFが生成される（理由は不明）。

　ドキュメンののクラス（documentclass）はltjsクラスなら何でも良い。論文ならltjsarticle、書籍ならltjsreportかltjsbookで良いだろう。参考文献のスタイルのキーはbiblio-styleであり、スタイルファイル（.bst）のパスを書く。jecon.bstの場合、natbibという\(\LaTeX\)のパッケージを必要とするため、cite-method: natbibを加える。最後に参考文献の書誌情報が記録されている.bibファイルをbibliographyで指定するが、こちらは上記の例のようにformatと同じ階層でも良いし、biblio-styleと同じ階層でも良い。

　以上の設定でレンダーするとoutputというフォルダー内にPDFが生成される。しかし、この方法はレンダー時、時々エラーが表示され気持ち悪かったり、生成されたPDFファイルがRStudioのViewerペインに表示されなかったりなどいくつかの短所がある。以上の内容は現時点での筆者（宋）の使い方であり、今後、より簡単な方法が提案されるかも知れない。

最低限の機能といっても、言い換えれば「あまり使わないパッケージをインストールしない」だけである。tinytex::tlmgr_install()を使えばパッケージの追加もできるため、通常の\(\LaTeX\)環境でできるものが{tinytex}だとできないことはない。↩︎
.qmdファイルの最上段でなく、別途のファイル（たとえば、_quarto.yml）で指定する場合もある。YAMLヘッダーの内容が長かったり、複数の.qmdファイルが同じYAMLヘッダーを共有したりする場合に使う。↩︎
書籍やウェブサイトなどの特殊なタイプでないのであれば、ここは省略されるケースが多い。↩︎
実はこれらすらなくても良い。↩︎
一つややこしいのが見出しの相互参照である。英語のままだと「Section 1」のように出力されるが、lang:jaで日本語化すると「セクション 1」のように表示される。これを「第1章」にしたい場合は、第[-@sec-aboutR]章のように書く必要がある。[-@ラベル名]にすると「Section」、「セクション」、「Figure」、「図」などを出力せず番号のみが出力される。↩︎
原ノ味フォントでなく、NotoやIPAexフォントを使用する場合でもなぜか原ノ味フォントが要求されるので、原ノ味フォントを使用する予定がなくてもインストールしておこう。↩︎
最初のチャンクにif (!("haranoaji" %in% tinytex::tl_pkgs())) tinytex::tlmgr_install("haranoaji")を入れておき、#| include: falseで非表示にしておくのも良いかも知れない。これは原ノ味フォントのインストール有無をチェックし、未インストールの場合のみインストールするコードだ。使用するR環境が複数であれなら、こちらの方が安全かも知れない。ただし、tinytex::tl_pkgs()関数はやや重いのでレンダリング時間が若干長くなる。↩︎