Plots bar charts in high-resolution graphics.
Options
TITLE = text |
General title; default * |
|---|---|
WINDOW = scalar |
Window number for the bar charts; 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 token |
Whether or not the bars of the bar charts are appended together (yes, no); default no |
ORIENTATION = string token |
Direction of the plot (horizontal, vertical); default vert |
YSCALING = string token |
What scale to use to label the y-axis (absolute, proportion, percentage); default abso |
OUTLINE = string token |
Where to draw outlines (bars, perimeter); default bars |
PENOUTLINE = scalar |
Pen to use for the outlines; default -9 |
SCREEN = string token |
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 token |
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 bar chart |
|---|---|
ERRORBARS = scalars, tables or variates |
Heights of error bars plotted above the bars of each bar chart; default 0 i.e. none |
LOWERERRORBARS = scalars, tables or variates |
Heights of error bars plotted below the bars of each bar chart; if any of these is omitted, the corresponding setting of ERRORBARS is used as the default so that the error bars will have equal heights above and below the bars of the bar chart |
GROUPS = factors |
Which factor of a 2-way table to use as the groups factor; default uses the second classifying factor |
PEN = scalars, tables or variates |
Pen number(s) for each bar chart; 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 -11 |
DESCRIPTION = texts |
Annotation for key |
Description
BARCHART plots high-resolution bar charts. You can plot a single bar chart by setting the DATA parameter to a one-way table or a variate defining the heights of the bars. To plot several bar charts on the same graph, you can set DATA to a 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. The GROUPS parameter then specifies which of the two classifying factors is to be treated as the “groups” factor (by default this is the second factor). BARCHART now plots a bar chart for every level of the GROUPS factors, with bars defined by the other 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 bar charts, they are plotted with their bars alongside each other. So BARCHART first plots the first bar of every bar chart, then the second bar, and so on. Alternatively, you can set option APPEND=yes to stack the bars. The bottom portion of each bar then corresponds to the first bar chart, and the top to the last bar chart.
You can include error bars in a single bar chart or when several bar charts are plotted alongside each other, by specifying their heights with the ERRORBARS and LOWERERRORBARS parameters. The error bars take the form of a horizontal line joined by a vertical line of the specified height, above and below each bar. The ERRORBARS parameter specifies the heights of the error bars above the bars of the bar chart, and the LOWERERRORBARS parameter specifies the heights of the error bars below the bars. If LOWERERRORBARS is not specified, the error bars are assumed to have the same heights below and above the bars. You can set ERRORBARS and LOWERERRORBARS to a scalar if the heights are the same for every bar of a bar chart, or to a table or variate if different bars have error bars with different heights.
The ORIENTATION option controls whether the bars of the bar chart 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 bar chart is oriented.
By default, Genstat uses pen 2 for the first bar chart, pen 3 for the second bar chart, and so on, so that a different colour 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 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 (default -11).
The bars in a bar chart 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 bar chart. 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 bar chart 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 bar chart and key using the TITLE and KEYDESCRIPTION options respectively.
The SCREEN option controls whether the graphical display is cleared before the bar chart 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 YSCALING option controls the scale used to label the y-axis, with settings absolute, proportion or percentage; the default is absolute.
The key consists of the title, if set by KEYDESCRIPTION, followed information about each bar chart. You can specify a description for each bar chart 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 GROUPS factor.
Options: TITLE, WINDOW, KEYWINDOW, BARWIDTH, BARCOVERING, LABELS, APPEND, ORIENTATION, SCALING, OUTLINE, PENOUTLINE, SCREEN, KEYDESCRIPTION, ENDACTION.
Parameters: DATA, ERRORBARS, LOWERERRORBARS, GROUPS, PEN, PENERRORBARS, DESCRIPTION.
See also
Directives: DHISTOGRAM, D3HISTOGRAM, DPIE, LPHISTOGRAM, FRAME, XAXIS, YAXIS, PEN.
Procedures: TRELLIS, DBARCHART, DMASS, DMOSAIC, DOTHISTOGRAM, DOTPLOT, DCIRCULAR, D2GROUPS, WINDROSE.
Commands for: Graphics.
Example
" Example 1:6.3.2 and Figure 1:6.3.2 "
FACTOR [LEVELS=!(1999,2000)] Year
FACTOR [LABELS=!t(April,June,September,December)] Month
TABLE [CLASSIFICATION=Year,Month; VALUES=45000,10000,-24000,11000,\
21000,34000,-10000,47000] Results
BARCHART [TITLE='Profit and loss'] Results