MNT: Rebuild APIs.

hyriver · Jul 7, 2024 · f01f764 · f01f764
1 parent a344076
commit f01f764
Show file tree

Hide file tree

Showing 9 changed files with 214 additions and 139 deletions.
diff --git a/docs/source/autoapi/hydrosignatures/hydrosignatures/index.rst b/docs/source/autoapi/hydrosignatures/hydrosignatures/index.rst
@@ -129,13 +129,13 @@ Module Contents
    :returns: :class:`float` or :class:`pandas.Series` or :class:`xarray.DataArray` -- The aridity index.
 
 
-.. py:function:: baseflow(discharge, alpha = 0.925, n_passes = 3, pad_width = 10)
+.. py:function:: baseflow(discharge, alpha = 0.925, n_passes = 1, pad_width = 10)
 
    Extract baseflow using the Lyne and Hollick filter (Ladson et al., 2013).
 
    :Parameters: * **discharge** (:class:`numpy.ndarray` or :class:`pandas.DataFrame` or :class:`pandas.Series` or :class:`xarray.DataArray`) -- Discharge time series that must not have any missing values. It can also be a 2D array
                   where each row is a time series.
-                * **n_passes** (:class:`int`, *optional*) -- Number of filter passes, defaults to 3. It must be an odd number greater than 3.
+                * **n_passes** (:class:`int`, *optional*) -- Number of filter passes, defaults to 1.
                 * **alpha** (:class:`float`, *optional*) -- Filter parameter that must be between 0 and 1, defaults to 0.925.
                 * **pad_width** (:class:`int`, *optional*) -- Padding width for extending the data from both ends to address the warm up issue.
 
@@ -155,6 +155,44 @@ Module Contents
    :returns: :class:`numpy.float64` -- The baseflow index.
 
 
+.. py:function:: baseflow_recession(streamflow, freq = 1.0, recession_length = 15, n_start = 0, eps = 0, start_of_recession = 'baseflow', fit_method = 'nonparametric_analytic', lyne_hollick_smoothing = 0.925)
+
+   Calculate baseflow recession constant and master recession curve.
+
+   .. rubric:: Notes
+
+   This function is ported from the TOSSH Matlab toolbox, which is based on the
+   following publication:
+
+   Gnann, S.J., Coxon, G., Woods, R.A., Howden, N.J.K., McMillan H.K., 2021.
+   TOSSH: A Toolbox for Streamflow Signatures in Hydrology.
+   Environmental Modelling & Software.
+   https://doi.org/10.1016/j.envsoft.2021.104983
+
+   This function calculates baseflow recession constant assuming exponential
+   recession behaviour (Safeeq et al., 2013). Master recession curve (MRC) is
+   constructed using the adapted matching strip method (Posavec et al.,
+   2006).
+
+   According to Safeeq et al. (2013), :math:`K < 0.065` represent groundwater
+   dominated slow-draining systems, :math:`K >= 0.065` represent shallow subsurface
+   flow dominated fast draining systems.
+
+   :Parameters: * **streamflow** (:class:`numpy.ndarray`) -- Streamflow as a 1D array.
+                * **freq** (:class:`float`, *optional*) -- Frequency of steamflow in number of days. Default is 1, i.e., daily streamflow.
+                * **recession_length** (:class:`int`, *optional*) -- Minimum length of recessions [days]. Default is 15.
+                * **n_start** (:class:`int`, *optional*) -- Days to be removed after start of recession. Default is 0.
+                * **eps** (:class:`float`, *optional*) -- Allowed increase in flow during recession period. Default is 0.
+                * **start_of_recession** (``{'baseflow', 'peak'}``, *optional*) -- Define start of recession. Default is 'baseflow'.
+                * **fit_method** (``{'nonparametric_analytic', 'exponential'}``, *optional*) -- Method to fit mrc. Default is 'nonparametric_analytic'.
+                * **lyne_hollick_smoothing** (:class:`float`, *optional*) -- Smoothing parameter of Lyne-Hollick filter. Default is 0.925.
+
+   :returns: * **mrc** (:class:`numpy.ndarray`) -- Master Recession Curve as 2D array of [time, flow].
+             * **bf_recession_k** (:class:`float`) -- Baseflow Recession Constant [1/day].
+
+   :raises ValueError: If no recession segments are found or if a complex BaseflowRecessionK is calculated.
+
+
 .. py:function:: exceedance(daily, threshold = 0.001)
 
    Compute exceedance probability from daily data.

