Adjust spawning_biomass documentation feeedback

R/plot_abundance_at_age.R

@@ -22,7 +22,7 @@
 #' ("rda_files") that will be created if the argument `make_rda` = TRUE.
 #' Default is the working directory.
 #' @return Plot total abundance (or numbers) at age from a stock assessment model
-#' using a standardized output made from \link[asar]{convert_output}). Units of
+#' using a standardized output made from \link[stockplotr]{convert_output}). Units of
 #' abundance can either be manually added or will be extracted from the provided
 #' file if possible.
 #' @export

R/plot_biomass.R

@@ -20,15 +20,14 @@
 #' plot_biomass(
 #'   dat = stockplotr:::example_data,
 #'   unit_label = "mt",
-#'   ref_line = "target",
+#'   ref_line = c("target" = 20000),
 #'   scale_amount = 100,
 #'   module = "TIME_SERIES",
 #'   figures_dir = getwd()
 #' )
 #' plot_biomass(
 #'   dat = stockplotr:::example_data,
-#'   facet = "fleet",
-#'   ref_line = "target",
+#'   ref_line = NULL,
 #'   module = "TIME_SERIES",
 #'   figures_dir = getwd()
 #' )

R/plot_spawning_biomass.R

@@ -3,55 +3,83 @@
 #' Plot spawning biomass with a reference line as a dashed line. The figure can
 #' also be made relative to this reference line rather than in absolute units.
 #'
-#' @param dat A data frame or names list of data frames (input as `list()`)
-#' returned from \link[stockplotr]{convert_output}. The first data frame in the list
-#' is used in calculation of a reference line if one is present
-#' @param geom A string stating the geom used for the plot. Default is "line".
-#' Options include "line", "point", or "area"
-#' @param group a string of a single column that groups the data (e.g. "fleet",
-#' "sex", "area", etc.). Currently can only have one level of grouping. If you want to just summarize
-#' the data across all factors, set group = "none". In the case there is only
-#' one unique value of the grouping and/or NA is available, the function will
-#' default to the NAs and in some cases the grouping when there is not an equal
-#' number of rows for NA and the grouped data.
-#' @param facet a string or vector of strings of a column that facets the data
-#' (e.g. "year", "area", etc.)
-#' @param era a string naming the era of data such as historical ("early"), current ("time"), or
-#' projected ("fore") data if filtering should occur. Default is set to "time" which is
-#' the current time. To plot all data, set era to NULL.
-#' @param ref_line A string specifying the type of reference you want to
-#'   compare spawning biomass to. The default is `"target"`, which looks for
-#'   `"spawning_biomass_target"` in the `"label"` column of `dat`. The actual
-#'   searching in `dat` is case agnostic and will work with either upper- or
-#'   lower-case letters but you must use one of the options specified in the
-#'   default list to ensure that the label on the figure looks correct
-#'   regardless of how it is specified in `dat`.
-#' @param unit_label units for spawning_biomass
-#' @param module (Optional) A string indicating the linked module_name associated
-#' with the label for the plot if known. Default is NULL. By default, the function
-#' will select the most relevant module if more than 1 exists.
-#' @param scale_amount A number describing how much to scale down the quantities
-#' shown on the y axis. For example, scale_amount = 100 would scale down a value
-#' from 500,000 --> 5,000. This scale will be reflected in the y axis label.
-#' @param relative A logical value specifying if the resulting figures should
-#'   be relative spawning biomass. The default is `FALSE`. `ref_line` indicates
-#'   which reference point to use.
-#' @param make_rda TRUE/FALSE; indicate whether to produce an .rda file containing
-#' a list with the figure/table, caption, and alternative text (if figure). If TRUE,
+#' @param dat A tibble or named list of tibbles (input as `list()`)
+#' returned from \link[stockplotr]{convert_output}. 
+#' 
+#' If inputting a list of tibbles, the first tibble's reference point defined 
+#' in `ref_line` is used to plot a reference line or calculate relative spawning biomass.
+#' @param geom A string stating the geom used for the plot. 
+#' 
+#' Default: "line".
+#' 
+#' Options: "line", "point", or "area"
+#' @param group A string of a single column that groups the data (e.g. "fleet",
+#' "sex", "area", etc.). 
+#' 
+#' Set group = "none" to summarize data over all indexing values.
+#' 
+#' Default: NULL
+#' @param facet A string or vector of strings of a column name.
+#' 
+#' Default: NULL
+#' @param era A string naming the era of data.
+#' 
+#' Default: "time"
+#' 
+#' Options: "early", "time", "fore" (forecast), or NULL (all data)
+#' @param ref_line A string specifying a reference point name.
+#' 
+#' Default: "target"
+#' 
+#' Options: (including, but not limited to) "target", "msy", and "unfished"
+#' If the reference point is not found in the data, set `ref_line = c("{name}" = value)`. 
+#' @param unit_label A string specifying spawning biomass unit.
+#' 
+#' Default: "metric tons"
+#' @param module (Optional) A string indicating the module_name found in `dat`.
+#' 
+#' Default: NULL
+#' 
+#' If the interactive and >1 module_name is found, user will select the 
+#' module_name in the console. @seealso [filter_data()]
+#' @param scale_amount A number to scale the y-axis values.
+#' 
+#' Default: 1
+#' @param relative A logical value specifying to set y-axis values relative to 
+#' the ref_line value.
+#' 
+#' Default: `FALSE`
+#' @param make_rda A logical value indicating whether to save the object and 
+#' make an automated caption and alternative text in the form of an `rda` object. If TRUE,
 #' the rda will be exported to the folder indicated in the argument "figures_dir".
