Dash Callbacks 

This page contains all callbacks which are the backbone of the dash application. They are called by their inputs, get their data with states and return to properties of dash components with outputs.

An example callback, which takes on input and returns the values of the in put and the state to display in the output component is shown below. More information on dash callbacks can be found in the Dash User Guide, here for basic callbacks and here for more advanced callbacks.

@app.callback(
    Output('my-output', 'children'),
    Input('my-input', 'value'),
    State('my-state', 'value'),
)
def update_output_div(input_value, state_value):
    return f'Output: {input_value + state_value}'

Note

The automatic documentation of the callback files is not as straightforward as for the others, because of nested functions. See how to do it in Tools.

General Callbacks 

Warning

This documentation is not automatically generated by changing the docstrings in the code. See the note on thop of the page for more information.

general_callbacks.py contains all dash callbacks for general functions of the app.

general_callbacks.backup(interval, gridObject_dict, device_dict, elements_grid, elements_bath, elements_kitchen, elements_livingroom, elements_office, settings_dict, custom_house)

Stores all relevant data in DCC store components, which stays stored for the whole session, even on a reload. Is triggered by an intervall (e.g. every 10 seconds).

Parameters:

interval – [Input] Interval to trigger the backup
gridObject_dict – [State] Dictionary containing all grid objects and their properties
device_dict – [State] Dictionary containing all house devices and their properties
elements_grid – [State] Elements of grid cytoscape
elements_bath – [State] Elements of bathroom cytoscape
elements_kitchen – [State] Elements of kitchen cytoscape
elements_livingroom – [State] Elements of livingroom cytoscape
elements_office – [State] Elements of office cytoscape
settings_dict – [State] Dictionary containing the settings
custom_house – [State] Id of custom house

Returns:

store_backup > data

general_callbacks.control_tutorial(btn, page, style, tutorial_steps)

Opens or closes the tutorial on button click.

Parameters:

btn – [Input] “Tutorial” button
page – [Input] Pagination selection of tutorial step
style – [State] Opening status stored in the style property
tutorial_steps – [State] List of tutorial steps and help

Returns:

card_tutorial > style

Returns:

store_tutorial > data

Returns:

pagination_tutorial > total

Returns:

card_tutorial_content > children

general_callbacks.download_start_config(btn)

With the button the user can download a start grid configuration. The function reads the file in the assets folder and gives it to the download component.

Parameters:: btn – [Input] Download Start Configuration button in settings
Returns:: download_json > data

general_callbacks.enter_save(key_n, key_event)

Listen to Enter events and change store_save_by_enter to trigger save action.

Parameters:

key_n – [Input] Key event listener n_events
key_event – [State] Key event listener event

Returns:

store_save_by_enter > data

general_callbacks.filename_upload(filename)

Shows the filename of an uploaded file below the upload area to show the user that it was uploaded.

Parameters:: filename – [Input] Filename of uploaded file
Returns:: text_filename_load > children

general_callbacks.help_tutorial(btn, tutorial_steps, page)

Opens the help drawer and loads the help of the current tutorial step into it.

Parameters:

btn – [Input] Help button
tutorial_steps – [State] List of tutorial steps and help
page – [State] Selected page/step of the tutorial

Returns:

drawer_help > opened

Returns:

drawer_help > children

general_callbacks.main_menu(btn_save, btn_load_menu, btn_own, btn_load, btn_start_load, gridObject_dict, device_dict, elements_grid, elements_bath, elements_kitchen, elements_livingroom, elements_office, filename, upload_content, settings_dict, custom_house, own_devices)

Handles all functions of the main menu (burger menu in the navbar). It saves the configuration to a download-json file or loads an uploaded one. Also, it is handles the download of created own devices.

Parameters:

btn_save – [Input] Main Menu button to save a configuration
btn_load_menu – [Input] Main menu button to load a configuration
btn_own – [Input] Main menu button to download own devices
btn_load – [Input] Start Modal load button
btn_start_load – [Input] Button to start the upload of a configuration file
gridObject_dict – [State] Dictionary containing all grid objects and their properties
device_dict – [State] Dictionary containing all house devices and their properties
elements_grid – [State] Elements of grid cytoscape
elements_bath – [State] Elements of bathroom cytoscape
elements_kitchen – [State] Elements of kitchen cytoscape
elements_livingroom – [State] Elements of livingroom cytoscape
elements_office – [State] Elements of office cytoscape
filename – [State] Filename of uploaded file
upload_content – [State] Content of uploaded file
settings_dict – [State] Dictionary containing the settings
custom_house – [State] Id of custom house
own_devices – [State] Dictionary containing all own devices

