Table of contents

NAME

piecht - pie chart program from <PLOT79> package

SYNOPSIS

piecht* where the final character in the command name is drawn from the list [1, 3, 4, 9, b, e, h, i, j, k, m, o, p, r, s, t, v, w, x] and indicates the desired output device (t for the Tektronix 4014 in the default Sun installation: see plot79(1L) manual page for complete list)

DESCRIPTION

Piecht is a FORTRAN program which is supplied with the <PLOT79> scientific line graphics package, which creates simple pie charts. Input is taken from the standard input, and a run-time log is written to the standard output. The plottable output is sent to a file named by the CRT environment variable, or to CRT.num if CRT is undefined (num is a number which begins at 1 and is incremented appropriately to prevent files being overwritten). The device for which output is intended depends upon which device library was linked to the program at the time of installation (Tektronix 4014 for the default Sun installation).

FORMAT OF THE INPUT FILE

Any string starting in column 1 must be a command keyword. Command keywords may be abbreviated if desired as long as as the abbreviation is unique. At present, the first 2 characters are sufficient, but to provide for introduction of new parameters in later versions, at least 3 should be used. The commands are described in the section entitled "DETAILED INSTRUCTIONS" below.

Data items may be separated by white space (blanks and/or tabs) or commas. Numeric values can be specified in integer or floating-point form. Any necessary type conversion will occur automatically.

Character strings should normally be surrounded by quotes, with the usual convention that a quote inside the string is represented by two successive quotes. The quote character may be either a single quote or a double quote, but its use must be consistent within a single string. If the string consists of a single word, the surrounding quotes may be optionally omitted. Upper- and lower-case letters are equivalent in keywords, but distinct in strings.

Only the first 72 characters of input lines are examined, so that columns 73-80 can contain sequencing information. Blank lines can be inserted anywhere to increase readability.

Records are printed in the log file, prefixed with the record number, as they are read from the input stream. When an invalid command or input token is encountered, an error message is issued describing the problem, followed by a copy of the current input record and the value of the current column position. Then the remainder of the current input record is discarded. The input stream is flushed until a command line is found, and processing continues normally. An attempt is always made to plot the input data, even though the data may be invalid or incomplete. Plotting is only suppressed if the total of the data values is zero, since this does not allow definition of segment sizes.

Information also appears in the PLOT79 section of the rdinfo(1L) program,

EXAMPLE

Here is an example of a command file: 

TITLE "<<PLOT79>> Installations by Country"  "[30-Mar-82]"
DATA
     Austria         1
     Australia       3
     Belgium         1
     Brazil          1
     Britain         2
     Canada          3
     Denmark         1
     Eire            1
     France          1
     India           2
     Japan           1
     Mexico          2
     Sweden          6
     USA             49
PERCENT
VALUE
SCALE 0.8
DISPLAY

EXPLODE 0.05
DISPLAY

FILES

/usr/local/plot79/piecht.f
source code
/usr/local/plot79/piecht*
executable file (piechtt on the default Sun installation)
/usr/local/plot79/define
various environment definitions, an appropriate subset of which should be placed in the user's .cshrc or .profile file

SEE ALSO

drawit(1L), graph(1L), graph3(1L), linestyle(1L), markstyle(1L), plot79.intro(1L), plot79(1L), plottips(1L), plotfont(1L), pluto(1L), polyfill(1L), rdinfo(1L), slides(1L), tekalw(1L), tkvecs(1L), world(1L)

AUTHOR

Nelson H. F. Beebe, Ph.D.

Center for Scientific Computing

South Physics Building

University of Utah

Salt Lake City, UT 84112

Tel: (801) 581-5254

(Manual page by R. P. C. Rodgers, Computer Applications in Laboratory Medicine Project, UCSF, San Francisco, CA 94143).

DETAILED INSTRUCTIONS

