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

[whedon]

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

• 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

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• 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.

• Version: Does the release version given match the GitHub release (2.05)?
• 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

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• 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

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• 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

• 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• 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]

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 🎉.

⭐ Important ⭐

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:

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

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

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

@whedon commands

[pboesu]

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

1. There are conflicting licenses in the toolbox (MIT vs GPL3). Please use a single license: [JOSS review] Conflicting licenses randlab/hytool#1
2. Missing DOI in the paper. I've opened a pull request to add a DOI for one of the references cited in the paper. [JOSS review] added DOI for Stehfest 1970 reference randlab/hytool#2
3. 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. [JOSS review] lack of unit tests randlab/hytool#3
4. Lack of community guidelines. [JOSS review] Lack of community guidelines randlab/hytool#4

[philipperenard]

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]

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]

@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]

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

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

[kyleniemeyer]

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]

Dear @kyleniemeyer,

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

Here is what I did:

1. Add the same figure as in the wiki
2. Add a few sentences in the 4th paragraph explaining the figure.
3. Corrected "allowing to identify aquifer types" -> "used to identify aquifer types..."
4. Add a sentence explaining in the first paragraph whatis a hydraulic test
5. Corrected "Hytool is a matlab toolbox providing" -> "Hytool is a Matlab toolbox that provides"
6. Corrected "for the interpretation of hydraulic tests" -> "for interpreting hydraulic tests"
7. Corrected "allows adding easily new solutions" -> "allows a user to easily add new solutions"
8. Corrected "internal help within matlab" -> "internal help within Matlab"
9. 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]

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]

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]

@philipperenard ok, the edits definitely cleared that up.

@arfon this submission is now accepted!

[kyleniemeyer]

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

[philipperenard]

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

[kyleniemeyer]

@whedon set 10.5281/zenodo.1045538 as archive

[whedon]

OK. 10.5281/zenodo.1045538 is the archive.

[kyleniemeyer]

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

[arfon]

@philipperenard - please could you merge this PR: randlab/hytool#5

[arfon]

@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]

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.