Package 'asar'

Title: Build NOAA Stock Assessment Report
Description: Build a full or update stock assessment report for any stock assessment model. Parameterization allows the user to call a template based on their regional science center, species, area, ect.
Authors: Samantha Schiano [aut, cre] (ORCID: <https://orcid.org/0009-0003-3744-6428>), Sophie Breitbart [aut, ctb] (ORCID: <https://orcid.org/0000-0001-9641-9786>), Steve Saul [aut, ctb], Kelli Johnson [ctb] (ORCID: <https://orcid.org/0000-0002-5149-451X>), Bai Li [ctb] (ORCID: <https://orcid.org/0000-0002-8249-1442>)
Maintainer: Samantha Schiano <[email protected]>
License: MIT + file LICENSE
Version: 2.7.0
Built: 2026-10-14 19:13:47 UTC
Source: https://github.com/nmfs-ost/asar

Help Index

Add Accessibility to .tex documents

Description

Modifies a LaTeX report file to improve document accessibility. This function automates the process of adding PDF tagging and integrating alternative text for figures and tables.

Usage

add_accessibility(
  x = list.files(getwd())[grep("skeleton.tex", list.files(getwd()))],
  dir = getwd(),
  alttext_csv = file.path(getwd(), "captions_alt_text.csv"),
  compile = TRUE,
  rename = NULL
)

Arguments

x

Path. The name of the .tex file to modify.

Default: "...skeleton.tex"
dir

Path. The directory containing the .tex file.

Default: the working directory (getwd()).
alttext_csv

Path. csv file containing alternative text and captions, typically generated by stockplotr::exp_all_figs_tables().

Default: file.path(getwd(), "captions_alt_text.csv")
compile

Logical. TRUE/FALSE; If TRUE, renders the .tex file into a .pdf after modifications are complete.

Default: TRUE
rename

String. Optional new name for the modified .tex file (exclude the ".tex" extension). If NULL, the original file is overwritten.

Default: NULL

Details

This function acts as a wrapper for the asar package's accessibility workflow. It first applies document tagging via add_tagging and then injects alternative text using add_alttext.

Value

No return value. Modifies files on disk and optionally renders a .pdf.

See Also

add_alttext(), add_tagging()

Examples

## Not run: 
create_template(
  new_template = TRUE,
  format = "pdf",
  office = "NWFSC",
  region = "U.S. West Coast",
  species = "Dover sole",
  spp_latin = "Microstomus pacificus",
  year = 2010,
  author = c("John Snow" = "AFSC", "Danny Phantom" = "NWFSC", "Patrick Star" = "SEFSC-ML"),
  model_results = output,
  model = "SS3",
  new_section = "an_additional_section",
  section_location = "after-introduction"
)

quarto::quarto_render(file.path(getwd(), "report", "SAR_USWC_Dover_sole_skeleton.qmd"))

add_accessibility(
  x = "SAR_USWC_Dover_sole_skeleton.tex",
  dir = file.path(getwd(), "report"),
  alttext_csv = file.path(getwd(), "captions_alt_text.csv"),
  compile = TRUE
)

## End(Not run)

Add alternative text into latex

Description

Add alternative text into latex

Usage

add_alttext(
  x = list.files(getwd())[grep("skeleton.tex", list.files(getwd()))],
  dir = getwd(),
  alttext_csv = file.path(getwd(), "captions_alt_text.csv"),
  compile = TRUE,
  rename = NULL,
  tagged = TRUE
)

Arguments

x

Path. The name of the .tex file to modify.

Default: "...skeleton.tex"
dir

Path. The directory containing the .tex file.

Default: the working directory (getwd()).
alttext_csv

Path. csv file containing alternative text and captions, typically generated by stockplotr::exp_all_figs_tables().

Default: file.path(getwd(), "captions_alt_text.csv")
compile

Logical. TRUE/FALSE; If TRUE, renders the .tex file into a .pdf after modifications are complete.

Default: TRUE
rename

String. Optional new name for the modified .tex file (exclude the ".tex" extension). If NULL, the original file is overwritten.

Default: NULL
tagged

Logical. TRUE/FALSE; Indicate if the input tex file from dir has the latex package, tagpdf, used so that tagging is present.

Value

This function was made to help add in alternative text to latex documents generated from quarto. Quarto does not currently contain a way to add alternative text to PDF documents, so this function was developed as a work around. The addition of alternative text needs to be found in either the rda files produced from stockplotr::exp_all_figs_tables or in the captions_alt_text.csv also produced from the same function. Users not using this format should create a csv file with columns containing "label" and "alt_text" where the label column contains the exact label name when referencing the image/figure in text. The label is very important as it provides a way for the function to match where the alternative text gets placed. When compile is set to TRUE, the alternative text using this format will not be available and must be used in conjunction with asar::add_tagging() unless tagged is set to FALSE. Default is TRUE.

Examples

## Not run: 
create_template(
  new_template = TRUE,
  format = "pdf",
  office = "NWFSC",
  region = "U.S. West Coast",
  species = "Dover sole",
  spp_latin = "Microstomus pacificus",
  year = 2010,
  authors = c("John Snow" = "AFSC", "Danny Phantom" = "NEFSC", "Patrick Star" = "SEFSC-ML"),
  model_results = "Report.sso",
  model = "SS3",
  new_section = "an_additional_section",
  section_location = "after-introduction",
  figures_dir = getwd()
)

quarto::quarto_render(file.path(getwd(), "report", "SAR_USWC_Dover_sole_skeleton.qmd"))

add_alttext(
  x = "SAR_USWC_Dover_sole_skeleton.tex",
  dir = file.path(getwd(), "report"),
  alttext_csv = "my_alttext_file.csv",
  compile = FALSE,
  rename = "SAR_Dover_sole_tagged"
)

## End(Not run)

Format authors for skeleton

Description

Format authors for skeleton

Usage

add_authors(authors, rerender_skeleton = FALSE, prev_skeleton = NULL)

Arguments

authors

String. A character vector of author names and affiliations. For example, a Jane Doe at the NWFSC Seattle, Washington office would have an entry of c("Jane Doe"="NWFSC-SWA"). Information on NOAA offices can be found with: asar::affiliation_info. Keys to the office addresses follow the naming convention of: office acronym (ex. NWFSC), a hyphen (-), the first initial of the city, and then the two-letter abbreviation for the state the office is located in. If the city has two or more words (e.g., Panama City), the first initial of each word is used in the key (ex. Panama City, Florida = PCFL).

Default: NULL

Options: See asar::affiliation_info.
rerender_skeleton

TRUE/FALSE; Update the skeleton YAML and structure (R parameters, preamble, and skeleton sectioning) if relevant or indicated. All files in your folder, such as the .qmd child docs, will remain as is.

Default: FALSE
prev_skeleton

A character vector of the previous skeleton file read in through readLines()

Value

A list of authors formatted for a yaml in quarto. Viewable by running the return object inside of cat() for each part of the list.

Examples

## Not run: 
add_authors(
  authors = c("Danny Phantom" = "SWFSC-LJCA", "John Snow" = "AFSC-ABL", "Jane Doe" = "NWFSC-SWA"),
  rerender_skeleton = FALSE
)

## End(Not run)

Add selected sections to outline

Description

Add selected sections to outline

Usage

add_base_section(custom_sections = NULL)

Arguments

custom_sections

List of existing sections to include in a custom template (rather than the default for stock assessments in your region). If adding a new section, also use arguments 'new_section' and 'section_location'.

Default: NULL

Options: 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').

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

Path. 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

String. 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,
  label = NULL,
  add_option = TRUE,
  chunk_option = c("warnings: false", "eval: true"),
  rmark_option = NULL
)

