Produces bar charts for one or two-way tables (A.R.G. McLachlan & R.C. Butler).
Options
TITLE = text |
Title for the chart; no default |
|---|---|
WINDOW = scalar |
Window for the chart; default 1 |
KEYWINDOW = scalar |
Window for the key, no key is produced for one-way tables; default 2 |
LABELS = text |
Labels for clusters of bars; by default the labels or levels of the first classifying factor of TABLE are used |
APPEND = string token |
Whether to append bars (no, yes); default no |
SCREEN = string token |
Whether to clear screen before displaying chart (keep, clear); default clea |
KEYDESCRIPTION = text |
Title for key; default is the name of the second factor of TABLE |
YSCALE = expression structure |
Defines a transformation of the data, the expression must be a function of either Y or X, for example !e(log(X)), and should be valid for the range of the data in TABLE; default no transformation |
BELOWORIGIN = string token |
Whether to include values in TABLE less than ORIGIN (omit, include); default omit |
ORIENTATION = string token |
Direction of the plot (horizontal, vertical); default vert |
BARCOVERING = scalar |
What proportion of the space allocated along the x-axis each bar should occupy; default * gives proportion 0.8 (thus giving a gap between each bar or each group of bars) |
XPOSITION = string token |
Position of the x-axis on the y-axis (lower, origin); default lowe |
OMITEMPTYLEVELS = string token |
Whether to omit levels where there are only missing values (yes, no); default no |
Parameters
TABLE = tables |
One or two-way table of data |
|---|---|
ORIGIN = scalars |
Origin for y-axis; default 0 |
PEN = variates or scalars |
Pen (or pens) to use; default is !(1 ... nlevel(last_classifying_factor)) |
DESCRIPTION = texts |
Annotation for Key for two-way tables; default uses the labels or levels of the factor that is not being used as the XFACTOR |
YMARKS = variates |
Position of the tick-marks on the y-axis |
XFACTOR = factors |
X-axis factor for a 2-way TABLE; default first factor of TABLE |
LOWERERRORBARS = tables, variates or scalars |
Lower bounds of the error bars on the y-axis |
UPPERERRORBARS = tables, variates or scalars |
Upper bounds of the error bars on the y-axis |
YERRORBARS = tables, variates or scalars |
Y-axis position of any error bar symbols; by default no symbols are plotted |
XERRORBARS = tables, variates or scalars |
X-axis position of the error bars; default midpoints of bar-chart bars |
PENERRORBARS = tables, variates or scalars |
Pen (or pens) to use for plotting error bars; default 1 |
Description
DBARCHART produces bar charts for one or two-way tables. A transformation can be specified by the option YSCALE, in which case the data and y-axis are rescaled, but the y-axis is labelled on the original scale of the data. The table is specified by the TABLE parameter and the origin of the y-axis, which need not be zero, can be set with the ORIGIN parameter or with XAXIS. The PEN parameter specifies a pen, or pens, for the bars of the histogram. This can be input as a scalar if the same pen is to be used for the whole plot, or as a variate to allow the groups to be drawn in different pens; by default pens 1, 2 … are used for the successive bars. Positions of the tick-marks on the y-axis can be specified with the YMARKS parameter or with YAXIS. Upper and lower limits for the y-axis can be defined as normal with a YAXIS statement before DBARCHART is used. Bar charts of two-way tables are by default produced with the first factor defining the groups of bars in the chart, and the second the bars within each group. The factor used for the x-axis can be specified by the XFACTOR parameter; this is ignored for one-way tables. Labelling for the key can be supplied by the DESCRIPTION parameter; if this is not set, DBARCHART uses the labels of the classifying factor that is not being used as the XFACTOR.
To plot error bars attached to the ends of the bars of the bar chart, one or both of UPPERERRORBARS and LOWERERRORBARS can be set to specify the upper and/or lower bounds of the error bars. By default, the x-axis coordinates of the error bars are the midpoints of the bar-chart bars. XERRORBARS can be used to specify different x-axis positions for the error bars. As a guide, the tickmarks on the x-axis have coordinates: 1 … number of levels of first factor of TABLE. If errors occur with the error-bar parameters, an error message will be given and, where possible, the bar chart will still be drawn but without error bars. UPPERERRORBARS and LOWERERRORBARS must each be a table with factors that match that of TABLE or, if XERRORBARS is set, they must match the structure of XERRORBARS.
The colour, line style, line thickness, and cap width of the error bars is controlled by the definition of the pens specified by the PENERRORBARS parameter. If PENERRORBARS is not set, or there is an error with the PENERRORBARS setting, a default of PENERRORBARS=1 is used. The settings of the pen used for plotting the error bars are COLOUR (or CLINE), LINESTYLE, BARTHICKNESS, and BARCAPWIDTH, with the exception that when YERRORBARS is set, any SYMBOL and LABELS (and related) settings from the pen are used also. The YERRORBARS parameter is not necessary for the plotting of the actual error bars, but instead is used to specify a y-axis coordinate for a symbol or label to be associated with each error bar. The symbol and any label text associated with PENERRORBARS will be plotted at the (x, y) position given by (XERRORBARS, YERRORBARS). If YERRORBARS is not set, no symbols or labels are plotted regardless of the PEN settings given by PENERRORBARS.
The options of the procedure mainly control the plotting: the windows that are used for the plot (WINDOW) and for the key (KEYWINDOW), titles for the graph (TITLE) and for the key (KEYDESCRIPTION), whether the groups of bars are appended or placed side-by-side (APPEND), whether or not to clear the screen before plotting (SCREEN), and the proportion of x-axis space allocated to bars (BARCOVERING). Normally values in TABLE less than ORIGIN are omitted but, if you set BELOWORIGIN=include, bars will be drawn for these values extending below the x-axis. In that case, the x-axis will be placed at the bottom of the y-axis (XPOSITION=lower) but the axis can be placed at the origin if you set XPOSITION=origin. 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.
The default is to plot all TABLE factor levels. However, any levels that contain only missing values can be excluded from the plot by setting option OMITEMPTYLEVELS=yes.
Unless you have set them previously by using YAXIS, the y-axis limits will be set to accommodate the error bars but with the following limitation: the axis lower limit will not be lowered below the origin (even if BELOWORIGIN=include) unless at least one of the bar-chart bars is also below the origin (this is a limitation of DHISTOGRAM). The x-axis limits are automatically set to include all of the bar-chart bars with a margin of 5% at each end of the x-axis. The amount of space at the end of the x-axis (default: 5% of x-axis data range) can be set using the MLOWER% and MUPPER% settings of XAXIS before using DBARCHART. The x-axis limits are not adjusted for the x-axis placement of error bars, so any error bars given an XERRORBARS value outside the default x-axis limits will not be plotted unless the limits are increased by using XAXIS before using DBARCHART. However, if any previously specified x-axis limits are too narrow for the plotting of the bar-chart bars, the limits will be increased to fit the bars.
Options: TITLE, WINDOW, KEYWINDOW, LABELS, APPEND, SCREEN, KEYDESCRIPTION, YSCALE, BELOWORIGIN, ORIENTATION, BARCOVERING, XPOSITION, OMITEMPTYLEVELS.
Parameters: TABLE, ORIGIN, PEN, DESCRIPTION, YMARKS, XFACTOR, LOWERERRORBARS, UPPERERRORBARS, YERRORBARS, XERRORBARS, PENERRORBARS.
Method
If YSCALE is set, the expression is used to transform TABLE and ORIGIN. Any YMARKS are also transformed to find the position of the tick-marks. TABLE is then rescaled so that the ORIGIN is zero. The y-axis is set up with the labelling on the original scale of TABLE. Two-way tables are first split into one-way tables classified by the second factor of TABLE. One sub-table is produced for each level of the first factor of TABLE. The chart is then produced with a single DHISTOGRAM statement for all sub-tables. YSCALE is imported into the program by setting Y or X as a dummy, and printing the expression into a text. A new expression is then set up using this text with the EXECUTE directive. Y (or X) is then set to ORIGIN, TABLE and YMARKS in turn before the expression is calculated. When error bars are given, the UPPERERRORBARS, LOWERERRORBARS and YERRORBARS values are scaled, if necessary,using YSCALE. Then, the error bars are plotted on top of the bar chart by using DGRAPH with the same FRAME, XAXIS and YAXIS settings as used for the bar chart. When there are bar-chart values to be plotted below the origin (BELOWORIGIN=include) and XPOSITION=lower, the bar chart is first drawn without an x-axis, then an x-axis is plotted separately at the lower end of the y-axis, and finally, by using DGRAPH, a plain line is drawn parallel to the x-axis at the origin.
See also
Directives: BARCHART, HISTOGRAM, LPHISTOGRAM.
Commands for: Graphics.
Example
CAPTION 'DBARCHART example',!t(\
'A herbicide was applied with two different nozzles angled',\
'in three directions. The mean deposit was measured.');\
STYLE=meta,plain
FACTOR [LABELS=!t('11001','11004')] Nozzle
FACTOR [LABELS=!t(forward,vertical,backward)] Direction
TABLE [CLASS=Direction,Nozzle;\
VALUES=668.9,768.5,695.6,572.1,848.4,785.8] Deposit
DBARCHART [TITLE='Herbicide Deposit'] Deposit; XF=Nozzle
DBARCHART [YSCALE=!e(log(X))] Deposit; ORIGIN=400;\
DESCRIPTION=!t('Standard','Wide')
TABLE [CLASS=Direction,Nozzle;\
VALUES=100.3,115.3,104.3,85.8,127.3,117.9] SEM
CALCULATE eupper = Deposit + SEM
DBARCHART [title='Herbicide Deposit'; KEYDESCRIPTION='Nozzle Type']\
Deposit; UPPERERRORBARS=eupper
PEN 5; COLOUR='black'; SYMBOL=0; LABEL='5% LSD'; YLPOSITION=centre;\
XLPOSITION=right; XLOFFSET=1
DBARCHART [title='Herbicide Deposit'; KEYDESCRIPTION='Nozzle Type']\
Deposit; XERRORBARS=0.7; YERRORBARS=850; UPPERERRORBARS=900;\
LOWERERRORBARS=800; PENERRORBARS=5