quarto-alt-text

编写图表替代文本

为此项目中的数据可视化生成无障碍替代文本。

参数

• label：（可选）要生成替代文本的特定 fig- 标签
• file：（可选）要处理的特定 .qmd 文件

说明

调用时，请分析图表并按照以下指南生成替代文本：

主要优势：可访问源代码

与通常只能看到图像的替代文本场景不同，我们可以访问生成每个图表的代码。利用这些代码提取精确信息：

从绘图代码中提取：

• 变量映射 → 坐标轴的确切变量名称
• 颜色／填充映射 → 颜色编码的内容
• 绘图类型函数 → 散点图、直方图、折线图等
• 趋势线或拟合曲线 → 叠加的统计拟合
• 分面／子图 → 面板数量及变化的内容
• 颜色标度 → 编码方案（顺序、发散、类别）
• 坐标轴标签和标题 → 自定义标签

从数据生成代码中提取：

• 随机分布 → 预期的分布形状
• 转换 → 对数据所做的处理
• 特征工程 → 应用的预处理
• 筛选／子集 → 图中显示的子集

从周围的文字中提取：

• 代码块前后的文字会说明图表的用途和关键见解
• 章节背景会告诉你图表要传达什么
• 这通常是替代文本中“关键见解”部分的最佳来源

三部分结构（Amy Cesal 的公式）

1. 图表类型——开头先指出图表格式
2. 数据描述——坐标轴、变量和图表所示内容
3. 关键见解——模式或结论（通常可从周围文字中找到）

与 fig-cap 的关系

先阅读 fig-cap。替代文本应当补充而非重复它：

• 如果图注说明了见解，替代文本可以重点描述视觉结构
• 如果图注较为笼统，替代文本应包含关键见解
• 两者结合起来，应能提供完整的理解

内容规则

包含：

• 以图表类型开头
• 坐标轴标签及其代表的内容
• 代码中能确定的具体数值／范围（例如“峰值出现在 25-50 之间”）
• 面板／分面的数量
• 使用颜色／大小编码时，说明其编码的内容
• 支持章节观点的关键模式

排除：

• “图像……”或“图表显示……”（屏幕阅读器会读出这类信息）
• 装饰性颜色描述（除非颜色用于编码数据）
• fig-cap 中已有的信息
• 实现细节（包名称、函数内部实现）

长度指南

复杂度	句数	适用情况
简单	2-3	单一几何图层、无分面、模式明显
标准	3-4	多个几何图层或使用颜色编码
复杂	4-5	分面、多重叠加、见解细致

质量检查清单

• 以图表类型开头（散点图、直方图、分面条形图等）
• 指出坐标轴变量
• 在有帮助时，包含代码中的具体数值／范围
• 说明周围文字中的关键见解
• 补充而非重复 fig-cap
• 对看不到图像的人也有意义
• 使用通俗语言（避免“geom”或“美学映射”等术语）

模板模式

散点图：

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. 起草替代文本 - 应用三部分结构（类型 → 数据 → 洞见）
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.