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

[editorialbot]

Submitting author: @changliao1025 (Chang Liao)
Repository: https://github.com/changliao1025/pyflowline
Branch with paper.md (empty if default branch): main
Version: v0.3.4
Editor: @observingClouds
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]

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

[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

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

[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-patrignani<https://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 GitHub<#5446 (comment)>, or unsubscribe<https://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

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

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

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

[editorialbot]

Done! archive is now 10.5281/zenodo.10076553

[observingClouds]

@editorialbot generate pdf

[editorialbot]

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

[observingClouds]

@editorialbot check references

[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
- 10.5194/gmd-9-2223-2016 is OK
- 10.21105/joss.02952 is OK
- 10.1029/2012WR012313 is OK
- 10.5281/zenodo.6109987 is OK
- 10.1029/2022MS003487 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[observingClouds]

@editorialbot recommend-accept

[editorialbot]

Attempting dry run of processing paper acceptance...

[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
- 10.5194/gmd-9-2223-2016 is OK
- 10.21105/joss.02952 is OK
- 10.1029/2012WR012313 is OK
- 10.5281/zenodo.6109987 is OK
- 10.1029/2022MS003487 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

👋 @openjournals/ese-eics, this paper is ready to be accepted and published.

Check final proof 👉📄 Download article

If the paper PDF and the deposit XML files look good in openjournals/joss-papers#4757, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

[kthyng]

Hi! My job is to wrap up this publication. My steps are:

• Check that version was updated
• Check that software archive exists, has been input to JOSS, and title and author list look good
• Check paper

[kthyng]

Ok we're good to go!

[kthyng]

@editorialbot accept

[editorialbot]

Doing it live! Attempting automated processing of paper acceptance...

[editorialbot]

Ensure proper citation by uploading a plain text CITATION.cff file to the default branch of your repository.

If using GitHub, a Cite this repository menu will appear in the About section, containing both APA and BibTeX formats. When exported to Zotero using a browser plugin, Zotero will automatically create an entry using the information contained in the .cff file.

You can copy the contents for your CITATION.cff file here:

CITATION.cff

cff-version: "1.2.0"
authors:
- family-names: Liao
  given-names: Chang
  orcid: "https://orcid.org/0000-0002-7348-8858"
- family-names: Cooper
  given-names: Matt G
  orcid: "https://orcid.org/0000-0002-0165-209X"
doi: 10.5281/zenodo.10076553
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Liao
    given-names: Chang
    orcid: "https://orcid.org/0000-0002-7348-8858"
  - family-names: Cooper
    given-names: Matt G
    orcid: "https://orcid.org/0000-0002-0165-209X"
  date-published: 2023-11-07
  doi: 10.21105/joss.05446
  issn: 2475-9066
  issue: 91
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 5446
  title: "pyflowline: a mesh-independent river network generator for
    hydrologic models"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.05446"
  volume: 8
title: "pyflowline: a mesh-independent river network generator for
  hydrologic models"

If the repository is not hosted on GitHub, a .cff file can still be uploaded to set your preferred citation. Users will be able to manually copy and paste the citation.

Find more information on .cff files here and here.

[editorialbot]

🐘🐘🐘 👉 Toot for this paper 👈 🐘🐘🐘

[editorialbot]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.05446 joss-papers#4766
1. Wait five minutes, then verify that the paper DOI resolves https://doi.org/10.21105/joss.05446
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

[kthyng]

Congrats on your new publication @changliao1025! Many thanks to editor @observingClouds and reviewers @smchartrand and @andres-patrignani for your time, hard work, and expertise!!

[editorialbot]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.05446/status.svg)](https://doi.org/10.21105/joss.05446)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.05446">
  <img src="https://joss.theoj.org/papers/10.21105/joss.05446/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.05446/status.svg
   :target: https://doi.org/10.21105/joss.05446

This is how it will look in your documentation:

We need your help!

The Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://reviewers.joss.theoj.org/join
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

[changliao1025]

Thank you, @kthyng @observingClouds and reviewers, for the indispensable help and suggestions during this process.