Visual sets

1. What is a visual set

The data drawn on charts is passed to them using VisualSets. A VisualSet is an object that knows how to extract the data from some source and how to present it on a specific chart. Note that visual sets do not store the data. Visual sets provide the information about colors, number formats, line widths of plots, etc.

The example below shows how to create a simple VisualSet for a line plot on a LineChart. In this example, our data is the information about sales for the first 3 days of simulation. On day #0 we have sold 1 unit, on day #1 — 3 units, and on day #2 — 2 units. This data is stored in a form of List of pairs of Double values.

List<Pair<Double, Double>> data = List.of(new Pair<>(0.0, 1.0), new Pair<>(1.0, 3.0), new Pair<>(2.0, 2.0));
var visualSet = VisualSets.line("Daily sales", data);

This example shows how to create a VisualSet that would display static data, but the most common case is displaying the dynamically changing data that come from simulation model (or any other dynamic source). This can be easily implemented if we replace the static list that we pass to VisualSets.line() method with a Supplier of such list:

visualSet = VisualSets.line("Daily sales", () -> data);

The examples above create visual sets that show the line plot with default line width (1 px) and default line color (black). Specifying the appearance details of the plot can look like this:

visualSet.setLineColor(Color.red)
		.setLineWidth(2)
		.setLineStyle(LineStyle.DASHED);

If we add this visual set to a LineChart by calling lineChart.getVisualSetContainer().addVisualSet(), we will see the following plot:

Simple Chart

So, visual set is a means of decoupling data from its presentation on various types of Amalgama platform’s charts.

2. Types of visual sets

Visual sets can be of different types depending on charts they can be displayed on, and types of data rows on these charts. The most commonly used types of visual sets are shown in the table below:

Table 1. Most common types of visual sets
VisualSet class Description Key appearance parameters

LineVisualSet

Line plot for showing time series data or dependency of some value on some argument

Line color, line width, line style, interpolation type

PolylineVisualSet

Plots of parametric lines for which multiple values can correspond to a single argument

Line color, line width, line style, interpolation type

BarVisualSet

Bar plots, including bar plots with multiple categories when bars are split into several parts of different color

Bar background colors, categories text labels

HistogramVisualSet

Histograms, or plots that show distributions

Bar background colors, flag specifying whether or not to show CDF

GanttVisualSet

Sequences of slots on Gantt charts

Background colors, label texts on Gantt chart slots

RegionVisualSet

Sequences of regions, corresponding in length to duration of any events or states

Background colors, label texts on regions

HorizontalGridLineVisualSet

Sequences of Y-axis grid lines, corresponding to numeric value thresholds

Line color, line width, label texts

VerticalGridLineVisualSet

Sequences of X-axis grid lines, corresponding to events or key values

Line color, line width, label texts

TriangleMarkerVisualSet

Sequences of triangle markers usually used in common with a GanttVisualSet to mark specific areas on gantt-rectangles

Background and border colors, width/height in pixels, drawing side and vertex direction

There are some other visual set types for more specific cases, like PointsVisualSet for clouds of points, or ConnectionVisualSet for displaying connections between slots on Gantt charts.

3. Fluent API for creating visual sets

For most commonly used visual sets, there are typical underlying data structures that contain the data. VisualSets class offers a set of static methods for easy creation of visual sets for common data structures. Using VisualSets allows developers to reduce the boilerplate code of creating visual sets by calling constructors.

4. LineVisualSet

LineVisualSet is designed to show time series data or, more generically, a dependency of some value on some argument. Type parameter of this class determines the type of data elements being shown. For example, in daily sales data, a data element can be a Pair of two Double values: first value is the number of day, and second value is the amount of units sold. For each data element, functions mapping the element to argument and value of a 2-d point of a plot must be specified.

LineVisualSet
Table 2. Methods of class LineVisualSet
Method Description

setLineColor

Sets the line color of the plot. Transparent and semi-transparent colors are allowed

setLineWidth

Sets the width of the line, in pixels. Setting zero width will result in …​

setLineStyle

Sets the style of the line - can be solid or dashed

setPointSize

Sets the diameter of the point, in pixels

