Base Functions

Calculation Methods

Functions to analyse the precipitations series based on the core method.

class idf_analysis.idf_backend.IdfParameters(series_kind: str = 'partial', worksheet: str = 'KOSTRA', extended_durations=False)

get_array_param(p, duration)

Parameters:

• p (str) – name of the parameter ‘u’ or ‘w’

• duration (numpy.ndarray) – in minutes

Returns:

u, w

Return type:

(numpy.ndarray, numpy.ndarray)

get_scalar_param(p, duration)

Parameters:

• p (str) – name of the parameter ‘u’ or ‘w’

• duration (float | int) – in minutes

Returns:

u, w

Return type:

(float, float)

get_u_w(duration)

calculate the u and w parameters depending on the durations

Parameters:

duration (numpy.ndarray| list | float | int) – in minutes

Returns:

u and w

Return type:

(float, float)

measured_points(return_periods, max_duration=None)

Get the calculation results of the rainfall with u and w without the estimation of the formula.

Parameters:

• return_periods (float | np.ndarray | list | pd.Series) – return period in [a]

• max_duration (float) – max duration in [min]

Returns:

series with duration as index and the height of the rainfall as data

Return type:

pd.Series

set_parameter_approaches_from_worksheet(worksheet)

Set approaches depending on the duration and the parameter.

Parameters:

worksheet (str) – worksheet name for the analysis: - ‘DWA-A_531’ - ‘ATV-A_121’ - ‘DWA-A_531_advektiv’ (yet not implemented)

Returns:

table of approaches depending on the duration and the parameter

Return type:

list[dict]

Input and Output

Function for reading and writing files.

idf_analysis.in_out.import_series(filename, series_label='precipitation', index_label='datetime', csv_reader_args=None)

Import series data from csv, parquet of pickle file.

Parameters:

• filename (str or pathlib.Path)

• series_label (str) – name of series in file.

• index_label (str) – prefered index name. (just used for plotting)

• csv_reader_args (dict) – for example: sep=”,” or “.” and decimal=”;” or “,”

Returns:

precipitation series

Return type:

pandas.Series

idf_analysis.in_out.read_yaml(filename)

Read yaml file.

Parameters:

filename (str or pathlib.Path) – path to yaml file.

Returns:

dict to read

Return type:

dict

idf_analysis.in_out.write_yaml(data, filename)

Write dict to yaml file.

Parameters:

• data (dict) – dict to write

• filename (str or pathlib.Path) – path to yaml file.

SWW Utils

Functions to help analyse data in a general way. Most of this function have been developed on the institute of urban water management at the university of technology Graz.

exception idf_analysis.sww_utils.IdfError

Some Error Within this Package

idf_analysis.sww_utils.agg_events(events, series, agg='sum')

Parameters:

• events (pandas.DataFrame) – table of events

• series (pandas.Series) – time-series data

• agg (str | function) – aggregation of time-series

Returns:

result of function of every event

Return type:

numpy.ndarray

idf_analysis.sww_utils.event_duration(events)

calculate the event duration

Parameters:

events (pandas.DataFrame) – table of events with COL.START and COL.END times

Returns:

duration of each event

Return type:

pandas.Series

idf_analysis.sww_utils.event_number_to_series(events, index)

make a time-series where the value of the event number is paste to the <index>

Parameters:

• events (pandas.DataFrame)

• index (pandas.DatetimeIndex)

Return type:

pandas.Series

idf_analysis.sww_utils.guess_freq(date_time_index, default=Timedelta('0 days 00:01:00'))

guess the frequency by evaluating the most often frequency

Parameters:

• date_time_index (pandas.DatetimeIndex) – index of a time-series

• default (pandas.Timedelta)

Returns:

frequency of the date-time-index

Return type:

pandas.DateOffset

idf_analysis.sww_utils.rain_bar_plot(rain, ax=None, color='#1E88E5', reverse=False, step='post', joinstyle='miter', capstyle='butt')

Make a standard precipitation/rain plot.

Parameters:

• rain (pandas.Series)

• ax (matplotlib.axes.Axes)

• color (str)

• reverse (bool)

• step (str) – ‘mid’ ‘post’ pre’

Returns:

rain plot

Return type:

matplotlib.axes.Axes

idf_analysis.sww_utils.rain_events(series, ignore_rain_below=0.01, min_gap=Timedelta('0 days 04:00:00'))

get rain events as a table with start and end times

Parameters:

• series (pandas.Series) – rain series

• ignore_rain_below (float) – where it is considered as rain

• min_gap (pandas.Timedelta) – 4 hours of no rain between events

Returns:

table of the rain events

Return type:

pandas.DataFrame

