[REVIEW]: PyFlowline a mesh independent river network generator for hydrologic models

[editorialbot]

Submitting author: !--author-handle-->@changliao1025<!--end-author-handle-- (Chang Liao) Repository: https://github.com/changliao1025/pyflowline Branch with paper.md (empty if default branch): main Version: v0.3.4 Editor: !--editor-->@observingClouds<!--end-editor-- Reviewers: @smchartrand, @andres-patrignani Archive: 10.5281/zenodo.10076553

Status

Status badge code:

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

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

@smchartrand & @andres-patrignani, 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 @observingClouds 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 @smchartrand

📝 Checklist for @andres-patrignani

[editorialbot]

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]

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

[editorialbot]

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

[editorialbot]

Wordcount for paper.md is 743

[editorialbot]

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

[observingClouds]

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!

[smchartrand]

Review checklist for @smchartrand

Conflict of interest

• [x] 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

• [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 https://github.com/changliao1025/pyflowline?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] 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?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• [x] 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.
• [x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• [x] 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

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

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] 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?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] 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?

[observingClouds]

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.

[smchartrand]

Hi Hauke,

I should have my review wrapped up in the next day or two. Thanks for your patience.

best,

-Shawn

---

From: Hauke Schulz @.***> Sent: May 31, 2023 10:04:26 AM To: openjournals/joss-reviews Cc: Shawn Chartrand; Mention Subject: Re: [openjournals/joss-reviews] [REVIEW]: PyFlowline a mesh independent river network generator for hydrologic models (Issue #5446)

Hi everyone, I'm glad to see that the review process is in full swing now and the first issues are being created. @andres-patrignanihttps://github.com/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.

— Reply to this email directly, view it on GitHubhttps://github.com/openjournals/joss-reviews/issues/5446#issuecomment-1570570186, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AE7I77S6R5TLYFP5OFQ6Y6TXI5YOPANCNFSM6AAAAAAXXBP3F4. You are receiving this because you were mentioned.Message ID: @.***>

[smchartrand]

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.

[observingClouds]

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.

[changliao1025]

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

[changliao1025]

Hi, @smchartrand , Thank you for taking the time to write a review of our work. I appreciate your feedback. Below is the full response to your comments. Thank you for reviewing our submission and recognizing our modeling tool. PyFlowline was developed to close several gaps in hydrologic modeling. For example, although it is designed to run at regional and global scales using any mesh type, many modelers may be more interested in the watershed scale using structured meshes. To this extent, most existing applications can be viewed as a special case in PyFlowline, and PyFlowline provides an opportunity to expand existing applications to other domains and meshes.

General Checks reply:

• Thanks for the comment.

• There was a format issue in our original license file. It has now been resolved. The current license is BSD-3-Clause license.

• Thanks for the comment.

• We understand that there needs to be some clarification regarding the visualization component of the workflow. We have improved the visualization component in both the source code and documentation.

1. First, we revised the visualization class and function completely. Because PyFlowline is a core component in HexWatershed and both models share similar visualization patterns (point, polyline, polygon, and mixed), we merged all the visualization feature into an external module within PyFlowline. This module is largely based on another Python package PyEarth, developed by @chango1025. We plan to add PyEarth as a dependency package.

2. Although visualization is an important component in PyFlowline, it is not a required step to run the model. Besides, our choice of using GeoJSON as the main data I/O format is to ease the visualization task as many tools can visualize GeoJSON. Given the complexity of structured/unstructured datasets that contain point/polyline/polygon, we list the visualization feature as experimental, so users should expect undesired behavior.

3. We added Geopandas as another option in the notebook so users can easily switch to Geopandas for a quick fix.

4. Indeed, it is highly possible that the cartopy installation may affect the visualization. As discussed above, all the vector objects in PyFlowline are plotted using a geodetic framework. If some of the spatial reference information is missing, the vector objects may not be plotted correctly.

Functionality reply:

• Thanks for the comment.

• We updated the documentation, so there are consistent now.

• Susquehanna River basin is average size watershed with a moderate amount of mesh cells. If running with a large domain with more than 10k mesh cells and 100+ river channels, the cython feature may be used to improve the performance. Besides, our workflow can be run using a SLURM job on a high-performance computer to obtain the best performance.

Documentation reply:

• Thanks for the comment.

• We update the readme file to explicitly list the dependency. We also specifically separate the optional dependency. The readthedocs documentation is also updated to maintain consistency.

• Thanks for the comment.

• Thanks for the comment.

• Thanks for the comment. In most cases, our PyFlowline model should be run as a whole workflow. Running individual steps may not be feasible because the model requires all the objects to be accessible during simulation. In the future, we plan to add the checkpoint feature so the model can resume at certain points, which may support more unit test capability.

• Thanks for the comment.

Software Paper reply:

• Thanks for the comment. We revised the summary to highlight that the model output from our package can be used in general hydrologic models, including With PyFlowline, hydrologic modelers can generate conceptual river networks at various spatial resolutions for both structured and unstructured computational meshes. The generated river network datasets can be used by hydrologic models across scales.

• Thanks for the comment. We added some background related to the existing vector-based river network method and explained why we developed this new model. We also cited related references. For hydrologic modelers, river networks are a key input for hydrologic models. While some hydrologic models accept vector-based river networks [@Schwenk:2021], others only accept mesh cell-based, which require a generation method from the vector-based river network. Currently, generating a mesh cell-based river network from a given vector-based river network and arbitrary computational mesh is a major challenge. Existing methods are typically limited to structured rectangular meshes, such as 30m x 30m cartesian grids for high-resolution watershed-scale modeling or 0.5 degree x 0.5 degree geographic grids for global climate modeling.

• Thanks for the comment. We provided details of several different methods:

Existing river network representation methods often fall into these three categories:

1. Vector-based, hydrologic models that use this method cannot couple river and land because there is no one-to-one mapping [@Schwenk:2021];
2. High-resolution DEM-based, only supports structured rectangle grids (e.g., 30m x 30m ) at high spatial resolutions [@Esri:2011];
3. Upscaling-based, only supports structured geographic grids (e.g., 0.5 degree x 0.5 degree) at coarse resolutions [@Wu:2012]. This method often cannot provide global coverage, including Greenland and the Antarctic.

PyFlowline is the only modeling software that provides these unique features:

1. It can generate river networks on unstructured meshes;
2. It uses topological relationships to capture river networks precisely;
3. It can be applied at both high and coarse resolutions;
4. It can provide global coverage, including Greenland and the Antarctic.

Thank you.

[andres-patrignani]

Review checklist for @andres-patrignani

Conflict of interest

• [x] 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

• [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 https://github.com/changliao1025/pyflowline?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] 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?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• [x] 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.
• [x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• [x] 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

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

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] 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?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] 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?

[andres-patrignani]

General checks

1. Repository: Good
2. License: License is available and easy to find.
3. Contribution and authorship: Author has made substantial contribution to the project repository. Paper authors re appropriate and complete.

Functionality

1. Installation: Does installation proceed as outlined in the documentation? Yes, but it may be good to indicate that in some cases creating a new conda environment is necessary. It seems to me that most users having already a working conda environment will not attempt to do this.
2. Functionality: Good
3. Performance: I did not have any performance issue.

Documentation

1. Overall the documentation is extensive with tables, figures, an “Overview” section stating the need for the package, and additional detailed information about how to use and get started with the package. I do have some comments to improve the language, which sometimes can lead to unclear statements that may result confusing to users. Below are some suggestions for improvement:

• Consider adding the URL to the documentation page in both the “About” section of the repository (so that the link appears below “A mesh independent river network generator for hydrologic models”)

• Consider moving the “Quickstart” section in the Readme file to the top, so that people can easily find and access the documentation page.

• Consider the following re-worded sentences: “River networks are landscape features typically represented using vector layers. However, most hydrologic models rely on regular grids to discretize the spatial domain and cannot directly ingest vector features into the model. As a result, hydrologic models usually implement a so-called stream-burning process to convert the vector-based river network into a mesh-based river network. PyFlowline solves this issue by using a mesh-independent approach that intersects the vector river network and mesh to reconstruct the conceptual river network.”

• The following sentence is offers little detail about limitations: “and there are also some other limitations”. Can you add one or a couple of other specific limitations?

• Consider adding the target audience and coding level required to install and use the package. I assume the library is aimed at hydrologists, geographers, urban planners, etc. In its current format I found the library a bit hard to get started for people that are just getting started.

• There is a typo in the main Readme file when listing dependency packages. Please, change matplotlin for matplotlib

• The caption of Figure 1 in the paper (which also appears in the “Data Model” section of the online documentation) could benefit from a longer caption to better describe the connection between the OOP approach, vertex letters, and variables listed in the boxes. The current figure is fine for people with background in hydrology and computational geometry, but I'm not sure if the figure is clear to a wider audience.

• In section 4.3.1. it remains unclear whether there are multiple input files or just one. The first and second sentences contradict. Should it say: “Within these configuration files…”?

• There is an empty Readme file in /pyflowline-main/data/susquehanna/readme.md. Not sure if this was intentional.

2. Installation instructions: Instructions and dependencies are clearly stated. However, I had a hard time trying to install the package and making it work. Installation was resolved by creating a separate conda environment and then installing the package.

conda create --name pyflowline_test 
conda install -c conda-forge pyflowline

3. Example usage: Authors provided a real-world example, but editing all the file paths for the user’s local installation seems overwhelming for a simple example. It would be nice to have a simpler way to set the paths and run the example from the Jupyter Notebook, since this is probably the first thing that users unfamiliar with the package will try to do to become more familiar with it.

4. Functionality documentation: Great

5. Automated tests: Good

6. Community guidelines: There are guidelines pointing users to the FAQ page, developers contact information, and encouragement to submit a GitHub issue if something did not work. I personally made use of the latter option and the authors responded promptly with clear instructions.

Software paper

1. Summary: There is a clear description of the high-level functionality of the library. It may be good to provide a definition for “structured” and “unstructured” meshes in layman’s terms for non-technical readers. Perhaps the authors can add a figure illustrating both of these concepts and the perils of using structured rectangular meshes to represent river and streamflow networks. I wonder if the authors can explain some of these concepts using the concepts of vector and raster layers, which I think most people with basic training in geographic information systems will be able to understand and follow. I like the addition of a glossary in the online documentation, and it may be good to add the concepts of structured and unstructured meshes to that section.

2. A statement of need: The statement of need is clear and well-written.

3. State of the field: This seems to be the only software that can generate river networks on structured and unstructured meshes (so if I understand this correctly, the package is basically mesh-independent).

4. Quality of writing: The paper well written. The main website needs some clarification (see my comments above)

5. References: The list of references is complete.

   • The reference by Engwirda, D., & Liao is missing the year and the title is all in upper case letters. Please, adopt a consistent style across all references. According to Zenodo the citation should be: Engwirda, Darren, & Liao, Chang. (2021, October 9). 'Unified' Laguerre-Power Meshes for Coupled Earth System Modelling. 29th International Meshing Roundtable (IMR), Virtual Conference. https://doi.org/10.5281/zenodo.5558988
   • The reference by Liao et al. is missing the year. It seems that this article was published in 2023 according go the DOI.

[observingClouds]

Thank you @andres-patrignani for your review. We really appreciate it.

@changliao1025 I see that you have addressed already most, if not all, of @smchartrand comments. That's great! Could you please go now through @andres-patrignani review and let us know when you addressed all comments? We should then be relatively quick in moving forward.

Cheers!

[changliao1025]

Hi, @andres-patrignani , Thank you for taking the time to write a review of our work. I appreciate your feedback. Below is the full response to your comments.

General checks reply

• Thanks for the comment.
• Thanks for the comment.
• Thanks for the comment.

Functionality reply

• Thanks for the comment. Indeed creating a new conda environment is a better choice to avoid package conflict. We revised the document for this section.
• Thanks for the comment.
• Thanks for the comment.

Documentation reply

• Thanks for the comment. We address your comments one by one below.
• Thanks for the comment. We added the readthedocs link under the About section.
• Thanks for the comment. We moved the quickstart under the title.
• Thanks for the suggestion. We accepted this suggestion in the readthedocs.
• Thanks for the suggestion. We added an example

For example, existing stream-burning methods always treat the vector river networks as a binary mask and cannot describe the topology near river confluences and meanders.

• Thanks for the suggestion. Indeed, PyFlowline is a tool/model for computational hydrologists. We added some descriptions in the document to explain some required skillsets to use this tool. We added into the quickstart

Installing and running PyFlowline requires some basic knowledge of the Python ecosystem. Besides, configuring a PyFlowline simulation requires some knowledge of Geographic Information System (GIS) and computational hydrology.

• We fixed the typo.
• Thanks for the comment. We added more details in both figures to explain the graphics.
• Thanks for the comment. The model uses two configuration files. We fixed this error and updated the document. It was designed to provide a basic description of the data folder. We added some content to it.
• That is a good suggestion. We update that in the document.
• Thanks for the comment on the example. Indeed, setting up the model requires some effort. This is due to two reasons (1) the model was designed to run across scales, so there is a file structure; (2) we try to simplify the configuration files so they contain both paths and parameters; (3) PyFlowline is a core component in HexWatershed, and the configuration is designed to fit both models. As a result, some keywords are not used by PyFlowline. We might improve this part in future development.
• Thanks for the comment.
• Thanks for the comment.
• Thanks for the comment.

Software paper reply

• Thanks for the comment. We add a sentence in the paper to define both terms.

In PyFlowline, we define structured meshes (e.g., lat-lon, raster files with projections, and hexagon) as those with fixed cell sizes and shapes and unstructured meshes as those with variable cell sizes and shapes.

We also add them to the glossary.

• Thanks for the comment.
• Thanks for the comment.
• Thanks for the comment.
• Thanks for the comment. We fixed the reference issue.

[changliao1025]

I want to add that we recently dropped the 'shapely' dependency after we found alternative GDAL APIs.

[changliao1025]

Merged additional edit from coauthor @mgcooper.

[observingClouds]

Thank you for your update @changliao1025. I will have a look at this later today or tomorrow and will make sure all comments are addressed. Potentially I'll ask the reviewers to confirm that the changes are to their satisfaction.

[observingClouds]

@editorialbot generate pdf

[editorialbot]

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

[observingClouds]

Dear @changliao1025, I went through the reviews and responses and found that a few issues remain, some of which seem already addressed but not closed:

• https://github.com/changliao1025/pyflowline/issues/165 (seems addressed with changes in the documentation)
• https://github.com/changliao1025/pyflowline/issues/164 (still needs to be addressed, examples should work more straight forward; example files like these could be also uploaded to an external permanent storage like zenodo if the files are too big for GitHub or it should be mentioned explicitly if some of them are not used by pyflowline at all to reduce potential confusion; paths that point to files within the GitHub repository could be make relative paths in e.g. the notebook to allow direct execution of the example notebook)
• https://github.com/changliao1025/pyflowline/issues/137 (seems to be addressed)
• https://github.com/changliao1025/pyflowline/issues/136 (seems to be addressed)

  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.

might not yet be addressed.

Please close those issues that have already been addressed.

The execution of the example notebook was most challenging for the reviewers especially because some results could only be reproduced by writing additional code, e.g. by using geopandas to plot and evaluate the results. Because the plotting is a substantial part of the evaluation of this software package it is crucial to make this functionality work out of the box (e.g. by making data paths relative to the notebooks location). I would therefore like you and your co-authors to address these outstanding comments, before I kindly ask @smchartrand and @andres-patrignani to check if all the comments have been addressed appropriately and especially check if the example notebook is easy to follow.

Thank you.

[changliao1025]

@observingClouds We have closed the mentioned issues as they are resolved. Meanwhile, we are improving the file I/O part as it does create some confusion right now.

[observingClouds]

Thanks @changliao1025 for the update. Please let us know when you have improved the I/O part.

[changliao1025]

Hi,  @observingClouds , sorry for the late updates. We recently made many upgrades to the pyflowline model, including the spatial index algorithm, to speed up the algorithm.

As for the I/O part, we added two additional functions (see example in the notebook), to set and change the model parameters. These improvements are designed to ease how users interact with the model parameters. With these two functions, the users can change the parameters without directly editing the JSON files.

Besides, we simplify the visualization part using GeoPandas. The notebook is only intended to serve as an illustration of the workflow. Due to the computational nature of the model, it is recommended to use the model in the Python environment.

[observingClouds]

Hi @changliao1025,

Thank you very much for the update.

Cheers, Hauke

[observingClouds]

Dear @smchartrand, @andres-patrignani,

Could you please have a last look at this submission and check if your comments have been sufficiently addressed? In response to both of your earlier comments @changliao1025 and his colleagues have now improved the I/O interface. Please have a particular look at this and confirm if everything is to your satisfaction.

Thank you! Hauke

[smchartrand]

Hi All,

I will fit this into my schedule next week.

thanks,

-Shawn

---

From: Hauke Schulz @.***> Sent: September 30, 2023 9:59:57 PM To: openjournals/joss-reviews Cc: Shawn Chartrand; Mention Subject: Re: [openjournals/joss-reviews] [REVIEW]: PyFlowline a mesh independent river network generator for hydrologic models (Issue #5446)

Dear @smchartrandhttps://github.com/smchartrand, @andres-patrignanihttps://github.com/andres-patrignani,

Could you please have a last look at this submission and check if your comments have been sufficiently addressed? In response to both of your earlier comments @changliao1025https://github.com/changliao1025 and his colleagues have now improved the I/O interface. Please have a particular look at this and confirm if everything is to your satisfaction.

Thank you! Hauke

— Reply to this email directly, view it on GitHubhttps://github.com/openjournals/joss-reviews/issues/5446#issuecomment-1741955688, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AE7I77QUDLALE44DOQP2CSLX5DXZXANCNFSM6AAAAAAXXBP3F4. You are receiving this because you were mentioned.Message ID: @.***>

[andres-patrignani]

I want to thank the authors for the extensive work to improve the pyflowline package. I was able to successfully:

• re-install the pyflowline package using the provided step by step guidelines in the documentation
• run the new Jupyter Notebook from top to bottom for the example channel network and mesh

Features that I would like to see implemented in this or future versions (I leave this up to the editor and other reviewers):

• I was unable to find detailed guidelines on how users can create/use their own files for creating channel networks and meshes. For instance, if I want to find the channel network for a watershed in my area, what information and files do I need? The example seems to be using a NetCDF file, but is unclear how to get similar files for a different area. If I miss this part in the documentation, please let me know.

Overall I think that the code and the manuscript are in good shape and can be accepted.

Some additional comments for future improvement beyond JOSS:

• It may make more sense to use booleans (True and False) for the "iFlag" variables rather than "1" and "0". This is more of a semantic preference than a technical aspect.
• In the example notebook, consider using a coarse mesh for faster mesh generation (new users may wonder why it takes so long to run some lines). Some cells took several minutes to run.
• The notebook example is still a bit too verbose and will probably benefit from some additional Markdown to create sections and add some notes on what some of the input parameters mean. Perhaps the authors can gradually improve this part as they provide assistance to new users.
• Building a small library of simple examples could be a great resource for new users aiming at using this tool for their own applications.

I hope that my comments have been useful and I commend the authors for creating this library.

Andres

[changliao1025]

@andres-patrignani Thank you for the thoughtful comments, which helped us a lot in improving our package.

Here are some quick responses to your questions:

Indeed, the mesh generation process, especially unstructured meshes such as the MPAS mesh, has various technical challenges. Currently, pyflowline has built-in support to generate structured meshes, see reference in JAMES paper. But it does not have built-in unstructured mesh generators. Instead, it can read the outputs from these unstructured mesh generators, such as JIGSAW-MPAS by @dengwirda and the newly added DGGRID mesh feature by @sahrk. There are a certain amount of learning curves to using an unstructured mesh generator, considering whether it has good documentation. The MPAS mesh is unique because it involves a range of operations. However, it has many advantages that other meshes cannot provide. That is why we use it as an example to demonstrate the capability of pyflowline to support fully unstructured meshes. In the future, we may add a more straightforward example/notebook to use a different mesh, such as the DGGRID mesh. We have just released such a dataset on Zenodo which can be customized for this purpose.

Again, thanks for the suggestions, and we will keep improving it in future versions.

[smchartrand]

I want to echo the comments by @andres-patrignani, and thank the authors for their extensive efforts to improve pyflowline. All of my previous comments have been addressed (and done so very well), and yesterday I was able to:

• (re)install pyflowline using the detailed documentation and step by step instructions (Ubuntu 22.04 LTS release) , and

• implement an instance of the updated Jupyter Notebook and run each notebook component all the way through for the example provided by the authors.

I have no further suggestions. Congratulations to the authors on an excellent package. Thanks for the opportunity to review.

[observingClouds]

@andres-patrignani, @smchartrand thank you very much for your time and efforts to review this submission. I appreciate it!

@changliao1025 as you can see from the reviewers' comments all issues have been fixed to their satisfaction. The suggested additional improvements regarding a future release of the software are not necessary to implement for the acceptance in JOSS but I still encourage you to do them in the near future as those might widen your user base.

[observingClouds]

Post-Review Checklist for Editor and Authors

Additional Author Tasks After Review is Complete

• [x] Double check authors and affiliations (including ORCIDs)
• [x] Make a release of the software with the latest changes from the review and post the version number here. This is the version that will be used in the JOSS paper.
• [x] Archive the release on Zenodo/figshare/etc and post the DOI here.
• [x] Make sure that the title and author list (including ORCIDs) in the archive match those in the JOSS paper.
• [x] Make sure that the license listed for the archive is the same as the software license.

Editor Tasks Prior to Acceptance

• [x] Read the text of the paper and offer comments/corrections (as either a list or a PR)
• [x] Check the references in the paper for corrections (e.g. capitalization)
• [x] Check that the archive title, author list, version tag, and the license are correct
• [x] Set archive DOI with @editorialbot set <DOI here> as archive
• [x] Set version with @editorialbot set <version here> as version
• [x] Double check rendering of paper with @editorialbot generate pdf
• [x] Specifically check the references with @editorialbot check references and ask author(s) to update as needed
• [x] Recommend acceptance with @editorialbot recommend-accept

[observingClouds]

@changliao1025 could you please complete the above mentioned author tasks and ping me when completed? Thank you.

[changliao1025]

@observingClouds Thank you for the updates. We have checked the items as instructed.

• [x] Double check authors and affiliations (including ORCIDs)
• [x] Make a release of the software with the latest changes from the review and post the version number here. This is the version that will be used in the JOSS paper. version 0.3.2
• [x] Archive the release on Zenodo/figshare/etc and post the DOI here. https://zenodo.org/doi/10.5281/zenodo.6407298
• [x] Make sure that the title and author list (including ORCIDs) in the archive match those in the JOSS paper.
• [x] Make sure that the license listed for the archive is the same as the software license.

[observingClouds]

@editorialbot set 10.5281/zenodo.6407298 as archive

[editorialbot]

Done! archive is now 10.5281/zenodo.6407298

[observingClouds]

@editorialbot set 0.3.2 as version

[editorialbot]

Done! version is now 0.3.2

[observingClouds]

@editorialbot generate pdf

[editorialbot]

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

[observingClouds]

@changliao1025 thank you for finishing the post-review tasks. I have a few minor comments:

• [x] The zenodo package title is "river networks generator", while everywhere else it is called "river network generator". Please adapt accordingly so that all resources match.
• [x] I found a few typos in the paper and opened a PR. Feel free to merge it or correct those yourself.
• [x] Please make sure that the capitalisation in your references is preserved. You can preserve capitalisation by placing {} around characters/words in your .bib file. Liao et al. (2023b) is one example where the capitalisation is not preserved. There is also something wrong with the DOI url.
• [x] Please add the volume/issue information to Liao et al. (2023a).

Please address these points and we should be soon ready for publication.

[changliao1025]

Hi, @observingClouds; all the above issues are fixed now. The version is also bumped to 0.3.4. Thank you for identifying these issues.

[observingClouds]

Thanks @changliao1025. Thanks for changing also the title in the zenodo archive. The newest release is not corrected though (https://zenodo.org/records/10076553).

[changliao1025]

@observingClouds. I realized that Zenodo only updates the title for a specific version, not all versions. I updated the title for the v0.3.4. Thank you. I may find a way to update the title for all versions.

[observingClouds]

@editorialbot set v0.3.4 as version

[editorialbot]

Done! version is now v0.3.4

[observingClouds]

@editorialbot set 10.5281/zenodo.10076553 as archive

[editorialbot]

Done! archive is now 10.5281/zenodo.10076553