Text in time varying pars section

[k-doering-NOAA]

Hi all,

I am along this text in the manual, in the section about time varing pars: https://github.com/nmfs-stock-synthesis/ss-documentation/blob/edit_tv/15special.tex#L34

Another type of link in SS is between a model state variable, such as available biomass, and the expected value for a survey. Typically, this is a simple proportional link taking one parameter, q, but the q power feature is essentially a 2 parameter link function. So, a parameter link function can change q over time, and a survey link function then uses the annual value of q to link the annual value of a state variable to the expected value for a survey. As SS v.3.30 builds capability to allow an environment index to be a “survey” of a parameter deviation, we need a larger family of link functions such as logistic and even dome-shaped.

I'm not sure what it is talking about, so I can't tell if it is relavant to the specification of time varying parameters. Should it be deleted, kept and edited for clarity, or moved to a more relavent section? Anyone know?

[Rick-Methot-NOAA]

I can help on this. Later today.

[Rick-Methot-NOAA]

OK. That paragraph does need work. Before I think about alternative text, I want to consider where to put it.
There is a major section on time-varying within the MG parm section. It is labelled "Time_Varying Parameter Specification and Setup".
Then the "Advanced SS Configurations Settings" starts with "Using Time-Varying Parameters" with a comparable level of detail regarding setting of time-vary parameters.
Also, the MG, spawn-recruit, Q and selectivity sections each have varying amounts to say about considerations for using time-varying parameters.
Can you give some thought to consolidating these into a single section on time-varying parameters?

[k-doering-NOAA]

Sure, What about moving the bulk of the material to the "Advanced SS Configurations Settings, Using Time-Varying Parameters" section, and then linking to it from the other sections?

[k-doering-NOAA]

Also, is that paragraph describing setting up one of the environmental variable negative value options and linking it to q? If so, I think I can edit it and it perhaps can go as an example around here: https://github.com/nmfs-stock-synthesis/ss-documentation/blob/edit_tv/tv_parameter_description.tex#L35

[Rick-Methot-NOAA]

I think we should add 1-2 sentences at end of "Overview of Control File" and before "Parameter Line Elements" or perhaps within the Parameter Line Elements. That sentence(s) should identify the existence of the varied time-varying parameter options and link to the section describing these options. I think that section might best be located at the end of the "Control File" section, so before Optional Inputs, rather than in the Advanced Options later. Meanwhile, I will work on an edited version of the paragraph that launched this topic.

…

On Thu, Mar 18, 2021 at 3:23 PM Kathryn Doering ***@***.***> wrote: Sure, What about moving the bulk of the material to the "Advanced SS Configurations Settings, Using Time-Varying Parameters" section, and then linking to it from the other sections? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <https://github.com/orgs/nmfs-stock-synthesis/teams/developers/discussions/6/comments/3>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABPV4IFFJIAGTRYNWLSCY7DTEJ4NNANCNFSM4ZNGAVUA> .

[k-doering-NOAA]

ok, I won't make any changes til tomorrow at the earliest (finishing up for the day soon) - @chantelwetzel-noaa , I know you have spent more time thinking about where things should go in the manual, so please let us know if you have a preference for where most of the info for time varying pars - in the advanced options or at the end of the control file section.

Rick, thank you for the rewrite - Feel to push changes to the edit_tv branch, or just drop the new paragraph in this thread for me to add to the manual. I think users will benefit greatly from an updated tv parameters section :)

[Rick-Methot-NOAA]

My recommendation is to delete entirely the section entitled "Link Functions", except its second short paragraph beginning with "The link specifications in SS v.3.30 has been updated...". That second paragraph should be moved up in the document to the section entitled "Time-Varying Parameter Change from Earlier SS Versions". If we proceed with this merger of the TVP sections, I can give the whole thing a review and edit after merger accomplished.

…

