alt-text

アクセシブルな代替テキストの作成

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

引数

• label：（省略可）対象とする特定の図のラベルまたはチャンク
• file：（省略可）処理する特定のファイル

プロジェクトの種類を判別する

作業を進める前に、プロジェクトのコンテキストを特定し、該当するリファレンスを読みます。 プロジェクトのルートに _pkgdown.yml ファイルがあるか確認し、pkgdown サイトかどうかを判別します。

ls _pkgdown.yml 2>/dev/null && echo "pkgdown" || echo "not pkgdown"

• pkgdown サイト（_pkgdown.yml が存在する）→ references/pkgdown.md を読みます
• Quarto ドキュメント（_pkgdown.yml がなく、.qmd ファイルがある）→ references/quarto.md を読みます

コンテキストがまだ曖昧な場合は、どの形式を使用しているかユーザーに尋ねます。

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

画像しか見られない一般的な代替テキストの作成とは異なり、各チャートを生成するコードにアクセスできます。これを使って、正確な情報を抽出します。

プロットコードから得られる情報：

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

データ生成コードから得られる情報：

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

周辺の文章から得られる情報：

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

3 部構成（Amy Cesal の公式）

1. チャートの種類 — 最初の言葉で形式を示します
2. データの説明 — 軸、変数、表示内容を説明します
3. 重要な洞察 — パターンや要点を示します（多くの場合、周辺の文章から得られます）

キャプションとの関係

まずキャプション（fig-cap、fig.cap）を読みます。代替テキストはキャプションを補完するものであり、重複させないようにします。

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

内容に関するルール

含める内容：

• 最初にチャートの種類を示します
• 軸ラベルと、それぞれが表す内容
• コードからわかる具体的な値／範囲（例：「25～50 の間でピークに達します」）
• パネル／ファセットの数
• 色／サイズが使用されている場合、それらが表す内容
• 周辺の説明を裏付ける重要なパターン

含めない内容：

• 「画像…」「…を示すチャート」などの表現（スクリーンリーダーがその旨を読み上げます）
• 装飾目的の色の説明（色がデータを表す場合を除く）
• キャプションにすでに記載されている情報
• 実装の詳細（パッケージ名、関数の内部処理）

長さの目安

複雑さ	文の数	使用する状況
シンプル	2～3	ジオムが 1 つで、ファセットがなく、パターンが明確な場合
標準	3～4	複数のジオム、または色によるエンコーディングがある場合
複雑	4～5	ファセット、複数の重ね合わせ、微妙な洞察がある場合

品質チェックリスト

• チャートの種類（散布図、ヒストグラム、ファセット付き棒グラフなど）から始まっている
• 軸の変数名が記載されている
• 有用な場合、コードからわかる具体的な値／範囲が含まれている
• 周辺の文章から得られる重要な洞察が述べられている
• キャプションを補完している（重複していない）
• 画像が見えない人にも意味が通じる
• 平易な言葉を使っている（「geom」や「aesthetic」などの専門用語を避ける）

テンプレートのパターン

散布図：

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].

変更前／変更後の比較：

[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].

例

コードのコンテキスト：

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")

周辺の文章：「正規化しても、データがより正規になるわけではありません」

キャプション：「正規化しても、データがより正規になるわけではありません。緑色の曲線は、標準正規分布の密度を示しています。」

適切な代替テキスト：

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.