Returns:

download_json > data

Returns:

modal_load_configuration > opened

Returns:

store_grid_object_dict > data

Returns:

store_device_dict > data

Returns:

cyto_grid > elements

Returns:

cyto_bathroom > elements

Returns:

cyto_livingroom > elements

Returns:

cyto_kitchen > elements

Returns:

cyto_office > elements

Returns:

input_week > value

Returns:

input_year > value

Returns:

store_custom_house > data

Returns:

tab_house > disabled

Returns:

store_notification > data

general_callbacks.manage_menu_tabs(tab_value_house, tab_value_grid, tabs_main, menu_children, gridObject_dict, device_dict, selected_element_grid, selected_element_house)

Manages the menu tabs, which are shown when a grid object or house device was clicked. It removes all tab panels and creates the new one to show.

Parameters:

tab_value_house – [Input] Updated value of the house menu tab
tab_value_grid – [Input] Updated value of the grid menu tab
tabs_main – [Input] Tab value of main tab, whether grid, house or settings mode is shown
menu_children – [State] Existing tab panels of the menu_parent_tab
gridObject_dict – [State] Dictionary containing all grid objects and their properties
device_dict – [State] Dictionary containing all devices in the custom house
selected_element_grid – [State] Cytoscape element which was clicked in the grid
selected_element_house – [State] Cytoscape element which was clicked in the house

Returns:

menu_parent_tabs > children

Returns:

menu_parent_tabs > value

Returns:

active_switch_grid > style

Returns:

active_switch_house > style

Returns:

store_notification > data

general_callbacks.notification(notification_data, notif_list)

Handles all notifications raised. If it is a predefined notification, the text, icon and color is fetched and the notification is found. If not, the notification_data itself is shown in the notification. Also, the notification is added to the list in the drawer and the pill showing the number of notifications is updated.

Parameters:

notification_data – [Input] Raised notification data
notif_list – [State] List of notifications raised before

Returns:

notification_container > children

Returns:

drawer_notifications > children

Returns:

badge_notifications > children

general_callbacks.open_drawer_notifications(btn)

Opens the data drawer when button is clicked.

Parameters:: btn – [Input] Button Notification input
Returns:: True to open drawer
Return type:: bool

general_callbacks.open_readme(btn)

Opens the readme modal.

Parameters:: btn – [Input] Button Readme input
Returns:: True to open readme
Return type:: bool

general_callbacks.open_start_card(btn, btn_load)

Closes the start modal which is shown on loading the app.

Parameters:

btn – [Input] Button to start the app
btn_load – [Input] Button to load a configuration

Returns:

False to close the modal

Return type:

bool

general_callbacks.refresh(interval, backup_dict)

Loads all backup data on a refresh, if existing. Is triggered once by an interval. Closes the start-modal if it is a refresh with backup data.

Parameters:

interval – [Input] Interval which is only triggered once at a refresh
backup_dict – [State] Stored backup data

Returns:

store_grid_object_dict > data

Returns:

store_device_dict > data

Returns:

cyto_grid > elements

Returns:

cyto_bathroom > elements

Returns:

cyto_livingroom > elements

Returns:

cyto_kitchen > elements

Returns:

cyto_office > elements

Returns:

input_week > value

Returns:

input_year > value

Returns:

store_custom_house > data

Returns:

tab_house > disabled

Returns:

modal_start > opened

general_callbacks.save_props_action(btn_save, key_save, tabs_main, device_dict, selected_element_house, selected_element_grid, children, day, gridObject_dict, year, week, used_profiles, checkbox, figure_pv, figure_house)

Callback to save all properties of a selected element when save-button or enter was pressed.

Parameters:

