Traces

Bellow you can find the documentation of traces-drawing functions.

Lines

smartreport.v3.plot.traces.line.draw_trend_line(figure, data, **kwargs)

Draws a trend line on a provided figure.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the timeline traces.	required
data	Series	Series or Trend with data to draw.	required

Other Parameters:

Name	Type	Description
name	str	Name of the trace. Default: <data.name>
unit	str	Name of the trace. Default: <data.unit>
asset_name	str	Asset name of the trace. Default: <data.asset_name>
color	str	Color of the area. Default: ABBCommonUXColors.BLUE_60
alpha	str	Opacity of the area. Default: 1.0
mode	str	Display mode. ["markers", "lines"] connected with "+". Default: lines
showlegend	bool	If True, the legend values are shown. Otherwise, they are hidden. Default: False
row	int	When working with subplot, it's a row of the figure where this should be drawn on.
col	int	When working with subplot, it's a column of the figure where this should be drawn on.
legend_mode	str	name displays name in legend, asset_name displays asset_name in legend, all displays all. Default: name
marker_size	int	Size of the marker when displaying markers. Default 5
line_width	int	Line width. Default: 4
use_scattergl	bool	If True, ScatterGL plotting function will be used instead of standard Scatter. Use when you have big numer of points to plot (> 10_000). Default: False

Returns:

Type	Description
Figure	Updated figure

smartreport.v3.plot.traces.line.draw_min_max_area(figure, data_min, data_max, **kwargs)

Draws a min-max area on a provided figure. This area spans between data_min values, and data_max values.

If there are nan's in the input data the area is divided into continuous subareas, which are plotted separately.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the timeline traces.	required
data_min	Series	Series or Trend with data to draw. It should be a sequence values that defines the lower boundary of area.	required
data_max	Series	Series or Trend with data to draw. It should be a sequence values that defines the upper boundary of area.	required

Other Parameters:

Name	Type	Description
name	str	Name of the trace. Default: <data_min.name>
color	str	Color of the area. Default: ABBCommonUXColors.BLUE_60
alpha	str	Opacity of the area. Default: 0.5
mode	str	Display mode. ["markers", "lines"] connected with "+". Default: lines
showlegend	bool	If True, the legend values are shown. Otherwise, they are hidden. Default: False
row	int	When working with subplot, it's a row of the figure where this should be drawn on.
col	int	When working with subplot, it's a column of the figure where this should be drawn on.

Returns:

Type	Description
Figure	Updated figure

smartreport.v3.plot.traces.line.draw_vertical_lines(figure, vertical_lines_groups, x, y, **kwargs)

Draws vertical lines on a provided figure. The vertical lines have to be provided as a sequence of the SpectrumPointsGroup objects.

Each SpectrumPointsGroup object contains a list of values and a list of labels. The values are the x-coordinates of the vertical lines, and the labels are the text that will be displayed above the vertical lines.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the vertical lines.	required
vertical_lines_groups	Sequence[SpectrumPointsGroup]	List of SpectrumPointsGroup objects containing the vertical lines data.	required
x	ndarray	X-axis data for the plot. Used to determine the x-coordinates of the vertical lines.	required
y	ndarray	Y-axis data for the plot. Used to determine the y-coordinates of the vertical lines.	required

Other Parameters:

Name	Type	Description
use_logscale	bool	If True, the y-axis considered to be in log scale. Default: False
initial_y_position	float	Initial relative y position for the vertical lines text. Default: 1.03
initial_opacity	float	Initial opacity for the vertical lines text. Default: 1.0
y_position_delta	float	Delta for the relative y position of the vertical lines text. Default: 0.05
opacity_delta	float	Delta for the opacity of the vertical lines text. Default: 0.2
hover_precision	str	Precision for the hover text. Default: 3g

Returns:

Type	Description
Figure	Figure with added vertical lines.

Thresholds

smartreport.v3.plot.traces.threshold.draw_threshold(figure, threshold, **kwargs)

Draws threshold areas (yellow and/or red rectangles) on the provided figure.

Threshold can be displayed in two basic ways:

• horizontally (default) - vast majority of the cases, threshold spawns on (almost) all X axis and Y values are taken from Threshold object.
• vertically - Threshold rectangle spawns on all Y axis and X values are taken from the Threshold object.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the timeline traces.	required
threshold	Threshold	Threshold object that defines the threshold values.	required

Other Parameters:

Name	Type	Description
horizontal	bool	If True, the threshold is drawn in horizontal orientation. Otherwise, it's in vertical orientation. Default: True
opacity	float	Threshold rectangle opacity in scale from 0 to 1. Default 0.3
unit	str	Threshold unit. Default ``
showtype	bool	If True, then the High or Low prefix is added to the label, based on the inverted value. Default: False
showlegend	bool	If True, the legend values are shown. Otherwise, they are hidden. Default: False
row	int	When working with subplot, it's a row of the figure where this should be drawn on.
col	int	When working with subplot, it's a column of the figure where this should be drawn on.
legend_labels	dict	Dictionary with custom labels for the threshold areas. The keys are alarm, warning, and range.

