Add alt text to figures; glossary; formatting; R function for local compile #232
Conversation
e-perl-NOAA
requested review from
kellijohnson-NOAA,
iantaylor-NOAA and
chantelwetzel-noaa
There was a problem hiding this comment.
Change look good to me.
The alt-text looks good.
I confirmed that pdflatex_local_manual() builds the manual successfully on my computer while tinytex::pdflatex("SS330_User_Manual.tex") fails.
I like the List of Acronyms that appears near the end of the PDF, but I'm not seeing it in the HTML version. Is it possible to have it in the HTML as well?
13output.tex
Outdated
| \subsubsection[Virgin Spawning Biomass vs Unfished Spawning Biomass]{\protect\hyperlink{}{Virgin Spawning Biomass vs Unfished Spawning Biomass}} | ||
| Unfished is the condition for which reference points (benchmark) are calculated. Virgin Spawning Biomass (B0) is the initial condition on which the start of the time-series depends. If biology or spawner-recruitment parameters are time-varying, then the benchmark year input in the forecast file tells the model which years to average in order to calculate ``unfished''. In this case, virgin recruitment and/or the virgin spawning biomass will differ from their unfished counterparts. Virgin recruitment and spawning biomass are reported in the mgmt\_quant portion of the sd\_report and are now labeled as ``unfished'' for clarity. Note that if ln(R0) is time-varying, then this will cause unfished to differ from virgin. However, if regime shift parameter is time-varying, then unfished will remain the same as virgin because the regime shift is treated as a temporary offset from virgin. Virgin spawning biomass is denoted as SPB\_virgin and spawning biomass unfished is denoted as SPB\_unf in the report file. | ||
| \subsubsection[Virgin Spawning Biomass vs. Unfished Spawning Biomass]{\protect\hyperlink{VirginUnfished}{Virgin Spawning Biomass vs. Unfished Spawning Biomass}} | ||
| Unfished is the condition for which reference points (benchmark) are calculated. Virgin Spawning Biomass (B0, Bzero) is the initial condition on which the start of the time series depends. If biology or spawner-recruitment parameters are time-varying, then the benchmark year input in the forecast file tells the model which years to average in order to calculate ``unfished''. In this case, virgin recruitment and/or the virgin spawning biomass will differ from their unfished counterparts. Virgin recruitment and spawning biomass are reported in the mgmt\_quant portion of the sd\_report and are now labeled as ``unfished'' for clarity. Note that if ln(R0) is time-varying, then this will cause unfished to differ from virgin. However, if regime shift parameter is time-varying, then unfished will remain the same as virgin because the regime shift is treated as a temporary offset from virgin. Virgin spawning biomass is denoted as SPB\_virgin and spawning biomass unfished is denoted as SPB\_unf in the report file. |
There was a problem hiding this comment.
Why use "B0, Bzero"? I would think that it should be "$B_{0}$". Comment pertains to many other places as well.
There was a problem hiding this comment.
I'm confused about B0 because it seems like it refers to Virgin Spawning Biomass and Unfished Spawning Biomass in the user manual, is that correct or are they different? I also see these referred to as SSB_unf and SSB_virgin in 7forecast.tex (lines 379, 388, and 390) which I assume is how it is in the SS3 output. @chantelwetzel-noaa looping you in here since you had a comment on line 485 of this file about Virgin Spawning Biomass.
There was a problem hiding this comment.
I would like to standardize all of this but also want to make sure it's reflective of what is shown in the ss3 output.
| @@ -206,22 +206,22 @@ | |||
| \hline | |||
| \endlastfoot | |||
|
|
|||
| SSB\_Unfished \Tstrut & Unfished reproductive potential (SSB is commonly female mature spawning biomass). \\ | |||
| SSB\_Unfished \Tstrut & Unfished reproductive potential (gls{ssb} is commonly female mature spawning biomass). \\ | |||
There was a problem hiding this comment.
Should be SB not SSB. There is an inconsistency throughout the document of "spawning biomass" versus "spawning stock biomass" where I prefer the former but I guess I am just noting the inconsistency.
There was a problem hiding this comment.
I'm happy to switch to SB but I think in SS3 it's SSB throught. It might be confusing (or at least it could see it being confusing to people like me) to have SB in the manual and SSB in the output. Thoughts? @chantelwetzel-noaa
There was a problem hiding this comment.
I think keeping SSB in the manual to match the numerous occurrences in Report.sso makes sense to me. I'm happy to use SB in assessment reports and future assessment models, but it doesn't seem worth the effort to switch here.
13output.tex
Outdated
| \item Dynamic Bzero Report | ||
| \item \gls{spr}/\gls{ypr} Profile | ||
| \item Global \gls{msy} Report | ||
| \item Dynamic Bzero (B0) Report |
There was a problem hiding this comment.
Why not
There was a problem hiding this comment.
I would also suggest replacing Bzero with Unfished Biomass and then have the abbreviation in the parathesis.
There was a problem hiding this comment.
I see in other places B0 is called Virgin Spawning Biomass. Should it all be Unfished Biomass or Virgin Spawning Biomass (lines 78 and 80 of 13output.tex, also lines 217 in 6starter.tex)?
There was a problem hiding this comment.
Since the input and output text files can't have subscripts but the user manual can, I like the idea of replacing "Dynamic Bzero" with "Dynamic B0" in the manual.
In SS3, I think "Virgin Spawning Biomass" and B0 are interchangeable, but I think "Unfished Biomass" refers to the spawning biomass after application of any equilibrium F and may therefore differ from B0.
There was a problem hiding this comment.
I like use of subscript.
in ADMB, log() is used to implement ln(), e.g. use of base e. So I commonly write log() when I mean ln(). Not sure what to recommend for the manual; perhaps a glossary entry.
Virgin spawning biomass starts the time series and commonly serves as basis for depletion calculations. It uses start year biology in its calculation.
Unfished spawning biomass is used in the benchmark calculations (e.g. MSY and SPR). It uses biology from the years selected as the Bmark_yrs. So, it can differ from the virgin spawning biomass if there is time-varying biology.
There was a problem hiding this comment.
I've been in the habit of always using log() to mean ln(), but reading more about the two options, it's clear that the interpretation of log() depends on the discipline, context, or country (see https://en.wikipedia.org/wiki/Natural_logarithm#Notational_conventions for instance).
Since SS3 is used by folks with different backgrounds I'm now convinced that using ln() throughout the documentation (and my own future writing) makes sense for clarity. I would still use the spelling "log" in terms like log-likelihood, and I'm not worried about how it's represented in the code, or the output files, but in user manual equations I like the idea of switching from log() to ln().
There was a problem hiding this comment.
Okay, converting the log -> ln to a new issue and will do in a separate PR since there are already a ton of changes in this one.
…ing biomass; unit abbreviations; add mg to glossary
e-perl-NOAA
force-pushed
the
add-accessibility
branch
from
2d6d5ec
to
fc91003
Compare
There was a problem hiding this comment.
@e-perl-NOAA a lot of good forward progress has been made in this PR and rather than wait for my continued review it is probably best to just merge it in and continue to slowly make the manual better and better with each PR.
Attempted further accessibility changes by adding tags to latex but, it didn't work out well with the existing automatic tagging done by pdf tagging in pdfmanagement-testphase package which includes the tagpdf package. Please let me know if you have any more suggestions for accessibility but please put those in issue #46 as those would be addressed in a different pull request.