btn_save – [Input] Button to save properties
key_save – [Input] Event of Enter-click
tabs_main – [State] Tab value of main tab, whether grid, house or settings mode is shown
device_dict – [State] Dictionary containing all devices in the custom house
selected_element_house – [State] Cytoscape element which was clicked in the house
selected_element_grid – [State] Cytoscape element which was clicked in the grid
children – [State] Children of the menu_parent_tabs, all Inputs of the component menu
day – [State] Day selected in the pagination of the menu
gridObject_dict – [State] Dictionary containing all grid objects
year – [State] Year selected in settings
week – [State] Week selected in settings
used_profiles – [State] Already used random profiles from IZES
checkbox – [State] Bool if checkbox to load random profile is checked
figure_pv – [State] Figure element of graph_pv
figure_house – [State] Figure element of graph_house

Returns:

store_device_dict > data

Returns:

store_grid_object_dict > data

Returns:

graph_pv > figure

Returns:

graph_house > figure

Returns:

store_used_profiles > data

Returns:

checkbox_random_profile > checked

Returns:

store_save_by_enter > data

Returns:

store_notification > data

general_callbacks.settings(week, year, settings_dict)

Store the settings to the dcc store object if changed.

Parameters:

week – [Input] Week of the year
year – [Input] Year to get data from
settings_dict – DCC store object to save to

Returns:

store_settings > data

general_callbacks.update_settings(btn_update, gridObject_dict, week, year, data_energy, cost_kwh, device_dict)

Updates all components with the new settings.

Parameters:

btn_update – [Input] Button to update the settings
gridObject_dict – [State] Dictionary containing all grid objects and their properties
week – [State] Input week of year
year – [State] Input year
data_energy – [State] Energy result data of house calculation
cost_kwh – [State] Cost of 1 kWh of electrical energy, from settings
device_dict – [State] Dictionary containing all devices in the custom house

Returns:

store_device_dict > data

Returns:

store_grid_object_dict > data

Returns:

menu_parent_tabs > value

Returns:

cost_tab > children

Returns:

store_notification > data

Grid Callbacks 

Warning

This documentation is not automatically generated by changing the docstrings in the code. See the note on thop of the page for more information.

grid_callbacks.py contains all dash callbacks for grid functions of the app.

grid_callbacks.button_add_pressed()

Takes the id of a pressed button to add a grid object and passes it to the store element. A change of this then triggers another callback to add the object.

Parameters:: args – [Input] Add grid object buttons
Returns:: store_add_node > data

grid_callbacks.compass_action(gridObject_dict, selected_element)

If a button of the PV compass was clicked, the corresponding orientation is written to the PV object and the compass needle is rotated to the clicked orientation.

Parameters:

gridObject_dict – [State] Dictionary containing all grid objects and their properties
selected_element – [State] Cytoscape element which was clicked in the grid
args – [Input] One Input per button of the compass

Returns:

store_grid_object_grid > data

Returns:

button_compass > style

grid_callbacks.custom_house_style(selected_element, elements)

Sets the style of a house which is selected as custom. It changes the shape from a rounded rectangle to a normal one.

Parameters:

selected_element – [Input] Id of house which was selected as custom
elements – [State]

Returns:

cyto_grid > elements

grid_callbacks.edge_labels(labels, elements)

Takes generated edge labels, sets them for each edge, sets the direction of the edge arrow and returns the updates cytoscape elements.

Parameters:

labels – [Input] Generated edge labels
elements – [State] Cytoscape grid elements

Returns:

cyto_grid > elements

grid_callbacks.edit_grid(btn_add, node, btn_delete, btn_line, button_hv, button_lv, elements, gridObject_dict, btn_line_active, start_of_line, selected_element, node_ids, tabs_main)

This callback manages all the edit action of the grid cytoscape. It adds new nodes and lines and deletes them if wanted.

Parameters:

btn_add – [Input] Id of pressed add object button
node – [Input] Pressed node of cyto_grid
btn_delete – [Input] Button to delete an object
btn_line – [Input] Button to activate line edit mode
button_hv – [Input] Button to select the high voltage side of the transformer
button_lv – [Input] Button to select the low voltage side of the transformer
elements – [State] Elements of grid cytoscape
gridObject_dict – [State] Dictionary containing all grid objects and their properties
btn_line_active – [State] Status of the line edit mode
start_of_line – [State] First clicked node to add a line
selected_element – [State] Selected element of the cyto_grid
node_ids – [State] Two node ids of nodes to connect, but voltage has to be set
tabs_main – [State] Tab value of main tab, whether grid, house or settings mode is shown

