pynhd.nldi#

Access NLDI and WaterData databases.

Module Contents#

class pynhd.nldi.NLDI#

Access the Hydro Network-Linked Data Index (NLDI) service.

comid_byloc(coords, loc_crs=4326)#

Get the closest ComID based on coordinates using hydrolocation endpoint.

Notes

This function tries to find the closest ComID based on flowline grid cells. If such a cell is not found, it will return the closest ComID using the flowtrace endpoint of the PyGeoAPI service to find the closest downstream ComID. The returned dataframe has a measure column that indicates the location of the input coordinate on the flowline as a percentage of the total flowline length.

Parameters:

  • coords (tuple or list of tuples) – A tuple of length two (x, y) or a list of them.

  • loc_crs (str, int, or pyproj.CRS, optional) – The spatial reference of the input coordinate, defaults to EPSG:4326.

Returns:

geopandas.GeoDataFrame or (geopandas.GeoDataFrame, list) – NLDI indexed ComID(s) and points in EPSG:4326. If some coords don’t return any ComID a list of missing coords are returned as well.

Return type:

geopandas.GeoDataFrame

feature_byloc(coords, loc_crs=4326)#

Get the closest feature ID(s) based on coordinates using position endpoint.

Parameters:

  • coords (tuple or list) – A tuple of length two (x, y) or a list of them.

  • loc_crs (str, int, or pyproj.CRS, optional) – The spatial reference of the input coordinate, defaults to EPSG:4326.

Returns:

geopandas.GeoDataFrame or (geopandas.GeoDataFrame, list) – NLDI indexed feature ID(s) and flowlines in EPSG:4326. If some coords don’t return any IDs a list of missing coords are returned as well.

Return type:

geopandas.GeoDataFrame

get_basins(feature_ids, fsource='nwissite', split_catchment=False, simplified=True)#

Get basins for a list of station IDs.

Parameters:

  • feature_ids (str or list) – Target feature ID(s).

  • fsource (str) – The name of feature(s) source, defaults to nwissite. The valid sources are:

    • ‘comid’ for NHDPlus comid.

    • ‘ca_gages’ for Streamgage catalog for CA SB19

    • ‘gfv11_pois’ for USGS Geospatial Fabric V1.1 Points of Interest

    • ‘huc12pp’ for HUC12 Pour Points

    • ‘nmwdi-st’ for New Mexico Water Data Initiative Sites

    • ‘nwisgw’ for NWIS Groundwater Sites

    • ‘nwissite’ for NWIS Surface Water Sites

    • ‘ref_gage’ for geoconnex.us reference gages

    • ‘vigil’ for Vigil Network Data

    • ‘wade’ for Water Data Exchange 2.0 Sites

    • ‘WQP’ for Water Quality Portal

  • split_catchment (bool, optional) – If True, split basins at their outlet locations. Default to False.

  • simplified (bool, optional) – If True, return a simplified version of basin geometries. Default to True.

Returns:

geopandas.GeoDataFrame or (geopandas.GeoDataFrame, list) – NLDI indexed basins in EPSG:4326. If some IDs don’t return any features a list of missing ID(s) are returned as well.

Return type:

geopandas.GeoDataFrame

static get_characteristics(char_list, comids=None)#

Get characteristics using a list ComIDs.

Parameters:

  • char_list (str or list) – The list of characteristics to get.

  • comids (int or list, optional) – The list of ComIDs, defaults to None, i.e., all NHDPlus ComIDs.

Returns:

pandas.DataFrame – The characteristics of the requested ComIDs.

Return type:

pandas.DataFrame

getfeature_byid(fsource, fids)#

Get feature(s) based ID(s).

Parameters:

  • fsource (str) – The name of feature(s) source. The valid sources are:

    • ‘comid’ for NHDPlus comid.

    • ‘ca_gages’ for Streamgage catalog for CA SB19

    • ‘gfv11_pois’ for USGS Geospatial Fabric V1.1 Points of Interest

    • ‘huc12pp’ for HUC12 Pour Points

    • ‘nmwdi-st’ for New Mexico Water Data Initiative Sites

    • ‘nwisgw’ for NWIS Groundwater Sites

    • ‘nwissite’ for NWIS Surface Water Sites

    • ‘ref_gage’ for geoconnex.us reference gages

    • ‘vigil’ for Vigil Network Data

    • ‘wade’ for Water Data Exchange 2.0 Sites

    • ‘WQP’ for Water Quality Portal

  • fid (str or list of str) – Feature ID(s).

Returns:

geopandas.GeoDataFrame or (geopandas.GeoDataFrame, list) – NLDI indexed features in EPSG:4326. If some IDs don’t return any features a list of missing ID(s) are returned as well.

Return type:

geopandas.GeoDataFrame

navigate_byid(fsource, fid, navigation, source, distance=500, trim_start=False, stop_comid=None)#

Navigate the NHDPlus database from a single feature id up to a distance.

Parameters:

  • fsource (str) – The name of feature(s) source. The valid sources are:

    • ‘comid’ for NHDPlus comid.

    • ‘ca_gages’ for Streamgage catalog for CA SB19

    • ‘gfv11_pois’ for USGS Geospatial Fabric V1.1 Points of Interest

    • ‘huc12pp’ for HUC12 Pour Points

    • ‘nmwdi-st’ for New Mexico Water Data Initiative Sites

    • ‘nwisgw’ for NWIS Groundwater Sites

    • ‘nwissite’ for NWIS Surface Water Sites

    • ‘ref_gage’ for geoconnex.us reference gages

    • ‘vigil’ for Vigil Network Data

    • ‘wade’ for Water Data Exchange 2.0 Sites

    • ‘WQP’ for Water Quality Portal

  • fid (str or int) – The ID of the feature.

  • navigation (str) – The navigation method.

  • source (str) – Return the data from another source after navigating features from fsource.

  • distance (int, optional) – Limit the search for navigation up to a distance in km, defaults is 500 km. Note that this is an expensive request so you have be mindful of the value that you provide. The value must be between 1 to 9999 km.

  • trim_start (bool, optional) – If True, trim the starting flowline at the source feature, defaults to False.

  • stop_comid (str or int, optional) – The ComID to stop the navigationation, defaults to None.

Returns:

geopandas.GeoDataFrame – NLDI indexed features in EPSG:4326.

Return type:

geopandas.GeoDataFrame

navigate_byloc(coords, navigation=None, source=None, loc_crs=4326, distance=500, trim_start=False, stop_comid=None)#

Navigate the NHDPlus database from a coordinate.

Notes

This function first calls the feature_byloc function to get the comid of the nearest flowline and then calls the navigate_byid function to get the features from the obtained comid.

Parameters:

  • coords (tuple) – A tuple of length two (x, y).

  • navigation (str, optional) – The navigation method, defaults to None which throws an exception if comid_only is False.

  • source (str, optional) – Return the data from another source after navigating the features based on comid, defaults to None which throws an exception if comid_only is False.

  • loc_crs (str, int, or pyproj.CRS, optional) – The spatial reference of the input coordinate, defaults to EPSG:4326.

  • distance (int, optional) – Limit the search for navigation up to a distance in km, defaults to 500 km. Note that this is an expensive request so you have be mindful of the value that you provide.

  • trim_start (bool, optional) – If True, trim the starting flowline at the source feature, defaults to False.

  • stop_comid (str or int, optional) – The ComID to stop the navigationation, defaults to None.

Returns:

geopandas.GeoDataFrame – NLDI indexed features in EPSG:4326.

Return type:

geopandas.GeoDataFrame