Base Functions

Calculation Methods

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

idf_analysis.event_series_analysis.annual_series(rolling_sum_values, year_index)

Create an annual series of the maximum overlapping sum per year and calculate the “u” and “w” parameters.

acc. to DWA-A 531 chap. 5.1.5

Gumbel distribution | https://en.wikipedia.org/wiki/Gumbel_distribution

Parameters:

• rolling_sum_values (numpy.ndarray) – Array with maximum rolling sum per event per year.

• year_index (numpy.ndarray) – Array with year of the event.

Returns:

Parameter u and w from the annual series for a specific duration step as a tuple.

Return type:

dict[str, float]

idf_analysis.event_series_analysis.calculate_u_w(file_input, duration_steps, series_kind)

Statistical analysis for each duration step.

acc. to DWA-A 531 chap. 5.1

Save the parameters of the distribution function as interim results.

acc. to DWA-A 531 chap. 4.4: use the annual series only for measurement periods over 20 years

Parameters:

• file_input (pandas.Series) – precipitation data

• duration_steps (list[int] | numpy.ndarray) – in minutes

• series_kind (str) – ‘annual’ or ‘partial’

Returns:

with key=durations and values=dict(u, w)

Return type:

dict[int, dict]

idf_analysis.event_series_analysis.iter_event_series(file_input, duration_steps)

Statistical analysis for each duration step.

acc. to DWA-A 531 chap. 5.1

Save the parameters of the distribution function as interim results.

Parameters:

• file_input (pandas.Series) – precipitation data

• duration_steps (list[int] | numpy.ndarray) – in minutes

Yields:

series – max rainfall intensity per event for each duration step

idf_analysis.event_series_analysis.partial_series(rolling_sum_values, measurement_period)

Create a partial series of the largest overlapping sums and calculate the “u” and “w” parameters.

acc. to DWA-A 531 chap. 5.1.4

Exponential distribution | https://en.wikipedia.org/wiki/Exponential_distribution

Parameters:

• rolling_sum_values (numpy.ndarray) – Array with maximum rolling sum per event.

• measurement_period (float) – Measurement period in years.

Returns:

parameter u and w from the partial series for a specific duration step as a tuple

Return type:

dict[str, float]

idf_analysis.parameter_formulations.folded_log_formulation(duration, param, case, param_mean=None, duration_mean=None)

Parameters:

• duration

• param

• case

• param_mean

• duration_mean

Returns:

idf_analysis.parameter_formulations.hyperbolic_formulation(duration: array, param: array, a_start=20.0, b_start=15.0, param_mean=None, duration_mean=None)

Computes the hyperbolic formulation using the given parameters.

Parameters:

• duration (np.array) – Array of durations.

• param (np.array) – Array of parameters.

• a_start (float) – Initial value for ‘a’ parameter.

• b_start (float) – Initial value for ‘b’ parameter.

• param_mean (float, optional) – Mean value of parameters. Defaults to None.

• duration_mean (float, optional) – Mean value of durations. Defaults to None.

Returns:

Computed value of ‘a’ and ‘b’.

Return type:

tuple[float, float]

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

classmethod from_interim_results_file(interim_results_fn, worksheet='KOSTRA')

DEPRECIATED: for compatibility reasons. To use the old file and convert it to the new parameters file

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 formulation

Parameters:

• return_periods (float | np.array | 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)

Parameters:

• filename

• series_label

• index_label

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

Returns:

precipitation series

Return type:

pandas.Series

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)

Parameters:

series (pandas.Series)

Returns:

the resampled series AND the final frequency in minutes

Return type:

tuple[pandas.Series, int]

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.height2rate(height_of_rainfall, duration)

calculate the specific rain flow rate in [l/(s*ha)] if 2 array-like parameters are give, a 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, a 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.timedelta_components_plus(td, min_freq='min')

Schaltjahre nicht miteinbezogen

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

Schaltjahre nicht miteinbezogen

Plotting helper functions

Functions to add or manipulate plotting figures.

idf_analysis.plot_helpers.idf_bar_axes(ax, idf_table, return_period_colors={1: '#00ffff', 2: '#add8e6', 5: '#0000ff', 10: '#ffff00', 20: '#ffa500', 50: '#ff0000', 100: '#ff00ff'})

create

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