Returns:

cyto_grid > elements

Returns:

store_grid_object_dict > data

Returns:

start_of_line > data

Returns:

store_element_deleted > data,

Returns:

store_notification > data

Returns:

store_get_voltage > data

Returns:

modal_voltage > opened

grid_callbacks.edit_grid_objects(node, edge, element_deleted, control, selected_element, gridObject_dict, btn_line_active, custom_house)

Callback which controls what happens when nodes or edges in the grid are clicked. Also, this callback handles the selection of the house mode (preset or custom). If an element is deleted, it closes the connected tab.

Parameters:

node – [Input] Clicked node of cytoscape
edge – [Input] Clicked edge of cytoscape
element_deleted – [Input] Id of the element which was deleted
control – [Input] Segmented control if house mode is preset or custom
selected_element – [State] Selected element of the cyto_grid
gridObject_dict – [State] Dictionary containing all grid objects and their properties
btn_line_active – [State] Status of the line edit mode
custom_house – [State] Id of custom configured house

Returns:

store_grid_object_dict > data

Returns:

store_menu_change_tab_grid > data

Returns:

cyto_grid > tapNodeData,

Returns:

cyto_grid > tapEdgeData

Returns:

store_selected_element_grid > data

Returns:

tabs_main > value

Returns:

house_fade > is_in,

Returns:

store_custom_house > data

Returns:

tab_house > disabled

Returns:

house_mode > value

Returns:

store_notification > data

grid_callbacks.edit_mode(btn_line, n_events, event, btn_active)

This callback activates or deactivates the line edit mode with the line button and the ESC key. It also sets the style of the button if it is activated or not.

Parameters:

btn_line – [Input] Button to add a line between grid objects
n_events – [Input] Key event listener n_events
event – [State] Key event listener event
btn_active – [State] Status of line edit mode

Returns:

cyto_grid > autoungrabify

Returns:

store_line_edit_active > data

Returns:

button_line > variant

grid_callbacks.start_calculation_grid(btn, elements, gridObject_dict, tabs_main)

Starts the calculation of the grid and calls all necessary functions.

Parameters:

btn – [Input] Button to start calculation
elements – [State] Elements of grid cytoscape
gridObject_dict – [State] Dictionary containing all grid objects and their properties
tabs_main – [State] Tab value of main tab, whether grid, house or settings mode is shown

Returns:

store_flow_data > data

Returns:

store_power_grid > data

Returns:

tabs_menu > value

Returns:

result_parent_tabs > value

Returns:

cyto_grid > stylesheet

Returns:

cyto_grid > elements

Returns:

timestep_slider > max

Returns:

store_edge_labels > data

Returns:

store_notification > data

grid_callbacks.time_slider(slider, year, week)

If the slider selects a new timestep, this callback displays the weekday, date and time of the step in the grid result section.

Parameters:

slider – [Input] Timestep slider value
year – [State] Year from settings
week – [State] Week of the year from settings

Returns:

alert_time > children

grid_callbacks.update_grid_graph(data, day, tab_value, figure)

Updates the grid result graph and defines the x axis range.

Parameters:

data – [Input] Power calculation results
day – [Input] Selected day in the pagination
tab_value – [State] Tab value of main tab, whether grid, house or settings mode is shown
figure – [State] Figure of grid result graph

Returns:

graph_grid > figure

Returns:

graph_modal > figure

Returns:

modal_graph > opened

grid_callbacks.update_labels(slider, flow, figure)

If flow was calculated and the slider set to a new timestep, this function generates the cytoscape edge labels for this timestep from the flow results. It rounds them and get the power, which is taken or given to the external grid. This is then shown on the alert components in the grid result section.

Parameters:

slider – [Input] Timestep set by slider
flow – [State] The calculated flow data
figure – [State] Figure of grid result graph

Returns:

alert_externalgrid > children

Returns:

store_edge_labels > data

Returns:

graph_grid > figure

Returns:

store_notification > data

House Callbacks 

Warning

This documentation is not automatically generated by changing the docstrings in the code. See the note on thop of the page for more information.

house_callbacks.py contains all dash callbacks for house functions of the app.

house_callbacks.add_additional_device_check(btn, radio_device, radio_room)