setMaxValue

Sets the supplier of max value. This value allows to set some "natural" max value of the data being displayed It will be used when scaling the Y-axis of the chart.

setPointsAndLinesStyle

Specifies what of the following is displayed for the plot: points, lines, both, or none.

setInterpolationType

Sets the type of interpolation. Interpolation type determines how lines will be drawn between the data points.

setDrawingPolicy

Sets the policy used while drawing the plot. The drawing policy determines how several subsequent equal data points must be drawn

setStackVisible

Changes the visibility of the stack, i.e. area between the plot line and X-Axis.

setStackFillColor

Sets the filling color of the stack, i.e. the color that will be used to fill the area between the plot line and X-Axis. Applied only when display of stack was enabled by setStackVisible method.

setPointSize

Sets the size (diameter) of the point. Applied only if display of points was enabled by setPointsAndLinesStyle method.

setTooltipText

Sets the function that returns a tooltip text for a given data element

5. LineBarVisualSet

LineBarVisualSet enable showing visuals corresponding to the statistical data on LineChart. The bottom of the bar is always drawn at zero on the Y-axis and the top is at actual element value on the Y-axis.

LineBarVisualSet
Table 3. Methods of class LineBarVisualSet
Method Description

setBarColor

Sets the fill color of the bar. Transparent and semi-transparent colors are allowed

setBarWidth

Sets the width of the bar, in pixels

setBarAlignment

Sets the BarAlignment i.e. a way to draw bars relative to a grid line on the corresponding argument along the X-axis

setTooltipText

Sets the function that returns a tooltip text for a given data element

setClipboardText

Sets the the conversion method from string representations of each plot value into text that will be copied to clipboard

getValue

Returns the value of the given data element

6. PointsVisualSet

PointsVisualSet is designed to show time series data or, more generically, a dependency of some value on some argument. Type parameter of this class determines the type of data elements being shown. This VisualSet provides the opportunity to arrange points not only in ascending order of the X-axis values, but also in a random order, including the allocation of several different points on the same value of the horizontal axis.

PointsVisualSet
Table 4. Methods of class PointsVisualSet
Method Description

setPointSize

Sets the diameter of the point, in pixels

setFillColor

Sets the point fill color of the plot. Transparent and semi-transparent colors are allowed

setBorderColor

Sets the point border color of the plot. Transparent and semi-transparent colors are allowed

setTooltipText

Sets the function that returns a tooltip text for a given data element

7. PolylineVisualSet

PolylineVisualSet is designed to show time series data or, more generically, a dependency of some value on some argument. Differs from a LineVisualSet in that the data element arguments may not be strictly increasing.

PolylineVisualSet
Table 5. Methods of class PolylineVisualSet
Method Description

setLineColor

Sets the line color of the plot. Transparent and semi-transparent colors are allowed

setLineWidth

Sets the width of the line, in pixels. Setting zero width will result in …​

setLineStyle

Sets the style of the line - can be solid or dashed

setPointSize

Sets the diameter of the point, in pixels

setMaxValue

Sets the supplier of max value. This value allows to set some "natural" max value of the data being displayed It will be used when scaling the Y-axis of the chart.

setPointsAndLinesStyle

Specifies what of the following is displayed for the plot: points, lines, both, or none.

setDrawingPolicy

Sets the policy used while drawing the plot. The drawing policy determines how several subsequent equal data points must be drawn

setStackVisible

Changes the visibility of the stack, i.e. area between the plot line and X-Axis.

setStackFillColor

Sets the filling color of the stack, i.e. the color that will be used to fill the area between the plot line and X-Axis. Applied only when display of stack was enabled by setStackVisible method.

setPointSize

Sets the size (diameter) of the point. Applied only if display of points was enabled by setPointsAndLinesStyle method.

setTooltipText

Sets the function that returns a tooltip text for a given data element

8. GanttVisualSet

GanttVisualSet enables showing sequences of slots on a GanttChart. Gantt slots are shown as bars with borders, background colors and text labels. There can be several text labels on one slot, the labels can be located in 9 possible positions of a bar.

