FEATURES

EXAMPLES

sa1.p

PREREQUISITES

MODES

by name using the areaname attribute;

by specifying a rectangle (two points) using the rectangle attribute;

by specifying plotting area size using the box attribute and the location using the location attribute.

VARIABLES THAT ARE SET

MANDATORY ATTRIBUTES

If nothing else is specified, default behaviour is for the standard plotting area to be used, with linear scaling in x and y.

ATTRIBUTES

Location & size of the plotting rectangle

areaname name

Allows a plotting area to be defined by selecting a predefined rectangle by name. These are most useful when generating plots on standard paper. Example: areaname: 2hi
Available names include:

Name    	Description
--------	------------------------------
standard	the default
square		a square area
whole   	as much of the page as possible
2hi, 2lo	for two plots on a page, one above the other
2left, 2right	for two plots on a page, side by side
3hi, 3mid, 3lo	for three plots on a page
4ne, 4nw, 4se, 4sw	for four plots on a page (ne = northeast)
slide   	works well with slides generation
lifetab  	works well for life tables

rectangle x1 y1 x2 y2

Allows a plotting area to be defined by giving two points: (x1,y1) is the lower left corner and (x2,y2) is the upper right corner (both are in absolute units ).
Example: rectangle: 1.4 4 7.4 8

box width height

Allows a plotting area to be defined by giving width and height in absolute units . A location attribute should also be given to specify where to place the box. Example: box: 1.4 4

location x y

Used with the box attribute. Defines the location of the lower-left corner of the plotting area.

autowidth f [ minallowablesize maxallowablesize ]

Allows the width of the plotting area to be driven by the data range in X. For example, you would probably want to display 8 categories using a smaller plot area than 48 categories. autowidth allows this to be done automatically, driven by the data. You must fully specify the plotting area using rectangle or some other attribute(s), and specify the scaling in X. This attribute then revises the width of the plotting area by setting it to f times the number of basic units in the range of X, in absolute units. You can optionally set a minallowablesize and a maxallowablesize (both in absolute units) that the plot will never be smaller than, or larger than, respectively. For example:

   #proc areadef
      rectangle: 1 1 6 3
      xcategories: datafield=2
      autowidth: 0.3  3.0  8.0

For example, if there are 12 categories represented in your data, 12 x 0.3 = 3.6, so the resulting plotting area would be 3.6 inches wide. If there are 20 categories, 20 x 0.3 = 6.0, and the resulting plotting area would be 6.0 inches wide. If there are only six categories, the resulting plot would have been 1.8 inches wide, however a minimum allowable size of 3.0 inches was specified, so the plot will be 3 inches wide. If there are 40 categories, the resulting plot would have been 12 inches wide, however a maximum allowable size of 8.0 inches was specified, so the plot will be 8 inches wide.

Remember that with date and datetime scaling the basic unit is the day, and with time scaling the basic unit is the minute.

autoheight f

Allows the height of the plotting area to be determined by the data range in Y. See autowidth.

Scaling method & range in X and Y

xscaletype type [ format ]

Defines the type of scaling for the X axis. Default is linear. Other possible types include: log, log+1, categories, date, time, and datetime. The format parameter may be given when xscaletype is date, time, or datetime to set the default notation. See scaleunits for discussion of the various scale types and units, and the gallery scale & axis examples. There are a few additional proc areadef attributes for working with categories.
Example: xscaletype: date yymm
Example: xscaletype: datetime mm/dd/yyyy.hh:mm

yscaletype type [ format ]

Defines the type of scaling for the Y axis. Same syntax as xscaletype above. Default is linear.

xrange min max

Defines the plottable range in x. min and max must both be given, and must both be plottable values for the scaletype to be used. (To set the range automatically based on a data field, use xautorange; not used when xscaletype is categories.) If log scaling is being used, 0.0 may not given as the minima (but a very small value like 0.01 is ok). If date, time, log, categories, or other special type of scaling is to be done, see also xscaletype.
Example: if your data ranges in x between 1.5 and 23.5 you might use: xrange: 0 24

xautorange datafield=dfields .. other subattributes..

Scan the datafield(s) given in dfields to automatically find minima and maxima, and set the X range accordingly. (To set the range explicitly, use xrange.) This attribute has its own manual page.

yrange min max

Defines the plottable range in y. Same as xrange above. If date, time, log, categories, or other special type of scaling is to be done, see also yscaletype.
Example: if your data ranges in y between 4 and 78.3 you might use: yrange: 0 100

yautorange datafield=dfield .. other subattributes..

