Gribouille 0.3.0 リリース：ガイド制御の強化と

compose()

のテーマ機能

Gribouille の新版本 0.3.0 がリリースされました。今回のバージョンは範囲が狭められつつも、特に「ガイド（axes や legends）の制御」機能を大きく強化しています。

🚀 主な変更点一覧

• ガイドの簡易制御:

  theme()

  を通じた複雑な設定を不要にし、単一の引数で刻み線や凡例を消せるようになりました。

• compose()

  のテーマ統合: コンポジション全体の装飾要素を一度に定義可能になり、パネル間でカスケード適用がスムーズになりました。

• defer()

  構文の刷新:

  plot(..., defer: true)

  が非推奨となり、

  defer(plot, ...)

  が新しい標準となりました。

• geom-area()

  のデフォルト挙動変更: スタック描画とアライメントがデフォルトになり、異なる X 値を持つデータの再サンプリングが自動化されました。

• annotate()

  のクリップ機能:

  clip: false

  オプションにより、パネル範囲を超えてマークを表示できるようになりました。
• 放射座標系のガイド制御:

  coord-radial

  向けに角度軸と半径軸の刻み制御機能が追加されました。

Typst Universe でインストール

#import "@preview/gribouille:0.3.0": *

🔧 ガイド（Guide）制御の新機能

これまで

theme()

X/Y 軸のガイド制御

• guides(x: none)

  /

  guides(y: none)

  : 刻み線とラベルを消去します（軸ライン・グリッド・タイトルは維持）。

• guides(default: none)

  : 個別設定がないすべての美学に対し凡例を非表示にします。
• 代替機能: 以前削除された

  guide-none()

  の代わりに使用されます。

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.7),),
  guides: guides(x: none), // X 軸の刻み線とラベルのみ削除
  labs: labs(
    title: "Ticks Off, Grid Stays",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

凡例の制御

• guides(none)

  : すべての凡例を隠します。

• guides(auto)

  : デフォルト挙動に戻ります。

• guides(default: none)

  : 個別設定がない美学に適用され、凡例なしの状態を作ります。

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.7),),
  guides: guides(default: none), // 凡例を削除
  labs: labs(
    title: "No Legends",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

放射座標系 (

coord-radial

) での制御

• guides(theta: none)

  : 全角度軸（円弧・刻み目・ラベル）を隠す。

• guides(r: none)

  : 半径方向の刻み目ラベルのみを非表示にする（spoke と円は残る）。

#plot(
  data: penguins,
  mapping: aes(x: "species", fill: "species"),
  layers: (geom-bar(),),
  coord: coord-radial(),
  guides: guides(theta: none, default: none), // 角度軸と凡例を隠す
  labs: labs(
    title: "Angular Axis Hidden",
    x: none,
    y: "Count",
  ),
  theme: theme-minimal(),
  width: 10cm,
  height: 10cm,
)

🧩

compose()

とテーマの統合

compose()

theme:

破壊的変更と対応策

• 構文の置き換え:
  • 旧:

    plot(..., defer: true)

  • 新:

    defer(plot, ...)

• サイズ指定の変更: パネル内の

  width

  /

  height

  指定が削除されました。コンポジション側でセルサイズを決定します。

#let panel(y, title) = defer(plot,
  data: penguins,
  mapping: aes(x: "flipper-len", y: y, colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  labs: labs(title: title, x: none, y: none),
)

#compose(
  panel("body-mass", "Body Mass"),
  panel("bill-len", "Bill Length"),
  columns: 2,
  tag-levels: "1",
  tag-prefix: "(",
  tag-suffix: ")",
  guides: guides(default: guide-legend(position: "bottom")),
  labs: labs(title: "One Theme, Two Panels"),
  theme: theme-minimal(), // 全体に適用されるテーマ
  width: 18cm,
  height: 8cm,
)

📈 geom-area() のデフォルト変更

面積図の描画ロジックが簡素化され、以下のデフォルト設定になりました。

• デフォルト挙動:

  stat: "align"

  および

  position: "stack"

  が自動的に採用されます。
