sites_by_state: Get a List of USGS Site Numbers by State (or All States)

In wasquith-usgs/akqdecay: Many Distributional Statistics of USGS Daily Streamflow Hydrographs and Powerful Utilities

Description

Retrieve “site file” information for U.S. Geological Survey (USGS) streamgages by state abbreviation following the abbreviations in state.abb as part of base R. This function is a trivial wrapper (abstraction layer) on both dataRetrieval::whatNWISsites() and dataRetrieval::readNWISsite(), which are the functions used to retrieve sites by state and the site file information from the USGS National Water Information System (NWIS) (U.S. Geological Survey, 2020), respectively.

Usage

sites_by_state(states, parameterCd="00060", site_tp_cd="ST",
               agency_cd="USGS", ditch_15digit=TRUE,
               rm_alt=TRUE, rm_coord=TRUE, rm_countystate=TRUE,
               rm_huc=TRUE, rm_tz=TRUE,
               rm_drain=TRUE, make_CDA=TRUE,
               simplify=TRUE, strip_single_quote_mark=TRUE,
               silent=FALSE, ...)

Arguments

states	A vector of two-character state abbreviation and each element is compared to the list of datasets::state.abb;
parameterCd	The parameter code (default is discharge) of NWIS and the dataRetrieval package;
site_tp_cd	The site type code (default is stream) of NWIS and the dataRetrieval package;
agency_cd	The agency code to exclusively retain in the retrieved site files by state;
ditch_15digit	A logical to trigger removal of site numbers having 15 digits. This feature permits the removal of site numbers constructed of latitude and longitudes. Such surface water sites are almost always(?) some type of special project site and lack extensive records in time for the statistical analyses designed into the akqdecay package;
rm_alt	A logical to trigger removal of altitude related columns;
rm_coord	A logical to trigger removal of horizontal coordinate related columns. Note that the decimal latitude and longitude are always retained and are in the North American Datum of 1983 (NAD83);
rm_countystate	A logical to trigger removal of county, state, and country code columns;
rm_huc	A logical to trigger removal of the hydrologic unit code column;
rm_tz	A logical to trigger removal of the time-zone code column;
rm_drain	A logical to trigger removal of the total and contributing drainage area columns, but this trigger is not related to the makeCDA;
makeCDA	A logical to trigger the pairwise minimum of the two drainage areas and create a column titled CDA;
simplify	A logical to trigger the removal of many columns for which are quite unlikely of be of general interest in any type of “site table” construction for a publication;
strip_single_quote_mark	A logical to trigger the removal of single quotation marks. This is done so that should the table be exported to a delimited file that might not be using the double quotes correction, that it remains likely the table is still parsable. For example, there is a town in Texas called “D'Hanis” and is in a few streamgage names. This name quietly gets converted to “DHanis”;
silent	Suppress informative calls to message(); and
...	Additional arguments to pass.

Value

A data frame of the USGS site information file for stations in the given states with variable columns but reduction in columns from those retrieved by a straight call to dataRetrieval::readNWISsite(). Two drainage areas are recorded in the USGS database: total drainage area (drain_area_va) and contributing drainage area (contrib_drain_area_va). The pairwise minimum or

  CDA <- pmin(drain_area_va, contrib_drain_area_va, na.rm=TRUE)

of these is computed and placed into a new column CDA, if makeCDA is set. This is done in an effort to have a canonical access point of contributing drainage area. Not all streamgages will have both drainage areas populated in the site file.

Author(s)

W.H. Asquith

References

U.S. Geological Survey, 2020, National Water Information System, Web interface, accessed July 16, 2020, at https://doi.org/10.5066/F7P55KJN.

Examples

# This is a very convenient recipe for production of a "site table" for a
# publication using streamgages aligned to study area boundary of states.
SitesInMyStudy <- sites_by_state(c("RI","CT", "purpose mistake"))
print(head(SitesInMyStudy)) # agency_cd, site_no, station_nm,
                            # dec_lat_va, dec_long_va, and CDA
nm <- c("Agency_code", "Streamgage_identification_number", "Streamgage_name",
        "Decimal_latitude_NAD83", "Decimal_longitude_NAD83",
        "Contributing_drainage_area")
names(SitesInMyStudy) <- nm

wasquith-usgs/akqdecay documentation built on Nov. 9, 2020, 1:13 p.m.