🦝

Quartoを触ってみる

2023/02/19に公開

jupyter

quarto

tech

先週に引き続き、機械学習の実験環境について使えそうなものを調べてみた。
先週の記事：

Notebooksを使って実験レポートを作るための便利なツールを知ったので、ちょっと触ってみてどう便利か書いてみる。

TL; DR

Jupyter Notebooksなどで作る実験レポートをHTMLなどに見やすく出力できる
表示オプションなど豊富にあって手間をかけずに綺麗なレポートを作れる
成果物をHTMLなど一般的なフォーマットにできるので、他のサービスとの相性良さそう
（CLIで操作するだけなので”レポート生成用コンテナ（ポッド）”みたいなのも作りやすそう）

Quarto

https://quarto.org/

QuartoはPythonやR、Juliaなどの主に実験に使われる言語をサポートした、レポートを作るためのツールらしい。下の画像では、Pythonで静的なテキストと動的に生成するグラフを含んだレポートを生成している。

今のところの理解では、Jupyter Notebooksに対して以下のような利点がありそう。

"実験レポート"として見やすい
Figure 1など図表を簡単に引用できる
図表にラベル、キャプションなどのメタデータを付けられる
HTML、PDFなどで出力できる
（単純に"レポート"であればコード部分をいじる必要がないので、他の部分が見やすそう）

逆に欠点としては、

レポート内でコード実行ができない
（生成したものは静的なHTMLなどのファイルのため）

のようなものが挙げられる。

Get Started

Quarto CLIのインストール

https://quarto.org/docs/get-started/

各OSにあったCLIをダウンロード・インストールする。
今回はUbuntu（WSL2）にインストールした。

wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.2.335/quarto-1.2.335-linux-amd64.deb
sudo apt install ./quarto-1.2.335-linux-amd64.deb

また、開発環境はJupyter Labを選択した（Neovimもサポートしているの素晴らしい！あとでじっくり環境作ろ...）

Hello world

まずは手を動かしてどんなもんか見てみる。

コード

初めのほうに載せた例を実行してみる。

hello.ipynb

---
title: "matplotlib demo"
format:
  html:
    code-fold: true
jupyter: python3
---

For a demonstration of a line plot on a polar axis, see @fig-polar.

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()

HTML生成

インストールしたQuarto CLIから以下のコマンドでHTMLを生成する。

# コマンド
quarto render hello.ipynb --to html

# 出力
pandoc
  to: html
  output-file: hello.html
  standalone: true
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png

metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  title: matplotlib demo
  jupyter: python3

Output created: hello.html

コマンドを実行するとhello.htmlとhello_filesというディレクトリが生成される。HTMLの方はレポートで、ディレクトリはPythonコード部分で生成した画像ファイルやcss, jsが格納されている。
（なので当たり前だがHTMLだけでなく画像、CSSも一緒に管理する必要がある）

hello_files/
├── figure-html
│   └── fig-polar-output-1.png
└── libs
    ├── bootstrap
    │   ├── bootstrap-icons.css
    │   ├── bootstrap-icons.woff
    │   ├── bootstrap.min.css
    │   └── bootstrap.min.js
    ├── clipboard
    │   └── clipboard.min.js
    └── quarto-html
        ├── anchor.min.js
        ├── popper.min.js
        ├── quarto-syntax-highlighting.css
        ├── quarto.js
        ├── tippy.css
        └── tippy.umd.min.js

実際に生成できたレポートは以下の画像のようなもの。
（コードはデフォルトで折りたたまれているので見やすい）

表示オプション

ipynbファイルの先頭部分にYAMLでQuartoの各種設定を書くことができ、それによって生成されるレポートが変化する。
詳しくはリファレンスを参照。（下はHTML用）

execute

実行オプション。
Jupyterを使っている場合は、デフォルトで”既に実行されている結果”がレンダリングされる。つまり、Jupyter上で実行されていないものは結果が空白のままコードのみが表示されてしまう。
そこで以下の--executeオプションを付けるとレンダリングする前に一度全てのセル（コードブロック）を実行してくれる。

コマンドから

quarto render hoge.ipynb --execute

コード内から

---
title: "matplotlib demo"
execute:
  enabled: true
---

あと、execute内でecho: falseとするとコード部分をそもそも表示しないこともできる。

code-fold

コードの折り畳み。
上の方で「デフォルトでコードが折りたたまれて見やすい」といっていたが、このオプションの効果
だった。コード内のYAMLから設定可能。

title: "matplotlib demo"
format:
  html:
    code-fold: true

表示系のオプションはformat以下に固まっていそうなので、リファレンスで眺めると便利なものが見つかりそう。

複数の図

図表に対して以下のようなメタデータを付与することで簡単にキャプションなどを付けられ、それを参照することもできる。（下は複数の図に対してキャプションを設定している）

複数の図のキャプション設定

#| label: fig-gapminder
#| fig-cap: Life Expectancy and GDP
#| fig-subcap:
#|   - "Gapminder: 1957"
#|   - "Gapminder: 2007"
#| layout-ncol: 2
#| column: page

これら以外にも色々便利な表示設定があるっぽい。

bibliography（bibファイルを参照してReferenceを勝手に作ってくれる）
metadata-files（先頭のYAMLを別ファイルにできるの、テンプレートが作れる）

かなり豊富なので大抵のものは探せばありそう。