pynhd.nldi ========== .. py:module:: pynhd.nldi .. autoapi-nested-parse:: Access NLDI and WaterData databases. Module Contents --------------- .. py:class:: NLDI(dev = False) Access the Hydro Network-Linked Data Index (NLDI) service. :Parameters: **dev** (:class:`bool`, *optional*) -- If ``True``, use the development version of the NLDI service. Defaults to ``False``. .. py:method:: comid_byloc(coords, loc_crs = 4326) Get the closest ComID based on coordinates using ``hydrolocation`` endpoint. .. rubric:: 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** (:class:`tuple` or :class:`list` of :class:`tuples`) -- A tuple of length two (x, y) or a list of them. * **loc_crs** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- The spatial reference of the input coordinate, defaults to EPSG:4326. :returns: :class:`geopandas.GeoDataFrame` or :class:`(geopandas.GeoDataFrame`, :class:`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. .. py:method:: feature_byloc(coords, loc_crs = 4326) Get the closest feature ID(s) based on coordinates using ``position`` endpoint. :Parameters: * **coords** (:class:`tuple` or :class:`list`) -- A tuple of length two (x, y) or a list of them. * **loc_crs** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- The spatial reference of the input coordinate, defaults to EPSG:4326. :returns: :class:`geopandas.GeoDataFrame` or :class:`(geopandas.GeoDataFrame`, :class:`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. .. py:method:: get_basins(feature_ids, fsource = 'nwissite', split_catchment = False, simplified = True) Get basins for a list of station IDs. :Parameters: * **feature_ids** (:class:`str` or :class:`list`) -- Target feature ID(s). * **fsource** (:class:`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** (:class:`bool`, *optional*) -- If ``True``, split basins at their outlet locations. Default to ``False``. * **simplified** (:class:`bool`, *optional*) -- If ``True``, return a simplified version of basin geometries. Default to ``True``. :returns: :class:`geopandas.GeoDataFrame` or :class:`(geopandas.GeoDataFrame`, :class:`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. .. py:method:: get_characteristics(char_list, comids = None) :staticmethod: Get characteristics using a list ComIDs. :Parameters: * **char_list** (:class:`str` or :class:`list`) -- The list of characteristics to get. * **comids** (:class:`int` or :class:`list`, *optional*) -- The list of ComIDs, defaults to None, i.e., all NHDPlus ComIDs. :returns: :class:`pandas.DataFrame` -- The characteristics of the requested ComIDs. .. py:method:: getfeature_byid(fsource, fids) Get feature(s) based ID(s). :Parameters: * **fsource** (:class:`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** (:class:`str` or :class:`list` of :class:`str`) -- Feature ID(s). :returns: :class:`geopandas.GeoDataFrame` or :class:`(geopandas.GeoDataFrame`, :class:`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. .. py:method:: 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** (:class:`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** (:class:`str` or :class:`int`) -- The ID of the feature. * **navigation** (:class:`str`) -- The navigation method. * **source** (:class:`str`) -- Return the data from another source after navigating features from ``fsource``. * **distance** (:class:`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** (:class:`bool`, *optional*) -- If ``True``, trim the starting flowline at the source feature, defaults to ``False``. * **stop_comid** (:class:`str` or :class:`int`, *optional*) -- The ComID to stop the navigationation, defaults to ``None``. :returns: :class:`geopandas.GeoDataFrame` -- NLDI indexed features in EPSG:4326. .. py:method:: 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. .. rubric:: 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** (:class:`tuple`) -- A tuple of length two (x, y). * **navigation** (:class:`str`, *optional*) -- The navigation method, defaults to None which throws an exception if ``comid_only`` is False. * **source** (:class:`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** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- The spatial reference of the input coordinate, defaults to EPSG:4326. * **distance** (:class:`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** (:class:`bool`, *optional*) -- If ``True``, trim the starting flowline at the source feature, defaults to ``False``. * **stop_comid** (:class:`str` or :class:`int`, *optional*) -- The ComID to stop the navigationation, defaults to ``None``. :returns: :class:`geopandas.GeoDataFrame` -- NLDI indexed features in EPSG:4326. .. py:property:: dev :type: bool Get the development version of the NLDI service.