Package 'asar'

Add selected sections to outline

Description

Add selected sections to outline

Usage

add_base_section(custom_sections)

Arguments

custom_sections

List of existing sections to include in the custom template. Note: this only includes sections within list.files(system.file("templates", "skeleton", package = "asar")). The name of the section, rather than the name of the file, can be used (e.g., 'abstract' rather than '00_abstract.qmd'). If adding a new section, also use parameters 'new_section' and 'section_location'.

Value

Call and copy the sections in the package templates to create an outline for a stock assessment

Examples

add_base_section(c("executive summary", "assessment", "results"))

---

Write R Chunk to Add Child Document

Description

Write R Chunk to Add Child Document

Usage

add_child(x, label = NULL)

Arguments

x	An additional section to add into the template. Options for additional sections are in the 'skeleton' folder. Appropriate files are .qmd files and are formatted as such: XX_section.qmd (i.e., not a, b, c... subfiles).
label	Description of the child document being added. It should be short- one or two words, maximum.

Value

Formatting R chunk for child document to add section into the template/skeleton. Utilize the cat() function to implement into readable text.

Examples

add_child("test_quarto.qmd", label = "test_doc")

---

Write R chunk to template

Description

Write R chunk to template

Usage

add_chunk(
  x,
  echo = "false",
  warnings = "false",
  eval = "true",
  label = NULL,
  add_option = FALSE,
  chunk_op = NULL,
  rmark_op = NULL
)

Arguments

x	Content to be written within the R chunk. Wrap in quotation marks ("").
echo	TRUE/FALSE; Option to repeat code in the document. Default is false.
warnings	TRUE/FALSE; Option to report warnings in the console during render. Default is false.
eval	TRUE/FALSE; Option to evaluate the chunk. Default is true.
label	The name of the chunk in the 'label:' section of the R code chunk. This should be in snakecase (i.e., in which words are written in lowercase and connected by underscores).
add_option	TRUE/FALSE; Option to add additional chunk options. Default is false.
chunk_op	List of chunk options to add. For example: c("output: true", "error: false)
rmark_op	List of chunk options to add after indicating the language of the chunk as used in Rmarkdown.

Value

Write an additional R chunk into the template using this function. The code can be written as usual, just remember to put it entirely in quotes for the function to render it properly

Examples

add_chunk("plot(cars$speed, cars$distance)")

---

Add New Section or Subsection to Template

Description

Add New Section or Subsection to Template

Usage

add_section(
  new_section = NULL,
  section_location = NULL,
  custom_sections = NULL,
  subdir = NULL
)

Arguments

new_section	Names of section(s) (e.g., introduction, results) or subsection(s) (e.g., a section within the introduction) that will be added to the document. Please make a short list if >1 section/subsection will be added. The template will be created as a quarto document, added into the skeleton, and saved for reference.
section_location	Where new section(s)/subsection(s) will be added to the skeleton template. Please use the notation of 'placement-section'. For example, 'in-introduction' signifies that the new content would be created as a child document and added into the 02_introduction.qmd. To add >1 (sub)section, make the location a list corresponding to the order of (sub)section names listed in the 'new_section' parameter.
custom_sections	List of existing sections to include in the custom template. Note: this only includes sections within list.files(system.file("templates", "skeleton", package = "asar")). The name of the section, rather than the name of the file, can be used (e.g., 'abstract' rather than '00_abstract.qmd'). If adding a new section, also use parameters 'new_section' and 'section_location'.
subdir	Directory where the new sections will be saved. In the create_template function, this defaults to the location where the template is saved.

Value

Add an additional section or subsection to the report template if it is not already present in the default template. This provides the option to add it as a section before or after an existing section, or within a section as a child document.

Examples

add_section(
  new_section = "Ecosystem Considerations", section_location = "after-discussion",
  custom_sections = c("introduction.qmd", "model.qmd", "results.qmd", "discussion.qmd"),
  subdir = tempdir()
)

---

Add NOAA formatting to figure or table

Description

Add NOAA formatting to figure or table

Usage

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())

---

Convert Output

Description

Format stock assessment output files to a standardized format.

Usage

convert_output(
  output_file = NULL,
  outdir = getwd(),
  model = NULL,
  fleet_names = NULL,
  file_save = FALSE,
  savedir = getwd(),
  save_name = "std_model_output"
)

