In tbep-tech/tbepRSparrow: RSPARROW: An R system for SPARROW modeling

Introduction

This vignette provides a general summary of RSPARROW and guidance on the setup and execution of the system.

RSPARROW is a system of R scripts and functions for executing and evaluating SPARROW models that generates graphical, map, and tabular output. Users operate the system within RStudio from a single control script that accesses the supporting input files and functions.

The RSPARROW documentation describes the steps necessary to estimate the static version of the model. Static SPARROW models provide reach-level predictions (and uncertainties) of the long-term mean annual water-quality loads and flow-weighted concentrations. The predictions also include the shares of the load attributable to individual upstream sources and predictions of the mass quantities of the total load and individual sources that are delivered to downstream water bodies.

Users are directed to download the documentation from https://code.usgs.gov/water/stats/RSPARROW/RSPARROW_master/inst/doc/RSPARROW_docV1.0.pdf. This provides a complete guide to the installation and use of RSPARROW, including the steps needed to create and interpret SPARROW models.

Installation of RSPARROW

Download RSPARROW from the USGS GitLab repository: https://code.usgs.gov/water/stats/RSPARROW. This includes scripts, functions, and supporting documentation and tutorials.

See Chapter 1.3 of the documentation for information on the RSPARROW directory structure and contents.

Three directories contain the contents of RSPARROW (The figure below shows the contents of the RSPARROW directories as installed on a user's computer):

1. RSPARROW_master: Includes functions, sourced files (DLLs), meta-data, and documentation vignettes. The directory contents should not be modified by users; no other sub-directories should be created in this directory on a user's computer. The documentation, with clickable links in the PDF table of contents, is located in the "RSPARROW_master/inst/doc" sub-directory.

2. UserTutorial: Contains the SPARROW total nitrogen models that are used for the tutorials presented in Chapter 6 of the documentation.

   • The "results" sub-directory contains a control script, input control files to execute the SPARROW model, and sub-directories for the tutorial models. The control script executes a predetermined sequence of function calls, governed by user settings in the control script. Separate execution of RSPARROW library functions by users (e.g., to estimate models or generate predictions and maps) is not supported.

   • The directory structure and contents for the tutorial model, including the control scipt and input control files, can be used as a template to guide the setup and execution of user developed models.

3. R-3.5.0: Contains the recommended 3.5.0 version of R, with pre-installed RSPARROW library dependencies. The R library dependencies have been tested for compatibility with RSPARROW. More recent R versions (>3.5.0) may operate with RSPARROW, once the required package dependencies are installed, but full compatibility of these R versions with RSPARROW is not guaranteed. The R-3.5.0 directory should be located separately from the RSPARROW master and User Directories, such as parallel to a user's other versions of R.

Setup and execution of a SPARROW model in RSPARROW

See the documentation Chapter 4.1 ("Overview of the sparrow_control.R script settings") and 4.2 ("Executing the control script in RStudio") for details on getting started with RSPARROW. Chapter 4.2 gives information on finding a copy of the control script, a list of five major steps for executing RSPARROW, and a detailed checklist for the setup and testing of system settings, control files, and new models.

The tutorial models described in Chapter 6 also provide an illustration of how to build a SPARROW model, starting with a simple specification and adding variables to construct a more complex model. The descriptions of the models include helpful summaries of the model output and interpretations of the model results.

Reporting bugs

Please consider reporting bugs and asking questions on the GitHub Issues page: https://github.com/USGS-R/RSPARROW/issues

Citation for the RSPARROW Software Release

Alexander, Richard B., and Gorman Sanisaca, Lillian. (2019). RSPARROW: An R system for SPARROW modeling [Software release]. U.S. Geological Survey. DOI: https://doi.org/10.5066/P9UAZ6FO

Code of Conduct

We want to encourage a warm, welcoming, and safe environment for contributing to this project. See the code of conduct for more information.

Disclaimer

This software has been approved for release by the U.S. Geological Survey (USGS). Although the software has been subjected to rigorous review, the USGS reserves the right to update the software as needed pursuant to further analysis and review. No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. Furthermore, the software is released on condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from its authorized or unauthorized use.

Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government.

tbep-tech/tbepRSparrow documentation built on Oct. 9, 2020, 6:24 a.m.