Update vignette; add KQ meanings to template; add notes

Author: sbreitbart-NOAA

R/utils_rda.R

@@ -2,7 +2,8 @@
 # RDA utility functions
 # @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-# TODO: update new fxns to work with a specified 'dir' instead of default 'getwd()'?
+# TODO: update key quantities functions to work with a specified 'dir' instead of default 'getwd()'?
+# TODO: update key quantities functions for plots that need to extract values from KQs csv to calculate their own, dependent KQs (none present in current plotting functions)
 
 #' Substitute key quantities' values into template
 #'

inst/resources/key_quantity_template.csv

@@ -1,133 +1,133 @@
 key_quantity,value,meaning,dependent_on_other_kq,dependent_kq,dependent_on_other_fxn_args,fxn_with_other_args
-B.BMSY.end.yr,,,,,,
-B.end.year,,,,,,
-B.max,,,,,,
-B.min,,,,,,
-B.ref.pt,,,,,,
-B.start.year,,,,,,
-B.units,,,,,,
-Bend,,,,,,
-Bmsy,,,,,,
-Btarg,,,,,,
-caa.age.max,,,,,,
-caa.age.min,,,,,,
-caa.end.year,,,,,,
-caa.start.year,,,,,,
-cal.length.max,,,,,,
-cal.length.min,,,,,,
-cpue.end.year,,,,,,
-cpue.max,,,,,,
-cpue.min,,,,,,
-cpue.start.year,,,,,,
-cpue.units,,,,,,
-F.FMSY.end.yr,,,,,,
-F.end.year,,,,,,
-F.max,,,,,,
-F.min,,,,,,
-F.ref.pt,,,,,,
-F.start.year,,,,,,
-fecundity.length.max,,,,,,
-fecundity.length.min,,,,,,
-fecundity.length.units,,,,,,
-fecundity.max,,,,,,
-fecundity.min,,,,,,
-fecundity.units,,,,,,
-fork.length.max,,,,,,
-fork.length.min,,,,,,
-fork.length.units,,,,,,
-Ftarg,,,,,,
-kobe.end.year,,,,,,
-landings.end.year,,,,,,
-landings.max,,,,,,
-landings.min,,,,,,
-landings.start.year,,,,,,
-landings.units,,,,,,
-M.age.max,,,,,,
-M.age.min,,,,,,
-M.rate.max,,,,,,
-M.rate.min,,,,,,
-mod.fit.abun.end.year,,,,,,
-mod.fit.abun.start.year,,,,,,
-mod.fit.catch.end.year,,,,,,
-mod.fit.catch.max,,,,,,
-mod.fit.catch.min,,,,,,
-mod.fit.catch.start.year,,,,,,
-mod.fit.catch.units,,,,,,
-mod.fit.discards.end.year,,,,,,
-mod.fit.discards.max,,,,,,
-mod.fit.discards.min,,,,,,
-mod.fit.discards.start.year,,,,,,
-mod.fit.discards.units,,,,,,
-overfished.status.is.isnot,,,,,,
-overfishing.status.is.isnot,,,,,,
-pop.baa.age.max,,,,,,
-pop.baa.age.min,,,,,,
-pop.baa.end.year,,,,,,
-pop.baa.fish.max,,,,,,
-pop.baa.fish.min,,,,,,
-pop.baa.start.year,,,,,,
-pop.naa.age.max,,,,,,
-pop.naa.age.min,,,,,,
-pop.naa.end.year,,,,,,
-pop.naa.fish.max,,,,,,
-pop.naa.fish.min,,,,,,
-pop.naa.start.year,,,,,,
-proj.catch.end.year,,,,,,
-proj.catch.min,,,,,,
-proj.catch.start.year,,,,,,
-proj.catch.units,,,,,,
-prop.mat.length.max,,,,,,
-prop.mat.length.min,,,,,,
-prop.mat.length.units,,,,,,
-R0,,,,,,
-recruit.dev.end.year,,,,,,
-recruit.dev.max,,,,,,
-recruit.dev.min,,,,,,
-recruit.dev.start.year,,,,,,
-recruitment.end.year,,,,,,
-recruitment.max,,,,,,
-recruitment.min,,,,,,
-recruitment.start.year,,,,,,
-recruitment.units,,,,,,
-rel.B.max,,,,,,
-rel.B.min,,,,,,
-rel.F.max,,,,,,
-rel.F.min,,,,,,
-rel.recruitment.max,,,,,,
-rel.recruitment.min,,,,,,
-rel.ssb.max,,,,,,
-rel.ssb.min,,,,,,
-selectivity.end.year,,,,,,
-selectivity.length.max,,,,,,
-selectivity.length.min,,,,,,
-selectivity.length.units,,,,,,
-selectivity.start.year,,,,,,
-spr.max,,,,,,
-spr.min,,,,,,
-spr.ref.pt,,,,,,
-sr.age.min,,,,,,
-sr.ssb.max,,,,,,
-sr.ssb.min,,,,,,
-sr.ssb.units,,,,,,
-ssb.end.year,,,,,,
-ssb.max,,,,,,
-ssb.min,,,,,,
-ssb.ref.pt,,,,,,
-ssb.start.year,,,,,,
-ssb.units,,,,,,
-tot.catch.max,,,,,,
-tot.catch.min,,,,,,
-total.length.max,,,,,,
-total.length.min,,,,,,
-total.length.units,,,,,,
-vonb.age.max,,,,,,
-vonb.age.min,,,,,,
-vonb.length.max,,,,,,
-vonb.length.min,,,,,,
-vonb.length.units,,,,,,
-wl.length.max,,,,,,
-wl.length.min,,,,,,
-wl.length.units,,,,,,
-wl.weight.max,,,,,,
-wl.weight.min,,,,,,
-wl.weight.units,,,,,,
+B.BMSY.end.yr,,biomass relative to BMSY in the final year,,,,
+B.end.year,,final year of the biomass time series,,,,
+B.max,,maximum biomass,,,,
+B.min,,minimum biomass,,,,
+B.ref.pt,,biomass limit reference point,,,,
+B.start.year,,start year of the biomass time series,,,,
+B.units,,units of biomass measurement,,,,
+Bend,,biomass at the end of the time series,,,,
+Bmsy,,biomass at maximum sustainable yield,,,,
+Btarg,,target biomass reference point,,,,
+caa.age.max,,maximum age in catch-at-age data,,,,
+caa.age.min,,minimum age in catch-at-age data,,,,
+caa.end.year,,final year for catch-at-age data,,,,
+caa.start.year,,start year for catch-at-age data,,,,
+cal.length.max,,maximum length in catch-at-length histograms,,,,
+cal.length.min,,minimum length in catch-at-length histograms,,,,
+cpue.end.year,,final year of the CPUE time series,,,,
+cpue.max,,maximum catch per unit effort,,,,
+cpue.min,,minimum catch per unit effort,,,,
+cpue.start.year,,start year of the CPUE time series,,,,
+cpue.units,,units for catch per unit effort,,,,
+F.FMSY.end.yr,,fishing mortality relative to FMSY in the final year,,,,
+F.end.year,,final year of the fishing mortality time series,,,,
+F.max,,maximum fishing mortality,,,,
+F.min,,minimum fishing mortality,,,,
+F.ref.pt,,fishing mortality limit reference point,,,,
+F.start.year,,start year of the fishing mortality time series,,,,
+fecundity.length.max,,maximum fish length for fecundity relationship,,,,
+fecundity.length.min,,minimum fish length for fecundity relationship,,,,
+fecundity.length.units,,length units for fecundity measurement,,,,
+fecundity.max,,maximum observed fecundity,,,,
+fecundity.min,,minimum observed fecundity,,,,
+fecundity.units,,units for fecundity (number of eggs),,,,
+fork.length.max,,maximum fork length,,,,
+fork.length.min,,minimum fork length,,,,
+fork.length.units,,units for fork length,,,,
+Ftarg,,target fishing mortality reference point,,,,
+kobe.end.year,,final year displayed on the Kobe plot,,,,
+landings.end.year,,final year of historical landings data,,,,
+landings.max,,maximum historical landings,,,,
+landings.min,,minimum historical landings,,,,
+landings.start.year,,start year of historical landings data,,,,
+landings.units,,units for landings,,,,
+M.age.max,,maximum age for natural mortality,,,,
+M.age.min,,minimum age for natural mortality,,,,
+M.rate.max,,maximum natural mortality rate,,,,
+M.rate.min,,minimum natural mortality rate,,,,
+mod.fit.abun.end.year,,final year for model fit to abundance index,,,,
+mod.fit.abun.start.year,,start year for model fit to abundance index,,,,
+mod.fit.catch.end.year,,final year for model fit to catch data,,,,
+mod.fit.catch.max,,maximum model estimated catch,,,,
+mod.fit.catch.min,,minimum model estimated catch,,,,
+mod.fit.catch.start.year,,start year for model fit to catch data,,,,
+mod.fit.catch.units,,units for model estimated catch,,,,
+mod.fit.discards.end.year,,final year for model fit to discards,,,,
+mod.fit.discards.max,,maximum estimated discards,,,,
+mod.fit.discards.min,,minimum estimated discards,,,,
+mod.fit.discards.start.year,,start year for model fit to discards,,,,
+mod.fit.discards.units,,units for estimated discards,,,,
+overfished.status.is.isnot,,indicator of overfished status,,,,
+overfishing.status.is.isnot,,indicator of overfishing status,,,,
+pop.baa.age.max,,maximum age for biomass-at-age data,,,,
+pop.baa.age.min,,minimum age for biomass-at-age data,,,,
+pop.baa.end.year,,final year for biomass-at-age data,,,,
+pop.baa.fish.max,,maximum bubble size for biomass-at-age,,,,
+pop.baa.fish.min,,minimum bubble size for biomass-at-age,,,,
+pop.baa.start.year,,start year for biomass-at-age data,,,,
+pop.naa.age.max,,maximum age for numbers-at-age data,,,,
+pop.naa.age.min,,minimum age for numbers-at-age data,,,,
+pop.naa.end.year,,final year for numbers-at-age data,,,,
+pop.naa.fish.max,,maximum bubble size for numbers-at-age,,,,
+pop.naa.fish.min,,minimum bubble size for numbers-at-age,,,,
+pop.naa.start.year,,start year for numbers-at-age data,,,,
+proj.catch.end.year,,final year of catch projections,,,,
+proj.catch.min,,minimum forecasted catch,,,,
+proj.catch.start.year,,start year of catch projections,,,,
+proj.catch.units,,units for projected catch,,,,
+prop.mat.length.max,,maximum length for maturity schedule,,,,
+prop.mat.length.min,,minimum length for maturity schedule,,,,
+prop.mat.length.units,,length units for maturity data,,,,
+R0,,unfished equilibrium recruitment,,,,
+recruit.dev.end.year,,final year of recruitment deviations,,,,
+recruit.dev.max,,maximum recruitment deviation,,,,
+recruit.dev.min,,minimum recruitment deviation,,,,
+recruit.dev.start.year,,start year of recruitment deviations,,,,
+recruitment.end.year,,final year of estimated recruitment,,,,
+recruitment.max,,maximum estimated recruitment,,,,
+recruitment.min,,minimum estimated recruitment,,,,
+recruitment.start.year,,start year of estimated recruitment,,,,
+recruitment.units,,units for recruitment,,,,
+rel.B.max,,maximum relative biomass,,,,
+rel.B.min,,minimum relative biomass,,,,
+rel.F.max,,maximum relative fishing mortality,,,,
+rel.F.min,,minimum relative fishing mortality,,,,
+rel.recruitment.max,,maximum relative recruitment (R/R0),,,,
+rel.recruitment.min,,minimum relative recruitment (R/R0),,,,
+rel.ssb.max,,maximum relative spawning stock biomass,,,,
+rel.ssb.min,,minimum relative spawning stock biomass,,,,
+selectivity.end.year,,final year for selectivity estimates,,,,
+selectivity.length.max,,maximum length for gear selectivity,,,,
+selectivity.length.min,,minimum length for gear selectivity,,,,
+selectivity.length.units,,units for selectivity length,,,,
+selectivity.start.year,,start year for selectivity estimates,,,,
+spr.max,,maximum spawning potential ratio,,,,
+spr.min,,minimum spawning potential ratio,,,,
+spr.ref.pt,,spawning potential ratio reference point,,,,
+sr.age.min,,age of newly recruited fish in SR model,,,,
+sr.ssb.max,,maximum SSB in stock-recruit relationship,,,,
+sr.ssb.min,,minimum SSB in stock-recruit relationship,,,,
+sr.ssb.units,,units for SSB in stock-recruit relationship,,,,
+ssb.end.year,,final year of the SSB time series,,,,
+ssb.max,,maximum spawning stock biomass,,,,
+ssb.min,,minimum spawning stock biomass,,,,
+ssb.ref.pt,,spawning stock biomass reference point,,,,
+ssb.start.year,,start year of the SSB time series,,,,
+ssb.units,,units for spawning stock biomass,,,,
+tot.catch.max,,maximum total catch,,,,
+tot.catch.min,,minimum total catch,,,,
+total.length.max,,maximum total length,,,,
+total.length.min,,minimum total length,,,,
+total.length.units,,units for total length,,,,
+vonb.age.max,,maximum age for von Bertalanffy growth,,,,
+vonb.age.min,,minimum age for von Bertalanffy growth,,,,
+vonb.length.max,,maximum length for von Bertalanffy growth,,,,
+vonb.length.min,,minimum length for von Bertalanffy growth,,,,
+vonb.length.units,,units for length in growth model,,,,
+wl.length.max,,maximum length for weight-length relationship,,,,
+wl.length.min,,minimum length for weight-length relationship,,,,
+wl.length.units,,length units for weight-length conversion,,,,
+wl.weight.max,,maximum weight for weight-length relationship,,,,
+wl.weight.min,,minimum weight for weight-length relationship,,,,
+wl.weight.units,,weight units for weight-length conversion,,,,

vignettes/how-caps-alttext-are-made.Rmd

@@ -44,12 +44,16 @@ After the final plot has been created within the function, key quantities are ca
 
 **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: