visiannot.tools.pyqtgraph_overlayer¶

Summary¶

Module with functions for scientific graphics with pyqtgraph

See https://pyqtgraph.readthedocs.io/en/latest

Functions¶

`visiannot.tools.pyqtgraph_overlayer.add_legend_to_widget`(…)	Adds a legend to a 2D widget
`visiannot.tools.pyqtgraph_overlayer.add_mean_std_plot_to_widget`(…)	Adds a plot item to a 2D widget, a vertical line is associated to each point of the plot item, particularly useful to display a mean/median curve with the standard deviation
`visiannot.tools.pyqtgraph_overlayer.add_plot_to_widget`(…)	Adds a plot item to a 2D widget
`visiannot.tools.pyqtgraph_overlayer.add_region_to_widget`(…)	Creates a region item (pyqtgraph.LinearRegionItem) and displays it in a widget
`visiannot.tools.pyqtgraph_overlayer.add_text_item_to_widget`(…)	Adds a text item to a 2D widget, possibly along with an arrow
`visiannot.tools.pyqtgraph_overlayer.basic_image_plot`(im, …)	Creates a window with an image
`visiannot.tools.pyqtgraph_overlayer.basic_plot`(data)	Creates a window with a 2D plot
`visiannot.tools.pyqtgraph_overlayer.create_widget`(…)	Creates a 2D widget and adds it to a grid layout
`visiannot.tools.pyqtgraph_overlayer.create_widget_color_bar`(…)	Creates a widget with a color bar (useful for the legend of a heat map)
`visiannot.tools.pyqtgraph_overlayer.create_widget_image`(…)	Creates a widget containing an image and adds it to a grid layout
`visiannot.tools.pyqtgraph_overlayer.create_widget_logo`(…)	Creates a widget with no mouse interaction containing an image and adds it to a grid layout
`visiannot.tools.pyqtgraph_overlayer.initialize_gui_and_bg_color`([color])	Creates a Qt application for display and sets background color of the pyqtgraph widgets
`visiannot.tools.pyqtgraph_overlayer.remove_item_in_widgets`(…)	Removes an item from a list of widgets
`visiannot.tools.pyqtgraph_overlayer.set_background_color`([color])	Sets background color of pyqtgraph widgets (independent of PyQt5 widgets)
`visiannot.tools.pyqtgraph_overlayer.set_color_map`(…)	Creates a color map
`visiannot.tools.pyqtgraph_overlayer.set_temporal_ticks`(…)	Sets the ticks of the X axis of a widget in datetime format and the X axis range according to a temporal range
`visiannot.tools.pyqtgraph_overlayer.set_ticks_text_style`(…)	Sets ticks text style of an axis item

API¶

Functions¶

visiannot.tools.pyqtgraph_overlayer.add_legend_to_widget(widget, item_dict, position='inside', legend_wid_size=(0, 0), **kwargs)[source]¶

Adds a legend to a 2D widget

If specified, this function creates a widget dedicated to the legend, instead of having a legend item inside the 2D widget.

Parameters

widget (pyqtgraph.PlotWidget) – widget containing the plot items to legend
item_dict (dict) – plot items to legend, key is the plot item and value is the associated legend text
position (str) –
legend mode
- "inside": legend item inside the widget
- "right": legend item is in a new widget created at the right side of the widget
- "bottom": legend is in a new widget created at the bottom side of the 2D widget
legend_wid_size (tuple) – size of the created legend widget, length 2 (width, height) in case position is "right" or "bottom"
kwargs – keyword arguments of pyqtgraph.LegendItem constructor, see https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/legenditem.html

Returns

legend (-pyqtgraph.LegendItem) – legend item
legend_widget (pyqtgraph.PlotWidget) – widget containing the legend item if it has been created (otherwise None)

visiannot.tools.pyqtgraph_overlayer.add_mean_std_plot_to_widget(wid, data_mean, data_std, data_X=None, pen_std_style={'color': 'k'}, n_population_list=[], **kwargs)[source]¶

Adds a plot item to a 2D widget, a vertical line is associated to each point of the plot item, particularly useful to display a mean/median curve with the standard deviation

The method raises an exception if data_mean and data_std or data_mean and data_X do not have the same length.

Parameters

