Background

USGS streamflow observations are a primary source of hydrologic information and often used for validation and calibration of hydrlogic models. Recently, web services have been developed at NWIS and the dataRetrieval R package have emerged to make it easy to get USGS data into R.

This vignette demonstrates some rwrfhydro tools to collect, store, and manipulate USGS data. These are built ontop of the dataRetrieval package. As with the rest of the rwrfhydro package, development is on-going. Currently, we focus on instantaneous stream data observations from NWIS. The tools build a local database which has not yet been developed to allow appending (i.e. only grabbing and adding) observations beyond those existing locally. But there is enough existing functionality to make its exposition worthwhile. Check for updates to this vignette.

The fundamental layout of the local database is simply a directory containing:

Generally, there are two basic kinds of functions: “Get” and “Query”. Get functions use dataRetrieval functions to actually go out to NWIS and “get” data and metadata. Query functions query the local database. There are exceptions to this.

Setup

Load the rwrfhydro package.

library("rwrfhydro")
## To check rwrfhydro updates run: CheckForUpdates()

This is the path to the directory where you want your database to be built:

dbPath <- '~/wrfHydroTestCases/usgsDb/' 

Discover gage locations, get data, and save to local database.

Perhaps you know the lat/lon of a gage (e.g. from frxst_pts_out.txt) and you need the HUC8. The within argument is taken to be in decimal degrees.

stnDf <- FindUsgsStns(stnLon=254.67374999999998408, 
                      stnLat=40.018666670000001773,
                      within=.001)
str(stnDf)
## 'data.frame':    1 obs. of  12 variables:
##  $ stnLon       : num 255
##  $ stnLat       : num 40
##  $ within       : num 0.001
##  $ siteType     : chr "ST"
##  $ hasDataTypeCd: chr "iv"
##  $ agency_cd    : chr "USGS"
##  $ site_no      : chr "06727500"
##  $ station_nm   : chr "FOURMILE CREEK AT ORODELL, CO"
##  $ site_tp_cd   : chr "ST"
##  $ dec_lat_va   : num 40
##  $ dec_long_va  : num -105
##  $ queryTime    : POSIXct, format: "2015-05-05 12:40:47"

Now you have the site_no or station ID number, “06727500”. You could have also used FindUsgsStns() to reveal the gages in the HUC8, if you knew the HUC8 code. Because we organize the database by HUC8, we have a function to get HUC8 from station id. Then we get the above information for all locations in the HUC8.

huc8 <- GetSiteHuc(stnDf$site_no)
str(FindUsgsStns(huc=huc8))
## 'data.frame':    8 obs. of  10 variables:
##  $ huc8         : Factor w/ 1 level "10190005": 1 1 1 1 1 1 1 1
##  $ siteType     : chr  "ST" "ST" "ST" "ST" ...
##  $ hasDataTypeCd: chr  "iv" "iv" "iv" "iv" ...
##  $ agency_cd    : chr  "USGS" "USGS" "USGS" "USGS" ...
##  $ site_no      : chr  "06727410" "06730160" "06727500" "06730200" ...
##  $ station_nm   : chr  "FOURMILE CREEK AT LOGAN MILL ROAD NEAR CRISMAN, CO" "FOURMILE CANYON CREEK NEAR SUNSHINE, CO" "FOURMILE CREEK AT ORODELL, CO" "BOULDER CREEK AT NORTH 75TH ST. NEAR BOULDER, CO" ...
##  $ site_tp_cd   : chr  "ST" "ST" "ST" "ST" ...
##  $ dec_lat_va   : num  40 40.1 40 40.1 40.1 ...
##  $ dec_long_va  : num  -105 -105 -105 -105 -105 ...
##  $ queryTime    : POSIXct, format: "2015-05-05 12:40:51" "2015-05-05 12:40:51" "2015-05-05 12:40:51" "2015-05-05 12:40:51" ...

FindUsgsStns is a wrapper on dataRetrieval::whatNWISsites which has been written to focus on instantaneous values. (It is worth noting the flexibility and generality of the underlying function.)

Now pull the data for this HUC8. Currently, this grabs all available products for the HUC. Note that the HUC data are organized by product code (e.g. 00060) then by data and meta in the returned list. (Also note that this command sometimes fails on the remote end and may need to be rerun.) In meta, siteInfo is the meta that we use in querying the local data base in commands shown below.

