pynhd.pygeoapi ============== .. py:module:: pynhd.pygeoapi .. autoapi-nested-parse:: Access NLDI and WaterData databases. Module Contents --------------- .. py:class:: PyGeoAPI Access `PyGeoAPI `__ service. .. py:method:: cross_section(coord, width, numpts, crs = 4326) Return a GeoDataFrame from the xsatpoint service. :Parameters: * **coord** (:class:`tuple`) -- The coordinate of the point to extract the cross-section as a tuple,e.g., (lon, lat). * **width** (:class:`float`) -- The width of the cross-section in meters. * **numpts** (:class:`int`) -- The number of points to extract the cross-section from the DEM. * **crs** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- The coordinate reference system of the coordinates, defaults to EPSG:4326. :returns: :class:`geopandas.GeoDataFrame` -- A GeoDataFrame containing the cross-section at the requested point. .. rubric:: Examples >>> from pynhd import PyGeoAPI >>> pga = PyGeoAPI() >>> gdf = pga.cross_section((-103.80119, 40.2684), width=1000.0, numpts=101, crs=4326) # doctest: +SKIP >>> print(gdf.iloc[-1, 1]) # doctest: +SKIP 1000.0 .. py:method:: elevation_profile(line, numpts, dem_res, crs = 4326) Return a GeoDataFrame from the xsatpathpts service. :Parameters: * **line** (:class:`shapely.LineString` or :class:`shapely.MultiLineString`) -- The line to extract the elevation profile for. * **numpts** (:class:`int`) -- The number of points to extract the elevation profile from the DEM. * **dem_res** (:class:`int`) -- The target resolution for requesting the DEM from 3DEP service. * **crs** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- The coordinate reference system of the coordinates, defaults to EPSG:4326. :returns: :class:`geopandas.GeoDataFrame` -- A GeoDataFrame containing the elevation profile along the requested endpoints. .. rubric:: Examples >>> from pynhd import PyGeoAPI >>> from shapely import LineString >>> pga = PyGeoAPI() >>> line = LineString([(-103.801086, 40.26772), (-103.80097, 40.270568)]) >>> gdf = pga.elevation_profile(line, 101, 1, 4326) # doctest: +SKIP >>> print(gdf.iloc[-1, 2]) # doctest: +SKIP 1299.8727 .. py:method:: endpoints_profile(coords, numpts, dem_res, crs = 4326) Return a GeoDataFrame from the xsatendpts service. :Parameters: * **coords** (:class:`list`) -- A list of two coordinates to trace as a list of tuples, e.g., [(x1, y1), (x2, y2)]. * **numpts** (:class:`int`) -- The number of points to extract the elevation profile from the DEM. * **dem_res** (:class:`int`) -- The target resolution for requesting the DEM from 3DEP service. * **crs** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- The coordinate reference system of the coordinates, defaults to EPSG:4326. :returns: :class:`geopandas.GeoDataFrame` -- A GeoDataFrame containing the elevation profile along the requested endpoints. .. rubric:: Examples >>> from pynhd import PyGeoAPI >>> pga = PyGeoAPI() >>> gdf = pga.endpoints_profile( ... [(-103.801086, 40.26772), (-103.80097, 40.270568)], numpts=101, dem_res=1, crs=4326 ... ) # doctest: +SKIP >>> print(gdf.iloc[-1, 1]) # doctest: +SKIP 411.5906 .. py:method:: flow_trace(coord, crs = 4326, direction = 'none') Return a GeoDataFrame from the flowtrace service. :Parameters: * **coord** (:class:`tuple`) -- The coordinate of the point to trace as a tuple,e.g., (lon, lat). * **crs** (:class:`str`) -- The coordinate reference system of the coordinates, defaults to EPSG:4326. * **direction** (:class:`str`, *optional*) -- The direction of flowpaths, either ``down``, ``up``, or ``none``. Defaults to ``none``. :returns: :class:`geopandas.GeoDataFrame` -- A GeoDataFrame containing the traced flowline. .. rubric:: Examples >>> from pynhd import PyGeoAPI >>> pga = PyGeoAPI() >>> gdf = pga.flow_trace( ... (1774209.63, 856381.68), crs="ESRI:102003", direction="none" ... ) # doctest: +SKIP >>> print(gdf.comid.iloc[0]) # doctest: +SKIP 22294818 .. py:method:: split_catchment(coord, crs = 4326, upstream = False) Return a GeoDataFrame from the splitcatchment service. :Parameters: * **coord** (:class:`tuple`) -- The coordinate of the point to trace as a tuple,e.g., (lon, lat). * **crs** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- The coordinate reference system of the coordinates, defaults to EPSG:4326. * **upstream** (:class:`bool`, *optional*) -- If True, return all upstream catchments rather than just the local catchment, defaults to False. :returns: :class:`geopandas.GeoDataFrame` -- A GeoDataFrame containing the local catchment or the entire upstream catchments. .. rubric:: Examples >>> from pynhd import PyGeoAPI >>> pga = PyGeoAPI() >>> gdf = pga.split_catchment((-73.82705, 43.29139), crs=4326, upstream=False) # doctest: +SKIP >>> print(gdf.catchmentID.iloc[0]) # doctest: +SKIP 22294818 .. py:function:: pygeoapi(geodf, service) Return a GeoDataFrame from the flowtrace service. :Parameters: * **geodf** (:class:`geopandas.GeoDataFrame`) -- A GeoDataFrame containing geometries to query. The required columns for each service are: * ``flow_trace``: ``direction`` that indicates the direction of the flow trace. It can be ``up``, ``down``, or ``none`` (both directions). * ``split_catchment``: ``upstream`` that indicates whether to return all upstream catchments or just the local catchment. * ``elevation_profile``: ``numpts`` that indicates the number of points to extract along the flowpath and ``3dep_res`` that indicates the target resolution for requesting the DEM from 3DEP service. * ``endpoints_profile``: ``numpts`` that indicates the number of points to extract along the flowpath and ``3dep_res`` that indicates the target resolution for requesting the DEM from 3DEP service. * ``cross_section``: ``numpts`` that indicates the number of points to extract along the flowpath and ``width`` that indicates the width of the cross-section in meters. * **service** (:class:`str`) -- The service to query, can be ``flow_trace``, ``split_catchment``, ``elevation_profile``, ``endpoints_profile``, or ``cross_section``. :returns: :class:`geopandas.GeoDataFrame` -- A GeoDataFrame containing the results of requested service. .. rubric:: Examples >>> from shapely import Point >>> import geopandas as gpd >>> gdf = gpd.GeoDataFrame( ... { ... "direction": [ ... "none", ... ] ... }, ... geometry=[Point((1774209.63, 856381.68))], ... crs="ESRI:102003", ... ) >>> trace = nhd.pygeoapi(gdf, "flow_trace") >>> print(trace.comid.iloc[0]) 22294818