[REVIEW]: SSN2: The next generation of spatial stream network modeling in R

[editorialbot]

Submitting author: @michaeldumelle (Michael Dumelle)
Repository: https://github.com/USEPA/SSN2
Branch with paper.md (empty if default branch): develop
Version: v0.2.0(JOSS)
Editor: @mikemahoney218
Reviewers: @fernandomayer, @k-doering-NOAA, @fawda123
Archive: 10.5281/zenodo.12770259

Status

Status badge code:

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

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

@fernandomayer & @k-doering-NOAA, 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 @mikemahoney218 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 @k-doering-NOAA

📝 Checklist for @fawda123

📝 Checklist for @fernandomayer

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

Software report:

github.com/AlDanial/cloc v 1.88  T=0.23 s (888.3 files/s, 208289.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
HTML                            65           2240            198          14898
R                              117           1673           5470           9003
JavaScript                       4           2099           1928           7019
Markdown                         6            223              0            929
TeX                              2             94              0            782
XML                              2              0              2            639
Rmd                              2            171            561            216
C                                2             12             22             45
YAML                             3             12              2             44
SVG                              1              0              1             11
CSS                              1              0              5              1
JSON                             1              0              0              1
-------------------------------------------------------------------------------
SUM:                           206           6524           8189          33588
-------------------------------------------------------------------------------


gitinspector failed to run statistical information for the repository

[editorialbot]

Wordcount for paper.md is 1982

[editorialbot]

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

[mikemahoney218]

👋🏼 @michaeldumelle, @fernandomayer, @k-doering-NOAA, @fawda123: this is the review thread for the paper. Just about all of our communications will happen here from now on. 😄

As a reviewer, the first step is to create a checklist for your review by entering

@editorialbot generate my checklist

as the top of a new comment in this thread. For best results, don't include anything else in the comment!

These checklists contain the JOSS requirements. As you go over the submission, please check any items that you feel have been satisfied. The first comment in this thread also contains links to the JOSS reviewer guidelines.

The JOSS review is different from most other journals. Our goal is to work with the authors to help them meet our criteria instead of merely passing judgment on the submission. As such, the reviewers are encouraged to submit issues and pull requests on the software repository. When doing so, please mention openjournals/joss-reviews#6389 so that a link is created to this thread (and I can keep an eye on what is happening). Please also feel free to comment and ask questions on this thread. In my experience, it is better to post comments/questions/suggestions as you come across them instead of waiting until you've reviewed the entire package.

We aim for reviews to be completed within about 2-4 weeks. Please let me know if you require some more time.

Please feel free to ping me (@mikemahoney218) if you have any questions/concerns. Thanks again so much for agreeing to review!

[editorialbot]

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

OK DOIs

- 10.1371/journal.pone.0282524 is OK
- 10.32614/RJ-2018-009 is OK

MISSING DOIs

- 10.1002/2015wr018349 may be a valid DOI for title: Spatial statistical network models for stream and river temperature in New England, USA
- 10.1016/j.jtherbio.2021.103028 may be a valid DOI for title: Integrating thermal infrared stream temperature imagery and spatial stream network models to understand natural spatial thermal variability in streams
- 10.1111/rec.13626 may be a valid DOI for title: Riparian vegetation shade restoration and loss effects on recent and future stream temperatures
- 10.1111/1752-1688.12372 may be a valid DOI for title: The Stream-Catchment (StreamCat) Dataset: A database of watershed metrics for the conterminous United States
- 10.1139/cjfas-2016-0247 may be a valid DOI for title: Scalable population estimates using spatial-stream-network (SSN) models, fish density surveys, and national geospatial database frameworks for streams
- 10.1371/journal.pone.0239237 may be a valid DOI for title: Preparing GIS data for analysis of stream monitoring data: The R package openSTARS
- 10.1086/710340 may be a valid DOI for title: Variation in stream network relationships and geospatial predictions of watershed conductivity
- 10.1016/j.scitotenv.2017.08.151 may be a valid DOI for title: Using spatial-stream-network models and long-term data to understand and predict dynamics of faecal contamination in a mixed land-use catchment
- 10.1371/journal.pone.0238422 may be a valid DOI for title: SSNdesign — An R package for pseudo-Bayesian optimal and adaptive sampling designs on stream networks
- 10.1016/j.cageo.2004.03.012 may be a valid DOI for title: Multivariable geostatistics in S: the gstat package
- 10.1890/08-1668.1 may be a valid DOI for title: A mixed-model moving-average approach to geostatistical modeling in stream networks
- 10.1038/s41598-019-43132-7 may be a valid DOI for title: A spatial stream-network approach assists in managing the remnant genetic diversity of riparian forests
- 10.1007/s10021-018-0311-8 may be a valid DOI for title: Estimating ecosystem metabolism to entire river networks
- 10.1111/1752-1688.12543 may be a valid DOI for title: Improving predictive models of in-stream phosphorus concentration based on nationally-available spatial data coverages
- 10.1111/1365-2664.13997 may be a valid DOI for title: Dendritic prioritization through spatial stream network modeling informs targeted management of Himalayan riverscapes under brown trout invasion
- 10.1016/j.cageo.2014.02.009 may be a valid DOI for title: rtop: An R package for interpolation of data with a variable spatial support, with an example from river networks
- 10.1198/jasa.2009.ap08248 may be a valid DOI for title: A moving average approach for spatial statistical models of stream networks

INVALID DOIs

- None

[michaeldumelle]

Thank you @mikemahoney218 , @fernandomayer, and @k-doering-NOAA ! If anyone has any questions that come up that I can help with, please don't hesitate to reach out.

[mikemahoney218]

@editorialbot add @fawda123 as reviewer

All three reviewers I reached out to accepted, which is fantastic! While we can have a review with 2 reviewers, 3 is ideal, so I'm going ahead and adding @fawda123 as a reviewer as well. Thanks again so much for agreeing to review!

[editorialbot]

@fawda123 added to the reviewers list!

[michaeldumelle]

Thank you @fawda123 !

[mikemahoney218]

Hi all! Just wanted to bump this thread now that we're about two weeks into the review window.

@fernandomayer, @k-doering-NOAA, @fawda123 : note that when you post this comment on this thread:
@editorialbot generate my checklist

You'll get a checklist generated containing all the elements we're asking you to look over as part of your review. Please let me know if you've got any questions/comments/concerns regarding the review!

@michaeldumelle , I should have mentioned this earlier, but if you want to take a look at those "MISSING DOIs" in the Editorialbot message above -- assuming those DOIs correspond to your actual citations, please go ahead and add them to your bibtex file (eg doi = "10.1002/2015wr018349"). No rush, but they'll need to get fixed before we'd accept the paper.

[michaeldumelle]

@mikemahoney218 I updated the bibtex file, incorporating the aforementioned DOIs and adding a few more. I pushed the changes to the joss branch, and you can review the commit here. Please let me know when you need anything else from me. Thank you!

[mikemahoney218]

@editorialbot check references

[editorialbot]

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

OK DOIs

- 10.1007/978-1-4614-7618-4 is OK
- 10.1002/9781119115151 is OK
- 10.1002/2015wr018349 is OK
- 10.1371/journal.pone.0282524 is OK
- 10.1016/j.jtherbio.2021.103028 is OK
- 10.1111/rec.13626 is OK
- 10.1111/1752-1688.12372 is OK
- 10.1002/2017WR020969 is OK
- 10.1139/cjfas-2016-0247 is OK
- 10.1371/journal.pone.0239237 is OK
- 10.18637/jss.v063.i19 is OK
- 10.1086/710340 is OK
- 10.1016/j.scitotenv.2017.08.151 is OK
- 10.1016/j.cageo.2004.03.012 is OK
- 10.32614/RJ-2018-009 is OK
- 10.1890/08-1668.1 is OK
- 10.18637/jss.v056.i02 is OK
- 10.1111/j.1523-1739.2012.01897.x is OK
- 10.1038/s41598-019-43132-7 is OK
- 10.1007/s10021-018-0311-8 is OK
- 10.48550/arxiv.2110.02507 is OK
- 10.1111/1752-1688.12543 is OK
- 10.1111/1365-2664.13997 is OK
- 10.1016/j.cageo.2014.02.009 is OK
- 10.1198/jasa.2009.ap08248 is OK
- 10.18637/jss.v056.i03 is OK
- 10.1007/978-0-387-98141-3 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[fawda123]

Review checklist for @fawda123

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/USEPA/SSN2?
• License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@michaeldumelle) 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?