Arguments

output_file	Assessment model output file (e.g., the Report.sso file for SS3, the rdat file for BAM, etc.)
outdir	Directory of the assessment model output file. Defaults to working directory.
model	Assessment model used in evaluation ("ss3", "bam", "asap", "fims", "amak", "ms-java", "wham", "mas").
fleet_names	Names of fleets in the assessment model as shortened in the output file. If fleet names are not properly read, then indicate the fleets names as an acronym in a vector
file_save	TRUE/FALSE; Save the formatted object rather than calling the function and adding the formatted object to the global environment? Default is false.
savedir	Directory to save the converted output file. Defaults to working directory.
save_name	Name of the converted output file (do not use spaces).

Value

A reformatted and standardized version of assessment model results for application in building a stock assessment reports and to easily adapt results among regional assessments. The resulting object is simply a transformed and machine readable version of a model output file. There are 2 options for adding data to the function. (1) Add the full path with the file name in output.file or (2) output.file is the file name and outdir is the path to the file without a trailing forward slash.

Author(s)

Samantha Schiano

---

Generate Citation for Stock Assessment Report

Description

Generate Citation for Stock Assessment Report

Usage

create_citation(author = NULL, title = NULL, year = NULL, office = NULL)

Arguments

author	Ordered list of authors included in the assessment.
title	The alternative title. Example: "Management Track Assessments Spring 2024".
year	Year the assessment is being conducted. Default is the year in which the report is rendered.
office	Regional Fisheries Science Center producing the report (i.e., AFSC, NEFSC, NWFSC, PIFSC, SEFSC, SWFSC).

Value

Generate a citation for use in publications and other references associated with the stock assessment report produced with asar.

Examples

create_citation(
  title = "SA Report for Jellyfish",
  author = c("John Snow", "Danny Phantom", "Patrick Star"),
  year = 2024, office = "NEFSC"
)

---

Create Quarto Document of Figures

Description

Create Quarto Document of Figures

Usage

create_figures_doc(subdir = NULL, include_all = TRUE, rda_dir = NULL)

Arguments

subdir	Location of subdirectory storing the assessment report template
include_all	TRUE/FALSE; Option to include all default figures for a stock assessment report. Default is true.
rda_dir	If the user has already created .rda files containing figures, tables, alt text, and captions with satf, rda_dir represents the location of the folder containing these .rda files ("rda_files"). Otherwise, if the user has not used satf to make those .rda files already, those files will be generated automatically and placed within the "report" folder within the file_dir. The "rda_files" folder would have been made with satf::exp_all_figs_tables(), or by exporting files by running individual satf figure- and table-generating functions. If you have used satf to generate these .rda files, you can leave the arguments below blank. NOTE: If an "rda_files" folder is detected within rda_dir, .rda files will not be regenerated.

Value

A quarto document with pre-loaded R chunk that adds the stock assessment tables from the nmfs-ost/satf R package. The quarto document will become part of the stock assessment outline.

---

Create in-header latex document

Description

Create in-header latex document

Usage

create_inheader_tex(species = NULL, year = NULL, subdir)

Arguments

species	common species name - used for footer
year	year assessment is conducted
subdir	directory where other files will be copied into

Value

Create an in-header latex document that dynamically changes based on the species and year along with other factors.

---

Create Quarto Document of Tables

Description

Create Quarto Document of Tables

Usage

create_tables_doc(subdir = NULL, include_all = TRUE, rda_dir = NULL)

Arguments

subdir	subdirectory where the assessment report template is being stored
include_all	include all default tables for a stock assessment report
rda_dir	If the user has already created .rda files containing figures, tables, alt text, and captions with satf, rda_dir represents the location of the folder containing these .rda files ("rda_files"). Otherwise, if the user has not used satf to make those .rda files already, those files will be generated automatically and placed within the "report" folder within the file_dir. The "rda_files" folder would have been made with satf::exp_all_figs_tables(), or by exporting files by running individual satf figure- and table-generating functions. If you have used satf to generate these .rda files, you can leave the arguments below blank. NOTE: If an "rda_files" folder is detected within rda_dir, .rda files will not be regenerated.

Value

Create a quarto document as part of a stock assessment outline with pre-loaded R chunk adding the stock assessment tables from the nmfs-ost/satf R package

---

Create Stock Assessment Report Template

