uesgraphs.DHW_estimation.OpenDHW

Functions

add_additional_runs(timeseries_df, holidays, ...)	method to add more runs to a timeseries dataframe with the same input parameters as the original timeseries.
compare_generators(timeseries_df_1, ...[, ...])	Compares two timeseries by plotting them next to each other with the same x and y axis limits.
compute_heat(timeseries_df[, temp_dT])	Add heat columns to the timeseries
draw_detailed_histplot(timeseries_df)	https://towardsdatascience.com/advanced-histogram-using-python-bceae288e715 plot to further analyse timeseries with 1 drawoff category.
draw_histplot(timeseries_df[, extra_kde, ...])	Takes a DHW profile and plots a histogram with some stats in the title
draw_lineplot(timeseries_df[, plot_var, ...])	Plots the timeseries for a given timedelta in a year.
generate_and_distribute_drawoffs(...)	generate and distribute drawoffs
generate_daily_probability_step_function(...)	Generates probabilities for a day with 6 periods.
generate_dhw_profile(s_step, categories, ...)	Generates a DHW profile.
generate_single_drawoff_inside_boundaries(...)	From the data of one category, generate a drawoff inside the defined boundaries, similar to DHWcalc.
generate_yearly_probabilities(initial_day, ...)	Takes the probabilities of a working days and a off days and generates a list of yearly probabilities by adding a seasonal probability factor.
generate_yearly_probability_profile(s_step, ...)	generate a summed yearly probability profile.
get_data_drawoff_categories(s_step, ...)	Get some data for each drawoff category.
get_drawoffs(timeseries_df[, remove_cats])	get sorted drawoff events from a timeseries Dataframe.
get_holidays(country_code, year[, state])	Get the Julian day (day of the year) for holidays in a specific country, year, and state.
get_s_step(timeseries_df)	get the seconds within a timestep from a pandas dataframe.
import_from_dhwcalc(s_step, daylight_saving, ...)	DHWcalc yields Volume Flow TimeSeries (in Liters per hour).
jensen_shannon_distance(p, q)	method to compute the Jenson-Shannon Distance between two probability distributions.
load_steps_and_ps(mode, building[, ...])	Load the step durations and probabilities from a JSON file.
make_title_str(timeseries_df)	creates a title string based on the timeseries dataframe.
normalize_and_sum_list(lst[, save_fig])	takes a list and normalizes it based on the sum of all list elements.
plot_multiple_runs(timeseries_df[, ...])	This function should only be used when the 'add_additional_runs' function has been used before.
plot_multiple_timeseries(timeseries_lst[, ...])	plots multiple timeseries given in a list.
plot_three_histplots(timeseries_df_1, ...)	Compares three timeseries by means of a triple subplot.
reduce_no_drawoffs(timeseries_df)	for some reason, DHWcalc still yields less yearly drawoffs than OpenDHW.
resample_water_series(timeseries_df, ...)	Before resampling a dataframe, we have to choose which data has to be resampled in what way.
shift_weekend_weekday(p_work_day, p_off_day, ...)	Shifts the probabilities between the weekday list and the weekend list by a defined factor.

uesgraphs.DHW_estimation.OpenDHW.load_steps_and_ps(mode, building, building_type=None, s_step=None)

Load the step durations and probabilities from a JSON file.

Parameters:

• mode (str) – Mode of operation (“work-day” or “off-day”).

• building (str) – Type of building (“residential” or “non-residential”).

• building_type (str) – Specific type of building (e.g., “OB”, “SC”, “GS”, “RE”).

• s_step (int) – Step size in seconds, required only for residential buildings.

Returns:

List of tuples containing step durations and probabilities.

Return type:

list

uesgraphs.DHW_estimation.OpenDHW.import_from_dhwcalc(s_step, daylight_saving, categories, occupancy, mean_drawoff_vol_per_day, max_flowrate=1200)

DHWcalc yields Volume Flow TimeSeries (in Liters per hour).

Parameters:

• s_step – int: resolution of file in seconds

• categories – int: either ‘1’ or ‘4’

• mean_drawoff_vol_per_day – int: daily water demand in Liters

