[REVIEW]: Hytool: an open source matlab toolbox for the interpretation of hydraulic tests using analytical solutions

whedon commented 6 years ago

Submitting author: @philipperenard (Philippe Renard) Repository: https://github.com/UniNE-CHYN/hytool Version: 2.05 Editor: @kyleniemeyer Reviewer: @pboesu Archive: 10.5281/zenodo.1045538

Status

Status badge code:

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

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 questions

@pboesu, please carry out your review in this issue by updating the checklist below (please make sure you're logged in to GitHub). The reviewer guidelines are available here: http://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @kyleniemeyer know.

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?

The repository contains a MIT license at the top level, but a GNU GPL v3 in the package documentation. Please harmonize the license terms.

[x] Version: Does the release version given match the GitHub release (2.05)?
[x] Authorship: Has the submitting author (@philipperenard) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

The git repository consists of a single large commit of the entire software toolbox, and then some smaller commits related to the JOSS submission, so it is not possible to see how the code base grew. However, I do not see any reason to doubt that the software was created under the lead of @philipperenard. The Contents.m file lists 'Philippe Renard and Co.' as authors, the 'and Co.' are explicitely listed in the Acknowledgments section of the toolbox documentation.

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?

There are no automated tests as far as I can see, and as far as I can see no use is made of MATLABS testing framework

[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 There are no such guidelines in the MATLAB documentation or the github readme or wiki.

There are no such guidelines.

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)?

DOI is missing missing for one reference.

whedon commented 6 years ago

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks for JOSS. @pboesu 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 as reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all JOSS 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

pboesu commented 6 years ago

Hello @kyleniemeyer and @philipperenard,

thank you both for your patience, and my apologies again for delaying this review.

I have now reviewed the paper and code. This is a very well documented toolbox, and all of the example cases are detailed and work.

I have highlighted a few minor issues, but these should be easy to address

There are conflicting licenses in the toolbox (MIT vs GPL3). Please use a single license: https://github.com/UniNE-CHYN/hytool/issues/1
Missing DOI in the paper. I've opened a pull request to add a DOI for one of the references cited in the paper. https://github.com/UniNE-CHYN/hytool/pull/2
There are no unit tests. However, I am not familiar enough with MATLAB toolboxes or the MATLAB community to know whether or not this is standard practice, so I am neutral about whether this would be a requirement for publication in JOSS, and I would like to defer to @kyleniemeyer for further guidance on this. https://github.com/UniNE-CHYN/hytool/issues/3
Lack of community guidelines. https://github.com/UniNE-CHYN/hytool/issues/4

philipperenard commented 6 years ago

Thank you very much for the evaluation and suggestions. I adressed alll the points mentioned in the review and replied directly on the github links.

The only thing that I have not done yet is the to add unit tests. As I wrote in my reply, I will not be able to do them rapidly but I agree with the reviewer that they should be added.

pboesu commented 6 years ago

Thank you @philipperenard for the revisions!

Automated test would be great for future development, but given the very detailed worked examples, I think the review guidelines (which state that "manual steps described so that the function of the software can be verified" are sufficient) are satisfied.

@kyleniemeyer I am satisfied with the revisions and recommend the acceptance of this submission.

kyleniemeyer commented 6 years ago

@pboesu thanks for your review!

To both of you, JOSS does not require an automated test suite, but it is definitely encouraged in general as a best practice. However, we do want sufficient manual tests/examples to verify the functionality, and it sounds like that is satisfied.

philipperenard commented 6 years ago

Thank you @pboesu and @kyleniemeyer for the review and comments !

Is there anything else that you want me to do now ?

kyleniemeyer commented 6 years ago

Hi @philipperenard, I'm just taking a look at the actual paper now.

I notice that you have a great figure in your wiki that demonstrates a use case for the software. Could you incorporate that, along with an explanation (similar to what is also in the wiki) into the paper? I think that would help strengthen the paper, and make it more clear how the software can be used.

Also, a few additional minor comments/suggestions:

"allowing to identify aquifer types" -> "used to identify aquifer types..."
Could you perhaps add a sentence after the first that explains what hydraulic tests are, to a general reader?
"Hytool is a matlab toolbox providing" -> "Hytool is a Matlab toolbox that provides"
"for the interpretation of hydraulic tests" -> "for interpreting hydraulic tests"
"allows adding easily new solutions" -> "allows a user to easily add new solutions"
"internal help within matlab" -> "internal help within Matlab"
regarding the "several research projects", could you add some detail on how it was used? That would help people further see the use cases for their own work.

philipperenard commented 6 years ago

Dear @kyleniemeyer,

Thank you for your suggestions. They are very much appreciated.

Here is what I did:

Add the same figure as in the wiki
Add a few sentences in the 4th paragraph explaining the figure.
Corrected "allowing to identify aquifer types" -> "used to identify aquifer types..."
Add a sentence explaining in the first paragraph whatis a hydraulic test
Corrected "Hytool is a matlab toolbox providing" -> "Hytool is a Matlab toolbox that provides"
Corrected "for the interpretation of hydraulic tests" -> "for interpreting hydraulic tests"
Corrected "allows adding easily new solutions" -> "allows a user to easily add new solutions"
Corrected "internal help within matlab" -> "internal help within Matlab"
The last paragraph has been divided in two parts to split the text related to the help and the description of the exemples. In this last part, I added a few references and some details about "several research projects" to indicate briefly in which contect hytool was used.

kyleniemeyer commented 6 years ago

Thanks @philipperenard, a caught a few other things (or new one):

"They consist in" -> "They consist of"
"Many types of tests involving" -> "Many types of tests involve" (unless I misunderstand your meaning)

Once those are fixed, the submission will be ready to accept!

philipperenard commented 6 years ago

Thanks @kyleniemeyer !

I corrected the first point.

For the second, the sentence is a bit complicated, but the meaning was "Many types of tests .... had been developped...". I added some comas to clarify the structure of the sentence. In my mind, "involving...." is a parenthetic clause. I am not 100% sure that what I did is grammaticaly correct. I could try to split the sentence.

kyleniemeyer commented 6 years ago

@philipperenard ok, the edits definitely cleared that up.

@arfon this submission is now accepted!

kyleniemeyer commented 6 years ago

@philipperenard can you archive the final version and share the DOI here?

philipperenard commented 6 years ago

Thank you @kyleniemeyer. Here is the doi: 10.5281/zenodo.1045538

kyleniemeyer commented 6 years ago

@whedon set 10.5281/zenodo.1045538 as archive

whedon commented 6 years ago

OK. 10.5281/zenodo.1045538 is the archive.

kyleniemeyer commented 6 years ago

alright @arfon, now it's good to go.

arfon commented 6 years ago

@philipperenard - please could you merge this PR: https://github.com/UniNE-CHYN/hytool/pull/5

arfon commented 6 years ago

@pboesu - many thanks for your review here and to @kyleniemeyer for editing this submission ✨

@philipperenard - your paper is now accepted into JOSS and your DOI is https://doi.org/10.21105/joss.00441 ⚡️ 🚀 💥

philipperenard commented 6 years ago

Thank you all @pboesu , @kyleniemeyer and @arfon for all your work and advices.

What you do with this journal is fantastic ! I have been editor of a traditional journal, and the procedures and way you manage this journal should inspire all of us to move into an open framework.

openjournals / joss-reviews