idf_analysis.sww_utils.resample_rain_series(series)

Resamples a rain time-series to an appropriate frequency based on the duration of the series.

The function determines the optimal resampling frequency (in minutes) by comparing the total duration of the series against predefined thresholds. If the original frequency is already finer than the calculated optimal frequency, the series is returned unchanged. Otherwise, the series is resampled to the new frequency by summing the values within each interval.

Parameters:

series (pandas.Series) – A time-series of rain data, indexed by a pandas.DatetimeIndex. The series should contain numeric values representing rain amounts.

Returns:

A tuple containing:

• The resampled time-series (if resampling was applied) or the original series (if no resampling was needed).

• The final frequency of the series in minutes (e.g., 5 for 5-minute intervals).

Return type:

tuple[pandas.Series, int]

Notes

• The resampling thresholds are defined as follows:

  • Duration < 5 hours: 1-minute frequency.

  • Duration < 12 hours: 2-minute frequency.

  • Duration < 1 day: 5-minute frequency.

  • Duration < 2 days: 10-minute frequency.

  • Duration < 3 days: 15-minute frequency.

  • Duration < 4 days: 20-minute frequency.

• If the original frequency of the series is finer than the calculated optimal frequency, the series is returned unchanged, and the original frequency is converted to minutes.

• Resampling is performed using the sum of values within each interval to preserve the total rain amount.

Converter helper functions

Functions to help convert things and units.

idf_analysis.little_helpers.delta2min(time_delta)

convert timedelta to float in minutes

Parameters:

time_delta (pandas.Timedelta, pandas.DateOffset)

Returns:

the timedelta in minutes

Return type:

float

idf_analysis.little_helpers.duration_steps_readable(durations)

convert the durations to a more readable form

Parameters:

durations (list[int | float]) – in minutes

Returns:

of the readable duration list

Return type:

list[str]

idf_analysis.little_helpers.event_caption(event, unit='mm', lang='en')

Generates a human-readable caption for a rain event in English or German.

Parameters:

• event (dict or pandas.Series) – A dictionary or Series containing event details. Expected keys include: - COL.START: Start time of the event. - COL.END: End time of the event. - COL.LP: Total rainfall sum (optional). - COL.DUR: Duration of the event (optional). - COL.MAX_PERIOD: Maximum return period (optional). - COL.MAX_PERIOD_DURATION: Duration of the maximum return period in minutes (optional).

• unit (str, optional) – Unit for rainfall (default: ‘mm’).

• lang (str, optional) – Language (‘en’ for English, ‘de’ for German, default: ‘en’).

Returns:

A formatted string describing the rain event.

Return type:

str

Example

Given an event with:

• COL.START = pd.Timestamp(‘2023-01-01 12:00’)

• COL.END = pd.Timestamp(‘2023-01-01 14:00’)

• COL.LP = 15.5

• COL.DUR = pd.Timedelta(hours=2)

• COL.MAX_PERIOD = 10

• COL.MAX_PERIOD_DURATION = 30

The german output might look like:

“Regenereignis

von 01.01.2023 12:00 bis 14:00 mit einer Regensumme von 15.5 mm und einer Dauer von 2 Stunden. Die maximale Wiederkehrperiode war 10 a bei einer Dauerstufe von 30 minutes.”

The english output might look like:

“rain event

between 2023-01-01 12:00 and 14:00 with a total sum of 15.5 mm and a duration of 2 hours. The maximum return period was 10 years at a duration of 30 minutes.”

idf_analysis.little_helpers.height2rate(height_of_rainfall, duration)

calculate the specific rain flow rate in [l/(s*ha)]

if 2 array-like parameters are give, an element-wise calculation will be made. So the length of the array must be the same.

Parameters:

• height_of_rainfall (float | np.ndarray | pd.Series) – height_of_rainfall: in [mm]

• duration (float | np.ndarray | pd.Series) – in minutes

Returns:

specific rain flow rate in [l/(s*ha)]

Return type:

float | np.ndarray | pd.Series

idf_analysis.little_helpers.minutes_readable(minutes)

convert the duration in minutes to a more readable form

Parameters:

minutes (float | int) – duration in minutes

Returns:

duration as a string

Return type:

str

idf_analysis.little_helpers.rate2height(rain_flow_rate, duration)

convert the rain flow rate to the height of rainfall in [mm]

if 2 array-like parameters are give, an element-wise calculation will be made. So the length of the array must be the same.

Parameters:

• rain_flow_rate (float | np.ndarray | pd.Series) – in [l/(s*ha)]

• duration (float | np.ndarray | pd.Series) – in minutes

Returns:

height of rainfall in [mm]

Return type:

float | np.ndarray | pd.Series

