peilbeheer

peilbeheer

The level management (peilbeheer) of the peilgebieden of the water boards, in summer and winter.

The water boards deliver their peilgebieden in their own formats. read_peilbeheer reads them with the attribute mappings of SOURCES, see https://github.com/Deltares/Ribasim-NL/issues/893, into one table with per peilgebied the type of level management, the target level (streefpeil) and its lower and upper bound (ondergrens and bovengrens) in summer and winter, and the dates of the transitions between them. Where a dataset does not give these, they follow from the rules of complete_peilbeheer:

Without a target level, the target level is the mean of the bounds.
A season without a target level gets the levels of the other season, as for a fixed level.
Without a bound, or with a bound that does not lie within MAX_BOUND_DISTANCE beyond the target level, the bound is DEFAULT_BOUND from the target level, which is the band of the DiscreteControl thresholds of the model.
The transition from the winter to the summer level is from 1 to 10 April, and back from 1 to 10 October. Datasets with only the date at which the level changes start a transition of TRANSITION_DAYS days on that date. The models change their levels at once, at the begin of a transition, see ribasim_nl.seasonal_levels.

Levels of 99 m from NAP or more are unknown values, and so are levels of 0 in datasets that use 0 for unknown values, see valid_levels. Peilgebieden of which the summer and winter level differ more than MAX_SEASONAL_DIFFERENCE are data errors, and skipped. Most peilgebieden are areas, but they can also be points, such as weirs with their target levels.

Classes

Name	Description
Source	A dataset with the peilgebieden of a water board, and the attributes of their levels.

Source

peilbeheer.Source(
    path,
    code,
    mapping,
    layer=None,
    member=None,
    read=None,
    by=None,
    soort_peilbeheer=None,
    labels=dict(),
    transitions=dict(),
    zero_is_unknown=False,
)

A dataset with the peilgebieden of a water board, and the attributes of their levels.

mapping maps a value of attribute by to the attributes of the levels of the peilgebieden with that value, and "*" to those of all peilgebieden. The levels are streefpeil, ondergrens and bovengrens for both seasons, and these with the suffix _zomer or _winter for one season. Peilgebieden with other values of by are skipped.

Parameters

Name	Type	Description	Default
path	str	dataset, relative to the data directory	required
code	str	attribute with the code of a peilgebied	required
mapping	dict[str, dict[str, str]]	attributes of the levels of the peilgebieden, by value of `by`	required
layer	str \| None	layer of the dataset	`None`
member	str \| None	path of the dataset in the zip archive `path`	`None`
read	Callable[[Path], gpd.GeoDataFrame] \| None	function that reads the dataset from the data directory, instead of `path`, `layer` and `member`	`None`
by	str \| None	attribute that selects the mapping	`None`
soort_peilbeheer	str \| None	attribute with the type of level management	`None`
labels	dict[str, str]	the types of level management of the values of `soort_peilbeheer` that are codes	`dict()`
transitions	dict[str, str]	attributes with the dates of the transitions, as “dd-mm”, by their column of `COLUMNS`	`dict()`
zero_is_unknown	bool	whether the dataset uses levels of 0 for unknown levels	`False`

Methods

Name	Description
peilbeheer	Return the levels and transitions of the peilgebieden in `gdf`, the dataset, with the columns of `COLUMNS`.
read_dataset	Read the dataset, in `CRS`.

peilbeheer

peilbeheer.Source.peilbeheer(gdf)

Return the levels and transitions of the peilgebieden in gdf, the dataset, with the columns of COLUMNS.

read_dataset

peilbeheer.Source.read_dataset(data_dir)

Read the dataset, in CRS.

Functions

Name	Description
complete_peilbeheer	Complete the levels and transitions of the peilgebieden with the rules of this module, see its docstring.
day_month	Return a day of the year as “dd-mm”, the inverse of `day_of_year`.
day_of_year	Return the day of the year, from 1 to 365, of a date as “dd-mm” or “ddmm”, or None if it is not a date.
month_day	Return the month and day of a date as “dd-mm” or “ddmm”, or None if it is not a date of every year.
read_peilbeheer	Read the level management of the peilgebieden of a water board, with the columns of `COLUMNS`.
valid_levels	Return the levels as floats, with NaN for unknown levels.

complete_peilbeheer

peilbeheer.complete_peilbeheer(df)

Complete the levels and transitions of the peilgebieden with the rules of this module, see its docstring.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	peilgebieden with the columns of `COLUMNS`	required

Returns

Name	Type	Description
	pd.DataFrame	the peilgebieden with a target level, with all their levels and transitions

day_month

peilbeheer.day_month(day)

Return a day of the year as “dd-mm”, the inverse of day_of_year.

day_of_year

peilbeheer.day_of_year(day_month)

Return the day of the year, from 1 to 365, of a date as “dd-mm” or “ddmm”, or None if it is not a date.

month_day

peilbeheer.month_day(day_month)

Return the month and day of a date as “dd-mm” or “ddmm”, or None if it is not a date of every year.

read_peilbeheer

peilbeheer.read_peilbeheer(authority, data_dir)

Read the level management of the peilgebieden of a water board, with the columns of COLUMNS.

Parameters

Name	Type	Description	Default
authority	str	water board, a key of `SOURCES`	required
data_dir	Path	the data directory	required

Returns

Name	Type	Description
	gpd.GeoDataFrame	the peilgebieden with a target level, completed with `complete_peilbeheer`

valid_levels

peilbeheer.valid_levels(values, zero_is_unknown=False)

Return the levels as floats, with NaN for unknown levels.

Datasets use 99 or 9999 m NAP for unknown levels, so levels of 99 m from NAP or more are unknown. Some datasets also use 0, which is otherwise a level like any other.