Skip to content

Official Software Release Code and Security Review #2

Review of hyswap repository

Background information about the USGS software review process is here. In general, we will follow the 'Review with Git' process.

We have created a candidate-release branch where the reviews will take place. Please navigate to this branch for carrying out the review.

Project Overview

This repository contains the Python code for computing various streamflow metrics and presenting those data in maps, plots and graphs. This package is designed based on the Water Watch web application (https://waterwatch.usgs.gov/).

The example-notebooks folder provides example .ipynb's for users to familiarize themselves with the package functionality and presents common use cases in the USGS Water Watch application. We request that reviewers attempt to run the example notebooks to ensure proper functionality and provide feedback related to the content, style, and results. Note: Please refer to the readMe for guidance on running the example notebooks.

Review of the continuous integration pipelines (e.g., deployment .yml files) and other supporting repositories is also appreciated, but less critical to the overall evaluation of this project.

A note about installing hyswap

hyswap provides installation instructions from PyPi (using pip), from source (GitHub), and developer installation from GitHub. For running the example notebooks, we recommend reviewers install the developer version, which has an expanded list of package requirements.

Additional Instructions for Code Review

The repository was provisionally released April 20, 2023; commits through that date have been verified to meet security requirements for public release. If completing a Code Review, please also complete a security check on commits made after April 20, 2023.

Additional Instructions for Domain Review

  • Please review the content of the published supporting documentation documentation and code examples to ensure they are factually correct. Optional feedback on the utility and style in which the documentation is presented is also appreciated.
  • Please refer to the internal (USGS-only) validation scripts in the validation-testing repository that test that the hyswap functions are producing scientifically reliable results. This repository will not be published along with hyswap and is intended for validation and review purposes. The validation tests use the existing outputs from the NWIS Statistics Service as well as the USGS Water Watch application as comparison datasets of real-world data. These tests are intended to complement the automated suite of code tests. Note: the notebooks may use very large datasets that were stored locally in order to perform the testing. The data sources are cited in each validation notebook. The raw data used to run the validation tests is stored in a Sharepoint folder.

Review checklist for @hyswap

Background information for reviewers here

Please check off boxes as applicable, and elaborate in Comments section below. Asterisk (*)=required

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

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?
  • 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 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? This information could be found in the README, CONTRIBUTING, or DESCRIPTION sections of the documentation.
  • References: When present, do references in the text use the proper citation syntax? *

Functionality

  • Scientific soundness: Are the outputs of the package scientifically sound/accurate?
  • 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?
  • Automated tests: Do unit tests cover essential functions of the software and a reasonable range of inputs and conditions? Do all tests pass when run locally?
  • Packaging guidelines: Does the software conform to the applicable packaging guidelines? R packaging guidelines here; Python packaging guidelines here *

Review Comments

  • Add free text comments here.

Reviewer checklist source statement

This checklist combines elements of the rOpenSci review guidelines and the Journal of Open Source Science (JOSS) review checklist: it has been modified for use with USGS software releases. Version 2024-05-30.

Edited by Killian, Courtney