Callback to check whether a device and room was selected wenn the “add” button is clicked. If not, return corresponding notifications. It also closes the modal after.

Parameters:

btn – [Input] Button to add an additional device
radio_device – [State] Selected device type
radio_room – [State] Selected room

Returns:

modal_additional_devices > opened

house_callbacks.add_new_device(btn_add, filename, input_name, input_menu_type, input_icon, own_device_dict, upload_content)

Callback to add a new custom device to the app. The user has to input the name, type, icon and a file, which contains the power profiles in Watts. There are two possibilities for this file:

CSV-File: First column are timestamps. Every following column is read as a separate power profile
XLS-File: First column are timestamps. Every following column is read as a separate power profile.

Also, the file can contain several sheets, which will be read separately. This can be useful if the user wants to add several power profiles which don’t share the same timestamps. In general the profiles can contain several values per minute, they are resampled to 1-min-steps. A device dict is created and added to the own-devices-dictionary.

Parameters:

btn_add – [Input] Button to add new device
filename – [Input] Filename of uploaded file
input_name – [State] Name of new device
input_menu_type – [State] Type of new device (preset or custom)
input_icon – [State] Icon of new device (Iconify)
own_device_dict – [State] Dictionary containing all own devices
upload_content – [State] Content of uploaded file

Returns:

store_own_devices_dict > data

Returns:

text_filename_load_new > children

Returns:

store_notification > data

house_callbacks.cost_result(data, cost_kwh, device_dict)

Calculates the yearly energy costs for each device, fetches the dash components and displays them in the cost tab.

Parameters:

data – [Input] Energy result data of house calculation
cost_kwh – [State] Cost of 1 kWh of electrical energy, from settings
device_dict – [State] Dictionary containing all devices in the custom house

Returns:

cost_tab > children

Returns:

store_notification > data

house_callbacks.fill_additional_device_modal(modal_open, radio_room)

Load all devices from sql database and show them as additional devices in the additional devices modal.

Parameters:

modal_open – [Input] The opening of the modal_additional_devices triggers this callback
radio_room – [State] Selected room by radiogroup

Returns:

card_additional_devices > children

house_callbacks.initial_room_configuration(interval, backup, cyto_bathroom, cyto_livingroom, cyto_kitchen, cyto_office, device_dict)

This callback is executed only on the first load of the app when no backup exists. It creates the basic components in each room of the custom house: A socket with a lamp.

Parameters:

interval – [Input] Interval which triggers this callback on refresh
backup – [State] Backup store component to check whether there is a backup
cyto_bathroom – [State] Cytoscape of the bathroom
cyto_livingroom – [State] Cytoscape of the livingroom
cyto_kitchen – [State] Cytoscape of the kitchen
cyto_office – [State] Cytoscape of the office
device_dict – [State] Dictionary containing all devices in the custom house

Returns:

cyto_bathroom > data

Returns:

cyto_livingroom > data

Returns:

cyto_kitchen > data

Returns:

cyto_office > data

Returns:

store_device_dict > data

house_callbacks.load_own_devices(btn_load, tab, filename, upload_content, own_device_dict)

Callback to upload own devices, show them or to show already uploaded ones.

Parameters:

btn_load – [Input] Button to load the own devices from file
tab – [Input] Tab value of additional devices modal
filename – [Input] Filename of uploaded file
upload_content – [State] Content of uploaded file
own_device_dict – [State] Dictionary to store the own devices

Returns:

store_own_device_dict > data

Returns:

text_filename_load_own > children

Returns:

card_own_devices_add > children

Returns:

card_own_devices_load > style

Returns:

store_notification > data

house_callbacks.show_legend(checkbox, figure)

Controls the visibility of the legend of the graph_power_house figure.

Parameters:

checkbox – [Input] Input if legend should be visible
figure – [State] Figure which the legend belongs to

Returns:

Boolean if the legend should be visible

Return type:

bool

house_callbacks.start_calculation_house(btn, device_dict, tabs_main, gridObject_dict, house)

Start the calculation of the powers and energys in the rooms of the house.

Parameters:

btn – [Input] Button to start calculation
device_dict – [State] Dictionary containing all devices in the custom house
tabs_main – [State] Tab value of main tab, whether grid, house or settings mode is shown
gridObject_dict – [State] Dictionary containing all grid objects and their properties
house – [State] Id of custom house