The following commands are supported:
CENTER x y
Place the pie chart center at position (x,y) on the unit square. The default position is (0.50,0.41), which leaves additional space in the top margin for labelling.
CHECK
Check the input data, but suppress plotting. This option is useful when large numbers of charts are to be made and/or plotting turnaround is slow.
* text or COMMENT text
This command has no effect on processing, and is included only so that input data files can contain descriptive information which is not relevant to the program. The text on the remainder of the line is ignored, but the line will be printed as usual by the input reader.
DATA 'string1' value1 'string2' value2 ... (1 to 25 pairs)
or
DATA value1 value2 .... (1 to 25 values)
Provide labels and data values for the pie segments (format 1), or only data values (format 2). In the first case, the strings and numeric values will normally alternate, but it is not essential that this be so, since they are readily distinguished. The only important consideration is that the same number of strings and numbers be present. In the second case, labels are assumed to have been provided by the LEGEND command. This is useful if multiple charts are to be generated from the same legends and different data values. Numeric values are converted to internal form for computation of the pie segment sizes, but the user-specified strings are preserved for display in the legend boxes in response to a VALUE command (see below). Generally, one should order the numeric values to avoid adjacent small values, since this may not permit enough space for the legends. The SCALE command below gives a certain amount of control over this.
DISPLAY
Display the pie chart for the input data. If the CHECK option is not in effect, an implicit DISPLAY command is automatically issued on reaching an EXIT or QUIT command, or end-of-file on the input stream, if one has not been provided.
EXIT
Terminate execution, the same as if end-of-file had occurred on input.
EXPLODE value index1 index2 ...
Move the pie segments out from the origin by a fraction of the radius given by value in order to produce an exploded pie chart. A suggested size for value is 0.05. If no pie segment indices are specified, the explosion factor applies to all pie segments. Otherwise, it applies only to the segments with the given indices. Explosion factors for other segments are left intact, so that one can obtain different factors for different segments by specifying multiple EXPLODE commands.
FILL-INDEX index1 index2 ... (1 to 25 integer values)
Select the pie segment fill indices. An index value less than or equal to 0 gives no filling, and values 1-84 give progressively darker filling patterns. Values larger than 84 encode user-defined patterns (see the manual page polyfill(1L)). The default fill index is k for the k-th pie segment. If fewer fill indices are specified than there are pie segments, the list is used cyclically.
FONT fontname switchcharacter
Select the symbol font to be used for labelling. Fontname may be any one of the 144 font identifiers in the <PLOT79> system (see the manual page plotfont(1L)). The default is UCCR1 (Complex Roman). The optional second parameter, switchcharacter, is a single character which can be used in a text string to switch to this font. If omitted, or blank, no switch to this font is possible. Multiple FONT commands can be used to select up to 5 fonts, the most recently selected one being the current font. If more than five fonts are requested, the font name table is overwritten cyclically, so that the sixth replaces the first, the seventh replaces the second, and so on. By default, the characters "<" and ">" in text strings switch to upper- and lower-case respectively; if they are to be used as themselves, they must be doubled.
? topicname
or
HELP topicname
This command should be issued only if the input and output files are directed to the user's terminal. It writes a description of the subject topicname to the output file. Topicname may be an abbreviation of an actual command name. Typing a query (?) or a blank for topicname will display a list of all the topics for which HELP is available, and then the user will be prompted to enter a topic. If topicname is prefixed by an asterisk, then all topics which anywhere contain the characters following the asterisk will be displayed.
LEGEND string1 string2 ... (1 to 25 strings)
Provide labels for each of the pie segments.
PEN pen1 pen2 ... (1 to 25 integer values)
Set the pen number for subsequent plotting of pie segments. Labelling is always drawn with pen number 1 (generally black), but the pen used for each pie segment can be specified with this command. If fewer pen numbers are specified than there are pie segments, the list is used cyclically. For example, on a 2-pen plotter "PEN 1 2" could be used to alternate the pens on adjacent pie segments.
PERCENT
Display percentage of total under each segment label.
QUIT
Terminate execution, the same as if end-of-file had occurred on input.
RESET parametername parametername ...
If parametername (= ALL, CENTER, DATA, EXPLODE, FILL-INDEX, FONT, LEGEND, PEN, PERCENT, SCALE, SIZE, TITLE, VALUE) is omitted, reset all parameters to their original uninitialized or default state. If this option is not specified, parameters are unchanged unless they are specifically given in the input. If one or more parameternames are given, only the requested parameters are reset. A "RESET ALL" command is equivalent to a RESET. An explicit "RESET CHECK" command is the only way to rescind a CHECK command. It should seldom be required, since the intent of the CHECK command is to prevent plotting.
SCALE value
Scale the pie segment radius by multiplying it by value. This option is useful if there are so many small segments that legends must be moved into the margin and fall outside the viewport.
SIZE value unit
Define the size of the plot unit square to be value. The unit keyword may be INCHES or CENTIMETERS or CM, and if omitted, defaults to CM.
TITLE string1 string2 ... (1 to 5 strings)
Provide titles used to label the chart.
VALUE
Display actual value under each segment label. If both percent and value are requested, percent is displayed last.