Previous: karrtn Up: ../plot79.html Next: plot
The following description of the <PLOT79> pie chart facility is
extracted from the source code. It is expected that many extensions
will be made to this system in response to user requirements, and
suggestions will be gratefully received [send mail to BEEBE, or phone
Nelson Beebe at 581-5254]. At present, only one plot device - the
Printronix printers - will be supported by the version on the system,
but other devices can be trivially added. To use the system on the
College of Science DECSYSTEM-20, simply type
@PIECHT inputfile,outputfile,plotfile
Default file extensions are ".DAT", ".LST", and ".PLT" respectively,
and file names are also defaulted so that in most cases, only a single
name is required on the command line (use @HELP FORTIO for more
information).
----source code comments follow----
This routine provides for free-form input of data for the production of
pie charts. Input is keyword-directed, with the convention that
keywords are recognized because they start in column 1. Operands and
data values may not start in column 1. Only the first 72 characters of
input lines are examined, so that columns 73..80 can contain sequencing
information on card-oriented systems.
Command keywords may be abbreviated if desired as long as as the
abbreviation is unique. At present, the first 3 characters are
sufficient.
Data items may be separated by white space (blanks and/or tabs) or
commas, and blank lines can be inserted anywhere to increase
readability.
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.
Records are printed, prefixed with the record number, as they are read
from the input stream.
The action taken when an invalid command or invalid input token is
encountered is to issue an error message describing the problem,
followed by a copy of the current input record and the value of the
current column position, then to discard the remainder of the current
input record. The input stream is then 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.
The following options are supported:
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.
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.
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 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.
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.
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 the pie chart for the input data. If the "CHECK" option is not in effect, an implicit "DISPLAY" command is automatically issued on reaching end of file on the input stream, or on finding an "EXIT" or "QUIT" command, if one has not been provided.
Terminate execution, the same as if end-of-file had occurred on input.
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.
Select the pie segment fill indices. An index value less than or equal
to 0 gives no filling, values 1..84 give progressively darker filling
patterns, and larger values select user-definable patterns. The
default fill index is k for the k-th pie segment.
For fill indices larger than 84, the pattern filling line spacings are
specified by the digits of the fill index. The digits taken from left
to right represent the spacing between adjacent lines of the pattern,
measured in steps of 0.002 unit in normalized device coordinate (NDC)
space. When the digits are exhausted, the pattern is repeated
cyclically. Thus, the digits in the fill index 631 represent the
parallel lines with NDC spacings 0.012, 0.006, 0.002, 0.012, 0.006,
0.002, etc. Zero digits in the fill index represent zero spacing, and
are therefore ignored. They are nevertheless useful for defining
patterns whose indices would otherwise conflict with the built-in fill
indices. Odd fill indices give cross-hatched patterns.
Fill index 0 corresponds to no pie segment filling. The other built-in
fill indices 1..84 are constructed by repeating the twelve basic
patterns in the following table seven times, each time halving the line
spacing parameter, d, of the previous group. The value of d for the
first group of twelve is 0.032, so that the closest lines in fill
indices 79..84 (which have spacing d/64, d/128) are 0.00025 NDC unit
apart. On typical raster CRT displays, with resolutions of 512 to 4096
scan lines, this is equal to or smaller than one pixel in width, giving
solid filling. Because coordinate roundoff to pixel boundaries can
result in blank raster lines or missed pixels in a tight shading
pattern, it is desirable to choose a line spacing which is about half
the raster spacing in order to get solid filling.
Fill Index Spacing Angle Hatch
============= ======= ===== =====
1 d 0 No
2 d 45 No
3 d 90 No
4 d 135 No
5 d 0 Yes
6 d 45 Yes
7 d,d/2 0 No
8 d,d/2 45 No
9 d,d/2 90 No
10 d,d/2 135 No
11 d,d/2 0 Yes
12 d,d/2 45 Yes
============= ======= ===== =====
Select the symbol font to be used for labelling. 'fontname' may be any
one of the 144 font identifiers in the <PLOT79> system. 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 from another font.
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. The principal fonts currently available are as
follows (the parenthesized number following each name is the grid
size):
UCKR1 - Cartographic Roman (9)
UCKG1 - Cartographic Greek (9)
UCIR1 - Indexical Roman (13)
UCII1 - Indexical Roman Italic (13)
UCIG1 - Indexical Greek (13)
UCSR1 - Simplex Roman (21)
UCSS1 - Simplex Roman Script (21)
UCSG1 - Simplex Greek (21)
UCCR1 - Complex Normal Roman (21)
UCCI1 - Complex Normal Roman Italic (21)
UCCG1 - Complex Normal Greek (21)
UCCS1 - Complex Script (21)
UCDR1 - Duplex Roman (21)
UCTR1 - Triplex Roman (21)
UCGE1 - Gothic English (21)
UCGI1 - Gothic Italian (21)
UCGG1 - Gothic German (21)
UCCC1 - Complex Cyrillic (21)
UCSA1 - Simplex ASCII (11)
UCBA1 - Block ASCII (11)
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.
Provide labels for each of the pie segments.
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.
Display percentage of total under each segment label.
Terminate execution, the same as if end-of-file had occurred on input.
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 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.
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.
Provide titles used to label the chart.
Display actual value under each segment label. If both percent and value are requested, percent is displayed last.
Example 1:
----------
TITLE 'Sample Pie Chart Display' "Superb Fruit Company Production"
"(kg in 1980)"
LEGEND 'Apples' 'Pears','Oranges'
DATA 20000,60000,15000
PERCENT
display
FONT UCTR1
SIZE 30 cm
EXPLODE 0.05
VALUE
DISPLAY
Example 2:
----------
TITLE "<<PLOT79>> Installations by Country" "[03-Mar-81]"
DATA USA 29
Canada 3
Britain 2
Australia 2
Mexico 2
Sweden 3
Denmark 1
Japan 1
Belgium 1
PERCENT
VALUE
SCALE 0.8
DISPLAY
EXPLODE 0.05
DISPLAY