Arguments

x

String. Content to be written within the R chunk. Wrap in quotation marks ("").
label

String. 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

Logical. TRUE/FALSE; Option to add additional chunk options. Default is false.
chunk_option

List. Chunk options to add. For example: c("output: true", "error: false)
rmark_option

List. 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(
  subdir = NULL,
  custom_sections = NULL,
  new_section = NULL,
  section_location = NULL
)

Arguments

subdir

Path. Directory where the new sections will be saved. In the create_template function, this defaults to the location where the template is saved.
custom_sections

List of existing sections to include in a custom template (rather than the default for stock assessments in your region). If adding a new section, also use arguments 'new_section' and 'section_location'.

Default: NULL

Options: 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').
new_section

String. Names of section(s) (e.g., "Special Section") 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.

Default: NULL
section_location

String. 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.

Default: NULL

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. For developers: this function creates a list of sections that will be added to the skeleton file made from create_template.

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 tagging structure to latex documents produced from quarto

Description

Add tagging structure to latex documents produced from quarto

Usage

add_tagging(
  x = list.files(getwd())[grep("skeleton.tex", list.files(getwd()))],
  dir = getwd(),
  compile = TRUE,
  rename = NULL
)

Arguments

x

Path. The name of the .tex file to modify.

Default: "...skeleton.tex"
dir

Path. The directory containing the .tex file.

Default: the working directory (getwd()).
compile

Logical. TRUE/FALSE; If TRUE, renders the .tex file into a .pdf after modifications are complete.

Default: TRUE
rename

String. Optional new name for the modified .tex file (exclude the ".tex" extension). If NULL, the original file is overwritten.

Default: NULL

Value

This function was made to help add in latex packages and content associated with PDF tagging. Quarto does not allow the user to edit anything before documentclass, so this function alters the rendered .tex file. Flextable-based tables will not be tagged as flextable is not compatible with tagpdf.

Examples

## Not run: 
create_template(
  new_template = TRUE,
  format = "pdf",
  office = "NWFSC",
  region = "U.S. West Coast",
  species = "Dover sole",
  spp_latin = "Microstomus pacificus",
  year = 2010,
  authors = c("John Snow" = "AFSC", "Danny Phantom" = "NEFSC", "Patrick Star" = "SEFSC-ML"),
  include_affiliation = TRUE,
  new_section = "an_additional_section",
  section_location = "after-introduction"
)

quarto::quarto_render(file.path(getwd(), "report", "SAR_USWC_Dover_sole_skeleton.qmd"))

add_tagging(
  x = "SAR_USWC_Dover_sole_skeleton.tex",
  dir = file.path(getwd(), "report"),
  compile = TRUE
)

## End(Not run)

Author affiliations

Description

Reference table containing information about authors' affiliations, including regional office acronyms, addresses, and the standardized way to reference each office in create_template() when specifying the authors argument.

Usage

affiliation_info

Format

A data frame with rows and columns.

Generate Citation for Stock Assessment Report

Description

Generate Citation for Stock Assessment Report

Usage

create_citation(
  authors = NULL,
  title = "[TITLE]",
  year = format(as.POSIXct(Sys.Date(), format = "%YYYY-%mm-%dd"), "%Y")
)

Arguments

authors

String. A character vector of author names and affiliations. For example, a Jane Doe at the NWFSC Seattle, Washington office would have an entry of c("Jane Doe"="NWFSC-SWA"). Information on NOAA offices can be found with: asar::affiliation_info. Keys to the office addresses follow the naming convention of: office acronym (ex. NWFSC), a hyphen (-), the first initial of the city, and then the two-letter abbreviation for the state the office is located in. If the city has two or more words (e.g., Panama City), the first initial of each word is used in the key (ex. Panama City, Florida = PCFL).

Default: NULL

Options: See asar::affiliation_info.
title

String. Custom report title superceding the default composed in asar::create_title(). Example: "Management Track Assessments Spring 2024".

Default: ⁠[TITLE]⁠. If species and region are provided, a title will be generated based on the report type, species, and region.
year

Number. Year the assessment is conducted.

Default: the year in which the report is rendered.

Value

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

Examples

## Not run: 
create_citation(
  title = "SA Report for Jellyfish",
  authors = c("Danny Phantom" = "SWFSC-LJCA", "John Snow" = "AFSC-ABL", "Jane Doe" = "NWFSC-SWA"),
  year = 2024
)

## End(Not run)

Create Quarto Document of Figures

Description

Create Quarto Document of Figures

Usage

create_figures_doc(subdir = getwd(), figures_dir = getwd())

Arguments

subdir

Path. Location of subdirectory storing the assessment report template
figures_dir

Path. Location of the "figures" folder, which contains figures files.

Value

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

Examples

## Not run: 
create_figures_doc(
  subdir = getwd(),
  figures_dir = here::here()
)

## End(Not run)

Create in-header latex document

Description

Create in-header latex document

Usage

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

Arguments

species

String. Common species name - used for footer
year

Number. Year assessment is conducted
subdir

Path. 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

Only tables in an rda format (e.g., my_table.rda) will be imported. Tables in other formats (e.g., .jpg, .png) are not supported; they lack text recognition. See the asar custom figures and tables vignette for more information about making .rda files with custom tables.

Usage

create_tables_doc(subdir = getwd(), tables_dir = getwd())

Arguments

subdir

Path. Location of subdirectory storing the assessment report template
tables_dir

Path. Location of the "tables" folder, which contains tables files.

Details

If your table is too wide to print on a portrait-oriented page, the page will be rotated to landscape view. If if is too wide to print in landscape view, it will be split into multiple tables. In this case, a new rda will be created and is identifiable by the phrase "split" in the filename (e.g., indices.abundance_table.rda will generate a new indices.abundance_table_split.rda file), and column 1 will be repeated across split tables. These tables will share the same caption. To specify a different repeated column(s), use asar::export_split_tbls with your preferred essential_columns value.

Value

Create a quarto document as part of a stock assessment outline with pre-loaded R chunks that add stock assessment tables from the nmfs-ost/stockplotr R package, or other tables in the same rda format.

Examples

## Not run: 
create_tables_doc(
  subdir = getwd(),
  tables_dir = here::here()
)

## End(Not run)

Create Stock Assessment Report Template

Description

Generates a set of Quarto files (.qmd) that set up a stock assessment report with supporting files. Function builds a YAML specific to the region and utilizes current resources and workflows from different NOAA Fishery Science Centers. Automates authorship, bibliography, and other report components.

Usage

create_template(
  format = "pdf",
  type = "sar",
  office = NULL,
  region = NULL,
  species = "species",
  spp_latin = NULL,
  year = format(as.POSIXct(Sys.Date(), format = "%YYYY-%mm-%dd"), "%Y"),
  authors = NULL,
  file_dir = getwd(),
  title = "[TITLE]",
  model_results = NULL,
  tables_dir = getwd(),
  figures_dir = getwd(),
  spp_image = NULL,
  bib_file = TRUE,
  new_template = TRUE,
  custom_sections = NULL,
  new_section = NULL,
  section_location = NULL,
  custom_params = NULL,
  rerender_skeleton = lifecycle::deprecated(),
  param_names = lifecycle::deprecated(),
  param_values = lifecycle::deprecated(),
  ...
)

Arguments

format

String. Report rendering format. Note: "docx" is currently unsupported and will default to "pdf".

Default: "pdf"

Options: "pdf", "html"
type

String. Report template type.

Default: "sar" (a NOAA standard "Stock Assessment Report")

Options: "sar" (Stock Assessment Report), "nemt" (Northeast Management Track), "pfmc" (Pacific Fishery Management Council), "safe" (Stock Assessment and Fishery Evaluation)
office

String. Regional Fisheries Science Center producing the report.

Default: NULL

Options: "AFSC", "NEFSC", "NWFSC", "PIFSC", "SEFSC", "SWFSC"
region

String. Full name of the stock's sub-region, if applicable. If the region is not specified for your center or species, leave default. Example: "US West Coast".

Default: NULL
species

String. Common name of target species. Split multi-word names with space and capitalize first letter(s). Example: "Dover sole".

Default: "species"
spp_latin

String. Latin name of target species. Example: "Pomatomus saltatrix".

Default: NULL
year

Number. Year the assessment is conducted.

Default: the year in which the report is rendered.
authors

String. A character vector of author names and affiliations. For example, a Jane Doe at the NWFSC Seattle, Washington office would have an entry of c("Jane Doe"="NWFSC-SWA"). Information on NOAA offices can be found with: asar::affiliation_info. Keys to the office addresses follow the naming convention of: office acronym (ex. NWFSC), a hyphen (-), the first initial of the city, and then the two-letter abbreviation for the state the office is located in. If the city has two or more words (e.g., Panama City), the first initial of each word is used in the key (ex. Panama City, Florida = PCFL).

Default: NULL

Options: See asar::affiliation_info.
file_dir

Path. Directory where report files will be created.

Default: the working directory (getwd()).
title

String. Custom report title superceding the default composed in asar::create_title(). Example: "Management Track Assessments Spring 2024".

Default: ⁠[TITLE]⁠. If species and region are provided, a title will be generated based on the report type, species, and region.
model_results

Path. Filepath to the standardized, converted model output .rda file generated with stockplotr::convert_output(), relative to the skeleton .qmd file that will be created within the 'report' folder.

Default: NULL
tables_dir

Path. The location of the "tables" folder, which contains tables files

Default: the working directory
figures_dir

Path. The location of the "figures" folder, which contains figures files

Default: the working directory
spp_image

Path. Filepath to a custom species image to be used on the report cover. Supported file extension is .png. If empty, searches asar resources for a matching species name.

Default: NULL
bib_file

Path or logical. A character string of the path to a custom .bib file, or a logical (TRUE/FALSE). If a path is provided, the custom file is used and journal templates are skipped. If TRUE, default journal .bib templates are downloaded. If FALSE or NULL (default), a minimal .bib file containing only the asar package citation is created.

Default: TRUE
new_template

Logical. TRUE/FALSE; Create a new template? If true, will pull the last saved stock assessment report skeleton.

Default: FALSE
custom_sections

List of existing sections to include in a custom template (rather than the default for stock assessments in your region). If adding a new section, also use arguments 'new_section' and 'section_location'.

Default: NULL

Options: 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').
new_section

String. Names of section(s) (e.g., "Special Section") 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.

Default: NULL
section_location

String. 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.

Default: NULL
custom_params

List. Character vector of additional custom parameter names and values to include in the skeleton YAML. For example, a parameter "year2" and its value "2026" would have an entry of c("year2" = "2026"). Parameters automatically included: office, region, species (each of which are listed as individual parameters for this function, above).

Default: NULL
rerender_skeleton

[Deprecated] This argument was deprecated in favor of a separate function rerender_skeleton() in order to provide more clarity and separation of functionality.
param_names

[Deprecated] This argument was deprecated in favor of the custom_params argument in order to provide more clarity and decrease necessary arguments.
param_values

[Deprecated] This argument was deprecated in favor of the custom_params argument in order to provide more clarity and decrease necessary arguments.
...

Additional arguments passed into functions used in create_template such as create_citation() or create_yaml().

Details

The function creates a ⁠report/⁠ subdirectory within file_dir. The primary file is a "skeleton" Quarto document that calls various sections as child documents. The skeleton will be named based on arguments provided to create_template(). For instance, in example 2, below, the filename would be 'sar_Dover_sole_skeleton.qmd'.

The skeleton contains several sections that should require little to no editing by the user. These sections include: the yaml, Parameters R chunk, Preamble R chunk, Disclaimer, and Citations.

Report content is called as child documents in this skeleton. Each child document (e.g., '01_executive_summary.qmd', '02_introduction.qmd') should be edited separately.

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

For help with editing any of the sections in the skeleton, please see the cheatsheet, tutorial, and other resources available at https://nmfs-ost.github.io/asar/.

Value

Path to the created ⁠report/⁠ directory containing files needed to produce the stock assessment report. Side effects include the creation of a directory structure, .qmd files, and support files (e.g., images, .bib, .tex).

See Also

add_authors(), add_base_section(), add_child(), add_chunk(), add_base_section(), add_section(), create_citation(), create_figures_doc(), create_tables_doc(), create_title(), create_yaml(), format_quarto()

Examples

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

create_template(
  new_template = TRUE,
  format = "pdf",
  office = "NWFSC",
  species = "Dover sole",
  spp_latin = "Microstomus pacificus",
  year = 2010,
  authors = c(
    "John Snow" = "AFSC",
    "Danny Phantom" = "NEFSC",
    "Patrick Star" = "SEFSC-ML"
  ),
  model_results = here::here("folder", "std_output.rda"),
  figures_dir = here::here(),
  tables_dir = here::here("tables_folder_location"),
  new_section = "an_additional_section",
  section_location = "after-introduction"
)

asar::create_template(
  new_template = TRUE,
  format = "pdf",
  office = "PIFSC",
  species = "Striped marlin",
  spp_latin = "Kajikia audax",
  year = 2018,
  authors = c("John Snow" = "AFSC"),
  new_section = c("a_new_section", "another_new_section"),
  section_location = c("before-introduction", "after-introduction"),
  custom_sections = c("executive_summary", "introduction")
)

create_template(
  new_template = TRUE,
  format = "pdf",
  office = "NWFSC",
  region = "my_region",
  species = "Bluefish",
  spp_latin = "Pomatomus saltatrix",
  year = 2010,
  authors = c("John Snow" = "NEFSC", "Danny Phantom" = "SWFSC", "Patrick Star" = "SEFSC-ML"),
  title = "Management Track Assessments Spring 2024",
  custom_params = c("region2" = "North Coast", "year2" = "2026"),
  model_results = here::here("folder", "std_output.rda"),
  new_section = "an_additional_section",
  section_location = "before-discussion",
  type = "sar",
  custom_sections = c("executive_summary", "introduction", "discussion"),
  spp_image = "dir/containing/spp_image"
)

## End(Not run)

Write Stock Assessment Report Title

Description

Write Stock Assessment Report Title

Usage

create_title(
  type = "skeleton",
  office = "",
  species = "species",
  spp_latin = NULL,
  region = NULL,
  year = format(Sys.Date(), "%Y"),
  complex = NULL
)

Arguments

type

String. Report template type.

Default: "sar" (a NOAA standard "Stock Assessment Report")

Options: "sar" (Stock Assessment Report), "nemt" (Northeast Management Track), "pfmc" (Pacific Fishery Management Council), "safe" (Stock Assessment and Fishery Evaluation)
office

String. Regional Fisheries Science Center producing the report.

Default: NULL

Options: "AFSC", "NEFSC", "NWFSC", "PIFSC", "SEFSC", "SWFSC"
species

String. Common name of target species. Split multi-word names with space and capitalize first letter(s). Example: "Dover sole".

Default: "species"
spp_latin

String. Latin name of target species. Example: "Pomatomus saltatrix".

Default: NULL
region

String. Full name of the stock's sub-region, if applicable. If the region is not specified for your center or species, leave default. Example: "US West Coast".

Default: NULL
year

Number. Year the assessment is conducted.

Default: the year in which the report is rendered.
complex

Logical. TRUE/FALSE; Is this a species complex? Default is false.

Value

Return a string containing a title for a NOAA Fisheries stock assessment report.

Examples

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

Create a title page latex document

Description

Create a title page latex document

Usage

create_titlepage_tex(office = "", subdir, species = "")

Arguments

office

String. Primary science center writing the document
subdir

Path. Directory where files are going to be held
species

String. 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.

Create string for yml header in quarto file

Description

Create string for yml header in quarto file

Usage

create_yaml(
  format = "pdf",
  office = NULL,
  region = NULL,
  species = "species",
  spp_latin = NULL,
  spp_image = NULL,
  year = NULL,
  bib_name = NULL,
  author_list = NULL,
  title = "[TITLE]",
  rerender_skeleton = FALSE,
  prev_skeleton = NULL,
  prev_format = NULL,
  parameters = TRUE,
  custom_params = NULL,
  type = "SAR"
)

Arguments

format

String. Report rendering format. Note: "docx" is currently unsupported and will default to "pdf".

Default: "pdf"

Options: "pdf", "html"
office

String. Regional Fisheries Science Center producing the report.

Default: NULL

Options: "AFSC", "NEFSC", "NWFSC", "PIFSC", "SEFSC", "SWFSC"
region

String. Full name of the stock's sub-region, if applicable. If the region is not specified for your center or species, leave default. Example: "US West Coast".

Default: NULL
species

String. Common name of target species. Split multi-word names with space and capitalize first letter(s). Example: "Dover sole".

Default: "species"
spp_latin

String. Latin name of target species. Example: "Pomatomus saltatrix".

Default: NULL
spp_image

Path. Filepath to a custom species image to be used on the report cover. Supported file extension is .png. If empty, searches asar resources for a matching species name.

Default: NULL
year

Number. Year the assessment is conducted.

Default: the year in which the report is rendered.
bib_name

String. Name of a bib file being added into the yaml. For example, "asar.bib".
author_list

A vector of strings containing pre-formatted author names and affiliations that would be found in the format in a yaml of a quarto file when using base R function cat().
title

String. Custom report title superceding the default composed in asar::create_title(). Example: "Management Track Assessments Spring 2024".

Default: ⁠[TITLE]⁠. If species and region are provided, a title will be generated based on the report type, species, and region.
rerender_skeleton

TRUE/FALSE; Update the skeleton YAML and structure (R parameters, preamble, and skeleton sectioning) if relevant or indicated. All files in your folder, such as the .qmd child docs, will remain as is.

Default: FALSE
prev_skeleton

List. Vector of strings containing all the lines of the previous skeleton file. File is read in using the function readLines from base R.
prev_format

String. Format that the previous skeleton was directed to render to. Parameter is inherited from create_template.
parameters

Logical indicating whether to include parameters in the yaml. Default is TRUE.
custom_params

List. Character vector of additional custom parameter names and values to include in the skeleton YAML. For example, a parameter "year2" and its value "2026" would have an entry of c("year2" = "2026"). Parameters automatically included: office, region, species (each of which are listed as individual parameters for this function, above).

Default: NULL
type

String. Report template type.

Default: "sar" (a NOAA standard "Stock Assessment Report")

Options: "sar" (Stock Assessment Report), "nemt" (Northeast Management Track), "pfmc" (Pacific Fishery Management Council), "safe" (Stock Assessment and Fishery Evaluation)

Value

Create a string indicating the important formatting pieces for a quarto file for a stock assessment report.

Examples

## Not run: 
my_author_list <- paste(
  "  - name: 'Patrick Star'",
  "    affiliations:",
  "      - name: 'NOAA Fisheries Southeast Fisheries Science Center'",
  "        address: '75 Virginia Beach Drive'",
  "        city: 'Miami'",
  "        state: 'FL'",
  "        postal-code: '33149'",
  sep = "\n"
)
create_yaml(
  rerender_skeleton = FALSE,
  prev_skeleton = NULL,
  title = "My title",
  author_list = my_author_list,
  author = c("Patrick Star" = "SEFSC"),
  office = "SEFSC",
  add_author = NULL,
  spp_image = NULL,
  species = "",
  spp_latin = NULL,
  region = NULL,
  format = "pdf",
  parameters = TRUE,
  custom_params = NULL,
  bib_name = "asar_references.bib",
  year = 2025
)

## End(Not run)

Create and export glossary

Description

Create and export glossary

Usage

export_glossary()

Split extra-wide tables into smaller tables and export

Description

Split extra-wide tables into smaller tables and export

Usage

export_split_tbls(
  tables_dir = NULL,
  plot_name = NULL,
  essential_columns = NULL
)

Arguments

tables_dir

Path. Location of the "tables" folder, which contains tables files.
plot_name

String. Name of the .rda file containing the table
essential_columns

List. The columns that will be retained between the split tables, formatted as a sequence (e.g., 1:2 for columns 1-2, or 1 for a single column). Example: for the indices table, this could be the year column.

Value

The number of split tables

Examples

## Not run: 
export_split_tbls(
  tables_dir = here::here(),
  plot_name = "bnc_table.rda",
  essential_columns = 5
)

export_split_tbls(
  tables_dir = getwd(),
  plot_name = "indices.abundance_table.rda",
  essential_columns = 1:2
)

## End(Not run)

Add Formatting Arguments for YAML Header

Description

Add Formatting Arguments for YAML Header

Usage

format_quarto(format = "pdf", type = "sar")

Arguments

format

String. Report rendering format. Note: "docx" is currently unsupported and will default to "pdf".

Default: "pdf"

Options: "pdf", "html"
type

String. Report template type.

Default: "sar" (a NOAA standard "Stock Assessment Report")

Options: "sar" (Stock Assessment Report), "nemt" (Northeast Management Track), "pfmc" (Pacific Fishery Management Council), "safe" (Stock Assessment and Fishery Evaluation)

Value

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

Examples

## Not run: 
format_quarto(format = "pdf")

## End(Not run)

Map legacy document names to current document names

Description

Map legacy document names to current document names

Usage

get_doc_order()

Value

A list containing vector mappings for legacy and current tables and figures files.

Split a table into a group of tables (a gt_group)

Description

With a gt table, you can split it into multiple tables and get that collection in a gt_group object. This function is useful for those cases where you want to section up a table in a specific way and print those smaller tables across multiple pages (in RTF and Word outputs, primarily via gtsave, or, with breaks between them when the output context is HTML.

Usage

gt_split(data, row_every_n = NULL, row_slice_i = NULL, col_slice_at = NULL)

Arguments

data

The gt table data object

⁠obj:<gt_tbl>⁠ // required

This is the gt table object that is commonly created through use of the gt() function.
row_every_n

Split at every n rows

⁠scalar<numeric|integer>⁠ // default: NULL (optional)

A directive to split at every n number of rows. This argument expects a single numerical value.
row_slice_i

Row-slicing indices

⁠vector<numeric|integer>⁠ // default: NULL (optional)

An argument for splitting at specific row indices. Here, we expect either a vector of index values or a function that evaluates to a numeric vector.
col_slice_at

Column-slicing locations

⁠<column-targeting expression>⁠ // default: NULL (optional)

Any columns where vertical splitting across should occur. The splits occur to the right of the resolved column names. Can either be a series of column names provided in c(), a vector of column indices, or a select helper function (e.g. starts_with, ends_with, contains, matches, num_range, and everything).

Value

An object of class gt_group.

Examples

Use a subset of the gtcars dataset to create a gt table. Format the msrp column to display numbers as currency values, set column widths with cols_width, and split the table at every five rows with gt_split(). This creates a gt_group object containing two tables. Printing this object yields two tables separated by a line break. 

gtcars |>
  dplyr::slice_head(n = 10) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt() |>
  fmt_currency(columns = msrp) |>
  cols_width(
    year ~ px(80),
    everything() ~ px(150)
  ) |>
  gt_split(row_every_n = 5)

Use a smaller subset of the gtcars dataset to create a gt table. Format the msrp column to display numbers as currency values, set the table width with tab_options() and split the table at the model column This creates a gt_group object again containing two tables but this time we get a vertical split. Printing this object yields two tables of the same width. 

gtcars |>
  dplyr::slice_head(n = 5) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt() |>
  fmt_currency(columns = msrp) |>
  tab_options(table.width = px(400)) |>
  gt_split(col_slice_at = "model")

Function ID

14-2

Function Introduced

v0.9.0 (Mar 31, 2023)

Note

This function is a temporary export of asar, but all development and rights belong to rstudio/gt. This function provides a fix to the function introduced by a bug in gt v1.3.0. Until this is corrected in the package, we are using the function here. Once this bug is patched, we will deprecate and remove this function from asar and direct users to use the gt package version of this function.

Identify table length class

Description

Identify table length class

Usage

ID_tbl_length_class(tables_dir, plot_name)

Arguments

tables_dir

Path. Location of the "tables" folder, which contains tables files.
plot_name

String. Name of the .rda file containing the table

Value

The length class of a table: regular or long. The result will determine whether the table can be rendered on a page as-is, or if it needs to be split across multiple pages.

Examples

## Not run: 
ID_tbl_length_class(
  plot_name = "indices.abundance_table.rda",
  tables_dir = here::here()
)

## End(Not run)

Identify table width class

Description

Identify table width class

Usage

ID_tbl_width_class(tables_dir, plot_name, portrait_pg_width)

Arguments

tables_dir

Path. Location of the "tables" folder, which contains tables files.
plot_name

String. Name of the .rda file containing the table
portrait_pg_width

Number. The amount of space between the margins of a portrait-oriented page, in inches. Represents the threshold for the maximum width of a table that can be rendered on a portrait page before it needs to be resized, rotated, and/or split across multiple pages.

Value

The width class of a table: regular, wide, or extra-wide. The result will determine whether the table can be rendered on a portrait page as-is, or if it needs to be resized, rotated, and/or split across multiple pages.

Examples

## Not run: 
ID_tbl_width_class(
  plot_name = "indices.abundance_table.rda",
  tables_dir = here::here(),
  portrait_pg_width = 5
)

## End(Not run)

Detect, rename, and resolve legacy document paths

Description

Detect, rename, and resolve legacy document paths

Usage

migrate_legacy_docs(subdir, doc_type, rerender_skeleton = FALSE)

Arguments

subdir

Path. Directory where template files are located.
doc_type

String. Document type.

Options: "figures", "tables"
rerender_skeleton

Logical. TRUE/FALSE; Indicate if rerendering is active.

Default: FALSE

Value

A list containing using_legacy (logical), legacy_name, current_name, and resolved_name.

Split an extra-wide table into multiple tables

Description

Split an extra-wide table into multiple tables

Usage

render_lg_table(report_gt, essential_columns, tables_dir, plot_name)

Arguments

report_gt

List. The extra-wide gt table.
essential_columns

List. The columns that will be retained between the split tables, formatted as a sequence (e.g., 1:2 for columns 1-2, or 1 for a single column). Example: for the indices table, this could be the year column.
tables_dir

Path. Location of the "tables" folder, which contains tables files.
plot_name

String. Name of the .rda file containing the table

Value

A list of the split tables.

Examples

## Not run: 
render_lg_table(
  report_gt = indices_table,
  essential_columns = 1,
  tables_dir = here::here(),
  plot_name = "indices.abundance_table.rda"
)

render_lg_table(
  report_gt = important_table,
  essential_columns = 1:3,
  tables_dir = "data",
  plot_name = "bnc_table.rda"
)

## End(Not run)

Rerender skeleton quarto document

Description

Rerender skeleton quarto document

Usage

rerender_skeleton(
  file_dir,
  species = "species",
  spp_latin = NULL,
  office = NULL,
  region = NULL,
  year = format(as.POSIXct(Sys.Date(), format = "%YYYY-%mm-%dd"), "%Y"),
  custom_sections = NULL,
  new_section = NULL,
  section_location = NULL,
  custom_params = NULL,
  title = "[TITLE]",
  model_results = NULL,
  bib_file = NULL,
  type = "sar",
  spp_image = NULL,
  format = "pdf",
  authors = NULL
)

Arguments

file_dir

Required. Directory where the skeleton file is located. Can include or leave out the report folder in the path.
species

String. Common name of target species. Split multi-word names with space and capitalize first letter(s). Example: "Dover sole".

Default: "species"
spp_latin

String. Latin name of target species. Example: "Pomatomus saltatrix".

Default: NULL
office

String. Regional Fisheries Science Center producing the report.

Default: NULL

Options: "AFSC", "NEFSC", "NWFSC", "PIFSC", "SEFSC", "SWFSC"
region

String. Full name of the stock's sub-region, if applicable. If the region is not specified for your center or species, leave default. Example: "US West Coast".

Default: NULL
year

Number. Year the assessment is conducted.

Default: the year in which the report is rendered.
custom_sections

List of existing sections to include in a custom template (rather than the default for stock assessments in your region). If adding a new section, also use arguments 'new_section' and 'section_location'.

Default: NULL

Options: 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').
new_section

String. Names of section(s) (e.g., "Special Section") 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.

Default: NULL
section_location

String. 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.

Default: NULL
custom_params

List. Character vector of additional custom parameter names and values to include in the skeleton YAML. For example, a parameter "year2" and its value "2026" would have an entry of c("year2" = "2026"). Parameters automatically included: office, region, species (each of which are listed as individual parameters for this function, above).

Default: NULL
title

String. Custom report title superceding the default composed in asar::create_title(). Example: "Management Track Assessments Spring 2024".

Default: ⁠[TITLE]⁠. If species and region are provided, a title will be generated based on the report type, species, and region.
model_results

Path. Filepath to the standardized, converted model output .rda file generated with stockplotr::convert_output(), relative to the skeleton .qmd file that will be created within the 'report' folder.

Default: NULL
bib_file

A character string of the path to a custom .bib file, or a logical. If a path is provided, the custom file is added to the skeleton and copied into the bibliography files folder.

Default: NULL
type

String. Report template type.

Default: "sar" (a NOAA standard "Stock Assessment Report")

Options: "sar" (Stock Assessment Report), "nemt" (Northeast Management Track), "pfmc" (Pacific Fishery Management Council), "safe" (Stock Assessment and Fishery Evaluation)
spp_image

Path. Filepath to a custom species image to be used on the report cover. Supported file extension is .png. If empty, searches asar resources for a matching species name.

Default: NULL
format

String. Report rendering format. Note: "docx" is currently unsupported and will default to "pdf".

Default: "pdf"

Options: "pdf", "html"
authors

String. A character vector of author names and affiliations. For example, a Jane Doe at the NWFSC Seattle, Washington office would have an entry of c("Jane Doe"="NWFSC-SWA"). Information on NOAA offices can be found with: asar::affiliation_info. Keys to the office addresses follow the naming convention of: office acronym (ex. NWFSC), a hyphen (-), the first initial of the city, and then the two-letter abbreviation for the state the office is located in. If the city has two or more words (e.g., Panama City), the first initial of each word is used in the key (ex. Panama City, Florida = PCFL).

Default: NULL

Options: See asar::affiliation_info.

Value

Update the "skeleton" file produce after running create_template. Prevents the loss of data in child documents and make easy updates without prior knowledge of quarto.

Examples

## Not run: 
rerender_skeleton(
file_dir = getwd(),
species = "Red Snapper",
office = "SEFSC",
region = "Gulf of America",
year = 2027,
authors = c("Jane Doe" = "SEFSC")
)

## End(Not run)

Call previous assessment report and update

Description

Call previous assessment report and update

Usage

update_report(
  file_dir = getwd(),
  previous_file_dir,
  authors = NULL,
  model_results = NULL,
  year = format(as.POSIXct(Sys.Date(), format = "%YYYY-%mm-%dd"), "%Y"),
  format = "pdf",
  region = NULL,
  custom_sections = TRUE,
  new_section = NULL,
  section_location = NULL,
  figures_dir = getwd(),
  tables_dir = getwd(),
  reset_tables_and_figures = FALSE,
  reset_authors = FALSE
)

Arguments

file_dir

String of the path where the new report folder and files should be located. Required.

Default: The working directory (getwd())
previous_file_dir

String of the path where the previous report files are located. Required.
authors

String. A character vector of author names and affiliations. For example, a Jane Doe at the NWFSC Seattle, Washington office would have an entry of c("Jane Doe"="NWFSC-SWA"). Information on NOAA offices can be found with: asar::affiliation_info. Keys to the office addresses follow the naming convention of: office acronym (ex. NWFSC), a hyphen (-), the first initial of the city, and then the two-letter abbreviation for the state the office is located in. If the city has two or more words (e.g., Panama City), the first initial of each word is used in the key (ex. Panama City, Florida = PCFL).

Default: NULL

Options: See asar::affiliation_info.
model_results

Path. Filepath to the standardized, converted model output .rda file generated with stockplotr::convert_output(), relative to the skeleton .qmd file that will be created within the 'report' folder.

Default: NULL
year

Number. Year the assessment is conducted.

Default: the year in which the report is rendered.
format

String. Report rendering format. Note: "docx" is currently unsupported and will default to "pdf".

Default: "pdf"

Options: "pdf", "html"
region

String. Full name of the stock's sub-region, if applicable. If the region is not specified for your center or species, leave default. Example: "US West Coast".

Default: NULL
custom_sections

Logical. Indicate whether the previous report had a customized sectioning. If TRUE, the report outline will mimic the previous report. If FALSE, the report will include the full standard guidelines outline along with any custom sectioning from the previous report.

Default: FALSE
new_section

String. Names of section(s) (e.g., "Special Section") 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.

Default: NULL
section_location

String. 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.

Default: NULL
figures_dir

Path. The location of the "figures" folder, which contains figures files

Default: the working directory
tables_dir

Path. The location of the "tables" folder, which contains tables files

Default: the working directory
reset_tables_and_figures

Logical indicating whether to reset tables and figures Quarto documents.

Default: FALSE
reset_authors

Logical indicating whether to reset authorship for the report. Only will work if authors argument is also used.

Default: FALSE

Details

This function is designed so a report made from asar::create_template() can be called and updated with the following:

  • year (year)

  • model results (model_results)

  • authorship (authors)

  • region (region)

  • custom sections (custom_sections )

  • new sections (⁠new_section and section_location⁠)

  • figure and table folder locations (⁠figures_dir and tables_dir⁠)

  • format (format)

  • check standard structure against current structure (performed automatically)

This function performs three major tasks: (1) copies all files from the old directory to the new one, (2) updates the skeleton according the the input arguments using the rerender_skeleton() function, and (3) if desired, resets your figures and tables documents.

Value

Creates a new folder of pre-filled assessment report files for the next assessment cycle.

Examples

## Not run: 
update_report(
  previous_file_dir = "~/testing/goa_2023/report",
  file_dir = "~/testing/goa_2025",
  model_results = "../new_std_res.rda")
  
update_report(
  previous_file_dir = "report_a",
  file_dir = "report_b",
  year = 2027,
  authors = c("John Doe" = "NEFSC"),
  reset_authors = TRUE
)

## End(Not run)