coData <- GetUsgsHucData(huc=huc8)
str(coData)
str(coData)
## List of 2
##  $ 00060:List of 2
##   ..$ data:'data.frame': 1265329 obs. of  6 variables:
##   .. ..$ agency_cd       : chr [1:1265329] "USGS" "USGS" "USGS" "USGS" ...
##   .. ..$ site_no         : chr [1:1265329] "06724970" "06724970" "06724970" "06724970" ...
##   .. ..$ dateTime        : POSIXct[1:1265329], format: "2014-03-06 07:00:00" "2014-03-06 07:10:00" "2014-03-06 07:20:00" "2014-03-06 07:30:00" ...
##   .. ..$ tz_cd           : chr [1:1265329] "UTC" "UTC" "UTC" "UTC" ...
##   .. ..$ X_00060_00011_cd: chr [1:1265329] "A" "A" "A" "A" ...
##   .. ..$ X_00060_00011   : num [1:1265329] 11 11 11 12 12 13 13 13 13 13 ...
##   ..$ meta:List of 3
##   .. ..$ siteInfo     :'data.frame': 8 obs. of  46 variables:
##   .. .. ..$ site_no              : chr [1:8] "06724970" "06725450" "06727410" "06727500" ...
##   .. .. ..$ agency_cd            : chr [1:8] "USGS" "USGS" "USGS" "USGS" ...
##   .. .. ..$ dec_lat_va           : num [1:8] 40.1 40.2 40 40 40.1 ...
##   .. .. ..$ dec_long_va          : num [1:8] -105 -105 -105 -105 -105 ...
##   .. .. ..$ huc_cd               : chr [1:8] "10190005" "10190005" "10190005" "10190005" ...
##   .. .. ..$ site_tp_cd           : chr [1:8] "ST" "ST" "ST" "ST" ...
##   .. .. ..$ state_cd             : chr [1:8] "08" "08" "08" "08" ...
##   .. .. ..$ station_nm           : chr [1:8] "LEFT HAND CREEK AT HOVER ROAD NEAR LONGMONT, CO" "ST. VRAIN CREEK BELOW LONGMONT, CO" "FOURMILE CREEK AT LOGAN MILL ROAD NEAR CRISMAN, CO" "FOURMILE CREEK AT ORODELL, CO" ...
##   .. .. ..$ tz_cd                : chr [1:8] "MST" "MST" "MST" "MST" ...
##   .. .. ..$ lat_va               : num [1:8] 400803 400927 400231 400107 400327 ...
##   .. .. ..$ long_va              : num [1:8] 1050751 1050055 1052154 1051934 1052056 ...
##   .. .. ..$ coord_meth_cd        : chr [1:8] "N" "N" "M" "N" ...
##   .. .. ..$ coord_acy_cd         : chr [1:8] "M" "5" "1" "5" ...
##   .. .. ..$ coord_datum_cd       : chr [1:8] "NAD83" "NAD83" "NAD83" "NAD83" ...
##   .. .. ..$ dec_coord_datum_cd   : chr [1:8] "NAD83" "NAD83" "NAD83" "NAD83" ...
##   .. .. ..$ district_cd          : chr [1:8] "08" "08" "08" "08" ...
##   .. .. ..$ county_cd            : chr [1:8] "013" "123" "013" "013" ...
##   .. .. ..$ country_cd           : chr [1:8] "US" "US" "US" "US" ...
##   .. .. ..$ land_net_ds          : chr [1:8] "  SWSWS16 T02N  R69W  6" "  NWNWS09 T002N R068W" "  NWNES20 T01N  R71W" "  NWSES27 T001N R071W" ...
##   .. .. ..$ map_nm               : chr [1:8] "HYGIENE, CO" "LONGMONT, CO" "BOULDER, CO" "BOULDER, CO" ...
##   .. .. ..$ map_scale_fc         : chr [1:8] "  24000" "  24000" "  24000" "  24000" ...
##   .. .. ..$ alt_va               : num [1:8] 4994 4852 6341 5750 6639 ...
##   .. .. ..$ alt_meth_cd          : chr [1:8] "N" "M" "N" "M" ...
##   .. .. ..$ alt_acy_va           : num [1:8] 4.3 10 4.3 15 4.3 10 10 4.3
##   .. .. ..$ alt_datum_cd         : chr [1:8] "NAVD88" "NGVD29" "NAVD88" "NGVD29" ...
##   .. .. ..$ basin_cd             : chr [1:8] "06" "06" "" "06" ...
##   .. .. ..$ topo_cd              : chr [1:8] "" "" "C" "" ...
##   .. .. ..$ instruments_cd       : chr [1:8] "YNNNYNNNNNNNNNNNNNNNNNNNNNNNNN" "NNNNYNNNNNNNNNNNNNNNNNNNNNNNNN" "NNNNYNYNNYNNNNNNNNNNNNNNNNNNNN" "NNNNYNYNNYNNNNNNNNNNNNNNNNNNNN" ...
##   .. .. ..$ construction_dt      : chr [1:8] "" "" "" "" ...
##   .. .. ..$ inventory_dt         : chr [1:8] "20140304" "" "20110317" "20110323" ...
##   .. .. ..$ drain_area_va        : num [1:8] 71.6 423 19.2 24.2 1.8 307 447 NA
##   .. .. ..$ contrib_drain_area_va: num [1:8] NA NA NA NA NA NA NA NA
##   .. .. ..$ local_time_fg        : chr [1:8] "Y" "Y" "Y" "Y" ...
##   .. .. ..$ reliability_cd       : chr [1:8] "U" "" "" "" ...
##   .. .. ..$ gw_file_cd           : chr [1:8] " Y" "NYNNNNNN" " Y" "NYNNNNNN" ...
##   .. .. ..$ nat_aqfr_cd          : chr [1:8] "" "" "" "" ...
##   .. .. ..$ aqfr_cd              : chr [1:8] "" "" "" "" ...
##   .. .. ..$ aqfr_type_cd         : chr [1:8] "" "" "" "" ...
##   .. .. ..$ well_depth_va        : num [1:8] NA NA NA NA NA NA NA NA
##   .. .. ..$ hole_depth_va        : num [1:8] NA NA NA NA NA NA NA NA
##   .. .. ..$ depth_src_cd         : chr [1:8] "" "" "" "" ...
##   .. .. ..$ project_no           : chr [1:8] "00001200" "" "000012000" "000012000" ...
##   .. .. ..$ timeZoneOffset       : chr [1:8] "-07:00" "-07:00" "-07:00" "-07:00" ...
##   .. .. ..$ srs                  : chr [1:8] "EPSG:4326" "EPSG:4326" "EPSG:4326" "EPSG:4326" ...
##   .. .. ..$ startTime            : POSIXct[1:8], format: "2014-03-06 07:00:00" "2007-10-01 06:00:00" "2011-04-01 07:00:00" "2011-04-01 06:00:00" ...
##   .. .. ..$ endTime              : POSIXct[1:8], format: "2015-04-29 21:10:00" "2013-09-12 05:45:00" "2013-09-12 05:55:00" "2015-04-29 21:10:00" ...
##   .. ..$ variableInfo :'data.frame': 1 obs. of  6 variables:
##   .. .. ..$ parameterCd   : chr "00060"
##   .. .. ..$ parameter_nm  : chr "Streamflow, ft&#179;/s"
##   .. .. ..$ parameter_desc: chr "Discharge, cubic feet per second"
##   .. .. ..$ valueType     : chr "Derived Value"
##   .. .. ..$ param_units   : chr "ft3/s"
##   .. .. ..$ noDataValue   : logi NA
##   .. ..$ statisticInfo:'data.frame': 1 obs. of  2 variables:
##   .. .. ..$ statisticName: chr ""
##   .. .. ..$ statisticCd  : chr "00011"
##  $ 00065:List of 2
##   ..$ data:'data.frame': 71329 obs. of  6 variables:
##   .. ..$ agency_cd       : chr [1:71329] "USGS" "USGS" "USGS" "USGS" ...
##   .. ..$ site_no         : chr [1:71329] "06724970" "06724970" "06724970" "06724970" ...
##   .. ..$ dateTime        : POSIXct[1:71329], format: "2014-12-30 07:00:00" "2014-12-30 07:10:00" "2014-12-30 07:20:00" "2014-12-30 07:30:00" ...
##   .. ..$ tz_cd           : chr [1:71329] "UTC" "UTC" "UTC" "UTC" ...
##   .. ..$ X_00065_00011_cd: chr [1:71329] "P" "P" "P" "P" ...
##   .. ..$ X_00065_00011   : num [1:71329] 6.86 6.86 6.85 6.86 6.86 6.87 6.86 6.86 6.85 6.84 ...
##   ..$ meta:List of 3
##   .. ..$ siteInfo     :'data.frame': 6 obs. of  46 variables:
##   .. .. ..$ site_no              : chr [1:6] "06724970" "06727500" "06730160" "06730200" ...
##   .. .. ..$ agency_cd            : chr [1:6] "USGS" "USGS" "USGS" "USGS" ...
##   .. .. ..$ dec_lat_va           : num [1:6] 40.1 40 40.1 40.1 40.1 ...
##   .. .. ..$ dec_long_va          : num [1:6] -105 -105 -105 -105 -105 ...
##   .. .. ..$ huc_cd               : chr [1:6] "10190005" "10190005" "10190005" "10190005" ...
##   .. .. ..$ site_tp_cd           : chr [1:6] "ST" "ST" "ST" "ST" ...
##   .. .. ..$ state_cd             : chr [1:6] "08" "08" "08" "08" ...
##   .. .. ..$ station_nm           : chr [1:6] "LEFT HAND CREEK AT HOVER ROAD NEAR LONGMONT, CO" "FOURMILE CREEK AT ORODELL, CO" "FOURMILE CANYON CREEK NEAR SUNSHINE, CO" "BOULDER CREEK AT NORTH 75TH ST. NEAR BOULDER, CO" ...
##   .. .. ..$ tz_cd                : chr [1:6] "MST" "MST" "MST" "MST" ...
##   .. .. ..$ lat_va               : num [1:6] 400803 400107 400327 400306 400820 ...
##   .. .. ..$ long_va              : num [1:6] 1050751 1051934 1052056 1051042 1050113 ...
##   .. .. ..$ coord_meth_cd        : chr [1:6] "N" "N" "G" "M" ...
##   .. .. ..$ coord_acy_cd         : chr [1:6] "M" "5" "S" "M" ...
##   .. .. ..$ coord_datum_cd       : chr [1:6] "NAD83" "NAD83" "NAD83" "NAD27" ...
##   .. .. ..$ dec_coord_datum_cd   : chr [1:6] "NAD83" "NAD83" "NAD83" "NAD83" ...
##   .. .. ..$ district_cd          : chr [1:6] "08" "08" "08" "08" ...
##   .. .. ..$ county_cd            : chr [1:6] "013" "013" "013" "013" ...
##   .. .. ..$ country_cd           : chr [1:6] "US" "US" "US" "US" ...
##   .. .. ..$ land_net_ds          : chr [1:6] "  SWSWS16 T02N  R69W  6" "  NWSES27 T001N R071W" "      S09 T01N  R71W  6" "  SENWS13 T001N R070W" ...
##   .. .. ..$ map_nm               : chr [1:6] "HYGIENE, CO" "BOULDER, CO" "BOULDER, CO" "" ...
##   .. .. ..$ map_scale_fc         : chr [1:6] "  24000" "  24000" "  24000" "" ...
##   .. .. ..$ alt_va               : num [1:6] 4994 5750 6639 5106 4860 ...
##   .. .. ..$ alt_meth_cd          : chr [1:6] "N" "M" "N" "M" ...
##   .. .. ..$ alt_acy_va           : num [1:6] 4.3 15 4.3 10 10 4.3
##   .. .. ..$ alt_datum_cd         : chr [1:6] "NAVD88" "NGVD29" "NAVD88" "NGVD29" ...
##   .. .. ..$ basin_cd             : chr [1:6] "06" "06" "06" "" ...
##   .. .. ..$ topo_cd              : chr [1:6] "" "" "" "" ...
##   .. .. ..$ instruments_cd       : chr [1:6] "YNNNYNNNNNNNNNNNNNNNNNNNNNNNNN" "NNNNYNYNNYNNNNNNNNNNNNNNNNNNNN" "NNNNYNNNNYNNNNNNNNNNNNNNNNNNNN" "YNNNYNNNNNNNNNNNNNNNNNNNNNNNNN" ...
##   .. .. ..$ construction_dt      : chr [1:6] "" "" "20120416" "" ...
##   .. .. ..$ inventory_dt         : chr [1:6] "20140304" "20110323" "" "" ...
##   .. .. ..$ drain_area_va        : num [1:6] 71.6 24.2 1.8 307 447 NA
##   .. .. ..$ contrib_drain_area_va: num [1:6] NA NA NA NA NA NA
##   .. .. ..$ local_time_fg        : chr [1:6] "Y" "Y" "Y" "Y" ...
##   .. .. ..$ reliability_cd       : chr [1:6] "U" "" "" "" ...
##   .. .. ..$ gw_file_cd           : chr [1:6] " Y" "NYNNNNNN" " Y" "NYNNNNNN" ...
##   .. .. ..$ nat_aqfr_cd          : chr [1:6] "" "" "" "" ...
##   .. .. ..$ aqfr_cd              : chr [1:6] "" "" "" "" ...
##   .. .. ..$ aqfr_type_cd         : chr [1:6] "" "" "" "" ...
##   .. .. ..$ well_depth_va        : num [1:6] NA NA NA NA NA NA
##   .. .. ..$ hole_depth_va        : num [1:6] NA NA NA NA NA NA
##   .. .. ..$ depth_src_cd         : chr [1:6] "" "" "" "" ...
##   .. .. ..$ project_no           : chr [1:6] "00001200" "000012000" "000012000" "" ...
##   .. .. ..$ timeZoneOffset       : chr [1:6] "-07:00" "-07:00" "-07:00" "-07:00" ...
##   .. .. ..$ srs                  : chr [1:6] "EPSG:4326" "EPSG:4326" "EPSG:4326" "EPSG:4326" ...
##   .. .. ..$ startTime            : POSIXct[1:6], format: "2014-12-30 07:00:00" "2015-03-27 16:15:00" "2015-03-27 19:35:00" "2014-12-30 07:00:00" ...
##   .. .. ..$ endTime              : POSIXct[1:6], format: "2015-04-29 21:10:00" "2015-04-29 21:10:00" "2015-04-29 21:20:00" "2015-04-29 21:15:00" ...
##   .. ..$ variableInfo :'data.frame': 1 obs. of  6 variables:
##   .. .. ..$ parameterCd   : chr "00065"
##   .. .. ..$ parameter_nm  : chr "Gage height, ft"
##   .. .. ..$ parameter_desc: chr "Gage height, feet"
##   .. .. ..$ valueType     : chr "Derived Value"
##   .. .. ..$ param_units   : chr "ft"
##   .. .. ..$ noDataValue   : logi NA
##   .. ..$ statisticInfo:'data.frame': 1 obs. of  2 variables:
##   .. .. ..$ statisticName: chr ""
##   .. .. ..$ statisticCd  : chr "00011"
##  - attr(*, "split_type")= chr "data.frame"
##  - attr(*, "split_labels")='data.frame': 2 obs. of  1 variable:
##   ..$ parm_cd: chr [1:2] "00060" "00065"

