As part of a collaborative research effort, the multi-decadal reanalysis products from the NOAA National Water Model (versions 1.2 and 2.0) have been reformatted and exposed through CUAHSI at the RENCI computing facility. This document outlines how someone can interact with the interface.
TL;DR
nwmHistoric allows you to extract streamflow data from the NOAA National Water Model reanalysis products by NHD Catchment Identifier or USGS NWIS siteNumber:
library(nwmHistoric) # Extract NWM flow records for USGS-11120000 nwis_extract <- readNWMdata(siteNumber = 11120000) # Extract NWM flow records for comid-101 and comid-17595383 nhd_extract <- readNWMdata(comid = c(101,17595383))
Extraction
Reanalysis data can be found with the readNWMdata function. The API requires users to specify NHD Catchment Identifier(s) (COMID), or NWIS gage ID(s) for time series extraction.
NHD Catchment Identifier (COMID)
NWM reanalysis data can be extracted by NHD Catchment Identifier(s). The following code pulls the complete reanalysis data archive for COMID 17595383, a NHD reach near Goleta, California.
flows = readNWMdata(comid = 17595383) head(flows) #> model comid time flow #> 1 NWM2 17595383 1993-01-01 00:00:00 0.21 #> 2 NWM2 17595383 1993-01-01 01:00:00 0.21 #> 3 NWM2 17595383 1993-01-01 02:00:00 0.21 #> 4 NWM2 17595383 1993-01-01 03:00:00 0.21 #> 5 NWM2 17595383 1993-01-01 04:00:00 0.21 #> 6 NWM2 17595383 1993-01-01 05:00:00 0.21 dim(flows) #> [1] 227904 4
USGS NWIS Site Number
Alternatively, data can be extracted using USGS NWIS site ID(s).
flows = readNWMdata(siteNumber = 11120000) head(flows) #> model comid time flow siteNumber #> 1 NWM2 17595429 1993-01-01 00:00:00 0.41 11120000 #> 2 NWM2 17595429 1993-01-01 01:00:00 0.41 11120000 #> 3 NWM2 17595429 1993-01-01 02:00:00 0.41 11120000 #> 4 NWM2 17595429 1993-01-01 03:00:00 0.41 11120000 #> 5 NWM2 17595429 1993-01-01 04:00:00 0.42 11120000 #> 6 NWM2 17595429 1993-01-01 05:00:00 0.42 11120000 dim(flows) #> [1] 227904 5
Contraint Parameters
Date Range
By default, the API extracts the complete flow record for each ID. This range can constrained by providing a startDate and endDate in the form of (“YYYY-MM-DD”).
utc <- readNWMdata(comid = 17595383, startDate = "2010-01-01", endDate = "2010-01-31") # Check time dimensions range(utc$time) #> [1] "2010-01-01 00:00:00 UTC" "2010-01-31 23:00:00 UTC"
Time-zone
NWM output is recorded in UTC. Instead, users can specify a timezone. For our COMID in Goleta, California we can request data in US/Pacific time. Valid times zone can be found with OlsonNames().
pst = readNWMdata(comid = 17595383, startDate = "2010-01-01", endDate = "2010-01-31", tz = "US/Pacific") # Check time dimensions range(pst$time) #> [1] "2010-01-01 00:00:00 PST" "2010-01-31 23:00:00 PST"
Finally, we can plot the UTC return against the PST return:
Model Version
The reanalysis product for versions 1.2 and 2.0 of the NWM are available. By default the API extracts data from version 2.0, but data from 1.2 can be requested as well.
pst_v12 = readNWMdata(comid = 17595383, startDate = "2010-01-01", endDate = "2010-01-31", tz = "US/Pacific", version = 1.2)
In section 2, we will look at how we can facilitate COMID and USGS NWIS discovery. In section 3 we will look at some techniques to handle time aggregations and splitting.