hydroflows.methods.discharge.fluvial_design_events

Derive fluvial design events from a discharge time series.

class hydroflows.methods.discharge.fluvial_design_events.FluvialDesignEvents(discharge_nc: Path, event_root: Path = 'data/events/discharge', rps: list[int] | None = None, event_names: list[str] | None = None, wildcard: str = 'event', **params)

Derive fluvial design events from a discharge time series.

Parameters:

• discharge_nc (Path) – The file path to the discharge time series in NetCDF format.

• event_root (Path, optional) – The root folder to save the derived design events, by default “data/events/discharge”.

• rps (List[float], optional) – Return periods of the design events, by default [1, 2, 5, 10, 20, 50, 100].

• event_names (List[str], optional) – List of event names of the design events, by default “q_event{i}”, where i is the event number.

• wildcard (str, optional) – The wildcard key for expansion over the design events, by default “event”.

• **params – Additional parameters to pass to the FluvialDesignEvents Params instance. See fluvial_design_events Params.

See also

fluvial_design_events Input fluvial_design_events Output fluvial_design_events Params hydromt.stats.extremes

Create a new expand method instance.

pydantic model hydroflows.methods.discharge.fluvial_design_events.Input

Input parameters for the FluvialDesignEvents method.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• discharge_nc (pathlib.Path)

field discharge_nc: Path [Required]

The file path to the discharge time series in NetCDF format which is used to apply EVA and derive design events. This file should contain an index dimension and a time dimension for several (gauge) locations.

• The discharge time series can be produced either by the Wflow toolchain (via the hydroflows.methods.wflow.wflow_update_forcing.WflowBuild, hydroflows.methods.wflow.wflow_update_forcing.WflowUpdateForcing, and hydroflows.methods.wflow.wflow_run.WflowRun methods) or can be directly supplied by the user.

• When the design events are used in Sfincs using the hydroflows.methods.sfincs.sfincs_update_forcing.SfincsUpdateForcing method, the index dimension should correspond to the index of the Sfincs source points, providing the corresponding time series at specific locations.

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self – The BaseModel instance.

• context – The context.

pydantic model hydroflows.methods.discharge.fluvial_design_events.Output

Output parameters for the FluvialDesignEvents method.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• event_csv (pathlib.Path)

• event_set_yaml (pathlib.Path)

• event_yaml (pathlib.Path)

field event_csv: Path [Required]

The path to the event csv timeseries file.

field event_set_yaml: Annotated[Path, AfterValidator(func=filedir_validator)] [Required]

The path to the event set yml file that contains the derived fluvial event configurations. This event set can be created from a dictionary using the hydroflows.methods.events.EventSet class.

field event_yaml: Annotated[Path, AfterValidator(func=filedir_validator)] [Required]

The path to the event description file, see also hydroflows.methods.events.Event.

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self – The BaseModel instance.

• context – The context.

pydantic model hydroflows.methods.discharge.fluvial_design_events.Params

Parameters for the FluvialDesignEvents method.

See also

hydromt.stats.extremes

For more details on the event selection, EVA and peak hydrographs using HydroMT.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• ev_type (Literal['BM', 'POT'])

• event_names (list[str] | None)

• event_root (pathlib.Path)

• index_dim (str)

• min_dist_days (int)

• min_sample_perc (int)

• n_peaks (int)

• plot_fig (bool)

• qthresh (float)

• rps (list[int])

• t0 (str)

• time_dim (str)

• var_name (str)

• warm_up_years (int)

• wdw_size_days (int)

• wildcard (str)

field ev_type: Literal['BM', 'POT'] = 'BM'

Method to select events/peaks. Valid options are ‘BM’ for block maxima or ‘POT’ for Peak over threshold.

field event_names: <lambda>, json_schema_input_type=PydanticUndefined)] | None = None

List of event names derived from the design events.

field event_root: Annotated[Path, AfterValidator(func=outputdirpath_validator)] [Required]

“Root folder to save the derived design events.

field index_dim: str = 'Q_gauges'

Index dimension of the input time series provided in Input class.

field min_dist_days: int = 7

Minimum distance between events/peaks measured in days.

field min_sample_perc: int = 80

Minimum sample percentage in a valid block. Peaks of invalid bins are set to NaN

field n_peaks: int = None

Number of largest peaks to get hydrograph. If None (default) all peaks are used.

field plot_fig: bool = True

Determines whether to plot figures, including the derived design hydrograph per location and return period, as well as the EVA fits.

field qthresh: float = 0.95

Quantile threshold used with peaks over threshold method.

field rps: <lambda>, json_schema_input_type=PydanticUndefined)] [Required]

Return periods of of design events.

field t0: str = '2020-01-01'

Random initial date for the design events.

field time_dim: str = 'time'

Time dimension of the input time series provided in Input class.

field var_name: str = 'Q'

Name of the discharge time series variable provided in Input class

field warm_up_years: Annotated[int, Gt(gt=0)] = None

The number of initial years (positive integer) to exclude from the discharge time series as a warm-up period, typically used when the data is generated through hydrological modeling and requires an initial warm-up phase.

field wdw_size_days: int = 6

Duration for hydrograph in days.

field wildcard: str = 'event'

The wildcard key for expansion over the design events.

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self – The BaseModel instance.

• context – The context.