Package 'satf' reference manual

Title:	Stock Assessment Tables and Figures
Description:	Creates exploratory and finished tables and figures for stock assessment documents from U.S. stock assessment model outputs. This packages addresses parts of the stock assessment workflow that interprets outputs of stock assessment models as well as allows the analyst to create report ready tables and figures, reducing the need to create their own and format then when adding into a report. This package is intended to be used in conjuction with `asar`, a partially automated template for writing various stock assessment reports. Throughout development, we will be creating a set of standardized figures and tables for a stock assessment report, developing functions to produce a variety of diagonostic plots, and other helpful materials. The advantage of using this package over others is that it applies to a range of stock assessment model outputs and standardizes them.
Authors:	Samantha Schiano, Bai Li, Steve Saul, Kelli F. Johnson, & Megumi Oshima
Maintainer:	Samantha Schiano <[email protected]>
License:	MIT + file LICENSE
Version:	0.1.0
Built:	2025-02-14 16:31:59 UTC
Source:	https://github.com/nmfs-ost/satf

Add NOAA formatting to figure or table

Description

Add NOAA formatting to figure or table

Usage

add_theme(x)
add_theme(x)

Arguments

`x`	table or figures object from ggplot, base r plot, gt table, flextable, or kable extra

Value

Add the standard formatting for stock assessment reports for any figure or table. Currently, the function is able to format objects from: ggplot (ggplot2), base r plot, flextable (flextable), gt tables (gt), and kable tables (kableExtra).

Examples

add_theme(ggplot2::ggplot(data = cars, ggplot2::aes(x = speed, y = dist)) +
  ggplot2::geom_point())
add_theme(ggplot2::ggplot(data = cars, ggplot2::aes(x = speed, y = dist)) +
  ggplot2::geom_point())

Export all figures and tables

Description

Export all figures and tables to Rda files within one function.

Usage

