Improve Schnute/Richards equations

[arni-magnusson]

This pull request improves the Schnute/Richards equations and the surrounding text.

The equations had significant errors, with Eq. 6 missing outer brackets and parts of Eq. 7 that should be subscripted or superscripted. There were also some inconsistencies in parameter names, such as Lmax/Linf/y2 that have been named L2.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.html
Please review your changes in the linked artifacts.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.pdf
textidote_report
Please review your changes in the linked artifacts.

[Rick-Methot-NOAA]

Thanks Arni. I presume you checked this against the actual code as the algorithm in the SS3 code might be a non-standard variant of Schnute/Richards

[iantaylor-NOAA]

@arni-magnusson, these changes definitely look like an improvement, but I'm not able to get them to match what's in the model output.

Using the model in simple_small_richards.zip, and the R script richards_growth_notes.R.txt, I got the following results, where "equation" is the corrected equation. I thought that maybe it was just off by a scaling parameter, but rescaling to have an asymptote at the correct Linf sitll didn't quite match for the youngest ages.

#   age  output     code  equation equation_scaled
# 1   0 22.7690 22.76900  11804.07         2.28927
# 2   1 39.3016 39.30161 196332.66        38.07656
# 3   2 46.8948 46.89477 239042.70        46.35970
# 4   3 51.9159 51.91588 266192.42        51.62509
# 5   4 55.5968 55.59675 285774.07        55.42273
# 6   5 58.4357 58.43566 300742.82        58.32576

In the code, there is a separate calculation of Linf at https://github.com/nmfs-ost/ss3-source-code/blob/3f26fa7999b6398698e094b012cc5f3f4a1e1850/SS_biofxn.tpl#L353-L354
which is then used in the calculation of mean size.
https://github.com/nmfs-ost/ss3-source-code/blob/3f26fa7999b6398698e094b012cc5f3f4a1e1850/SS_biofxn.tpl#L473-L474, so if it were up to me, I would just change the documentation to provide separate equations for the two components rather than try to solve for the single closed form solution, but if you can figure out the remaining issue with the equation, so much the better.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.html
Please review your changes in the linked artifacts.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.html
Please review your changes in the linked artifacts.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.html
Please review your changes in the linked artifacts.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.pdf
textidote_report
Please review your changes in the linked artifacts.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.pdf
textidote_report
Please review your changes in the linked artifacts.

[arni-magnusson]

Thanks, Ian, for the reproducible example and for encapsulating the ADMB Richards growth calculations in an R function.

It looks like you omitted the outermost parentheses in the growth_Arni() function. See this commit. After this fix, the two R functions are now in agreement with the growth curve in the SS3 model output.

I think this pull request is ready to be merged: the corrections in the equations and text are valid and useful. Now validated with your reproducible example.

[arni-magnusson]

The example that you created provides an important insight into how the Richards growth curve works in Stock Synthesis. I think it would be good to store it in a prominent place and make it available outside this discussion thread, for Stock Synthesis users to understand the details of the Richards growth curve implementation, sensible parameter starting values, bounds, etc.

With this in mind, I have created a placeholder repo arni-magnusson/ss3-richards and converted the example to a vignette richards.pdf. I extended it substantially, adding a mathematical proof and a demonstration of a variety of different Richards growth curve shapes.

Can you think of a good place to store and make this vignette available somewhere where Stock Synthesis users can find it? I can think of at least three possible 'homes' for the vignette, but I'm not sure which home would be most appropriate and useful:

• https://github.com/nmfs-ost/ss3-doc
• https://github.com/nmfs-ost/ss3-user-examples
• https://github.com/r4ss/r4ss

To address the points raised by Rick above, I would say that there are many equivalent ways to parametrize the Richards growth function (some more limited than others), and the Schnute (1981, Eq. 15) parametrization is a good one and as standard as the others. The stepwise calculations of Richards growth in the ADMB code appears efficient and stable, and does not need to be updated. Only the user manual.

[kellijohnson-NOAA]

I am not sure if FIMS would be an appropriate place to store it but we are working on a repository that stores "design" documents, currently populated by just the design document for length structure.

[iantaylor-NOAA]

