API

Main Function

class idf_analysis.idf_class.IntensityDurationFrequencyAnalyse(series_kind='partial', worksheet='KOSTRA', extended_durations=False)

heavy rain as a function of the duration and the return period acc. to DWA-A 531 (2012)

This program reads the measurement data of the rainfall and calculates the distribution of the rainfall as a function of the return period and the duration

for duration steps up to 12 hours (and more) and return period in a range of ‘0.5a <= T_n <= 100a’

_series

rain time-series

Type:

pandas.Series

_freq

frequency of the rain series

Type:

pandas.DateOffset

_return_periods_frame

with return periods of all given durations

Type:

pandas.DataFrame

_rain_events

Type:

pandas.DataFrame

_rainfall_sum_frame

with rain sums of all given durations

Type:

pandas.DataFrame

add_max_intensities_to_events(events, column_format='max_sum_{:0.0f}')

Add the maximum intensities for all duration steps to the events table.

Parameters:

• events (pandas.DataFrame) – events table

• column_format (str) – format of the column names.

Returns:

events table including the columns with the maximum intensities

Return type:

pandas.DataFrame

add_max_return_periods_per_duration_to_events(events, column_format='max_return_period_{:0.0f}')

Add the maximum return periods for all duration steps to the events table.

Parameters:

• events (pandas.DataFrame) – events table

• column_format (str) – format of the column names.

Returns:

events table including the columns with the maximum return periods

Return type:

pandas.DataFrame

auto_save_parameters(filename: str)

Auto-save the parameters as a yaml-file to save computation time.

auto_save_rain_events(filename: Path, sep=';', decimal='.')

auto-save the rain-events dataframe as a csv-file to save computation time.

auto_save_return_periods_frame(filename: Path)

auto-save the return-periods dataframe as a parquet-file to save computation time.

curve_figure(min_duration=None, max_duration=None, logx=False, return_periods=None, color=True, ax=None, add_interim=False, duration_steps_ticks=False, add_range_limits=False, **kwargs)

Create a plot with the idf-curves with duration on the x-axis and rainfall depth on the y-axis.

Parameters:

• min_duration (float) – Shortest duration on the plot.

• max_duration (float) – Longest duration on the plot.

• logx (bool) – Use a logarithmic scale on the x-axis.

• return_periods (list[int] | Optional) – List of return periods to plot. Default = [1, 2, 5, 10, 50, 100]

• color (bool) – Use color and a legend to differentiate between the return periods (default). Otherwise, annotation text and black lines.

• ax (plt.Axes) – Axes to plot on. Default = create new one.

• add_interim (bool) – Add interim results from the series analysis as scatter points.

• duration_steps_ticks (bool) – set the duration steps as ticks on the x-axis.

• add_range_limits (bool) – make vertical lines at each change of the duration range for the parameter formula.

Returns:

figure and axes of the plot.

Return type:

(plt.Figure, plt.Axes)

depth_of_rainfall(duration, return_period)

calculate the height of the rainfall h in L/m² = mm

Parameters:

• duration (int | float | list | numpy.ndarray | pandas.Series) – duration: in minutes

• return_period (float) – in years

Returns:

height of the rainfall h in L/m² = mm

Return type:

int | float | list | numpy.ndarray | pandas.Series

property duration_steps

get duration steps (in minutes) for the parameter calculation and basic evaluations

Returns:

duration steps in minutes

Return type:

list | numpy.ndarray

property duration_steps_for_output

get duration steps (in minutes) for the parameter calculation and basic evaluations

Returns:

duration steps in minutes

Return type:

list | numpy.ndarray

event_report(filename, min_event_rain_sum=25, min_return_period=0.5, durations=None)

create pdf file with the biggest rain events for each event is represented by a plot of the rain series and a IDF analysis where the return periods are calculated

Parameters:

• filename (str) – path (directory + filename) for the created pdf-report

• min_event_rain_sum (float) – only events with a bigger rain sum will be created

• min_return_period (float) – only events with a bigger return period will be analysed (the plot will be created anyway)

• durations (list[int]) – analysed durations (default: [5, 10, 15, 20, 30, 45, 60, 90, 120, 180, 240, 360, 540, 720, 1080, 1440, 2880, 4320])

classmethod from_idf_table(idf_table, worksheet='KOSTRA', linear_interpolation=True)

Create an IDF-analysis-object based on an idf-tabel (i.e. from a given KOSTRA table)

Parameters:

• idf_table (pandas.DataFrame) – idf-table with index=Durations and columns=return Period and values=Rainheight

• worksheet (str | optional) – name of the worksheet to use. default: ‘KOSTRA’

Returns:

idf-object

Return type:

IntensityDurationFrequencyAnalyse

get_duration(height_of_rainfall, return_period)

calculate the duration, when the height of rainfall and the return period are given

Parameters:

• height_of_rainfall (float) – in [mm]

• return_period (float) – in years

Returns:

duration in minutes

Return type:

float

get_rainfall_sum_frame(series=None, durations=None)

Get a rainfall sum frame for any series with the duration steps as columns.