Returns:

Type	Description
Figure	Updated figure

Notes

Inverted thresholds are supported only for horizontal thresholds. Threshold, by default, is displayed on the legend with proper label.

Timelines

smartreport.v3.plot.traces.timeline.draw_timeline(figure, data, **kwargs)

Draws timeline on a provided figure. It's based on the draw_timelines function, but it's optimized for single series.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the timeline traces.	required
data	Series	Series or Trend with data to draw. Should have DateTimeIndex.	required

Keyword Args are the same as for draw_timelines function.

Returns:

Type	Description
Figure	Updated figure

smartreport.v3.plot.traces.timeline.draw_timelines(figure, data, **kwargs)

Draws timelines on a provided figure. Timeline is a sequence of horizontal bars that spans over the datetime X axis.

The number of bars is reduced to minimum, so it works well with long inputs, as long as the value doesn't change very often.

We convert input data frame of states into a DataFrame with state ranges. Then the Plotly Express Timeline function is used to create a new figure, from which we copy the traces to the original figure.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the timeline traces.	required
data	DataFrame	DataFrame with data to draw. Each column should be a sequence of states with DateTimeIndex.	required

Other Parameters:

Name	Type	Description
color_mapping	Dict	Dictionary that maps the values in the data series into colors. If not provided, then default plotly colors are used.
label_mapping	Dict	Dictionary that maps the values in the data series into label names. If not provided, then data values are used.
columns_to_use	List	List of columns to use from the data DataFrame. If not provided, then all columns are used.
showlegend	bool	If True, the legend values are shown. Otherwise, they are hidden. Default: False
row	int	When working with subplot, it's a row of the figure where this should be drawn on.
col	int	When working with subplot, it's a column of the figure where this should be drawn on.
auto_layout_update	bool	If True, then the layout of the figure is automatically adjusted to the needs of timeline plot. Check the Notes for more details. Default: False
add_missing_colors_to_legend	bool	If True, then the colors that are not present in the legend are added to the legend. Default: True
join_on_ends	bool	If True, then the index of the input data indicates the end of the state. If False, then the index indicates the start of the state. Default: False

Returns:

Type	Description
Figure	Updated figure

Notes

Since this function don't update the figure layout by default, in order to make the timeline look nice, you need to update the barmode='overlay' in general layout and type='date' in X-Axis layout.

If you are OK with updating it here, use auto_layout_update=True

Scatters

smartreport.v3.plot.traces.scatter.draw_scatter_points(figure, data, **kwargs)

Draws scatter points on a provided figure.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the timeline traces.	required
data	DataFrame	Data frame data to draw.	required

Other Parameters:

Name	Type	Description
x_key	str	Key of the X values in the provided data frame. Default: x
y_key	str	Key of the Y values in the provided data frame. Default: y
x_title	str	Title of the X axis. Default: ``
y_title	str	Title of the Y axis. Default: ``
x_unit	str	Unit of the X values. Default: ``
y_unit	str	Unit of the Y values. Default: ``
color_key	str	Key of the Color values in the provided data frame. If not provided then the color is used for all points on the scatter plot. Default: None
label_key	str	Key of the Label values in the provided data frame. If not provided then the name is used for all points on the scatter plot. Default: None
color	str	Color to be used with all scatter point when color_key is not provided or not present in the data frame. Default: <ABB Colors20.C01>
name	str	Name of the scatter points. Default ``
marker_size	int	Size of the scatter points. Default 4
alpha	str	Opacity of the scatter points. Default: 1.0
showlegend	bool	If True, the legend values are shown. Otherwise, they are hidden. Default: True
row	int	When working with subplot, it's a row of the figure where this should be drawn on.
col	int	When working with subplot, it's a column of the figure where this should be drawn on.
show_threshold	bool	If True, the threshold values are shown. Otherwise, they are hidden. Default: True
threshold	Threshold	Threshold of the scatter points. Default: Threshold(None, None)

Returns:

Type	Description
Figure	Updated figure

smartreport.v3.plot.traces.scatter.draw_polygon(figure, polygon, **kwargs)

Draws Polygon object on a provided figure.

Parameters:

Name	Type	Description	Default
figure	Figure	Figure on which we draw the timeline traces.	required
polygon	Polygon	Polygon to be drawn.	required

Other Parameters:

Name	Type	Description
color	str	Color of the polygon: <ABB Colors20.C01>
name	str	Name of the polygon trace. Default ``
alpha	str	Opacity of the scatter points. Default: 1.0
line_width	int	Line width. Default: 4
showlegend	bool	If True, the legend values are shown. Otherwise, they are hidden. Default: True
row	int	When working with subplot, it's a row of the figure where this should be drawn on.
col	int	When working with subplot, it's a column of the figure where this should be drawn on.

Returns:

Type	Description
Figure	Updated figure