idf_analysis.little_helpers.return_period_formatter(t)

Formats a return period value into a human-readable string.

The function categorizes the return period value into specific ranges and returns a formatted string based on the range. This is useful for displaying return periods in a clear and concise manner.

Parameters:

t (float) – The return period value to format.

Returns:

A formatted string representing the return period. The formatting rules are:

• If t < 1: Returns “< 1”.

• If t > 200: Returns “$gg$ 100” (indicating much greater than 100).

• If t > 100: Returns “> 100”.

• Otherwise: Returns the value formatted to one decimal place (e.g., “50.0”).

Return type:

str

Example

>>> return_period_formatter(0.5)
'< 1'
>>> return_period_formatter(150)
'> 100'
>>> return_period_formatter(250)
'$\gg$ 100'
>>> return_period_formatter(50.123)
'50.1'

idf_analysis.little_helpers.timedelta_components_plus(td, min_freq='min')

Decomposes a timedelta into its components, approximating years and weeks.

Parameters:

• td (datetime.timedelta or pandas.Timedelta) – The time difference to decompose.

• min_freq (str, optional) – The minimum frequency for rounding (e.g., ‘min’, ‘s’). Defaults to ‘min’.

Returns:

A list of lists, where each sublist contains a numerical value and its corresponding time unit.

Return type:

list

Note

Leap years are not considered in year calculations. Possible components: [years, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds]

idf_analysis.little_helpers.timedelta_components_readable(list_of_components, short=False, sep=', ', lang='en')

Converts a list of time components into a human-readable string.

Parameters:

• list_of_components (list) – A list of [value, unit] pairs representing time components.

• short (bool, optional) – If True, uses abbreviated unit names (e.g., ‘y’ for years). Defaults to False.

• sep (str, optional) – Separator between components. Defaults to ‘, ‘.

• lang (str, optional) – Language (‘en’ for English, ‘de’ for German, default: ‘en’).

Returns:

A formatted string representing the time components, with the last component joined by “and”.

Return type:

str

Note

• Singular units (e.g., “1 year” instead of “1 years”) are handled automatically.

• The last separator is replaced with “and” for better readability unless short mode is enabled.

Example

timedelta_components_readable([(2, ‘days’), (3, ‘hours’)]) -> ‘2 days and 3 hours’

idf_analysis.little_helpers.timedelta_readable(td, min_freq='min', short=False, sep=', ', lang='en')

Converts a timedelta into a human-readable string.

Parameters:

• td (datetime.timedelta or pandas.Timedelta) – The time difference to format.

• min_freq (str, optional) – The minimum frequency for rounding (e.g., ‘min’, ‘s’). Defaults to ‘min’.

• short (bool, optional) – Whether to use abbreviated unit names (e.g., ‘h’ for hours). Defaults to False.

• sep (str, optional) – Separator used between components in the output string. Defaults to ‘, ‘.

• lang (str, optional) – Language (‘en’ for English, ‘de’ for German, default: ‘en’).

Returns:

A formatted string representing the time duration.

Return type:

str

Note

Leap years are not considered in year calculations.

Example

timedelta_readable(pd.Timedelta(days=400, hours=5)) -> ‘1 year, 5 weeks and 5 hours’

idf_analysis.little_helpers.timedelta_readable2(d1, d2, min_freq='min', short=False, sep=', ', lang='en')

Computes the difference between two dates and returns a human-readable string.

Parameters:

• d1 (datetime-like) – The start date.

• d2 (datetime-like) – The end date.

• min_freq (str, optional) – The minimum frequency for rounding (e.g., ‘min’, ‘s’). Defaults to ‘min’.

• short (bool, optional) – Whether to use abbreviated unit names (e.g., ‘h’ for hours). Defaults to False.

• sep (str, optional) – Separator used between components in the output string. Defaults to ‘, ‘.

• lang (str, optional) – Language (‘en’ for English, ‘de’ for German, default: ‘en’).

Returns:

A formatted string representing the time difference.

Return type:

str

Note

• Approximates the number of years by adjusting for the closest full year.

• Leap years are not considered in year calculations.

Example

timedelta_readable2(pd.Timestamp(‘2020-01-01’), pd.Timestamp(‘2023-06-15’)) -> ‘3 years, 5 months and 14 days’

Plotting helper functions

Functions to add or manipulate plotting figures.

idf_analysis.plot_helpers.idf_bar_axes(ax, idf_table, return_period_colors=None)

Create a return period bar axes for the event plot.

Parameters:

• ax (matplotlib.pyplot.Axes)

• idf_table (pandas.DataFrame)

• return_period_colors (dict) – color of each return period {return period: color}

Return type:

matplotlib.pyplot.Axes