Now save this data to the local database. Note that this also could have been achieved by specifying the outPath argument to GetUsgsHucData.

coFiles <- SaveHucData(coData, outPath=dbPath)
coFiles

For a little more variety of HUCs in the database, let’s also grab the following HUC.

filesAL <- GetUsgsHucData(huc='03160203', outPath=dbPath) ## Satilpa, AL

Query the local data

Now we work entirely locally, having grabbed the data of interest. For all HUC8 and products, any of the siteInfo metadata can be retrieved from the local DB. Note that the same site is repeated for multiple products.

QuerySiteInfo(c('station_nm','site_no','dec_lat_va','dec_long_va'), path=dbPath)
station_nm site_no dec_lat_va dec_long_va product HUC8
LEFT HAND CREEK AT HOVER ROAD NEAR LONGMONT, CO 06724970 40.13428 -105.13082 00060 10190005
ST. VRAIN CREEK BELOW LONGMONT, CO 06725450 40.15742 -105.01539 00060 10190005
FOURMILE CREEK AT LOGAN MILL ROAD NEAR CRISMAN, CO 06727410 40.04203 -105.36492 00060 10190005
FOURMILE CREEK AT ORODELL, CO 06727500 40.01867 -105.32625 00060 10190005
FOURMILE CANYON CREEK NEAR SUNSHINE, CO 06730160 40.05761 -105.34878 00060 10190005
BOULDER CREEK AT NORTH 75TH ST. NEAR BOULDER, CO 06730200 40.05165 -105.17888 00060 10190005
BOULDER CREEK AT MOUTH NEAR LONGMONT, CO 06730500 40.13878 -105.02022 00060 10190005
ST VRAIN CR BLW BOULDER CR AT HWY 119 NR LONGMONT 06730525 40.16035 -105.00783 00060 10190005
LEFT HAND CREEK AT HOVER ROAD NEAR LONGMONT, CO 06724970 40.13428 -105.13082 00065 10190005
FOURMILE CREEK AT ORODELL, CO 06727500 40.01867 -105.32625 00065 10190005
FOURMILE CANYON CREEK NEAR SUNSHINE, CO 06730160 40.05761 -105.34878 00065 10190005
BOULDER CREEK AT NORTH 75TH ST. NEAR BOULDER, CO 06730200 40.05165 -105.17888 00065 10190005
BOULDER CREEK AT MOUTH NEAR LONGMONT, CO 06730500 40.13878 -105.02022 00065 10190005
ST VRAIN CR BLW BOULDER CR AT HWY 119 NR LONGMONT 06730525 40.16035 -105.00783 00065 10190005
TOMBIGBEE R AT COFFEEVILLE L&D NR COFFEEVILLE, AL. 02469761 31.75849 -88.12918 00060 03160203
SATILPA CREEK NEAR COFFEEVILLE AL 02469800 31.74432 -88.02251 00060 03160203
BASSETT CREEK AT US HIGHWAY 43 NR THOMASVILLE, AL. 02470072 31.86404 -87.74722 00060 03160203
TOMBIGBEE R AT COFFEEVILLE L&D NR COFFEEVILLE, AL. 02469761 31.75849 -88.12918 00065 03160203
TOMBIGBEE R BL COFFEEVILLE L&D NEAR COFFEEVILLE 02469762 31.75710 -88.12501 00065 03160203
SATILPA CREEK NEAR COFFEEVILLE AL 02469800 31.74432 -88.02251 00065 03160203
TOMBIGBEE RIVER AT STEAMPLANT NR LEROY, AL 02470050 31.48600 -87.90889 00065 03160203
BASSETT CREEK AT US HIGHWAY 43 NR THOMASVILLE, AL. 02470072 31.86404 -87.74722 00065 03160203
TOMBIGBEE R AT COFFEEVILLE L&D NR COFFEEVILLE, AL. 02469761 31.75849 -88.12918 45592 03160203

