quarto-alt-text

グラフの代替テキストを作成する

このプロジェクトのデータ可視化に、アクセシブルな代替テキストを生成します。

引数

• label：（任意）代替テキストを生成する特定の fig- ラベル
• file：（任意）処理する特定の .qmd ファイル

手順

実行時に、図を分析し、次のガイドラインに従って代替テキストを生成します。

主な利点：ソースコードにアクセスできる

画像だけを見る通常の代替テキスト作成とは異なり、各グラフの生成コードにアクセスできます。これを活用して、詳細を正確に抽出してください。

プロットコードから：

• 変数のマッピング → 軸に使われている正確な変数名
• 色／塗りつぶしのマッピング → 色が何を表しているか
• プロットタイプの関数 → 散布図、ヒストグラム、折れ線グラフなど
• トレンドラインまたは当てはめた曲線 → 重ねて表示された統計的な当てはめ
• ファセット／サブプロット → パネルの数と、パネルごとに異なる内容
• 色スケール → エンコーディング方式（連続、発散、カテゴリ）
• 軸ラベルとタイトル → カスタマイズされたラベル

データ生成コードから：

• ランダム分布 → 想定される分布の形状
• 変換 → データに施された処理
• 特徴量エンジニアリング → 適用された前処理
• フィルタリング／サブセット化 → 表示されているデータの範囲

前後の説明文から：

• チャンクの前後にあるテキストは、図の目的と主な洞察を説明しています
• 章の文脈から、図を通して何を伝えるのかがわかります
• 代替テキストの「主な洞察」を把握するには、ここが最適な情報源となることがよくあります

3 部構成（Amy Cesal の公式）

1. グラフの種類 - 冒頭で形式を特定します
2. データの説明 - 軸、変数、表示内容を説明します
3. 主な洞察 - パターンや要点を伝えます（多くの場合、前後の説明文に記載されています）

fig-cap との関係

最初に fig-cap を確認してください。代替テキストは、キャプションを補完するものであり、重複するものではありません。

• キャプションに洞察が記載されている場合、代替テキストでは視覚的な構造を説明します
• キャプションが一般的な内容の場合、代替テキストに主な洞察を含めます
• 両方を合わせて、内容を完全に理解できるようにします

内容に関するルール

含める内容：

• 最初にグラフの種類を示す
• 軸ラベルと、それが表す内容
• コードから特定できる具体的な値や範囲（例：「25〜50 の間でピークになる」）
• パネル／ファセットの数
• 色やサイズが使われている場合、それが表す内容
• 章の要点を裏付ける主なパターン

含めない内容：

• 「画像…」や「…を示すグラフ」（スクリーンリーダーが読み上げます）
• データを表さない装飾的な色の説明
• fig-cap にすでに記載されている情報
• 実装の詳細（パッケージ名、関数の内部処理）

長さの目安

複雑さ	文の数	使用する場面
シンプル	2〜3	単一のジオム、ファセットなし、パターンが明確
標準	3〜4	複数のジオム、または色によるエンコーディング
複雑	4〜5	ファセットあり、複数の重ね合わせ、解釈に工夫が必要な洞察

品質チェックリスト

• グラフの種類から始まっている（散布図、ヒストグラム、ファセット付き棒グラフなど）
• 軸の変数を明記している
• 有益な場合、コードからわかる具体的な値や範囲を含めている
• 前後の説明文から得られる主な洞察を示している
• fig-cap を補完している（重複していない）
• 画像が見えない人にも意味が伝わる
• 平易な言葉を使っている（「ジオム」や「美的属性」などの専門用語を避ける）

テンプレートのパターン

散布図：

Scatter chart. [X var] along the x-axis, [Y var] along the y-axis.
[Shape: linear/curved/clustered]. [Specific pattern, e.g., "peaks when X is 25-50"].
[Any overlaid fits or annotations].

ヒストグラム：

Histogram of [variable]. [Shape: right-skewed/bimodal/normal/uniform].
[If transformed: "after [transformation], the distribution [result]"].
[Notable features: outliers, gaps, multiple modes].

棒グラフ：

Bar chart. [Categories] along the x-axis, [measure] along the y-axis.
[Key comparison: which is highest/lowest, relative differences].
[Pattern: increasing/decreasing/grouped].

タイル／ラスターグラフ：

Tile chart [or heatmap]. [Row variable] along the y-axis, [column variable] along the x-axis.
Color encodes [what value]. [Pattern: where values are high/low].
[If faceted: "N panels showing [what varies]"].

ファセット付きグラフ：

Faceted [chart type] with [N] panels, one per [faceting variable].
[What's constant across panels]. [What changes/varies].
[Key comparison or insight across panels].

相関ヒートマップ：

Correlation [matrix/heatmap] of [what variables]. [Arrangement].
[Overall pattern: mostly positive/negative/mixed].
[Notable clusters or strong/weak pairs].
[If relevant: contrast with expected behavior, e.g., "unlike PCA, these are not orthogonal"].

変更前／変更後の比較：

[N] [chart type]s arranged [vertically/in grid]. [Top/Left] shows [original].
[Bottom/Right] shows [transformed]. [Key difference/similarity].
[If overlay: "[color] curve shows [reference]"].

重ね合わせを含む折れ線グラフ：

[Line/Scatter] chart with overlaid [fits/curves]. [Axes].
[Number] of [lines/fits] shown: [list what each represents].
[Which fits well vs. poorly and why].

ワークフロー

図を見つける

プロジェクト内のすべての図チャンクを見つけるには：

# List all figure labels with file and line number
grep -n "#| label: fig-" *.qmd

# Find figures in a specific file
grep -n "#| label: fig-" numeric-splines.qmd

# Find a specific figure
grep -rn "#| label: fig-splines-predictor-outcome" *.qmd

各図について

1. 特定 - grep を使用してファイルと行番号を検索します
2. 文脈を読む - 該当箇所の前後約50行（コードの前の文章＋コード＋コードの後の文章）を読みます
3. 詳細を抽出 - fig-cap、ggplot コード、データ生成方法、周辺の説明を確認します
4. 代替テキストを作成 - 3部構成（種類 → データ → 示唆）を適用します
5. 確認 - 品質チェックリストに照らして確認します

例

コードの文脈：

plotting_data |>
  ggplot(aes(value)) +
  geom_histogram(binwidth = 0.2) +
  facet_grid(name~., scales = "free_y") +
  geom_line(aes(x, y), data = norm_curve, color = "green4")

周辺の文章：「正規化してもデータがより正規分布に近づくわけではありません」

fig-cap：「正規化してもデータがより正規分布に近づくわけではありません。緑色の曲線は標準正規分布の密度を示しています。」

適切な代替テキスト：

#| fig-alt: |
#|   Faceted histogram with two panels stacked vertically. Top panel shows
#|   original data with a bimodal distribution. Bottom panel shows the same
#|   data after z-score normalization, retaining the bimodal shape. A green
#|   normal distribution curve overlaid on the bottom panel clearly does not
#|   match the data, demonstrating that normalization preserves distribution
#|   shape rather than creating normality.