JOSS Review from MikeKaller,
Please see the original review at https://github.com/openjournals/joss-reviews/issues/3444
There were three points and here is how we addressed them:
- Functionality: Have the functional claims of the software been confirmed? #3563
I had good success testing several functions (h_vb_stan, h_gompertz_stan, and catch_curve) with my data and with public data sets (BlackDrum2001 and Brook Trout). The Gompertz model was spot on to my previous estimates. When testing h_vb_stan, the estimate for L infinity was 5000 mm more than it should have been, when I requested t0 = TRUE. The estimates were fine for t0 = FALSE. This occurred with one data set (mine), but was fine with BlackDrum2001 (from Ogle). My data are biased toward very young fish (age 1-2), with few fish over age 4, which might be the problem. However, I have been able to achieve reasonable estimates in R and SAS. These data are in press, but I attached for the authors to check. Please consider them not open data at the moment. It might have been me or it might have been the data, but then again, it might have been the package. I attempted to attach, hope it worked. MG.xlsx
We examined your data. Thank you for sharing. We had to increase the number iterations and change RStan settings for your data to converge. We have uploaded our script to GitHub as well as emailed them to you (the reviewer).
- Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems). #3567
I evaluated this package from two perspectives. First, I examined the package from the perspective of a fisheries professional who understands the models and who has programming experience. Second, I examined the package from the perspective of a graduate student who is both new to the models and to programming. I end up assisting a lot of students in this position. My largest criticism is from this second perspective. Please strongly consider using published datasets in your vignettes. This would allow students and others new to modeling to compare their outcomes to published outcomes. This would then allow them to tinker and modify to understand better how the models work. Consider using the datasets used in Ogle (2016), like the Black Drum data set used in individual growth examples and the Brook Trout data used in the catch curve examples. This would be my strongest recommendation to increase accessibility.
Thank you for your perspective. We have included a vignette using a data set that we created the package for. This data was not public at the time of our original submission.
I have another general recommendation. Instead of targeting more intermediate users, the authors could with a little effort make this more accessible to new users. I would like one of MS students students to use this package, however, the leap from her R experience to this package is not trivial. Recognizing the her data needs to be converted to vectors for analysis is not something the she would intuitively do without clear instructions. I recognize that that fish_length is describe as a vector, but new users get confused about data structure. Data structure is the #1 (closed) question that I get from students. A little more description and a clear example of the data structure would increase accessibility and usage.
One other general rant – students find the random data generated for package examples frustrating. They don’t know enough to know if the output is reasonable. Conversely, as previously mentioned, providing example with public datasets allows students to follow the process and check their results.
We agree. We included these ideas in our worked example with the new vignette.
We also mention this example paper, dataset, and workflow in our manuscript.
- References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax? #3568
- Lines 42 and 63: The copy of Ogle that I am staring in my hand at states copyright 2016. Please correct.
Thank you for catching this, we updated the references as requested.