Barchart widgets - 1

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

This module defines predicates to 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:

No numeric values for the x axis are needed because they will be interpreted as labels. See xbarelement1/1 definition type.
The bars will be displayed at uniform intervals.
The user can either select the appearance of the bars (background color, foreground color and stipple style) or not. See the xbarelement1 type definition. Thus, the user can call each predicate in two ways.
The bar chart has a legend. One entry (symbol and label) per bar.
If you don't 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 contains elements but are not correct, the exception error1 or error3 will be thrown, depending on the error type. error1 means that XVector and YVector do 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(genbar1)).
Exports:
- Predicates:
  barchart1/7, barchart1/9, percentbarchart1/7.
- Regular Types:
  yelement/1, axis_limit/1, header/1, title/1, footer/1.
Imports:
- System library modules:
  chartlib/bltclass, chartlib/test_format, chartlib/color_pattern, chartlib/install_utils, lists, random/random.
- Packages:
  prelude, nonpure, assertions, nortchecks, regtypes, isomodes.

Documentation on exports

PREDICATE

barchart1/7:

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

The y axis range is determined from the limits of the data. Two examples are given to demonstrate clearly how to call the predicates. In the first example the user sets the bar appearance, in the second one the appearance features will be chosen by the system and the colors that have been assigned to the variables Color1, Color2 and Pattern will be shown also.

Example 1:

barchart1('This is the header text',
  'Barchart title',
  'xaxistitle',
  [ ['bar1','legend_element1','Blue','Yellow','pattern1'],
           ['bar2','legend_element2','Plum','SeaGreen','pattern2'],
           ['bar3','legend_element3','Turquoise','Yellow',
	    'pattern5'] ],
  'yaxixtitle',
  [20,10,59],
  'footer').

Example 2:

barchart1('This is the header text',
  'Barchart title',
  'xaxistitle',
  [ ['element1','legend_element1',Color1,Color2,Pattern],
            ['element2','legend_element2'],
            ['element3','legend_element3'] ],
  'yaxixtitle',
  [20,10,59],
  'footer').

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 xbarelement1s.
(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

barchart1/9:

barchart1(Header,BTitle,XTitle,XVector,YTitle,YVector,YMax,YMin,Footer)

You can set the minimum and maximum limits of the y axis. Data outside the limits will not be plotted. Each limit, as you can check by 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:

barchart1('This is the header text',
  'Barchart title',
  'xaxistitle',
  [ ['element1','e1','Blue','Yellow','pattern1'],
      ['element2','e2','Turquoise','Plum','pattern5'],
      ['element3','e3','Turquoise','Green','pattern5'] ],
  'yaxixtitle',
  [20,10,59],
  70,
  _,
  'footer').

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 xbarelement1s.
(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: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

percentbarchart1/7:

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

The y axis maximum coordinate value is 100. The x axis limits are automatically worked out.

Example:

percentbarchart1('This is a special barchart to represent percentages',
  'Barchart with legend',
  'My xaxistitle',
  [ [1,'bar1','Blue','Yellow','pattern1'],
       [8,'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 xbarelement1s.
(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

yelement/1:

yelement(Y) :-
        number(Y).

Y is the bar lenght, so it must be a numeric value.

Both Prolog and Tcl-Tk support integers and floats. Integers are usually specified in decimal, but if the first character is 0 the number is read in octal (base 8), and if the first two characters are 0x, the number is read in hexadecimal (base16). Float numbers may be specified using most of the forms defined for ANSI C, including the following examples:

9.56
5.88e-2
5.1E2

Note: Be careful when using floats. While 8. or 7.e4 is interpreted by Tcl-tk as 8.0 and 7.0e4, Prolog will not read them as float numbers. Example:

        ?- number(8.e+5).
        {SYNTAX ERROR: (lns 130-130) , or ) expected in arguments
        number ( 8 
        ** here **
        . e + 5 ) . 
        }

        no
        ?- number(8.).
        {SYNTAX ERROR: (lns 138-138) , or ) expected in arguments
        number ( 8 
        ** here **
        . ) . 
        }

        no

        ?- number(8.0e+5).

        yes
        ?- number(8.0).

        yes

Precision: Tcl-tk internally represents integers with the C type int, which provides at least 32 bits of precision on most machines. Since Prolog integers can (in some implementations) exceed 32 bits but the precision in Tcl-tk depends on the machine, it is up to the progammer to ensure that the values fit into the maximum precision of the machine for integers. Real numbers are represented with the C type double, which is usually represented with 64-bit values (about 15 decimal digits of precision) using the IEEE Floating Point Standard.

Conversion: If the list is composed by integers and floats, Tcl-tk will convert integers to floats.

REGTYPE

axis_limit/1:

axis_limit(X) :-
        number(X).
axis_limit(_1).

This type is defined in order to set the minimum and maximum limits of the axes. Data outside the limits will not be plotted. Each limit, is a number or a variable. If the argument is not a number the limit will be calculated from the data (i.e., if YMax value is Var the maximum y axis limit will be calculated using the largest data value).

REGTYPE

Usage:header(X)

X is a text (an atom) describing the header of the graph.

REGTYPE

title/1:

Usage:title(X)

X is a text (an atom) to be used as label, usually not very long.

REGTYPE

Usage:footer(X)

X is a text (an atom) describing the footer of the graph.

Documentation on internals

REGTYPE

xbarelement1/1:

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

Defines the attributes of the bar.

XValue: bar label. Although XValue values may be numbers, the will be treated as labels. Different elements with the same label will produce different bars.
LegendElement: Legend element 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: 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.
BackgColor: 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.
SPattern: 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.

Known bugs and planned improvements

Run-time checks have been reported not to work with this code. That means that either the assertions here, or the code that implements the run-time checks are erroneous.

Barchart widgets - 1

Usage and interface

Documentation on exports

Documentation on internals

Known bugs and planned improvements

Module Sections

Global Links

Indices