Develop shared functions for making tables

[iantaylor-NOAA]

Problem

U.S. West Coast groundfish assessment reports all use the same Terms of Reference which require the same tables. However, there have not been any shared functions developed to create most of the tables. Meeting Section 508 accessibility requirements will be easier with some changes to our tables and these changes will be easier if we share the effort.

Proposal

Write some new generalized functions for making standard tables. There are a bunch of functions that @kellijohnson-NOAA wrote for the 2021 lingcod assessments in https://github.com/pfmc-assessments/lingcod/tree/main/R that could be a starting place (just look for files with the name R/table_*). The other 2021 assessment repositories also have table-making code. Another useful reference is this spreadsheet of tables created by @chantelwetzel-noaa https://docs.google.com/spreadsheets/d/1NSFVKXfOLz0xQ_q7HsvxUmWY0778Os8O1kOwqf4kCAw/, which was the origin of Appendix I in our Terms of Reference.

I don't know if these functions would be better added to {sa4ss} or a separate repository, and we don't need to have functions for 100% of the tables, but I think some shared functions would save a lot of time and angst and result in better and more consistent assessments.

I'm assigning myself and @chantelwetzel-noaa who just volunteered to look at the exec summary table functions (which is an example of shared functions that we are already using). @kellijohnson-NOAA, please comment on where you think stuff like this should go and if you have time or interest in helping with the code, that's welcome too.

Note that there's an r4ss issue related to this need as well, r4ss/r4ss#8, but it's been in place since 2014 without much progress, and the Rmarkdown/LaTeX-needs of U.S. west coast groundfish assessments make me think that something the pfmc-assessments organization is the better place to house these functions.

List of functions that could be added [edited at various times to add more detail and additional functions]

• table of estimated and fixed parameters (also discussed below)
  • table_pars() in petrale repo: https://github.com/pfmc-assessments/petrale/blob/main/R/table_pars.R
• timeseries table (in lingcod linked above and adapted to petrale in https://github.com/pfmc-assessments/petrale/blob/main/R/table_ts.R)
• table of sensitivity results (copied from lingcod to petrale and modified slightly: https://github.com/pfmc-assessments/petrale/blob/main/R/table_sens.R and also multiple helper functions in https://github.com/pfmc-assessments/petrale/blob/main/R/sensitivity_output.R)
• decision tables
  • merge stuff from sablefish 2023 and petrale 2023
  • https://github.com/pfmc-assessments/petrale/blob/main/R/table_decision.R
• model specifications
  • lingcod option: https://github.com/pfmc-assessments/lingcod/blob/main/R/table_outputconfig.R (I think the selectivity component should be simplified to be more robust to differences in model setup, didn't work for petrale)
  • table_parcounts() function developed for petrale could be added to r4ss instead of sa4ss: https://github.com/pfmc-assessments/petrale/blob/main/R/table_parcounts.R
• data weights, the petrale function https://github.com/pfmc-assessments/petrale/blob/main/R/table_compweight.R is expanded from what was used in lingcod

[chantelwetzel-noaa]

Thank you for starting this discussion @iantaylor-NOAA. Currently, sa4ss has some function that help users create tex tables via the es_table_tex() function which can work on a csv file where there is a column for file location to create the tex table and table caption text by calling the formatting table_format() function. This approach allows users to only make a master csv file for all the various csv file located across a users computer rather than having to move each file into a document table folder. I suspect the function @kellijohnson-NOAA created for lingcod has some nicer bells and whistles for table formatting but I suspect we could merge the two existing files into a single one for users.

[kellijohnson-NOAA]

I think it would be great to store these in {sa4ss}. Then we could load the simple model from {r4ss} as a default for testing and for examples with the template.

[iantaylor-NOAA]

I started working on this in https://github.com/pfmc-assessments/sa4ss/tree/table_functions_78 . So far it's just the table of parameters, modified slightly from the lingcod version to fill in the blank cells based on guidance in #87.

Based on input from @kellijohnson-NOAA about long tables split across pages causing problems for accessibility, I added the a wrapper function table_pars_split() which splits the table created by table_pars() into one table per page, where the following commands in 52tables.Rmd produced 16 tables as shown in the snippets below.

```{r tables-model, results = "asis"}
cat("\\begin{landscape}")
table_pars_split(mod_base)
cat("\\end{landscape}")
```

It's on the user to figure out how many tables get produced and add text like Parameters values are shown in Tables \ref{tab:table-pars-base-1}-\ref{tab:table-pars-base-16}.

Here's the top of the first table (useful to create this early in the process to see that there are some unnecessary priors on fixed parameters):

Here's the last table:

@kellijohnson-NOAA, I don't know how quickly I'll be able to add more functions. Do you want this branch to stay separate until we have lots of table functions in it or should I create pull requests along the way as useful pieces get added?

[kellijohnson-NOAA]

@iantaylor-NOAA this is great stuff, 🙏 thank you for working on this. I would like to merge it in next week when I am back from leave rather than waiting for more tables. Really quick, I see two things that we might want to change.

• The left parentheses in the Bounds column has a space between the parentheses and the first number or negative symbol.
• Can we use tolower() on the Status column to change "OK" to "ok", though I did confirm that they are both read by the screen reader the same and the same as "okay".

[iantaylor-NOAA]

Thanks for the input @kellijohnson-NOAA (though better to truly be on leave next time).

I don't know why sprintf("(%8.3f, %8.3f)", Min, Max) was adding a space, but I fixed it via %>% stringr::str_replace("\\(\\s+", "(") and then changed my mind and applied signif() instead (via a new signif_string() function added to utils.R).

The resulting tables looks like this, which seems very readable to my eyes at least:

[iantaylor-NOAA]

As I've been adding tables for the petrale report, I've been adding to a checklist at the top of this issue of which table-making functions might be useful to re-use either from lingcod or those I've modified for petrale.

For example, I just modified the table_compweight() function written by @kellijohnson-NOAA for lingcod to add some additional columns and show CAAL as distinct from Age comps. I think the information on the mean and total sample sizes is helpful to understand the influence of these data on the model.

The function is in
https://github.com/pfmc-assessments/petrale/blob/main/R/table_compweight.R
and gets called in 52tables.Rmd with a command as below to create the following table:

table_compweight(mod_base, 
  caption_extra = paste("The WCGBTS age comps are conditioned on length,",
   "so there are more observations with fewer samples per observation.")
)

[brianlangseth-NOAA]

Ive updated @iantaylor-NOAA function here and here to allow output as a data.frame for instances where table manipulation is helpful and we dont have to edit tex tables!

[iantaylor-NOAA]

I simplified the lingcod decision table function and added it to the petrale repo in pfmc-assessments/petrale@d9b3dc1 along with the script to call it and the entry in the exec summary. The result is pasted below. I'm sure the code could be improved in many ways, but this should work for any set of 9 models populating a 3x3 decision table. It should work with just 1 or 2 catch streams as well, but is would break if you don't have 3 states of nature.