manual

General manual

This manual is a work in progress. In the meantime, please read the function documentation and refer to the documentation of the companion package, asar.

Updating alternative text and captions

When a plotting function (e.g., plot_biomass(), table_indices(), exp_all_figs_tables()) is run, placeholders within the plot’s associated alternative text and captions are replaced with key quantities (see the asar package’s Accessibility vignette and/or the satf::write_captions() function for more details).

As stated in the Accessibility vignette’s “Your to-do list” section, you should always:

1. Check that these alternative texts and captions have been assembled correctly.

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

Here’s how to alter the alternative text and/or captions in satf, depending on what you wish to change:

Add or Remove Text

Directly edit the rda’s caption or alt_text objects. To do so, assign a new value to the text you wish to change. For example:

  1. Locate your rda file. It may be called something like “biomass_figure.rda”.

  2. Load it into your R environment. You can do this by clicking the file or by using a command like this: load("biomass_figure.rda"). It will probably be called rda.

  3. If 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".).

  4. Save the changes to the rda’s file (most likely you’ll want to overwrite your original rda) by entering the following command: save(rda, file = 'biomass_figure.rda').

NOTE: Your edits will be lost if:

  • You regenerate (overwrite) the captions_alt_text.csv file
  • You rerun exp_all_figs_tables() or that plot’s function with the make_rda argument = T after regenerating the captions_alt_text.csv file.

We recommend saving a version of your altered text elsewhere to ensure you can reuse it if it were to be overwritten.

Change/Update Arguments or Key Quantities

exp_all_figs_tables()

  1. Delete the captions_alt_text.csv file

  2. Rerun exp_all_figs_tables() with the correct arguments

NOTE: It is possible to directly edit the captions_alt_text.csv file to change the caption or alternative text. However, if you wish to do anything besides adding or removing text, we recommend using the two-step workflow, above, to avoid potential issues where an incorrect argument was used to calculate other (now incorrect) key quantities. For instance, end_year may be used to calculate values associated with F, which are then used to calculate other values.

Individual functions (e.g., plot_biomass())

  1. Open your function’s R file and find the topic_label object. If you set the relative argument to TRUE, then choose the topic_label with “relative” in it (e.g., “relative.biomass”).

  2. Open your caps_alt_text.csv file.

  3. Find the row in the caps_alt_text.csv file where the “label” column is the topic_label. Delete it.

  4. Open the inst/resources/captions_alt_text_template.csv file. Find the row where the “label” column is the topic_label. Copy that row.

  5. Paste the row into the caps_alt_text.csv file.

  6. Rerun the function so that the key quantities are replaced correctly.

This process ensures that only the alt text and/or captions for your specific function are being changed, and not those associated with other plotting functions.