Multi barchart widgets

Author(s): Isabel Martín García.

This module defines predicates which show barchart widgets. These bar charts are somewhat different from the bar charts generated by the predicates in modules genbar1, genbar2, genbar3 and genbar4. Predicates in the present module show different features of each dataset element in one chart at the same time. Each bar chart element is a group of bars, and the element features involve three vectors defined as follows:

xvector is a list containing the names (atoms) of the bars (n elements). Each bar group will be displayed at uniform intervals.
yvector is a list that contains m sublists, each one is composed of n elements. The i-sublist contains the y-values of the i-BarAttribute element for all of the XVector elements.
bar_attributtes is a list containing the appearance features of the bars (m elements). Each element of the list can be partial or complete, which means that you can define as bar attributes only the element name or by setting the element name, its background and foreground color and its stipple pattern.

Other relevant aspects about this widgets are:

If you don't want to display text in the elements header, barchart title, xaxis title, yaxis title or footer, simply type ” as the value of the argument.
The bar chart has a legend, and one entry (symbol and label) per feature group bar.
The user can either select the appearance of the bars (background color, foreground color and stipple style) or not. See the multibar_attribute type definition.
Data points can have their bar segments displayed in one of the following modes: stacked, aligned, overlapped or overlayed. They user can change the mode clicking in the checkboxes associated to each mode.
The predicates test whether the format of the arguments is correct. If one or both vectors are empty, the exception error2 will be thrown. If the vectors contains elements but are not correct, the exception error5 or error6 will be thrown, depending on what is incorrect. error5 means that XVector and each element of YVector do not contain the same number of elements or that YVector and BarsAtt do not contain the same number of elements, while error6 indicates that not all the BarsAtt elements contain a correct number of attributes.

The examples will help you to understand how these predicates should be called.

Usage and interface

Library usage:
:- use_module(library(genmultibar)).
Exports:
- Predicates:
  multibarchart/8, multibarchart/10.
Imports:
- System library modules:
  chartlib/genbar1, chartlib/bltclass, chartlib/color_pattern, chartlib/test_format, chartlib/install_utils, lists, random/random.
- Packages:
  prelude, nonpure, assertions, regtypes, isomodes.

Documentation on exports

PREDICATE

multibarchart/8:

multibarchart(Header,BTitle,XTitle,XVector,YTitle,BarsAtts,YVector,Footer)

The x axis limits are autoarrange. The user can call the predicate in two ways. In the first example the user sets the appearance of the bars, in the second one the appearance features will be chosen by the library.

Example1:

multibarchart('This is the Header text',
	'My BarchartTitle',
	'Processors',
	['processor1','processor2','processor3','processor4'],
	'Time (seconds)',
	[['setup time','MediumTurquoise','Plum','pattern2'],
	    ['sleep time','Blue','Green','pattern5'],
	    ['running time','Yellow','Plum','pattern1']],
	[[20,30,40,50],[10,8,5,35],[60,100,20,50]],
	'This is the Footer text').

Example2:

multibarchart('This is the Header text',
	'My BarchartTitle',
	'Processors',
	['processor1','processor2','processor3','processor4'],
	'Time (seconds)',
	[['setup time'],['sleep time'],['running time']],
	[[20,30,40,50],[10,8,5,35],[60,100,20,50]],
	'This is the Footer text').

Usage:

The following properties should hold at call time:
(genbar1:header/1)Header is a text (an atom) describing the header of the graph.
(genbar1:title/1)BTitle is a text (an atom) to be used as label, usually not very long.
(genbar1:title/1)XTitle is a text (an atom) to be used as label, usually not very long.
(basic_props:list/2)XVector is a list of xelements.
(genbar1:title/1)YTitle is a text (an atom) to be used as label, usually not very long.
(basic_props:list/2)BarsAtts is a list of multibar_attributes.
(basic_props:list/2)YVector is a list of yelements.
(genbar1:footer/1)Footer is a text (an atom) describing the footer of the graph.

PREDICATE

multibarchart/10:

multibarchart(Header,BT,XT,XVector,YT,BAtts,YVector,YMax,YMin,Footer)

This predicate is quite similar to multibarchart/8, except in that you can choose limits in the y axis. The part of the bars placed outside the limits will not be plotted.

Example2:

multibarchart('This is the Header text',
	'My BarchartTitle',
	'Processors',
	['processor1','processor2','processor3','processor4'],
	'Time (seconds)',
	[['setup time'],['sleep time'],['running time']],
	[[20,30,40,50],[10,8,5,35],[60,100,20,50]],
	[80],
	[0],
	'This is the Footer text').

Usage:

The following properties should hold at call time:
(genbar1:header/1)Header is a text (an atom) describing the header of the graph.
(genbar1:title/1)BT is a text (an atom) to be used as label, usually not very long.
(genbar1:title/1)XT is a text (an atom) to be used as label, usually not very long.
(basic_props:list/2)XVector is a list of xelements.
(genbar1:title/1)YT is a text (an atom) to be used as label, usually not very long.
(basic_props:list/2)BAtts is a list of multibar_attributes.
(basic_props:list/2)YVector is a list of yelements.
(genbar1:axis_limit/1)genbar1:axis_limit(YMax)
(genbar1:axis_limit/1)genbar1:axis_limit(YMin)
(genbar1:footer/1)Footer is a text (an atom) describing the footer of the graph.

Documentation on internals

REGTYPE

multibar_attribute/1:

multibar_attribute([LegendElement]) :-
        atomic(LegendElement).
multibar_attribute([LegendElement,ForegroundColor,BackgroundColor,StipplePattern]) :-
        atom(LegendElement),
        color(ForegroundColor),
        color(BackgroundColor),
        pattern(StipplePattern).

Defines the attributes of each feature bar along the different datasets.

LegendElement: Legend element name. It may be a number or an atom. Every LegendElement value of the list must be unique.
ForegroundColor: It sets the Foreground color of the bar. Its value must be a valid color, otherwise the system will throw an exception. If the argument value is a variable, it gets instantiated to a color chosen by the library.
BackgroundColor: It sets the Background color of the bar. Its value must be a valid color, otherwise the system will throw an exception. If the argument value is a variable, it gets instantiated to a color chosen by the library.
StipplePattern: It sets the stipple of the bar. Its value must be a valid pattern, otherwise the system will throw an exception. If the argument value is a variable, it gets instantiated to a pattern chosen by the library.

REGTYPE

xelement/1:

xelement(Label) :-
        atomic(Label).

This type defines a dataset label. Although Label values may be numbers, the will be treated as atoms, So it will be displayed at uniform intervals along the x axis.

Multi barchart widgets

Usage and interface

Documentation on exports

Documentation on internals

Module Sections

Global Links

Indices