Returns:

store_results_house_power > data

Returns:

store_results_house_energy > data

Returns:

graph_power_house > figure

Returns:

graph_sunburst_house > figure

Returns:

result_parent_tabs > value

Returns:

tabs_menu > value

Returns:

store_grid_object_dict > data

Returns:

store_notification > data

house_callbacks.update_figure_devices(day, figure)

Update the values of the result graphs if another day is chosen to be shown. Also opens the modal with the full screen graph if the total timeframe is selected.

Parameters:

day – [Input] Selected day of the pagination below a figure
figure – [State] Figure to update

Returns:

graph_power_house > figure

Returns:

graph_modal > figure

Returns:

modal_graph > opened

house_callbacks.update_figure_house(data, day_control, selected_element, figure, day)

Update the values of the device graph if another day is chosen to be shown or the device dict is changed.

Parameters:

data – [Input] Dictionary containing all house devices and their properties
day_control – [Input] Day from pagination below device power profile
selected_element – [State] Cytoscape element which was clicked in the house
figure – [State] Figure of graph which shows power profile of device
day – [State] Day from pagination below device power profile

Returns:

graph_device > figure

house_callbacks.update_new_icon(icon)

Returns a dash iconify icon as the icon of the text input, if the content of the input was changed to another icon name.

Parameters:: icon – [Input] Text input with icon name
Returns:: input_new_icon > icon

Room Callbacks 

Warning

This documentation is not automatically generated by changing the docstrings in the code. See the note on thop of the page for more information.

room_callbacks.py creates all dash callbacks for room functions of the app.

room_callbacks.manage_devices_room(elements, device_dict, tabs_main, selected_element, radio_room, radio_devices, own_device_dict, node, btn_delete, btn_close, active_switch, btn_additional, btn_own)

Manages all functions of a device in a room. If a node of the cytoscape was clicked, it either opens the corresponding menu tab or the add device menu. It updates and synchronizes the active state of a device with the socket state and the slider in the menu. It adds devices to the room and deletes them with their socket and connection.

Parameters:

elements – [State] Elements of the room cytoscape
device_dict – [State] Dictionary containing all devices in the custom house
tabs_main – [State] Tab value of main tab, whether grid, house or settings mode is shown
selected_element – [State] Cytoscape element which was clicked in the house
radio_room – [State] Selected room by radiogroup
radio_devices – [State] Selected device by radiogroup
own_device_dict – [State] Dictionary to store the own devices
node – [Input] Node that was clicked in a room cytoscape
btn_delete – [Input] Button to delete device
btn_close – [Input] Button to close the menu in a room
active_switch – [Input] Slider to activate or deactivate a device
btn_additional – [Input] Button to add an additional devices modal
btn_own – [Input] Button to add an own device
btn_add – [Inputs] Button to add a device from a room menu

Returns:

cyto{room} > elements

Returns:

store_device_dict > data

Returns:

menu_devices{room} > style

Returns:

menu_devices{room} > opened

Returns:

store_menu_change_tab_house > data

Returns:

store_selected_element_house > data

Returns:

active_switch_house > checked,

Returns:

store_notification > data

room_callbacks.menu_show(btn_additional)

Opens the additional devices modal, closes the room menu and passes the room as a preset to the room radio

Parameters:: btn_additional – [Input] Button to open the additional device menu
Returns:: menu_devices_{room} > opened
Returns:: modal_additional_devices > opened
Returns:: radiogroup_room > value

room_callbacks.room_callbacks(app, button_dict, rooms)

Functions creates room callbacks for the rooms of the house. For each room, the same callbacks with different Inputs and outputs are created. It is important that the room name has to match the room identifying string in the dash component ids (for example cyto_{room} creates cyto_bathroom, cyto_kitchen and so forth).

Parameters:

app (Dash App) – Dash Application to add callbacks to
button_dict (dict) – Dictionary with buttons to create grid objects
rooms (list[str]) – Names of rooms in the house

Returns:

Nothing

Dash Callbacks

General Callbacks

Grid Callbacks

House Callbacks

Room Callbacks

Dash Callbacks 

General Callbacks 

Grid Callbacks 

House Callbacks 

Room Callbacks 