---
title: "Achieve Greater Accessibility"
output:
  rmarkdown::html_vignette:
    toc: TRUE
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Achieve Greater Accessibility}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: references.bib
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

When someone reads your document, they may read it with a [screen reader](https://www.afb.org/blindness-and-low-vision/using-technology/assistive-technology-products/screen-readers). 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](https://www.section508.gov/test/documents/). 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.

# Your to-do list

1.  **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.

2.  **Write the final component** of each figure's alt text.

    -   This prewritten alt text usually contains 3/4 essential ingredients for well-written alt text. The remaining ingredient (#4): *the relationship between the variables shown (i.e., what the figure is conveying).* Since we can't program `asar` to analyze the figure's meaning, *you must provide this*.

# Guidance and Resources

## Alternative text

### What is alternative text?

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:

````{verbatim}
```{r}
#| eval: false
#| fig-alt: '...'
```
````

The [`fig-alt`](https://quarto.org/docs/computations/execution-options.html#caption-and-alt-text) 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](https://www.section508.gov/create/alternative-text/) should answer this essential question:

> What is this image conveying?

### Which information belongs in alt text?

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

[^1]: 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/](spcanelon.github.io/csvConf2021/slides/).

1.  Type of data visualization (e.g., scatterplot, line graph, box-and-whisker plot)
2.  Axis variables
3.  Range of the data
4.  The relationship between the variables shown (i.e., what the figure is conveying)

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

[^2]: Hare, Liz. *Writing Meaningful Alt Texts for Data Visualizations in R*, R Ladies NYC, 10 Oct. 2022, [lizharedogs.github.io/RLadiesNYAltText/](lizharedogs.github.io/RLadiesNYAltText/).

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.

### Example of alt text

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.

```{r, warning=FALSE, eval = TRUE, fig.align='center', fig.cap= "Tree circumference and age for 5 orange trees.", fig.alt="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."}
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)"
  )
```

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

### How to write ingredient #4

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

#### Many figures

-   Describe the span of the 95% confidence interval at a meaningful x axis value.
-   Describe the meaning of the legend.

#### Line graphs

-   Describe where the line increases and decreases.
-   Describe where the line dips below the reference point (if present).

#### Kobe plots

-   Describe where most points fall (in the four quadrants).

### How to edit your report's alt text and captions

To edit your rda’s alt text, follow these steps:

1.  Open your report's 09_figures.qmd file.
2.  Run the first code chunk, which saves the filepath of your rda directory as an object (it has the label `"set-rda-dir-figs"`).
3.  Find the two code chunks associated with the figure you're interested (e.g., recruitment). Run the first chunk, which will have "setup" in the label (e.g., `"fig-recruitment-setup"`,`"fig-spawning_biomass-setup"`, etc.).
4.  **Add to the alt text by** pasting the existing alt text with a new string *within the chunk*. To do this, find your existing alt text object, which is an object named with the figure's topic and "alt_text" (e.g., `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:

```{r, eval = FALSE}
# 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)
```

5.  **Replace the alt text by** updating the original alt text object *within the chunk*. To do this, reassign the original alt text object as your new text object. For example:

```{r, eval = FALSE}
# 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**:

1.  Changes to your alt text will be saved within your 09_figures.qmd file, but not within the rda file itself.
2.  Edit figure and table captions with the same process. Just substitute mentions of alt text with caption or cap, depending on the context.
3.  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.

### More resources

Looking for more resources for writing alt text? Check out the [NOAA Library's website for creating accessible documents](https://library.noaa.gov/Section508/CreatingDocs).

## Acronyms

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

## Tables

Please do not place figures inside tables. Doing so makes it very difficult for software to properly identify the structure of (i.e., *tag*) the table and its inner elements.