Say you just want Orodell and you want your code to be readable: translate the name to the code with QuerySiteName (which translates both ways).

dataOrodell <- QuerySiteData(QuerySiteName("FOURMILE CREEK AT ORODELL, CO", path=dbPath), 
                             product='00060', path=dbPath)
str(dataOrodell)
## 'data.frame':    212472 obs. of  5 variables:
##  $ site_no : chr  "06727500" "06727500" "06727500" "06727500" ...
##  $ dateTime: POSIXct, format: "2011-04-01 06:00:00" "2011-04-01 06:05:00" "2011-04-01 06:10:00" "2011-04-01 06:15:00" ...
##  $ code    : chr  "A" "A" "A" "A" ...
##  $ value   : num  1.2 1.2 1.2 1.2 1.2 1.2 1.2 1.2 1.2 1.2 ...
##  $ variable: chr  "X_00060_00011" "X_00060_00011" "X_00060_00011" "X_00060_00011" ...
##  - attr(*, "siteInfo")='data.frame': 1 obs. of  46 variables:
##   ..$ site_no              : chr "06727500"
##   ..$ agency_cd            : chr "USGS"
##   ..$ dec_lat_va           : num 40
##   ..$ dec_long_va          : num -105
##   ..$ huc_cd               : chr "10190005"
##   ..$ site_tp_cd           : chr "ST"
##   ..$ state_cd             : chr "08"
##   ..$ station_nm           : chr "FOURMILE CREEK AT ORODELL, CO"
##   ..$ tz_cd                : chr "MST"
##   ..$ lat_va               : num 4e+05
##   ..$ long_va              : num 1051934
##   ..$ coord_meth_cd        : chr "N"
##   ..$ coord_acy_cd         : chr "5"
##   ..$ coord_datum_cd       : chr "NAD83"
##   ..$ dec_coord_datum_cd   : chr "NAD83"
##   ..$ district_cd          : chr "08"
##   ..$ county_cd            : chr "013"
##   ..$ country_cd           : chr "US"
##   ..$ land_net_ds          : chr "  NWSES27 T001N R071W"
##   ..$ map_nm               : chr "BOULDER, CO"
##   ..$ map_scale_fc         : chr "  24000"
##   ..$ alt_va               : num 5750
##   ..$ alt_meth_cd          : chr "M"
##   ..$ alt_acy_va           : num 15
##   ..$ alt_datum_cd         : chr "NGVD29"
##   ..$ basin_cd             : chr "06"
##   ..$ topo_cd              : chr ""
##   ..$ instruments_cd       : chr "NNNNYNYNNYNNNNNNNNNNNNNNNNNNNN"
##   ..$ construction_dt      : chr ""
##   ..$ inventory_dt         : chr "20110323"
##   ..$ drain_area_va        : num 24.2
##   ..$ contrib_drain_area_va: num NA
##   ..$ local_time_fg        : chr "Y"
##   ..$ reliability_cd       : chr ""
##   ..$ gw_file_cd           : chr "NYNNNNNN"
##   ..$ nat_aqfr_cd          : chr ""
##   ..$ aqfr_cd              : chr ""
##   ..$ aqfr_type_cd         : chr ""
##   ..$ well_depth_va        : num NA
##   ..$ hole_depth_va        : num NA
##   ..$ depth_src_cd         : chr ""
##   ..$ project_no           : chr "000012000"
##   ..$ timeZoneOffset       : chr "-07:00"
##   ..$ srs                  : chr "EPSG:4326"
##   ..$ startTime            : POSIXct, format: "2011-04-01 06:00:00"
##   ..$ endTime              : POSIXct, format: "2015-04-29 21:10:00"
##  - attr(*, "variableInfo")='data.frame': 1 obs. of  6 variables:
##   ..$ parameterCd   : chr "00060"
##   ..$ parameter_nm  : chr "Streamflow, ft&#179;/s"
##   ..$ parameter_desc: chr "Discharge, cubic feet per second"
##   ..$ valueType     : chr "Derived Value"
##   ..$ param_units   : chr "ft3/s"
##   ..$ noDataValue   : logi NA
##  - attr(*, "statisticInfo")='data.frame':    1 obs. of  2 variables:
##   ..$ statisticName: chr ""
##   ..$ statisticCd  : chr "00011"