Scan the datafield(s) given in dfields to automatically find minima and maxima, and set the Y range accordingly. (To set the range explicitly, use yrange.) This attribute has its own manual page.

Setting up categories

xcategories datafield=dfield [selectrows=conditional expression]
..OR..
xcategories multi-line text

Defines a set of categories for use on the X axis. To take categories from a data field, use the construct datafield=dfield where dfield is a data field specification. Or, category names may be listed explicitly one per line, terminating with a blank line. An optional conditional expression may be supplied if taking categories from data field, to use selected data rows only (new in 2.03.. see example 2 below).

Example 1:   xcategories: datafield=1

Example 2:   xcategories: datafield=1  selectrows=@3 like S*

Example 3:   xcategories: Red
   			  Blue
   			  Green

ycategories datafield=dfield [selectrows=conditional expression]
..OR..
ycategories multi-line text

Specify categories for use in Y, one per line. Same syntax as xcategories above. Default orientation of categories along Y is from top to bottom.

xextracategory text

Allows an extra X axis category to be added explicitly. For example, this attribute might be useful when categories are being set by a data field and it is desired to have an additional "Total" category. Unlike most other ploticus attributes, its behavior is position-dependent, and it may be specified more than once. If specified before (above) xcategories in the proc areadef attributes, the extra category will be added to the beginning of the category list and it will appear near the X axis min. If specified after, the extra category will be appended to the category list and appear near the X max. This attribute may be specified one or more times, with each adding a category.

Example: 	xextracategory: Total
		xextracategory: Weekly average

yextracategory text

Same as xextracategory above, but for the Y axis.

catcompmethod beginswith | exact | length=N

Control the details of how category comparisons are done. The default is beginswith for backward compatibility; exact is highly recommeded for new work. In all cases, the comparisons are case-insensitive, and work from the beginning of the categories list to the end, stopping when a match is found.

beginswith = the comparison is successful if the data item matches the category name but only to the length of the data item.

exact = the comparison is successful if the data item exactly matches the category name.

length=N = the comparison is successful if the first N characters of the data item match the first N characters of the category name.

fuzzy=D = a "fuzzy match" algorithm is applied to do the comparison. D controls the degree of strictness: 5 = strict, 4 = medium-strict, 3 = medium 2= loose, 1 = very loose. With fuzzy matching an asterisk (*) at beginning or end of data item will be interpreted as a wild card.

Note: There is a minor issue when cloning an areadef where categories are used. Categories attributes cannot be "turned off" when cloning. If categories are used in an areadef and then that areadef is cloned, the categories will be active in the clone, and cannot be suppressed.

Axis generation

xaxis.*

proc axis attributes for the x axis. Any proc xaxis attributes may be used from within proc areadef as a convenience, by prefixing the name with xaxis.. See proc axis

yaxis.*

proc yaxis options for the y axis. Any proc yaxis attributes may be used from within proc areadef as a convenience, by prefixing the name with yaxis.. See proc axis

axisline, tic*, minortic*

These proc xaxis/yaxis attributes may be defined within proc areadef to control both axes. See proc axis

Other attributes of the plotting area

areacolor color

Causes the area background to be filled with color. Example: areacolor: yellow

frame linedetails | no | yes | bevel

Specifies a box or frame around the plotting area. Options are: no (no frame), yes (do a default line frame), bevel for a beveled gray frame, or a line detail specification, which results in a frame made of lines with the given characteristics (A bevel frame will probably clash with tics and stubs unless these are positioned inward.)
Example 1: frame: none
Example 2: frame: color=red width=4.0
Example 3: frame: bevel

linebottom linedetails

Specifies a line to be drawn along the bottom edge of the plotting area. This is just a line, not an X axis.
Example: linebottom: yes
Example: linebottom: none
Example: linebottom: width=0.5 color=green

lineside linedetails

Same as linebottom but specifies a line to be drawn along the left side. This is just a line, not a Y axis.

title text

Specifies a plot title (not a page title). Plot title will appear above the upper left corner of the plotting area by default.
Example: title: Subgroup 24-C

titledetails textdetails

Text details for the plot title.
Example: titledetails: align=R size=9 style=I

title2 text

Allows a second title to be specified. May be useful to create a plot header on both left and right.

title2details textdetails

Text details for the second plot title.

clickmapurl url template

If a clickmap is being generated, and the plotting area is being mapped as a grid, this attribute must be specified to supply a URL template, into which @@XVAL and/or @@YVAL will be substituted. See the clickmap page for more details and examples.

Example: clickmapurl: http://abc.com/cgi-bin/details?x=@@XVAL&y=@@YVAL