On Thu, Mar 18, 2021 at 3:58 PM Kathryn Doering ***@***.***> wrote: ok, I won't make any changes til tomorrow at the earliest (finishing up for the day soon) - @chantelwetzel-noaa <https://github.com/chantelwetzel-noaa> , I know you have spent more time thinking about where things should go in the manual, so please let us know if you have a preference for where most of the info for time varying pars - in the advanced options or at the end of the control file section. Rick, thank you for the rewrite - Feel to push changes to the edit_tv branch, or just drop the new paragraph in this thread for me to add to the manual. I think users will benefit greatly from an updated tv parameters section :) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <https://github.com/orgs/nmfs-stock-synthesis/teams/developers/discussions/6/comments/6>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABPV4IBLVWH75XEQ2XQMN4TTEKASNANCNFSM4ZNGAVUA> .

[iantaylor-NOAA]

I support the merge. I always have to hunt around to find the information I'm looking for with regard to time-varying parameters.

I'm taking tomorrow off but am happy to help next week.

[k-doering-NOAA]

Thanks @iantaylor-NOAA , I will probably ping you next week for a read through.

I copy/pasted the text into all 1 section for now in the edit_tv branch . Will continue next week synthesizing, as I think there is likely some info that is duplicative.

[k-doering-NOAA]

Ok, @iantaylor-NOAA and @Rick-Methot-NOAA , I have a first revised draft in the edit_tv branch. You can find the text here: https://github.com/nmfs-stock-synthesis/ss-documentation/blob/edit_tv/15special.tex#L3-L73 and this additional file (which is called from 15special.text): https://github.com/nmfs-stock-synthesis/ss-documentation/blob/edit_tv/tv_parameter_description.tex

Basically, all the text is now in the "Advanced SS Configurations Settings, Using Time-Varying Parameters", while each place where time varying parameters might be used within the control file links to this section.

Would one of you be willing to read and add changes in the branch? It is probably best to do this one at a time to avoid merge conflicts of multiple people editing simultaneously.

In particular, I think one thing that we may want to add is a table or list clarifying what the parameters in the short parameter lines are, as this isn't explicitly spelled out anywhere, and whether these parameters should be estimated or not (or if users decide). I'm not really sure exactly what they are myself, to be honest!

[Rick-Methot-NOAA]

I don't think I could compile the tex without hurting myself, so please send me a WSIWYG and I'll send you comments. Perhaps you could create it as an artifact?

[k-doering-NOAA]

lol, same here, Rick (I was not successful last week when I tried with tinytex - Maybe I need MikTex?). I think @chantelwetzel-noaa is the only one of us who compiles (well, maybe Kelli).

Chantel, any chance you could try to compile the edit_tv branch when you get the chance and send the compiled version to Rick? I may have made syntax mistakes, but hopefully it is not a huge pain...

[chantelwetzel-noaa]

@k-doering-NOAA I was able to get the document to build. I encounter two error that needed to be addressed:

1. Added "" prior to "_" in selectivity table in the control file.
2. Comment out the Bounded replacement equation in the Environmental Link section. This still needs to be fixe but did not have time to deal with this evening.

I have pushed my changes and a compiled document to the repo.

[k-doering-NOAA]

thanks so much, @chantelwetzel-noaa ! I thought I may have messed up some of those equations. I'll look over it and try to fix.

@Rick-Methot-NOAA , find the manual here: https://github.com/nmfs-stock-synthesis/ss-documentation/blob/edit_tv/SS330_User_Manual.pdf

[iantaylor-NOAA]

I probably can't get to this for a couple days.
@Rick-Methot-NOAA, if you can take the first look at the "Using Time-Varying Parameters" text on pages 172-180 and make any comments, then I can go next either before or after @k-doering-NOAA makes further edits based on your feedback.

[Rick-Methot-NOAA]

I am editing it now by putting comments and edits on the pdf version

[k-doering-NOAA]

that sounds great, thanks Rick! Maybe Ian can then make comments on your pdf in a few days when he has time and then I can incorporate your comments into the .tex. Thanks all for helping me with this.

[Rick-Methot-NOAA]

I will send pdf with my edits via email