Finish fsar template

[seananderson]

• check 'final' templates against currently in package (note it may be easiest to modify the current one because all the work adding 'bookmarks' has already been done)
• add more template content to main .Rmd
• move example figure code out of .Rmd?
• work on getting table and bullet styles to carry over (likely involves using standard styles in the .docx)

Update this issue as we remember what was left to do...
@ricardd @jdunic @PaulRegular

If some of these require a lot of work, they can be pulled out into their own issue and broken down into steps.

[ricardd]

just some running notes as I get back into this, a few packages that were missing for me when rendering a FSAR were ggtext and cowplot

moving the figure code out of the .Rmd is a good idea, that way people that only want to see the template for figures can access a script that is not dependent on rendering in csasdown

[ricardd]

Comments from Julie about the 4-panel figure

[Yesterday 2:58 PM] Marentette, Julie (she, her / elle, la) (DFO/MPO)
Right now this is the guidance for the figure

[Yesterday 2:58 PM] Marentette, Julie (she, her / elle, la) (DFO/MPO)

Figure aesthetics:
The figure should be understandable in greyscale; ensure that colour is not used as the only visual means of conveying information. Use text, symbols, shapes, patterns, and / or textures to distinguish differences, and add them to the descriptions (example: say “the red dotted line” instead of “the red line”).

Figures should have as minimal text as possible and the figure caption can be used for information/descriptions as needed. Text in the figure should be easily legible when view zoom is at 100% (print view) and kept to a minimum given complexity of translating figures. Ideally any necessary text is bilingual. Font on axes should be Arial 10.

Confidence intervals should be presented graphically with shading that includes fading edges at more extreme probabilities in order to better characterize improbably but high consequence events).

Use standardized graphs templates (CSASdown) if possible.

The figure caption should be Arial font, size 10, italics, left-aligned, paragraph spacing 6 pt (0.08 in, 0.21 cm) before and 12 pt (0.17 in, 0.42 cm) after, keep lines together. The figure caption goes below the figure.

[seananderson]

This part

Confidence intervals should be presented graphically with shading that includes fading edges

has always seemed harder to interpret to me. I'd favour multiple levels of shaded quantiles if possible. Say, 50% and 95% in darker and lighter grey.

[seananderson]

I got pretty far down the rabbit hole of trying to get list bullet styles to work in the fsar docx. Summary: the default docx file created, e.g. by pandoc, does not have a list style applied to lists. This is a widely known pandoc limitation and there are open pandoc issues about it. A work around:

<div custom-style="fsar-bullet"> testing! </div>

and then define fsar-bullet in the template to match the unordered list. Note it can't be a bullet itself in markdown! The style is defined as a bullet.

Alternatively

::: {custom-style="fsar-bullet"}
Mandatory bullet(s)
:::

More elegantly, do that behind the scenes, converting * text here... to use the div style.

Then I got caught up trying to figure out how to preprocess the .Rmd as a hook in knitr/bookdown to do that...

Then I realized https://github.com/davidgohel/officedown/ carries over list styles and does a ton of other stuff that could be useful here and for res docs etc. like figure and table formatting and tables of contents.

So, maybe we should look into somehow using that with or instead of bookdown rather than trying to hack this all together ourselves? I'm not sure if they integrate. Maybe @PaulRegular has experience?

Just leaving this here so I don't lose my train of thought.

[seananderson]

In the short term, this works:

31f105d

[cgrandin]

"Then I got caught up trying to figure out how to preprocess the .Rmd as a hook in knitr/bookdown to do that..."

If you're still interested in doing it -

Take a look at how a made a copy of the XX.rmd files as tmp_XX.rmd files in csasdown and a copy of the _bookdown.yml file and used that as the bookdown yaml file argument to render the document using bookdown. That seems to work fairly well and was the only way I could find to pre-process RMD files.

The functions are already written to do most of it.

See

csasdown/R/render.R

Line 62 in f3d342d

