How captions and alternative text are generated

How captions and alternative text are generated

If you create tables and/or figures with this package, you will notice that captions and alternative text will be automatically generated. This vignette explains how these texts are created.

Templates

The ‘captions_alt_text_template.csv’ file contains the templates for each table or figure’s caption/alternative text. Tables have captions, and figures have captions and alternative text. Please refer to the {asar} package’s accessibility vignette to learn more about how we aimed to construct clear and comprehensive alternative text.

As templates, these texts are the starting point for the final captions and alternative text (again, we encourage users to read the the {asar} package’s accessibility vignette to learn how and why they should check the accuracy and write the final component of each figure’s alternative text). Specifically, there are placeholders throughout the texts (e.g., B.ref.pt, B.min, B.max). If the model results are parsed successfully, these placeholders will eventually be replaced with key quantities from the model results. For example, B.ref.pt will be replaced with the biomass figure’s reference point, and B.min and B.max will be replaced with the minimum and maximum biomass.

The file is set up like this:

• Column 1 (“label”) is a shorthand label for your figure or table. Labels are somewhat short and exclude spaces. Examples include “kobe”, “relative.biomass”, and “fishing.mortality”.
• Column 2 (“type”) contains “figure” or “table”.
• Column 3 (“caption”) contains the caption.
• Column 4 (“alt_text”) contains alternative text for figures. For tables, this column is blank.

Format for csv containing table and figure captions and alternative text.

label | type | caption | alt_text |
example_fig	figure | Example caption for figure. | Example alternative text for figure. |
example_tab	table | Example caption for table. | |

Calculating and exporting captions and alternative text

The process of extracting and inserting key quantities begins when a user runs a plotting function with the argument make_rda = TRUE. For example, plot_biomass(dat, make_rda = TRUE). If make_rda = FALSE, key quantities will not be calculated.

After the final plot has been created within the function, key quantities are calculated by extracting values from the dataset used to create the final plot. For example, in plot_biomass(), the minimum biomass will be saved to an object called “B.min”.

NOTE: While we extract key quantities as accurately as we can, we cannot guarantee that each quantity will be calculated perfectly. Input data varies widely. It’s always your responsibility to check the accuracy of your figures’ alt text.

NOTE: The key quantities are exported to a file saved to your working directory (“key_quantities.csv”) via export_kqs().

Next, the function insert_kqs() imports an empty or partially-filled template with captions and alternative text (“captions_alt_text_template.csv” or “captions_alt_text.csv”, respectively), depending on if the user has already created a “captions_alt_text.csv” file in their working directory. The .csv file is imported as a dataframe.

The key quantities are substituted into the dataframe’s appropriate placeholders. For example, “The y axis shows biomass in B.units, which spans from B.min to B.max.” will changed to “The y axis shows biomass in B.units, which spans from 100 to B.max.”

Finally, the function exports the updated dataframe as a new .csv, or overwrites the old version, to “captions_alt_text.csv”.

NOTE: If you export a plot with the same filename (e.g., you exported a biomass plot, then decided to slightly change it and reexport), you will be prompted in the console to decide if you want to overwrite your original plot. You will NOT be prompted to decide if you want to overwrite your original plot’s caption and alternative text with an updated version from your new plot, which may have different key quantities. To get updated key quantities, you must 1) revert the plot’s caption and alternative text in “captions_alt_text.csv” to contain the placeholders present in the “captions_alt_text_template.csv” OR 2) edit those entries manually.

Connecting the tables & figures with the captions & alternative text

The function create_rda() creates an R data (“rda”) file containing a package with 1) the figure or table, 2) caption, 3) alternative text (if a figure) OR a LaTeX version of a table (if a table). To make this package of files, the following steps occur:

1. The extract_caps_alttext() function selects the appropriate captions and alternative text from captions_alt_text.csv when a figure or table.

2. The export_rda() function exports the rda package.

Expected outcomes

Single plot functions

When using functions that produce one table or figure at a time, like plot_biomass(), only the key quantities associated with that plot will be substituted into the placeholders.

Multi-plot functions

When using save_all_plots(), the {stockplotr} function that exports all figures and tables, all key quantities (or, as many key quantities as possible) will be substituted into the placeholders.