exp_all_figs_tables(
  dat,
  recruitment_unit_label = "mt",
  scale_amount = 1,
  end_year = NULL,
  n_projected_years = 10,
  relative = FALSE,
  rda_dir = getwd(),
  ref_line = c("target", "MSY", "msy", "unfished"),
  ref_point = NULL,
  landings_unit_label = "mt",
  spawning_biomass_label = "mt",
  ref_line_sb = c("target", "MSY", "msy", "unfished"),
  ref_point_sb = NULL,
  indices_unit_label = NULL,
  biomass_unit_label = "mt",
  catch_unit_label = "mt"
)
exp_all_figs_tables(
  dat,
  recruitment_unit_label = "mt",
  scale_amount = 1,
  end_year = NULL,
  n_projected_years = 10,
  relative = FALSE,
  rda_dir = getwd(),
  ref_line = c("target", "MSY", "msy", "unfished"),
  ref_point = NULL,
  landings_unit_label = "mt",
  spawning_biomass_label = "mt",
  ref_line_sb = c("target", "MSY", "msy", "unfished"),
  ref_point_sb = NULL,
  indices_unit_label = NULL,
  biomass_unit_label = "mt",
  catch_unit_label = "mt"
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`recruitment_unit_label`	Units for recruitment
`scale_amount`	indicate the exact amount of scale (i.e. 1000)
`end_year`	last year of assessment
`n_projected_years`	Number of years spawning biomass is projected for. By default this number is set to 10
`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.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.
`ref_line`	A string specifying the type of reference you want to compare biomass to. The default is '"target"', which looks for '"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'.
`ref_point`	A known value of the reference point along with the label for the reference point as specified in the output file. Please use this option if the ref_line cannot find your desired point. Indicate the reference point in the form c("label" = value).
`landings_unit_label`	Units for landings
`spawning_biomass_label`	Units for spawning biomass
`ref_line_sb`	Identical definition as 'ref_line', but this argument is applied to plot_spawning_biomass.
`ref_point_sb`	Identical definition as 'ref_point', but this argument is applied to plot_spawning_biomass.
`indices_unit_label`	Units for index of abundance/CPUE
`biomass_unit_label`	Abbreviated units for biomass
`catch_unit_label`	Abbreviated units for catch

Value

Rda files for each figure/table.

Examples

## Not run: 
exp_all_figs_tables(dat, end_year = 2022, ref_line = "unfished", ref_point = 13000,
ref_point_sb = 13000, ref_line_sb = "target", indices_unit_label = "CPUE")

## End(Not run)
## Not run: 
exp_all_figs_tables(dat, end_year = 2022, ref_line = "unfished", ref_point = 13000,
ref_point_sb = 13000, ref_line_sb = "target", indices_unit_label = "CPUE")

## End(Not run)

Export a figure or table to rda

Description

Export a figure/table, and its caption and alternative text, to an rda object. Typically used after satf::extract_caps_alttext().

Usage

export_rda(
  final = NULL,
  caps_alttext = NULL,
  rda_dir = NULL,
  topic_label = NULL,
  fig_or_table = NULL
)
export_rda(
  final = NULL,
  caps_alttext = NULL,
  rda_dir = NULL,
  topic_label = NULL,
  fig_or_table = NULL
)

Arguments

`final`	The final figure (ggplot) or table (flextable) object.
`caps_alttext`	The object containing a figure's caption and alternative text, in a list, or a table's caption, likely generated with satf::extract_caps_alttext().
`rda_dir`	If the user has already created a folder containing .rda files with figures, tables, alt text, and captions, rda_dir represents the location of the folder containing these .rda files ("rda_files"). Otherwise, an "rda_files" folder will be created automatically, then used to store the exported rda files.
`topic_label`	A string that describes a figure or table's label. These labels are found in the "label" column of the "captions_alt_text.csv" file and are used to link the figure or table with its caption/alt text.
`fig_or_table`	A string describing whether the plot is a figure or table.

Value

An rda file with a figure's ggplot, caption, and alternative text, or a table's flextable and caption.

Examples

## Not run: 
export_rda(final = final_table_object,
caps_alttext = caps_alttext_object,
rda_dir = here::here(),
topic_label = "bnc",
fig_or_table = "table")

export_rda(final = final_figure_object,
caps_alttext = another_caps_alttext_object,
rda_dir = "my_rda_dir",
topic_label = "landings",
fig_or_table = "figure")

## End(Not run)
## Not run: 
export_rda(final = final_table_object,
caps_alttext = caps_alttext_object,
rda_dir = here::here(),
topic_label = "bnc",
fig_or_table = "table")

export_rda(final = final_figure_object,
caps_alttext = another_caps_alttext_object,
rda_dir = "my_rda_dir",
topic_label = "landings",
fig_or_table = "figure")

## End(Not run)

Extract captions and alternative texts

Description

Extract a figure or table's caption and alternative text for usage when generating a figure or table. Typically used before satf::export_rda().

Usage

extract_caps_alttext(topic_label = NULL, fig_or_table = NULL, dir = getwd())
extract_caps_alttext(topic_label = NULL, fig_or_table = NULL, dir = getwd())

Arguments

`topic_label`	A string that describes a figure or table's label. These labels are found in the "label" column of the "captions_alt_text.csv" file and are used to link the figure or table with its caption/alt text.
`fig_or_table`	A string describing whether the plot is a figure or table.
`dir`	The directory containing the "captions_alt_text.csv" file.

Value

A figure's caption and alternative text, in a list, or a table's caption.

Examples

## Not run: 
extract_caps_alttext(topic_label = "biomass",
                    fig_or_table = "figure",
                    dir = here::here())

extract_caps_alttext(topic_label = "bnc",
                    fig_or_table = "table",
                    dir = getwd())

## End(Not run)
## Not run: 
extract_caps_alttext(topic_label = "biomass",
                    fig_or_table = "figure",
                    dir = here::here())

extract_caps_alttext(topic_label = "bnc",
                    fig_or_table = "table",
                    dir = getwd())

## End(Not run)

Plot Total Biomass

Description

Plot Total Biomass

Usage

plot_biomass(
  dat,
  unit_label = "metric tons",
  scale_amount = 1,
  ref_line = c("target", "MSY", "msy", "unfished"),
  ref_point = NULL,
  end_year = NULL,
  relative = FALSE,
  make_rda = FALSE,
  rda_dir = getwd()
)
plot_biomass(
  dat,
  unit_label = "metric tons",
  scale_amount = 1,
  ref_line = c("target", "MSY", "msy", "unfished"),
  ref_point = NULL,
  end_year = NULL,
  relative = FALSE,
  make_rda = FALSE,
  rda_dir = getwd()
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`unit_label`	units for recruitment
`scale_amount`	indicate the exact amount of scale (i.e. 1000)
`ref_line`	A string specifying the type of reference you want to compare biomass to. The default is '"target"', which looks for '"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'.
`ref_point`	A known value of the reference point along with the label for the reference point as specified in the output file. Please use this option if the ref_line cannot find your desired point. Indicate the reference point in the form c("label" = value).
`end_year`	last year of assessment
`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.
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Plot total biomass from a stock assessment model as found in a NOAA stock assessment report. Units of total biomass can either be manually added or will be extracted from the provided file if possible. In later releases, model will not

Plot Index of Abundance

Description

Plot Index of Abundance

Usage

plot_indices(dat, unit_label = NULL, make_rda = TRUE, rda_dir = NULL)
plot_indices(dat, unit_label = NULL, make_rda = TRUE, rda_dir = NULL)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`unit_label`	units for index of abundance/CPUE
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Plot the estimated indices as indicated from a standard assessment model output file.

Plot observed landings by fleet

Description

Plot observed landings by fleet

Usage

plot_landings(
  dat,
  unit_label = "metric tons",
  make_rda = FALSE,
  rda_dir = getwd()
)
plot_landings(
  dat,
  unit_label = "metric tons",
  make_rda = FALSE,
  rda_dir = getwd()
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`unit_label`	indicate the name of the units of landings as to label the axis
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Create a plot ready for a stock assessment report of cumulative landings over time by fleet.Includes options to plot by fleet, total observed landings with and without predicted landings. Indicate if fleet should be faceted or on one plot (default). Warning: i

Plot Recruitment

Description

Plot Recruitment

Usage

plot_recruitment(
  dat,
  unit_label = "metric tons",
  scale_amount = 1,
  end_year = NULL,
  n_projected_years = 10,
  relative = FALSE,
  make_rda = FALSE,
  rda_dir = getwd()
)
plot_recruitment(
  dat,
  unit_label = "metric tons",
  scale_amount = 1,
  end_year = NULL,
  n_projected_years = 10,
  relative = FALSE,
  make_rda = FALSE,
  rda_dir = getwd()
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`unit_label`	units for recruitment
`scale_amount`	indicate the exact amount of scale (i.e. 1000)
`end_year`	last year of assessment
`n_projected_years`	Number of years spawning biomass is projected for. By default this number is set to 10
`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.
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Plot recruitment over time from an assessment model output file translated to a standardized output. There are options to return a ggplot2 object or export an rda object containing associated caption and alternative text for the figure.

Plot Recruitment Deviations

Description

Plot Recruitment Deviations

Usage

plot_recruitment_deviations(
  dat = NULL,
  end_year = NULL,
  n_projected_years = 10,
  make_rda = FALSE,
  rda_dir = getwd()
)
plot_recruitment_deviations(
  dat = NULL,
  end_year = NULL,
  n_projected_years = 10,
  make_rda = FALSE,
  rda_dir = getwd()
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`end_year`	last year of assessment
`n_projected_years`	Number of years spawning biomass is projected for. By default this number is set to 10
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Plot recruitment deviations relative to one over time from an assessment model output file translated to a standardized output. There are options to return a ggplot2 object or export an .rda object containing associated caption and alternative text for the figure.

Plot Spawn-Recruit Curve

Description

Plot Spawn-Recruit Curve

Usage

plot_spawn_recruitment(
  dat = NULL,
  spawning_biomass_label = "metric tons",
  recruitment_label = "metric tons",
  end_year = NULL,
  make_rda = FALSE,
  rda_dir = getwd()
)
plot_spawn_recruitment(
  dat = NULL,
  spawning_biomass_label = "metric tons",
  recruitment_label = "metric tons",
  end_year = NULL,
  make_rda = FALSE,
  rda_dir = getwd()
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`spawning_biomass_label`	Units for spawning biomass
`recruitment_label`	units for recruitment
`end_year`	last year of assessment
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Plot spawning recruitment relationship from a standardized output file originating from asar::convert_output()

Plot spawning biomass (SB)

Description

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.

Usage

plot_spawning_biomass(
  dat,
  unit_label = "metric ton",
  scale_amount = 1,
  ref_line = c("target", "unfished", "msy"),
  ref_point = NULL,
  end_year = NULL,
  relative = FALSE,
  n_projected_years = 10,
  make_rda = FALSE,
  rda_dir = getwd()
)
plot_spawning_biomass(
  dat,
  unit_label = "metric ton",
  scale_amount = 1,
  ref_line = c("target", "unfished", "msy"),
  ref_point = NULL,
  end_year = NULL,
  relative = FALSE,
  n_projected_years = 10,
  make_rda = FALSE,
  rda_dir = getwd()
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`unit_label`	units for spawning_biomass
`scale_amount`	indicate the exact amount of scale (i.e. 1000)
`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'.
`ref_point`	A known value of the reference point along with the label for the reference point as specified in the output file. Please use this option if the ref_line cannot find your desired point. Indicate the reference point in the form c("label" = value).
`end_year`	last year of assessment
`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.
`n_projected_years`	Number of years spawning biomass is projected for. By default this number is set to 10
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Plot spawning biomass from the results of an assessment model translated to the standard output. The ggplot2 object is returned for further modifications if needed.

Biomass, abundance, and catch time series table

Description

Biomass, abundance, and catch time series table

Usage

table_bnc(
  dat,
  end_year = NULL,
  biomass_unit_label = "mt",
  catch_unit_label = "mt",
  make_rda = FALSE,
  rda_dir = getwd()
)
table_bnc(
  dat,
  end_year = NULL,
  biomass_unit_label = "mt",
  catch_unit_label = "mt",
  make_rda = FALSE,
  rda_dir = getwd()
)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`end_year`	last year of assessment
`biomass_unit_label`	abbreviated units for biomass
`catch_unit_label`	abbreviated units for catch
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Create a table of biomass, abundance, and catch through all years of the assessment model output translated to a standard structure.There are options to return a flextable object or export an rda object containing associated caption for the table.

Create Indices of Abundance Table

Description

Create Indices of Abundance Table

Usage

table_indices(dat, make_rda = FALSE, rda_dir = getwd())
table_indices(dat, make_rda = FALSE, rda_dir = getwd())

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`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, the .rda will be exported to the folder indicated in the argument "rda_dir". Default is FALSE.
`rda_dir`	The location of the folder containing the generated .rda files ("rda_files") that will be created if the argument 'make_rda' = TRUE. Default is the working directory.

Value

Create table of observed annual indices of abundance plus error stratified by fleet.

Write captions and alternative text

Description

Function to create captions and alternative text that contain key quantities from the model results file.

Usage

write_captions(dat, dir = NULL, year = NULL)
write_captions(dat, dir = NULL, year = NULL)

Arguments

`dat`	A data frame returned from 'asar::convert_output()'.
`dir`	Directory where the output captions and alt text file should be saved
`year`	the last year of the data or the current year this function is being performed

Value

Exports .csv with captions and alt text for figures and tables that contain key quantities (e.g., an assessment's start year) that are automatically extracted from the converted model results file.

Package 'satf'

Help Index

Add NOAA formatting to figure or table

Description

Usage

Arguments

Value

Examples

Export all figures and tables

Description

Usage

Arguments

Value

Examples

Export a figure or table to rda

Description

Usage

Arguments

Value

Examples

Extract captions and alternative texts

Description

Usage

Arguments

Value

Examples

Plot Total Biomass

Description

Usage

Arguments

Value

Plot Index of Abundance

Description

Usage

Arguments

Value

Plot observed landings by fleet

Description

Usage

Arguments

Value

Plot Recruitment

Description

Usage

Arguments

Value

Plot Recruitment Deviations

Description

Usage

Arguments

Value

Plot Spawn-Recruit Curve

Description

Usage

Arguments

Value

Plot spawning biomass (SB)

Description

Usage

Arguments

Value

Biomass, abundance, and catch time series table

Description

Usage

Arguments

Value

Create Indices of Abundance Table

Description

Usage

Arguments

Value

Write captions and alternative text

Description

Usage

Arguments

Value