Layouts
Bellow you can find the documentation of layout-defining classes.
Base Layout
smartreport.plot.layout.base.BaseLayout
dataclass
Base layout class with parameters (represented as class attributes) common to all types of charts used in reports. This class shall NOT be used directly by plotting functions, but rather should be extended by child classes by parameters that are more specific to a given type of chart.
Values of default parameters + look/behaviour of the plot components (title, axes, ticks etc.) were developed in collaboration with ABB UX Team and according to ABB visual guidelines.
Layout classes work closely with plot functions. Workflow is the following: 1. Plot function fills figure.data property by defining traces which will be displayed 2. Layout object, based on the traces in figure.data, fills figure.layout property (calculates axis ranges, tick placement etc).
In other words, the plot function defines WHAT data should be displayed (plot function defines the content of figure.data property); layout classes define HOW this data should be displayed (mostly by modifying figure.layout property). This border is sometimes weak (e.g. plot function to set axis title needs to modify figure.layout property; layout classes also modifies figure.data in some cases), but generally it accurately represents the overall idea.
Each defined plotting function shall accept instance of BaseLayout class. During the execution, layout shall be applied to plotly figure using .apply_to_figure(figure) method. Example:
plotting function definition, passing TrendPlotLayout (child of BaseLayout) as a parameter
def draw_trends(data, **kwargs) -> figure:
layout: VerticalPlotLayout = kwargs.get("layout", VerticalPlotLayout())
fig = go.Figure()
... # logic needed to correctly display the data using fig object
layout.apply_to_figure(fig) # at the end of the plotting function, layout is applied to figure object
# (at this point figure object should contain fully defined data property)
call to plotting function
draw_trends( data=..., layout=VerticalPlotLayout( plot_line_width_px=2, ... )
background_text = None
class-attribute
instance-attribute
Displays watermark-like background text
color_palette = field(default_factory=(lambda: ColorPalette.get_default()))
class-attribute
instance-attribute
Color palette which will be used in the plot. Color palette defines two basic color sets: - default color sequence -> sequence of the colors which will be used as default colors for traces - status colors -> colors which are associated with statuses ("good", "poor", etc.)
empty_plot
abstractmethod
property
Returns empty (no data) plot specific to this layout
font_family = '"ABBvoice", "Open Sans", "HelveticaNeue", "Helvetica Neue", Helvetica, Arial, sans-serif'
class-attribute
instance-attribute
Font color and family used for all text components of the plot
legend = None
class-attribute
instance-attribute
Type of the legend to draw on the plot. If set to none, legend will NOT be displayed.
margin = field(default_factory=(lambda: Margin()))
class-attribute
instance-attribute
Margin of the plot in [px] - adds requested amount of empty space by squeezing the plot
plot_theme = PlotTheme.Plotly.WHITE
class-attribute
instance-attribute
Theme used by this layout. Theme allows to set static properties of the plot (background colors, font sizing etc.); functionality-wise theme is similar to BaseLayout structure. It don't have an access to figure object however, so using theme, layout parameters cannot be set based on the passed data. That's why using BaseLayout object is preferred. More on themes in plotly: https://plotly.com/python/templates/
title_font_size_px = 21
class-attribute
instance-attribute
Size of the font used for title in px
apply_to_figure(figure)
Applies this layout to given figure by calling all setter functions defined for this object. Executes every layout method which name starts with "preset" "set" prefix (we are referring to those methods in docs as setter methods). Execution happens in 2 waves, first all methods with "preset" prefix are called and then methods with "set" prefix. This allows to control the order of execution.
Setter method shall mutate passed figure object and should have the following signature:
if setter uses class attributes (most cases)
def set...(self, figure: Figure) -> None: ...
if setter is NOT using class attributes
@staticmethod def set...(figure: Figure) -> None: ...
calculate_width_and_height()
Calculates actual plot width and height based on the relative parameters
update(**kwargs)
Updates this layout object by provided parameters. If None will be provided as a value, parameter will NOT be set (old value will be preserved).
update_by_plot_kwargs(plot_kwargs)
Updates layout by plot function kwargs. It is a convince method - often it is more intuitive to pass layout parameters directly to plot function than create layout object with proper parameters and pass it as a function parameter.
Vertical Plot Layout
smartreport.plot.layout.vertical.VerticalPlotLayout
dataclass
Bases: BaseLayout
Most common type of layout, which represents vertical plot: plot where x-axis is the main axis and y-axis is a data axis. If traces uses y2 axis, it will be also added and styled. Layout fully supports scatter and bar traces.
bar_groups_gap_pct = 0.5
class-attribute
instance-attribute
Defines the space between bars within same group (of the same location coordinate). Provided in [%], relative to the calculated range. This setting will be only taken into account if figure's bar_mode == group.
bar_width_pct = 2
class-attribute
instance-attribute
Controls width of the bars on the plot (if present); width is provided in [%], relative to calculated x range.
plot_line_width_px = 4
class-attribute
instance-attribute
Width (thickness, in px) of lines used to draw trends on the plot
show_y_grid_line = True
class-attribute
instance-attribute
Controls the visibility of grid lines. By default, X axis grid is OFF, and Y axis grid is ON.
x_range_offsets_pct = field(default_factory=(partial(Range, min=1.1, max=1.1)))
class-attribute
instance-attribute
Relative offsets for the x axis in [%] - represents how much empty space will be add before min value (left side of the plot; min(figure.data) * range.min * 0.01) and after max value (right side of the plot; max(figure.data) * range.max * 0.01) - can be used to move plot horizontally.
y2_fixed_range = None
class-attribute
instance-attribute
Parameters allows to force given range on axis - if provided, auto-calculation for axis will not be preformed
y_axis_allowed_ticks_nbr = field(default_factory=(partial(Range, min=5, max=12)))
class-attribute
instance-attribute
Parameters which allows to customize ticks setting behaviour for y axis - see associated parameter in YAxis class
y_fixed_ticks = None
class-attribute
instance-attribute
Provides the option to use predefined ticks (axis labels). If used, ticks won't be automatically calculated.
y_range_offsets_pct = field(default_factory=(partial(Range, min=15, max=15)))
class-attribute
instance-attribute
Same as above, but for y range; can be used to move vertically. By default, centers the traces on the plot.
y_title = ''
class-attribute
instance-attribute
Sets the title of the x and y axes. If not provided, then the title is not displayed.
Horizontal Plot Layout
smartreport.plot.layout.horizontal.HorizontalPlotLayout
dataclass
Bases: BaseLayout
Layout where y is the main axis and x is a data axis. Currently, supports only bar traces. Used in horizontal bar chart.
labels_alignment = HorizontalPosition.LEFT
class-attribute
instance-attribute
Alignment of the y axis labels - currently left and right alignments are supported
single_abstract_unit_width_px = 16
class-attribute
instance-attribute
Number of pixels which occupy single Y axis abstract unit
space_between_bars_width = 1
class-attribute
instance-attribute
Width of the bar with data in abstract y units. By default, bar will be 2x wider than the empty space between bars.
tick_labels_offset_px = 20
class-attribute
instance-attribute
Offset in [px] between labels and the plot (when right labels alignment is requested) and widest label and the plot (for left alignment)
x_axis_fixed_range = None
class-attribute
instance-attribute
Option to force given range on x axis - range calculation process will be skipped in this case (tick labels will be still auto-calculated).
Donut Plot Layout
smartreport.plot.layout.donut.DonutPlotLayout
dataclass
Bases: BaseLayout
clockwise_direction = True
class-attribute
instance-attribute
Direction in which donut will display data
figure_size = (8, 3.5)
class-attribute
instance-attribute
Specific figure size for donut plot
inside_hole_pct = 75
class-attribute
instance-attribute
Inside (empty) hole radius in [%] with respect to donut radius
margin = field(default_factory=(partial(Margin, top=20, bottom=20, left=5, right=5)))
class-attribute
instance-attribute
Margin of the plot represented by Margin class
Timeline Plot
smartreport.plot.layout.timeline.TimelinePlotLayout
dataclass
Bases: BaseLayout
Layout to display long term trends. It is used with overlayed bar chart that shows changes of state in time.
allowed_chars_y_label = None
class-attribute
instance-attribute
Number of allowed characters displayed in the y labels.
bar_gap = 0.0
class-attribute
instance-attribute
Specified gap between displayed bars. It should be within range of [0, 1).
grid_color = ABBCommonUXColors.GREY_20.value
class-attribute
instance-attribute
Specify color of the grid vertical lines connected to x-axis ticks.
legend = field(default_factory=HorizontalLegend)
class-attribute
instance-attribute
Specify legend type and way of displaying labels. By default horizontal legend is used.
margin = Margin(top=100, bottom=140, left=300, right=80)
class-attribute
instance-attribute
Margin of the plot in [px] - adds requested amount of empty space by squeezing the plot
show_first_line = True
class-attribute
instance-attribute
Parameter setting visibility of the first thick line along one of the axes.
show_tick_labels = True
class-attribute
instance-attribute
Parameter setting visibility of the tick labels along one of the axes.
width = 1440.0
class-attribute
instance-attribute
Width of the graph in [px].
x_axis_fixed_range = None
class-attribute
instance-attribute
Specify the range x axis pre-defined range.
y_axis_auto_range = 'reversed'
class-attribute
instance-attribute
Used to display timelines in reversed order. It is not recommended to be changed.
y_labels_font_size = 16
class-attribute
instance-attribute
Font size of the labels displayed along y-axis.
Trend with Timeline Plot
smartreport.plot.layout.trend_with_timeline.TrendWithTimelinePlotLayout
dataclass
Bases: BaseLayout
Layout for two subplots displayed together: Main trend plot on top, and the second plot with Timeline beneath.
Top plot is similar to VerticalLayout where x-axis is the main axis and y-axis is a data axis. Bottom plot represents the timeline and is used to indicate the change of discrete state.
Both plots shares x-axis, which is a date time axis.