readNWISwatstore: Read NWIS WATSTORE-Formatted Period of Record Peak...
In MGBT: Multiple Grubbs-Beck Low-Outlier Test

Description Usage Arguments Value Author(s) References See Also Examples

Read U.S. Geological Survey (USGS) National Water Information System (NWIS) (U.S. Geological Survey, 2019) peak streamflows. But with a major high-level twist what is retained or produced by the operation. This function retrieves the WATSTORE formatted version of the peak streamflow data on a streamgage by streamgage basis and this is the format especially suitable for the USGS PeakFQ software (U.S. Geological Survey, 2020). That format will reflect the period of record. This function uses direct URL pathing to NWIS to retrieve this format and write the results to the user's file system. The function does not use the dataRetrieval package for the WATSTORE format. Then optionally, this function uses the dataRetrieval package to retrieve a tab-delimited version of the peak streamflows and write those to the user's file system. Peak streamflow visualization with attention to the peak discharge qualification codes and other features is optionally made here by the plotPeaks function and optionally a portable document formatted graphics file can be written as well. This function is explicitly design around a single directory for each streamgage to store the retrieved and plotted data.

1
2
3

readNWISwatstore(siteNumbers, path=".", dirend="d",
                              tabpk=TRUE, vispk=TRUE, vispdf=TRUE,
                              unlinkpath=FALSE, citeNWISdoi=TRUE, ...)

`siteNumbers`	USGS site number(or multiple sites) as string(s). This is usually an 8 digit number but not exclusively so and is the `site_no` slot in the NWIS database. The WATSTORE formatted data will be written into file name being set to `site_no".pkf"` (the extension `".pkf"` is to be read as “peak flows”);
`path`	A directory path with default to current working directory;
`dirend`	Optional character content appended to the site number as part of directory creation. For example, if the `site_no` is `08167000` and the default `dirend="d"`, then if the `path` is the current working directory, then the full path to the directory staged to contain results of this function is `./08167000d`;
`tabpk`	A logical to trigger writing of the period of record of the peak streamflows in a tab-delimited format by the `write.table()` function with the file name being set to `site_no".txt"`;
`vispk`	A logical to trigger `plotPeaks` for the peak streamflow visualization;
`vispdf`	A logical to trigger `pdf()` and `dev.off()` to create a portable document format of the peak streamflow visualization by `plotPeaks` file name being set to `site_no".pdf"`;
`unlinkpath`	A logical to trigger unlinking of the full path ahead of its recreation and then operation of the side effects of this function. The unlinking is recursive, so attention to settings of `path` and `dirend` are self evident;
`citeNWISdoi`	A logical to trigger the writing of a `CITATION.md` file to the NWIS DOI on the date of the retrieval. It is USGS policy to use the citation to NWIS by its digital object identifier (DOI) and provide an accessed date. The`CITATION.md` has been written in a simple markdown format so that software repository infrastructure (such as https://code.usgs.gov) would markup this file to a simple web page when selected by the user in an internet browser; and
`...`	Additional arguments to pass to `plotPeaks`.

No values are returned; this function is used for its file system side effects. Those effects will include ".pkf" (WATSTORE formatted peak streamflow data) and potentially include the following additional file by extension: ".pdf", ".txt" (tab-delimited peak streamflow data), and CITATION.md file recording a correct policy-compliant citation to the USGS NWIS DOI number with access date as per additional arguments to this function. This function does not recognize the starting and ending period options that the dataRetrieval package provides because the WATSTORE format is ensured to be period of record. Therefore, the disabling of optional period retrievals ensures that the ".pkf" and ".[txt|pdf]" files have the same data.

W.H. Asquith

U.S. Geological Survey, 2019, USGS water data for the Nation: U.S. Geological Survey National Water Information System database, accessed October 11, 2019, at doi: 10.5066/F7P55KJN.

U.S. Geological Survey, 2020, PeakFQ—Flood frequency analysis based on Bulletin 17C and recommendations of the Advisory Committee on Water Information (ACWI) Subcommittee on Hydrology (SOH) Hydrologic Frequency Analysis Work Group (HFAWG), version 7.3, accessed February 1, 2020, at https://water.usgs.gov/software/PeakFQ/.

plotPeaks

  # The dataRetrieval package provides a readNWISpeak() function but that works on
  # the tab-delimited like format structure and not the WATSTORE structure. The
  # WATSTORE structure is used by the USGS PeakFQ software and direct URL is needed
  # to acquire such data
  path <- tempdir()
  readNWISwatstore("08167000", path=path)
  # path/08167000d/08167000.[pdf|pkf|txt]
  #                CITATION.md
  # files will be created in the temporary directory