proc areadef


Version 2.33 Jun'06

Scripts


Manual page for proc_areadef(PL) proc areadef defines a rectangular area where subsequent scaled plotting will take place. The size, location of the rectangle are specified, and the scaling method and range of both X and Y are defined here. 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, but only one plotting area and scale system is in effect at any one time (referred to as the "current plotting area").

Various scaling types, including linear, log, date, time and category are available for X and Y. The xautorange and yautorange attributes can be used to perform automatic axis scaling based on the data. Clickmap and mouseover support is available for the plotting area grid or as a whole.


Attributes

The range in X and Y must be specified, either using xrange / yrange, or xautorange / yautorange. If nothing else is specified, default behaviour is for the standard plotting area to be used, with linear scaling in x and y.


Location & size of the plotting rectangle

The size and location of the plotting area on a page (the plotting area) may be specified in one of these three ways:
- 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.
- by name using the areaname attribute;

You can also make the plot area size vary automatically based on how much data you are plotting (autowidth and autoheight).

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.

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

autowidth     f     [minallowablesize maxallowablesize]

If sepcified, the width of the plotting area will be influenced 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 that will be in effect for the X axis. Supported types include:
scaletype      description
----------     ------------------------------------------
linear         the default; continuous linear
log log+1      logarithmic scaling
date           scaling based on date values, usually in X
time           scaling based on time values, usually in X
datetime       for plotting time values over several days
categories     bins for categorical data.  

The format parameter may be given with date, time, or datetime, to set the default date/time notation. See scaleunits for discussion of the various scale types and units, and the gallery scale & axis examples.

xrange or xautorange will also need to be specified. For categories, a set of categories must be already defined using proc categories or using the equivalent proc areadef categories attributes.

Example: xscaletype: date yymm
Example: xscaletype: datetime mm/dd/yyyy.hh:mm
Example: xscaletype: categories

yscaletype     type     [format]

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

xrange     min max | categories

Defines the plottable range in x. min and max must both be given, and must both be plottable values with respect to xscaletype. (To set a continuous range automatically using a data field, use xautorange.) 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, xscaletype must be set appropriately. If you want, you can specify categories, but this just has the same effect as setting the scaletype to categories.
Example: if your data ranges in x between 1.5 and 23.5 you might use: xrange: 0 24
Example: xrange: categories
Example: xrange: 01FEB2002 28FEB2002
Example: xrange: 01FEB2002.00:00 04FEB2002.24:00

xautorange     datafield=dfields .. other subattributes..

This may be used as an alternative to xrange, in order to automatically find an appropriate range based on the data. dfields are the data field(s) to be scanned. This attribute has its own manual page.

yrange     min max

Defines the plottable range in y. See xrange above.

yautorange     datafield=dfield .. other subattributes..

This may be used as an alternative to yrange, in order to automatically find an appropriate range based on the data. Similar to xautorange. This attribute has its own manual page.


Categories

As of version 2.11 categories can be defined beforehand using a new proc called proc categories. Previously, categories were defined within proc areadef using the attributes listed below, and this syntax will continue to be supported. However, additional capabilities and higher capacities are available via proc categories. See the proc categories man page for fuller descriptions.

xcategories ..define a set of categories to be used in X.

ycategories ..define a set of categories to be used in Y.

xextracategory ..allows an extra X axis category to be added explicitly

yextracategory ..allows an extra Y axis category to be added explicitly

catcompmethod ..control the details of how category comparisons are done.


Axis generation

X and Y axes are generated by proc axis ; however, axis attributes may be specified from within proc areadef as a convenience. This usually involves adding a xaxis. or yaxis. prefix to the attribute name. If axes are defined this way then the plotting area and axes can all be #clone'd as a unit.

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

Example:

  #proc areadef
    xscaletype: date dd-Mmm-yyyy
    xrange: 01-Jun-2003 15-Jun-2003
    yrange: 0 100
    xaxis.label: Date
    xaxis.stubs: inc 3 day
    xaxis.stubformat: mm/dd
    yaxis.label: Percent occupied
    yaxis.stubs: inc



Other attributes of the plotting area

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.

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.


Clickmaps and mouseover

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

This attribute can also be used to make the entire plotting area one clickable region. This will be done if niether @@XVAL nor @@YVAL are found in the template.

clickmaplabel     label

If generating a client-side clickmap, region encompassing the entire plotting area, this specifies a mouseover text label.
Example: clickmaplabel: Animals tested without drug effect

clickmaplabeltext     multiline text

Same as clickmaplabel but multiline text. Must be terminated with a blank line.


Variables set by proc areadef

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.


Pre-defined plotting area names

Pre-defined plotting area names, used with the areaname: attribute, are:
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



data display engine  
Copyright Steve Grubb


Ploticus is hosted at http://ploticus.sourceforge.net
SourceForge Logo


Markup created by unroff 1.0,    June 02, 2006.