RMarkdownユーザーのためのQuarto

ニッタ ジョエル


Bio"Pack"athon 2014 #12


https://joelnitta.github.io/2024-12-11-biopack

自己紹介：@joelnitta

  • 千葉大学 准教授
  • シダ植物の進化と生態学
  • Rパッケージ開発
    （進化生態学向け）

https://www.joelnitta.com

Image of Joel Nitta in field

誰のためのお話？

  • RMarkdownを使っていて、Quartoに興味がある方
  • Quarto初心者の方

注意

  • Quartoは非常に大きなプロジェクトで、この発表ではとても全部をカバーすることができません。

  • 私はエキスパートではありません。まだ学んでいる最中です。

  • 分からないことがあれば、公式サイトを参考にしてください https://quarto.org/

アウトライン

  • Quartoとは？
  • QuartoとRMarkdownの違い
  • Quartoの活用例
  • 注意点

Quartoとは？

Quartoとは？

  • Rなどの計算結果を文章に直接組み込めるツール
  • 様々な出力形式に対応
  • RMarkdownの後継

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.

なぜQuartoを使うべきか？

  • ① RMarkdownよりも楽で、機能が豊富だから
    • RMarkdownでは目的ごとに異なるパッケージが必要でした：
      • {blogdown} (ブログ)
      • {xaringan} (スライド)
      • {distill} (ウェブサイト)
      • {officedown} (MS Word)
      • {rticles} (学術論文)
  • Quartoだけでこれがすべて可能です！

なぜQuartoを使うべきか？

  • ② 複数のプログラミング言語が使える
    • R
    • Python
    • Julia
    • Observable JS

Quartoのインストール

  • RStudioとバンドルされており、基本的な操作はRStudioだけで可能
  • 更新時は個別にインストールが必要（RStudioの更新では自動更新されません）
  • https://quarto.org/docs/get-started/から簡単にインストールできます

Quartoの使い方

  • ファイル拡張子は.qmd
  • 基本的にはRMarkdownファイルの記述方法とほぼ同じ
    • .rmdファイルの拡張子を.qmdに変えるだけで、ほとんどの場合そのまま動作します

QuartoとRMarkdownの違い

QuartoはRとは独立したツール

  • Quarto CLIが必要（RMarkdownはRパッケージ）
  • Pandoc（文書形式を変換するソフト）を基盤としています

Quarto is an open-source scientific and technical publishing system built on Pandoc

チャンクオプションの記述法

  • チャンクオプションは { } の中に書くのではなく、#| コメントを使い、YAML形式で記述します

R Markdown

```{r, fig-airquality, fig.cap="Temperature and ozone level.", warning=FALSE}

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

Quarto

```{r}
#| label: fig-airquality
#| fig-cap: "Temperature and ozone level."
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

Quarto YAML

  • QuartoのYAML設定はRMarkdownとは若干異なります
    • 単語間の区切り記号は_（アンダースコア）ではなく-（ハイフン）
    • キーが違う場合があります。例：RMarkdownのoutputはQuartoではformat

R Markdown

title: "My Document"
output:
  html_document:
    toc: true
    number_sections: true
    css: styles.css

Quarto

title: "My Document"
format:
  html:
    toc: true
    number-sections: true
    css: styles.css

レンダー方法

Rとは独立しているため、rmarkdown::render()ではなくCLIで実行します：

quarto render

（{quarto}パッケージのquarto_render()関数はラッパーです）

Fenced Divの使い方

  • Fenced Divとは、カスタムHTML要素や特定のスタイル、レイアウトを適用するための柔軟な仕組みです。
    • 元々はPandocで始まった記述法で、裏ではHTMLのdivと同じものです。
    • CSSファイルを指定することで、カスタムなdivを作成可能です。
      • 例：文字の色やサイズを指定する
  • :::で始まり、また:::で終わります（:は三つ以上必要）。
  • 例えば、スライドショーでは{.incremental}を使用すると、内容が一つずつ現れるスタイルを適用できます。

コード

::: {.incremental}

- ラーメン
- 餃子

:::

出力

  • ラーメン
  • 餃子

Shortcodeの使い方

  • Shortcodeは「様々な要素を挿入する」ための仕組みで、Fenced Divと似ています。

  • 書き方の例：{{< meta title >}} と記述すると、現在の文章のタイトルを返します。

  • 他のShortcodeの例:

    • pagebreak: 改ページを挿入する
    • video: ビデオを挿入する
    • include: 別のQmdファイルの内容を挿入する

コード

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

出力

Quartoの活用例

発表

LaTeXなしのPDF（Typst）

Screenshot of a page showing a article styled according IEEE standards. The title is centered with authors below in two columns.

IEEE

Screenshot of a poster in landscape orientiation. The poster includes a logo in the top right, a title in the top left, and content arranged in three columns.

Poster

Screenshot of a page showing a letter. A sender address is across the top of the page, followed by a recipient address left justified. The body of the letter includes a subject line in bold.

Letter

Screenshot of a page showing a department newsletter. The page is split vertically with a white column on the left and a red one on the right. An image spans across the column with the text "Award Winning Science" oriented to run vertically down its right side.

Dept News

他言語ウェブサイト

ダッシュボード

Screenshot of a Stock Trader dashboard: a row of three values boxes, then a row with a stock ticker graph and a table of closing values. Navy blue and green theme.

Screenshot of a Customer Churn dashboard: a row of three values boxes, then a row with two plots, then a row with a table. Light blue and yellow theme.

Screenshot of a Palmer Penguins dashboard: a sidebar with checkboxes and a dropdown, and two plots in main panel. Blue theme.

WebR

コード

```{webr}
fit = lm(
  mpg ~ am,
  data = mtcars)
summary(fit)
plot(fit)
```

出力

Extensions

  • Extensionsとは、Quartoの機能を拡張するためのコードです。

  • プロジェクトごとにインストールが必要です（Gitのサブモジュールのようなものです）。

  • 多くのExtensionsが公開されています！ https://quarto.org/docs/extensions/

  • quarto add <gh-org>/<gh-repo> で追加可能
    • 例：quarto add _extensions/schochastics/academicons
    • 追加したコードはコミットするのがおすすめです

Extensionsの例：academicons

Google Scholar [{{< ai google-scholar >}}](https://scholar.google.com/citations?hl=en&user=FtzrMYwAAAAJ)

Google Scholar

注意点

キーが分からないときは検索バーを活用する

  • https://quarto.org/ で検索し、使用したいフォーマットのドキュメンテーションを確認してください。

  • 同じキー（例：title）でも、出力フォーマットにより使い方が異なる場合があります。

CSS（とSCSS）を少し勉強するとよい

様々なYAMLが存在する

  • コードチャンク内のYAML
  • 文書（Qmdファイル）ヘッダーのYAML
  • プロジェクトの_quarto.yml
  • その他も
  • 使い分けに慣れる必要があります。

まとめ

  • QuartoはRMarkdownの後継です。
  • Quartoの機能は非常に豊富で、デザインも洗練されています。
  • 機能が多いため全貌を把握するのが難しい場合もあります。
  • 小さなプロジェクトから試してみるのがおすすめです！