Description

To see templates included in the base skeleton, please run 'list.files(system.file('templates','skeleton', package = 'asar'))' in the console.

Usage

create_template(
  new_template = TRUE,
  format = c("pdf", "docx", "html", NULL),
  office = c("AFSC", "PIFSC", "NEFSC", "NWFSC", "SEFSC", "SWFSC"),
  region = NULL,
  complex = FALSE,
  species = NULL,
  spp_latin = NULL,
  year = NULL,
  file_dir = getwd(),
  author = "",
  add_author = NULL,
  include_affiliation = TRUE,
  simple_affiliation = FALSE,
  alt_title = FALSE,
  title = NULL,
  parameters = TRUE,
  param_names = NULL,
  param_values = NULL,
  convert_output = FALSE,
  fleet_names = NULL,
  resdir = NULL,
  model_results = NULL,
  model = NULL,
  new_section = NULL,
  section_location = NULL,
  type = "SAR",
  prev_year = NULL,
  custom = FALSE,
  custom_sections = NULL,
  include_figures = TRUE,
  include_tables = TRUE,
  add_image = FALSE,
  spp_image = NULL,
  bib_file = "asar_references.bib",
  rda_dir = getwd(),
  scale_amount = 1,
  end_year = NULL,
  n_projected_years = 10,
  relative = FALSE,
  recruitment_unit_label = "metric tons",
  ref_line = c("target", "MSY", "msy", "unfished"),
  ref_point = NULL,
  landings_unit_label = "metric tons",
  ref_point_sb = NULL,
  spawning_biomass_label = "metric tons",
  ref_line_sb = c("target", "MSY", "msy", "unfished"),
  indices_unit_label = "",
  biomass_unit_label = "mt",
  catch_unit_label = "mt"
)

Arguments

