ReadNWISData: Read USGS NWIS Data
In jfisher-usgs/ObsNetwork: Optimization of Observation Networks

Description Usage Arguments Format Details Value Author(s) See Also Examples

This function reads water-level measurements exported from the U.S. Geological Survey (USGS) National Water Information System (NWIS) database and summarizes this data for a specified duration of time.

1	ReadNWISData(file, dt.lim, dt.fmt = "%Y-%m-%d %H:%M", sep = "\t")

`file`	`character`; a path to the file to be opened.
`dt.lim`	`character`; a vector of length 2 giving the starting and ending date-time limits. Measurements recorded during this time period are used to calculate the median water-level elevation `var1` and mean measurement accuracy `var1.acy`. Defaults to the entire period of record.
`dt.fmt`	`character`; a date-time format as used by `strptime`. Date-time values specified in `dt.lim` must be provided in this format.
`sep`	`character`; the field separator string. Values on each line of the file are separated by this string, its default is the tab separator.

The input text file contains the names of the variables in its first line. Each subsequent line corresponds to a single water-level measurement. Measurement variables (columns in the data table) include:

SITE_NO: is the site number.
DEC_LONG_VA: is the decimal longitude.
DEC_LAT_VA: is the decimal latitude.
COORD_ACY_CD: is the latitude/longitude coordinate accuracy code (optional).
COORD_DATUM_CD: is the latitude/longitude (horizontal) coordinate datum code (optional).
COORD_METH_CD: is the code indicating the method used to determine horizontal datum (optional).
ALT_VA: is the gage or land-surface datum, in feet.
ALT_ACY_VA: is the accuracy of land-surface datum, in feet.
ALT_DATUM_CD: is a code indicating the geodetic or local vertical datum of the elevation datum elevation component (optional); for example, "NGVD29" or "NAVD88".
ALT_METH_CD: is a code indicating the method used to determine the elevation of land-surface datum (optional).
HOLE_DEPTH_VA: is the borehole depth, in feet (optional).
WELL_DEPTH_VA: is the well depth, in feet (optional).
LEV_DT: is the date/time when water-level measurement was recorded. The expected conversion specification format is "%Y-%m-%d %H:%M:%S"; see strftime for details.
LEV_VA: is the water-level measurement referenced to land-surface datum (that is, depth below land surface), in feet.
LEV_ACY_CD: is a water-level measurement accuracy code.
LEV_METH_CD: is a code indicating how the water level was measured (optional).
STATION_NM: is the site name (optional).
NETWORK_NM: is the water-level monitoring network name (optional). Sites belonging to multiple networks should be comma separated. This variable is not included in the NWIS database and it is tasked to the user to populate this field.

This function is a pre-processor for ObsNetwork. Groundwater data can be downloaded at NWISWeb.

Returns an object of SpatialPointsDataFrame-class with the following components:

`site.no`	`numeric`; a unique identifier for site.
`var1`	`numeric`; the median value of the water-level elevation, in meters, for the time period defined by `dt.lim`.
`var1.acy`	`numeric`; the mean measurement accuracy of the water-level elevation, in meters, for the time period defined by `dt.lim`. This variable is calculated from the summation of `alt.acy.va` and `lev.acy.va` values.
`var1.sd`	`numeric`; the standard deviation of the water-level elevation, in meters, for the entire period of record.
`var2`	`numeric`; the land-surface datum, in meters.
`map.no`	`integer`; an identifier (row index number) used to locate sites on map.
`network.nm`	`character`; the monitoring network name.
`nrec.por`	`integer`; the number of records in the entire period of record.
`nrec`	`integer`; the number of records in the time period defined by `dt.lim`.
`alt.acy.va`	`numeric`; the accuracy of land-surface datum, in meters.
`lev.acy.va`	`numeric`; the mean water-level measurement accuracy, in meters, for the time period defined by `dt.lim`.
`coord.acy.va`	`numeric`; the latitude/longitude coordinate accuracy, in arc-seconds.
`coord.meth.cd`	`character`; the method used to determine horizontal datum.
`alt.meth.cd`	`character`; the method used to determine elevation at land-surface datum.
`lev.meth.cd`	`character`; all methods used to determine water levels, comma separated.
`site.nm`	`character`; the site name.

J.C. Fisher

read.table, as.POSIXct

# Read data from text file
file <- system.file("extdata/ESRP_NWIS.tsv", package = "ObsNetwork")
dt.lim <- c("2008-01-01 00:00", "2008-12-31 23:59") # 2008 calendar year
obj <- ReadNWISData(file, dt.lim)
str(obj)

# Compare with available data set
data(ESRP_NWIS)
identical(obj, ESRP_NWIS)