Skip to content

Draft: Software release domain review

Review of hyswap-geospatial-data-assembly repository

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

Project Overview

This repository contains the Python code for acquiring and pre-processing geospatial data that is used as input to the hyswap package, which will replace the core computational functionality currently available in the Water Watch web application.

The repository was provisionally released Nov 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 Nov 20, 2023.

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

For completing the Domain Review, please complete a review of the content within the documentation and code examples to ensure it is factually correct and please provide feedback on the utility and style in which the documentation is presented.

Review Checklist

Please check off boxes as applicable, and elaborate in comments below.

Repository location:

Repository contents:

  1. misc/ folder containing miscellaneous files related to generating example notebooks
  2. src/ folder containing the python scripts
  3. data/ folder containing datasets used in validation testing
  4. notebooks/ folder containing a notebook for testing and validating code outputs

Deployment approach:

  • This is described in the ReadMe in the Getting Started section

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

  • 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: 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? Python packaging guidelines here

Review Comments

Please update with your comments

Acknowledgements

This checklist combines elements of the rOpenSci review guidelines and the Journal of Open Source Science (JOSS) review checklist.

Edited by Sleckman, Margaux