[fawda123]

@michaeldumelle I've finished my initial review of the package and paper, nice work! These package updates are critical to maintain relevancy of "legacy" software as R continues to develop. It's nice to see the effort put into this work. I've added a few issues (USEPA/SSN2#11, USEPA/SSN2#12, USEPA/SSN2#13, USEPA/SSN2#14, USEPA/SSN2#15) in the main repo for your consideration. I think the biggest ask is updates to your unit tests. Let me know if you have any questions!

[michaeldumelle]

@fawda123 thank you so much for the kind words about the software and for the thorough and helpful review! I really appreciate the time you put into this, and I look forward to incorporating all of your feedback once the remaining reviews come in. I will reach out if I have any clarifying questions.

@mikemahoney218 SSN2 currently has three branches: 1) main, which is up to date with CRAN; 2) which is the development version that is ahead of CRAN; and 3) joss, which is up to date with main but has the joss paper in it. When incorporating feedback on the software, can I push changes to the development branch with the understanding that the changes will be merged into main alongside the next CRAN update? And when incorporating feedback on the paper, can I push changes to the joss branch?

[mikemahoney218]

Life will be easier if you can merge the development branch into the JOSS branch -- in particular, I think it will be easier for reviewers if there's one branch containing all of the most up-to-date revisions to the code and the paper (and it will also be better when we move to accepting the package and need an archive and DOI). Is that possible?

