[REVIEW]: Self-Guided Decision Support Groundwater Modelling with Python

editorialbot commented 6 months ago

Submitting author: !--author-handle-->@rhugman@kls2177<!--end-editor-- Reviewers: @codyalbertross, @incsanchezro Archive: 10.5066/P901F9G0 Paper kind: learning module

Status

Status badge code:

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

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

@codyalbertross & @incsanchezro, 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://openjournals.readthedocs.io/en/jose/reviewer_guidelines.html. Any questions/concerns please let @kls2177 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 @codyalbertross

editorialbot commented 6 months ago

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

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 6 months ago

Software report:

github.com/AlDanial/cloc v 1.90  T=1.86 s (236.1 files/s, 245809.7 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
CSV                             22             10              0         196080
Python                         312          21537          54873         127736
Markdown                        44           6809              0          17172
Jupyter Notebook                41              0          23849           4828
TeX                              8             14              0           3224
ReasonML                         1              2              0           1437
TOML                             3             17              4            216
YAML                             7             25             36            136
Unity-Prefab                     1              0              0             66
JSON                             1              0              0             49
-------------------------------------------------------------------------------
SUM:                           440          28414          78762         350944
-------------------------------------------------------------------------------

Commit count by author:

    68  Mike Fienen
    52  jdub
    32  rhugman
    12  briochh
     8  unknown
     2  mnfienen
     1  Brioch Hemmings
     1  J Dub
     1  edesousa-intera

editorialbot commented 6 months ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1016/j.envsoft.2016.08.017 is OK
- 10.5066/P9AUZMI7 is OK
- 10.5066/F76Q1VQV is OK
- 10.1111/gwat.13129 is OK
- 10.5194/hess-20-3739-2016 is OK

MISSING DOIs

- 10.3133/tm7c26 may be a valid DOI for title: Approaches to highly parameterized inversion: PEST...
- 10.1016/j.envsoft.2016.08.017 may be a valid DOI for title: A python framework for environmental model uncerta...
- 10.3389/feart.2020.00050 may be a valid DOI for title: Toward reproducible environmental modeling for dec...
- 10.1016/j.envsoft.2021.105022 may be a valid DOI for title: Towards improved environmental modeling outcomes: ...
- 10.1016/j.envsoft.2022.105316 may be a valid DOI for title: A model-independent tool for evolutionary constrai...
- No DOI given, and none found for title: PEST and Its Utility Support Software
- No DOI given, and none found for title: PEST: a unique computer program for model-independ...
- 10.3389/978-2-8325-3581-3 may be a valid DOI for title: Rapid, Reproducible, and Robust Environmental Mode...
- No DOI given, and none found for title: Where companies go wrong with learning and develop...

INVALID DOIs

- https://doi.org/10.1111/gwat.12413 is INVALID because of 'https://doi.org/' prefix

editorialbot commented 6 months ago

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

editorialbot commented 6 months ago

Paper file info:

📄 Wordcount for paper.md is 3093

✅ The paper includes a Statement of need section

editorialbot commented 6 months ago

License info:

🟡 License found: GNU General Public License v3.0 (Check here for OSI approval)

kls2177 commented 5 months ago

Hi @codyalbertross, @incsanchezro, I am checking-in to see how your reviews are going. Please post your comments in this issue linked to your comments that are directly tied to the resource repo. Here is an example of how you can post your review

incsanchezro commented 5 months ago

I am writing to provide feedback on your paper titled "Self-Guided Decision Support Groundwater Modelling with Python.". Following the JOSE guidelines for reviewers, I would like to confirm that I have no conflicts of interest in reviewing your work. Additionally, I affirm that I have adhered to the review code of conduct of JOSE as of April 2024.

Upon reviewing the paper and associated source code, I find that the overall quality of the learning framework meets essential criteria. I congratulate the authors for making the source code readily available on the specified GitHub repository. The inclusion of a generic plain-text LICENSE file reflects a commitment to open-source principles and provides clarity regarding usage rights. However, I recommend providing explicit identification of the software version as v1.0 to enhance clarity for users.

Furthermore, I appreciate the integrity with which authorship and contributions to the module have been managed. The primary author's significant and visible contributions demonstrate a profound commitment to the project's success and broader educational goals. While some authors may not have been actively engaged in the GitHub repository, their contributions are appropriately acknowledged in the written paper.

Overall, I recommend this paper for publication with attention to the comments listed below. I acknowledge the author's efforts in developing this valuable learning framework and look forward to seeing its continued evolution.

To the authors and JOSE editor, I extend my gratitude for the opportunity to review this work. Please do not hesitate to reach out if you require further clarification or feedback. While I will happily review the reviewed version of this publication.

SPECIFIC COMMENTS AVAILABLE HERE

incsanchezro commented 5 months ago

Dear @kls2177 Please find the reviewer comments for the paper "Self-Guided Decision Support Groundwater Modelling with Python" in the comment above ( >> https://github.com/openjournals/jose-reviews/issues/240#issuecomment-2096875833 ). Please accept my apologies for the delay.

codyalbertross commented 4 months ago

Review checklist for @codyalbertross

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSE 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 JOSE code of conduct.

General checks

[x] Repository: Is the source for this learning module available at the https://github.com/gmdsi/GMDSI_notebooks/?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of a standard license? (OSI-approved for code, Creative Commons for content)
[x] Version: Does the release version given match the repository release?
[x] Authorship: Has the submitting author (@rhugman) made visible contributions to the module? Does the full list of authors seem appropriate and complete?

Documentation

[x] A statement of need: Do the authors clearly state the need for this module and who the target audience is?
[x] Installation instructions: Is there a clearly stated list of dependencies?
[x] Usage: Does the documentation explain how someone would adopt the module, and include examples of how to use it?
[x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support

Pedagogy / Instructional design (Work-in-progress: reviewers, please comment!)

[x] Learning objectives: Does the module make the learning objectives plainly clear? (We don't require explicitly written learning objectives; only that they be evident from content and design.)
[x] Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
[x] Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
[x] Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
[x] Instructional design: Is the instructional design deliberate and apparent? For example, exploit worked-example effects; effective multi-media use; low extraneous cognitive load.

JOSE paper

[x] Authors: Does the paper.md file include a list of authors with their affiliations?
[x] A statement of need: Does the paper clearly state the need for this module and who the target audience is?
[x] Description: Does the paper describe the learning materials and sequence?
[x] Does it describe how it has been used in the classroom or other settings, and how someone might adopt it?
[x] Could someone else teach with this module, given the right expertise?
[x] Does the paper tell the "story" of how the authors came to develop it, or what their expertise is?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

codyalbertross commented 4 months ago

@kls2177

Thank you for your patience with my review.

Self-Guided Decision Support Groundwater Modelling with Python is a valuable contribution and satisfies a need for concise and informed guidance on PEST and pyEMU. I agree with @incsanchezro regarding the organization of the workbook and the effort put forward by the authors to develop and improve GMDSI.

I found that the detail and theoretical background was exceptional and that the workbook followed a logical trajectory that is aligned with a typical workflow.

Overall, I believe that this work is suitable for publication and that the authors seem ready to take feedback from end-users to continuously improve their experience.

rhugman commented 4 months ago

Thank you @incsanchezro and @codyalbertross for your time and effort on the reviews.

We have addressed your comments and updated the repo and paper in the jose-review branch. I will leave direct responses to each of the specific comments.

All the best, -R

kls2177 commented 4 months ago

Hi @incsanchezro, thank you very much for your review. A technical request: can you please add your issues to the groundwater resource repo, not the JOSE repo? Please see the example that I provided above - if you click on the links in this example, you will notice that the links go to the resource repo. Thanks!

rhugman commented 4 months ago

Hi @kls2177,

We have updated the repo in the jose-review branch addressing @incsanchezro and @codyalbertross comments. We are not clear on what the next steps are, can you please let us know what we need to do next?

kls2177 commented 3 months ago

Hi @rhugman,

Thank you for responding to the reviewers feedback. I apologize for the delay. The next step is for your reviewers, @incsanchezro and @codyalbertross to respond to your revisions. I look forward to their feedback. There may be further revisions required.

rhugman commented 1 month ago

Hi @kls2177 , @incsanchezro and @codyalbertross,

Any update on the response to revisions?

Cheers, -R

kls2177 commented 4 weeks ago

Hi @rhugman, sorry for the delay. I will follow-up with the reviewers by email.

kls2177 commented 4 weeks ago

Hi @kls2177,

We have updated the repo in the jose-review branch addressing @incsanchezro and @codyalbertross comments. We are not clear on what the next steps are, can you please let us know what we need to do next?

Hi @rhugman, to speed the process along, can you please provide links to your responses to the comments by reviews in the chat? Thanks!

rhugman commented 4 weeks ago

Hi @kls2177, thanks for expediting this.

We responded to comments by @incsanchezro directly in the issues they raised (linked below):

JOSE Review - comments on "Self-Guided Decision Support Groundwater Modelling with Python " [Documentation section] #244

JOSE Review - comments on "Self-Guided Decision Support Groundwater Modelling with Python " [Pedagogy / Instructional design ] #245

JOSE Review - comments on "Self-Guided Decision Support Groundwater Modelling with Python " [JOSE paper] #246

codyalbertross commented 3 weeks ago

Hi @kls2177, thanks for expediting this.

We responded to comments by @incsanchezro directly in the issues they raised (linked below):

JOSE Review - comments on "Self-Guided Decision Support Groundwater Modelling with Python " [Documentation section] #244

JOSE Review - comments on "Self-Guided Decision Support Groundwater Modelling with Python " [Pedagogy / Instructional design ] #245

JOSE Review - comments on "Self-Guided Decision Support Groundwater Modelling with Python " [JOSE paper] #246

I have reviewed the author's response to comments and have also seen that several tweaks were made in response to a workshop. I think that all of the suggestions have been adequately resolved and recommend the paper for publication.

kls2177 commented 3 weeks ago

Hi @rhugman,

While we wait for any final comments from @incsanchezro, I have a few comments of my own.

The JOSE paper is over the suggested word limit of 1000 words. I encourage the authors to revise and shorten this paper. Some of my suggestions include moving the Resources section and the Contents section to the tutorial website.

Also, I recommend a quick grammatical/spell check of the paper. There are a couple of minor issues.

The learning outcomes for each section in the tutorials need to be more explicit and clearly stated at the outset of each section. This is sometimes the case, but is not consistent throughout. A stylistic option could also be to place the learning outcomes within a "special content blocks" so that they are clearly marked for students.
For each Chapter, I recommend removing the table of contents landing page (as this is visible in the side-bar) and replace with a narrative landing page that provides the big picture context and lays out the connections between the sections within the chapter.
Finally, it would be helpful for students to hyperlink within your tutorial to earlier chapters/sections of the tutorial to help students make the connections between topics.

rhugman commented 1 week ago

Thanks @kls2177,

The JOSE paper is over the suggested word limit of 1000 words. I encourage the authors to revise and shorten this paper. Some of my suggestions include moving the Resources section and the Contents section to the tutorial website. Also, I recommend a quick grammatical/spell check of the paper. There are a couple of minor issues.

As requested,:

The learning outcomes for each section in the tutorials need to be more explicit and clearly stated at the outset of each section. This is sometimes the case, but is not consistent throughout. A stylistic option could also be to place the learning outcomes within a "special content blocks" so that they are clearly marked for students.

Placed learning outcomes in special content block

For each Chapter, I recommend removing the table of contents landing page (as this is visible in the side-bar) and replace with a narrative landing page that provides the big picture context and lays out the connections between the sections within the chapter.

I am not quite clear on what 3. and 4. refer to. Were these in regard to the GitHub Page? That page was very much out of date and has since been taken down. It was never part of the submitted paper. The only "website" that we maintain as part of this project is the git-hub repo.

Finally, it would be helpful for students to hyperlink within your tutorial to earlier chapters/sections of the tutorial to help students make the connections between topics.

Within the notebooks, where relevant we provide links to other specific notebooks.

Please let me know if that addresses your concerns.

Regards, R

kls2177 commented 1 week ago

Thanks @rhugman. The link to the notebooks is not working for me today.

rhugman commented 1 week ago

Hi @kls2177, as I mentioned in the previous post, that website was out of date and not intended as part of this submission. (Thank you for bringing to our attention that it was still live.) Apologies for any confusion this has caused - we missed that that was still there.

I have removed reference to it from the repo's landing page. As is described in the README.md, the tutorials are intended to be cloned/downloaded and run locally. The compute requirements are too large to make it feasible to host up-to-date versions of the notebooks on GitHub.

kls2177 commented 1 week ago

Thanks for the clarification @rhugman. I had been looking at the website.

Thank you for revising the paper. I apologize for this, but I think it would be worth putting the "Content" section back in the paper. It will make the paper longer, but something is lost now that it is removed.

Once this is in place, we can move ahead with publication. Thank you for your patience!!

rhugman commented 1 week ago

Thanks for the clarification @rhugman. I had been looking at the website.

Thank you for revising the paper. I apologize for this, but I think it would be worth putting the "Content" section back in the paper. It will make the paper longer, but something is lost now that it is removed.

Once this is in place, we can move ahead with publication. Thank you for your patience!!

No worries! Moved it back into the paper: here

kls2177 commented 5 days ago

Thanks @rhugman! The next step in the publication process will to make sure that your archive doi is current. I see that you have the following archive. Please be sure that it is up-to-date. Thanks!

rhugman commented 4 days ago

Thanks @rhugman! The next step in the publication process will to make sure that your archive doi is current. I see that you have the following archive. Please be sure that it is up-to-date. Thanks!

Thanks, I confirm that the archive is up to date.

kls2177 commented 2 days ago

@editorialbot set 10.5066/P901F9G0 as archive

editorialbot commented 2 days ago

Done! archive is now 10.5066/P901F9G0

kls2177 commented 2 days ago

@editorialbot generate pdf

editorialbot commented 2 days ago

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

kls2177 commented 2 days ago

@editorialbot check references

editorialbot commented 2 days ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.1016/j.envsoft.2016.08.017 is OK
- 10.5066/P9AUZMI7 is OK
- 10.5066/F76Q1VQV is OK
- 10.1111/gwat.13129 is OK
- 10.5194/hess-20-3739-2016 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: PEST and Its Utility Support Software
- No DOI given, and none found for title: PEST: a unique computer program for model-independ...
- No DOI given, and none found for title: Where companies go wrong with learning and develop...

❌ MISSING DOIs

- 10.3133/tm7c26 may be a valid DOI for title: Approaches to highly parameterized inversion: PEST...
- 10.1016/j.envsoft.2016.08.017 may be a valid DOI for title: A python framework for environmental model uncerta...
- 10.3389/feart.2020.00050 may be a valid DOI for title: Toward reproducible environmental modeling for dec...
- 10.1016/j.envsoft.2021.105022 may be a valid DOI for title: Towards improved environmental modeling outcomes: ...
- 10.1016/j.envsoft.2022.105316 may be a valid DOI for title: A model-independent tool for evolutionary constrai...
- 10.3389/978-2-8325-3581-3 may be a valid DOI for title: Rapid, Reproducible, and Robust Environmental Mode...

❌ INVALID DOIs

- https://doi.org/10.1111/gwat.12413 is INVALID because of 'https://doi.org/' prefix

kls2177 commented 2 days ago

I just updated the branch with the revised paper.md document. I will generate the pdf again.

kls2177 commented 2 days ago

@editorialbot generate pdf

editorialbot commented 2 days ago

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

kls2177 commented 2 days ago

@editorialbot check references

editorialbot commented 2 days ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.3133/tm7C26 is OK
- 10.1016/j.envsoft.2016.08.017 is OK
- 10.5066/P9AUZMI7 is OK
- 10.3389/feart.2020.00050 is OK
- 10.1016/j.envsoft.2021.105022 is OK
- 10.1016/j.envsoft.2022.105316 is OK
- 10.5066/F76Q1VQV is OK
- 10.1111/gwat.12413 is OK
- 10.3389/978-2-8325-3581-3 is OK
- 10.1111/gwat.13129 is OK
- 10.5194/hess-20-3739-2016 is OK
- 10.1109/MCSE.2021.3059263 is OK
- 10.1016/j.envsoft.2013.05.005 is OK
- 10.3133/sir20225046 is OK
- 10.1111/gwat.13107 is OK
- 10.1016/j.agwat.2023.108225 is OK
- 10.1111/j.1745-6584.1988.tb00399.x is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: PEST and Its Utility Support Software
- No DOI given, and none found for title: PEST: a unique computer program for model-independ...
- No DOI given, and none found for title: Where companies go wrong with learning and develop...

❌ MISSING DOIs

- 10.1016/j.envsoft.2016.08.017 may be a valid DOI for title: A python framework for environmental model uncerta...
- 10.3389/feart.2022.904271 may be a valid DOI for title: Decision-Support Groundwater Modelling of Managed ...

❌ INVALID DOIs

- http://dx.doi.org/10.1016/B978-0-08-091638-5.00010-9 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1016/j.envsoft.2024.105952 is INVALID because of 'https://doi.org/' prefix

rhugman commented 2 days ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

❌ MISSING DOIs

- 10.1016/j.envsoft.2016.08.017 may be a valid DOI for title: A python framework for environmental model uncerta...
- 10.3389/feart.2022.904271 may be a valid DOI for title: Decision-Support Groundwater Modelling of Managed ...

❌ INVALID DOIs

- http://dx.doi.org/10.1016/B978-0-08-091638-5.00010-9 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1016/j.envsoft.2024.105952 is INVALID because of 'https://doi.org/' prefix

Addressed here.

kls2177 commented 2 days ago

Hi @rhugman, the generated pdf is 8 pages long, which is much longer than typical JOSE papers. Although I feel the Content section should stay, some revision is required. I have made some suggested edits in a word doc (attached) in an attempt to consolidate and reduce the word count. Please let me know if you feel that these edits still capture the essence of what you intend for the paper.

I felt that the "Statement of Need" and "Story of the Project" contained some repetitive and/or complementary material that could be consolidated. I have also removed the learning outcomes from the paper although I these should still be included in the repository. I have also made a few other smaller edits in an attempt to reduce the word count.

Also, please check the references (see reference check above). Thanks for your patience!

groundwater_paper_suggested_edits.docx

rhugman commented 2 days ago

No worries @kls2177. Thanks for the edits.

Ive added them in here here.

The pdf is still ~6 pages. If you feel it needs to be shortened further, we could remove Fig2 and the paragraph that discusses it...that should gain 1 page...

kls2177 commented 1 day ago

@editorialbot generate pdf

editorialbot commented 1 day ago

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

kls2177 commented 1 day ago

@editorialbot check references

editorialbot commented 1 day ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.3133/tm7C26 is OK
- 10.1016/j.envsoft.2016.08.017 is OK
- 10.1016/j.envsoft.2016.08.017 is OK
- 10.5066/P9AUZMI7 is OK
- 10.3389/feart.2020.00050 is OK
- 10.1016/j.envsoft.2021.105022 is OK
- 10.1016/j.envsoft.2022.105316 is OK
- 10.5066/F76Q1VQV is OK
- 10.1111/gwat.12413 is OK
- 10.1016/B978-0-08-091638-5.00010-9 is OK
- 10.3389/978-2-8325-3581-3 is OK
- 10.1111/gwat.13129 is OK
- 10.5194/hess-20-3739-2016 is OK
- 10.1109/MCSE.2021.3059263 is OK
- 10.1016/j.envsoft.2013.05.005 is OK
- 10.1016/j.envsoft.2024.105952 is OK
- 10.3133/sir20225046 is OK
- 10.1111/gwat.13107 is OK
- 10.3389/feart.2022.904271 is OK
- 10.1016/j.agwat.2023.108225 is OK
- 10.1111/j.1745-6584.1988.tb00399.x is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: PEST and Its Utility Support Software
- No DOI given, and none found for title: PEST: a unique computer program for model-independ...
- No DOI given, and none found for title: Where companies go wrong with learning and develop...

❌ MISSING DOIs

- None

❌ INVALID DOIs

- None

kls2177 commented 1 day ago

@editorialbot set v1.0 as version

editorialbot commented 1 day ago

Done! version is now v1.0

kls2177 commented 1 day ago

@editorialbot recommend-accept

editorialbot commented 1 day ago

Attempting dry run of processing paper acceptance...

openjournals / jose-reviews