[REVIEW]: PyFlowline a mesh independent river network generator for hydrologic models about joss-reviews HOT 12 OPEN

Hi @smchartrand, @andres-patrignani,
I just want to check if you have any questions regarding the review process. As a start, each of you should run @editorialbot generate my checklist to get a checklist of the individual tasks a JOSS review requires. Tasks can then be ticked off one by one. You can find additional information in the guidelines. Also, feel free to tag me here if you have any additional questions.

Cheers!

from joss-reviews.

from joss-reviews.

Thank you very much for your review @smchartrand.
@changliao1025 please feel free to already respond to the issues and comments, while @andres-patrignani is doing their review.

@andres-patrignani could you please create your checklist with @editorialbot generate my checklist? That would be awesome.

from joss-reviews.

@smchartrand Thank you for your comments, which will undoubtedly help us to provide better software.
We will address your concerns soon about some details in the document and example code.

Below are a few responses to your concerns:

• pyflowline was developed with visualization as an optional feature, see the setup file:

    extras_require={
       'visualization': ['cython', 'matplotlib', 'cartopy>=0.21.0']
    }
  

  This decision is made to reduce the model dependency. Users can run the model with only core dependency. But in the
  notebook, it is desired to have the visualization. We will update the documentation to clarify that, and users can use
  whatever methods for visualization, including QGIS, etc. And we recommend the Conda virtual environment for
  applications.

• We will add some discussion comparing our model with others. Thanks for the suggestions for the other two similar tools. In short, our tool aims to provide the conceptual river networks for spatially-distributed hydrology models. Since these hydrologic models use the meshes to represent land surface, our model closes the gap by providing a method to define the river networks on top of meshes. This is different from vector line features.

We will address the remaining comments in the coming weeks.
Thank you.

from joss-reviews.

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

from joss-reviews.

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

OK DOIs

- 10.5281/zenodo.5558988 is OK
- 10.5194/hess-26-5473-2022 is OK
- 10.1029/2022MS003089 is OK

MISSING DOIs

- None

INVALID DOIs

- None

from joss-reviews.

Software report:

github.com/AlDanial/cloc v 1.88  T=1.33 s (99.6 files/s, 337480.5 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
JSON                            22              2              0         420104
Python                          69           1982           1794           8325
C++                              1            331           1115           6043
C                                1            328           1093           5936
reStructuredText                19            309             65            683
Cython                           2            100             63            262
DOS Batch                        2             37              2            238
make                             2             49              6            209
Markdown                         6             87              0            109
YAML                             5             15             28             77
Jupyter Notebook                 1              0            978             67
TeX                              1              3              0             35
INI                              1              4              0             13
TOML                             1              0              0              6
-------------------------------------------------------------------------------
SUM:                           133           3247           5144         442107
-------------------------------------------------------------------------------


gitinspector failed to run statistical information for the repository

from joss-reviews.

Wordcount for paper.md is 743

from joss-reviews.

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

from joss-reviews.

Review checklist for @smchartrand

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

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 https://github.com/changliao1025/pyflowline?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@changliao1025) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

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 functionality of the software can be verified?
• 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

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

from joss-reviews.

Hi everyone,
I'm glad to see that the review process is in full swing now and the first issues are being created. @andres-patrignani if you could run editorialbot generate my checklist as well that would be awesome. It makes it easier for me to track the process.

from joss-reviews.

I want to start by congratulating @changliao1025 (and Matt Cooper) for their submission. The software authors have tackled a long standing problem in hydrologic modelling, and the outcome is impressive. Thanks for the opportunity to review your submission, and get to explore the code in more detail. I hope my comments are helpful.

Most of my comments below address either (a) challenges with using the .ipynb and .py codes provided in the repository for the Susquehanna example to generate results, or (b) setting the context of the code with respect to existing platforms. All the comments are relatively minor, or moderate in scope, and should be easily addressed. I organized my comments under the review checklist headers to simplify things.

General Checks:

1. Repository: good.
2. License: I opened an issue in the home repository regarding the License.
3. Contribution and authorship, scholarly effort and data sharing: good.
4. Reproducibility - The primary challenge I encountered was using the .ipynb file [in the notebooks directory] to generate results with pyflowline. The challenges are summarized in the following.

• Jupyter Notebook: I could not successfully plot the flow network using oPyflowline.plot(sFilename_in = 'filter_flowline.png', sVariable_in = 'flowline_filter' ). I did successfully plot the flow network using geopandas (I added this to the notebook), and using QGIS. After lots of digging, I think the issue lies in the dependencies. The notebook requires cartopy>=0.21.0 [based on setup.py]; I run Ubuntu 22.04 LTS and python 3.7.10 [which is the maintained version for this OS distribution], with cartopy 0.18.0 as the standard install version. After many attempts and breaking my "apt", I attempted to use a virtual python environment and then decided to stop as the effort in to address the plotting issue was too large. Perhaps the authors can think about a different way to setup the notebook visualization, or make the required dependencies more clear without having to dig through the software repository to piece things together. Geopandas was easy to implement in this case (geopandas image of the raw network geometry copied and pasted here from mpas_example notebook), although some of the formatting may be lost or more difficult to implement.
  

• I was able to successfully execute run_simulation_mpas.py in the examples/Susquehanna directory. However, the saved image of the filter_flowline.png has the same issues as decribed above for plotting in the Jupyter Notebook - the file saves but the network is not illustrated in the image file (saved image file shown at the bottom of this review). When I load the corresponding .geojson file into QGIS the network shows up just fine. So, I suspect the same dependency issues described for the Jupyter Notebook are affecting the reproducibility with the .py implementation.

5. Human and animal research is n/a.

Functionality:

1. Installation: good.
2. Functionality - I was able to follow the Quickstart and the Installation instructions separately to successfully install pyflowline. The "Functionality" needs some attention based on my comments above regarding use of the provided Jupyter Notebook mpas_example.ipynb [note: in the Quickstart the notebook is referred to by mpas_notebook.ipynb].
3. Performance: good - I found no performance issues and the example calculations for the Susquehanna ran in approximately 65 seconds on my laptop [ThinkPad X1 Carbon Intel i7 with 32 GB ram].

Documentation:

1. Statement of need: good.
2. Installation instructions are good, but a clear list of dependencies is missing. There are three sources of dependencies and all three provide a different set: requirements_dev.txt [root directory], setup.py [root directory], and requirements.txt [docs directory]. It may make sense to have a requirements.txt file in the root directory that can be linked to installation so the trace is more clear OR clearly state the dependencies in the README on the git home page? The key is to have the dependencies clearly highlighted in one location.
3. Example usage: good - Authors provide a real-wrold example for the Susquehanna River.
4. Fucntionality documentation: good.
5. Automated tests are lacking, but use of the provided python script and Jupyter Notebook with the example offers a manual test of the software.
6. Community guidelines are clearly addressed in the License.

Software Paper:

1. Summary - A clear statement of how the software benefits non-specialist audiences would be helpful.
2. Statement of need - More clear statement of who the intended or target audience is, would be helfpul. In the relating the current software to other and existing tools, the authors discuss just a few examples. I understand the contribution is a first of its kind, but it might be useful to expand this discussion a bit more. Is their merit in mentioning River Network Toolkit (http://rivtoolkit.com/)? Or RivGraph (https://joss.theoj.org/papers/10.21105/joss.02952)?
3. State of the field - Please elaborate a bit more on what existing packages can do, and why this is not enough (i.e. how pyflowline fills this gap). See comments above under Statement of Need.
4. References - See comment above under Statement of Need.

from joss-reviews.