Now make it “pretty”. The main difference here is meaningful column names and identification of variables and codes in the attributes. We have defined “prettyUsgs” as an S3 class.

prettyOrodell <- PrettyUsgs(dataOrodell, metric=TRUE)
str(prettyOrodell)
## Classes 'prettyUsgs' and 'data.frame':   211144 obs. of  5 variables:
##  $ site_no : chr  "06727500" "06727500" "06727500" "06727500" ...
##  $ POSIXct : POSIXct, format: "2011-04-01 06:00:00" "2011-04-01 06:05:00" "2011-04-01 06:10:00" "2011-04-01 06:15:00" ...
##  $ code    : chr  "A" "A" "A" "A" ...
##  $ value   : num  0.034 0.034 0.034 0.034 0.034 ...
##  $ variable: chr  "Discharge (cms)" "Discharge (cms)" "Discharge (cms)" "Discharge (cms)" ...
##  - attr(*, "siteInfo")='data.frame': 1 obs. of  46 variables:
##   ..$ site_no              : chr "06727500"
##   ..$ agency_cd            : chr "USGS"
##   ..$ dec_lat_va           : num 40
##   ..$ dec_long_va          : num -105
##   ..$ huc_cd               : chr "10190005"
##   ..$ site_tp_cd           : chr "ST"
##   ..$ state_cd             : chr "08"
##   ..$ station_nm           : chr "FOURMILE CREEK AT ORODELL, CO"
##   ..$ tz_cd                : chr "MST"
##   ..$ lat_va               : num 4e+05
##   ..$ long_va              : num 1051934
##   ..$ coord_meth_cd        : chr "N"
##   ..$ coord_acy_cd         : chr "5"
##   ..$ coord_datum_cd       : chr "NAD83"
##   ..$ dec_coord_datum_cd   : chr "NAD83"
##   ..$ district_cd          : chr "08"
##   ..$ county_cd            : chr "013"
##   ..$ country_cd           : chr "US"
##   ..$ land_net_ds          : chr "  NWSES27 T001N R071W"
##   ..$ map_nm               : chr "BOULDER, CO"
##   ..$ map_scale_fc         : chr "  24000"
##   ..$ alt_va               : num 5750
##   ..$ alt_meth_cd          : chr "M"
##   ..$ alt_acy_va           : num 15
##   ..$ alt_datum_cd         : chr "NGVD29"
##   ..$ basin_cd             : chr "06"
##   ..$ topo_cd              : chr ""
##   ..$ instruments_cd       : chr "NNNNYNYNNYNNNNNNNNNNNNNNNNNNNN"
##   ..$ construction_dt      : chr ""
##   ..$ inventory_dt         : chr "20110323"
##   ..$ drain_area_va        : num 24.2
##   ..$ contrib_drain_area_va: num NA
##   ..$ local_time_fg        : chr "Y"
##   ..$ reliability_cd       : chr ""
##   ..$ gw_file_cd           : chr "NYNNNNNN"
##   ..$ nat_aqfr_cd          : chr ""
##   ..$ aqfr_cd              : chr ""
##   ..$ aqfr_type_cd         : chr ""
##   ..$ well_depth_va        : num NA
##   ..$ hole_depth_va        : num NA
##   ..$ depth_src_cd         : chr ""
##   ..$ project_no           : chr "000012000"
##   ..$ timeZoneOffset       : chr "-07:00"
##   ..$ srs                  : chr "EPSG:4326"
##   ..$ startTime            : POSIXct, format: "2011-04-01 06:00:00"
##   ..$ endTime              : POSIXct, format: "2015-04-29 21:10:00"
class(prettyOrodell)
## [1] "prettyUsgs" "data.frame"