Default: The time-series and the duration-steps of the analysis.

Parameters:

• series (pandas.Series, Optional) – rainfall time-series

• durations (list, Optional) – list of durations in minutes which are of interest (default: pre-defined durations)

Returns:

Rain sum depending on the duration per datetime-index.

Return type:

pandas.DataFrame

get_return_period(height_of_rainfall, duration)

calculate the return period, when the height of rainfall and the duration are given

Parameters:

• height_of_rainfall (float) – in [mm]

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

Returns:

return period in years

Return type:

int | float | list | numpy.ndarray | pandas.Series

get_return_periods_frame(series=None, durations=None)

Get the return periods for any time-series with the duration steps as columns.

Default: The time-series and the duration-steps of the analysis.

Is NaN if rainfall sum is smaller than 0.1 mm.

Parameters:

• series (pandas.Series, Optional) – rainfall time-series

• durations (list, Optional) – Durations in minutes which are of interest (default: pre-defined durations)

Returns:

Return periods depending on the duration per datetime-index.

Return type:

pandas.DataFrame

property model_rain_block

Create a model block rain class.

Returns:

Synthetic model block rain.

Return type:

_BlockRain

property model_rain_euler

Create a model Euler rain class.

Returns:

Synthetic model Euler rain.

Return type:

_EulerRain

property parameters

get the calculation parameters

calculation method depending on the used worksheet and on the duration also the parameters for each method

to save some time and save the parameters with IntensityDurationFrequencyAnalyse.write_parameters() and read them later with IntensityDurationFrequencyAnalyse.read_parameters()

Returns:

calculation parameters

Return type:

IdfParameters

r_720_1()

rain flow rate in [l/(s*ha)] for a duration of 12h and a return period of 1 year

Returns:

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

Return type:

float

property rain_events

get the all the rain events of the time-series

default minimal gap between events is 4 hours

Returns:

data-frame of events with start-, end-time and duration

Return type:

pandas.DataFrame

rain_flow_rate(duration, return_period)

Convert the height of rainfall to 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:

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

• return_period (float) – in years

Returns:

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

Return type:

int | float | list | numpy.ndarray | pandas.Series

property rainfall_sum_frame

Get the rainfall sum over the whole time-series for the default duration steps.

Returns:

Rain sum depending on the duration per datetime-index.

Return type:

pandas.DataFrame

read_parameters(filename, worksheet=None)

Read parameters from a .yaml-file to save computation time.

Extract interim results from parameters.

Parameters:

filename (str, Path) – filename of the parameters yaml-file

read_rain_events(filename, sep=';', decimal='.')

read the rain-events dataframe as a csv-file to save computation time.

read_return_periods_frame(filename, **kwargs)

read the return-periods dataframe as a parquet-file to save computation time.

result_figure(min_duration=None, max_duration=None, logx=False, return_periods=None, color=True, ax=None, add_interim=False, duration_steps_ticks=False, add_range_limits=False, **kwargs)

Create a plot with the idf-curves with duration on the x-axis and rainfall depth on the y-axis.

Parameters:

• min_duration (float) – Shortest duration on the plot.

• max_duration (float) – Longest duration on the plot.

• logx (bool) – Use a logarithmic scale on the x-axis.

• return_periods (list[int] | Optional) – List of return periods to plot. Default = [1, 2, 5, 10, 50, 100]

• color (bool) – Use color and a legend to differentiate between the return periods (default). Otherwise, annotation text and black lines.

• ax (plt.Axes) – Axes to plot on. Default = create new one.

• add_interim (bool) – Add interim results from the series analysis as scatter points.

• duration_steps_ticks (bool) – set the duration steps as ticks on the x-axis.

• add_range_limits (bool) – make vertical lines at each change of the duration range for the parameter formula.

Returns:

figure and axes of the plot.

Return type:

(plt.Figure, plt.Axes)

result_table(durations=None, return_periods=None, add_names=False, add_unit=True, as_intensity=False)

Get an idf-table of rainfall depth with return periods as columns and durations as rows.

Parameters:

• durations (list | numpy.ndarray) – list of durations in minutes for the table

• return_periods (list) – list of return periods in years for the table

• add_names (bool) – weather to use expressive names as index- & column-label

• add_unit (bool) – weather to add units to index- & column-label

Returns:

idf table

Return type:

pandas.DataFrame

property return_periods_frame

Get the return periods over the whole time-series for the default duration steps.

Is NaN if rainfall sum is smaller than 0.1 mm.

Returns:

data-frame of return periods where the columns are the duration steps

Return type:

pandas.DataFrame

set_series(series)

set the series for the analysis

Parameters:

series (pandas.Series) – precipitation time-series

write_parameters(filename)

save parameters as yaml-file to save computation time.

Parameters:

filename (str) – filename for the parameters yaml-file

write_rain_events(filename, sep=';', decimal='.')

save the rain-events dataframe as a csv-file for external use or to save computation time.

write_return_periods_frame(filename, **kwargs)

save the return-periods dataframe as a parquet-file to save computation time.