BARCHART directive

Plots barcharts in high-resolution graphics.


Options

TITLE = text
General title; default *

WINDOW = scalar
Window number for the histograms; default 1

KEYWINDOW = scalar
Window number for the key (zero for no key); default 2

BARWIDTH = scalar, variate or table
Width(s) of the bars; default * sets equal widths to fill the x-axis

BARCOVERING = scalar
What proportion of the space allocated along the x-axis each bar should occupy; default * gives proportion 1 for a DATA variate, and 0.8 for a factor or table (thus giving a gap between each bar)

LABELS = text
Labels for the bars or groups of bars; default *

APPEND = string
Whether or not the bars of the histograms are appended together (yes, no); default no

ORIENTATION = string
Direction of the plot (horizontal, vertical); default vert

OUTLINE = string
Where to draw outlines (bars, perimeter); default bars

PENOUTLINE = scalar
Pen to use for the outlines; default -9

SCREEN = string
Whether to clear the screen before plotting or to continue plotting on the old screen (clear, keep); default clea

KEYDESCRIPTION = text
Overall description for the key; default *

ENDACTION = string
Action to be taken after completing the plot (continue, pause); default * uses the setting from the last DEVICE statement


Parameters

DATA = tables or variates
Heights of the bars in each barchart

ERRORBARS = scalars, tables or variates
Error bars to be plotted above the bars of each barchart

PEN = scalars, tables or variates
Pen number(s) for each barchart; default * uses pens 2, 3, and so on for the successive structures specified by DATA

PENERRORBARS = scalars, tables or variates
Pen number(s) for the error bars; default 1

DESCRIPTION = texts
Annotation for key


Description

BARCHART plots high-resolution barcharts. You can plot a single barchart by setting the DATA parameter to a one-way table or a variate defining the heights of the bars. To plot several barcharts on the same graph, you can set DATA to list of one-way tables or variates. These must all contain the same number of values, and any tables must be classified by the same factor. Alternatively, you can set DATA to a two-way table. BARCHART then plots a barchart for every level of the first classifying factor, with bars defined by the second classifying factor.

   Labels can be supplied for the bars, using the LABELS option. If this is not set, the labels will be the labels or levels of the factor classifying the DATA tables, or the integers 1 upwards for a DATA variate.

   By default, if there are several barcharts, they are plotted with their bars alongside each other, in groups. So BARCHART first plots the first bar of every barchart (group 1), then the second bar (group 2), and so on. Alternatively, you can set option APPEND=yes to stack the bars in each group into a single bar. The bottom portion of each bar then corresponds to the first barchart, and the top to the last barchart.

   You can include error bars in a single barchart or when several barcharts are plotted alongside each other, by specifying the heights of the bars using the ERRORBARS parameter. These take the form of a horizontal line joined by a vertical line of the specified height, above and below each bar. You can set ERRORBARS to a scalar if the heights are the same for every bar of a barchart, or to a table or variate if different bars have error bars with different heights.

   The ORIENTATION option controls whether the bars of the histogram are plotted vertically (the default) or horizontally. When ORIENTATION=horizontal, the horizontal axis is taken to be the y-axis, so the same XAXIS and YAXIS settings can be used however the histogram is oriented.

   By default, GenStat uses pen 2 for the first barchart, pen 3 for the second barchart, and so on, so that a different colour or shading is used for each one. Alternatively, you can define your own colours or shading, using the PEN parameter. If you set PEN to a scalar, a single pen is used for all the bars. Alternatively, you can specify a variate or a table to define a different pen for each bar. The relevant aspects of the pens should be set in advance, if required, using the BRUSH and COLOUR parameters of the PEN directive. Generally, however, the default attributes of the pens will be satisfactory. Similarly, the PENERRORBARS parameter specifies the pen or pens to use for the error bars. By default these are all plotted using pen 1.

   The bars in a barchart usually have equal widths, defined to fill the available space along the x-axis. However, you can set your own widths by setting option BARWIDTH to either a scalar or a variate or table with as many values as the number of bars. The BARCOVERING option indicates what proportion of the space allocated along the x-axis each bar should occupy; the default is 0.8 (giving a gap between each bar).

   The OUTLINE option controls whether lines are drawn around the bars or around the perimeter of the barchart. These are drawn using the pen specified by the PENOUTLINE option (default -9). You can suppress all the outlines by setting OUTLINE=*.

   The WINDOW option defines the window where the histogram is plotted, and the KEYWINDOW option similarly specifies where the key should appear. You can set either of these to zero if you want to suppress the corresponding output. Titles can be added to the histogram and key using the TITLE and KEYDESCRIPTION options respectively.

   The SCREEN option controls whether the graphical display is cleared before the histogram is plotted and the ENDACTION option controls whether GenStat pauses at the end of the plot.

   The axes of the plot are formed automatically from the data. By default, the upper bound of the y-axis is set to be five percent greater than the height of the longest bar. If any of the bars has a negative height the lower bound is adjusted in a similar way, otherwise it is set to zero. You can control the form of the axes by using the XAXIS and YAXIS directives to set the required attributes (such as titles) before the BARCHART directive is used.

   The key consists of the title, if set by KEYDESCRIPTION, followed information about each barchart. You can specify a description for each barchart using the DESCRIPTION parameter. If the DATA parameter was set to a list of one-way tables or variates, the default description takes the identifier of the table or variate. If DATA was set to a two-way table, the default descriptions are formed from the labels or levels of the first classifying factor.

 

Options: TITLE, WINDOW, KEYWINDOW, BARWIDTH, BARCOVERING, LABELS, APPEND, ORIENTATION, OUTLINE, PENOUTLINE, SCREEN, KEYDESCRIPTION, ENDACTION.

Parameters: DATA, ERRORBARS, PEN, PENERRORBARS, DESCRIPTION.