hydromt_wflow.WflowModel.setup_gauges#

WflowModel.setup_gauges(gauges_fn: str | Path | GeoDataFrame, index_col: str | None = None, snap_to_river: bool = True, mask: ndarray | None = None, snap_uparea: bool = False, max_dist: float = 10000.0, wdw: int = 3, rel_error: float = 0.05, abs_error: float = 50.0, fillna: bool = False, derive_subcatch: bool = False, basename: str | None = None, toml_output: str = 'csv', gauge_toml_header: List[str] = ['Q', 'P'], gauge_toml_param: List[str] = ['lateral.river.q_av', 'vertical.precipitation'], **kwargs)[source]#

Set a gauge map based on gauges_fn data.

Supported gauge datasets include data catlog entries, direct GeoDataFrame or “<path_to_source>” for user supplied csv or geometry files with gauge locations. If a csv file is provided, a “x” or “lon” and “y” or “lat” column is required and the first column will be used as IDs in the map.

There are four available methods to prepare the gauge map:

  • no snapping: mask=None, snap_to_river=False, snap_uparea=False. The gauge locations are used as is.

  • snapping to mask: the gauge locations are snapped to a boolean mask map based on the closest dowsntream cell within the mask: either provide mask or set snap_to_river=True to snap to the river cells (default). max_dist can be used to set the maximum distance to snap to the mask.

  • snapping based on upstream area matching: : snap_uparea=True. The gauge locations are snapped to the closest matching upstream area value. Requires gauges_fn to have an uparea [km2] column. The closest value will be looked for in a cell window of size wdw and the absolute and relative differences between the gauge and the closest value should be smaller than abs_error and rel_error.

  • snapping based on upstream area matching and mask: snap_uparea=True, mask or snap_to_river=True. The gauge locations are snapped to the closest matching upstream area value within the mask.

If derive_subcatch is set to True, an additional subcatch map is derived from the gauge locations.

Finally the output locations can be added to wflow TOML file sections [csv] or [netcdf] using the toml_output option. The gauge_toml_header and gauge_toml_param options can be used to define the header and corresponding wflow variable names in the TOML file.

Adds model layers:

  • wflow_gauges_source map: gauge IDs map from source [-] (if gauges_fn)

  • wflow_subcatch_source map: subcatchment based on gauge locations [-] (if derive_subcatch)

  • gauges_source geom: polygon of gauges from source

  • subcatch_source geom: polygon of subcatchment based on gauge locations [-] (if derive_subcatch)

Parameters:

  • gauges_fn (str, Path, geopandas.GeoDataFrame) –

    Catalog source name, path to gauges file geometry file or geopandas.GeoDataFrame.

    • Required variables if snap_uparea is True: ‘uparea’ [km2]

  • index_col (str, optional) – Column in gauges_fn to use for ID values, by default None (use the default index column)

  • mask (np.boolean, optional) – If provided snaps to the mask, else snaps to the river (default).

  • snap_to_river (bool, optional) – Snap point locations to the closest downstream river cell, by default True

  • snap_uparea (bool, optional) – Snap gauges based on upstream area. Gauges_fn should have “uparea” in its attributes.

  • max_dist (float, optional) – Maximum distance [m] between original and snapped point location. A warning is logged if exceeded. By default 10 000m.

  • wdw (int, optional) – Window size in number of cells around the gauge locations to snap uparea to, only used if snap_uparea is True. By default 3.

  • rel_error (float, optional) – Maximum relative error (default 0.05) between the gauge location upstream area and the upstream area of the best fit grid cell, only used if snap_uparea is True.

  • abs_error (float, optional) – Maximum absolute error (default 50.0) between the gauge location upstream area and the upstream area of the best fit grid cell, only used if snap_uparea is True.

  • fillna (bool, optional) – Fill missing values in the gauges uparea column with the values from wflow upstream area (ie no snapping). By default False and the gauges with NaN values are skipped.

  • derive_subcatch (bool, optional) – Derive subcatch map for gauges, by default False

  • basename (str, optional) – Map name in grid (wflow_gauges_basename) if None use the gauges_fn basename.

  • toml_output (str, optional) – One of [‘csv’, ‘netcdf’, None] to update [csv] or [netcdf] section of wflow toml file or do nothing. By default, ‘csv’.

  • gauge_toml_header (list, optional) – Save specific model parameters in csv section. This option defines the header of the csv file. By default saves Q (for lateral.river.q_av) and P (for vertical.precipitation).

  • gauge_toml_param (list, optional) – Save specific model parameters in csv section. This option defines the wflow variable corresponding to the names in gauge_toml_header. By default saves lateral.river.q_av (for Q) and vertical.precipitation (for P).

  • kwargs (dict, optional) – Additional keyword arguments to pass to the get_data method ie get_geodataframe or get_geodataset depending on the data_type of gauges_fn.