GanttVisualSet
Table 6. Methods of class GanttVisualSet
Method Description

setBackgroundColor

Sets the function that calculates background color of a Gantt slot for a given data element.

setBorderColor

Sets the function that calculates border color of a Gantt slot for a given data element.

setBorderWidth

Sets the function that calculates border width of a Gantt slot for a given data element, in pixels.

setRowHeightFraction

Sets the function that calculates the fraction of height that a Gantt slot will occupy. Setting 1.0 means the slot will occupy the entire height of the row.

setBeginArgument

Sets the function that calculates the begin position of a Gantt slot, i.e. value on X-Axis where the slot begins, for a given data element.

setEndArgument

Sets the function that calculates the end position of a Gantt slot, i.e. value on X-Axis where the slot ends, for a given data element.

setTooltipText

Sets the function that returns a tooltip text for a given data element

setLabelText

Sets the labels of the rectangles representing plot data elements. The label of each rectangle is set independently of the labels on other sides of this rectangle or the labels on other rectangles. The label will not be displayed if the specified text is empty. The label color is generated automatically based on the inverted background color of the rectangle

getGanttChartRow

Returns the GanttChartRow in which this visual set is shown.

9. GanttPolylineVisualSet

GanttPolylineVisualSet is designed to show time series data or, more generically, a dependency of some value on some argument. Polylines are drawn within a single GanttChartRow that does not have its own numerical vertical axis. A drawn polyline is usually used not for the purpose of represents exact values, but for the purpose of understanding the general profile of changing values. The minimum Y-value within the data elements corresponds to the lower bound of the GanttChartRow, and the maximum value corresponds to the upper one. The remaining values are drawn relative to the minimum and maximum.

GanttPolylineVisualSet
Table 7. Methods of class GanttPolylineVisualSet
Method Description

setRowHeightFraction

Sets the fraction height of the region in which polyline is drawn. Fraction is calculated relative to the height of the region allocated for corresponding GanttChart.

setLineColor

Sets the line color of the plot. Transparent and semi-transparent colors are allowed

setLineWidth

Sets the width of the line, in pixels. Setting zero width will result in …​

setLineStyle

Sets the style of the line - can be solid or dashed

setPointSize

Sets the diameter of the point, in pixels

setMaxValue

Sets the supplier of max value. This value allows to set some "natural" max value of the data being displayed It will be used when scaling the Y-axis of the chart.

setPointsAndLinesStyle

Specifies what of the following is displayed for the plot: points, lines, both, or none.

setPointSize

Sets the size (diameter) of the point. Applied only if display of points was enabled by setPointsAndLinesStyle method.

setTooltipText

Sets the function that returns a tooltip text for a given data element

10. ConnectionVisualSet

ConnectionVisualSet used to draw connections or dependencies. Each dependency is defined by a source and target points, with each of these points being a pair of a GanttChartRow and an X-axis argument.

ConnectionsVisualSet
Table 8. Methods of class ConnectionVisualSet
Method Description

setLineColor

Sets the line color of the plot. Transparent and semi-transparent colors are allowed

setWidth

Sets the width of the line, in pixels

setLineStyle

Sets the {@link LineStyle} of the lines representing plot data elements. The LineStyle of each line is set independently of the LineStyle of other lines

getSourceArgument

Returns a source dependency argument for a given data element

getSourceGanttChartRow

Returns a source dependency GanttChartRow for a given data element

getTargetArgument

Returns a target dependency argument for a given data element

getTargetGanttChartRow

Returns a target dependency GanttChartRow for a given data element

11. BarVisualSet

BarVisualSet enable showing of one column of bar chart, probably consisting of several bars on top of each other. Each such bar corresponds to certain category.

For example, if we want to plot domestic and overseas sales for 3 years, we can use:

  • enumeration of DOMESTIC and OVERSEAS as categories,

  • 3 instances of BarVisualSet for every year. They will be shown in different columns

We can define different columns for DOMESTIC and OVERSEAS categories, as well as ordering of these categories in the stack of bars.

BarVisualSet
Table 9. Methods of class BarVisualSet
Method Description

setColumnWidthFraction