render <- function(yaml_fn = "_bookdown.yml",

and

csasdown/R/create-tmp-yaml-rmd-files.R

Line 45 in f3d342d

create_tmp_yaml_rmd_files <- function(yaml_fn = "_bookdown.yml",

[PaulRegular]

Then I realized https://github.com/davidgohel/officedown/ carries over list styles and does a ton of other stuff that could be useful here and for res docs etc. like figure and table formatting and tables of contents.

So, maybe we should look into somehow using that with or instead of bookdown rather than trying to hack this all together ourselves? I'm not sure if they integrate. Maybe @PaulRegular has experience?

I've only contemplated making the switch from bookdown to officedown. Experience so far has been to post-process the word files produced by bookdown using officer. Indeed, the fsar branch inspired efforts to use officer to add frontmatter to a resdoc on render (see resdocx branch). e.g.:

csasdown/R/resdoc-word.R

Lines 43 to 59 in d56a7d1

	## Note: bookmarks (bkm) were manually added to the "resdoc-frontmatter.docx" file
	## Also needed to copy and paste character strings like "french_title", otherwise
	## officer may not detect that string if manually typed (b/c Word operates in chunks)
	file <- "resdoc-frontmatter.docx"
	front <- officer::read_docx(system.file("csas-docx", file, package = "csasdown")) |>
	officer::headers_replace_text_at_bkm("region", x$region) |>
	officer::headers_replace_text_at_bkm("year", as.character(x$year)) |>
	officer::headers_replace_text_at_bkm("report_number", as.character(x$report_number)) |>
	officer::footers_replace_text_at_bkm("date", paste(x$month, x$year)) |>
	officer::body_replace_all_text("^title$", x$title) |>
	officer::body_replace_all_text("^french_title$", x$french_title) |>
	officer::body_replace_all_text("^author$", x$author) |>
	officer::body_replace_all_text("^address$", x$address) |>
	officer::body_replace_all_text("^author_list$", x$author_list) |>
	officer::body_replace_all_text("^year$", as.character(x$year)) |>
	officer::body_replace_all_text("^report_number$", as.character(x$report_number)) # |>
	# officer::body_replace_all_text("^abstract$", x$abstract)

But this is admittedly clunky and it may be more elegant to utilize officedown to impose specific formatting in the Rmd file. Just need to get around to trying it out to see what the learning curve is like / determine how difficult it might be to make the switch.

[ricardd]

just a few ideas/notes as I am writing the draft FSAR for southern Gulf cod

• We need a better way to handle the first page so that the context text appears there appropriately and the notes existing about "Mandatory text" disappear. Perhaps copying the first page and adding an option to not overwrite when rendering would work (like we do with copy_sty in the ResDoc)?
• What is the best way to handle Tables? I tried making a table with markdown but it didn't produce a table in the rendered Word document. Using csasdown::csas_table works well, so I am guessing that would be the preferred way?
• We may consider having a "short report title" to use in the FSAR headers, otherwise it can get pretty crowded to put the full title there.

[PaulRegular]

• What is the best way to handle Tables? I tried making a table with markdown but it didn't produce a table in the rendered Word document. Using csasdown::csas_table works well, so I am guessing that would be the preferred way?

For word documents, I tend to use knitr::kable if the tables require minimal customizations, but I resort to the flextable package when custom formatting is needed. Must admit that I've yet to use the csasdown::csas_table function, so I don't know how flexible it is for word documents.

[seananderson]

csasdown::csas_table() is just a wrapper on kable() with some defaults so that the TeX tables work for CSAS. It's not optimized for Word. Getting tables formatted correctly for FSARs is still to be determined but as @PaulRegular said, either kable() or flextable is likely the answer.

We need a better way to handle the first page so that the context text appears there appropriately and the notes existing about "Mandatory text" disappear. Perhaps copying the first page and adding an option to not overwrite when rendering would work (like we do with copy_sty in the ResDoc)?

Can you provide screenshots for this?

[ricardd]

@seananderson this is what I mean, the part that mentions that this is a mandatory section, and the part that says to refer to the guidance document:

[ricardd]

and my other suggestion about adding a "short title" is to avoid this where the full title is repeated in the headers and takes up too much real estate:

[ricardd]

after using the four-panel template that was added to csasdown and that plotted simulated timeseries in a format similar to what was used in the RAM Legacy database, I had the following comments:

• could the uncertainty component of the timeseries be plotted using a polygon and a line instead of three lines? if so, it should be made greyscale friendly and colorblind friendly
• should units appear on the y axis labels, or in legends, or in the figure caption?
• in the csasdown example FASR, we should have the four-panel template in both base R and using ggplot2

[seananderson]

could the uncertainty component of the timeseries be plotted using a polygon and a line instead of three lines? if so, it should be made greyscale friendly and colorblind friendly

with ggplot, it should likely be geom_ribbon(), with base graphics, yeah, probably polygons

should units appear on the y axis labels, or in legends, or in the figure caption?

I would think y-axis labels would be most common

in the csasdown example FASR, we should have the four-panel template in both base R and using ggplot2

yes

Also, where is that file currently? I forget. Also see: #248

[ricardd]

@seananderson the simulated data is in R/fake-data.R and the 4-panel figure is in R/plot-timeseries.R

[PaulRegular]

Then I realized https://github.com/davidgohel/officedown/ carries over list styles and does a ton of other stuff that could be useful here and for res docs etc. like figure and table formatting and tables of contents.

So, maybe we should look into somehow using that with or instead of bookdown rather than trying to hack this all together ourselves? I'm not sure if they integrate. Maybe @PaulRegular has experience?

I've continued working on experimental modifications to the resdoc_word format (resdocx branch) and I managed to utilize officedown. It's behaviour isn't always consistent with bookdown (e.g., it didn't work well with kable() in my experimentation, but flextable() is even more flexible). To allow both options, I worked up a resdoc_word2() function which utilizes officedown. What do you think about trying this with the fsar function? It should help enable more fine-tune control over the formatting (e.g., list formatting, landscape sections, etc.).

[seananderson]

By all means, go for it!

[PaulRegular]

I've made some progress on tidying up the output, most of it was accomplished by pre-processing a tmp-*.Rmd file (see 74b1ffb). However, I've yet to work out how to force the style of bullets and numbered lists. I have created a function that uses officedown in the background, and that is a hopeful path for setting default list styles.

[PaulRegular]

I made some more progress (63d8372). The bullets and numbered lists should now follow the FSAR style by default using fsar_word2().

## SCIENCE ADVICE {-}

### Status {-}

- [Mandatory bullet(s)] 

### Trends {-}

- [Mandatory bullet(s)] 

### Environmental and Climate Change Considerations {-}

- [Mandatory bullet(s)]

Renders to:

[grinnellm]

I really appreciate all the work you have done on this new template -- it looks great! I just started setting up a FSAR for our herring stock assessment this year. I'm wondering about making a PDF instead of a Word document.. is that difficult to set up? I can try working on this if you don't mind, but I would appreciate some direction on how to start if you have time. I can start a new issue for this too if you think that's wise -- this issue may have enough in it already!

[seananderson]

By all means give it a shot, but my thinking was we'd try to make it work with Word only output.

1. We don't have to fuss with the formatting every time they change the template.
2. Translation and accessibility is easier and doesn't require most of the burden being back on scientists.
3. I figure SARs/FSARs are shorter, made once an analysis is finalized, and are more likely to be collaboratively edited by many people with track changes in Word after an initial draft is rendered.

officedown looked promising for some of the fancier formatting stuff we might struggle with otherwise.

[grinnellm]

Thanks @seananderson, those are all good reasons.. maybe I'll leave it as is for now and tackle a PDF later if it turns out Word is not working for us.

[ricardd]

this is on the fsar branch, which is up-to-date with main

rendering the FSAR Word document works in RStudio works when using the "Knit" button, but render() doesn't

when we merge the fsar branch into main, this should not happen

[seananderson]

The "Knit" button in RStudio is running csasdown::render_sar():

csasdown/inst/rmarkdown/templates/fsar/skeleton/skeleton.Rmd

Line 23 in fcfa748

csasdown::render_sar()

instead of the usual csasdown::render().

[ricardd]

just some running notes as I am working on my Science Response (FSR)

• we should give the option to have a shorter report title to appear in the header of the rendered word document

• the title page and context section keeps extraneous text that has to be manually removed from the rendered word document, how to improve this?

• how to best handle italics for latin names? using latin name in the title does not propagate to italicized text, it just add the asterisk to the title

• need to add csl to the index.Rmd template, so that references are formatted using the CSAS style (DONE, see merge request use Word templates for 2024 for ResDoc #263 )

• how to format the list of participants to match CSAS requirements (adding bold_header=TRUE in csas_table doesn't work in the rendered word document)?

• we need to remove phone number for the approval page, based on the most recent template shared by CSAS where there is no phone number appearing

• is there a way to have references in the context section that is in index.Rmd?

[PaulRegular]

FYI:

just some running notes as I am working on my Science Response (FSR)

• we should give the option to have a shorter report title to appear in the header of the rendered word document

Agree.

• the title page and context section keeps extraneous text that has to be manually removed from the rendered word document, how to improve this?
• how to best handle italics for latin names? using latin name in the title does not propagate to italicized text, it just add the asterisk to the title

These issues are solved for the fsar template in the resdocx branch via post-processing.

• need to add csl to the index.Rmd template, so that references are formatted using the CSAS style (DONE, see merge request use Word templates for 2024 for ResDoc #263 )
• how to format the list of participants to match CSAS requirements (adding bold_header=TRUE in csas_table doesn't work in the rendered word document)?

For the Northern cod process, the CSAS office manually added this table.

• we need to remove phone number for the approval page, based on the most recent template shared by CSAS where there is no phone number appearing

I think this is done under the resdocx branch.

• is there a way to have references in the context section that is in index.Rmd?

Here's how I augmented the context section under the 01_fsar.Rmd file, with a reference included, for the Northern cod FSAR:

:::{custom-style="Context-text"}
\
This is the first assessment of this stock to use the updated assessment model  and  Limit Reference  Point (LRP)  defined  at the October  2023  Framework  process [@dfo2024b]. The assessment model was extended back to 1954 (previously starting at 1983) through the inclusion of additional data, and the longer term perspective provided by this model informed a revision of the LRP. While estimates of stock size since 1983 were largely the same, the previous LRP was roughly 40% higher than the current LRP. Following this revision, the stock was determined to be out of the Critical Zone in 2016.
:::