Barchart widgets - 1

Author(s): Isabel Martín.

Version: 1.10#7 (2006/4/26, 19:22:13 CEST)

Version of last change: 1.9#260 (2003/12/31, 0:13:52 CET)

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 (genbar1)
• Documentation on exports (genbar1)
• Documentation on internals (genbar1)

Usage and interface (genbar1)

Documentation on exports (genbar1)

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').

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').

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').

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: header/1:

Usage: header(X)

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

REGTYPE: title/1:

Usage: title(X)

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

REGTYPE: footer/1:

Usage: footer(X)

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

Documentation on internals (genbar1)

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.

Go to the first, previous, next, last section, table of contents.