Sets the width fraction to region allocated for each individual category-bar. Note than depending on the type of BarLayout, the visual can be drawn with category-bars stacked on top of each other or a series of category-bars in a row. The fraction is applied to the region calculation results for each data element with respect to summary bars width fraction, set by the call setVisualWidthFraction. The resulting region is divided by the number of category-bars arranged in a row horizontally and then the width of each bar is multiplied by columnWidthFraction.

setVisualWidthFraction

Sets the fraction width of the region in which bars are drawn. Fraction is calculated relative to the width of the region allocated for each data element. By controlling this parameter, the total width of the bars region is configured, in which bars can be drawn. As a result the width of the bars themselves can be adjusted.

setCategoriesComparator

Specifies the comparator used to sort the categories. Sorting affects the display order of the bars and the order of the legend elements

setElementText

Sets the label text for each data element. This label is displayed on the ticks of the X-axis, below the corresponding bars

setLegendLabelText

Sets the legend label text for each category

setBackgroundColor

Sets the background color for each category. The color may be different for different categories and it does not depend on different data elements. Also used to display a color icon in the Legend

setBorderColor

Sets the border color for each category. The color may be different for different categories and it does not depend on different data elements

setBorderWidth

Sets the border width in pixels for each category. The width may be different for different categories and it does not depend on different data elements

setTooltipText

Sets the function that returns a tooltip text for a given data element

setLabelText

Sets the labels of the bars representing plot data elements. The label of each bar is set independently of the labels on other sides of this bar or the labels on other bars. The label will not be displayed if the specified text is empty

setBarLabelText

Sets the label text for each visual element. This label is displayed above the corresponding bars

setBarLabelFontSize

Sets the label font size for each visual element. This label is displayed above the corresponding bars

setBarLabelColor

Sets the label color for each visual element. This label is displayed above the corresponding bars

getMinArgument

Returns the minimum possible value that stored in the current data elements list

getMaxArgument

Returns the maximum possible value that stored in the current data elements list

getPercentOfMaxValue

Returns the ratio of the value for the maximum group to the total sum of the all values across the entire statistics

getMaxGroupValue

Returns the maximum value for any data group within all existed data elements. The data group in the case of a histogram is the range of the X-axis arguments, and in the case of a bar chart, each individual data element

getMaxValueByAnyCategory

Returns the maximum value for any category within all existed data elements

getValue

Returns the value for given category within the given data element

getSummaryValue

Returns the total value for all categories within the given data element

getCategories

Returns the list of data categories

12. HistogramVisualSet

HistogramVisualSet enable showing histograms, possibly with categories. The histogram divides all statistical data into a number of buckets and estimates how frequently the data falls within each bucket.

HistogramVisualSet
Table 10. Methods of class HistogramVisualSet
Method Description

setColumnWidthFraction

Sets the width fraction to region allocated for each individual category-bar

setElementText

Sets the label text for each data element. This label is displayed on the ticks of the X-axis, below the corresponding bars

setLegendLabelText

Sets the legend label text for each category

setBackgroundColor

Sets the background color for each category. The color may be different for different categories and it does not depend on different data elements. Also used to display a color icon in the Legend

setBorderColor

Sets the border color for each category. The color may be different for different categories and it does not depend on different data elements

setBorderWidth

Sets the border width in pixels for each category. The width may be different for different categories and it does not depend on different data elements

setTooltipText

Sets the function that returns a tooltip text for a given data element

setLabelText

Sets the labels of the bars representing plot data elements. The label of each bar is set independently of the labels on other sides of this bar or the labels on other bars. The label will not be displayed if the specified text is empty

setBarLabelText

Sets the label text for each visual element. This label is displayed above the corresponding bars

setBarLabelFontSize

Sets the label font size for each visual element. This label is displayed above the corresponding bars

setBarLabelColor

Sets the label color for each visual element. This label is displayed above the corresponding bars

getMinArgument

Returns the minimum possible value that stored in the current data elements list

getMaxArgument

Returns the maximum possible value that stored in the current data elements list

getPercentOfMaxValue

Returns the ratio of the value for the maximum group to the total sum of the all values across the entire statistics

