sites2sp: Convert a List of USGS Site Numbers to a...

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 site identification number and convert to a SpatialPointsDataFrame of the sp package. This function is a trivial wrapper (abstraction layer) on dataRetrieval::readNWISsite(), which is the function used to retrieve the site file information from the USGS National Water Information System (NWIS) (U.S. Geological Survey, 2020). The sites_to_SpatialPointsDataFrame streamlines an expected need of akqdecay users requiring spatial representation in the sp package framework, and EPSG declarations are described herein. EPSG Geodetic Parameter Dataset (also EPSG registry) is a public registry of spatial reference systems, Earth ellipsoids, coordinate transformations and related units of measurement.

This function loops site-by-site and queries NWIS instead of groups or ensembles of site numbers—large scale testing indicates that this is a prudent design decision because expected applications could readily send too many site numbers simultaneously to the USGS waterdata services. Also there is a question of how to handle invalid or otherwise “bad sites”. The function has try() wrapped around readNWISsite() to trap for individual errors—for example, an invalid site number.

Usage

sites_to_SpatialPointsDataFrame(siteNumbers, latlongcrs="+init=epsg:4269",
                                             proj4string=NA,
                                             usesp=TRUE, silent=FALSE, ...)

Arguments

siteNumbers	USGS streamgage identification numbers and nomenclature matches that of the dataRetrieval package, and multiple site numbers can be provided;
latlongcrs	A sp::CRS string defining the meaning of the North American Datum of 1983 (NAD83) decimal latitude and longitude values from NWIS and the applicable EPSG spatial reference system is "+init=epsg:4269" (geographic coordinates, NAD83)(Klokan Technologies, 2020). A call to sp::CRS(latlongcrs) is made internally. The authors do not anticipate that the latlongcrs would ever require explicit redefinition and can be left to the default shown;
proj4string	An sp::CRS() string that will optionally be used for coordinate projection by sp::spTransform() and nomenclature matches that of the sp package. A suggested EPSG is "+init=epsg:5070" (Albers equal area, NAD83) (Klokan Technologies, 2020) and this is suggested by the message(), if proj4string=NA. Unprojected data are returned unless the proj4string is explicitly given;
usesp	A logical to actually trigger sp::SpatialPointsDataFrame(), otherwise a merger (total aggregation) of the site information as an R data.frame is simply returned. This is provided in case problems with spatial conversion occur;
silent	Suppress informative calls to message(); and
...	Additional arguments to pass (see source code to ascertain flexible usage).

Value

A SpatialPointsDataFrame of the sp package unless usesp=FALSE at which point a standard R data.frame is returned. For the standard data.frame option, a vector of bad sites, which are sites for which the web interface of NWIS does not know about, is stored in the attribute triggered as attr("bad sites"). Bad sites can be those for which the number has never been a USGS number and perhaps these numbers are mistakes on part of the user. There is another possibility. A user might have acquired a valid USGS streamgage identification number for some really old and also likely short record site that did not “fully make it” to the digital age. It is possible that internal USGS database access might find some information about these.

Also the akqdecay package is oriented around streamflow processing. To this end, columns related to groundwater site information are removed (see source code). Also, 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 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

Klokan Technologies, 2020, EPSG.io—Find coordinate systems worldwide: Unterageri, Switzerland, Klokan Technologies GmbH, digital data, accessed July 15, 2020, at https://epsg.io/. [Geographic coordinates directly accessible at https://epsg.io/4269; Albers equal area projection directly accessible at https://epsg.io/5070.]

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

Examples

## Not run: 
ms_sites <- c("07288000", "07288500") # Streamgages on the Sunflower River, MS
spSites  <- sites_to_SpatialPointsDataFrame2(ms_sites, proj4string="+init=epsg:5070")
plot(spSites)

# This example needs to stop at the plot(), but for a stubout of how results
# could be combined to the spatial data frame:
#ms_dv <- new.env(); fill_dvenv(ms_sites,     envir=ms_dv)
#ms_ak <- new.env(); fill_akqenv(dvenv=ms_dv, envir=ms_ak)
#
#LM <- akq_lmom(ms_ak); LM$site_no <- LM$site
#spSites <- merge(spSites, LM)
#head(spSites@data) #
## End(Not run)

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