mnget: Retrieve USGS Discharge Monthly Values structured in the...

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

Description

Retrieve U.S. Geological Survey (USGS) daily mean-streamflow values for a streamgage identification number. This function is a wrapper on dataRetrieval::readNWISstat() to provide an abstraction layer to the dataRetrieval package. The mnget function adds some additional information for purpose of the akqdecay package. The function creates the canonical daily-mean streamflow table (an R data.frame) to be picked up in turn by the akqdecay function of this package. The function fill_mnenv is a wrapper that can be used to fill an R environment with the output of the akqdecay function. Users interested in monthly values might be especially interested in the monthly computations based on the daily streamflows but with the inclusion of separated streamflow in dvpart and fill_dvpartenv (see Examples in dvpart for a demonstration).

Usage

mnget(siteNumber, sdate="", edate="", flowlo=NULL, flowhi=NULL,
                  silent=FALSE,
                  drsilent=TRUE, drget=FALSE, pCode="00060", message="", ...)

Arguments

siteNumber	USGS streamgage identification number and nomenclature matches that of the dataRetrieval package. Multiple site numbers can be provided because the underlying dataRetrieval::readNWISstat() supports that and the resulting behavior should be about the same between these two functions. A warning message though is shown. This is important because akqdecay is not vectorized to handle multiple streamgages and will trigger a stop() in execution—Multiple streamgages should be processed through fill_mnenv and fill_akqenv;
sdate	Start date (default is earliest) and nomenclature matches that of the dataRetrieval package with string format of “YYYY-MM” for year (YYYY) and month (MM) respectively padded by zeros as needed;
edate	Ending date (default is earliest) and nomenclature matches that of the dataRetrieval package with string format of “YYYY-MM” for year (YYYY) and month (MM) padded by zeros as needed;
flowlo	Optional lower streamflow threshold on which to convert to NA (to keep continuous day time stamps) through Q > flowlo \rightarrow NA;
flowhi	Optional upper streamflow threshold on which to convert to NA (to keep continuous day time stamps) through Q < flowhi \rightarrow NA;
silent	Suppress informative calls to message;
drsilent	The argument though converted to “silent” that is passed to try for a level of informative error trapping on top of dataRetrieval::readNWISstat();
drget	If set, the retrieval from dataRetrieval::readNWISstat() is immediately returned following the internal call to dataRetrieval::renameNWISColumns();
pCode	Parameter code (default is discharge [streamflow]) and nomenclature almost matches that of the dataRetrieval package;
message	An optional string that if populated will trigger a message() call that a user might find useful in massive batch processing operations; and
...	Additional arguments to pass to function dataRetrieval::readNWISstat().

Value

An R data.frame is returned with these expected columns. Some streamgages can have multiple discharges descriptors typed as monthly values—Is this actually true for monthly flows? Only the Flow column is handled by akqdecay.

agency_cd	The agency code for the data;
site_no	The streamgage identification number;
site	The streamgage identification number;
year	The calendar year of the date;
month	The month;
decade	The decade of the daily value. The decade is assign by taking the year and the trailing digit has been stripped and replaced with zero. This is not a technique in which a “decade” is centered on an even step of 10—meaning, say that 1996–2005 is not the “2000 decade” but simply 01/*/2000–12/*/2009 is the “2000 decade”; and
Flow	The streamflow in cubic feet per second, note that the capitalization is from the dataRetrieval package, elsewhere in akqdecay this will become lower case or an alternative name for streamflow.

Note

For the greater purposes of the akqdecay package, the argument pCode for the defaults is expected to be left untouched. The capitalization inconsistency in the returned R data.frame is left intact as it is consistent with the operation of the dataRetrieval::renameNWISColumns() function that is called internally. But at the time of this development (July 2018), the renaming has no effect.

Author(s)

W.H. Asquith

References

Hirsch, R.M., and De Cicco, L.A., 2015, User guide to Exploration and Graphics for RivEr Trends (EGRET) and dataRetrieval: R packages for hydrologic data (version 2.0, February 2015): U.S. Geological Survey Techniques and Methods book 4, chap. A10, 93 p., https://doi.org/10.3133/tm4A10.

See Also

fill_mnenv

Examples

## Not run: 
# USGS 14362000 Applegate River near Copper, Oregon
Copper <- mnget("14362000", sdate="1940-01", edate="1942-06")
print(Copper) # An inspection of the retrieved monthly values. #
## End(Not run)

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