src.dynamic_boundary_conditions.river.main_river
================================================

.. py:module:: src.dynamic_boundary_conditions.river.main_river

.. autoapi-nested-parse::

   Main river script used to read and store REC data in the database, fetch OSM waterways data, create a river network
   and its associated data, and generate the requested river model input for BG-Flood etc.



Attributes
----------

.. autoapisummary::

   src.dynamic_boundary_conditions.river.main_river.log
   src.dynamic_boundary_conditions.river.main_river.sample_polygon


Functions
---------

.. autoapisummary::

   src.dynamic_boundary_conditions.river.main_river.retrieve_hydro_dem_info
   src.dynamic_boundary_conditions.river.main_river.get_hydro_dem_boundary_lines
   src.dynamic_boundary_conditions.river.main_river.remove_existing_river_inputs
   src.dynamic_boundary_conditions.river.main_river.main


Module Contents
---------------

.. py:data:: log

.. py:function:: retrieve_hydro_dem_info(engine: sqlalchemy.engine.Engine, catchment_area: geopandas.GeoDataFrame) -> Tuple[xarray.Dataset, shapely.geometry.LineString, Union[int, float]]

   Retrieves the Hydrologically Conditioned DEM (Hydro DEM) data, along with its spatial extent and resolution,
   for the specified catchment area.

   :param engine: The engine used to connect to the database.
   :type engine: Engine
   :param catchment_area: A GeoDataFrame representing the catchment area.
   :type catchment_area: gpd.GeoDataFrame

   :returns: A tuple containing the Hydro DEM data as a xarray Dataset, the spatial extent of the Hydro DEM as a LineString,
             and the resolution of the Hydro DEM as either an integer or a float.
   :rtype: Tuple[xr.Dataset, LineString, Union[int, float]]


.. py:function:: get_hydro_dem_boundary_lines(engine: sqlalchemy.engine.Engine, catchment_area: geopandas.GeoDataFrame) -> geopandas.GeoDataFrame

   Get the boundary lines of the Hydrologically Conditioned DEM.

   :param engine: The engine used to connect to the database.
   :type engine: Engine
   :param catchment_area: A GeoDataFrame representing the catchment area.
   :type catchment_area: gpd.GeoDataFrame

   :returns: A GeoDataFrame containing the boundary lines of the Hydrologically Conditioned DEM.
   :rtype: gpd.GeoDataFrame


.. py:function:: remove_existing_river_inputs(bg_flood_dir: pathlib.Path) -> None

   Remove existing river input files from the specified directory.

   :param bg_flood_dir: The BG-Flood model directory containing the river input files.
   :type bg_flood_dir: pathlib.Path

   :returns: This function does not return any value.
   :rtype: None


.. py:function:: main(selected_polygon_gdf: geopandas.GeoDataFrame, flow_length_mins: int, time_to_peak_mins: Union[int, float], maf: bool = True, ari: Optional[int] = None, bound: src.dynamic_boundary_conditions.river.river_enum.BoundType = BoundType.MIDDLE, log_level: src.digitaltwin.utils.LogLevel = LogLevel.DEBUG) -> None

   Read and store REC data in the database, fetch OSM waterways data, create a river network and its associated data,
   and generate the requested river model input for BG-Flood.

   :param selected_polygon_gdf: A GeoDataFrame representing the selected polygon, i.e., the catchment area.
   :type selected_polygon_gdf: gpd.GeoDataFrame
   :param flow_length_mins: Duration of the river flow in minutes.
   :type flow_length_mins: int
   :param time_to_peak_mins: The time in minutes when flow is at its greatest (reaches maximum).
   :type time_to_peak_mins: Union[int, float]
   :param maf: Set to True to obtain MAF-based scenario data or False to obtain ARI-based scenario data.
   :type maf: bool = True
   :param ari: The Average Recurrence Interval (ARI) value. Valid options are 5, 10, 20, 50, 100, or 1000.
               Mandatory when 'maf' is set to False, and should be set to None when 'maf' is set to True.
   :type ari: Optional[int] = None
   :param bound: Set the type of bound (estimate) for the REC river inflow scenario data.
                 Valid options include: 'BoundType.LOWER', 'BoundType.MIDDLE', or 'BoundType.UPPER'.
   :type bound: BoundType = BoundType.MIDDLE
   :param log_level: The log level to set for the root logger. Defaults to LogLevel.DEBUG.
                     The available logging levels and their corresponding numeric values are:
                     - LogLevel.CRITICAL (50)
                     - LogLevel.ERROR (40)
                     - LogLevel.WARNING (30)
                     - LogLevel.INFO (20)
                     - LogLevel.DEBUG (10)
                     - LogLevel.NOTSET (0)
   :type log_level: LogLevel = LogLevel.DEBUG

   :returns: This function does not return any value.
   :rtype: None


.. py:data:: sample_polygon