[mikemahoney218]

@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.1007/978-1-4614-7618-4 is OK
- 10.18637/jss.v067.i01 is OK
- 10.1016/j.fishres.2022.106583 is OK
- 10.1002/9781119115151 is OK
- 10.1002/2015wr018349 is OK
- 10.1371/journal.pone.0282524 is OK
- 10.1016/j.jtherbio.2021.103028 is OK
- 10.1111/rec.13626 is OK
- 10.5281/zenodo.4679423 is OK
- 10.1111/1752-1688.12372 is OK
- 10.1002/wat2.1023 is OK
- 10.1002/2017WR020969 is OK
- 10.1139/cjfas-2016-0247 is OK
- 10.1371/journal.pone.0239237 is OK
- 10.18637/jss.v063.i19 is OK
- 10.1086/710340 is OK
- 10.1016/j.scitotenv.2017.08.151 is OK
- 10.32614/CRAN.package.fields is OK
- 10.1016/j.cageo.2004.03.012 is OK
- 10.32614/RJ-2018-009 is OK
- 10.1890/08-1668.1 is OK
- 10.18637/jss.v056.i02 is OK
- 10.1111/j.1523-1739.2012.01897.x is OK
- 10.32614/CRAN.package.geoR is OK
- 10.1038/s41598-019-43132-7 is OK
- 10.1007/s10021-018-0311-8 is OK
- 10.32614/CRAN.package.broom is OK
- 10.18637/jss.v108.i10 is OK
- 10.1111/1752-1688.12543 is OK
- 10.1111/1365-2664.13997 is OK
- 10.1016/j.cageo.2014.02.009 is OK
- 10.1198/jasa.2009.ap08248 is OK
- 10.18637/jss.v056.i03 is OK
- 10.1007/978-0-387-98141-3 is OK
- 10.21105/joss.01686 is OK

MISSING DOIs

- No DOI given, and none found for title: rgeos: Interface to Geometry Engine - Open Source ...
- No DOI given, and none found for title: maptools: Tools for Handling Spatial Objects
- No DOI given, and none found for title: rgdal: Bindings for the ’Geospatial’ Data Abstract...
- No DOI given, and none found for title: Tidy modeling with R
- No DOI given, and none found for title: NHDPlus Version 2: User Guide
- No DOI given, and none found for title: National Stream Internet protocol and user guide
- No DOI given, and none found for title: Upcoming Changes to Popular R Packages for Spatial...
- No DOI given, and none found for title: SSNbler: Assemble SSN objects in R
- No DOI given, and none found for title: Mixed-effects models in S and S-PLUS
- No DOI given, and none found for title: Spatial Linear Models for Environmental Data

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#5647, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

[mikemahoney218]

Sorry folks -- I got slightly ahead of myself. One last issue before I hand back to the EiC:

@michaeldumelle , would you please archive the source code of your package, rather than the binary version?

[michaeldumelle]

Hi @mikemahoney218, in both the release tag and Zenodo archive, both the source and binaries are archived. Are you suggesting that the binaries should be removed, or is it okay that they are both there? Thanks!

