v1.4.0

[Schiano-NOAA]

TLDR

• New templates
• Notation for author argument in create_template() changed
• Improvements to the converter
• Reduction in number of arguments in all functions
• Updated preamble
• Disclaimer added to outline (replaced "DRAFT" watermark)
• Improved messages and warnings to the console
• Tables and figures are now separated in their own respective folders

Summary

The asar team gathered feedback following the Workflows Workthrough activity done by NOAA's Stock Assessment Workflows Steering Committee. The team prioritized feedback from the activity which developed a full cleanup of the package with some minor tweaks to the workflow. The majority of these changes occurred on the backend of development, but minor impacts to the workflow resulted in a more modular workflow and need for explicit steps taken. We hope this workflow is easier to follow and more user friendly than the completely all-in-one approach we have taken in the past.

Updates

Major Changes (user impacts)

• Major reduction in the number of arguments in all functions used in the asar workflow
• Default arguments have now changed and are no longer hidden in some cases
• Folders for rda objects made by {stockplotr} are now called "tables" and "figures" (previously "rda_files")
• Improved messaging in the console
• If rdas made from {stockplotr} do exist, they are no longer loaded in automatically by create_template(). The user is required to run create_tables_doc() and create_figures_doc() to perform this action
• Improved documentation through expanded definitions of arguments and prioritized argument order
• Any rda can be added to the tables or figures qmd when running create_tables_doc() or create_figures_doc()
• Any .jpg or .png located in the figures folder will be formatted into the create_figures_doc()

`create_template()

• Three new templates to choose from! -- We understand that the standard guidelines found in asar are not yet widely accepted by regional SSCs and councils. In response, we have incorporated alternative templates the meet the stock assessment guidelines from the Pacific Fisheries Management Council (pfmc), Northeast Fisheries Science Center Management Track (nemt), and Stock Assessment and Fishery Evaluation documents (safe). Each of these templates can be called using the 'type' argument in create_template()

asar::create_template(type = "pfmc")
asar::create_template(type = "nemt")
asar::create_template(type = "safe")

Note: these templates will be deprecated in the future once asar guidelines are reviewed and formally approved for use in management.

• Authors are now called through c("name" = "affiliation") in a vector. We removed the use of a database of assessment authors across NOAA since there were many missing entries and the work to maintain this database is above the small team's capacity. If the office is not currently recognized or found in our database, we recommend users to leave an issue to submit a request to add an office.

asar::create_template(author = c("Jane Smith" = "AFSC"))

• Removed "DRAFT" watermark over documents
• Added in a disclaimer to the beginning of the document (alternative to watermark)
• Removed the option to convert output and produce .rda files all within create_template
• Fixed bug when re-rendering template. Previously, title or species cover image is was not updated when defined
• Quantities in the preamble are updated to include improvements suggested by the NWFSC and to reflect changes to convert_output() resulting data frame.
• model_results is still a path to the standard file; however, users must have saved it as either an rda object. Due to the limitations of Quarto, the file must be loaded into the document at some point in order to make the quantities available to the user to make a reproducible document.
• Minor changes updating our standard guidelines found in the default report

convert_output()

• Major improvements that fixed issues with some quantities and estimates in the data frame for both Stock Synthesis and BAM
• The option to save the resulting data frame as a csv was deprecated
• Fleet names are automatically extracted from converted stock synthesis Report.sso file (users still have the option to specify fleet names if they wish using fleet_names)
• The number of "keywords" from stock synthesis found in the converted data frame has increased
• Users now input a single file path as the model_results argument instead of having 2 separate arguments to input file name and file path
• The option to save a file has changed from a .csv to an .rda. Quarto requires the user to load in a saved file in order to process quantities referenced throughout the report. Rda is easily read in by R.

Minor Changes (dev info)

• Update messaging system to show user errors, messages, warnings, and stops
• add_chunk() has options to add both quarto and rmarkdown chunk options. The defaults for this function have remained the same, however, the method in which it is implemented has changed
• Automated the processing of keywords found in stock synthesis Report.sso in convert_output()
• Removed old, unused functions
• Removed 'the' from NWFC title
• The previous message when installing or loading the package has been removed

Full Changelog: v1.3.0...v1.4.0

---

This discussion was created from the release v1.4.0.

[BenWilliams-NOAA]

Looks like some excellent updates!
Quick question - does the SAFE variant have compatibility to be generated as a word document?

[Schiano-NOAA]

Thanks so much, Ben! Currently, asar does not have any functionality for generating a word doc. I haven't looked into it recently, but when I was trying to get docx as a format into the tool, it was almost impossible to get a functioning template to generate a report that was formatted the same way as pdf.

I think we can add this for development for a future release, but if you have a template already, that would greatly improve the speed at which this feature gets added in.

[BenWilliams-NOAA]

The safe package compiles to docx - but there are a lot of hoops to jump through for that! It is also using bookdown and I haven't kept up to date enough to know how quarto overlaps (or doesn't). I think it would probably be more work than it is worth to get this to compile to word...

[Schiano-NOAA]

Potentially! I do know other people are required to submit as word doc as well, but I am hoping we can force a shift to using pdf for all. I did do a brief search and quarto has made some updates on their documentation on how to make these docs template, so I might be able to add something in the future.

I think having word doc as a format could be advantageous to the general use of asar for having template for reports broader than just stock assessments (but that's sort of getting away from the intention of the package)

[okenk]

FWIW, I have made something that is sort of the quarto version of bookdown. The repo is here, the _quarto.yml file contains all of the structural stuff (order of child files, etc.).