Barchart widgets - 2

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

This module defines predicates which show barchart widgets. The three predicates exported by this module plot two-variable data as regular bars in a window. They all share the following features:

Numeric values for the x axis are needed, otherwise it does not work properly. See xbarelement2/1 definition type.
The bar position is proportional to the x-coordinate value.
The user can either select the appearance of the bars (background color, foreground color and stipple style) or not. See the xbarelement2/1 type definition. Thus, the user can call each predicate in two ways.
The bar chart has a legend and one entry (symbol and label) per bar.
If you do not want to display text in the elements header, barchart title, x axis title, y axis title or footer, simply type ” as the value of the argument.
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 contain elements but are not correct, the exception error1 or error3 will be thrown, depending on the error type. error1 means that XVector and YVector does not contain the same number of elements and error3 indicates that not all the XVector elements contain a correct number of attributes .

Particular features will be pointed out in the corresponding predicate.

Usage and interface

Library usage:
:- use_module(library(genbar2)).
Exports:
- Predicates:
  barchart2/7, barchart2/11, percentbarchart2/7.
- Regular Types:
  xbarelement2/1.
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

barchart2/7:

barchart2(Header,BarchartTitle,XTitle,XVector,YTitle,YVector,Footer)

The maximum and minimum limits for axes are determined from the data.

Example:

barchart2('This is the header text',
  'Barchart with legend',
  'My xaxistitle',
  [ [1,'bar1','Blue','Yellow','pattern1'],
       [2,'bar2','MediumTurquoise','Plum','pattern5'] ],
  'My yaxixtitle',
  [20,10],
  '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)BarchartTitle 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 xbarelement2s.
(genbar1:title/1)YTitle is a text (an atom) to be used as label, usually not very long.
(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

barchart2/11:

barchart2(Header,BT,XT,XVector,XMax,XMin,YT,YVector,YMax,YMin,Footer)

You can set the minimum and maximum limits of the axes. Data outside the limits will not be plotted. Each limit, as you can check looking at the axis_limit/1 definition, is a number. If the argument is a variable the limit will be calculated from the data (i.e., if YMax value is YValueMax the maximum y axis limit will calculated using the largest data value).

Example:

barchart2('This is the header text',
  'Barchart with legend',
  'My xaxistitle',
  [ [1,'bar1',Color1,Color2,Pattern1],
         [2,'bar2',Color3,Color4,Pattern2] ],
  10,
  -10,
  'My yaxixtitle',
  [20,10],
  100,
  -10,
  'The limits for the axes are set by the user').

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 xbarelement2s.
(genbar1:axis_limit/1)genbar1:axis_limit(XMax)
(genbar1:axis_limit/1)genbar1:axis_limit(XMin)
(genbar1:title/1)YT is a text (an atom) to be used as label, usually not very long.
(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.

PREDICATE

percentbarchart2/7:

percentbarchart2(Header,BTitle,XTitle,XVector,YTitle,YVector,Footer)

The y axis maximum coordinate value is 100. The x axis limits are autoarrange.

Example:

percentbarchart2('This is a special barchart to represent percentages',
  'Barchart with legend',
  'My xaxistitle',
  [ [1,'bar1','Blue','Yellow','pattern1'],
          [2,'bar2','MediumTurquoise','Plum','pattern5'] ],
  'My yaxixtitle',
  [80,10],
  '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 xbarelement2s.
(genbar1:title/1)YTitle is a text (an atom) to be used as label, usually not very long.
(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.

REGTYPE

xbarelement2/1:

xbarelement2([XValue,LegendElement]) :-
        number(XValue),
        atomic(LegendElement).
xbarelement2([XValue,LegendElement,ForegColor,BackgColor,SPattern]) :-
        number(XValue),
        atomic(LegendElement),
        color(ForegColor),
        color(BackgColor),
        pattern(SPattern).

Defines the attributes of the bar.

XValue: x-coordinate position of the bar. Different elements with the same abscissas will produce overlapped bars.
LegendElement: Element legend name. It may be a number or an atom and equal or different to the XValue. Every LegendElement value of the list must be unique.
ForegColor: Is 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.
BackgColor: Is 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.
SPattern: Is 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.

Barchart widgets - 2

Usage and interface

Documentation on exports

Module Sections

Global Links

Indices