search

openjournals / joss-reviews

Reviews for the Journal of Open Source Software
Creative Commons Zero v1.0 Universal
700 stars 36 forks source link

[REVIEW]: PlanktonIndividuals.jl: A GPU supported individual-based phytoplankton life cycle model. #4207

Closed editorialbot closed 2 years ago

editorialbot commented 2 years ago

Submitting author: !--author-handle-->@zhenwu0728<!--end-author-handle-- (Zhen Wu) Repository: https://github.com/JuliaOcean/PlanktonIndividuals.jl Branch with paper.md (empty if default branch): Version: v0.5.1 Editor: !--editor-->@elbeejay<!--end-editor-- Reviewers: @Datseris, @BrodiePearson Archive: 10.5281/zenodo.6507001

Status

status

Status badge code:

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

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) by leaving comments 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

@navidcy & @Datseris, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @elbeejay know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @Datseris

📝 Checklist for @BrodiePearson

editorialbot commented 2 years ago

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

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

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf
editorialbot commented 2 years ago 
Software report:

github.com/AlDanial/cloc v 1.88  T=0.15 s (643.0 files/s, 92586.9 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Julia                           74           2112            653           9565
Markdown                        13            224              0            739
TOML                             5             86              1            357
TeX                              1             11              0            129
YAML                             4              6              0             84
-------------------------------------------------------------------------------
SUM:                            97           2439            654          10874
-------------------------------------------------------------------------------

gitinspector failed to run statistical information for the repository
editorialbot commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.21105/joss.02813 is OK
- 10.5194/gmd-10-4175-2017 is OK
- 10.1111/j.1529-8817.1973.tb04092.x is OK
- 10.3354/meps148187 is OK
- 10.1029/2021gb006941 is OK
- 10.1177/00375497211068820 is OK
- 10.3389/fmicb.2020.00086 is OK
- 10.1038/nrmicro.2016.62 is OK
- 10.1126/science.1254421 is OK
- 10.1016/j.ecolmodel.2011.10.001 is OK
- 10.1126/science.1138544 is OK

MISSING DOIs

- None

INVALID DOIs

- None
editorialbot commented 2 years ago

Wordcount for paper.md is 827

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

elbeejay commented 2 years ago

@navidcy and @Datseris thanks again for agreeing to review this submission to JOSS. We've just switched over from whedon to the new editorialbot, and the review process has changed subtly. Instead of your checklist being at the top of this issue, you can generate your own checklist with the command @editorialbot generate my checklist. Otherwise the review process is functionally the same as it has been in the past -- please feel free to reach out to me with any questions. Remember to open issues in the PlanktonIndividuals.jl repository that are related to this JOSS review, and "link" them to this review issue by posting this URL (https://github.com/openjournals/joss-reviews/issues/4207) in the text of the issue you open.

We're starting this review before I've found a 3rd reviewer out of respect for @navidcy's availability in late March, so as a heads up to @zhenwu0728 and co-authors, I will still be reaching out to and hopefully adding another reviewer here.

Datseris commented 2 years ago

Review checklist for @Datseris

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

elbeejay commented 2 years ago

@editorialbot add @BrodiePearson as reviewer

editorialbot commented 2 years ago

@BrodiePearson added to the reviewers list!

BrodiePearson commented 2 years ago

Review checklist for @BrodiePearson

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

Datseris commented 2 years ago

Hello @elbeejay , I would like to submit my review:

Summary

PlanktonIndividuals.jl is a Julia package that simulates the lifecycle and transport of plankton in oceanic currents. It has strong performance capabilities utilizing GPU infrastructure. The paper makes a clear case supporting the need for the package. The paper and authors satisfy the official checklist of JOSS. As far as I can tell, the documentation of the package is very good. It includes documentation strings, examples, and clearly states the actual physics used in the models via stating actual equations, something that (unfortunately) is missing from many packages. I was able to install the software and run their 0D example without problems. All in all, I would recommend publication, however, there are some points I would strongly recommend the authors to consider, and address satisfactorily.

Additions I would recommend

  1. The first couple of sentences of either the Summary or the Statement of Need sections should introduce a general audience to the relevance of phytoplankton in general. The paper is written with the expectation that the reader already knows why this topic is useful, important, or relevant to do research on. As such, it is not written for a diverse, non-specialist audience as expected by JOSS guidelines. A couple of sentences can fix this. The paper furthermore does not define what "Eulerian" or "Lagrangian" means.
  2. Julia has a general purpose software for individual based modelling, called Agents.jl, which the authors cite. The authors however do not discuss what features or functionalities are missing from Agents.jl that requires them to write a new package instead of extending the existing one. (Full disclosure to the editor: I am a developer of Agents.jl. Admittedly, for me it is actually clear why the authors could not use the existing Agents.jl infrastructure, but I do not believe it would be as clear for a general audience).
  3. A discussion on the software design and extendability of the package is missing. For example, how does the software simulate ocean currents that transport phytoplantkon? Does it integrate with existing packages such as Oceanigans.jl? How much flexibility is there in the ocean+plankton interplay? Could it simulate other "particles" besides plankton? Could it simulate the tranport of non-alive chemicals, that nevertheless perform reactions with other chemicals? If not, why? is there something fundamentally special about planktons that separates them from other physical entities? It really is not clear to me why this package is named "PlanktonIndividuals" instead of something like "InvidualOceanTranport" or so. Given my experience in individual based modelling, I do not see a particularly reason of why the infastructure of this package would be limited only to Plankton.
  4. The test suite of the package could definitely benefit from improvements. For example, the tests do not test individual atomic functions, as a unit test suite should, but rather entire simulation pipelines. The coverage also seems to be low at only 62%.
  5. The documentation does not have installation instructions. Given that this is a registered package, it is easy to resolve this simply by adding "This package is registered, use Pkg.add("PlanktonIndividuals") to install it." in the homepage.
  6. The package GitHub page does not have Community guidelines.

Minor technical details

elbeejay commented 2 years ago

Thank you for the thorough review @Datseris! I agree with your comments about the documentation being quite comprehensive and clear, and your suggestions to @zhenwu0728 and co-authors seem reasonable to me.

elbeejay commented 2 years ago

@navidcy I was going to ping you so that hopefully this review doesn't slip through the cracks before you are unavailable - the new JOSS procedure requires you to create your own reviewer checklist with the command @editorialbot generate my checklist

Thanks!

zhenwu0728 commented 2 years ago

Thank you for your comments and suggestions @Datseris! @gaelforget and I are working on it.

navidcy commented 2 years ago

@navidcy I was going to ping you so that hopefully this review doesn't slip through the cracks before you are unavailable - the new JOSS procedure requires you to create your own reviewer checklist with the command @editorialbot generate my checklist

Thanks!

Thanks. I haven't forgotten about this.

elbeejay commented 2 years ago

Hello all, I'm going to ask our editorial bot to send out reminders to @navidcy and @BrodiePearson over the next few weeks just to hopefully keep things moving along with this review. @zhenwu0728 please feel free to provide an update in this thread when you feel you have addressed @Datseris comments to ensure those outstanding review checklist items can be crossed off.

Thanks all, Jay

editorialbot commented 2 years ago

Reminder set for @navidcy in one week

elbeejay commented 2 years ago

@editorialbot remind @BrodiePearson in two weeks

editorialbot commented 2 years ago

Reminder set for @BrodiePearson in two weeks

elbeejay commented 2 years ago

@editorialbot remind @navidcy in seven days

editorialbot commented 2 years ago

Reminder set for @navidcy in seven days

editorialbot commented 2 years ago

:wave: @navidcy, please update us on how your review is going (this is an automated reminder).

editorialbot commented 2 years ago

:wave: @navidcy, please update us on how your review is going (this is an automated reminder).

navidcy commented 2 years ago

I’m really sorry. I’m down with covid… :(

BrodiePearson commented 2 years ago

@elbeejay Here is my review:

Overall this looks like a useful package with good documentation. I particularly like that the package has both stand-alone utility (lab experiments) and an ability to integrate with other software packages used to simulate ocean flows (e.g., Oceananigans). I only have a few very small comments to add beyond the previous review

Review Comments

elbeejay commented 2 years ago

@navidcy I wish you all the best in your recovery. I'll remove you from the reviewer list here in a moment.

@BrodiePearson thanks for completing your review :+1: your comments appear to be fairly straightforward for @zhenwu0728 and co-authors to address.

elbeejay commented 2 years ago

@editorialbot remove @navidcy from reviewers

editorialbot commented 2 years ago

@navidcy removed from the reviewers list!

editorialbot commented 2 years ago

:wave: @BrodiePearson, please update us on how your review is going (this is an automated reminder).

elbeejay commented 2 years ago

@zhenwu0728 I think you've gotten a nice set of reviews that are overall quite supportive of the package, and constructive in terms of their feedback and suggestions. When do you anticipate making changes and having revisions complete by? Some rough timeline will be helpful so that @BrodiePearson, @Datseris, and I know when we can expect to have to take another look at this. Thanks!

zhenwu0728 commented 2 years ago

Thanks for the reminder, @elbeejay. And thanks for all the insightful and constructive comments from @Datseris and @BrodiePearson. We've already started the revision of the paper and the package (e.g. add unit tests) and hopefully finish in one week or so. I'll upload a point-to-point response once finished. Thanks again!

zhenwu0728 commented 2 years ago

Hi @elbeejay, @Datseris, and @BrodiePearson, Thanks for all your comments and suggestions. With the help of @gaelforget, we would like to submit our responses: Please note that the revised package and paper are tagged v0.5.0.

Reply to @Datseris

Summary

PlanktonIndividuals.jl is a Julia package that simulates the lifecycle and transport of plankton in oceanic currents. It has strong performance capabilities utilizing GPU infrastructure. The paper makes a clear case supporting the need for the package. The paper and authors satisfy the official checklist of JOSS. As far as I can tell, the documentation of the package is very good. It includes documentation strings, examples, and clearly states the actual physics used in the models via stating actual equations, something that (unfortunately) is missing from many packages. I was able to install the software and run their 0D example without problems. All in all, I would recommend publication, however, there are some points I would strongly recommend the authors to consider, and address satisfactorily.

Reply: Thank you for the positive evaluation of our package and paper.

Additions I would recommend

  1. The first couple of sentences of either the Summary or the Statement of Need sections should introduce a general audience to the relevance of phytoplankton in general. The paper is written with the expectation that the reader already knows why this topic is useful, important, or relevant to do research on. As such, it is not written for a diverse, non-specialist audience as expected by JOSS guidelines. A couple of sentences can fix this. The paper furthermore does not define what "Eulerian" or "Lagrangian" means.

    Reply: Thanks for pointing it out. We have added two sentences at the beginning of Summary. Also, "Eulerian" or "Lagrangian" are explained at the end of the second paragraph of Summary.

  2. Julia has a general purpose software for individual based modelling, called Agents.jl, which the authors cite. The authors however do not discuss what features or functionalities are missing from Agents.jl that requires them to write a new package instead of extending the existing one. (Full disclosure to the editor: I am a developer of Agents.jl. Admittedly, for me it is actually clear why the authors could not use the existing Agents.jl infrastructure, but I do not believe it would be as clear for a general audience).

    Reply: Thanks for the comment. We are sorry that we did not state clearly in the paper about the purpose of our package and how it compares with other individual based models. Now we have added some text in the fourth and fifth paragraph in Statement of Need for clarification.

  3. A discussion on the software design and extendability of the package is missing. For example, how does the software simulate ocean currents that transport phytoplantkon? Does it integrate with existing packages such as Oceanigans.jl? How much flexibility is there in the ocean+plankton interplay? Could it simulate other "particles" besides plankton? Could it simulate the tranport of non-alive chemicals, that nevertheless perform reactions with other chemicals? If not, why? is there something fundamentally special about planktons that separates them from other physical entities? It really is not clear to me why this package is named "PlanktonIndividuals" instead of something like "InvidualOceanTranport" or so. Given my experience in individual based modelling, I do not see a particularly reason of why the infastructure of this package would be limited only to Plankton.

    Reply: Thank you for the comment. Individual-based modeling and the transport of Lagrangian particles are part of the framework of our package. However, its defining component is the phytoplankton physiological equations and biogeochemical equations embeded in this framework. The possibility to simplify equations in the model to simulate simple passive tracers and particles is shown in Fig 3. Yet, representing all types of material interactions within the Ocean is beyond the scope of our package.

    The discussion of the package design has been extended in the last two paragraphs of the summary. Possible extensions to the model are provided in the final paragraph of the paper. Others can be envisioned but those listed are viewed as rather high priority.

  4. The test suite of the package could definitely benefit from improvements. For example, the tests do not test individual atomic functions, as a unit test suite should, but rather entire simulation pipelines. The coverage also seems to be low at only 62%.

    Reply: Thank you for the suggestion. We have now added unit tests and brought up the coverage to 80%.

  5. The documentation does not have installation instructions. Given that this is a registered package, it is easy to resolve this simply by adding "This package is registered, use Pkg.add("PlanktonIndividuals") to install it." in the homepage.

    Reply: It has been added in Readme.

  6. The package GitHub page does not have Community guidelines.

    Reply: Thanks for pointing it out. We have added a CONTRIBUTING.md in the package.

Minor technical details

Reply to @BrodiePearson

Overall this looks like a useful package with good documentation. I particularly like that the package has both stand-alone utility (lab experiments) and an ability to integrate with other software packages used to simulate ocean flows (e.g., Oceananigans). I only have a few very small comments to add beyond the previous review

Review Comments

zhenwu0728 commented 2 years ago

@editorialbot generate pdf

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

elbeejay commented 2 years ago

Hi @zhenwu0728, thanks for addressing the comments and providing us with a thorough set of responses. At this time, I'd like to ask @Datseris and @BrodiePearson to take a look at your responses when they get a chance. I'll update the version number for JOSS, thanks for pointing that out!

elbeejay commented 2 years ago

@editorialbot set v0.5.0 as version

editorialbot commented 2 years ago

Done! version is now v0.5.0

BrodiePearson commented 2 years ago

@elbeejay @zhenwu0728 Thanks for making the modifications. This looks good to me now. (note, there is a minor typo in the new Figure 3 caption: "liens" to "lines")

Datseris commented 2 years ago

@zhenwu0728 Thanks for your reply! @elbeejay I recommend publication as is!

elbeejay commented 2 years ago

Fantastic, thanks @BrodiePearson and @Datseris for taking a look at the revisions. @Datseris if you don't mind checking off the remaining boxes in your reviewer checklist just for the sake of completeness that'd be appreciated.

@zhenwu0728 I'll have a closer look at everything later today or tomorrow to hopefully catch any remaining typos and the like, then I'll give you a list of the final steps we'll need you to take before publication.

Thanks all!

elbeejay commented 2 years ago

@editorialbot generate pdf

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

gaelforget commented 2 years ago

Thanks @Datseris and @BrodiePearson for the very helpful reviews.

elbeejay commented 2 years ago

@zhenwu0728 and @gaelforget I have some minor suggestions for edits I think you should make to the paper.


Minor comments aside this seems like it's about ready to go. Once the the above changes to the paper are made (and I would suggest you both do a final read through yourselves to ensure it reads the way you'd like), there are a few final archival steps I need you to do:

Please let me know when these steps are complete, they allow us to finalize the metadata that will be associated with the JOSS publication. Once that is done I can recommend that we accept and publish this paper.

zhenwu0728 commented 2 years ago

@editorialbot generate pdf

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

zhenwu0728 commented 2 years ago

@editorialbot generate pdf

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

zhenwu0728 commented 2 years ago

@elbeejay Thanks for these comments! I've incorporated them into the paper. The version tag is v0.5.1. The DOI of the archived version is 10.5281/zenodo.6507001. Please let me know if you have any questions.

elbeejay commented 2 years ago

Hi @zhenwu0728,

Thanks for making those revisions. One minor thing, and I apologize if I was unclear above, please revise the citation in the Statement of need to be: [e.g. lakes, coastal waters, and open ocean, @follows2007emergent; @geider1997dynamic], in the paper.md file, which I believe should end up getting typeset as: (e.g. lakes, coastal waters, and open ocean, Follows et al., 2007; Geider et al. 1997) in the compiled PDF. Let me know if this doesn't work, my intent is for the paper to no longer have the nested parentheses there.