diff --git a/docs/source/autoapi/py3dep/py3dep/index.rst b/docs/source/autoapi/py3dep/py3dep/index.rst
@@ -199,10 +199,10 @@ Module Contents
    >>> bbox = (-69.77, 45.07, -69.31, 45.45)
    >>> src = py3dep.query_3dep_sources(bbox)
    >>> src.groupby("dem_res")["OBJECTID"].count().to_dict()
-   {'10m': 8, '1m': 2, '30m': 8}
+   {'10m': 16, '1m': 4, '30m': 8}
    >>> src = py3dep.query_3dep_sources(bbox, res="1m")
    >>> src.groupby("dem_res")["OBJECTID"].count().to_dict()
-   {'1m': 2}
+   {'1m': 4}
 
 
 .. py:function:: static_3dep_dem(geometry, crs, resolution = 10)

diff --git a/docs/source/autoapi/pygeohydro/index.rst b/docs/source/autoapi/pygeohydro/index.rst
@@ -18,6 +18,7 @@ Submodules
    /autoapi/pygeohydro/helpers/index
    /autoapi/pygeohydro/levee/index
    /autoapi/pygeohydro/nfhl/index
+   /autoapi/pygeohydro/nid/index
    /autoapi/pygeohydro/nlcd/index
    /autoapi/pygeohydro/nwis/index
    /autoapi/pygeohydro/plot/index

