Add envelope curve gage plot

[amedenblik]

In the Exploration tools, create a new tool that generates a plot with:

• Peak flow on y-axis
• Drainage area on x-axis
• Point data that represent gages

There should be a drop-down that allows users to select a State / Region to show all that gages in that state/region.

In subsequent issues (see tagged issues below), there will be numerous options to select gages. I would explore the Exploration Tools for inspiration on how you may want to design this interface.

Example in R (Seth Siefken has some code for this-- see below):

Seth's code:

MTsites <- dataRetrieval::whatNWISsites(stateCd="MT", hasDataTypeCd="pk")

peaks <- dataRetrieval::readNWISpeak(MTsites$site_no, convertType = FALSE)

#Add columns for month, year, and day
peaks$peak_year <-  as.numeric(substring(peaks$peak_dt, 1, 4))
peaks$peak_month <-  as.numeric(substring(peaks$peak_dt, 5, 6))
peaks$peak_day <-  as.numeric(substring(peaks$peak_dt, 7, 8))

peaks$peak_va <- as.numeric(peaks$peak_va)

#Compute water year of peak
#For peaks with a valid month before September, year in is the water year
peaks[!is.na(peaks$peak_month) & peaks$peak_month < 10,"peak_WY"] <- peaks[!is.na(peaks$peak_month) & peaks$peak_month < 10,"peak_year"]
#For peaks with a valid month after September, year in is the year prior to the water year
peaks[!is.na(peaks$peak_month) & peaks$peak_month >= 10,"peak_WY"] <- peaks[!is.na(peaks$peak_month) & peaks$peak_month >= 10,"peak_year"] + 1
peaks[is.na(peaks$peak_month),"peak_WY"] <- peaks[is.na(peaks$peak_month),"peak_year"] #For peaks without a month, the year in WATSTORE file is the water year

siteInfo <- dataRetrieval::readNWISsite(MTsites$site_no)

peaks <- merge(peaks, siteInfo, by="site_no")

peaks <- peaks[!grepl("3", peaks$peak_cd),] #Remove dam breaks

peaks$DA <- peaks$contrib_drain_area_va
peaks$DA[is.na(peaks$DA)] <- peaks$drain_area_va[is.na(peaks$DA)]

showWY <- 2011
showcode <- "7"

library(plotly)

p <- plot_ly( x = peaks$DA, y = peaks$peak_va, type = "scatter", mode='markers', marker = list(color="gray"), 
              text = paste(peaks$site_no, "\n", peaks$peak_WY), hoverinfo='text', name = "Peak Flow") %>%

  add_trace(x = peaks$DA[grepl(showcode, peaks$peak_cd)], y = peaks$peak_va[grepl(showcode, peaks$peak_cd)], type = "scatter", mode='markers', marker = list(color="red"), 
            text = paste(peaks$site_no[grepl(showcode, peaks$peak_cd)], "\n", peaks$peak_WY[grepl(showcode, peaks$peak_cd)]), hoverinfo='text', name = paste("Estimated")) %>%

   add_trace(x = peaks$DA[peaks$peak_WY == showWY], y = peaks$peak_va[peaks$peak_WY == showWY], type = "scatter", mode='markers', marker = list(color="blue"), 
             text = paste(peaks$site_no[peaks$peak_WY == showWY], "\n", peaks$peak_WY[peaks$peak_WY == showWY]), hoverinfo='text', name = as.character(showWY)) %>%
  layout(title="Montana Peak Streamflow", yaxis = list( title = 'Peak flow, in cubic feet per second', zeroline=FALSE, gridcolor='gray', type='log'),
         xaxis = list(title = 'Drainage area, in square miles', zeroline=FALSE, gridcolor='gray', type='log'))

print(p)

[maggiejaenicke]

@USGSPMM3 Question for you: I'm pulling in the drainage area data for this plot, and I noticed some stations have two drainage area values (one from NWIS and one from elsewhere). It seems that some are marked with comments: "null," so I was thinking those would be excluded (see example gage 02169500 which has one marked null but the other not). But stations with a single value also seemed to be marked with the same "null" comments, see this example gage: 02162093. And at this gage, 02168845, there are two drainage area values and both are marked with the comments: "null." Is there another identifier that can tell me which drainage area value I should be using at gages that have multiple?

[USGSPMM3]

@maggiejaenicke : I put a question to the GIS folks in the Teams General Chat for StreamStats. Generally speaking I doubt we have any comments or very few comments in the fields for DA. I think that any of the fields that have a reference other than NWIS would likely be better. That said, I'm wondering if we should be using NWIS data calls to call the most recent value from NWIS rather than using the StreamStats database values that may be outdate (I really hope they aren't). I guess it could be a good exercise for us to do a compare of the DAs in our database against the NWIS database and see how many have 3 unique and separate values

[amedenblik]

@maggiejaenicke

CitationID 193 is the citation for DRNAREA (Drainage Area) characteristics that were imported from NWIS.

For now, if a gage has multiple DRNAREA characteristics and one of them has citation ID 193, let's use the value that is not associated with NWIS/citationID 193.

I am still not sure how to handle the situation where a gage has multiple DRNAREA characeristics and neither is associated with citationID 193. Maybe that situation doesn't exist?

We will work on a better solution in the database/services for the long-term.

[amedenblik]

@maggiejaenicke I created numerous related issues (see tagged issues above). I went ahead and assigned them to you, but feel free to unassign yourself if you run out of time, etc. These issues contain some new functionality that I don't think you've worked with before, so please don't hesitate to reach out if you could use help.

There are a few other features we discussed, which I think we can wait on for now until we finish these issues. Listing them here so we don't forget:

• Selecting gages by HUC-2: not sure how performant this would be, because HUC-2s are quite large
• Selecting gages by flood frequency regression regions: I have some questions about how we would present the list of regression regions to the user or how the user would select the regression region, and I'm not completely sure if this feature is necessary

[amedenblik]

See related GageStatsServices issue to edit the GET Stations endpoint: https://code.usgs.gov/StreamStats/web-services-and-apis/GageStatsServices/-/issues/142