Review checklist

[amsnyder]

Review checklist for Richard McDonald

Background information for reviewers here

Please check off boxes as applicable and elaborate in comments below. If minor issues are found, feel free to create a branch or fork the project for review and make suggested changes directly in the source code using a pull request

• Code location https://code.usgs.gov/wma/hytest/nhm-assist
• authors Adel E. Haj, Matthew I. Barker, Parker A. Norton, James L. McCreight, and Lukka Ludden

Comment to Reviewer

Rich,

Thank you for agreeing to conduct the review of our software release of NHM-Assist. We have provided a checklist that will assist you in completion of the security review, domain review, and code review. These notebooks are designed to allow cooperators and modelers alike to evaluate, interrogate, and visualize the model hydrofabric elements, parameter values, and output of domains extracted from the National Hydrologic Model (NHM). We also wanted to keep the code easily readable and editable by modelers with an introductory to intermediate python coding skill level. As such, we acknowledge there may be faster and more elegant ways to code some steps of our workflow. We hope to gain more of your impressions and suggestions regarding data presentation, visualization and interaction. Again, we thank you for you review and hope you enjoy version 1 of the NHM-Assist notebooks.

After cloning NHM-Assist and following the instructions for the installation of the nhm environment found in the README, please download the example domain 'willamette_river' for testing purposes. From the miniforge command window, navigate to the repository, and then run python pull_domain.py --name=willamette_river. This will download the example domain to the domain_data folder in the repository from the HyTEST OSN POD. If you would like other example domains to run, or have any questions, please reach out to us.

Note: The notebooks are intended to be run in order, starting with the notebook 0_Workspace_setup.ipynb. This is the only notebook you may need to edit if you have an example domain that is not 'willamette_river'. We set defaults in notebook 0 for the provided example. Other notebooks have selections from dropdowns (or you may choose to copy/paste a gage id from a map into a selection box).

Conflict of interest

• I confirm that I have no COIs with reviewing this work, meaning that there is no relationship with the product or the product's authors or affiliated institutions that could influence or be perceived to influence the outcome of the review (if you are unsure whether you have a conflict, please speak to your supervisor before starting your review).

Adherence to Fundamental Science Practices

• I confirm that I read and will adhere to the Federal Source Code Policy for Scientific Software and relevant federal guidelines for approved software release as outlined in SM502.1 and SM502.4.

Security Review

• No proprietary code is included
• No Personally Identifiable Information (PII) is included
• No other sensitive information such as data base passwords are included

General checks

• Repository: Is the source code for this software available?
• License: Does the repository contain a plain-text LICENSE file?
• Disclaimer: Does the repository have the USGS-required provisional Disclaimer?
• Contribution and authorship: Has the submitting author made major contributions to the software? Does the full list of software authors seem appropriate and complete?
• Code.json: Does the repository have a code.json file?

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve?
• 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?
• References: When present, do references in the text use an appropriate citation method?

Functionality

• Installation: Does installation succeed 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.)
• Automated tests: If there are unit tests, do they cover essential functions of the software and a reasonable range of inputs and conditions? Do all tests pass when run locally? (If there are no tests, as in the case of a collection of notebooks, please check off this item.)

Reviewer checklist source statement

This checklist utilizes elements of the Journal of Open Source Science (JOSS) review checklist: it has been modified for use with USGS software releases.