dataRetrieval

This R package is designed to obtain USGS or EPA water quality sample data, streamflow data and metadata directly from web services.
https://github.com/DOI-USGS/dataRetrieval

Category: Natural Resources
Sub Category: Water Supply and Quality

Keywords

r r-package rstats usgs

Keywords from Contributors

hydrology water-quality measur observation generic ecology features grid-data geo-data-portal annotation

Last synced: about 19 hours ago
JSON representation

Repository metadata

This R package is designed to obtain USGS or EPA water quality sample data, streamflow data, and metadata directly from web services.

README.Rmd

          ---
title: "README"
output:
  md_document:
    variant: gfm
editor_options: 
  chunk_output_type: console
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/",
  warning = FALSE,
  message = FALSE,
  fig.height = 7,
  fig.width = 7
)
library(dataRetrieval)
```


# dataRetrieval 

[![CRAN version](http://www.r-pkg.org/badges/version/dataRetrieval)](https://cran.r-project.org/package=EGRET)
[![](http://cranlogs.r-pkg.org/badges/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval)
[![](http://cranlogs.r-pkg.org/badges/grand-total/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval)

The `dataRetrieval` package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrology data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. Direct USGS data is obtained from a service called the National Water Information System (NWIS). 

# Introduction

:warning: USGS discrete water-quality data availability and format are changing. Beginning March 11, 2024 USGS data obtained from legacy services will not include new USGS data or recent updates to existing data. To view the status of changes in data availability and code functionality, visit: 

If you have additional questions about these changes, email [email protected].

# What would you like to do?

1. Get instantaneous USGS discharge data. Start here: `?readNWISuv`

2. Get daily USGS discharge data. Start here: `?readNWISdv`

3. Get USGS groundwater data. Start here: `?readNWISgwl`

4. Get discrete water quality data. Start here: `?readWQPdata`

4. Discover USGS data (not including discrete water quality data). Start here: `?whatNWISdata`

6. Find Hydro Network-Linked Data Index (NLDI) data. Start here: `?findNLDI`

For additional tutorials, see:

[Basic Tutorial](https://doi-usgs.github.io/dataRetrieval/articles/tutorial.html)

[dataRetrieval Introduction 1](https://rconnect.usgs.gov/dataRetrieval_workshop)

[dataRetrieval Introduction 2](https://rconnect.usgs.gov/NMC_dataRetrieval_2)


# Installation of dataRetrieval

To install the `dataRetrieval` package, you must be using R 3.0 or greater and run the following command:

```{r eval=FALSE}
install.packages("dataRetrieval")
```

# New USGS data access

The USGS is planning to modernize all web services in the near future. For each of these updates, `dataRetrieval` will create a new function to access the new services. 

## New Features

### Style

New functions will use a "snake case", such as "read_USGS_samples". Older functions use camel case, such as "readNWISdv". The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. 

### Structure

Historically, we allowed users to customize their queries via the `...` argument structure. With `...`, users needed to know the exact names of query parameters before using the function. Now, the new functions will include **ALL** possible arguments that the web service APIs support. This will allow users to use tab-autocompletes (available in RStudio and other IDEs). **Users will need to understand that it is not advisable to specify all of these parameters. The systems can get bogged down with redundant query parameters.** We expect this will be easier for users, but it might take some time to smooth out the documentation and test usability. There may be additional consequences, such as users won't be able to build up argument lists to pass into the function.  

### Dependencies

As we develop functions for the modern USGS web services, we'll continue to explore updating package dependencies.  

### Developmental workflow

CRAN-stable documentation will be available on the GitHub pages:


In-development documentation will be available on the USGS GitLab pages:


Development of `dataRetrieval` will happen on a git branch called "develop". The "develop" branch will only move to the "main" branch when we submit to CRAN, unless there are bug fixes that pertain to the CRAN release. The "develop" branch WILL change frequently, and there are no promises of future behavior. Users must accept that they are using those functions at their own risk. If you willing to accept this risk, the installation instructions are:

```{r eval=FALSE}
library(remotes)

install_github("DOI-USGS/dataRetrieval",
               ref = "develop")

```


# Reporting bugs

Please consider reporting bugs and asking questions on the Issues page:
[https://github.com/DOI-USGS/dataRetrieval/issues](https://github.com/DOI-USGS/dataRetrieval/issues)

# Citations

## Citing the dataRetrieval package

```{r cite, eval=TRUE}
citation(package = "dataRetrieval")
```

## Citing NWIS data

U.S. Geological Survey, 2023, National Water Information System data available on the World Wide Web (USGS Water Data for the Nation), accessed [April 26, 2023], at http://waterdata.usgs.gov/nwis/. http://dx.doi.org/10.5066/F7P55KJN

This can be done using the `create_NWIS_bib` function:


```{r}

dv <- readNWISdv("09010500", "00060")

NWIScitation <- create_NWIS_bib(dv)

NWIScitation
print(NWIScitation, style = "Bibtex")


```

## Citing WQP data

Citations for specific datasets should use this format:

National Water Quality Monitoring Council, YYYY, Water Quality Portal, accessed mm, dd, yyyy, hyperlink_for_query, https://doi.org/10.5066/P9QRKUVJ.

This can be done using the `create_WQP_bib` function:

```{r}
SC <- readWQPqw(siteNumbers = "USGS-05288705",
                parameterCd = "00300")