new_template	TRUE/FALSE; Create a new template? If true, will pull the last saved stock assessment report skeleton. Default is false.
format	Rendering format (pdf, html, or docx).
office	Regional Fisheries Science Center producing the report (i.e., AFSC, NEFSC, NWFSC, PIFSC, SEFSC, SWFSC).
region	Full name of region in which the species is evaluated (if applicable). If the region is not specified for your center or species, do not use this variable.
complex	TRUE/FALSE; Is this a species complex? Default is false.
species	Full common name for target species. Split naming with a space and capitalize first letter(s). Example: "Dover sole".
spp_latin	Latin name for the target species. Example: "Pomatomus saltatrix".
year	Year the assessment is being conducted. Default is the year in which the report is rendered.
file_dir	Location of stock assessment files produced by this function. Default is the working directory.
author	Ordered list of authors included in the assessment.
add_author	Author that is not currently in the database and who should be temporarily added to the author list. Format as "First MI Last". Please leave a comment on the GitHub issues page to be added.
include_affiliation	TRUE/FALSE; Does the analyst want to include the authors' affiliations in the document? Default is false.
simple_affiliation	TRUE/FALSE; If including affiliations, should the office name function as the affiliation, rather than the full address? Default is true.
alt_title	TRUE/FALSE; Use a title that is not the default title (i.e., an alternative title)? Default is false.
title	The alternative title. Example: "Management Track Assessments Spring 2024".
parameters	TRUE/FALSE; For parameterization of the script. Default is true.
param_names	List of parameter names that will be called in the document. Parameters automatically included: office, region, species (each of which are listed as individual parameters for this function, above).
param_values	List of values associated with the order of parameter names. Parameters automatically included: office, region, species (each of which are listed as individual parameters for this function, above).
convert_output	TRUE/FALSE; Convert the output file to standard model format while creating report template? Default is false.
fleet_names	Deprecated: List of fleet names as described in BAM output file (abbreviations).
resdir	Filepath of the directory storing the model results file(s). Examples where dover_sole_2024 is the project root for absolute and relative filepaths, respectively: "C:/Users/patrick.star/Documents/dover_sole_2024/models", "here::here("models")".
model_results	The model results file. Before the stock assessment output file has been converted to a standardized format with the function convert_output.R, the model results file may be a .sso or .rdata file. After conversion, this file will be a .csv file.
model	Type of assessment model that was used to assess the stock (e.g., "BAM", "SS3", "AMAK", "ASAP", etc.).
new_section	Names of section(s) (e.g., introduction, results) or subsection(s) (e.g., a section within the introduction) that will be added to the document. Please make a short list if >1 section/subsection will be added. The template will be created as a quarto document, added into the skeleton, and saved for reference.
section_location	Where new section(s)/subsection(s) will be added to the skeleton template. Please use the notation of 'placement-section'. For example, 'in-introduction' signifies that the new content would be created as a child document and added into the 02_introduction.qmd. To add >1 (sub)section, make the location a list corresponding to the order of (sub)section names listed in the 'new_section' parameter.
type	Type of report to build. Default is SAR.
prev_year	Year in which the previous assessment report was conducted. Used to pull previous assessment template.
custom	TRUE/FALSE; Build custom sectioning for the template, rather than the default for stock assessments in your region? Default is false.
custom_sections	List of existing sections to include in the custom template. Note: this only includes sections within list.files(system.file("templates", "skeleton", package = "asar")). The name of the section, rather than the name of the file, can be used (e.g., 'abstract' rather than '00_abstract.qmd'). If adding a new section, also use parameters 'new_section' and 'section_location'.
include_figures	TRUE/FALSE; Should figures be included in the report? Default is true.
include_tables	TRUE/FALSE; Should tables be included in the report? Default is true.
add_image	TRUE/FALSE; Add image of species to the template that is not already included in the project's inst/resources/spp_img folder? Default is false.
spp_image	File path to the species' image if not using the image included in the project's repository.
bib_file	File path to a .bib file used for citing references in the report
rda_dir	If the user has already created .rda files containing figures, tables, alt text, and captions with satf, rda_dir represents the location of the folder containing these .rda files ("rda_files"). Otherwise, if the user has not used satf to make those .rda files already, those files will be generated automatically and placed within the "report" folder within the file_dir. The "rda_files" folder would have been made with satf::exp_all_figs_tables(), or by exporting files by running individual satf figure- and table-generating functions. If you have used satf to generate these .rda files, you can leave the arguments below blank. NOTE: If an "rda_files" folder is detected within rda_dir, .rda files will not be regenerated.
end_year	The last year of assessment. The default is year - 1.
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.
recruitment_unit_label	Units for recruitment
ref_line	An argument inherited from satf::plot_spawning_biomass.R. 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	An argument inherited from satf::plot_biomass.R. 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
ref_point_sb	Identical definition as ref_point, but this argument is applied to plot_spawning_biomass.
spawning_biomass_label	Units for spawning biomass
ref_line_sb	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.
indices_unit_label	Units for index of abundance/CPUE
biomass_unit_label	Abbreviated units for biomass
catch_unit_label	Abbreviated units for catch

Value

Create template and pull skeleton for a stock assessment report. Function builds a YAML specific to the region and utilizes current resources and workflows from different U.S. Fishery Science Centers. General sections are called as child documents in this skeleton and each of the child documents should be edited separately.

Examples

## Not run: 
create_template(
  new_section = "a_new_section",
  section_location = "before-introduction",
  rda_dir = here::here()
)


create_template(
  new_template = TRUE,
  format = "pdf",
  office = "NWFSC",
  species = "Dover sole",
  spp_latin = "Microstomus pacificus",
  year = 2010,
  author = c("John Snow", "Danny Phantom", "Patrick Star"),
  include_affiliation = TRUE,
  resdir = "C:/Users/Documents/Example_Files",
  model_results = "Report.sso",
  model = "SS3",
  new_section = "an_additional_section",
  section_location = "after-introduction",
  rda_dir = here::here()
)

asar::create_template(
  new_template = TRUE,
  format = "pdf",
  office = "PIFSC",
  species = "Striped marlin",
  spp_latin = "Kajikia audax",
  year = 2018,
  author = "Alba Tross",
  model = "BAM",
  new_section = c("a_new_section", "another_new_section"),
  section_location = c("before-introduction", "after-introduction"),
  custom = TRUE,
  custom_sections = c("executive_summary", "introduction"),
  rda_dir = here::here()
)