Plot the “pretty”" data.

oroPlot <- PlotPrettyUsgs(prettyOrodell)

Do this same as above, but for all sites in the HUC8. We restrict the plotting to just 3 locations so it’s legible for output here.

siteInfo<-QuerySiteInfo(c('station_nm','site_no','state_cd'), path=dbPath)
dataCO <- PrettyUsgs(QuerySiteData(subset(siteInfo, state_cd=='08' & product=='00060')$site_no, 
                                       product='00060', path=dbPath))
## 1:3 just to make the plot legible
coPlot <- PlotPrettyUsgs(subset(dataCO, site_no %in% unique(dataCO$site_no)[1:3]), plot=FALSE) 
coPlot(yLog=TRUE)

We can also retrieve data from sites in different HUC8s.

dataMultiHuc <- PrettyUsgs(QuerySiteData(c('06730500','02469800'), product='00060', path=dbPath))
str(dataMultiHuc)
## Classes 'prettyUsgs' and 'data.frame':   374243 obs. of  5 variables:
##  $ site_no : chr  "06730500" "06730500" "06730500" "06730500" ...
##  $ POSIXct : POSIXct, format: "2007-10-01 06:00:00" "2007-10-01 06:15:00" "2007-10-01 06:30:00" "2007-10-01 06:45:00" ...
##  $ code    : chr  "A" "A" "A" "A" ...
##  $ value   : num  0.51 0.51 0.51 0.51 0.51 ...
##  $ variable: chr  "Discharge (cms)" "Discharge (cms)" "Discharge (cms)" "Discharge (cms)" ...
##  - attr(*, "siteInfo")='data.frame': 2 obs. of  46 variables:
##   ..$ site_no              : chr  "06730500" "02469800"
##   ..$ agency_cd            : chr  "USGS" "USGS"
##   ..$ dec_lat_va           : num  40.1 31.7
##   ..$ dec_long_va          : num  -105 -88
##   ..$ huc_cd               : chr  "10190005" "03160203"
##   ..$ site_tp_cd           : chr  "ST" "ST"
##   ..$ state_cd             : chr  "08" "01"
##   ..$ station_nm           : chr  "BOULDER CREEK AT MOUTH NEAR LONGMONT, CO" "SATILPA CREEK NEAR COFFEEVILLE AL"
##   ..$ tz_cd                : chr  "MST" "CST"
##   ..$ lat_va               : num  400820 314439
##   ..$ long_va              : num  1050113 880121
##   ..$ coord_meth_cd        : chr  "N" "M"
##   ..$ coord_acy_cd         : chr  "5" "U"
##   ..$ coord_datum_cd       : chr  "NAD83" "NAD27"
##   ..$ dec_coord_datum_cd   : chr  "NAD83" "NAD83"
##   ..$ district_cd          : chr  "08" "01"
##   ..$ county_cd            : chr  "123" "025"
##   ..$ country_cd           : chr  "US" "US"
##   ..$ land_net_ds          : chr  "  NWSWS17 T002N R068W" ""
##   ..$ map_nm               : chr  "LONGMONT, CO" ""
##   ..$ map_scale_fc         : chr  "  24000" ""
##   ..$ alt_va               : num  4860 39.8
##   ..$ alt_meth_cd          : chr  "M" "U"
##   ..$ alt_acy_va           : num  10 0.01
##   ..$ alt_datum_cd         : chr  "NGVD29" "NGVD29"
##   ..$ basin_cd             : chr  "06" ""
##   ..$ topo_cd              : chr  "" ""
##   ..$ instruments_cd       : chr  "NNNNYNNNNNNNNNNNNNNNNNNNNNNNNN" "NNNNYNNNNNNNNNNNNNNNNNNNNNNNNN"
##   ..$ construction_dt      : chr  "" ""
##   ..$ inventory_dt         : chr  "" ""
##   ..$ drain_area_va        : num  447 164
##   ..$ contrib_drain_area_va: num  NA 164
##   ..$ local_time_fg        : chr  "Y" "Y"
##   ..$ reliability_cd       : chr  "" ""
##   ..$ gw_file_cd           : chr  "NYNNNNNN" "NNNNNNNN"
##   ..$ nat_aqfr_cd          : chr  "" ""
##   ..$ aqfr_cd              : chr  "" ""
##   ..$ aqfr_type_cd         : chr  "" ""
##   ..$ well_depth_va        : num  NA NA
##   ..$ hole_depth_va        : num  NA NA
##   ..$ depth_src_cd         : chr  "" ""
##   ..$ project_no           : chr  "" ""
##   ..$ timeZoneOffset       : chr  "-07:00" "-06:00"
##   ..$ srs                  : chr  "EPSG:4326" "EPSG:4326"
##   ..$ startTime            : POSIXct, format: "2007-10-01 06:00:00" "2007-10-01 05:00:00"
##   ..$ endTime              : POSIXct, format: "2015-04-29 21:00:00" "2015-04-29 21:00:00"