diff --git a/docs/source/autoapi/pygeohydro/nid/index.rst b/docs/source/autoapi/pygeohydro/nid/index.rst
@@ -0,0 +1,135 @@
+pygeohydro.nid
+==============
+
+.. py:module:: pygeohydro.nid
+
+.. autoapi-nested-parse::
+
+   Accessing data from the supported databases through their APIs.
+
+
+
+
+
+Module Contents
+---------------
+
+.. py:class:: NID
+
+   Retrieve data from the National Inventory of Dams web service.
+
+
+   .. py:method:: get_byfilter(query_list)
+
+      Query dams by filters from the National Inventory of Dams web service.
+
+      :Parameters: **query_list** (:class:`list` of :class:`dict`) -- List of dictionary of query parameters. For an exhaustive list of the parameters,
+                   use the advanced fields dataframe that can be accessed via ``NID().fields_meta``.
+                   Some filter require min/max values such as ``damHeight`` and ``drainageArea``.
+                   For such filters, the min/max values should be passed like so:
+                   ``{filter_key: ["[min1 max1]", "[min2 max2]"]}``.
+
+      :returns: :class:`list` of :class:`geopandas.GeoDataFrame` -- Query results in the same order as the input query list.
+
+      .. rubric:: Examples
+
+      >>> from pygeohydro import NID
+      >>> nid = NID()
+      >>> query_list = [
+      ...    {"drainageArea": ["[200 500]"]},
+      ...    {"nidId": ["CA01222"]},
+      ... ]
+      >>> dam_dfs = nid.get_byfilter(query_list)
+
+
+
+   .. py:method:: get_bygeom(geometry, geo_crs)
+
+      Retrieve NID data within a geometry.
+
+      :Parameters: * **geometry** (:class:`Polygon`, :class:`MultiPolygon`, or :class:`tuple` of :class:`length 4`) -- Geometry or bounding box (west, south, east, north) for extracting the data.
+                   * **geo_crs** (:class:`list` of :class:`str`) -- The CRS of the input geometry.
+
+      :returns: :class:`geopandas.GeoDataFrame` -- GeoDataFrame of NID data
+
+      .. rubric:: Examples
+
+      >>> from pygeohydro import NID
+      >>> nid = NID()
+      >>> dams = nid.get_bygeom((-69.77, 45.07, -69.31, 45.45), 4326)
+
+
+
+   .. py:method:: get_suggestions(text, context_key = None)
+
+      Get suggestions from the National Inventory of Dams web service.
+
+      .. rubric:: 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: * **text** (:class:`str`) -- Text to query for suggestions.
+                   * **context_key** (:class:`str`, *optional*) -- Suggestion context, defaults to empty string, i.e., all context keys.
+                     For a list of valid context keys, see ``NID().fields_meta``.
+
+      :returns: :class:`tuple` of :class:`pandas.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.
+
+      .. rubric:: Examples
+
+      >>> from pygeohydro import NID
+      >>> nid = NID()
+      >>> dams, contexts = nid.get_suggestions("houston", "city")
+
+
+
+   .. py:method:: inventory_byid(federal_ids)
+
+      Get extra attributes for dams based on their dam ID.
+
+      .. rubric:: Notes
+
+      This function is meant to be used for getting extra attributes for dams.
+      For example, first you need to use either ``get_bygeom`` or ``get_byfilter``
+      to get basic attributes of the target dams. Then you can use this function
+      to get extra attributes using the ``id`` column of the ``GeoDataFrame``
+      that ``get_bygeom`` or ``get_byfilter`` returns.
+
+      :Parameters: **federal_ids** (:class:`list` of :class:`str`) -- List of the target dam Federal IDs.
+
+      :returns: :class:`pandas.DataFrame` -- Dams with extra attributes in addition to the standard NID fields
+                that other ``NID`` methods return.
+
+      .. rubric:: Examples
+
+      >>> from pygeohydro import NID
+      >>> nid = NID()
+      >>> dams = nid.inventory_byid(['KY01232', 'GA02400', 'NE04081', 'IL55070', 'TN05345'])
+
+
+
+   .. py:method:: stage_nid_inventory(fname = None)
+
+      Download the entire NID inventory data and save to a parquet file.
+
+      :Parameters: **fname** (:class:`str`, :class:`pathlib.Path`, *optional*) -- The path to the file to save the data to, defaults to
+                   ``./cache/full_nid_inventory.parquet``.
+
+
+
+   .. py:property:: df
+      Entire NID inventory (``csv`` version) as a ``pandas.DataFrame``.
+
+
+   .. py:property:: gdf
+      Entire NID inventory (``gpkg`` version) as a ``geopandas.GeoDataFrame``.
+
+
+   .. py:property:: nid_inventory_path
+      :type: pathlib.Path
+
+      Path to the NID inventory parquet file.
+
+
diff --git a/docs/source/autoapi/pygeohydro/pygeohydro/index.rst b/docs/source/autoapi/pygeohydro/pygeohydro/index.rst
@@ -16,7 +16,7 @@ pygeohydro.pygeohydro
 Module Contents
 ---------------
 
-.. py:class:: EHydro(data_type = 'points')
+.. py:class:: EHydro(data_type = 'points', cache_dir = 'ehydro_cache')
 
 
 
@@ -39,18 +39,19 @@ Module Contents
       Get features using a valid SQL 92 WHERE clause.
 
 
-   :Parameters: **data_type** (:class:`str`, *optional*) -- Type of the survey data to retrieve, defaults to ``points``.
-                Note that the ``points`` data type gets the best available point
-                cloud data, i.e., if ``SurveyPointHD`` is available, it will be
-                returned, otherwise ``SurveyPoint`` will be returned.
-                Available types are:
+   :Parameters: * **data_type** (:class:`str`, *optional*) -- Type of the survey data to retrieve, defaults to ``points``.
+                  Note that the ``points`` data type gets the best available point
+                  cloud data, i.e., if ``SurveyPointHD`` is available, it will be
+                  returned, otherwise ``SurveyPoint`` will be returned.
+                  Available types are:
 
-                - ``points``: Point clouds
-                - ``outlines``: Polygons of survey outlines
-                - ``contours``: Depth contours
-                - ``bathymetry``: Bathymetry data
+                  - ``points``: Point clouds
+                  - ``outlines``: Polygons of survey outlines
+                  - ``contours``: Depth contours
+                  - ``bathymetry``: Bathymetry data
 
-                Note that point clouds are not available for all surveys.
+                  Note that point clouds are not available for all surveys.
+                * **cache_dir** (:class:`str` or :class:`pathlib.Path`, *optional*) -- Directory to store the downloaded raw data, defaults to ``./ehydro_cache``.
 
 
    .. py:property:: survey_grid
@@ -59,125 +60,6 @@ Module Contents
       Full survey availability on hexagonal grid cells of 35 km resolution.
 
 
-.. py:class:: NID
-
-   Retrieve data from the National Inventory of Dams web service.
-
-
-   .. py:method:: get_byfilter(query_list)
-
-      Query dams by filters from the National Inventory of Dams web service.
-
-      :Parameters: **query_list** (:class:`list` of :class:`dict`) -- List of dictionary of query parameters. For an exhaustive list of the parameters,
-                   use the advanced fields dataframe that can be accessed via ``NID().fields_meta``.
-                   Some filter require min/max values such as ``damHeight`` and ``drainageArea``.
-                   For such filters, the min/max values should be passed like so:
-                   ``{filter_key: ["[min1 max1]", "[min2 max2]"]}``.
-
-      :returns: :class:`list` of :class:`geopandas.GeoDataFrame` -- Query results in the same order as the input query list.
-
-      .. rubric:: Examples
-
-      >>> from pygeohydro import NID
-      >>> nid = NID()
-      >>> query_list = [
-      ...    {"drainageArea": ["[200 500]"]},
-      ...    {"nidId": ["CA01222"]},
-      ... ]
-      >>> dam_dfs = nid.get_byfilter(query_list)
-
-
-
-   .. py:method:: get_bygeom(geometry, geo_crs)
-
-      Retrieve NID data within a geometry.
-
-      :Parameters: * **geometry** (:class:`Polygon`, :class:`MultiPolygon`, or :class:`tuple` of :class:`length 4`) -- Geometry or bounding box (west, south, east, north) for extracting the data.
-                   * **geo_crs** (:class:`list` of :class:`str`) -- The CRS of the input geometry.
-
-      :returns: :class:`geopandas.GeoDataFrame` -- GeoDataFrame of NID data
-
-      .. rubric:: Examples
-
-      >>> from pygeohydro import NID
-      >>> nid = NID()
-      >>> dams = nid.get_bygeom((-69.77, 45.07, -69.31, 45.45), 4326)
-
-
-
-   .. py:method:: get_suggestions(text, context_key = None)
-
-      Get suggestions from the National Inventory of Dams web service.
-
-      .. rubric:: 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: * **text** (:class:`str`) -- Text to query for suggestions.
-                   * **context_key** (:class:`str`, *optional*) -- Suggestion context, defaults to empty string, i.e., all context keys.
-                     For a list of valid context keys, see ``NID().fields_meta``.
-
-      :returns: :class:`tuple` of :class:`pandas.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.
-
-      .. rubric:: Examples
-
-      >>> from pygeohydro import NID
-      >>> nid = NID()
-      >>> dams, contexts = nid.get_suggestions("houston", "city")
-
-
-
-   .. py:method:: inventory_byid(federal_ids)
-
-      Get extra attributes for dams based on their dam ID.
-
-      .. rubric:: Notes
-
-      This function is meant to be used for getting extra attributes for dams.
-      For example, first you need to use either ``get_bygeom`` or ``get_byfilter``
-      to get basic attributes of the target dams. Then you can use this function
-      to get extra attributes using the ``id`` column of the ``GeoDataFrame``
-      that ``get_bygeom`` or ``get_byfilter`` returns.
-
-      :Parameters: **federal_ids** (:class:`list` of :class:`str`) -- List of the target dam Federal IDs.
-
-      :returns: :class:`pandas.DataFrame` -- Dams with extra attributes in addition to the standard NID fields
-                that other ``NID`` methods return.
-
-      .. rubric:: Examples
-
-      >>> from pygeohydro import NID
-      >>> nid = NID()
-      >>> dams = nid.inventory_byid(['KY01232', 'GA02400', 'NE04081', 'IL55070', 'TN05345'])
-
-
-
-   .. py:method:: stage_nid_inventory(fname = None)
-
-      Download the entire NID inventory data and save to a parquet file.
-
-      :Parameters: **fname** (:class:`str`, :class:`pathlib.Path`, *optional*) -- The path to the file to save the data to, defaults to
-                   ``./cache/full_nid_inventory.parquet``.
-
-
-
-   .. py:property:: df
-      Entire NID inventory (``csv`` version) as a ``pandas.DataFrame``.
-
-
-   .. py:property:: gdf
-      Entire NID inventory (``gpkg`` version) as a ``geopandas.GeoDataFrame``.
-
-
-   .. py:property:: nid_inventory_path
-      :type: pathlib.Path
-
-      Path to the NID inventory parquet file.
-
-
 .. py:function:: get_camels()
 
    Get streaflow and basin attributes of all 671 stations in CAMELS dataset.

diff --git a/docs/source/autoapi/pygeoutils/geotools/index.rst b/docs/source/autoapi/pygeoutils/geotools/index.rst
@@ -279,12 +279,12 @@ Module Contents
    (-97.06127, 32.83200)]
 
 
-.. py:function:: snap2nearest(lines, points, tol)
+.. py:function:: snap2nearest(lines_gdf, points_gdf, tol)
 
    Find the nearest points on a line to a set of points.
 
-   :Parameters: * **lines** (:class:`geopandas.GeoDataFrame` or :class:`geopandas.GeoSeries`) -- Lines.
-                * **points** (:class:`geopandas.GeoDataFrame` or :class:`geopandas.GeoSeries`) -- Points to snap to lines.
+   :Parameters: * **lines_gdf** (:class:`geopandas.GeoDataFrame` or :class:`geopandas.GeoSeries`) -- Lines.
+                * **points_gdf** (:class:`geopandas.GeoDataFrame` or :class:`geopandas.GeoSeries`) -- Points to snap to lines.
                 * **tol** (:class:`float`, *optional*) -- Tolerance for snapping points to the nearest lines in meters.
                   It must be greater than 0.0.