• daylight_saving – Bool: apply daylight saving or not

• max_flowrate – int: maximum water flowrate in L/h

Return timeseries_df:

df: dataframe that holds the data

uesgraphs.DHW_estimation.OpenDHW.generate_dhw_profile(s_step, categories, mean_drawoff_vol_per_day, occupancy, holidays, building_type, weekend_weekday_factor, initial_day=0)

Generates a DHW profile. The generation is split up in different functions and generally follows the methodology described in the DHWcalc paper from Uni Kassel.

1. Load some data for the drawoff categories (cats_df).

2. Generate a yearly probability profile

3. Generate Drawoffs and distribute them randomly into the probability profile p_norm_integral.

4. Add some additionally stats to the dataframe.

Parameters:

• s_step – int: timestep width in seconds.

• categories – int: 1 or 4 (see DHWcalc)

• weekend_weekday_factor – int: taken from DHWcalc

• mean_drawoff_vol_per_day – int: daily water demand in Liters

• initial_day – int: 0:Mon - 1:Tues … 6:Sun

Returns:

timeseries_df df: dataframe with all timeseries

uesgraphs.DHW_estimation.OpenDHW.get_data_drawoff_categories(s_step, categories, mean_drawoff_vol_per_day, building_type)

Get some data for each drawoff category. If only one category is chosen, a simplified datafarme is returned.

Parameters:

• s_step – int: seconds in a timestep. f.e 900

• categories – int: 1 or 4, 1: short laod (washing hands, etc.), 2: medium load (dish-washer, etc.), 3: bath, 4:shower (see DHWcalc)

• mean_drawoff_vol_per_day – int: volume per day used in house

Returns:

cats_df: df: Categores Data

uesgraphs.DHW_estimation.OpenDHW.generate_daily_probability_step_function(mode, s_step, building_type, save_fig=False, test_concentrated_ps=False)

Generates probabilities for a day with 6 periods. Corresponds to the mode “step function for working days and off days” in DHWcalc and uses the same standard values. Each Day starts at 0:00. Steps in hours. Sum of steps has to be 24. Sum of probabilities has to be 1.

Parameters:

• test_concentrated_ps – bool: different probabilities, very concentrated in the morning

• mode – string: working day or off day

• s_step – int: seconds within a timestep

• save_fig – Bool: plot the probability distribution

Returns:

p_day list: distribution for one day.

uesgraphs.DHW_estimation.OpenDHW.generate_yearly_probability_profile(s_step, weekend_weekday_factor, building_type, holidays, initial_day=0)

generate a summed yearly probability profile. The whole function is deterministic. The same inputs always produce the same outputs.

1. Probabilities for working days and off days are loaded (p_we, p_wd).

2. Probability of off days is increased relative to working days (shift).

3. Based on an initial day, the yearly probability distribution (p_final) is generated. The seasonal influence is modelled by a sine-function.

4. p_final is normalized and integrated. The sum over the year is thus equal to 1 (p_norm_integral).

Parameters:

• s_step – int: seconds in a timestep

• weekend_weekday_factor – float: shift probabilities towards weekend

• initial_day – int: Mon: 0 … Sun: 6

Returns:

timeseries_df: df: df that holds the yearly profile

uesgraphs.DHW_estimation.OpenDHW.shift_weekend_weekday(p_work_day, p_off_day, factor)

Shifts the probabilities between the weekday list and the weekend list by a defined factor. If the factor is bigger than 1, the probability on the weekend is increased. If its smaller than 1, the probability on the weekend is decreased.

Parameters:

• p_work_day – list: probabilities for 1 work day of the week [0…1]

• p_off_day – list: probabilities for 1 off day of the week [0…1]

• factor – float: factor to shift the probabilities between weekdays and weekend-days

Returns:

uesgraphs.DHW_estimation.OpenDHW.generate_yearly_probabilities(initial_day, p_off_day, p_work_day, s_step, holidays, building_type, plot_p_yearly=False)

Takes the probabilities of a working days and a off days and generates a list of yearly probabilities by adding a seasonal probability factor. The seasonal factor is a sine-function, like in DHWcalc.