[mikemahoney218]

Oh, sorry, Zenodo's default display only showed me the contents of the .zip file and not the .tar.gz. I think it's fine that they're both there.

@openjournals/ese-eics please ignore my concern above, this one is good to go 😄

[mikemahoney218]

🎉 With everything looking good on my end, it's time for me to hand this back to the EiC for last steps. Thanks @michaeldumelle for the submission, and thank you so much to @fernandomayer, @k-doering-NOAA, and @fawda123 for reviewing!

[michaeldumelle]

Thank you so much @fernandomayer, @k-doering-NOAA, @fawda123, for the helpful feedback which greatly improved both the software and manuscript.

A special thanks to @mikemahoney218 for being so prompt and helpful throughout this process!

[fawda123]

@michaeldumelle happy to help, looking forward to seeing this in print!

[michaeldumelle]

@mikemahoney218, this paper came out yesterday, which details the formulation we have in the software for generalized linear models. Is it possible to add this citation (to the sentence in the paper where we currently talk about ssn_glm())? If you approve, I can make the change and push.

[mikemahoney218]

That'll be fine -- if you can link the commit here so I can do a quick copy edit of your changes, that'd be ideal, but I don't see why we couldn't

[michaeldumelle]

Thanks so much @mikemahoney218 ; the relevant commit is linked here.

[mikemahoney218]

Looks good to me! @openjournals/ese-eics will correct me if I'm wrong, but this should be ready for processing.

[kthyng]

Hi! I'll take over now as Track Associate Editor in Chief to do some final submission editing checks. After these checks are complete, I will publish your submission!

• Are checklists all checked off?
• Check that version was updated and make sure the version from JOSS matches github and Zenodo.
• Check that software archive exists, has been input to JOSS, and title and author list match JOSS paper (or purposefully do not).
• Check paper.

[kthyng]

@michaeldumelle

• Can you update the version in Zenodo to match the version here too? It currently says v1.

[michaeldumelle]

@kthyng done! link here. Thank you for catching that!

[kthyng]

Ok ready 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: Dumelle
  given-names: Michael
  orcid: "https://orcid.org/0000-0002-3393-5529"
- family-names: Peterson
  given-names: Erin E.
  orcid: "https://orcid.org/0000-0003-2992-0372"
- family-names: Hoef
  given-names: Jay M. Ver
  orcid: "https://orcid.org/0000-0003-4302-6895"
- family-names: Pearse
  given-names: Alan
  orcid: "https://orcid.org/0000-0002-4133-8548"
- family-names: Isaak
  given-names: Daniel J.
doi: 10.5281/zenodo.12770259
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Dumelle
    given-names: Michael
    orcid: "https://orcid.org/0000-0002-3393-5529"
  - family-names: Peterson
    given-names: Erin E.
    orcid: "https://orcid.org/0000-0003-2992-0372"
  - family-names: Hoef
    given-names: Jay M. Ver
    orcid: "https://orcid.org/0000-0003-4302-6895"
  - family-names: Pearse
    given-names: Alan
    orcid: "https://orcid.org/0000-0002-4133-8548"
  - family-names: Isaak
    given-names: Daniel J.
  date-published: 2024-07-26
  doi: 10.21105/joss.06389
  issn: 2475-9066
  issue: 99
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 6389
  title: "SSN2: The next generation of spatial stream network modeling
    in R"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.06389"
  volume: 9
title: "SSN2: The next generation of spatial stream network modeling in
  R"

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.06389 joss-papers#5686
1. Wait five minutes, then verify that the paper DOI resolves https://doi.org/10.21105/joss.06389
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]

Congratulations on your new publication @michaeldumelle! Many thanks to @mikemahoney218 and to reviewers @fernandomayer, @k-doering-NOAA, and @fawda123 for your time, hard work, and expertise!! JOSS wouldn't be able to function nor succeed without your efforts.

@michaeldumelle If you'd like to review for JOSS, please register at https://reviewers.joss.theoj.org/.

[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.06389/status.svg)](https://doi.org/10.21105/joss.06389)

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

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

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

[michaeldumelle]

A final, huge thanks to @kthyng, @mikemahoney218, @fawda123, @k-doering-NOAA, and @fernandomayer for making this such an enriching process! Your hard work and feedback led me to adopt better software development practices that notably improved both the SSN2 software and the associated manuscript.