WQPcitation <- create_WQP_bib(SC)
WQPcitation
print(WQPcitation, style = "Bibtex")
```

## Citing Water Quality Portal itself

General Water Quality Portal citations should use the following:

Water Quality Portal. Washington (DC): National Water Quality Monitoring Council, United States Geological Survey (USGS), Environmental Protection Agency (EPA); 2021. https://doi.org/10.5066/P9QRKUVJ.

# Package Support

The Water Mission Area of the USGS supports the development and maintenance of `dataRetrieval`, and most likely further into the future. Resources are available primarily for maintenance and responding to user questions. Priorities on the development of new features are determined by the `dataRetrieval` development team. This software was last released with USGS record: IP-147158.

```{r disclaimer, child="DISCLAIMER.md", eval=TRUE}
```



        

Owner metadata


GitHub Events

Total
Last Year

Committers metadata

Last synced: 7 days ago

Total Commits: 2,263
Total Committers: 27
Avg Commits per committer: 83.815
Development Distribution Score (DDS): 0.133

Commits in past year: 264
Committers in past year: 4
Avg Commits per committer in past year: 66.0
Development Distribution Score (DDS) in past year: 0.042

Name Email Commits
Laura DeCicco l****o@u****v 1963
wdwatkins w****s@u****v 135
Lindsay Carr l****r@u****v 48
mike j****0@u****u 25
David Blodgett d****t@u****v 11
Krall a****l@u****v 11
Jessica Thompson j****s@u****v 9
Jordan S Read j****d@u****v 8
Julie Padilla p****0@g****m 7
Doug Friedman s****b@g****m 6
Jordan Walker j****r@u****v 6
elbeejay j****n@u****v 6
jsta s****2@m****u 5
Lee Stanish 8****s 5
Elise Hinman e****n@u****v 4
Jerry Martin A****t 2
matt rhoads m****1@g****m 2
Alison Appling a****g@u****v 1
Bryan McCloskey b****y@u****v 1
Jim Hester j****r@g****m 1
Katrin Leinweber 9****r 1
Kevin M. Smith K****h@t****u 1
unknown l****o@I****t 1
David Blodgett 1
Padilla J****a@s****v 1
dependabot[bot] 4****] 1
jwpestrak j****k 1

Committer domains:


Issue and Pull Request metadata

Last synced: 2 days ago

Total issues: 120
Total pull requests: 157
Average time to close issues: 9 months
Average time to close pull requests: 2 days
Total issue authors: 68
Total pull request authors: 12
Average comments per issue: 2.75
Average comments per pull request: 0.32
Merged pull request: 150
Bot issues: 0
Bot pull requests: 0

Past year issues: 17
Past year pull requests: 55
Past year average time to close issues: 13 days
Past year average time to close pull requests: 3 days
Past year issue authors: 13
Past year pull request authors: 4
Past year average comments per issue: 2.18
Past year average comments per pull request: 0.38
Past year merged pull request: 49
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/DOI-USGS/dataRetrieval

Top Issue Authors

  • ldecicco-USGS (27)
  • jmusgs (7)
  • lstanish-usgs (4)
  • lindsayplatt (4)
  • dblodgett-usgs (3)
  • jordansread (3)
  • ehinman (3)
  • Katianagr (2)
  • fhmejia (2)
  • jfisher-usgs (2)
  • nrlottig (2)
  • mkoohafkan (2)
  • mps9506 (2)
  • tjstagni (2)
  • jkreft-usgs (2)

Top Pull Request Authors

  • ldecicco-USGS (130)
  • dblodgett-usgs (8)
  • mikejohnson51 (4)
  • alkrall (3)
  • jsta (3)
  • elbeejay (3)
  • padilla410 (1)
  • jpadilla-spu (1)
  • lstanish-usgs (1)
  • ehinman (1)
  • jimhester (1)
  • rckwzrd (1)

Top Issue Labels

  • bug (44)
  • question (34)
  • enhancement (30)
  • Backlog (8)

Top Pull Request Labels


Package metadata

cran.r-project.org: dataRetrieval

Retrieval Functions for USGS and EPA Hydrology and Water Quality Data

  • Homepage:
  • Documentation: http://cran.r-project.org/web/packages/dataRetrieval/dataRetrieval.pdf
  • Licenses: CC0
  • Latest release: 2.7.18 (published 3 months ago)
  • Last Synced: 2025-05-16T00:08:21.516Z (2 days ago)
  • Versions: 35
  • Dependent Packages: 10
  • Dependent Repositories: 50
  • Downloads: 3,469 Last month
  • Docker Downloads: 42,194
  • Rankings:
    • Dependent repos count: 3.522%
    • Dependent packages count: 5.343%
    • Downloads: 7.765%
    • Average: 10.606%
    • Docker downloads count: 25.793%
  • Maintainers (1)

Dependencies

DESCRIPTION cran
  • R >= 3.5.0 depends
  • curl * imports
  • httr >= 1.0.0 imports
  • jsonlite * imports
  • lubridate >= 1.5.0 imports
  • readr >= 1.0.0 imports
  • stats * imports
  • utils * imports
  • xml2 * imports
  • DT * suggests
  • covr * suggests
  • dplyr * suggests
  • ggplot2 * suggests
  • gridExtra * suggests
  • knitr * suggests
  • rmarkdown * suggests
  • sf * suggests
  • testthat * suggests
.github/workflows/R-CMD-check.yaml actions
  • actions/checkout v3 composite
  • r-lib/actions/check-r-package v2 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/pkgdown.yaml actions
  • JamesIves/github-pages-deploy-action v4.4.1 composite
  • actions/checkout v3 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/style-and-lint.yaml actions
  • actions/cache v2 composite
  • actions/checkout v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
  • stefanzweifel/git-auto-commit-action v4 composite
.github/workflows/test-coverage.yaml actions
  • actions/cache v1 composite
  • actions/checkout v2 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite

Score: 19.736795567275262