Parameters:

• initial_day – int: 0: Mon, 1: Tue, 2: Wed, 3: Thur, 4: Fri, 5 : Sat, 6 : Sun

• p_off_day – list: probabilities of an off day

• p_work_day – list: probabilities of a working day

• s_step – int: seconds within a timestep

• plot_p_yearly – bool: plot the yearly probabilities

Returns:

p_final: list: probabilities of a full year

uesgraphs.DHW_estimation.OpenDHW.normalize_and_sum_list(lst, save_fig=False)

takes a list and normalizes it based on the sum of all list elements. then generates a new list based on the current sum of each list entry.

Parameters:

• lst – list: input list

• save_fig – bool: plot the output list

Returns:

lst_norm_integral: list output list

uesgraphs.DHW_estimation.OpenDHW.generate_and_distribute_drawoffs(timeseries_df, cats_series)

generate and distribute drawoffs

Parameters:

• timeseries_df – df: holds the timeseries

• cats_series – series: constants for a category

uesgraphs.DHW_estimation.OpenDHW.generate_single_drawoff_inside_boundaries(cats_series, s_step)

From the data of one category, generate a drawoff inside the defined boundaries, similar to DHWcalc.

Parameters:

• cats_series – df: pandas series that holds the drawoff data

• s_step – int: seconds in a timestep

Returns:

drawoff: int: drawoff eevnt in L/h

uesgraphs.DHW_estimation.OpenDHW.compute_heat(timeseries_df, temp_dT=35)

Add heat columns to the timeseries

Parameters:

• timeseries_df – df: Pandas Dataframe with all the timeseries

• temp_dT – int: temperature difference between freshwater and average DHW outlet temperature.

Returns:

timeseries_df: df: Dataframe with added ‘Heat’ Column

uesgraphs.DHW_estimation.OpenDHW.draw_lineplot(timeseries_df, plot_var='water', start_plot='2019-02-01', end_plot='2019-02-05', save_fig=False)

Plots the timeseries for a given timedelta in a year.

Parameters:

• timeseries_df – df: Dataframe that holds the timeseries.

• plot_var – str: choose to plot Water or Heat series.

• start_plot – str: start date of the plot. F.e. 2019-01-01

• end_plot – str: end date of the plot. F.e. 2019-01-07

• save_fig – bool: decide to save plots as pdf

uesgraphs.DHW_estimation.OpenDHW.draw_histplot(timeseries_df, extra_kde=False, save_fig=False)

Takes a DHW profile and plots a histogram with some stats in the title

Parameters:

• save_fig – bool: save the figure

• timeseries_df – df: Dataframe that holds the water timeseries

• extra_kde – bool: plot a detailed kde plot behind the main histogram.

uesgraphs.DHW_estimation.OpenDHW.draw_detailed_histplot(timeseries_df)

https://towardsdatascience.com/advanced-histogram-using-python-bceae288e715 plot to further analyse timeseries with 1 drawoff category.

uesgraphs.DHW_estimation.OpenDHW.add_additional_runs(timeseries_df, holidays, occupancy, building_type, total_runs=5, dir_output=None)

method to add more runs to a timeseries dataframe with the same input parameters as the original timeseries.

Parameters:

• timeseries_df –

• total_runs –

• dir_output –

Returns:

uesgraphs.DHW_estimation.OpenDHW.get_drawoffs(timeseries_df, remove_cats=True)

get sorted drawoff events from a timeseries Dataframe.

uesgraphs.DHW_estimation.OpenDHW.plot_multiple_runs(timeseries_df, plot_demands_overlay=True, start_plot='2019-02-01', end_plot='2019-02-02', plot_hist=True, plot_kde=True)

This function should only be used when the ‘add_additional_runs’ function has been used before.

Parameters:

• timeseries_df – df: dataframe with timesieries

• plot_demands_overlay – bool: plot lineplot

• start_plot – str: start date

• end_plot – str: end date

• plot_hist – bool: plot histogram

• plot_kde – bool: plot kde plot

