From 5d73de764c5ee67ffb36df1e0d0322321e6110cd Mon Sep 17 00:00:00 2001 From: Paul Regular Date: Tue, 17 Dec 2019 16:36:52 -0330 Subject: [PATCH] Complete draft of replies to Reviewer #1 --- R/sim_dist.R | 4 +- analysis/paper/rebuttal_letter.Rmd | 71 +++++++++++++--------------- analysis/paper/rebuttal_letter.docx | Bin 19118 -> 21080 bytes analysis/paper/sim_survey_paper.Rmd | 51 ++++++++++++-------- man/sim_ays_covar.Rd | 4 +- 5 files changed, 67 insertions(+), 63 deletions(-) diff --git a/R/sim_dist.R b/R/sim_dist.R index 31c7709..dd5018b 100644 --- a/R/sim_dist.R +++ b/R/sim_dist.R @@ -37,8 +37,8 @@ #' length as ages #' @param phi_year Defines autocorrelation through years. Can be one value or a vector of the same #' length as years -#' @param group_ages Make space-age-year variance equal across these ages -#' @param group_years Make space-age-year variance equal across these years +#' @param group_ages Make space-age-year noise equal across these ages +#' @param group_years Make space-age-year noise equal across these years #' @param model String indicating either "exponential" or "matern" as the correlation function #' #' @export diff --git a/analysis/paper/rebuttal_letter.Rmd b/analysis/paper/rebuttal_letter.Rmd index 9dfde08..844025b 100644 --- a/analysis/paper/rebuttal_letter.Rmd +++ b/analysis/paper/rebuttal_letter.Rmd @@ -30,14 +30,9 @@ A1C 5X1, Canada E-mail: Paul.Regular@dfo-mpo.gc.ca Phone: (709) 772-2067 - - - - - - - - + + +---------------------------------------------------------------------------------------------------- @@ -49,16 +44,11 @@ I found the paper very interesting and the package of great potential value and 1. Verify some of the equations and model description used in the model. I think that some of them lack description to fully understand what was done and few others are misleading, even incorrect. The detail can be found below but in general, they are linked to the problem of bias correction for log-normal distribution, re-scaling”, moving from abundance at age to abundance at length. -*Please see our specific responses to lines X, X, and X.* - 2. Add additional explanation to justify the choices. E.g. why population dynamics is modeled independently of the spatial distribution. Is this reasonable, limitation, etc. -*TODO* - 3. Few suggestions (add-ons, renaming) to increase the generality of the paper (without requiring too much work) -Please see our specific responses to... -*TODO* +*We hope we have addressed each of these main comments by 1) clarifying several equations, 2) adding more details and justifications, and 3) modifying naming conventions and clarifying extensibility. See replies below for more details.* Detailed comments: @@ -109,39 +99,39 @@ I have a few comments on this section: 3. L161. I think it would be good to say upfront that there are two ways of defining the spatial structure. Using the function in the package or user defined. -*TODO* +*Given a suggestion from Reviewer #2, we have restructured the paper to have two core sections: "Model structure" and "Using SimSurvey". We have included a blanket statement under the "Model structure" section noting that users can circumvent specific components of the framework.* 4. L161: I think another possibility is to generate a random field by using the package “Randomfields” for example. This way you can generate a map where “depth” is patchily distributed (maybe more like an island type case study) -*TODO* +*Good idea! We actually pursued this idea in an earlier iteration of `make_grid`, however, we abandoned the option because it was difficult to automate; the random field created random problems with the depth-stratification (e.g. one cell strata).* 5. L163-164: please add more description about the division or strata. How can we set it up and what do you specifically mean by division and strata? Is one nested within the other, or not necessarily? Your examples are based on Atlantic Ocean and people in other regions might not be familiar with how these divisions are created. -*TODO* +*We have added more detail on the structure of the divisions and strata.* 6. L163: Why only focus on “depth-based strata”? I think it would be good to allow the user to choose their own stratification approach. It could be depth based as you did (which happens most often in surveys) but it could technically be any other thing (user supplied). This allows more flexibility. -*TODO* +*See reply to point 2. above.* 7. L167: the equation is misleading and I am not sure it is right based on what is written in the text. You mentioned later on L178: that you “re-scaled” so that the total number of fish in a specific year and age across space is equal to the single number from the population dynamics model. If so, the re-scaling should be done in the identify (natural) scale, not in log scale. In log scale, even if ,, sums to zero across space, the sum in the identity scale won’t match. This is often refer to as “bias correction” for the log normal models. And you should ideally show how the rescaling was done in terms of the equations too. -*TODO* +*Right, the equation presented was not an accurate reflection of the calculations. We have revised the equation to explicitly show how the values were normalized to sum to 1.* 8. L167: this “depth preference” function is very simplistic and gives only very “smooth” symmetric distribution. More often, fish have a skewed depth preference: often right-skewed. -*TODO* +*True. Some users may find this parameterization insufficient for their species and we hope they will implement their own closure to use in the `sim_distribution` function to better simulate the effect. In addition to our blanket statement under the "Model structure" section, we have added a more specific statement under the "Using SimSurvey" section stating that alternate formulations can be used by supplying alternate closures to the core functions.* 9. L173-174: I think it might be worth adding, in simpler terms, the meaning of the spatial smoothing and scaling parameters. -*TODO* +*We have prefaced that sentence with "The rate at which point-to-point spatial correlation decays with distance is controlled by...".* 10. L178: it is another question of scaling. How did you exactly do the scaling? In the identity scale? By dividing my the sum of the effects? I am asking this because depending on how you did the rescaling, your correlation structure in space and age might have been affected and is not the same as the one specified in L172. Did you verify that? -*TODO* +*See reply to point 7. above* Table 4. “group_ages”. Ok but how is the variance controlled for the other age classes? -*TODO* +*"Variance" was a poor word choice. We have replaced it with "noise" as it is the simulated noise that we fix across multiple age groups.* L189: “user supplied”. This is a good feature. However, I think it is important to mention here that user have to make sure that they use the correct projection method to ensure that each grid is of the same dimension. @@ -153,7 +143,7 @@ L216: reference to figure 3? L221: there is not “group_years” argument in Table 4. -*TODO* +*We have added it to the table.* L237: “this function”. I think it would be better to replace “this function” with “sim_distribution” as you do not mention the word “sim_distribution” in the sentence above this. @@ -161,31 +151,31 @@ L237: “this function”. I think it would be better to replace “this functio L158-251: In general, I think re-organising this section using sub-section headers could be useful. Just to guide the readers -*This is an excellent suggestion and we have inserted headers where appropriate.* +*This is an excellent suggestion. By following a suggestion by Reviewer #2 to re-organize the paper into two core sections we have added more headers to help guide the readers.* L254: you say that sampling is stratified random but SRS is also an option based on Table5. Please correct. -*TODO* +*We have made the suggested change.* L257: what does this mean? Does this control the number of set but how is this calculated? -*TODO* +*We have clarified how number of sets per strata is calculated.* L257: I do not see how you control for the total number of set in the survey? How do you control it? -*TODO* +*We have clarified how number of sets per strata is calculated.* L261: I think you should mention here that you can also force the sample size (as seen on table 5). Moreover, in table 5, it would be good to set-up a “ages_min” for the minimum number of ages to sample […]” so that it gives the ability to fix the sample size if needed by writing the same value for “ages_min” and “ages_cap”. -*TODO* +*We are not sure what the reviewer would like to have implemented here. Is the suggestion to impose a minimum number of ages to collect across all length groups?* L261: How are you making sure that the number of sampled fish for that specific cell, age and year won’t be above the total number of fish in that cell, age, and year? The probability value could be close to one and if you fish in a few a time, then you are at risk. Especially because your population dynamics model is not spatially explicit and is completely independent of the distribution function itself i.e. you can technically fish out all the fish in an area but it will be populated back the year after the way you implemented in this study… Maybe you need to put a condition (or just a note) for general users to make sure that this probability value is much below 1? -*TODO* +*The sampling is implemented such that the number of fish sampled in a cell cannot exceed the number of fish in a cell because the population is split across sets in cases where more than one set is conducted in a cell. We have added this missing detail to our manuscript. We also added a note that the survey is assumed to have no impact on the population from one year to the next.* L267: I recommend to clarify something here. 1. Depending on the number of fish caught? What do you mean? What is the rule you used? 2. The way you coded, sample by age is first decided, then the corresponding length is calculated, then age-subsample is determined. In reality, length sample is taken in the field, then age sub-samples are taken. While similar, I do not think it always equal. Especially, when you start including some correlation structure in the sampling. By the way, did you consider including some correlation structure in the sampling process to make more realistic? -*TODO* +*Honestly, we do not recall what we mean by "depending on the number of fish caught". Perhaps we added those words to cover off cases where no fish are caught. Whatever the case, we have removed the statement to minimize confusion. We have also clarified the sub-sampling sequence. Finally, we have yet to consider including correlation structure in the sampling process as we went about imposing correlation via the spatial correlation of age groups (i.e. age-specific clustering tends to result in sets with high intraclass correlation). We are open to learning more about other processes that may contribute to correlated samples.* L275 Table 1 on should be table 5 @@ -198,23 +188,23 @@ L275: Table5: “age_sammpling” should be “age_sampling” L275: “min_sets” you have not described it yet and what is it? You have sample from all cells? If no, this is not realistic. -*TODO* +*We have clarified the meaning and utility of the `min_sets` argument (i.e. a small strata may be allocated only one set under a low set density scenario; this argument overrides the allocation and imposes the `min_sets` if it is greater than the allocation).* L279: Table5 not Table1? -*We have changed the page numbers accordingly.* +*We have changed the numbers accordingly.* L285-286: Could you be more specific on how custom closures can be supplied and where? -*TODO* +*We have included an example that ought to clarify how a custom closure can be supplied.* L306: how are these catchability corrected abundance matrices calculated? It is important to write this information somewhere (or write “please refer to the section “Stratified analysis” for further information on the calculation of abundance indices”) or something alike and Appendix S3. -*We have adopted the Reviewers suggestion and referred the reader to the section on Stratified analysis.* +*We have clarified how this was calculated.* L336: I think it would be good to say that other methods exist and people can use it in this package (maybe)? -*TODO* +*Good point, however, we think this is covered by referencing a paper that describes a geostatistical R package and we also note that other options can be used under the "Research opportunities" section.* L421: color gradient. Even though it is obvious it might be good to say green to purple gradient. @@ -230,7 +220,12 @@ L452: say that the color ramps from yellow to purple S1 appendix: missing figure in S1 -*TODO* +*We have included the figure* + + + +---------------------------------------------------------------------------------------------------- + Reviewer #2: @@ -241,7 +236,7 @@ This manuscript describes an R package called SimSurvey. The package includes a The title announces a package for optimizing survey designs. As far as I can see the package does not allow survey design optimization, neither in terms of defining survey strata nor in terms of number of stations per stratum. The strata are defined by the user. The only option available for the number of stations is proportional to stratum surface; the user sets the minimum number of stations taken in the smallest stratum. It would be useful to be able to specify the total number of stations and test different allocation schemes, such as proportional to surface area (implemented), equal number per stratum, Neyman allocation (accounting for surface area and abundance variability), etc. Please consider revising the title (e.g. “compare” and instead of “optimize)” and spell out the available sampling design options. -*We agree with the Reviewer and retitled the ms "`SimSurvey`: an `R` package to compare the design and analysis of fisheries surveys by simulating spatially-correlated fish stocks".* +*We agree with the Reviewer and retitled the ms "`SimSurvey`: an `R` package for comparing the design and analysis of fisheries surveys by simulating spatially-correlated fish stocks".* 2. Manuscript structure diff --git a/analysis/paper/rebuttal_letter.docx b/analysis/paper/rebuttal_letter.docx index 7e55f99a52dd792185ad53afb3b264b56b000e14..5a4ea7d52ec092dce0962209b9eaed8906e76a03 100644 GIT binary patch delta 12580 zcmajF1#}(DjxKCw#+aFznK@==$1yWAwIOCZ=9rlw=9rn8nVB(WemUpPKj*)9=B?Lj zRZCl~PtuaAYVWSC$|TUG0#HOHS#Ssp5HJ`Rkiwj}8pLc+@ISP!3KRtt=?|kA$ekAe zO$7qtwVW^xh6Ct2<4L*sO;#N-tJBni`9sh|ptaSK%61G{FGm#UQ?&k4<}kw*W;$$` zW&5@jnh1y*s3xhM&%VdL(Y#aeG+yBN=g3Jn4c|vHfCXh;%oZzVkGfAhjrTTM=2gla z+hhrFA3Z1_B@XBDH!MGPcV8O#PPe;XUCjcI<1Q$N%0OmXh00aX7-A7J5~aF2!uJ?` zc9v4N_BLi5AFh#6HO(t?9>J^wQ@un_lZ>G2nZ3u`y}b*^GFvy|-hxIPN}^~RldK_# zSK|3TWR;Ff;zAi0NO*U2U2Y+r_pKbpx&VZEd0VvuMk4ifYDH-Nh}X%FofG}erqAdf zYxRIrBv2D)@s9n>Nf#+A&>qkh9KB%-@u;qz{MB=IM_?dj^O@>(zq`0gx|cs|`vd-Y z@+SWMp*D>|QXX29*VExDm_h$eFWF1)1kCN}ads0wRO(o$FBn|&Xo#Pi`tz=wrzw)4 zZyuX9+MTDOKxt$jZ$972(;n=5OCC!aY6wN!PaqBR>Sd(ur$KKzTt;r&8P%7&U{`ci zo!!IQmxDRu%wsM49oL5m#kt6~%BYCw&-GqrBl2wr+F9yC?^l~&4#Uq&fb#Jv z@pO;z$^khplhf#RTyKIIznpZ2BpLTBxfX-E+^Lr-Fk4h@ZEi3SDss+rEv??i~U@!mg$U)iA=va6F?e`fN;M`R}8dp8=R3mtxuOo z-TSHbmqYEtNGb+)eLkV=*^SlL^Ecc=GJ`GYU)b;T=n~uLkssry*9Eu%#3EKb*%W^M zx02QarN@1e=p4Uf@Z2>sm$0Y5hdv7=cn2}!rJo!-p_GSk0-%zg)(S3tE z!INhF!?{(>AXLkg?zO5>M@gB!+FzMZbWvSh?|2Kc$q1^qurC&>vAJdhYKU!xp~^Jz zl5zUO?z_SYIYCOZ#(PLgHJQZ%6c%izvNN_{6FO>es%Qb=-1>m690(H_WUL9PU}G1r z&nC29Ru?{Pt-y4&<0ev;ZJmS!3vs8cG^HUZ2nOgPUet+nx*K#UPXN#fDpWai{M=z- z0Z(L_pd|a&&!PC9xDO3ryX~1W?}Qp3b3|)xGj}*w#J$?e(7#~!9#9n6O2I#4R3PF| zb6Ff*<{R0sHyQnehA9?^JCc-K_Mm&4HLIaPc%>?DV{8d-y`<4=GaA z3{ptH;;4c%Lp({VR0HBPnYE|BW45((R_qNUJDwMeT!V=ef2S8bqpc?F94Rj8b)8dP zIKh91?1kV!z?g#T$T)BXI|*nvNs?bIvF63s8DwdLtXJVzGL#9tH{61DXt50Yu8paSXS;Hhlk|Uk-$Nol!Fw0%0>-z$wALwN4Yv+R0`ZhG_?ov z$w}}AjiX}W#RKmG6?7S=OD0YGd*~_Cu^tjBOV%}pvD&&;H$i%MfH&5lH=N?!aV`H+vMKZxf*4hEP_ld*cypog+!K% z5t239lJ{sED2zbsEtpLFSGpCaM}n+IwX;Vsa!!XFM{B*M5h`#+@gMn--x)hd*0db9 zmkLgFG};}M^*c)ztoHN3nnOiuJ@6tlHIh8_W|JBq%^nXXmW8{&Vh1#y%99Ea>hse# zT%!OAE}WdJIX)B-6gH3Clg86jGW{fqX`sGcG*hm^cY(5Zm%!V>t4U^M?nBjvRp=1`UW9(WmE4}K3|Df8vk_aWy-Uy5UU%cCoqQ8(0bX3Q!Wj67fyv5Z(y zz^arYc_b(>Z_`S%Tmw^C*nK{7Dox2e=u!bI&E{y4d?yE2ilf*GNe)knd2C|Dab1jz z9E|R+V}x&EL4YDv4w4Y&D8wydRw??vD;N>|L%8j_&kyQQ%fzkd38RbscI(@2Hz(w>d{l)zqC*?BXIzF)CH=nh zsYz)zZ6daAS1loTkdij0N32V0Q7XWbJqTnJzv!-Wiul9R%g0L`%1j2U6Q9#0%hIy^ z?dtP(#X}ECFd=B7+euX7DRw;$KnxVa>!9>uNb{=fGDJ$jwflSNG}?gMI}p8ZAEhOj z_|_$1za~4(le|Y4@SlYIykw>$u(g0vWV?6BNyTQ<0;O_z6isRGX>tIK`b-bI+2#SB z;1hHK1+Le8rus?}gRV=!tQd)Q-akRUoa~VusEsYZWSh^%WlI_klrHBS>;vwVGRTQX z(pad3PNnhC7!`qVP=WpWY>27XU4D?H{%dl3^*0bxz9}`Q;aj{Rfh}Dr!m1Lp4*?d9 zTiB=7q8RcXhdwYwotb%*hjQ~j;qftx?CHbo@zJ;t`c|zm$XJ&8WDGpI{1=J4HZnbc zeGL2ZX=;*4m|)~<_$XMnet=a$*OE;TCeN`|lh}NNJbQt2aWy)YNj>mB+R$5+e%wer z**K&Ju4K? zx~ykgg2PJ0wwzA{f^bf#Q7~u}^yiXiR)OXMAc1?9jd8`qpf{%)Fo30KAB>jQ=?IxOhEjCeVa${53^mhs=STUAWjIOQ|A29~1Z5{4C7WJ6H=bI6#54p@-%( z_IyQy9)m@AXqcGnt9Sxg737nm$u@kaqe1f1n|V_;4gZmA5m}4iPR5th6B5rt8T~S8 zxVR%RQA!y?*jhW9LYfQWS>ltsAC8;2x6V;G5b1l$Rhy@qB0w5Ccr>p4SZJFcjzdwW z!4?7~Q*-zAwF~dL>1bwE2Q2v7S?RaPeJ z0VPIZ0y4@sgcMM0n-`?~4b%}i0#@1mW&z~%*vSAn*3`C_ua(t7(qsaSXm!8`Tlb0p zK1)1-Nl08MoIqG764`CulV1|wQ*Btn$C&%Y#dq7ri2%qiXOrQz72?)ew2Vtm@_5`* zsnGe3e~v#CHn8eW07JZm8grz5V)W}qiF}oTE%D^+r+P2%!lG>WLnWa-d^$^OTY8koJR$jM~HOQp@oQ` zlA@&|HW)AsLn=0@s>iAh*~7OVRs`KIZAd_oHpsz&c5PX-2C-yJeDoCcrr3idQWh5) z;-gJc5)*{_R*oZI9JtPzmpFV+$%Y(OyvkVt;mi1lhXQDh$vO;jf4gTtbW8Oz7^@6;4>|<*F1#^mZD4)@@zyjoNJ5sp1rS8wlVRnID!LhD5_>WaX zav}tfx(Ld5F@xXG_e^n9`Hu0$9+CI3vXHH?T0yDGqTMvKj~2wj8hx*X@X?d{#@IYl zIBuP7M5@%4go@OdC}wV*AhvmXdG9T|>mVj}A<&XBt+Nt4(75swimD{d=Ima_bi>P1 zX9~C{LyZCzy)b4vp)TFVfI=E11Cer~OBT`x^%hBb`WyO@^7I%A=95X1syV~YI#jAi{xSfmUzXsENYsdcMehn@JCKohHAokuSzGbC z(_=Iq7MlGWjXm=6P|T^8xy+h79RL@Bjv2zJ@KO5I0ZGPeyg5aPa<3_wP9y>rSYfI{ zNt4Q2y>7>DObJTUOewjtmk98PYf?$pTz7U-k5NZs^Clhel#G9 zmvG?|RhpKU!g;bIBKL1}tYf4+uHXM5NNa<@dn*MB94v!!E4 zv$9QwK|DEhfo%Pe8iv-cSNIC^5DFl#+geH5*aNu8<%a#nV^NAOZkDue0?PDhJ#0ex zt@nqXYHf9JyEB5c`k}2HwWeytnu%UVsP#v?AnD)mOQLjfbGaa$4LM!3v#RcDZBY7j zc90Qv_Yq)Z&9JFJNgy5xKuk$U1nOY3FufChKL?u0BNy$RRwMgQAYeF*v2UKTCy=Kh=LN!c9*}i&A^CR z80UY)(Ke&FVJxW36_&S`<9BK#2IfaGqQi$yYji*iiE@s#?C-Y3%0ADuiO}r?QSn`3 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 JT>M|{{SO|XskHzA diff --git a/analysis/paper/sim_survey_paper.Rmd b/analysis/paper/sim_survey_paper.Rmd index cf8b50e..b52b97b 100644 --- a/analysis/paper/sim_survey_paper.Rmd +++ b/analysis/paper/sim_survey_paper.Rmd @@ -85,12 +85,12 @@ Fisheries-independent surveys have become a mainstay in the management of dynami Here we document **`SimSurvey`**, an `R` package designed to simplify and facilitate realistic simulations of fisheries-independent trawl surveys. In short, the package allows for the simulation of random or stratified-random surveys of an age-structured population that varies in space and time. The package has two main components: the first focuses on mimicking realistic fish stocks by simulating a spatially and age-correlated population distributed across a habitat gradient, and the second component focuses on simulating various surveys of these virtual fish stocks. -This simulation framework has similarities to those presented by Schnute and Haigh [-@schnute2003] and Puerta et al. [-@puerta2019], however, efforts were focused on developing a series of general and accessible functions to simplify the process of testing multiple sampling scenarios and analytical pathways. The steps taken to simulate surveys of spatial, age-structure populations are outlined below. First we outline the equations underlying the package in the [*Model structure*][Model structure] section and then move into a vignette of the package under the [_Using **`SimSurvey`**_][Using **`SimSurvey`**] section. While the core of this paper focuses on how to use this package, it is important to note that the defaults of the package are based on a case study. Output from default function calls are therefore relevant to the case study and these results are described and discussed in [*S1 Appendix*][S1 Appendix: Case study]. +This simulation framework has similarities to those presented by Schnute and Haigh [-@schnute2003] and Puerta et al. [-@puerta2019], however, efforts were focused on developing a series of general and accessible functions to simplify the process of testing multiple sampling scenarios and analytical pathways. The steps taken to simulate surveys of spatial, age-structure populations are outlined below. First we outline the equations underlying the package in the *[Model structure]* section and then move into a vignette of the package under the *[Using **`SimSurvey`**]* section. While the core of this paper focuses on how to use this package, it is important to note that the defaults of the package are based on a case study. Output from default function calls are therefore relevant to the case study and these results are described and discussed in [*S1 Appendix*][S1 Appendix: Case study]. # Model structure -In this section, we describe the framework currently implemented in the **`SimSurvey`** package. With this framework, we tried to strike a balance between realism, simplicity, generality and computational feasibility. The framework follows four general steps: 1) simulate a spatially-aggregated age-structured population; 2) distribute the population throughout a spatial grid, imposing correlation across space, time and age; 3) sample the population using random sampling; and, 4) obtain population estimates using a design-based analysis. Though there is a degree of flexibility in each of these steps, keep in mind that users can circumvent specific components by applying user defined equations, inputs and/or analyses. +In this section, we describe the framework currently implemented in the **`SimSurvey`** package. With this framework, we tried to strike a balance between realism, simplicity, generality and computational feasibility. The framework follows four general steps: 1) simulate a spatially-aggregated age-structured population; 2) distribute the population throughout a spatial grid, imposing correlation across space, time and age; 3) sample the population using random sampling; and, 4) obtain population estimates using a design-based analysis. Though there is a degree of flexibility in each of these steps, keep in mind that users can circumvent specific components by applying user defined equations, inputs and/or analyses. Details on how to use the package and circumvent some aspects of its structure are outlined in the *[Using **`SimSurvey`**]* section. ## Simulate abundance @@ -111,20 +111,22 @@ Though some typical relationships have yet to be implemented (e.g. stock-recruit ## Simulate spatial distribution -Rather than developing a full spatially-explicit model, population and spatial dynamics are modeled as independent processes for simplicity. The complexities of spatial population dynamics - such as larval dispersal, spatial differences in growth and meta-population connectivity - are therefor not accounted for and, as such, the model is a substantial simplification of reality. Despite this limitation, the approach taken facilitates the simulation of spatial, age-structured populations with sufficient complexity for testing the efficacy of various survey designs. The simplicity also limits the number of unknown parameters that need to be specified to simulate a population. Parameter estimates from spatially-aggregated age-structured models, which are commonly used in stock assessments, can therefore be used to simulate a population using the cohort model and the resultant abundance at age values can be distributed across a spatial grid. Here, a grid of $s$ cells is generated where each cell has an area of $A$ and depth $d$; depth is defined using a sigmoid curve, applied across longitude only, with a depth range of $[d_{\mathrm{min}}, d_{\mathrm{max}}]$, shelf depth of $d_{\mathrm{shelf}}$ and a shelf width of $w_{\mathrm{shelf}}$. The grid is divided into $H_{\mathrm{div}}$ divisions (e.g. NAFO or ICES divisions) and $H_{\mathrm{strat}}$ depth-based strata. The simulated population is distributed through the grid by simulating spatial-temporal noise controlled by a parabolic relationship with depth and covariance between ages, years and space via: +Rather than developing a full spatially-explicit model, population and spatial dynamics are modeled as independent processes for simplicity. The complexities of spatial population dynamics - such as larval dispersal, spatial differences in growth and meta-population connectivity - are therefor not accounted for and, as such, the model is a substantial simplification of reality. Despite this limitation, the approach taken facilitates the simulation of spatial, age-structured populations with sufficient complexity for testing the efficacy of various survey designs. The simplicity also limits the number of unknown parameters that need to be specified to simulate a population. Parameter estimates from spatially-aggregated age-structured models, which are commonly used in stock assessments, can therefore be used to simulate a population using the cohort model and the resultant abundance at age values can be distributed across a spatial grid. Here, a grid of $s$ cells is generated where each cell has an area of $A$ and depth $d$; depth is defined using a sigmoid curve, applied across longitude only, with a depth range of $[d_{\mathrm{min}}, d_{\mathrm{max}}]$, shelf depth of $d_{\mathrm{shelf}}$ and a shelf width of $w_{\mathrm{shelf}}$. The grid can be divided into two hierarchical levels. For demonstration purposes, we envision these levels as part of a stratified-random survey within international fishery divisions, i.e., $H_{\mathrm{strat}}$ depth-based strata within $H_{\mathrm{div}}$ divisions (e.g. NAFO or ICES divisions). The simulated population is distributed through the grid by simulating spatial-temporal noise controlled by a parabolic relationship with depth and covariance between ages, years and space. This noise term is normalized to sum to 1 to ensure that the total population of each age for each year through the grid equals the number simulated by the cohort model: -$$\begin{aligned}log(N_{a,y,s}) &= log(N_{a,y}) + \eta_{a,y,s} \\ \eta_{a,y,s} &= \frac{(d_s - \mu_{d}) ^ 2}{2 \sigma_d^2} + \xi_{a,y,s} \end{aligned}$$ +$$\begin{aligned}N_{a,y,s} &= N_{a,y} \frac{\eta_{a,y,s}}{\sum_{s = 1}^{N_s} \eta_{a,y}} \\ \eta_{a,y,s} &= \frac{(d_s - \mu_{d}) ^ 2}{2 \sigma_d^2} + \xi_{a,y,s} \end{aligned}$$ -Where $d_s$ is the depth in a specific cell of the grid, $\mu_d$ is the mean depth where abundance is typically highest and $\sigma_d$ controls the width or dispersion of abundance around the mean depth. Residual noise $\xi_{a,y,s}$ is added to this depth relationship using a combination of Matérn covariance, to control the level of spatial aggregation within ages and years, and a two dimension AR1 age-year covariance described in Cadigan [-@Cadigan2016], to control the level of similarity in distributions across ages and years. Spatial correlations are controlled by a smoothing ($\lambda$) and a scaling parameter ($\kappa$) [here $\kappa$ is approximated from the range parameter ($r$), $\kappa = \sqrt{8 \lambda} / r$; @Blangiardo2015] and correlation across ages and years is controlled by $\varphi_{\xi, \mathrm{age}}$ and $\varphi_{\xi, \mathrm{year}}$, respectively. The overall variance of the spatial process is controlled by $\sigma_{\xi}^2$ (see [*S2 Appendix*][S2 Appendix: Age-year-space covariance] for a more detailed description of the space-age-year covariance structure). In short, this formulation allows control of depth preferences, the level of spatial aggregation and the degree of age and year specific clustering. Note that $\eta_{a,y,s}$ values are rounded and re-scaled to ensure that discrete numbers of fish reside in each grid cell and to ensure that the total population of each age for each year through the grid equals the number simulated by the cohort model. +Where $d_s$ is the depth in a specific cell of the grid, $\mu_d$ is the mean depth where abundance is typically highest and $\sigma_d$ controls the width or dispersion of abundance around the mean depth. Residual noise $\xi_{a,y,s}$ is added to this depth relationship using a combination of Matérn covariance, to control the level of spatial aggregation within ages and years, and a two dimension AR1 age-year covariance described in Cadigan [-@Cadigan2016], to control the level of similarity in distributions across ages and years. The rate at which point-to-point spatial correlation decays with distance is controlled by a smoothing ($\lambda$) and a scaling parameter ($\kappa$) [here $\kappa$ is approximated from the range parameter ($r$), $\kappa = \sqrt{8 \lambda} / r$; @Blangiardo2015] and correlation across ages and years is controlled by $\varphi_{\xi, \mathrm{age}}$ and $\varphi_{\xi, \mathrm{year}}$, respectively. The overall variance of the spatial process is controlled by $\sigma_{\xi}^2$ (see [*S2 Appendix*][S2 Appendix: Age-year-space covariance] for a more detailed description of the space-age-year covariance structure). In short, this formulation allows control of depth preferences, the level of spatial aggregation and the degree of age and year specific clustering. ## Simulate survey -The final step in the simulation is to sample the simulated population over the age-year-space array generated. The sampling is stratified random, emulating real-world surveys conducted by many research institutions around the world. The area of each strata is calculated and this is used to define the number of sampling stations, hereafter referred to as sets, allocated to each strata under a particular set density, $D_{\mathrm{sets}}$. The allocated number of cells are randomly selected in each strata and the number of fish caught in each set is calculated by applying binomial sampling of the fish in each sampled cell by the proportion of the area covered by the trawl and the catchability of each age: +The final step in the simulation is to sample the simulated population over the age-year-space array generated. The sampling is random or stratified random, emulating real-world surveys conducted by many research institutions around the world. The area of each strata $A_{\mathrm{strat}}$ is calculated and this is used to define the number of sampling stations $H_{\mathrm{sets}}$, hereafter referred to as sets, allocated to one or more strata under a particular set density, $D_{\mathrm{sets}}$ (i.e. $H_{\mathrm{sets}} = A_{\mathrm{strat}}~D_{\mathrm{sets}}$). The allocated number of cells are randomly selected in each strata and the number of fish caught in each set is calculated by applying binomial sampling of the fish in each sampled cell by the proportion of the area covered by the trawl and the catchability of each age: $$n_{a,y,s} \sim Bin(N_{a,y,s}, \frac{A_{\mathrm{trawl}}}{A_{\mathrm{cell}}} q_a )$$ -Where $n_{a,y,s}$ is the number of fish of age $a$ in year $y$ sampled by a set at location $s$, $A_{\mathrm{trawl}}$ indicates the area covered by the trawl, $A_{\mathrm{cell}}$ is the area of a grid cell, and $q_a$ is the catchability coefficient of each age (i.e. the ability of the trawling gear to catch specific age groups). Here, catchabilities were defined using a logistic curve controlled by a steepness, $k$, and midpoint parameter, $x_0$. The lengths of the fish sampled by the set are then simulated using the von Bertalanffy growth equation found above in the *[Simulate abundance]* section. Depending on the number of fish caught, sub-sampling is then conducted. Specifically, a maximum number of lengths are measured per set, $M_{\mathrm{lengths}}$, and a maximum number of ages, $M_{\mathrm{ages}}$, are sampled per length group, $l_{\mathrm{group}}$, per division. Such sub-sampling is common in fisheries-independent surveys as it is costly, impractical and unnecessary to sample every fish captured. Age determination is especially time-consuming, which is why otoliths for age-determination tend to be sub-sampled by length-bin to obtain a representative age sample across a wider range of lengths than would be obtained via random sampling. +Where $n_{a,y,s}$ is the number of fish of age $a$ in year $y$ sampled by a set at location $s$, $A_{\mathrm{trawl}}$ indicates the area covered by the trawl, $A_{\mathrm{cell}}$ is the area of a grid cell, and $q_a$ is the catchability coefficient of each age (i.e. the ability of the trawling gear to catch specific age groups). Here, catchabilities were defined using a logistic curve controlled by a steepness, $k$, and midpoint parameter, $x_0$. In cases where there are multiple sets in one cell, the population in that cell is split across the sets. While this means that numbers caught in an isolated simulation cannot exceed the numbers in the population, keep in mind that the survey, no matter how intense, is assumed to have no impact on the population from one year to the next. + +Once catches are simulated, lengths of the fish sampled by each set are simulated using the von Bertalanffy growth equation found above in the *[Simulate abundance]* section. Sub-sampling is then conducted whereby a subset of fish are sampled for length measurements and a subset of this subset are sampled for age determination. Specifically, a maximum number of lengths are measured per set, $M_{\mathrm{lengths}}$, and a maximum number of ages, $M_{\mathrm{ages}}$, are sampled per length group, $l_{\mathrm{group}}$, per division. Such sub-sampling is common in fisheries-independent surveys as it is costly, impractical and unnecessary to sample every fish captured. Age determination is especially time-consuming, which is why otoliths for age-determination tend to be sub-sampled by length-bin to obtain a representative age sample across a wider range of lengths than would be obtained via random sampling. ## Stratified analysis @@ -142,7 +144,7 @@ Like any model, this simulation is a simplification of a much more complex reali # Using **`SimSurvey`** -The **`SimSurvey`** package was written in the programming language `R` [@R] and it holds a series of functions for 1) simulating the abundance and distribution of virtual fish populations with correlation across space, time and age (`sim_abundance`, `sim_distribution`), 2) simulating surveys with a range of sampling strategies and intensities (`sim_survey`), and 3) estimating the stratified mean and variance of simulated survey data (`test_surveys`; Table \@ref(tab:fun)). The equations behind these functions are detailed in the sections below. **`SimSurvey`** relies heavily on functions from the **`data.table`** [@dowle2017], **`raster`** [@hijmans2016] and **`plotly`** [@sievert2018] packages for their efficient data processing, geographic and plotting facilities, respectively. Package documentation has been published online using **`pkgdown`** (https://paulregular.github.io/SimSurvey/) and all the source `R` code behind **`SimSurvey`** is available on GitHub (https://github.com/PaulRegular/SimSurvey). **`SimSurvey`** can be installed via GitHub using the **`remotes`** package: +The **`SimSurvey`** package was written in the programming language `R` [@R] and it holds a series of functions for 1) simulating the abundance and distribution of virtual fish populations with correlation across space, time and age (`sim_abundance`, `sim_distribution`), 2) simulating surveys with a range of sampling strategies and intensities (`sim_survey`), and 3) estimating the stratified mean and variance of simulated survey data (`test_surveys`; Table \@ref(tab:fun)). **`SimSurvey`** relies heavily on functions from the **`data.table`** [@dowle2017], **`raster`** [@hijmans2016] and **`plotly`** [@sievert2018] packages for their efficient data processing, geographic and plotting facilities, respectively. Package documentation has been published online using **`pkgdown`** (https://paulregular.github.io/SimSurvey/) and all the source `R` code behind **`SimSurvey`** is available on GitHub (https://github.com/PaulRegular/SimSurvey). **`SimSurvey`** can be installed via GitHub using the **`remotes`** package: ```{r, echo = TRUE, eval = FALSE} install.packages("remotes") @@ -167,6 +169,8 @@ Table: (\#tab:fun) Names and descriptions of the key functions of **`SimSurvey`*
+The equations behind the functions listed in Table \@ref(tab:fun) are detailed in the *[Model structure]* section. Note that several of the core equations are implemented using closures, which are functions that contain data and return functions [@wickham2014]. This was done to avoid the repeated specifications of key arguments, such as ages and years, and also provide an option for advanced R users to supply custom closures with alternate equations. + ## `sim_abundance` @@ -194,7 +198,7 @@ Table: (\#tab:abundance) Default `sim_abundance` function call, with description
-Abundance at age and length is simulated using the `sim_abundance` function and a default function call is described in Table \@ref(tab:abundance) along with associated symbols from the equations outlined above. This function has a simple structure and requires the specification of a series of `ages` and `years` along with functions known as "closures", such as `sim_R`, `sim_Z` and `sim_vonB`, for simulating recruitment (`R`), total mortality (`Z`) and growth (`growth`), respectively. Closures are functions that contain data and return functions [@wickham2014]. For example, `sim_R(log_mean = log(500), log_sd = 0.5)` returns a function that holds the supplied parameter values and requires a sequence of years to be supplied. (Note that each of the above-mentioned closures include a plot argument such that quick visuals can be obtained using a line of code like this: `sim_R(log_mean = log(500), log_sd = 0.5, plot = TRUE)(years = 1:100)`). This structure was chosen to avoid the repeated specifications of ages and years. The use of closures also allows users to construct and use their own closures with a similar structure but different underlying formula. Overall, the function provides a simple tool for simulating a range of dynamic age-structured populations. For instance, below we provide examples where we simulate a relatively long and short lived species (note that default variance, starting abundance and growth settings were used in both simulations). +Abundance at age and length is simulated using the `sim_abundance` function and a default function call is described in Table \@ref(tab:abundance) along with associated symbols from the equations outlined above. This function has a simple structure and requires the specification of a series of `ages` and `years` along with functions known as "closures", such as `sim_R`, `sim_Z` and `sim_vonB`, for simulating recruitment (`R`), total mortality (`Z`) and growth (`growth`), respectively. Closures are functions that contain data and return functions [@wickham2014]. For example, `sim_R(log_mean = log(500), log_sd = 0.5)` returns a function that holds the supplied parameter values and requires a sequence of years to be supplied. (Note that each of the above-mentioned closures include a plot argument such that quick visuals can be obtained using a line of code like this: `sim_R(log_mean = log(500), log_sd = 0.5, plot = TRUE)(years = 1:100)`). Overall, the function provides a simple tool for simulating a range of dynamic age-structured populations. For instance, below we provide examples where we simulate a relatively long and short lived species (note that default variance, starting abundance and growth settings were used in both simulations). ```{r, echo = TRUE, eval = replot | is_html} set.seed(438) @@ -268,13 +272,16 @@ Table: (\#tab:distribution) Default `sim_distribution` function call, with descr | `+ lambda = 1,` | Smoothness of spatial correlation | $\lambda$ | | `+ phi_age = 0.5,` | Correlation across ages in spatial distribution | $\varphi_{\xi, \mathrm{age}}$ | | `+ phi_year = 0.9,` | Correlation across years in spatial distribution | $\varphi_{\xi, \mathrm{year}}$ | -| `+ group_ages = 5:20),` | Make space-age-year variance equal across these ages |   | +| `+ group_ages = 5:20,` | Make space-age-year noise equal across these ages^1^ |   | +| `+ group_years = NULL),` | Make space-age-year noise equal across these years^1^ |   | | `+ depth_par = sim_parabola(mu = 200,` | Depth at which abundance is typically highest (m) | $\mu_d$ | | `+ sigma = 70))` | Dispersion around depth of peak abundance (m) | $\sigma_d$ | +^1^ All ages or years are independent if argument values is `NULL`. +
-The above equations are used in the `make_grid`, `sim_ays_covar` and `sim_parabola` functions, and these functions are used within `sim_distribution` to distribute a population simulated using `sim_abundance` throughout a grid (Table \@ref(tab:distribution)). The output from `make_grid` is a raster object [@hijmans2016] with four layers: `depth`, `cell`, `division` and `strat`. If a more detailed and realistic grid is required, users can manually generate their own survey grid using real data and this grid can be supplied as a raster to `sim_distribution` if the same structure is used. The package includes a manually constructed survey grid of NAFO Subdivision 3Ps off the southern coast of Newfoundland (named `survey_grid`) and the data-raw folder in the GitHub directory includes the data and code used to construct this grid. However, for simplicity, we use `make_grid` to construct a square grid for a default run of `sim_distribution`. Below we generate and plot (Figure \@ref(fig:grid)) a default grid, another grid with the number of strata increased by increasing the number of `strat_splits`, and another with four divisions and a linear depth gradient (the sigmoid curve is forced to be linear when `shelf_width` is set to zero). +The above equations are used in the `make_grid`, `sim_ays_covar` and `sim_parabola` functions, and these functions are used within `sim_distribution` to distribute a population simulated using `sim_abundance` throughout a grid (Table \@ref(tab:distribution)). The output from `make_grid` is a raster object [@hijmans2016] with four layers: `depth`, `cell`, `division` and `strat`. If a more detailed and realistic grid is required, users can manually generate their own survey grid using real data and this grid can be supplied as a raster to `sim_distribution` if the same structure structure and correct projection is used. The package includes a manually constructed survey grid of NAFO Subdivision 3Ps off the southern coast of Newfoundland (named `survey_grid`) and the data-raw folder in the GitHub directory includes the data and code used to construct this grid. However, for simplicity, we use `make_grid` to construct a square grid for a default run of `sim_distribution`. Below we generate and plot (Figure \@ref(fig:grid)) a default grid, another grid with the number of strata increased by increasing the number of `strat_splits`, and another with four divisions and a linear depth gradient (the sigmoid curve is forced to be linear when `shelf_width` is set to zero). ```{r, echo = TRUE, eval = FALSE} @@ -309,7 +316,7 @@ if (replot) export_plot(p, file = "analysis/paper/figures/plot_grid.png", width ``` -```{r grid, out.height = "320px", fig.cap = "Plots produced by `plot_grid` when supplied a raster object produced by `make_grid` a) using default settings, b) settings that increase the number of times depth strata are horizontally split, and c) settings that produce a more linear depth gradient and increase the number of divisions. In these plots, the color gradient represents depth, the thick grey lines delineate divisions and thin white lines delineate strata."} +```{r grid, out.height = "320px", fig.cap = "Plots produced by `plot_grid` when supplied a raster object produced by `make_grid` a) using default settings, b) settings that increase the number of times depth strata are horizontally split, and c) settings that produce a more linear depth gradient and increase the number of divisions. In these plots, the yellow to purple color gradient represents depth, the thick grey lines delineate divisions and thin white lines delineate strata."} if (is_html) { p @@ -320,7 +327,7 @@ if (is_html) { ``` -In addition to supplying objects produced by `sim_abundance` and `make_grid`, the `sim_distribution` function requires two closures that describe the age-year-space covariance and the relationship with depth. Here we use `sim_ays_covar` and `sim_parabola` to control these relationships and a wide range of age and year specific distributions can be obtained by tweaking a few parameters in these closures. Below we run a default `sim_distribution` call, which generates a population that forms tight clusters that are more strongly correlated across years than ages, and another call that generates a population that is more diffuse (i.e. wider `range`) and exhibits stronger correlation across ages than years (i.e. lower `phi_year` and higher `phi_age`). Distributions can also be forced to be the same across ages and years by using the `group_ages` and `group_years` arguments, respectively, in the `sim_ays_covar` closure. Variance in the size of the clusters can also be modified by changing the `sd` argument in the `sim_ays_covar` function. In other words, these parameters can be modified to control the degree of age-specific clustering and inter-annual site-fidelity exhibited by the simulated population. Note that the resolution of the default grid is high and, as such, the simulations below may take minutes to complete. Also note that the key functions in the **`SimSurvey`** package have been set-up to be pipe [`%>%`; @bache2014] friendly. +In addition to supplying objects produced by `sim_abundance` and `make_grid`, the `sim_distribution` function requires two closures that describe the age-year-space covariance and the relationship with depth. Here we use `sim_ays_covar` and `sim_parabola` to control these relationships and a wide range of age and year specific distributions can be obtained by tweaking a few parameters in these closures (Figure \@ref(fig:distribution)). Below we run a default `sim_distribution` call, which generates a population that forms tight clusters that are more strongly correlated across years than ages, and another call that generates a population that is more diffuse (i.e. wider `range`) and exhibits stronger correlation across ages than years (i.e. lower `phi_year` and higher `phi_age`). Distributions can also be forced to be the same across ages and years by using the `group_ages` and `group_years` arguments, respectively, in the `sim_ays_covar` closure. Variance in the size of the clusters can also be modified by changing the `sd` argument in the `sim_ays_covar` function. In other words, these parameters can be modified to control the degree of age-specific clustering and inter-annual site-fidelity exhibited by the simulated population. Note that the resolution of the default grid is high and, as such, the simulations below may take minutes to complete. Also note that the key functions in the **`SimSurvey`** package have been set-up to be pipe [`%>%`; @bache2014] friendly. ```{r, echo = TRUE, eval = replot | is_html} @@ -336,7 +343,7 @@ b <- sim_abundance() %>% # pipe approach ``` -This function retains all the data simulated by `sim_abundance` and adds a data.table [@dowle2017], named `sp_N`, with abundance (`N`) split by `age`, `year` and `cell`. The function also retains the grid object and converts these data into a data.table, named `grid_xy`, with headers `x`, `y`, `depth`, `cell`, `division` and `strat`. The `sp_N` object can be merged with the `grid_xy` data by `cell` to associate abundance with specific locations, depth, divisions or strata. The `plot_distribution` function can be used to provide a quick visual of the distribution across ages and years. The code below will generate interactive plots with an Age-Year slider, however, for this paper we present a facet plot of the simulated data (Figure \@ref(fig:distribution)). +The `sim_distribution` function retains all the data simulated by `sim_abundance` and adds a data.table [@dowle2017], named `sp_N`, with abundance (`N`) split by `age`, `year` and `cell`. The function also retains the grid object and converts these data into a data.table, named `grid_xy`, with headers `x`, `y`, `depth`, `cell`, `division` and `strat`. The `sp_N` object can be merged with the `grid_xy` data by `cell` to associate abundance with specific locations, depth, divisions or strata. The `plot_distribution` function can be used to provide a quick visual of the distribution across ages and years. The code below will generate interactive plots with an Age-Year slider, however, for this paper we present a facet plot of the simulated data (Figure \@ref(fig:distribution)). ```{r, echo = TRUE, eval = FALSE} @@ -428,11 +435,13 @@ Table: (\#tab:survey) Default `sim_survey` function call, with descriptions and | `+ lengths_cap = 500,` | Maximum number of lengths to collect / set | $M_{\mathrm{lengths}}$ | | `+ length_group = 1,` | Length group bin size for age sampling (cm) | $l_{\mathrm{group}}$ | | `+ ages_cap = 10,` | Maximum number of ages to sample / length group / division | $M_{\mathrm{ages}}$ | -| `+ age_sammpling = "stratified")` | Controls whether age sampling is length `"stratified"` or `"random"` |   | +| `+ age_sampling = "stratified")` | Controls whether age sampling is length `"stratified"` or `"random"` |   |
-The function `sim_survey` can be used to simulate data from one survey over a population created using `sim_distribution`. A default function call is described in Table \@ref(tab:survey). The `sim_survey` function simulates the sampling process of the survey and, as such, requires a closure for defining catchability as a function of age and definitions of the design of the survey. Specifically, the `q` argument requires a closure, such as `sim_logistic`, for defining the probability of catching specific age groups, trawl dimensions are defined in the `trawl_dim` argument, and set, length and age sampling effort are defined using the `set_den`, `lengths_cap` and `ages_cap` arguments, respectively. Like `sim_abundance` and `sim_distribution`, custom closures can be supplied to `sim_survey` to impose alternate parametric curves for catchability at age. Multiple simulations of the same survey can be run using the `n_sims` argument, however, requesting large numbers of simulations can be computationally demanding depending on the processing capacity available. Below we use `sim_survey` to simulate two surveys over a default population, of which one is set-up to have higher set density (`set_den`) than the other. +The function `sim_survey` can be used to simulate data from one survey over a population created using `sim_distribution`. A default function call is described in Table \@ref(tab:survey). The `sim_survey` function simulates the sampling process of the survey and, as such, requires a closure for defining catchability as a function of age and definitions of the design of the survey. Specifically, the `q` argument requires a closure, such as `sim_logistic`, for defining the probability of catching specific age groups, trawl dimensions are defined in the `trawl_dim` argument, and set, length and age sampling effort are defined using the `set_den`, `lengths_cap` and `ages_cap` arguments, respectively. Also note that the `min_sets` argument imposes a minimum of number of sets to conduct per strata, regardless of its allocation given strat area and set density. This argument imposes a useful constraint for generating data to be analyzed using design-based approaches that require more than one value for the calculation of a mean. + +Like `sim_abundance` and `sim_distribution`, custom closures can be supplied to `sim_survey` to impose alternate parametric curves for catchability at age (i.e. a closure including an equation for a dome can be constructed and used in lieu of `sim_logistic` to impose a dome-shaped catchability). Multiple simulations of the same survey can be run using the `n_sims` argument, however, requesting large numbers of simulations can be computationally demanding depending on the processing capacity available. Below we use `sim_survey` to simulate two surveys over a default population, of which one is set-up to have higher set density (`set_den`) than the other. ```{r, echo = TRUE, eval = replot | is_html} @@ -452,7 +461,7 @@ b <- pop %>% ``` -Again, this function retains all the objects listed in the output of `sim_distribution` and adds data.tables that detail the set locations (`setdet`) and sampling details (`samp`). Catchability corrected abundance matrices, named `I` and `I_at_length`, are also produced and added to the output; these matrices are useful for comparing the true abundance available to the survey to abundance estimates obtained using design-based or model-based analyses of the simulated survey data. Specific surveys can be explored using the `plot_survey` function, which uses plotly [@sievert2018] and crosstalk [@cheng2016] in the background to link the bubble plot of aggregate set catch to the histogram of lengths and ages sampled to facilitate explorations of set-specific catches (Figure \@ref(fig:survey)). +Again, this function retains all the objects listed in the output of `sim_distribution` and adds data.tables that detail the set locations (`setdet`) and sampling details (`samp`). Catchability corrected abundance matrices (abundance at age matrix multiplied by survey catchability), named `I` and `I_at_length`, are also produced and added to the output; these matrices are useful for comparing the true abundance available to the survey to abundance estimates obtained using design-based or model-based analyses of the simulated survey data. Specific surveys can be explored using the `plot_survey` function, which uses plotly [@sievert2018] and crosstalk [@cheng2016] in the background to link the bubble plot of aggregate set catch to the histogram of lengths and ages sampled to facilitate explorations of set-specific catches (Figure \@ref(fig:survey)). ```{r, echo = TRUE, eval = FALSE} @@ -579,7 +588,7 @@ if (replot) export_plot(p, file = "analysis/paper/figures/plot_total_strat_fan.p ``` -```{r fan1, out.height = "250px", fig.cap = "Fan chart of stratified estimates of the trend in total abundance from surveys with different set densities, $D_{\\mathrm{sets}}$. The thick black line indicates the true trend in the total population available to the survey and the color gradient represents a range of probability envelopes from 10% to 90%. This plot is a facet of plots produced by `plot_total_strat_fan` when supplied results from `test_surveys`."} +```{r fan1, out.height = "250px", fig.cap = "Fan chart of stratified estimates of the trend in total abundance from surveys with different set densities, $D_{\\mathrm{sets}}$. The thick black line indicates the true trend in the total population available to the survey and the yellow to purple color gradient represents a range of probability envelopes from 10% to 90%. This plot is a facet of plots produced by `plot_total_strat_fan` when supplied results from `test_surveys`."} if (is_html) { p @@ -627,7 +636,7 @@ if (replot) export_plot(p, file = "analysis/paper/figures/plot_length_strat_fan. ``` -```{r fan2, out.height = "600px", fig.cap = "Fan chart of stratified estimates of abundance at length from year seven of the simulation from surveys with different set densities, $D_{\\mathrm{sets}}$, and length sampling protocol, $M_{\\mathrm{lengths}}$. The thick black line indicates the true trend in the total population available to the survey and the color gradient represents a range of probability envelopes from 10% to 90%. This plot is a facet of plots produced by `plot_total_strat_fan` when supplied results from `test_surveys`."} +```{r fan2, out.height = "600px", fig.cap = "Fan chart of stratified estimates of abundance at length from year seven of the simulation from surveys with different set densities, $D_{\\mathrm{sets}}$, and the maximum number of length samples, $M_{\\mathrm{lengths}}$. The thick black line indicates the true trend in the total population available to the survey and the yellow to purple color gradient represents a range of probability envelopes from 10% to 90%. This plot is a facet of plots produced by `plot_total_strat_fan` when supplied results from `test_surveys`."} if (is_html) { p @@ -654,7 +663,7 @@ if (replot) export_plot(p, file = "analysis/paper/figures/plot_age_strat_fan.png ``` -```{r fan3, out.height = "600px", fig.cap = "Fan chart of stratified estimates of the trend in abundance at age four from surveys with different set densities, $D_{\\mathrm{sets}}$, and length sampling protocol, $M_{\\mathrm{lengths}}$. Number of ages sampled per length group, $M_{\\mathrm{ages}}$, was 10 in all scenarios. The thick black line indicates the true trend in the total population available to the survey and the color gradient represents a range of probability envelopes from 10% to 90%. This plot is a facet of plots produced by `plot_total_strat_fan` when supplied results from `test_surveys`."} +```{r fan3, out.height = "600px", fig.cap = "Fan chart of stratified estimates of the trend in abundance at age four from surveys with different set densities, $D_{\\mathrm{sets}}$, and the maximum number of length samples, $M_{\\mathrm{lengths}}$. Number of ages sampled per length group, $M_{\\mathrm{ages}}$, was 10 in all scenarios. The thick black line indicates the true trend in the total population available to the survey and the yellow to purple color gradient represents a range of probability envelopes from 10% to 90%. This plot is a facet of plots produced by `plot_total_strat_fan` when supplied results from `test_surveys`."} if (is_html) { p @@ -724,7 +733,7 @@ surface_p <- plot_error_surface(tests, plot_by = "rule") ``` -```{r rank, out.height = "400px", fig.cap = "Divergent dot plot of the precision and accuracy (RMSE) of length based stratified estimates of abundance, and total sampling effort (number of sets [$N_{\\mathrm{sets}}$] and length measurements [$N_{\\mathrm{measured}}$]), under various sampling protocols (set density [$D_{\\mathrm{sets}}$] and maximum number of lengths measured per set [$M_{\\mathrm{lengths}}$]). Records are ranked by lowest to highest RMSE score. Within each plot, a color ramp is applied from lowest to highest value as an additional visual aid. Note that the exponent format of the axes defaults to SI unit symbols (e.g. M for million)."} +```{r rank, out.height = "400px", fig.cap = "Divergent dot plot of the precision and accuracy (RMSE) of length based stratified estimates of abundance, and total sampling effort (number of sets [$N_{\\mathrm{sets}}$] and length measurements [$N_{\\mathrm{measured}}$]), under various sampling protocols (set density [$D_{\\mathrm{sets}}$] and maximum number of lengths measured per set [$M_{\\mathrm{lengths}}$]). Records are ranked by lowest to highest RMSE score. Within each plot, a yellow to purple color gradient is applied from lowest to highest value as an additional visual aid. Note that the exponent format of the axes defaults to SI unit symbols (e.g. M for million)."} if (is_html) { rank_p diff --git a/man/sim_ays_covar.Rd b/man/sim_ays_covar.Rd index 3eb5c9a..c7df066 100644 --- a/man/sim_ays_covar.Rd +++ b/man/sim_ays_covar.Rd @@ -23,9 +23,9 @@ length as ages} \item{phi_year}{Defines autocorrelation through years. Can be one value or a vector of the same length as years} -\item{group_ages}{Make space-age-year variance equal across these ages} +\item{group_ages}{Make space-age-year noise equal across these ages} -\item{group_years}{Make space-age-year variance equal across these years} +\item{group_years}{Make space-age-year noise equal across these years} } \description{ These functions return a function to use inside \code{\link{sim_distribution}}.