|
Manual page for proc_areadef(PL)
proc areadef is used to define the size, location, and scaling in X and Y
of the rectangle within which a subsequent plot will be rendered.
This rectangle is referred to as the plotting area.
proc areadef may be used any number of times within the same script
to do multiple plots per page, to produce multiple page results, or to
overlay different scales or units on the same plot.
FEATURES
Various scaling types, including linear, log, date, and time are available
for X and Y.
Automatic scaling based on data content may be done using
xautorange and yautorange.
Axes may be specified within proc areadef
or individually later using proc xaxis or proc yaxis.
If specified here, the various proc axis attributes should be
prefixed with xaxis. or yaxis..
EXAMPLES
sa1.p
Almost all of the examples in the gallery use
proc areadef in various ways.
PREREQUISITES
None.
MODES
The size and location of the plotting area
on a page (the plotting area) may be specified in one
of these three ways:
- 1.
-
by name using the areaname attribute;
- 2.
-
by specifying a rectangle (two points) using the rectangle attribute;
- 3.
-
by specifying plotting area size using
the box attribute and the location using the location attribute.
VARIABLES THAT ARE SET
Areadef will set the variables AREALEFT, AREARIGHT,
AREABOTTOM, and AREATOP
to hold the locations of the plot area edges in
absolute units
.
Also, XMIN, XMAX, YMIN, and YMAX are set to the
scaled space boundaries.
MANDATORY ATTRIBUTES
The range in X and Y must be specified, either using
xrange / yrange, or
xautorange / yautorange.
Exception: when categories are being used for an axis, range does not
need to be specified.
If nothing else is specified,
default behaviour is for the standard
plotting area to be used, with linear scaling in x and y.
ATTRIBUTES
Attributes for specifying 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
xscaletype: categories
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.
New in version 1.40.
autoheight f
Allows the height of the plotting area to be determined by the data range in Y.
See autowidth.
Attributes for specifying scale type and units
xscaletype type [ format ]
Defines the type of scaling for the X axis. Default is linear.
Other possible types include: linear, log, log+1,
categories, date, time. The format parameter may be given when
xscaletype is date or time to set the default notation.
If categories scale type is used, use the xcategories attribute
to define the categories,
and see also the catcompmethod attribute.
Scale types are not remembered from any previous proc defineunits or
proc autoscale invocations; they must be repeated here.
See
scaleunits
for discussion of the various scale types and units, and
the gallery
for examples.
Example: xscaletype: date yymm
Example: xscaletype: categories
yscaletype type [ format ]
Defines the type of scaling for the Y axis.
Same syntax as xscaletype above.
Default is linear.
Attributes for specifying plottable data range in X and Y
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 xrange accordingly.
(To set the range explicitly, use xrange.)
For details, see
autorange(pl)
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 yrange accordingly.
(To set the range explicitly, use yrange.)
For details, see
autorange(pl)
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
Attributes pertaining to categories
Categories are a type of scaling where instead of a continuous numeric range,
the axis is populated with a number of categories or labels.
Useful for certain types of plots such as bar graphs showing distributions.
To use categories on the x axis, for example, do xscaletype: categories
then specify the categories using the xcategories attribute.
xcategories
multi-line text
| datafield=dfield
A list of categories for use in X, one per line, terminating with
a blank line.
Or, to take categories from a data field, use
xcategories: datafield=dfield
where dfield references a data field. Only unique names will be taken.
See also
scaleunits
for a description of how categories scaling works.
The category comparison method may be controlled using areadef attribute catcompmethod.
Example 1:
xcategories: Red
Blue
Green
Example 2:
xcategories: datafield=1
ycategories
multi-line text
| datafield=dfield
A list of categories for use in Y, one per line.
Same syntax as xcategories.
Default orientation of categories is from top downward.
See also
scaleunits
for a description of how categories scaling works.
The category comparison method may be controlled using areadef attribute catcompmethod.
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. New in version 1.40.
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.
Attributes pertaining to 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 options 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.
proc axis
|
 data display engine
Copyright Steve Grubb
|