uesgraphs.DHW_estimation.OpenDHW.plot_multiple_timeseries(timeseries_lst, col_part='Water_LperH', plot_demands_overlay=True, start_plot='2019-02-01', end_plot='2019-02-02', plot_hist=True, plot_kde=True)

plots multiple timeseries given in a list. better than “plot multiple runs?”

Parameters:

• timeseries_lst – list: list with timeseries dataframes

• col_part – str: string that matches colum names which should be plotted

• plot_demands_overlay – bool: plot lineplot of all dfs

• start_plot – str: start of lineplot

• end_plot – str: end of lineplot

• plot_hist – bool: plot histogram

• plot_kde – bool: plot kde plot

Returns:

uesgraphs.DHW_estimation.OpenDHW.compare_generators(timeseries_df_1, timeseries_df_2, start_plot='2019-03-01', end_plot='2019-03-08', plot_date_slice=True, plot_distribution=True, plot_detailed_distribution=True, save_fig=False)

Compares two timeseries by plotting them next to each other with the same x and y axis limits.

Parameters:

• timeseries_df_1 – df: first timeseries dataframe

• timeseries_df_2 – df: second timeseries dataframe

• start_plot – str: date, f.e. 2019-03-01

• end_plot – str: date, f.e. 2019-03-08

• plot_date_slice – bool: plot lineplots

• plot_distribution – bool: plot histplots

• plot_detailed_distribution – bool: plot detailed histplots

• save_fig – bool: save the plot

uesgraphs.DHW_estimation.OpenDHW.plot_three_histplots(timeseries_df_1, timeseries_df_2, timeseries_df_3)

Compares three timeseries by means of a triple subplot. :param timeseries_df_1: df: first time series :param timeseries_df_2: df: second time series :param timeseries_df_3: df: third time series

uesgraphs.DHW_estimation.OpenDHW.jensen_shannon_distance(p, q)

method to compute the Jenson-Shannon Distance between two probability distributions. 0 indicates that the two distributions are the same, and 1 would indicate that they are nowhere similar.

From https://medium.com/@sourcedexter/how-to-find-the-similarity-between-two-probability-distributions-using-python-a7546e90a08d

uesgraphs.DHW_estimation.OpenDHW.get_s_step(timeseries_df)

get the seconds within a timestep from a pandas dataframe. When loading Dataframes from a csv, the index loses its ‘freq’ attribute. This is thus just a workaround when loading Timeseries from csv.

uesgraphs.DHW_estimation.OpenDHW.make_title_str(timeseries_df)

creates a title string based on the timeseries dataframe. The title string can then be used for a variety of plots.

uesgraphs.DHW_estimation.OpenDHW.resample_water_series(timeseries_df, s_step_output)

Before resampling a dataframe, we have to choose which data has to be resampled in what way. some columns list constants, some list intensive properties (like L/h, kW) and some list extensive properties (Like Liters/kWh). Constants should stay the same, intensive properties should be averaged and extensive properties should be summed up.

Parameters:

• timeseries_df – df: dataframe that holds the timeseries

• s_step_output – int: desired output seconds in a timestep

Returns:

timeseries_df_re: df: resampled dataframe

uesgraphs.DHW_estimation.OpenDHW.reduce_no_drawoffs(timeseries_df)

for some reason, DHWcalc still yields less yearly drawoffs than OpenDHW. In case the yearly water demand is higher in an OpenDHW timeseries than the expected one, this function removes some randomly selected drawoffs events with a small flowrate to reduce the yearly water demand until its just under the expected one and simultaneously decreasing the number of drawoffs.

Parameters:

timeseries_df – df: input dataframe

Returns:

timeseries_df_cleaned: df output dataframe

uesgraphs.DHW_estimation.OpenDHW.get_holidays(country_code: str, year: int, state: str = None)

Get the Julian day (day of the year) for holidays in a specific country, year, and state.

Parameters:

• country_code (str) – The country’s ISO 3166-1 alpha-2 code (e.g., ‘DE’ for Germany).

• year (int) – The year for which to retrieve holidays.

• state (str) – The state or region subdivision code (e.g., ‘NW’ for North Rhine-Westphalia in Germany).

Returns:

A list of tuples containing the Julian day of the holiday.

Return type:

list