getMaxGroupValue

Returns the maximum value for any data group within all existed data elements. The data group in the case of a histogram is the range of the X-axis arguments, and in the case of a bar chart, each individual data element

getMaxValueByAnyCategory

Returns the maximum value for any category within all existed data elements

getValue

Returns the value for given category within the given data element

getSummaryValue

Returns the total value for all categories within the given data element

getCategories

Returns the list of data categories

13. RegionVisualSet

RegionVisualSet enable showing regions on GanttChart or LineChart. Each region is defined by a pair of begin and end values on the X-axis and fills the full height of the chart’s content area on the Y-axis.

RegionVisualSet
Table 11. Methods of class RegionVisualSet
Method Description

setBackgroundColor

Sets the background color for each data element. The color may be different for different data elements

setBorderColor

Sets the border color for each data element. The color may be different for different data elements

setBorderWidth

Sets the border width in pixels for each data element. The width may be different for different data elements

setLabelText

Sets the labels of the rectangles representing plot data elements. The label of each rectangle is set independently of the labels on other sides of this rectangle or the labels on other rectangles. The label will not be displayed if the specified text is empty

setTooltipText

Sets the function that returns a tooltip text for a given data element

getValue

Returns the value of the given X-axis argument

14. VerticalGridLineVisualSet

VerticalGridLineVisualSet enables showing some events on the time-relative X-axis.

VerticalGridLineVisualSet
Table 12. Methods of class VerticalGridLineVisualSet
Method Description

setLineColor

Sets the line color of the lines representing plot data elements. The color of each element is set independently of the color of other elements. Transparent and semi-transparent colors are allowed

setLineWidth

Sets the width of the grid lines representing plot data elements, in pixels. The width of each grid line is set independently of the width of other grid lines

setLabelText

Sets the labels of the grid lines representing plot data elements. The label of each grid line is set independently of the labels of other grid lines. The label will not be displayed if the specified text is empty

setTooltipText

Sets the function that returns a tooltip text for a given data element

setClipboardText

Sets the the conversion method from string representations of each plot value into text that will be copied to clipboard.

15. HorizontalGridLineVisualSet

HorizontalGridLineVisualSet enables showing some threshold values on the Y-axis.

HorizontalGridLineVisualSet
Table 13. Methods of class HorizontalGridLineVisualSet
Method Description

setLineColor

Sets the line color of the lines representing plot data elements. The color of each element is set independently of the color of other elements. Transparent and semi-transparent colors are allowed

setLineWidth

Sets the width of the grid lines representing plot data elements, in pixels. The width of each grid line is set independently of the width of other grid lines

setLabelText

Sets the labels of the grid lines representing plot data elements. The label of each grid line is set independently of the labels of other grid lines. The label will not be displayed if the specified text is empty

setTooltipText

Sets the function that returns a tooltip text for a given data element

setClipboardText

Sets the the conversion method from string representations of each plot value into text that will be copied to clipboard

16. TriangleMarkerVisualSet

TriangleMarkerVisualSet enables showing triangle markers used in common with a GanttVisualSet to mark specific areas on gantt-rectangles. The triangle can be drawn in different directions (i.e. point up or down) and on different sides of the gantt-rectangle (i.e. on rectangle top or bottom side).

TriangleMarkersVisualSet
Table 14. Methods of class TriangleMarkerVisualSet
Method Description

setSide

Sets the drawing Side for each data element i.e. the side of the intended rectangle, relative to which the triangle is drawn

setDirection

Sets the drawing Direction for each data element i.e. the direction of the vertex of the triangle

setWidth

Sets the width in pixels for each data element

setHeight

Sets the height in pixels for each data element

setBorderColor

Sets the border color for each data element. The color may be different for different data elements

setBorderWidth

Sets the border width in pixels for each data element

setFillColor

Sets the background color for each data element. The color may be different for different data elements

setRowHeightFraction

Sets the fraction height of the region in which triangle is drawn. The fraction may be different for different data elements. Fraction is calculated relative to the height of the region allocated for corresponding GanttChartRow

setTooltipText

Sets the function that returns a tooltip text for a given data element