Hi @arni-magnusson, thanks for working through this, correcting my error in the code, and creating a very helpful vignette.

I think the ideal spot for the moment to store your vignette would be on the ss3 website: https://nmfs-ost.github.io/ss3-website/ which has a model features vignettes section menu at the top (as that list grows, maybe we need a vignette landing page to organize and provide more detailed descriptions of the vignettes). I'll open a separate issue for that but we likely have to wait for @e-perl-NOAA to return from leave to make that happen (if she thinks it makes sense).

It will be easy to find this and similar files there to inform future FIMS design docs, but at the moment it's pretty specific to the SS3 implementation so seems better suited to being on the SS3 side.

@arni-magnusson, bigger picture question: are you and others actually using the Schnute/Richards growth option in SS3? My sense is that for tuna stocks if there was evidence (e.g. tagging data) that the von Bertalanffy wasn't working right, then people just used the age-specific k option to fix growth at whatever shape they want. Or more recently some folks might use the growth secession model (as I once did for Big Skate).

[Rick-Methot-NOAA]

Adding my thanks to Arni for improving this documentation and example. I agree that the SS3 vignette list is the best landing site for this work.

[iantaylor-NOAA]

New issue created at nmfs-ost/ss3-website#16.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.html
Please review your changes in the linked artifacts.

[github-actions]

Here are the artifacts from your PR:
SS330_User_Manual.pdf
textidote_report
Please review your changes in the linked artifacts.

[GiancarloMCorrea]

Hi @arni-magnusson, thanks for working through this, correcting my error in the code, and creating a very helpful vignette.

I think the ideal spot for the moment to store your vignette would be on the ss3 website: https://nmfs-ost.github.io/ss3-website/ which has a model features vignettes section menu at the top (as that list grows, maybe we need a vignette landing page to organize and provide more detailed descriptions of the vignettes). I'll open a separate issue for that but we likely have to wait for @e-perl-NOAA to return from leave to make that happen (if she thinks it makes sense).

It will be easy to find this and similar files there to inform future FIMS design docs, but at the moment it's pretty specific to the SS3 implementation so seems better suited to being on the SS3 side.

@arni-magnusson, bigger picture question: are you and others actually using the Schnute/Richards growth option in SS3? My sense is that for tuna stocks if there was evidence (e.g. tagging data) that the von Bertalanffy wasn't working right, then people just used the age-specific k option to fix growth at whatever shape they want. Or more recently some folks might use the growth secession model (as I once did for Big Skate).

Hi @iantaylor-NOAA and others. Sorry for jumping in. To mention that the Richards parametrization was used this year in the Atlantic yellowfin assessment. It fitted the data relatively well, though we did not have tagging data. For the yellowfin in the Indian Ocean, we used the age-specific K option to approximate the two-stage von Bertalanffy curve, which is not available in SS3.

[e-perl-NOAA]

Yes, the ss3-website under the vignettes tab is a great place to house this. I will work on converting your rmd/pdf @arni-magnusson into a quarto website page. Thank you for your work on this!

[arni-magnusson]

@iantaylor-NOAA: SPC tuna assessments have all used von Bertalanffy growth. Outside of the assessment work, I'm currently working with a group of people who are interested in skipjack tuna growth, where we're using both otoliths and tagging data. So far, we've tried von Bertalanffy and the growth cessation model (GCM). The GCM fitted the data badly, and the von Bertalanffy fitted so-so. Richards seemed like a good thing to try out as well, so that's what I'm up to right now. By the way, this is a stand-alone regression model, not a stock assessment population model. While reading up on some background material, I noticed a couple of things that could be improved in the SS3 manual, hence the pull request.

@e-perl-NOAA: Thanks, that sounds great. I just committed a small improvement/simplification in the schnute() function in the vignette, so please use the newest version of the vignette. Let me know if there's anything I can clarify or help out with.

[Rick-Methot-NOAA]

Arni - there is a question on the SS3 Forum regarding Gompertz growth. Could you respond to it there?
https://groups.google.com/g/ss3-forum/c/dS-5KOnVjek

[e-perl-NOAA]

@arni-magnusson could you review my addition of your vignette on the ss3-website? I made some small changes including defining the parameters.