pygeohydro.pygeohydro
¶
Accessing data from the supported databases through their APIs.
Module Contents¶
- class pygeohydro.pygeohydro.NID(expire_after=EXPIRE, disable_caching=False)¶
Retrieve data from the National Inventory of Dams web service.
- Parameters
- get_byfilter(self, query_list)¶
Query dams by filters from the National Inventory of Dams web service.
- Parameters
query_list (
list
ofdict
) – List of dictionary of query parameters. For an exhaustive list of the parameters, use the advanced fields dataframe that can be accessed viaNID().fields_meta
. Some filter require min/max values such asdamHeight
anddrainageArea
. For such filters, the min/max values should be passed like so:{filter_key: ["[min1 max1]", "[min2 max2]"]}
.- Returns
geopandas.GeoDataFrame
– Query results.
Examples
>>> from pygeohydro import NID >>> nid = NID() >>> query_list = [ ... {"huc6": ["160502", "100500"], "drainageArea": ["[200 500]"]}, ... {"nidId": ["CA01222"]}, ... ] >>> dam_dfs = nid.get_byfilter(query_list) >>> print(dam_dfs[0].name[0]) Stillwater Point Dam
- get_bygeom(self, geometry, geo_crs)¶
Retrieve NID data within a geometry.
- Parameters
- Returns
geopandas.GeoDataFrame
– GeoDataFrame of NID data
Examples
>>> from pygeohydro import NID >>> nid = NID() >>> dams = nid.get_bygeom((-69.77, 45.07, -69.31, 45.45), "epsg:4326") >>> print(dams.name.iloc[0]) Little Moose
- get_suggestions(self, text, context_key='')¶
Get suggestions from the National Inventory of Dams web service.
Notes
This function is useful for exploring and/or narrowing down the filter fields that are needed to query the dams using
get_byfilter
.- Parameters
- Returns
tuple
ofpandas.DataFrame
– The suggestions for the requested text as two DataFrames: First, is suggestions found in the dams properties and second, those found in the query fields such as states, huc6, etc.
Examples
>>> from pygeohydro import NID >>> nid = NID() >>> dams, contexts = nid.get_suggestions("texas", "huc2") >>> print(contexts.loc["HUC2", "value"]) 12
- inventory_byid(self, dam_ids)¶
Get extra attributes for dams based on their dam ID.
Notes
This function is meant to be used for getting extra attributes for dams. For example, first you need to use either
get_bygeom
orget_byfilter
to get basic attributes of the target dams. Then you can use this function to get extra attributes using theid
column of theGeoDataFrame
thatget_bygeom
orget_byfilter
returns.- Parameters
dam_ids (
list
ofint
orstr
) – List of the target dam IDs (digists only). Note that the dam IDs are not the same as the NID IDs.- Returns
pandas.DataFrame
– Dams with extra attributes in addition to the standard NID fields that otherNID
methods return.
Examples
>>> from pygeohydro import NID >>> nid = NID() >>> dams = nid.inventory_byid([514871, 459170, 514868, 463501, 463498]) >>> print(dams.damHeight.max()) 120.0
- pygeohydro.pygeohydro.cover_statistics(ds)¶
Percentages of the categorical NLCD cover data.
- Parameters
ds (
xarray.DataArray
) – Cover DataArray from a LULC Dataset from thenlcd
function.- Returns
dict
– Statistics of NLCD cover data
- pygeohydro.pygeohydro.nlcd(geometry, resolution, years=None, region='L48', geo_crs=DEF_CRS, crs=DEF_CRS)¶
Get data from NLCD database (2019).
Deprecated since version 0.11.5: Use
nlcd_bygeom()
ornlcd_bycoords()
instead.- Parameters
geometry (
Polygon
,MultiPolygon
, ortuple
oflength 4
) – The geometry or bounding box (west, south, east, north) for extracting the data.resolution (
float
) – The data resolution in meters. The width and height of the output are computed in pixel based on the geometry bounds and the given resolution.years (
dict
, optional) – The years for NLCD layers as a dictionary, defaults to{'impervious': [2019], 'cover': [2019], 'canopy': [2019], "descriptor": [2019]}
. Layers that are not in years are ignored, e.g.,{'cover': [2016, 2019]}
returns land cover data for 2016 and 2019.region (
str
, optional) – Region in the US, defaults toL48
. Valid values areL48
(for CONUS),HI
(for Hawaii),AK
(for Alaska), andPR
(for Puerto Rico). Both lower and upper cases are acceptable.geo_crs (
str
, optional) – The CRS of the input geometry, defaults to epsg:4326.crs (
str
, optional) – The spatial reference system to be used for requesting the data, defaults to epsg:4326.
- Returns
xarray.Dataset
– NLCD within a geometry
- pygeohydro.pygeohydro.nlcd_bycoords(coords, years=None, region='L48', expire_after=EXPIRE, disable_caching=False)¶
Get data from NLCD database (2019).
- Parameters
coords (
list
oftuple
) – List of coordinates in the form of (longitude, latitude).years (
dict
, optional) – The years for NLCD layers as a dictionary, defaults to{'impervious': [2019], 'cover': [2019], 'canopy': [2019], "descriptor": [2019]}
. Layers that are not in years are ignored, e.g.,{'cover': [2016, 2019]}
returns land cover data for 2016 and 2019.region (
str
, optional) – Region in the US, defaults toL48
. Valid values areL48
(for CONUS),HI
(for Hawaii),AK
(for Alaska), andPR
(for Puerto Rico). Both lower and upper cases are acceptable.expire_after (
int
, optional) – Expiration time for response caching in seconds, defaults to -1 (never expire).disable_caching (
bool
, optional) – IfTrue
, disable caching requests, defaults to False.
- Returns
geopandas.GeoDataFrame
– A GeoDataFrame with the NLCD data and the coordinates.
- pygeohydro.pygeohydro.nlcd_bygeom(geometry, resolution, years=None, region='L48', crs=DEF_CRS, validation=True, expire_after=EXPIRE, disable_caching=False)¶
Get data from NLCD database (2019).
- Parameters
geometry (
geopandas.GeoDataFrame
orgeopandas.GeoSeries
) – A GeoDataFrame or GeoSeries with the geometry to query. The indices are used as keys in the output dictionary.resolution (
float
) – The data resolution in meters. The width and height of the output are computed in pixel based on the geometry bounds and the given resolution.years (
dict
, optional) – The years for NLCD layers as a dictionary, defaults to{'impervious': [2019], 'cover': [2019], 'canopy': [2019], "descriptor": [2019]}
. Layers that are not in years are ignored, e.g.,{'cover': [2016, 2019]}
returns land cover data for 2016 and 2019.region (
str
, optional) – Region in the US, defaults toL48
. Valid values areL48
(for CONUS),HI
(for Hawaii),AK
(for Alaska), andPR
(for Puerto Rico). Both lower and upper cases are acceptable.crs (
str
, optional) – The spatial reference system to be used for requesting the data, defaults to epsg:4326.validation (
bool
, optional) – Validate the input arguments from the WMS service, defaults to True. Set this to False if you are sure all the WMS settings such as layer and crs are correct to avoid sending extra requests.expire_after (
int
, optional) – Expiration time for response caching in seconds, defaults to -1 (never expire).disable_caching (
bool
, optional) – IfTrue
, disable caching requests, defaults to False.
- Returns
dict
ofxarray.Dataset
orxarray.Dataset
– A single or adict
of NLCD datasets. If dict, the keys are indices of the inputGeoDataFrame
.
- pygeohydro.pygeohydro.ssebopeta_bycoords(coords, dates, crs=DEF_CRS)¶
Daily actual ET for a dataframe of coords from SSEBop database in mm/day.
- Parameters
coords (
pandas.DataFrame
) – A dataframe withid
,x
,y
columns.dates (
tuple
orlist
, optional) – Start and end dates as a tuple (start, end) or a list of years [2001, 2010, …].crs (
str
, optional) – The CRS of the input coordinates, defaults to epsg:4326.
- Returns
xarray.Dataset
– Daily actual ET in mm/day as a dataset withtime
andlocation_id
dimensions. Thelocation_id
dimension is the same as theid
column in the input dataframe.
- pygeohydro.pygeohydro.ssebopeta_bygeom(geometry, dates, geo_crs=DEF_CRS)¶
Get daily actual ET for a region from SSEBop database.
Notes
Since there’s still no web service available for subsetting SSEBop, the data first needs to be downloaded for the requested period then it is masked by the region of interest locally. Therefore, it’s not as fast as other functions and the bottleneck could be the download speed.
- Parameters
geometry (
shapely.geometry.Polygon
ortuple
) – The geometry for downloading clipping the data. For a tuple bbox, the order should be (west, south, east, north).dates (
tuple
orlist
, optional) – Start and end dates as a tuple (start, end) or a list of years [2001, 2010, …].geo_crs (
str
, optional) – The CRS of the input geometry, defaults to epsg:4326.
- Returns
xarray.DataArray
– Daily actual ET within a geometry in mm/day at 1 km resolution
- pygeohydro.pygeohydro.ssebopeta_byloc(coords, dates)¶
Daily actual ET for a location from SSEBop database in mm/day.
Deprecated since version 0.11.5: Use
ssebopeta_bycoords()
instead. For now, this function callsssebopeta_bycoords()
but retains the same functionality, i.e., returns a dataframe and accepts only a single coordinate. Whereas the new function returns axarray.Dataset
and accepts a dataframe containing coordinates.- Parameters
- Returns
pandas.Series
– Daily actual ET for a location