gauge module¶
Module for handling USGS and AHPS gauge data for flood inundation mapping.
GetAhpsGaugeDatumElevation(ahpsGaugeUrl)
¶
Retrieve gauge stage datum elevation and vertical datum name from AHPS web HTML page.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ahpsGaugeUrl |
str |
URL of AHPS gauge web page. |
required |
Returns:
| Type | Description |
|---|---|
tuple |
vertical datum name (str), gauge stage datum elevation (float). |
GetAhpsGaugeForecast(scratchFolder, fcstLength, gaugeDatumFile)
¶
Get AHPS gauge forecast for a specified number of future days.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scratchFolder |
str |
scratch folder to store downloaded files. |
required |
fcstLength |
int |
forecast length in days between 0 and 14 days. 0 is current observation. |
required |
gaugeDatumFile |
str |
file name of gauge datum information. |
required |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of AHPS gauge forecast. |
GetAhpsGaugeHistoricalFloodStages(scratchFolder, gaugeDatumFile)
¶
Get AHPS gauge historical flood stages: 'Action','Flood','Moderate','Major'.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scratchFolder |
str |
scratch folder to store downloaded files. |
required |
gaugeDatumFile |
str |
file name of gauge datum information. |
required |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of AHPS gauge historical flood stages. |
GetAhpsGaugeStageFromWebService(ahpsIds, fcstDays=0, histFloodType=None)
¶
Get AHPS gauge stage from web service.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ahpsIds |
list |
a list of AHPS gauge IDs. |
required |
fcstDays |
int |
forecasted time in 0 to 14 days. 0 is current obersevation. default to 0. |
0 |
histFloodType |
str |
historical flood types of Major, Moderate, Flood, Action. default to None. |
None |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of AHPS gauge stage. |
GetAhpsGauges(geobox, epsg=32614)
¶
Get AHPS gauges within a box and project them to a specified coordinate system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geobox |
list |
a list of geographic box elements of [minX,minY,maxX,maxY] |
required |
epsg |
int |
EPSG integer representing the projected coordinate system, default to UTM14 (epsg = 32614) for Kansas. |
32614 |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of AHPS gauges projected to the specified coordinate system. |
GetAhpsUsgsGaugeStageFromWebServices(gaugeIdOrgs, whichStage='Nowcast', periodInDays=7)
¶
Read AHPS/USGS gauge stage from their respective web services.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gaugeIdOrgs |
data frame |
a data frame with columns of ["stationid", "organization"]. stationid is either USGS, AHPS, or the combination of their gauge IDs. Organization is either USGS, AHPS or both. |
required |
whichStage |
str |
Nowcast, Forecast, Postcast, and historical stages Action, Flood, Moderate, Major. |
'Nowcast' |
periodInDays |
int |
period in days (0 - 14) for forecast. Default to 7. |
7 |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of gauge stage with the fields of stationid, x, y, stage_elevation, stage_time. |
GetGaugeStageFromAhpsUsgsWebServices(gaugeFile, whichStage='Nowcast')
¶
Read gauge stage from AHPS or USGS web services.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gaugeFile |
str |
file name of gauge information. |
required |
whichStage |
str |
Nowcast, Forecast, Postcast, and historical stages Action, Flood, Moderate, Major. Default to 'Nowcast'. |
'Nowcast' |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of gauge stage with the fields of stationid, x, y, stage_elevation, stage_time, status. |
GetUsgsGaugeInfo(ids)
¶
Get USGS gauge information with a list of gauge IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids |
list |
a list of USGS gauge IDs. |
required |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of USGS gauge information. |
GetUsgsGaugeStageFromWebService(usgsIds, startDate='Now', endDate='MostRecent')
¶
Get USGS gauge stage from web service. USGS Instantaneous Values Service URL: https://waterservices.usgs.gov/rest/IV-Test-Tool.html
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
usgsIds |
list |
a list of USGS IDs. |
required |
startDate |
str |
start date of the query. Default to 'Now'. |
'Now' |
endDate |
str |
end date of the query. Default to 'MostRecent'. |
'MostRecent' |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of USGS gauge stage. |
GetUsgsGauges(geobox, epsg=32614)
¶
Get USGS gauges within a box and project them to a specified coordinate system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geobox |
list |
a list of geographic box elements of [minX,minY,maxX,maxY]. |
required |
epsg |
int |
EPSG integer representing the projected coordinate system, default to UTM14 (epsg = 32614) for Kansas. |
32614 |
Returns:
| Type | Description |
|---|---|
data frame |
a geo data frame of USGS gauges projected to the specified coordinate system. |
MergeUsgsAhpsGauges(usgsGauges, ahpsGauges, nearDist=350)
¶
Merge USGS and AHPS gauges based on the nearest neighbor that is within a specified distance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
usgsGauges |
data frame |
USGS gauges data frame. |
required |
ahpsGauges |
data frame |
AHPS gauges data frame. |
required |
nearDist |
float |
distance threshold for finding the nearest gauge, default to 350 meters. |
350 |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of merged USGS and AHPS gauges. |
NGVD29ToNAVD88OrthoHeightAdjustment(lat, lon, inDatum, outDatum, inVertDatum='NGVD29', outVertDatum='NAVD88', orthoHt=0.0)
¶
Calculate vertical datum shift between NGVD29 and NAVD88 using NGS web service. NGS Latitude-longitude-height Service: https://www.ngs.noaa.gov/web_services/ncat/lat-long-height-service.shtml
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lat |
float |
latitude of the gauge. |
required |
lon |
float |
longitude of the gauge. |
required |
inDatum |
str |
input datum name. |
required |
outDatum |
str |
output datum name. |
required |
inVertDatum |
str |
input vertical datum name, default to NGVD29. |
'NGVD29' |
outVertDatum |
str |
output vertical datum name, default to NAVD88. |
'NAVD88' |
orthoHt |
float |
orthometric height, default to 0.0. |
0.0 |
Returns:
| Type | Description |
|---|---|
float |
vertical datum shift from NGVD29 to NAVD88. |
PrepareAhpsGaugeDatum(scratchFolder, libFolder, prjFileName, datumFile)
¶
Prepare AHPS gauge datum.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scratchFolder |
str |
scratch folder to store downloaded files. |
required |
libFolder |
str |
library folder to store files. |
required |
prjFileName |
str |
file name of projection information. |
required |
datumFile |
str |
file name of gauge datum information. |
required |
Returns:
| Type | Description |
|---|---|
data frame |
a data frame of AHPS gauges. |