wid (pyqtgraph.PlotWidget) – widget where to add the plot items
data_mean (numpy array) – mean/median values (1D array)
data_std (numpy array) – standard deviation values (1D array), same length as data_mean
data_X (numpy array) – coordinates of the mean/std values on the X axis (1D array), must have the same length as data_mean
pen_std_style (dict) – style of the standard deviation plot item
n_population_list (list) – number of samples at each point (same length than data_mean), a text item is then added near each point
kwargs – keyword arguments of the function add_plot_to_widget(), used for the plot item of the mean/median values

Returns

mean_plot (pyqtgraph.PlotDataItem) – plot item of the mean/median values
std_plot (pyqtgraph.PlotDataItem) – plot item of the standard deviation values
text_item_list (list) – text items (pyqtgraph.TextItem) of the number of samples at each point, empty list if n_population_list is empty

visiannot.tools.pyqtgraph_overlayer.add_plot_to_widget(widget, data, flag_clear=False, flag_nan_void=True, plot_style={'pen': {'color': 'b', 'width': 1}})[source]¶

Adds a plot item to a 2D widget

For details about plot style, see https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/plotdataitem.html

For details about color, see https://pyqtgraph.readthedocs.io/en/latest/functions.html#color-pen-and-brush-functions

Parameters

widget (pyqtgraph.PlotWidget) – widget where the plot must be displayed
data (numpy array) –
data to plot, two possibilites:
- shape $(n, 2)$ , first column contains X values, second column contains Y values, if only one point to plot make sure to have shape $(1, 2)$
- shape $(n,)$ , only Y values, then X values are the array indexes
flag_clear (bool) – specify if content currently displayed must be cleared before plotting the data
flag_nan_void (bool) – specify if NaN values must be handled by pyqtgraph.PlotDataItem by setting the keyword argument connect to "finite", see https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/plotdataitem.html#pyqtgraph.PlotDataItem.__init__
plot_style (dict) – plot style, keys are keyword arguments of the constructor of pyqtgraph.PlotDataItem, see link above

Returns

plot item (or a list of pyqtgraph.PlotDataItem in case nan_void is true)

Return type

pyqtgraph.PlotDataItem

visiannot.tools.pyqtgraph_overlayer.add_region_to_widget(bound_1, bound_2, wid, color)[source]¶

Creates a region item (pyqtgraph.LinearRegionItem) and displays it in a widget

Parameters

bound_1 (int) – start value of the region item (expressed as a coordinate in the X axis of the widget)
bound_2 (int) – end value of the region item (expressed as a coordinate in the X axis of the widget)
wid (pyqtgraph.PlotWidget) – widget where to display the region item, might be any widget class with a method addItem
color (tuple or list) – plot color (RGBA)

Returns

region item displayed in the widget

Return type

pyqtgraph.LinearRegionItem

visiannot.tools.pyqtgraph_overlayer.add_text_item_to_widget(widget, pos, flag_arrow=False, text_alignement=None, opts_text_dict={'anchor': (0.5, 0.5), 'color': 'k'}, opts_arrow_dict={'brush': '#000000', 'headLen': 15, 'pen': '#000000', 'tipAngle': 20})[source]¶

Adds a text item to a 2D widget, possibly along with an arrow

For details about color, see https://pyqtgraph.readthedocs.io/en/latest/functions.html#color-pen-and-brush-functions

Parameters

widget (pyqtgraph.PlotWidget) – widget where the text item must be displayed
pos (tuple) – position of the text item in the widget, length 2 (x, y)
flag_arrow (bool) – specify if an arrow must be added
text_alignement – flag for specifying text alignement, particularly useful in case of multi-line text, see https://doc.qt.io/qt-5/qt.html#AlignmentFlag-enum for the possible values, for example: Qt.AlignCenter, imported as from PyQt5.QtCore import Qt
opts_text_dict (dict) – keyword arguments of the constructor of pyqtgraph.TextItem, see https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/textitem.html#pyqtgraph.TextItem
opts_arrow_dict (dict) – keyword arguments of the constructor of pyqtgraph.ArrowItem, see https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/arrowitem.html#pyqtgraph.ArrowItem

Regarding anchor argument in TextItem, (0, 0) => top left, (1, 0) => top right, (1, 0) => bottom left, (1, 1) => bottom right.

Regarding opts_arrow_dict, the position of the arrow item is specified by the keyword argument pos.

Returns

text_item (pyqtgraph.TextItem)
arrow_item (pyqtgraph.ArrowItem) – may be None if arrow not specified

visiannot.tools.pyqtgraph_overlayer.basic_image_plot(im, **kwargs)[source]¶

Creates a window with an image

Parameters

