|
|
Docs: bargraf
Bargraf (E1) utilizes the standard ERPSS graphics user interface and standard graphics commands, as described in the Multiplot User's Manual. Bargraf is a program which plots a bar graph on a display device according to formatting specifications and data which are acquired from an input file. This file is normally created with a text editor such as vi (1), and contains a set of commands that describe the data and the appearance of the graph. It is possible to specify labels and legends to aid in the interpretation of the graph, and to set arbitrary margins on all four sides, although there are defaults which will be automatically employed if these optional parameter specifications do not appear in the input file.
Bargraf is invoked as:
Bargraf is really quite easy to use, but the formal explication of the contents of a data/formatting file is somewhat complex. It is therefore best to look at an example of a data/formatting file and the plot that it generates in order to learn how to use bargraf. In fact, imitation of this example is by far the fastest way to begin using bargraf. The graph generated by the data/formatting file for this example is shown in Figure 1. Here are the verbatim contents of the file which produced the graph in Figure 1.
group *Fido complex textsize=6 thin
bar 4.0:0.4 fill=3
bar -5.0:0.9 fill=1
bar -7.3:1.3 fill=2
bar -8.3 fill=17
group *Kula complex textsize=6 thin
bar -4.3 fill=3
bar 7.3 fill=1
bar 3.1 fill=2
bar 6.1 fill=17
group "\\(dgChew Biz" complex textsize=6 medium
bar 6.2 fill=3
bar 8.1 fill=1
bar 9.3 fill=2
bar 23.6 fill=17
ylabel kilos/year complex textsize=7 thin
xlabel "*--Dry \\(dg--Can" complex textsize=4 thin
header "Weight Increase" complex textsize=9 medium
header "(German Shepherds Only)" italics textsize=5 thin
legend 1983 fill=3 complex textsize=5 thin
legend 1984 fill=1 complex textsize=5 thin
legend 1985 fill=2 complex textsize=5 thin
legend "\\(cs('83-'85)" fill=17 italics textsize=5 thin
ytickstyle format=2.1 complex textsize=4
ymax 25.0
ymin -10.0
draw
coord screen
text .1 .03 "Figure 1." complex textsize=4
While some of the specific arguments may be unclear, the basic format and
manner in which bargraf works should be apparent from this example.
The remainder of this document simply explains all the possibilities,
limitations, and default values for the various statements which comprise a
data/formatting file.
All the data to be graphed as well as parameters controlling the appearance of the plot must be formatted according to the standard ERPSS command conventions, which are described in the Multiplot User's Manual. Many of the bargraf commands use standard options (e.g., "thick", "color=") that are also described in plotcmd (E3p), and which will be abbreviated here as "line_opts" (line style options), "text_opts" (text style options), and "trans_opts" (transformation options).
There are few restrictions on the format of the data/format file, except that there must be at least one group and one bar statement, and that all group and bar specifications must precede any additional commands. The syntax of the group and bar statements is related to the implicit nature of the plots produced by bargraf. Often one wishes to depict data from a number of levels of experimental factors or variables as individual bars, and this is done by using a bar statement and its associated data and parameters for each data value corresponding to each level of that factor. It is often desired, however, to display data along one factor dimension at various levels of another experimental variable or factor; this is the purpose of the group statements. The data/formatting file must start with a group statement and its label, which will be plotted under the group of bars whose specifications follow that group statement in the file. If more than one group of bars is desired, another group statement and its associated bar statements should follow the last bar statement of the previous group statement. There is a maximum of 20 groups, and 100 bars per group. Groups of bars will be separated by more space than bars within each group in the plot. While the design of bargraf (E1) implicitly assumed that the bars in different groups would have similar fill types and represent data corresponding to similar levels of an experimental factor, this is not checked nor enforced in any way by bargraf, thus allowing arbitrary graphs to be generated. See the explication of the legend command below for further information on this point.
Once all group and bar statements are complete at the beginning of the data/formatting file, one may include any of the other commands.
group "label" [text_opts]
This command simply defines a group and gives it a label that will be printed under the bars for that group. The data defined in a bar command will be assigned to the group defined in the immediately preceding group command.
bar value[:error] [text_opts] [fill=###]
This command defines the values that should be used to create a particular bar within the current group. The value parameter determines the height of the bar. A colon and another value can be appended onto this value to define a standard error bar. The fill=### option specifies the fill pattern that will be used for the bar (-1 is the default fill pattern, which produces an unfilled bar). The program showpatterns (E8) can be used to show the available fill patterns.
legend "label" [text_opts] [fill=###]
To bargraf, legends refer to descriptions of the individual bars in the various groups. Usually one includes a legend statement for each type of bar in the group/bar section, using corresponding values for the fill type. This causes a small segment of a bar with a specified fill type along with its label to be plotted near the top of the page, above the graph.
Since the type of plot produced by bargraf implies that the bars in one group represent similar data as do the bars in other groups (if present), the legend statements are separate from the group/bar statements. In other words, the group/bar categorization corresponds to the format of data one might collect from completely crossed, factorial experimental design. Hence the bars in different groups represent the same levels of one factor while the other factor varies (corresponding to the various groups). For example, if there are two groups with three bars per group, one usually will include only three legend statements. While this describes the expected use and design of bargraf, there is no implicit relation between the bars and legends as far as bargraf is concerned; it is up to the user to ensure that the correspondence is faithful.
barwidth value
Unless one includes a barwidth statement in the data/formatting file, bargraf automatically calculates a reasonable width for the bars which are to be plotted. Since these will be quite wide if one has but two or three bars on a particular graph, this statement allows specification of thinner bars than would be calculated by default. The decimal value which needs to be supplied as the argument in the barwidth statement is a fraction of the total width of the plot. Hence, if the SPARCprinter E is being used in "portrait" mode (psprne), the printing region is 8 by 10 inches, and supplying a .10 as the argument will cause bargraf to generate bars that are .8 inches in width, regardless of how many bars and/or groups are specified.
barspace value
As it is with barwidths, so it shall be for barspacings. Unless this statement is included as an option in the input to bargraf, the inter-bar spacings will be automatically set to the width of a bar. This statement allows tailoring the inter-bar spacings to any desired value (within reason). As with the barwidth command, the argument to the barspace command is the decimal fraction of the total width of the plot. Hence to get a bar spacing of zero, enter a .0001 or so.
title string [text_opts] or header string [text_opts]
xtitle string [text_opts] or xlabel string [text_opts]
ytitle string [text_opts] or ylabel string [text_opts]
These commands plot titles for the entire graph, the x-axis or the y-axis (to retain some backwards compatibility, two equivalent names are provided for this set of three functional commands). The entire graph can be given several titles, which are plotted on consecutive lines, but the x and y axes may have only one title each.
gridstyle [line_opts]
This command is used to determine the line style values that will be used to draw the grid on which the bars are drawn.
ymin value
ymax value
These commands allow the user to specify the minimum and maximum values for the y axis. By default, bargraf uses values derived from the minimum and maximum values in the data.
lmargin value
tmargin value
rmargin value
bmargin value
These commands are used to control the size of the overall graph, and specify blank margins at the left, top, right, and bottom sides of the graph, respectively. The margins are specified as proportions of the width of the screen (e.g., .20 for 20% of the width).
nyticks value
These commands specify the number of ticks that should be used on the y axis.
ytickstyle [text_opts] [format=fw.prec]
These commands control the style of the numbers that are plotted at each tick on the y axis. The fw portion of the format= option specifies the total number of characters printed for each number (the field width), and the prec portion specifies the number of digits to the right of the decimal point (the precision). For C buffs, the fw.prec string is used in a printf floating point format string between the '%' character and the 'f' character (e.g., format=3.2 would result in a printf format of "%3.2f").
draw
coord screen/graph
The draw command causes the graph specified by the preceding format commands to be drawn. If this command is not specified, the graph is simply drawn after the entire format file has been processed. The only reason for the existence of this command is that the graph must be drawn before the coord command can be used. The coord command controls whether the coordinate system used to specify locations for various commands is the usual screen system (0.0 to 1.0 for the x axis and 0.0 to 0.75 for the y axis in landscape mode or 0.0 to 1.33 for the y axis in portrait mode), or the graph system (which uses the values of the graph's x and y axes to determine the placement of objects). Once the graph has been drawn, it is possible to go back and forth between the screen and graph systems.
readfile filename [trans_opts] or rf filename [trans_opts]
These commands cause bargraf to read the format commands located in the file named filename, using the translation, rotation, and scaling options.
In addition to the commands listed above, all of the standard graphics commands that are available for multiplot (E1) are also available for bargraf (E1).
group "label" [text_opts] (Mandatory) bar value[:error] [line_opts] [fill=###] (Mandatory) legend "label" [text_opts] [fill=###] title string [text_opts] header string [text_opts] xtitle string [text_opts] xlabel string [text_opts] ytitle string [text_opts] ylabel string [text_opts] ymin value ymax value nyticks value ytickstyle [text_opts] [format=fw.prec] barwidth value barspace value lmargin value tmargin value rmargin value bmargin value gridstyle [line_opts] draw coord screen/graph readfile filename [trans_opts] rf filename [trans_opts]
linestyle [line_opts] gridstyle [line_opts] textstyle [line and text_opts] point x y [line_opts] line x1 y1 x2 y2 [line_opts] moveto x y lineto x y [line_opts] arrow x1 y1 x2 y2 length angle [line_options] arc mid_x mid_y radius start_degrees stop_degrees [line_opts] rect left top right bottom [line_opts fill=value] startpgon endpgon drawpgon x y [line_opts fill=value] text x y "string" [line and text_opts] translate [trans_opts] trans [trans_opts] vfile filename [trans_opts]