-#' Default is FALSE.
-#' @param figures_dir The location of the folder containing the generated figure
-#' rda files ("figures") that will be created if the argument `make_rda` = TRUE.
-#' Default is the working directory.
-#' @param interactive TRUE/FALSE; indicate whether the environment in which the
-#' function is operating  is interactive. This bypasses some options for
-#' filtering when preparing data for the plot. Default is FALSE.
-#' @param ... Arguments called from ggplot2::geom_line or ggplot2::geom_point
+#' 
+#' Default: `FALSE`.
+#' @param figures_dir A string indicating a path to the "figures" folder.
+#' 
+#' Default: `getwd()`
+#' 
+#' The folder is created within the path if it does not exist.
+#' @param interactive A logical value indicating if the environment is interactive.
+#' 
+#' Default: `FALSE`
+#' @param ... Arguments called from \link[ggplot2]{geom_line} or \link[ggplot2]{geom_point}
 #' @return
 #' Plot spawning biomass over time from the results of an assessment model translated to
-#' the a standardized output (\link[asar]{convert_output}). There are options to return a
-#' [ggplot2::ggplot()] object or export an rda object containing associated
+#' the a standardized output (\link[stockplotr]{convert_output}). There are options to return a
+#' \link[ggplot2]{ggplot} object or export an rda object containing associated
 #' caption and alternative text for the figure.
+#' 
+#' @note
+#' All plotting functions automatically recognize indexing variables and will 
+#' use them in groupings and/or facetting. @seealso [process_data()].
+#' 
+#' @seealso 
+#' * [plot_timeseries()]
+#' * [calculate_reference_point()]
+#' * [reference_line()]
+#' * [filter_data()]
+#' * [process_data()]
+#' 
 #' @export
 #'
 #' @examples
@@ -71,6 +99,12 @@
 #'   ref_line = "msy",
 #'   module = "TIME_SERIES"
 #' )