GagesII Attributes

We’ve imported the gages-II atributes to be directly available in R.
?gages2Attr
gages2Attr R Documentation

Gages-II attributes

Description

These are the attributes taken from the USGS Gages-II data set.
http://water.usgs.gov/GIS/metadata/usgswrd/XML/gagesII_Sept2011.xml
The original gages-II atributes are in gages2Attr additional attributes may be placed in gages2AttrPlus.

Usage

gages2Attr

Format

data.frame: 9322 obs. of 16 variables:

STAID

Station ID from USGS NWIS

STANAME

Station Name from USGS NWIS

CLASS

Classification (Ref or Non-ref)

AGGECOREGI

Aggregated ecoregion

DRAIN_SQKM

Drainage area, sq km

HUC02

Hydrologic Unit Code, 2-digit

HUC08

ONLY in gages2AttrPlus: Hydrologic Unit Code, 8-digit

LAT_GAGE

Latitude, decimal degrees

LNG_GAGE

Longitude, decimal degrees

STATE

State at gage location

HCDN_2009

If gage is part of HCDN-2009

ACTIVE09

If gage active in water year 2009

FLYRS1900

Number of complete years of flow data between 1900 and 2009

FLYRS1950

Number of complete years of flow data between 1950 and 2009

FLYRS1990