im (numpy array) – RGB image array of shape $(width, height, 3)$
kwargs – keyword arguments of the function create_window(), if background color of the window is specified, then it is also applied to the image widget

Returns

win (QWidgets.QWidget) – window container
lay (QWidgets.QGridLayout) – layout
widget (pyqtgraph.PlotWidget) – 2D widget filling the whole layout
img (pyqtgraph.ImageItem) – image item

visiannot.tools.pyqtgraph_overlayer.basic_plot(data, opts_win_dict={}, opts_wid_dict={}, **kwargs)[source]¶

Creates a window with a 2D plot

For details about plot style, see https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/plotdataitem.html

For details about color, see https://pyqtgraph.readthedocs.io/en/latest/functions.html#color-pen-and-brush-functions

Parameters

data (numpy array) –
data to plot, two possibilites:
- shape $(n, 2)$ , first column contains X values, second column contains Y values, if only one point to plot make sure to have shape $(1, 2)$
- shape $(n,)$ , only Y values, then X values are the array indexes
opts_win_dict (dict) – keyword arguments of the function create_window()
opts_wid_dict (dict) – keyword arguments of the function create_widget()
kwargs – keyword arguments of add_plot_to_widget()

Returns

win (QWidgets.QWidget) – window container
lay (QWidgets.QGridLayout) – layout
widget (pyqtgraph.PlotWidget) – 2D widget filling the whole layout
plot (pyqtgraph.PlotDataItem) – plot item

visiannot.tools.pyqtgraph_overlayer.create_widget(lay, widget_position, widget_size=(0, 0), widget_title=None, title_style={'color': '#0000', 'size': '9pt'}, x_range=[], y_range=[], axes_label_dict={'bottom': None, 'left': None}, flag_invert_x=False, flag_invert_y=False, flag_aspect_locked=False, flag_plot_menu=True)[source]¶

Creates a 2D widget and adds it to a grid layout

The widget content is empty.

Parameters

lay (QtWidgets.QGridLayout) – parent layout where the widget is added
widget_position (tuple) – position of the widget in the parent layout, length 2 (row, col) or 4 (row, col, rowspan, colspan)
widget_size (tuple) – maximum size of the widget, length 2 (width, height), set a value to 0 in order to have an automatic sizing in the corresponding axis
widget_title (str) – widget title, basic HTML allowed
title_style (dict) – title style
x_range (tuple) – range values on the X axis, length 2 (x_min, x_max)
y_range (tuple) – range values on the Y axis, length 2 (y_min, y_max)
axes_label_dict (dict) –
axes to show and their respective label
- Key is the axis identifier ("left", "right", "bottom" or "top")
- Value is the associated label as a list of length 2:
  - axis label (str)
  - label style (dict), e.g. {'color': '#000', 'font-size': '10pt'}
- In case no label is associated to the axis, set the corresponding value to None
flag_invert_x (bool) – specify if the X axis must be inverted
flag_invert_y (bool) – specify if the Y axis must be inverted
flag_aspect_locked (bool) – specify if the aspect ratio must be locked
flag_plot_menu (bool) – specify if the plot menu is enabled

Returns

widget

Return type

pyqtgraph.PlotWidget

visiannot.tools.pyqtgraph_overlayer.create_widget_color_bar(lay, widget_position, color_map, lut, ticks_values, widget_width=80, ticks_val_formatting='%s', img_width=5)[source]¶

Creates a widget with a color bar (useful for the legend of a heat map)

Parameters

lay (QtWidgets.QGridLayout) – parent layout where the widget is added
widget_position (tuple) – position of the widget in the parent layout, length 2 (row, col) or 4 (row, col, rowspan, colspan)
color_map (pyqtgraph.ColorMap) – color map to define the color bar
lut (numpy array) – look up table to define the color bar
ticks_values (list or tuple) – values of the ticks to display
widget_width (int) – width of the widget in pixels
ticks_val_formatting (str) – formatting pattern of the ticks text
img_width (int) – width of the color bar in pixels

Returns

wid_bar (pyqtgraph.PlotWidget) – widget containing the color bar
bar_img_item (pyqtgraph.ImageItem) – image item of the color bar

visiannot.tools.pyqtgraph_overlayer.create_widget_image(lay, widget_position, im=None, title=None, title_style={'color': '#000', 'size': '9pt'})[source]¶

Creates a widget containing an image and adds it to a grid layout

Parameters