• メリット:
  • 明示的な引数指定なしでスタック描画が実現します。

  • stat: "align"

    により、異なる X 値を持つグループも共通グリッド上に再サンプリングされ、X 値を揃える手間が省けます。

#let series = (
  (x: 0, y: 5, g: "A"), (x: 1, y: 8, g: "A"), (x: 3, y: 6, g: "A"), (x: 4, y: 9, g: "A"),
  (x: 0, y: 3, g: "B"), (x: 2, y: 5, g: "B"), (x: 3, y: 4, g: "B"), (x: 4, y: 6, g: "B"),
  (x: 0, y: 2, g: "C"), (x: 1, y: 3, g: "C"), (x: 2, y: 2, g: "C"), (x: 4, y: 4, g: "C"),
)

#plot(
  data: series,
  mapping: aes(x: "x", y: "y", fill: "g"),
  layers: (geom-area(),), // デフォルトでスタック描画に再サンプリングされる
  labs: labs(
    title: "Stacked by Default",
    x: "x",
    y: "y",
    fill: "Group",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

🏷️ annotate() でパネル外表示の実現

annotate()

clip

• デフォルト (

  clip: true

  ): パネル範囲外のマークはクリップされます（従来の動作）。

• clip: false

  :
  • 軸やパネル境界を超えてもマークを可視化します。
  • 角部の注釈やデータ範囲外への配置、余白内の装飾要素に便利です。
  • 修正点: スケール外にある注釈（以前のバージョンでは無視されていた）が正しく描画されるようになりました。

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (
    geom-point(size: 2pt, alpha: 0.6),
    annotate(
      geom-text(label: "← past the edge"),
      x: 235, // パネル範囲を超えた位置
      y: 5000,
      clip: false, // クリップを無効化
    ),
  ),
  labs: labs(
    title: "Annotation Outside the Panel",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

🛠️ 内部構造・修正・改善

本リリースの多くは機能追加ではなく、既存の問題に対する修正です。

レイアウトと凡例の改善

• 凡例整列: 水平凡例で中央/右揃えにした際、キーグラフィックも適切に配置されます。
• グリッド対応:

  guide-legend(nrow:)

  /

  ncolumn:

  は連続値スケールの凡例にも適応し、グリッド上にキーを配置します。
• エラーレポートの改善:

  • guide-legend(align:)

    に無効な文字列を渡すと、以前は静黙に無視されていたのが明確なエラーとして報告されます。
  • 空間不足による凡例の重なりのようなレイアウト問題も、エラーとして通知されるようになりました。

統計関数とスケール動作

• 密度計算 (

  stat-bin-2d

  ,

  stat-bin-hex

  ): セル内のカウント比率として計算され、ggplot2 と整合性が取られました。
• 変換の検証 (

  sqrt

  ,

  log10

  ): ドメイン外データに対し明確なエラーを報告し、零点での軸挙動が適切になります。
• 範囲外フィルタ: スケール拡大 (

  scale expand

  ) を尊重し、ヘッダーム内のポイントや注釈を保持します。
• パラメータ適用:

  geom-linerange()

  の

  alpha

  パラメータが正しく適用されるようになりました。

📝 エディタサポート：Tinymist ドキュメント

公開パッケージには Tinymist 向けのドキュメント文字列（docstrings）が含まれています。

• 互換性のあるエディタで関数名にカーソルを置くと、引数や戻り値、使用例がフォーマットされます。
• 可変長シンクでも、受け付けるキーが明示的にリストされるため、API の確認が容易です。

まとめ

Gribouille 0.3.0 では、ガイド制御の粒度が細かくされ、テーマ設定の手間が省かれました。特に

compose()

🌐 リンク集

• リポジトリ: https://github.com/mcanouil/gribouille
• ドキュメント: https://m.canouil.dev/gribouille
• Typst Universe: https://typst.app/universe/package/gribouille

⚠️ 注意: Gribouille は資金を受けていない趣味のプロジェクトです。バグ報告やアイデアは Issue tracker で大歓迎ですが、Pull Request の受入れは停止しています（ローンチ記事参照）。ご耐心等待ください。