create_template(
  new_template = TRUE,
  format = "pdf",
  office = "NWFSC",
  region = "my_region",
  complex = FALSE,
  species = "Bluefish",
  spp_latin = "Pomatomus saltatrix",
  year = 2010,
  author = c("John Snow", "Danny Phantom", "Patrick Star"),
  add_author = "Sun E Day",
  include_affiliation = TRUE,
  simple_affiliation = TRUE,
  alt_title = FALSE,
  title = "Management Track Assessments Spring 2024",
  parameters = TRUE,
  param_names = c("region", "year"),
  param_values = c("my_region", "2024"),
  convert_output = FALSE,
  fleet_names = c("fleet1", "fleet2", "fleet3"),
  resdir = "C:/Users/Documents/Example_Files",
  model_results = "Report.sso",
  model = "SS3",
  new_section = "an_additional_section",
  section_location = "before-discussion",
  type = "SAR",
  prev_year = 2021,
  custom = TRUE,
  custom_sections = c("executive_summary", "introduction", "discussion"),
  include_figures = TRUE,
  include_tables = TRUE,
  add_image = TRUE,
  spp_image = "dir/containing/spp_image",
  rda_dir = "C:/Users/Documents",
  scale_amount = 1,
  end_year = 2022,
  n_projected_years = 10,
  relative = FALSE,
  recruitment_unit_label = "metric tons",
  ref_line = "target",
  landings_unit_label = "metric tons",
  spawning_biomass_label = "metric tons",
  recruitment_unit_label = "metric tons",
  ref_line_sb = "target",
  indices_unit_label = "CPUE",
  biomass_unit_label = "mt",
  catch_unit_label = "mt"
)

## End(Not run)

---

Write Stock Assessment Title

Description

Write Stock Assessment Title

Usage

create_title(
  office = NULL,
  species = NULL,
  region = NULL,
  year = NULL,
  complex = NULL,
  type = NULL,
  spp_latin = NULL
)

Arguments

office	Regional Fisheries Science Center producing the report (i.e., AFSC, NEFSC, NWFSC, PIFSC, SEFSC, SWFSC).
species	Full common name for target species. Split naming with a space and capitalize first letter(s). Example: "Dover sole".
region	Full name of region in which the species is evaluated (if applicable). If the region is not specified for your center or species, do not use this variable.
year	Year the assessment is being conducted. Default is the year in which the report is rendered.
complex	TRUE/FALSE; Is this a species complex? Default is false.
type	Type of report to build. Default is SAR.
spp_latin	Latin name for the target species. Example: "Pomatomus saltatrix".

Examples

create_title(
  office = "SEFSC", species = "Red Snapper", region = "South Atlantic",
  year = 2024, type = "SAR", spp_latin = "Lutjanus campechanus"
)

---

Create a title page latex document

Description

Create a title page latex document

Usage

create_titlepage_tex(office = "", subdir, species)

Arguments

office	primary science center writing the document
subdir	directory where files are going to be held
species	target species for assessment

Value

Create a _titlepage.tex document that contains formatting options for a cover page. The only thing that changes currently is the primary author's fishery science center.

---

Export report object

Description

Function to export specified object from R environment found in the stock assessment report.

Usage

export_object(object = NULL, file_format = "docx", subdir = NULL)

Arguments

object	Table, plot, or other object in the R environment to export for reference outside of the report document.
file_format	The format of the exported file. Options include pdf, docx, xlsx, csv, and rdata. Default is docx.
subdir	Directory where object will be exported.

Value

Objects put through this function will be put into the folder "exported" for better organization; DO NOT PUSH THESE TO THE REPO

Author(s)

Samantha Schiano

Examples

source <- c("NMFS Groundfish Survey", "", "U.S. Trawl Fisheries", "", "")
data <- c("Survey biomass", "Age Composition", "Catch", "Age Composition", "Length Composition")
years <- c(
  "1984-1999 (triennial), 2001-2013 (biennial)",
  "1984, 1987, 1990, 1993, 1996, 1999, 2003, 2005, 2007, 2009, 2011", "1961-2013",
  "1990,1998-2002, 2004, 2005, 2006, 2008, 2010", "1963-1977, 1991-1997"
)
test_obj <- data.frame(source, data, years)

export_object(object = test_obj, file_format = "csv", subdir = "~")

---

Add Formatting Arguments for YAML Header

Description

Add Formatting Arguments for YAML Header

Usage

format_quarto(format = NULL)

Arguments

format

Rendering format (pdf, html, or docx).

Value

This function returns part of a quarto YAML header involved in formatting the document during rendering.

Examples

format_quarto(format = "pdf")

---