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:
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:
VisualSet class | Description | Key appearance parameters |
---|---|---|
Line plot for showing time series data or dependency of some value on some argument |
Line color, line width, line style, interpolation type |
|
Plots of parametric lines for which multiple values can correspond to a single argument |
Line color, line width, line style, interpolation type |
|
Bar plots, including bar plots with multiple categories when bars are split into several parts of different color |
Bar background colors, categories text labels |
|
Histograms, or plots that show distributions |
Bar background colors, flag specifying whether or not to show CDF |
|
Sequences of slots on Gantt charts |
Background colors, label texts on Gantt chart slots |
|
Sequences of regions, corresponding in length to duration of any events or states |
Background colors, label texts on regions |
|
Sequences of Y-axis grid lines, corresponding to numeric value thresholds |
Line color, line width, label texts |
|
Sequences of X-axis grid lines, corresponding to events or key values |
Line color, line width, label texts |
|
Sequences of triangle markers usually used in common with a |
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.
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 |
setPointSize |
Sets the size (diameter) of the point. Applied only if display of points was enabled by |
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.
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 |
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.
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.
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 |
setPointSize |
Sets the size (diameter) of the point. Applied only if display of points was enabled by |
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.
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 |
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.
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 |
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 |
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.
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 |
getSourceArgument |
Returns a source dependency argument for a given data element |
getSourceGanttChartRow |
Returns a source dependency |
getTargetArgument |
Returns a target dependency argument for a given data element |
getTargetGanttChartRow |
Returns a target dependency |
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.
Method | Description |
---|---|
setColumnWidthFraction |
Sets the width fraction to region allocated for each individual category-bar.
Note than depending on the type of |
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.
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.
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.
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.
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).
Method | Description |
---|---|
setSide |
Sets the drawing |
setDirection |
Sets the drawing |
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
|
setTooltipText |
Sets the function that returns a tooltip text for a given data element |