quarto-alt-text

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Chart Alt Text

编写图表Alt Text

Generate accessible alt text for data visualizations in this project.

ARGUMENTS

label: (optional) specific fig- label to generate alt text for
file: (optional) specific .qmd file to process

为项目中的数据可视化生成可访问的替代文本。

Instructions

参数

When invoked, analyze the figure(s) and generate alt text following these guidelines:

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

Key Advantage: Source Code Access

操作说明

Unlike typical alt text scenarios where you only see an image, we have access to the code that generates each chart. Use this to extract precise details:

From plotting code:

Variable mappings → exact variable names for axes
Color/fill mappings → what color encodes
Plot type functions → scatter, histogram, line chart, etc.
Trend lines or fitted curves → overlaid statistical fits
Faceting/subplots → number of panels and what varies
Color scales → encoding scheme (sequential, diverging, categorical)
Axis labels and titles → customized labels

From data generation code:

Random distributions → expected distribution shape
Transformations → what was done to data
Feature engineering → preprocessing applied
Filtering/subsetting → what subset is shown

From surrounding prose:

Text before/after the chunk explains the purpose and key insight
Chapter context tells you what the figure is meant to teach
This is often the best source for the "key insight" part of alt text

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

Three-Part Structure (Amy Cesal's Formula)

核心优势：源代码访问权限

Chart type - First words identify the format
Data description - Axes, variables, what's shown
Key insight - The pattern or takeaway (often found in surrounding text)

与仅能看到图片的常规替代文本场景不同，我们可以访问生成每个图表的代码。利用这一点提取精准细节：

从绘图代码中提取：

变量映射 → 坐标轴的精确变量名称
颜色/填充映射 → 颜色所代表的含义
绘图类型函数 → 散点图、直方图、折线图等
趋势线或拟合曲线 → 叠加的统计拟合线
分面/子图 → 面板数量及变化维度
颜色刻度 → 编码方案（连续型、发散型、分类型）
坐标轴标签和标题 → 自定义标签

从数据生成代码中提取：

随机分布 → 预期的分布形状
数据转换 → 对数据执行的操作
特征工程 → 应用的预处理步骤
过滤/子集化 → 展示的数据子集

从周边文本中提取：

代码块前后的文本解释了图表的用途和核心结论
章节上下文说明了图表要传达的信息
这通常是替代文本中“核心结论”部分的最佳来源

Relationship to fig-cap

三部分结构（Amy Cesal公式）

Read the

fig-cap

first. The alt text should complement, not duplicate it:

If caption states the insight, alt text can focus on describing the visual structure
If caption is generic, alt text should include the key insight
Together they should give a complete understanding

图表类型 - 开头点明图表格式
数据描述 - 坐标轴、变量及展示内容
核心结论 - 图表呈现的模式或要点（通常来自周边文本）

Content Rules

与fig-cap的关系

Include:

Chart type as first words
Axis labels and what they represent
Specific values/ranges when code reveals them (e.g., "peaks between 25-50")
Number of panels/facets
What color/size encodes if used
The key pattern that supports the chapter's point

Exclude:

"Image of..." or "Chart showing..." (screen readers announce this)
Decorative color descriptions (unless color encodes data)
Information already in fig-cap
Implementation details (package names, function internals)

先阅读

fig-cap

内容。替代文本应补充而非重复标题内容：

如果标题已经说明核心结论，替代文本可专注于描述视觉结构
如果标题较为通用，替代文本应包含核心结论
两者结合应能让读者完整理解图表信息

Length Guidelines

内容规则

Complexity	Sentences	When to use
Simple	2-3	Single geom, no facets, obvious pattern
Standard	3-4	Multiple geoms or color encoding
Complex	4-5	Faceted, multiple overlays, nuanced insight

需包含：

以图表类型开头
坐标轴标签及其代表的含义
代码中显示的特定数值/范围（例如：“峰值在25-50之间”）
面板/分面的数量
颜色/尺寸所代表的含义（若使用）
支撑章节观点的核心模式

需排除：

“图片展示...”或“图表显示...”（屏幕阅读器会自动播报此类内容）
装饰性颜色描述（除非颜色用于编码数据）
已在fig-cap中出现的信息
实现细节（包名称、函数内部逻辑）

Quality Checklist

长度指南

Starts with chart type (Scatter chart, Histogram, Faceted bar chart, etc.)
Names the axis variables
Includes specific values/ranges from code when informative
States the key insight from surrounding prose
Complements (not duplicates) the fig-cap
Would make sense to someone who cannot see the image
Uses plain language (avoid jargon like "geom" or "aesthetic")

复杂度	句子数量	适用场景
简单	2-3	单一几何对象、无分面、模式明显的图表
标准	3-4	多几何对象或颜色编码的图表
复杂	4-5	分面、多图层叠加、结论微妙的图表

Template Patterns

质量检查清单

Scatter chart:

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:

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

Bar chart:

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/raster chart:

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:

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 heatmap:

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

Before/after comparison:

[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 chart with overlays:

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

以图表类型开头（散点图、直方图、分面条形图等）
明确坐标轴变量
若有帮助，包含代码中的特定数值/范围
说明来自周边文本의核心结论
补充（而非重复）fig-cap的内容
让无法看到图片的人也能理解图表信息
使用平实语言（避免“geom”或“aesthetic”等术语）

Workflow

模板示例

Finding Figures

—

To find all figure chunks in the project:

bash

undefined

散点图：

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

要查找项目中的所有图表代码块：

bash

undefined

Find figures in a specific file

List all figure labels with file and line number

grep -n "#| label: fig-" numeric-splines.qmd

grep -n "#| label: fig-" *.qmd

Find a specific figure

Find figures in a specific file

grep -rn "#| label: fig-splines-predictor-outcome" *.qmd

undefined

grep -n "#| label: fig-" numeric-splines.qmd

For Each Figure

Find a specific figure

Locate - Use grep to find file and line number
Read context - Read ~50 lines around the chunk (prose before + code + prose after)
Extract details - Note fig-cap, ggplot code, data generation, surrounding explanation
Draft alt text - Apply three-part structure (type → data → insight)
Verify - Check against quality checklist

grep -rn "#| label: fig-splines-predictor-outcome" *.qmd

undefined

Example

处理每个图表的步骤

Code context:

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

Surrounding prose says: "Normalization doesn't make data more normal"

fig-cap: "Normalization doesn't make data more normal. The green curve indicates the density of the unit normal distribution."

Good alt text:

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

定位 - 使用grep查找文件和行号
阅读上下文 - 阅读代码块前后约50行内容（之前的文本 + 代码 + 之后的文本）
提取细节 - 记录fig-cap、ggplot代码、数据生成逻辑及周边解释
起草替代文本 - 应用三部分结构（类型 → 数据 → 结论）
验证 - 根据质量检查清单审核

—

示例

—

代码上下文：

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.