Number of complete years of flow data between 1990 and 2009

Citation

Originator: James Falcone
Publication_Date: 20111012
Title: GAGES-II: Geospatial Attributes of Gages for Evaluating Streamflow
Geospatial_Data_Presentation_Form: vector digital data Publication_Information:
Publication_Place: Reston, Virginia
Publisher: U.S. Geological Survey
Online_Linkage: http://water.usgs.gov/lookup/getspatial?gagesII_Sept2011

See Also

Other gages2: gages2AttrPlus

More specifically:

str(gages2Attr)
## 'data.frame':    9322 obs. of  14 variables:
##  $ STAID     : chr  "01011000" "01013500" "01015800" "01016500" ...
##  $ STANAME   : chr  "Allagash River near Allagash, Maine" "Fish River near Fort Kent, Maine" "Aroostook River near Masardis, Maine" "MACHIAS RIVER NEAR ASHLAND, ME" ...
##  $ CLASS     : chr  "Non-ref" "Ref" "Non-ref" "Non-ref" ...
##  $ AGGECOREGI: chr  "NorthEast" "NorthEast" "NorthEast" "NorthEast" ...
##  $ DRAIN_SQKM: num  3187 2253 2314 848 4279 ...
##  $ HUC02     : chr  "01" "01" "01" "01" ...
##  $ LAT_GAGE  : num  47.1 47.2 46.5 46.6 46.8 ...
##  $ LNG_GAGE  : num  -69.1 -68.6 -68.4 -68.4 -68.2 ...
##  $ STATE     : chr  "ME" "ME" "ME" "ME" ...
##  $ HCDN_2009 : chr  "" "yes" "" "" ...
##  $ ACTIVE09  : chr  "yes" "yes" "yes" "" ...
##  $ FLYRS1900 : num  78 85 51 32 79 0 1 9 6 47 ...
##  $ FLYRS1950 : num  60 60 51 32 60 0 1 9 6 39 ...
##  $ FLYRS1990 : num  20 20 19 0 20 0 1 9 6 6 ...