When someone reads your document, they may read it with a screen reader. To ensure that they are able to interpret your document as intended, the document must contain some essential features, like tagged elements, alternative text, and metadata.
We have built asar
so that the produced documents uphold
several federal
accessibility standards. However, to achieve our goal of producing
accessible documents, you must complete a few tasks
yourself. But don’t fret! We will help you. Below, we provide
several resources to help you achieve this important goal.
Check the accuracy of each figure’s alternative text (“alt text” for short).
asar
’s figures already contains some prewritten alt
text that includes data from the model results file. This means that
most of the work has been done for you! However, it is crucial that you
check this information for accuracy and update it where necessary. This
is especially true if the default figures have been modified. If you see
text that looks like a placeholder (e.g., “The x axis, showing the year,
spans from B_start_year to B_end_year…”), that means that there was at
least one instance where our tool failed to extract a specific value
from the model results and substitute it into the placeholder. Learn how
to manually add the right values in section “How to edit your report’s
alt text and captions”, below.Write the final component of each figure’s alt text.
asar
to analyze the
figure’s meaning, you must provide this.After using create_template()
to create a skeleton of
your document, you will see chunks containing fig-alt:
in
the figures.qmd files, like this:
The fig-alt
parameter in this chunk signifies that this is where you should add a
description of your figure that can be read aloud by the screen reader.
This description, otherwise known as alternative
text should answer this essential question:
What is this image conveying?
While tempting, tools like AI cannot be used to easily answer this question. Additionally, one should not use the caption as the alt text. Here are four essential ingredients for well-written alt text, as described by Drs. Silvia Canelón and Liz Hare in their talk, “Revealing Room for Improvement in Accessibility within a Social Media Data Visualization Learning Community”1:
Dr. Hare stresses the importance of ingredient #4 by explaining, “Don’t waste my time with 1-3 if you aren’t going to include 4. While some automatic alt text processes mine some of this information, I don’t want to spend time building a mental model of the graph if I can’t find out what the graph says.2”
Both presentations are great resources for learning about alt text and will help you as you craft your own alt text!
Remember: The first three essential ingredients should already be present in your figures’ prewritten alt texts! You just need to check them for accuracy and provide ingredient #4.
Here is an example of a figure with a caption and alt text. The
caption is shown directly below the figure and is written in the chunk’s
options (fig.cap=""
). The alt text is also included in the
chunk’s options (fig.alt=""
) but is not shown unless the
webpage is inspected with Developer Tools or it’s extracted with a
screen reader.
library(ggplot2)
orange <- as.data.frame(Orange)
orange <- orange |>
dplyr::mutate(Tree = base::factor(Tree,
levels = c(1, 2, 3, 4, 5)
)) |>
dplyr::rename(
Age = age,
Circumference = circumference
)
ggplot2::ggplot(
data = orange,
aes(
x = Age,
y = Circumference,
color = Tree
)
) +
ggplot2::geom_line(size = 1) +
ggplot2::geom_point(size = 2) +
ggplot2::scale_color_viridis_d() +
ggplot2::xlim(0, NA) +
ggplot2::ylim(0, NA) +
ggplot2::theme_bw() +
labs(
x = "Age (days since 1968/12/31)",
y = "Orange Tree Circumference (mm)"
)
Tree circumference and age for 5 orange trees.
The figure’s alt text is written as such:
A line graph showing how tree circumference increases with age for a set of 5 orange trees. Age, shown on the x axis, is measured in days since 1968/12/31 and spans from 118-1582 days. Circumference, shown on the y axis, spans from 30-214 mm. All trees showed an increasing trend of trunk circumference with age, with each tree starting with a circumference of 30-33 mm at age 0 and ending with a circumference of 140-216 mm at age 1582. At age 1582, the tree with the largest circumference was tree 4, followed by trees 2, 5, 1, and 3.
Ingredient #4 = the relationship between the variables shown (i.e., what the figure is conveying).
There is no one-size-fits-all approach for explaining what a figure is conveying. We’ve included some prompts, below, to get you started, but you will need to go beyond these prompts to properly complete this task.
To edit your rda’s alt text, follow these steps:
"set-rda-dir-figs"
)."fig-recruitment-setup"
,"fig-spawning_biomass-setup"
,
etc.).recruitment_alt_text
). Then,
make an object (a string) containing your additional text (e.g.,
new_alt_text
). Then, paste together the existing alt text
object and your new text object. For example:# the original alt text for the recruitment figure
recruitment_alt_text
# the new text that will be added on to the recruitment figure's alt text
new_alt_text <- "This is my new alt text."
# add the new text to the old text
recruitment_alt_text <- paste0(recruitment_alt_text, new_alt_text)
# the original alt text for the recruitment figure
recruitment_alt_text
# the new text that will replace the recruitment figure's alt text
new_alt_text <- "This is my new alt text."
# replace the old alt text with the new alt text
recruitment_alt_text <- new_alt_text
NOTES:
Changes to your alt text will be saved within your 09_figures.qmd
file, but not within the rda file itself. To directly edit the rda
file’s alt text or caption, assign a new value to the text you wish to
change. For example, if your rda is called rda
and you want
to change the caption to “my new caption”, you’d enter the following
command: rda[["cap"]] <- "my new caption"
. To change the
alt text, you’d change “cap” to “alt_text” (e.g.,
rda[["alt_text"]] <- "my new alt text"
.). Save the
changes to the rda’s file by entering the following command (in this
example, our rda is called “biomass_figure.rda”):
save(rda, file = 'biomass_figure.rda')
.
Edit figure and table captions with the same process. Just substitute mentions of alt text with caption or cap, depending on the context.
As stated earlier, if you see text that looks like a placeholder
(e.g., “The x axis, showing the year, spans from B.start.year to
B.end.year…”), that means that there was at least one instance where our
tool failed to extract a specific value from the model results and
substitute it into the placeholder. Please make sure that your alt text
and captions contain the expected values before moving forward with your
report. Check out the inst/resources/captions_alt_text_template.csv file
in the satf
package to view the template with placeholders.
The same package’s write_captions()
function shows how
values are extracted from the model results and substituted into the
placeholders.
Looking for more resources for writing alt text? Check out the NOAA Library’s website for creating accessible documents.
Your report will likely include several acronyms (e.g., NOAA in place of the National Oceanic and Atmospheric Administration). To ensure that your audience will be able to correctly interpret your acronyms, please write the acronym’s entire expanded form upon its first usage, followed by the acronym in parentheses. Upon further usage, use the acronym alone. For example:
The National Oceanic and Atmospheric Administration (NOAA) has offices spread throughout the United States of America (USA). NOAA regularly produces stock assessments on fish and mammal species.
Canelón, Silvia, and Liz Hare. Revealing Room for Improvement in Accessibility within a Social Media Data Visualization Learning Community, csv,conf,v6, 7 May 2021, spcanelon.github.io/csvConf2021/slides/.↩︎
Hare, Liz. Writing Meaningful Alt Texts for Data Visualizations in R, R Ladies NYC, 10 Oct. 2022, lizharedogs.github.io/RLadiesNYAltText/.↩︎