| 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.4.0.9000 |
| Built: | 2026-07-23 15:42:40 UTC |
| Source: | https://github.com/nmfs-ost/asar |
Altering latex file of report to increase accessibility of the document.
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 )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 )
x |
.tex file containing report. Typically produced after initially rendering the skeleton made from create_template. |
dir |
directory where the tex file is located that will be edited |
alttext_csv |
File path for the csv file containing alternative text and captions generated when running stockplotr::exp_all_figs_tables |
compile |
Indicate whether the document (X) should be rendered after these files are changed. Default TRUE. |
rename |
Indicate a name for the new tex file produced from this function. There is no need to include ".tex" in the name. Defaults to current name and overwrites the current tex file. |
This function runs all functions from asar associated with
accessibility and renders the final document. The document is tagged and
includes alternative text from the captions_alt_text.csv produced from
stockplotr package also available on GitHub.
## 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)## 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
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 )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 )
x |
.tex file containing report. Typically produced after initially rendering the skeleton made from create_template. |
dir |
directory where the tex file is located that will be edited |
alttext_csv |
File path for the csv file containing alternative text and captions generated when running stockplotr::exp_all_figs_tables |
compile |
Indicate whether the document (X) should be rendered after these files are changed. Default TRUE. |
rename |
Indicate a name for the new tex file produced from this function. There is no need to include ".tex" in the name. Defaults to current name and overwrites the current tex file. |
tagged |
Indicate if the input tex file from dir has the latex package, tagpdf, used so that tagging is present. |
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.
## 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)## 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
add_authors(authors, rerender_skeleton = FALSE, prev_skeleton = NULL)add_authors(authors, rerender_skeleton = FALSE, prev_skeleton = NULL)
authors |
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: Default: NULL Options: See |
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 Default: FALSE |
prev_skeleton |
A character vector of the previous skeleton file read in through |
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.
## Not run: add_authors( authors = c("Danny Phantom" = "SWFSC-LJCA", "John Snow" = "AFSC-ABL", "Jane Doe" = "NWFSC-SWA"), rerender_skeleton = FALSE ) ## End(Not run)## 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
add_base_section(custom_sections = NULL)add_base_section(custom_sections = NULL)
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
|
Call and copy the sections in the package templates to create an outline for a stock assessment
add_base_section(c("executive summary", "assessment", "results"))add_base_section(c("executive summary", "assessment", "results"))
Write R Chunk to Add Child Document
add_child(x, label = NULL)add_child(x, label = NULL)
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. |
Formatting R chunk for child document to add section into the template/skeleton. Utilize the cat() function to implement into readable text.
add_child("test_quarto.qmd", label = "test_doc")add_child("test_quarto.qmd", label = "test_doc")
Write R chunk to template
add_chunk( x, label = NULL, add_option = TRUE, chunk_option = c("warnings: false", "eval: true"), rmark_option = NULL )add_chunk( x, label = NULL, add_option = TRUE, chunk_option = c("warnings: false", "eval: true"), rmark_option = NULL )
x |
Content to be written within the R chunk. Wrap in quotation marks (""). |
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_option |
List of chunk options to add. For example: c("output: true", "error: false) |
rmark_option |
List of chunk options to add after indicating the language of the chunk as used in Rmarkdown. |
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
add_chunk("plot(cars$speed, cars$distance)")add_chunk("plot(cars$speed, cars$distance)")
Add New Section or Subsection to Template
add_section( subdir = NULL, custom_sections = NULL, new_section = NULL, section_location = NULL )add_section( subdir = NULL, custom_sections = NULL, new_section = NULL, section_location = NULL )
subdir |
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
|
new_section |
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 |
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 |
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.
add_section( new_section = "Ecosystem Considerations", section_location = "after-discussion", custom_sections = c("introduction.qmd", "model.qmd", "results.qmd", "discussion.qmd"), subdir = tempdir() )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
add_tagging( x = list.files(getwd())[grep("skeleton.tex", list.files(getwd()))], dir = getwd(), compile = TRUE, rename = NULL )add_tagging( x = list.files(getwd())[grep("skeleton.tex", list.files(getwd()))], dir = getwd(), compile = TRUE, rename = NULL )
x |
.tex file containing report. Typically produced after initially rendering the skeleton made from create_template. |
dir |
directory where the tex file is located that will be edited |
compile |
Indicate whether the document (X) should be rendered after these files are changed. Default TRUE. |
rename |
Indicate a name for the new tex file produced from this function. There is no need to include ".tex" in the name. Defaults to current name and overwrites the current tex file. |
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.
## 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)## 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)
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.
affiliation_infoaffiliation_info
A data frame with rows and columns.
Generate Citation for Stock Assessment Report
create_citation( authors = NULL, title = "[TITLE]", year = format(as.POSIXct(Sys.Date(), format = "%YYYY-%mm-%dd"), "%Y") )create_citation( authors = NULL, title = "[TITLE]", year = format(as.POSIXct(Sys.Date(), format = "%YYYY-%mm-%dd"), "%Y") )
authors |
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: Default: NULL Options: See |
title |
Custom report title superceding the default composed in
Default: |
year |
Year the assessment is conducted. Default: the year in which the report is rendered. |
Generate a citation for use in publications and other
references associated with the stock assessment report produced
with asar.
## 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)## 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
create_figures_doc(subdir = getwd(), figures_dir = getwd())create_figures_doc(subdir = getwd(), figures_dir = getwd())
subdir |
Location of subdirectory storing the assessment report template |
figures_dir |
The location of the "figures" folder, which contains figures files. |
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.
## Not run: create_figures_doc( subdir = getwd(), figures_dir = here::here() ) ## End(Not run)## Not run: create_figures_doc( subdir = getwd(), figures_dir = here::here() ) ## End(Not run)
Create in-header latex document
create_inheader_tex(species = NULL, year = NULL, subdir)create_inheader_tex(species = NULL, year = NULL, subdir)
species |
common species name - used for footer |
year |
year assessment is conducted |
subdir |
directory where other files will be copied into |
Create an in-header latex document that dynamically changes based on the species and year along with other factors.
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.
create_tables_doc(subdir = getwd(), tables_dir = getwd())create_tables_doc(subdir = getwd(), tables_dir = getwd())
subdir |
Location of subdirectory storing the assessment report template |
tables_dir |
The location of the "tables" folder, which contains tables files. |
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.
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.
## Not run: create_tables_doc( subdir = getwd(), tables_dir = here::here() ) ## End(Not run)## Not run: create_tables_doc( subdir = getwd(), tables_dir = here::here() ) ## End(Not run)
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.
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 = "asar_references.bib", new_template = TRUE, rerender_skeleton = FALSE, custom_sections = NULL, new_section = NULL, section_location = NULL, custom_params = NULL, ... )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 = "asar_references.bib", new_template = TRUE, rerender_skeleton = FALSE, custom_sections = NULL, new_section = NULL, section_location = NULL, custom_params = NULL, ... )
format |
Report rendering format. Note: "docx" is currently unsupported and will default to "pdf". Default: "pdf" Options: "pdf", "html" |
type |
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 |
Regional Fisheries Science Center producing the report. Default: NULL Options: "AFSC", "NEFSC", "NWFSC", "PIFSC", "SEFSC", "SWFSC" |
region |
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 |
Common name of target species. Split multi-word names with space and capitalize first letter(s). Example: "Dover sole". Default: "species" |
spp_latin |
Latin name of target species. Example: "Pomatomus saltatrix". Default: NULL |
year |
Year the assessment is conducted. Default: the year in which the report is rendered. |
authors |
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: Default: NULL Options: See |
file_dir |
Directory where report files will be created. Default: the working directory ( |
title |
Custom report title superceding the default composed in
Default: |
model_results |
Filepath to the standardized, converted model output
.rda file generated with Default: NULL |
tables_dir |
The location of the "tables" folder, which contains tables files Default: the working directory |
figures_dir |
The location of the "figures" folder, which contains figures files Default: the working directory |
spp_image |
Filepath to a custom species image to be used on the
report cover. Supported file extension is .png.
If empty, searches Default: NULL |
bib_file |
File path to bibliography file ( Default: "asar_references.bib" |
new_template |
TRUE/FALSE; Create a new template? If true, will pull the last saved stock assessment report skeleton. Default: FALSE |
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 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
|
new_section |
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 |
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 |
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
Default: NULL |
... |
Additional arguments passed into functions used in create_template
such as |
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/.
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).
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()
## 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)## 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
create_title( type = "skeleton", office = "", species = "species", spp_latin = NULL, region = NULL, year = format(Sys.Date(), "%Y"), complex = NULL )create_title( type = "skeleton", office = "", species = "species", spp_latin = NULL, region = NULL, year = format(Sys.Date(), "%Y"), complex = NULL )
type |
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 |
Regional Fisheries Science Center producing the report. Default: NULL Options: "AFSC", "NEFSC", "NWFSC", "PIFSC", "SEFSC", "SWFSC" |
species |
Common name of target species. Split multi-word names with space and capitalize first letter(s). Example: "Dover sole". Default: "species" |
spp_latin |
Latin name of target species. Example: "Pomatomus saltatrix". Default: NULL |
region |
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 |
Year the assessment is conducted. Default: the year in which the report is rendered. |
complex |
TRUE/FALSE; Is this a species complex? Default is false. |
Return a string containing a title for a NOAA Fisheries stock assessment report.
create_title( type = "SAR", office = "SEFSC", species = "Red Snapper", spp_latin = "Lutjanus campechanus", region = "South Atlantic", year = 2024 )create_title( type = "SAR", office = "SEFSC", species = "Red Snapper", spp_latin = "Lutjanus campechanus", region = "South Atlantic", year = 2024 )
Create a title page latex document
create_titlepage_tex(office = "", subdir, species = "")create_titlepage_tex(office = "", subdir, species = "")
office |
primary science center writing the document |
subdir |
directory where files are going to be held |
species |
target species for assessment |
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
create_yaml( format = "pdf", office = NULL, region = NULL, species = "species", spp_latin = NULL, spp_image = NULL, year = NULL, bib_name = NULL, bib_file = "asar_references.bib", author_list = NULL, title = "[TITLE]", rerender_skeleton = FALSE, prev_skeleton = NULL, prev_format = NULL, parameters = TRUE, custom_params = NULL, type = "SAR" )create_yaml( format = "pdf", office = NULL, region = NULL, species = "species", spp_latin = NULL, spp_image = NULL, year = NULL, bib_name = NULL, bib_file = "asar_references.bib", author_list = NULL, title = "[TITLE]", rerender_skeleton = FALSE, prev_skeleton = NULL, prev_format = NULL, parameters = TRUE, custom_params = NULL, type = "SAR" )
format |
Report rendering format. Note: "docx" is currently unsupported and will default to "pdf". Default: "pdf" Options: "pdf", "html" |
office |
Regional Fisheries Science Center producing the report. Default: NULL Options: "AFSC", "NEFSC", "NWFSC", "PIFSC", "SEFSC", "SWFSC" |
region |
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 |
Common name of target species. Split multi-word names with space and capitalize first letter(s). Example: "Dover sole". Default: "species" |
spp_latin |
Latin name of target species. Example: "Pomatomus saltatrix". Default: NULL |
spp_image |
Filepath to a custom species image to be used on the
report cover. Supported file extension is .png.
If empty, searches Default: NULL |
year |
Year the assessment is conducted. Default: the year in which the report is rendered. |
bib_name |
Name of a bib file being added into the yaml. For example, "asar.bib". |
bib_file |
File path to bibliography file ( Default: "asar_references.bib" |
author_list |
A list 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 |
title |
Custom report title superceding the default composed in
Default: |
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 Default: FALSE |
prev_skeleton |
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 |
The format that the previous skeleton was directed to render to. Parameter is inherited from create_template. |
custom_params |
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
Default: NULL |
type |
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) |
Create a string indicating the important formatting pieces for a quarto file for a stock assessment report.
## 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_file = "path/asar_references.bib", bib_name = "asar_references.bib", year = 2025 ) ## End(Not run)## 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_file = "path/asar_references.bib", bib_name = "asar_references.bib", year = 2025 ) ## End(Not run)
Create and export glossary
export_glossary()export_glossary()
Split extra-wide tables into smaller tables and export
export_split_tbls( tables_dir = NULL, plot_name = NULL, essential_columns = NULL )export_split_tbls( tables_dir = NULL, plot_name = NULL, essential_columns = NULL )
tables_dir |
The location of the "tables" folder, which contains tables files. |
plot_name |
Name of the .rda file containing the table |
essential_columns |
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. |
The number of split tables
## 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)## 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
format_quarto(format = "pdf", type = "sar")format_quarto(format = "pdf", type = "sar")
format |
Report rendering format. Note: "docx" is currently unsupported and will default to "pdf". Default: "pdf" Options: "pdf", "html" |
type |
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) |
This function returns part of a quarto YAML header involved in formatting the document during rendering.
## Not run: format_quarto(format = "pdf") ## End(Not run)## Not run: format_quarto(format = "pdf") ## End(Not run)
gt_group)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.
gt_split(data, row_every_n = NULL, row_slice_i = NULL, col_slice_at = NULL)gt_split(data, row_every_n = NULL, row_slice_i = NULL, col_slice_at = NULL)
data |
The gt table data object
This is the gt table object that is commonly created through use of the
|
row_every_n |
Split at every n rows
A directive to split at every n number of rows. This argument expects a single numerical value. |
row_slice_i |
Row-slicing indices
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
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 |
An object of class gt_group.
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")
14-2
v0.9.0 (Mar 31, 2023)
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
ID_tbl_length_class(tables_dir, plot_name)ID_tbl_length_class(tables_dir, plot_name)
tables_dir |
The location of the "tables" folder, which contains tables files. |
plot_name |
Name of the .rda file containing the table |
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.
## Not run: ID_tbl_length_class( plot_name = "indices.abundance_table.rda", tables_dir = here::here() ) ## End(Not run)## Not run: ID_tbl_length_class( plot_name = "indices.abundance_table.rda", tables_dir = here::here() ) ## End(Not run)
Identify table width class
ID_tbl_width_class(tables_dir, plot_name, portrait_pg_width)ID_tbl_width_class(tables_dir, plot_name, portrait_pg_width)
tables_dir |
The location of the "tables" folder, which contains tables files. |
plot_name |
Name of the .rda file containing the table |
portrait_pg_width |
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. |
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.
## Not run: ID_tbl_width_class( plot_name = "indices.abundance_table.rda", tables_dir = here::here(), portrait_pg_width = 5 ) ## End(Not run)## Not run: ID_tbl_width_class( plot_name = "indices.abundance_table.rda", tables_dir = here::here(), portrait_pg_width = 5 ) ## End(Not run)
Split an extra-wide table into multiple tables
render_lg_table(report_gt, essential_columns, tables_dir, plot_name)render_lg_table(report_gt, essential_columns, tables_dir, plot_name)
report_gt |
The extra-wide gt table. |
essential_columns |
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 |
The location of the "tables" folder, which contains tables files. |
plot_name |
Name of the .rda file containing the table |
A list of the split tables.
## 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)## 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)