+#' plot_spawning_biomass(
+#'  dat = stockplotr:::example_data,
+#'  ref_line = c("target" = 10),
+#'  interactive = FALSE,
+#'  module = "TIME_SERIES"
+#' )
 plot_spawning_biomass <- function(
   dat,
   geom = "line",

R/stockplotr-package.R

@@ -17,6 +17,6 @@ globvar <- c(
   "plot_data", "quantile", "rda_dir", "reorder", "total_estimate", "zvar", "filter_data",
   "Component", "age_bins", "alt_label", "final_df", "init", "keyword", "len_bins",
   "like", "match_key", "morph", "nsim", "output", "output_order", "parm_stdev", "seas",
-  "sexes", "subseas", "unique_count", "value", "yr"
+  "sexes", "subseas", "unique_count", "value", "yr", "fleet_names", "."
 )
 if (getRversion() >= "2.15.1") utils::globalVariables(globvar)

R/utils_plot.R

@@ -197,7 +197,7 @@ plot_timeseries <- function(
 #' Create plot with error
 #'
 #' @param dat filtered data frame from standard output file(s) preformatted for
-#'  the target label from \link[stockplotr]{prepare_data}
+#'  the target label from \link[stockplotr]{process_data}
 #' @param x a string of the column name of data used to plot on the x-axis (default
 #' is "year")
 #' @param y a string of the column name of data used to plot on the y-axis (default
@@ -521,25 +521,33 @@ reference_line <- function(
   era_name <- era
 
   # Add geom for ref line
-  plot +
-    ggplot2::geom_hline(
-      # ggplot2::aes(
-      yintercept = ref_line_val / ifelse(relative, ref_line_val, scale_amount),
-      # ),
-      color = "black",
-      linetype = "dashed"
-    ) +
-    ggplot2::annotate(
-      geom = "text",
-      # TODO: need to change this for general process
-      x = as.numeric(max(dat$year[dat$era == era_name], na.rm = TRUE)), # - as.numeric(max(dat$year[dat$era == "time"], na.rm = TRUE))/200,
-      y = ref_line_val / ifelse(relative, ref_line_val, scale_amount),
-      label = glue::glue("{label_name}[{reference}]"), # list(bquote(label_name[.(reference)])),
-      parse = TRUE,
-      hjust = 1,
-      vjust = 0,
-      size = 5 # this is not foolproof
-    )
+  if (is.null(ref_line_val)) {
+    # cli::cli_alert_warning(
+    #   glue::glue("Reference value for {label_name} not found. Cannot add reference line.")
+    # )
+    plot
+  } else {
+    plot +
+      ggplot2::geom_hline(
+        # ggplot2::aes(
+        yintercept = ref_line_val / ifelse(relative, ref_line_val, scale_amount),
+        # ),
+        color = "black",
+        linetype = "dashed"
+      ) +
+      ggplot2::annotate(
+        geom = "text",
+        # TODO: need to change this for general process
+        x = as.numeric(max(dat$year[dat$era == era_name], na.rm = TRUE)), # - as.numeric(max(dat$year[dat$era == "time"], na.rm = TRUE))/200,
+        y = ref_line_val / ifelse(relative, ref_line_val, scale_amount),
+        label = glue::glue("{label_name}[{reference}]"), # list(bquote(label_name[.(reference)])),
+        parse = TRUE,
+        hjust = 1,
+        vjust = 0,
+        size = 5 # this is not foolproof
+      )
+  }
+
 }
 
 #------------------------------------------------------------------------------
@@ -895,7 +903,7 @@ calculate_reference_point <- function(
   }
 
   # Check if the reference value was found
-  if (length(ref_line_val) == 0) {
+  if (!is.null(ref_line_val) && length(ref_line_val) == 0) {
     cli::cli_alert_warning(
       "The resulting reference value of `{reference_name}` was not found.",
       wrap = TRUE

inst/WORDLIST

@@ -12,7 +12,6 @@ Pre
 Preformatted
 Rda
 alttext
-amak
 asar
 bam
 birthseas
@@ -27,8 +26,10 @@ dat
 dataframe's
 diagonostic
 dplyr
+facetting
 fims
 flextable
+getwd
 ggplot
 gp
 hline
@@ -50,6 +51,7 @@ rowid
 satf
 sd
 se
+seealso
 socio
 spr
 ss
@@ -59,6 +61,8 @@ stringr
 subseason
 theming
 tibble
+tibble's
+tibbles
 tidyr
 tidyselect
 unfished