[REVIEW]: BeeNestABM: An open-source agent-based model of spatiotemporal distribution of bumblebees in nests

whedon commented 6 years ago

Submitting author: @ashleefv (Ashlee N. Ford Versypt) Repository: https://github.com/ashleefv/BeeNestABM Version: 2.0 Editor: @Kevin-Mattheus-Moerman Reviewer: @sdelandtsheer Archive: 10.5281/zenodo.1303422

Status

Status badge code:

HTML: <a href="http://joss.theoj.org/papers/d9a4bff31f9d3b362ce72234c1594e34"><img src="http://joss.theoj.org/papers/d9a4bff31f9d3b362ce72234c1594e34/status.svg"></a>
Markdown: [![status](http://joss.theoj.org/papers/d9a4bff31f9d3b362ce72234c1594e34/status.svg)](http://joss.theoj.org/papers/d9a4bff31f9d3b362ce72234c1594e34)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@sdelandtsheer, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

Make sure you're logged in to your GitHub account
Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @Kevin-Mattheus-Moerman know.

Review checklist for @sdelandtsheer

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

[x] Repository: Is the source code for this software available at the repository url?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
[x] Version: Does the release version given match the GitHub release (1.0)?
[x] Authorship: Has the submitting author (@ashleefv) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
[x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
[x] Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
[x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

[x] Authors: Does the paper.md file include a list of authors with their affiliations?
[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

whedon commented 6 years ago

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks. @sdelandtsheer it looks like you're currently assigned as the reviewer for this paper :tada:.

:star: Important :star:

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

watching

You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

notifications

For a list of things I can do to help you, just type:

@whedon commands

whedon commented 6 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

Kevin-Mattheus-Moerman commented 6 years ago

@ashleefv this is where the review will take place. @sdelandtsheer thanks for acting as reviewer. Let me know if you have any questions.

Kevin-Mattheus-Moerman commented 6 years ago

@ashleefv for the submitted works cited in your paper, are you able to post these on a pre-print server and add the URL's or DOI's to these references? e.g. https://engrxiv.org/ (you can check your rights for individual journals here)

ashleefv commented 6 years ago

I removed the line referencing the submitted works. My co-authors preferred this over pre-prints after the papers are in review.

Ashlee N. Ford Versypt, Ph.D. Assistant Professor, School of Chemical Engineering, Oklahoma State University Member, Harold Hamm Diabetes Center, University of Oklahoma Health Sciences Center 420 Engineering North, OSU, Stillwater, OK 74078 Ph: 405-744-5280 ashleefv@okstate.edu Ford Versypt Lab Website https://sites.google.com/site/ashleefordversypt/

On Wed, May 2, 2018 at 8:59 PM, Kevin Mattheus Moerman < notifications@github.com> wrote:

@ashleefv https://github.com/ashleefv for the submitted works cited in your paper, are you able to post these on a pre-print server and add the URL's or DOI's to these references? e.g. https://engrxiv.org/ (you can check your rights for individual journals here http://www.sherpa.ac.uk/romeo/index.php)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/joss-reviews/issues/718#issuecomment-386173011, or mute the thread https://github.com/notifications/unsubscribe-auth/AMD-Nm7HKP1tYfHZU5O1v1AqlB7vedZpks5tumR6gaJpZM4TwZcd .

sdelandtsheer commented 6 years ago

Hi, I have some minor remarks and a problem assessing the functionality:

"scienfic" should be corrected in the paper and the .md
if typical simulation times are 5-60 minutes and given bees' circadian rhythm is it correct to mention "days"?
a number of scripts call a specific local path: alternateParameterEstimation.m, _DistrRunNTumble.m, _EstimateTransProbSpatial.m, inSilicoExp.m. Is it possible to modify them or remove them if they are not used?

I had issues running the GUI. File "beefiles/beefiles/Beeimage.jpg" does not exist, so the app does not start. Furthermore, I could not run inSilicoExp_Working.m, and traced it to motionParams being a 3x3 matrix instead of a structure. Could you please either correct these and make sure the repo version is working as intended, or maybe provide more detailed instruction how to use the app for educational purposes and run simulations? Thanks,

ashleefv commented 6 years ago

Replying to the bullets in order

corrected in paper.md and README.md
In the experimental measurements, the bees are videotaped for 1 hour periods on different days. Additionally, when they are dosed with pesticides, the data is collected 24 hours after dosing for a one hour period. Thus, we deem it appropriate to mention days among in the short time scales.
The mentioned scripts were removed as they are not needed for the main functionality of the model. They were included in development stages.
Regarding inSilicoExp_Working.m, this was used for our first more specific paper (under review). We updated the modelParams object when we generalized for modelBeeScript.m. I have updated this section of inSilicoExp_Working.m and a related changed in simulationOutputSpatial.m. Both seem to be working as expected now.
Regarding the GUI, the image file was updated and referenced properly and the corresponding data files were included. The GUI is now running as intended.

Ashlee N. Ford Versypt, Ph.D. Assistant Professor, School of Chemical Engineering, Oklahoma State University Member, Harold Hamm Diabetes Center, University of Oklahoma Health Sciences Center 420 Engineering North, OSU, Stillwater, OK 74078 Ph: 405-744-5280 ashleefv@okstate.edu Ford Versypt Lab Website https://sites.google.com/site/ashleefordversypt/

On Fri, May 11, 2018 at 6:08 AM, Seb notifications@github.com wrote:

Hi, I have some minor remarks and a problem assessing the functionality:

"scienfic" should be corrected in the paper and the .md

if typical simulation times are 5-60 minutes and given bees' circadian rhythm is it correct to mention "days"?

a number of scripts call a specific local path: alternateParameterEstimation.m, Distr_RunNTumble.m, EstimateTransProb_Spatial.m, inSilicoExp.m. Is it possible to modify them or remove them if they are not used?

I had issues running the GUI. File "beefiles/beefiles/Beeimage.jpg" does not exist, so the app does not start. Furthermore, I could not run inSilicoExp_Working.m, and traced it to motionParams being a 3x3 matrix instead of a structure. Could you please either correct these and make sure the repo version is working as intended, or maybe provide more detailed instruction how to use the app for educational purposes and run simulations? Thanks,

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/joss-reviews/issues/718#issuecomment-388333835, or mute the thread https://github.com/notifications/unsubscribe-auth/AMD-NuwqTVidVRtWlvS4qCAQiKaUVtOlks5txXEYgaJpZM4TwZcd .

Kevin-Mattheus-Moerman commented 6 years ago

@sdelandtsheer can you comment on @ashleefv 's implementations/fixes. Please let us know if there are any more issues.

sdelandtsheer commented 6 years ago

Hi,

thanks for the correction in the paper, I now get your intention behind 'days' and find it valid.
while the app starts, the following error is generated when running: Index exceeds matrix dimensions. Error in rules (line 73) paramcase = varargin{2}; _Error in simulationattraction (line 18) nestSimulationData(timestep+1,:,:) = rules(dt,nestSimulationData(timestep,:,:),... so what happens is 'rules' is being called with 13 arguments while from the code I understand that if it has more than 12, then it should have 14 or 15. It also seems that in 'simulation_attraction.m', the variable dt is never defined.
optimizerShellSpatial: does not run for me, however when 'tags' is changed to 'colony.tags' in lines 39, 115, 205 the script works. Could you confirm this is ok and make the respective corrections?
inSilicoExp_Working.m: does not work either, except for the first treatment ('full'), and it seems that the variable MotionParamsCurrent is expected to have 3 dimensions, while in effect it has only two. This generates the following error: _Error using inSilicoExpWorking (line 146) You cannot subscript a table using linear indexing (one subscript) or multidimensional indexing (three or more subscripts). Use a row subscript and a variable subscript. The script 'generateMotionParamsObject_general.m' however always generate a table (2 dimensions).

In addition, there are scripts in the base folder and in the 'beefile' folder that are named identically. Sometimes they contain different code, which might make things go wrong depending the specific Matlab install and configuration. It would be much better to give them a unique name.

I hope this helps and I wait for your reply. I use Matlab 2017a. Let me know if I am getting anything wrong.

Best regards,

Kevin-Mattheus-Moerman commented 6 years ago

@ashleefv how are you getting on? Can you respond to @sdelandtsheer 's comments? Thanks. :robot:

ashleefv commented 6 years ago

I'm traveling through the end of the week and should be able to address them over the weekend.

Ashlee N. Ford Versypt, Ph.D. Assistant Professor, School of Chemical Engineering, Oklahoma State University Member, Harold Hamm Diabetes Center, University of Oklahoma Health Sciences Center 420 Engineering North, OSU, Stillwater, OK 74078 Ph: 405-744-5280 ashleefv@okstate.edu Ford Versypt Lab Website https://sites.google.com/site/ashleefordversypt/

On Wed, May 30, 2018 at 9:19 PM, Kevin Mattheus Moerman < notifications@github.com> wrote:

@ashleefv https://github.com/ashleefv how are you getting on? Can you respond to @sdelandtsheer https://github.com/sdelandtsheer 's comments? Thanks. 🤖

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/joss-reviews/issues/718#issuecomment-393371174, or mute the thread https://github.com/notifications/unsubscribe-auth/AMD-NuCFkjvEMvaJcckntgUseb-SM44Uks5t30UcgaJpZM4TwZcd .

ashleefv commented 6 years ago

I updated beefile folder script names to include _app at the end to make app versions of the files have unique names.
I am using MATLAB 2017b, and I don't think that we have anything that explicitly required 2017b vs. a or slightly older versions.

ashleefv commented 6 years ago

When the app starts on my computer I do not get an error. Perhaps it was due to the two instances of the filename rules.m (and other scripts) in the repository. Do you get any errors now that the app files all have unique names? Also, dt is defined in bee_setup_script_app.m.

Note that 'tags' and 'taglist' are two separate things. tags = colony.orTagTreat is a vector of 0, 1, 2, or 3 for each bee indicating the level of dosing treatment, while taglist = colony.tags is a vector of 4 digit indices for the bees, which is not actually used later (so I have deleted it). When I ran it, I got an error message that colony.tags wasn't even defined so I deleted taglist = colony.tags from line 39. This was a legacy statement from when we had .mat files with more information in them. Some time ago we reduced the size to simplify to information that we need for the simulations. We had run our tests and production runs on optimizerShellSpatial with the richer .mat files, so the useless line 39 hadn't thrown errors for us in another directory. Now I've tested it with 2016b and 2017b where optimizerShellSpatial.m is in the beeNestABm repository and reads the proper .mat files in the data subdirectory.

Good catch on the inSilicoExp_Working.m. My colleague ran the other non-full scenario "treatment groups". I had just seen that it ran on the "full" treatment scenario without issue. I have decided that I will remove inSilicoExp_Working.m because the in silico experiment it runs (with an older version of hard-coded motion params) is very specific to one empirical study that we have under review. Our more general simulation tool that we expect for others to adopt or use directly is modelBeeScript.m. It was developed most recently with the goal of enabling reuse and extension. So the inSilicoExp_Working.m file has been deleted from the repository, and the README has been updated accordingly with the modelBeeScript listed first among the main files now as it should be the most relevant for users.

sdelandtsheer commented 6 years ago

Thanks for the corrections, I will finalize the review in the next few days.

sdelandtsheer commented 6 years ago

I have successfully tested the toolbox and app. What was not working before has either been removed or corrected in a satisfying way. I recommend accepting this paper. Sorry for the delay, and thanks for the good work.

Regards,

Kevin-Mattheus-Moerman commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago

Attempting PDF compilation. Reticulating splines etc...

Kevin-Mattheus-Moerman commented 6 years ago

Thanks @sdelandtsheer for your review! :robot: :rocket:

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

Kevin-Mattheus-Moerman commented 6 years ago

Great. It looks like we are nearly there. @ashleefv would you be able to incorporate/mention the figure in the text of the paper?

ashleefv commented 6 years ago

The figure caption was typed in the paper.md file but doesn't show up when compiling. This has been moved into the text as two stand-alone sentences at the end of the paragraph to mention the figure in the text.

ashleefv commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

ashleefv commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

ashleefv commented 6 years ago

My last name is Ford Versypt, two words without a hyphen. Is there a way to make the auto citation at the bottom of the article to include the Ford part without including a hyphen?

arfon commented 6 years ago

My last name is Ford Versypt, two words without a hyphen. Is there a way to make the auto citation at the bottom of the article to include the Ford part without including a hyphen?

There is, but I'll have to do this manually before finishing up the paper acceptance. Please remind me to do this when we're done with the review.

ashleefv commented 6 years ago

Ok. I'm done with all the requested edits at this point.

Kevin-Mattheus-Moerman commented 6 years ago

Thanks @ashleefv can you create a DOI of the archived reviewed software and post it here? You can use a service like zenodo, see also https://guides.github.com/activities/citable-code/.

ashleefv commented 6 years ago

DOI: 10.5281/zenodo.1303422

Kevin-Mattheus-Moerman commented 6 years ago

Thanks @ashleefv. @arfon we are good to accept here. Above is the DOI and the version is now at v2.0.

arfon commented 6 years ago

@whedon set 10.5281/zenodo.1303422 as archive

whedon commented 6 years ago

OK. 10.5281/zenodo.1303422 is the archive.

arfon commented 6 years ago

@sdelandtsheer - many thanks for your review here and to @Kevin-Mattheus-Moerman for editing this submission ✨

@ashleefv - your paper is now accepted into JOSS and your DOI is https://doi.org/10.21105/joss.00718 :zap: :rocket: :boom:

whedon commented 6 years ago

:tada::tada::tada: Congratulations on your paper acceptance! :tada::tada::tada:

If you would like to include a link to your paper from your README use the following code snippet:

[![DOI](http://joss.theoj.org/papers/10.21105/joss.00718/status.svg)](https://doi.org/10.21105/joss.00718)

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://joss.theoj.org/reviewer-signup.html
Making a small donation to support our running costs here: https://www.flipcause.com/secure/cause_pdetails/Mjk3Nzk=

ashleefv commented 6 years ago

Can we still do this?

My last name is Ford Versypt, two words without a hyphen. Is there a way to make the auto citation at the bottom of the article to include the Ford part without including a hyphen?

There is, but I'll have to do this manually before finishing up the paper acceptance. Please remind me to do this when we're done with the review.

Ashlee N. Ford Versypt, Ph.D. Assistant Professor, School of Chemical Engineering, Oklahoma State University Member, Harold Hamm Diabetes Center, University of Oklahoma Health Sciences Center 420 Engineering North, OSU, Stillwater, OK 74078 Ph: 405-744-5280 ashleefv@okstate.edu Ford Versypt Lab Website https://sites.google.com/site/ashleefordversypt/

On Tue, Jul 3, 2018 at 6:29 AM whedon notifications@github.com wrote:

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippet:

This is how it will look in your documentation:

[image: DOI] https://doi.org/10.21105/joss.00718

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://joss.theoj.org/reviewer-signup.html

Making a small donation to support our running costs here: https://www.flipcause.com/secure/cause_pdetails/Mjk3Nzk=

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/joss-reviews/issues/718#issuecomment-402120339, or mute the thread https://github.com/notifications/unsubscribe-auth/AMD-Nvh108b8rIAwfER2OfdNNRuM-GgNks5uC1WFgaJpZM4TwZcd .

arfon commented 6 years ago

Sure thing. I've just updated the paper. This may take a few hours to show as updated on the JOSS site as the PDFs are cached.

openjournals / joss-reviews