lay (QtWidgets.QGridLayout) – parent layout where the widget is added
widget_position (tuple) – position of the widget in the parent layout, length 2 (row, col) or 4 (row, col, rowspan, colspan)
im (numpy array) – RGB image array of shape $(width, height, 3)$
title (str) – widget title
title_style (dict) – widget title style

Returns

widget (pyqtgraph.PlotWidget) – image container
img (pyqtgraph.ImageItem) – image item

visiannot.tools.pyqtgraph_overlayer.create_widget_logo(lay, widget_position, im, box_size=None)[source]¶

Creates a widget with no mouse interaction containing an image and adds it to a grid layout

Parameters

lay (QtWidgets.QGridLayout instance of QtWidgets.QGridLayout where the widget is added) – parent layout where the widget is added
widget_position (tuple) – position of the widget in the parent layout, length 2 (row, col) or 4 (row, col, rowspan, colspan)
im (numpy array) – RGB image array of shape $(width, height, 3)$
box_size (int or tuple) – size of the image, either an integer if same value for width and height, or a tuple of length 2 (width, height)

Returns

widget containing the image

Return type

pyqtgraph.PlotWidget

visiannot.tools.pyqtgraph_overlayer.initialize_gui_and_bg_color(color=(255, 255, 255))[source]¶

Creates a Qt application for display and sets background color of the pyqtgraph widgets

It calls the functions initialize_gui() and set_background_color().

Parameters: color (str or tuple) – background color as a string or RGB (see https://pyqtgraph.readthedocs.io/en/latest/style.html for details)
Returns: instance of QtCore.QCoreApplication or QtWidgets.QApplication

visiannot.tools.pyqtgraph_overlayer.remove_item_in_widgets(wid_list, item_list)[source]¶

Removes an item from a list of widgets

Parameters

wid_list (list) – widgets where to remove an item, each element must have a method removeItem (for example an instance of pyqtgraph.PlotWidget)
item_list (list) – items to remove from widgets, same length as wid_list, each element corresponds to one element of wid_list

visiannot.tools.pyqtgraph_overlayer.set_background_color(color=(255, 255, 255))[source]¶

Sets background color of pyqtgraph widgets (independent of PyQt5 widgets)

Parameters: color (str or tuple) – background color as a string or RGB (see https://pyqtgraph.readthedocs.io/en/latest/style.html for details)

visiannot.tools.pyqtgraph_overlayer.set_color_map(values, colors, lut_dim=256)[source]¶

Creates a color map

See https://pyqtgraph.readthedocs.io/en/latest/colormap.html for details.

Parameters

values (list or tuple) – values spanning the color map, at least two values are required, it may be a 1D numpy array
colors (list or numpy array) – colors corresponding to the values, must be the same length as values, each element is a (RGB) color
lut_dim (int) – dimension of the look up table

Returns

color_map (pyqtgraph.ColorMap)
lut (numpy array) – color of the look up table, shape (lut_dim, 4)

visiannot.tools.pyqtgraph_overlayer.set_temporal_ticks(widget, nb_ticks, temporal_info, ref_datetime, **kwargs)[source]¶

Sets the ticks of the X axis of a widget in datetime format and the X axis range according to a temporal range

It creates temporal labels for ticks in the format specified by fmt. The first (resp. last) tick is defined by the first (resp. last) value of the temporal range, which might be expressed in milliseconds or in number of frames.

Parameters

widget – widget where to set X axis ticks and X axis range, it may be any sub-class of pyqtgraph.PlotWidget
nb_ticks (int) – number of ticks to display on the X axis
temporal_info (list) –
temporal range, there are two ways to specify it:
- (first_frame_ms, last_frame_ms), the temporal range is expressed in milliseconds,
- (first_frame, last_frame, freq), the temporal range is expressed in number of frames sampled at the frequency freq
ref_datetime (datetime.datetime) – reference datetime for temporal range (if the first value of the temporal range is 0, then the tick value is ref_datetime)
kwargs – keyword arguments of convert_datetime_to_string()

visiannot.tools.pyqtgraph_overlayer.set_ticks_text_style(axis_item, color='#000', size=9, **kwargs)[source]¶

Sets ticks text style of an axis item

See https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/axisitem.html for details.

Parameters

axis_item (pyqtgraph.AxisItem) – axis for which the style of ticks text must be set
color (str or tuple) – color of the text in HEX string or RGB format
size (float or int) – font size of the text in pt
kwargs – keyword arguments of setStyle() applied on axis_item, see https://pyqtgraph.readthedocs.io/en/latest/graphicsItems/axisitem.html#pyqtgraph.AxisItem.setStyle