<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/11/09 12:56:21. -->
<!-- Do not edit! -->
<STYLE TYPE="text/css">
<!--
A:link{text-decoration:none}
A:visited{text-decoration:none}
A:active{text-decoration:none}
OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }
H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: proc scatterplot</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550><tr>
<td>
<table cellpadding=2 width=550><tr>
<td><br><h2>proc scatterplot</h2></td>
<td align=right>
<small>
<a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
Version 2.41 Mar2009
</small><br><a href="../doc/scripthome.html">Scripts</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
<title>Manual page for proc_scatterplot(PL)</title>
</head>
<body>
<center>
<img src="../gallery/scatterplot0.gif">
<img src="../gallery/heatmap0.gif">
</center>
<p>
<b>Proc scatterplot</b> displays data points in one or two dimensions using the
<a href="dataformat.html#currentds">
current data set
</a>
and
<a href="areadef.html">
current plotting area.<tt> </tt>
</a>
It can produce traditional scatterplots and distributions and also can be used as a general
technique for rendering data points or text at specific locations.<tt> </tt>
Data points can be rendered
as symbols, line segments, or bits of text. Data point color, shape, size,
and/or text content can be driven by data.
Duplicate data points can be clustered
in a variety of ways, or duplicity can be represented by color change.<tt> </tt>
(Unadjusted duplicate data points can appear as just one point, which may be misleading.)
Clickmap and mouseover text labels
are supported for data points.<tt> </tt>
See the
<a href="../gallery/gall.scat.html">
gallery scatterplot examples
</a>
and
<a href="../gallery/gall.heatmap.html">
heatmap examples.<tt> </tt>
</a>
<br><br><br>
<h2>Attributes</h2>
For a 2-D scatterplot both <tt>xfield</tt> and <tt>yfield</tt> <b>must</b>
be specified. For conventional scatterplots you'll probably also
want to specify a particular symbol.<tt> </tt>
<br><br><br>
<h2>Data point position</h2>
<p>
<b>xfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
Contents of this field controls the X location of data points.<tt> </tt>
First field is 1.<tt> </tt>
Example: <tt>xfield: 2</tt>
<br><br>
</dl>
<p>
<b>yfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
Contents of this field controls the Y location of data points.<tt> </tt>
First field is 1.<tt> </tt>
Example: <tt>yfield: 1</tt>
<br><br>
</dl>
<p>
<b>xlocation</b>
<a href="attributetypes.html#locvalue">
locvalue
</a>
<dl>
<dt> <dd>
If specified, a 1-D distribution will be rendered, with data points to be distributed
(before any clustering) vertically at X = <i>locvalue</i>.<tt> </tt>
<tt>yfield</tt> can be used for the Y component.<tt> </tt>
<br><br>
</dl>
<p>
<b>ylocation</b>
<a href="attributetypes.html#locvalue">
locvalue
</a>
<dl>
<dt> <dd>
If specified, a 1-D distribution will be rendered, with data points to be distributed
(before any clustering) horizontally at Y = <i>locvalue</i>.<tt> </tt>
<tt>xfield</tt> can be used for the X component.<tt> </tt>
<br><br><br>
</dl>
<h2>Displaying data points using symbols</h2>
<p>
<b>symbol</b>
<a href="symboldetails.html">
symboldetails
</a>
<dl>
<dt> <dd>
If specified, a geometric point symbol will mark data points.<tt> </tt>
This specifies the attributes of the symbols to be used.<tt> </tt>
<br>
Example: <tt>symbol: style=fill shape=circle fillcolor=red</tt>
<br><br>
</dl>
<p>
<b>rectangle</b>
<i>width height
</i><tt>[outline]</tt>
<dl>
<dt> <dd>
If specified, data points will be displayed using a rectangle centered around the data point
of <i>width</i> data units wide and <i>height</i> data units high.<tt> </tt>
If <tt>outline</tt> is specified, the rectangles will be outlined with a line
(controllable using <tt>linedetails</tt>). The color of the rectangle can be
controlled via a datafield (see <tt>symfield</tt>, <tt>symrangefield</tt>, and
<tt>dupsleg</tt> below).<tt> </tt>
<br>
Example: <tt>rectangle 1 1 outline</tt>
<br>
Example: <tt>rectangle 0.9 0.9</tt>
<br><br>
</dl>
<p>
See also the "Data-driven control" options for controlling the appearance of data points, below.<tt> </tt>
<br><br><br>
<h2>Displaying data points using line segments</h2>
<p>
<b>linelen</b>
<i>n</i>
<dl>
<dt> <dd>
If specified, data points will be displayed as short line segments.<tt> </tt>
The lines segments will be of length <i>n</i> in
<a href="attributetypes.html#positionunits">
absolute units.<tt> </tt>
</a>
The default direction of the line will
be appropriate for 1-D scatterplots; for 2-D it is horizontal.<tt> </tt>
Line color, etc. may be controlled using <tt>linedetails</tt>.<tt> </tt>
Line length may also be influenced using <tt>sizefield</tt>.<tt> </tt>
Line direction may be explicitly controlled using <tt>linedir</tt>.<tt> </tt>
Example: <tt>linelen: 0.2</tt>
<br><br>
</dl>
<p>
<b>linedir</b>
<tt>h|v|u|r</tt>
<dl>
<dt> <dd>
Allows explicit control of direction of line when displaying data points
as line segments (<tt>linelen</tt>).<tt> </tt>
<tt>h</tt> = horizontal (centered);
<tt>v</tt> = vertical (centered);
<tt>u</tt> = upward;
<tt>r</tt> = rightward.<tt> </tt>
Example: <tt>linedir: v</tt>
<br><br>
</dl>
<p>
<b>linedetails</b>
<a href="linedetails.html">
linedetails
</a>
<dl>
<dt> <dd>
If points are displayed using line segments (<tt>linelen</tt>), this
attribute allows control of color, line width, etc. Also can
be used to control outline when <tt>rectangle</tt> is used.<tt> </tt>
<br><br><br>
</dl>
<h2>Displaying data points using text</h2>
<p>
<b>text</b>
<a href="attributetypes.html#text">
text
</a>
<dl>
<dt> <dd>
If specified, data points will be displayed using the
given <i>text</i>, centered around the data point.<tt> </tt>
This attribute may be used with or without a <tt>symbol</tt>.<tt> </tt>
Example: <tt>text: A</tt>
<br><br>
</dl>
<p>
<b>labelfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, data points will be displayed using the text in data
field <i>dfield</i>. The text will be centered around the data point.<tt> </tt>
May not be used with symbol; in order to do datafield-driven label
plus a symbol proc scatterplot must be invoked twice.<tt> </tt>
<br>
Example: <tt>labelfield: 4</tt>
<br><br>
</dl>
<p>
<b>labelword</b>
<i>string</i>
<dl>
<dt> <dd>
A template for displaying the values rendered by <tt>labelfield</tt>.
The value will be substituted in at the token @@VAL.<tt> </tt>
Example:
<pre>
labelfield: 2
labelword: N=@@VAL
</pre>
<br><br>
</dl>
<p>
<b>textdetails</b>
<a href="textdetails.html">
textdetails
</a>
<dl>
<dt> <dd>
Details concerning the rendering of data point text or data point labels.<tt> </tt>
<br>
Example: <tt>textdetails: size=6</tt>
<br><br>
</dl>
<p>
<b>verticaltext</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, label text will be rendered vertically.<tt> </tt>
<br><br><br>
</dl>
<h2>Data-driven color / shape / size of data points</h2>
<p>
<b>sizefield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, the size of data point symbols, lines, or text are controlled by
this data field, effectively allowing another variable to be presented.<tt> </tt>
For symbols or text the value in <i>dfield</i> will be taken to be a character point size
(see also <i>sizescale</i>).<tt> </tt>
For line segments, the value in <i>dfield</i>
will scale the length of the lines, ie. a data value
of 2.0 doubles it and 0.5 halves it.<tt> </tt>
</dl>
<p>
<b>sizescale</b>
<i>n</i>
<dl>
<dt> <dd>
May be used with <tt>sizefield</tt> when the size of data point symbols or text is
being controlled by a datafield. This attribute may be used
to scale the size of the point symbols to the desired range.
Scaling is based on symbol area rather than diameter.<tt> </tt>
A value of 2.0 doubles the resulting size; 0.5 halves it.<tt> </tt>
<br><br>
</dl>
<p>
<b>colorfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, the color of data point symbols, lines, text, or rectangles is controlled by this data field,
effectively allowing another variable to be presented. The data field should contain
<a href="color.html">
color specifications.<tt> </tt>
</a>
(New in 2.41)
<br><br>
</dl>
<p>
<b>altwhen</b>
<a href="select.html">
select expression
</a>
<p>
<b>altsymbol</b>
<a href="symboldetails.html">
symboldetails
</a>
<dl>
<dt><dd><p>
In a scatterplot that is displaying data points as symbols (not lines or text),
you can use this easy method to conditionally display an alternate data point symbol.<tt> </tt>
New in version 2.40
<br><br>
</dl>
<p>
<b>symfield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, the data point color, size, shape, etc. can be driven by specific data values
in this field.<tt> </tt>
This attribute uses the
<a href="legendentry.html#legenddriven">
legend-driven technique
</a>
(the legend structure is used to map data values to symbol appearance specifications).<tt> </tt>
If rendering symbols, symbol attributes should be given in the legendentries <tt>details</tt>;
if rendering rectangles, colors should be given.<tt> </tt>
<br>
Example:
<a href="../gallery/symfld.htm">
symfld
</a>
<br><br>
</dl>
<p>
<b>symrangefield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt> <dd>
If specified, the symbol color, size, shape, etc. can be driven by numeric data
in this field.<tt> </tt>
Similar to <tt>symfield</tt> above, except that numeric range comparison is used
when finding the appropriate legend entry, using the
<a href="legendentry.html#legenddriven">
legend-driven technique
</a>
(the legend structure is used to map data values to symbol appearance specifications).<tt> </tt>
Legend tags must be a single numeric value.<tt> </tt>
Legend entries must be specified in numerical order by tag, from highest to lowest.<tt> </tt>
Prospective values will be compared against legend entries in the order specified (highest to lowest);
when a legend entry tag is found that is less than or equal to the contents of
the <tt>symrangefield</tt> data field,
that legend entry is chosen, and the point will be rendered using the symbol
described in that entry.<tt> </tt>
Examples:
<a href="../gallery/symrangefld.htm">
symrangefld
</a>
and
<a href="../gallery/heatmap3.htm">
heatmap3
</a>
<br><br><br>
</dl>
<h2>Displaying duplicity by clustering of data points</h2>
<p>
<b>cluster</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If yes, data will be sorted on X,Y and duplicate (or near-duplicate) data points
will be detected and offset slightly to show duplicity.
The default is <tt>no</tt> (changed in 2.33).<tt> </tt>
2-D clusters may be as large as N=38 (after this, points will overlap).<tt> </tt>
Additional attributes related to clustering are described below.<tt> </tt>
Note: If labelfield and/or sizefield are being used, clustering
will work properly only when data are presorted into X,Y order.<tt> </tt>
<br><br>
</dl>
<p>
<b>clustermethod</b>
<tt>2d | horiz | vert | upward | rightward</tt>
<dl>
<dt> <dd>
Explicitly control the way that duplicate points will be clustered.<tt> </tt>
<br>
<tt>2d</tt> clusters the points evenly around the data point.<tt> </tt>
<br>
<tt>horiz</tt> clusters the points evenly leftward and rightward.<tt> </tt>
<br>
<tt>vert</tt> clusters the points evenly upward and downward.<tt> </tt>
<br>
<tt>upward</tt> strings the points upward only for generating little vertical bars.<tt> </tt>
<br>
<tt>rightward</tt> strings the points rightward only for generating little horizontal bars.<tt> </tt>
<br>
Default is <tt>2d</tt> for 2-D scatterplots, or <tt>horiz</tt> or <tt>vert</tt> for 1-D
scatterplots depending on orientation.<tt> </tt>
An example of using <tt>clustermethod: upward</tt> to form rows of little bars is
<a href="../gallery/snpmap1.htm">
snpmap1
</a>
<dt> <dd>
To represent duplicate points using different symbol colors (etc.) see <tt>dupsleg</tt>.<tt> </tt>
<br><br>
</dl>
<p>
<b>clusterfact</b>
<i>f</i>
<dl>
<dt> <dd>
May be used when <tt>clustering</tt> is being done. The clustering offset distance
will be multiplied by <i>f</i>.<tt> </tt>
A value of 2.0 spreads clustered points out more, and 0.5 spreads them out less.<tt> </tt>
<br><br>
</dl>
<p>
<b>clusterdiff</b>
<i>f</i>
<dl>
<dt> <dd>
May be used when <tt>clustering</tt> is being done. Two values
that are within <i>f</i>
<a href="attributetypes.html#positionunits">
absolute units (inches)
</a>
of each other will be considered duplicates
eligible for clustering. Default value is <tt>0.001</tt>.
<br><br>
</dl>
<p>
<b>clustevery</b>
<i>n</i>
<dl>
<dt> <dd>
With clustering, normally every duplicate point is offset from all
the others, which may become cluttered and ineffective with large numbers of duplicates.<tt> </tt>
This attribute may be used to offset
only for every <i>n</i>th duplicate encountered.<tt> </tt>
<br>
Example: <tt>clustevery: 5</tt> ..would result in a point having 35 duplicates
represented using 7 point marks.<tt> </tt>
<br><br><br>
</dl>
<h2>Displaying duplicity by data point color</h2>
<p>
<b>dupsleg</b>
<tt>yes | no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, the appearance details of data points will be controlled by
the number of duplicate points counted.
This attribute can be used when rendering data points as symbols or rectangles, and it uses the
<a href="legendentry.html#legenddriven">
legend-driven technique
</a>
(the legend structure is used to map data values to appearance specifications).<tt> </tt>
Each legend entry must have a <tt>tag</tt> that is an integer.<tt> </tt>
If you're rendering symbols, supply
<a href="symboldetails.html">
symboldetails
</a>
for the legendentry <tt>details</tt>; supply a
<a href="color.html">
color
</a>
if rendering rectangles.<tt> </tt>
Legend entries must be specified in numerical order by tag, from highest to lowest.<tt> </tt>
As the scatterplot is drawn and duplicate points are detected,
a count of duplicates is maintained.
Then the count is compared against the set of tags (from highest to lowest).<tt> </tt>
When a tag is found that is <= the duplicate count, that
legend entry is chosen, and the point will be rendered using the symbol
described in that entry.<tt> </tt>
Example:
<a href="../gallery/dupsleg.htm">
dupsleg
</a>
<br><br><br>
</dl>
<h2>Selecting certain data points</h2>
<p>
<b>select</b>
<a href="select.html">
select expression
</a>
<dl>
<dt> <dd>
May be used to select data rows for inclusion into the scatterplot.<tt> </tt>
<br>
Example: <tt>select: @@3 = AA</tt>
</dl>
<p>
<b>xrange</b>
<i>low high</i>
<dl>
<dt> <dd>
If specified, only data points within the given plottable range in X
will be shown. By default the points will be drawn only if within
the plotting area.<tt> </tt>
Example: <tt>xrange: 0 50</tt>
</dl>
<p>
<b>yrange</b>
<i>low high</i>
<dl>
<dt> <dd>
If specified, only data points within the given plottable range in Y
will be shown. By default the points will be drawn only if within
the plotting area.<tt> </tt>
Example: <tt>yrange: 0 50</tt>
<br><br><br>
</dl>
<h2>Legend</h2>
<p>
<b>legendlabel</b>
<a href="attributetypes.html#text">
text
</a>
<dl>
<dt> <dd>
A label to be associated with the current set of points in the legend.<tt> </tt>
<b>proc legend</b> must be executed later in order to
render the legend. <b>@NVALUES</b> may be used to signify number of
points rendered.<tt> </tt>
The <tt>\n</tt> construct can be used to force a line break when the legend is displayed,
or the label can be wordwrapped using proc legend wraplen attribute (2.32+).<tt> </tt>
If
<a href="getdata.html">
proc getdata field names
</a>
are being used, use of
the special symbols <tt>#usexname</tt> (or <tt>#useyname</tt>) causes the field name of <tt>xfield</tt> (or <tt>yfield</tt>)
to be automatically used as the legend label (2.04+).<tt> </tt>
<br>
Example: <tt>legendlabel: Group 4, N=@NVALUES</tt>
<br>
Example: <tt>legendlabel: Round 2</tt>
<br>
Example: <tt>legendlabel: #useyname</tt>
<br><br><br>
</dl>
<h2>Clickmap and mouseover</h2>
<p>
Note: clickmap is not supported when data points are displayed using line segments.<tt> </tt>
<p>
<b>clickmapurl</b>
<i>url-template</i>
<dl>
<dt> <dd>
If generating an
<a href="clickmap.html">
HTML clickmap
</a>
, this specifies a url template, and
causes the data points (symbol or character) to be mapped.<tt> </tt>
This attribute usually contains one or more embedded
<a href="attributetypes.html#dfield">
data field references
</a>
preceded by double at-sign (@@).<tt> </tt>
See
<a href="clickmap.html">
HTML clickmap
</a>
for more details and examples.<tt> </tt>
<br>
Example: <tt>clickmapurl: http://abc.com/mycgi?category=@@3</tt>
<br><br>
</dl>
<p>
<b>clickmaplabel</b>
<i>label-template</i>
<dl>
<dt><dd><p>
If generating a
<a href="clickmap.html">
client-side clickmap,
</a>
this specifies a template for building mouseover text labels.<tt> </tt>
<br>
Example: <tt>clickmaplabel: @@3 (@@4)</tt>
</dl>
<p>
<b>clickmaplabeltext</b>
<a href="attributetypes.html#text">
multiline text
</a>
<dl>
<dt> <dd>
Same as <tt>clickmaplabel</tt> but multiline text. Must be terminated with a blank line.<tt> </tt>
<br><br><br>
</dl>
<h2>Variables that are set by proc scatterplot</h2>
<p>
<b>NVALUES</b> = the number of in-range plottable points that were rendered.<tt> </tt>
Note: this may be used in the legendlabel.<tt> </tt>
<br><br>
<p>
<b>MAXDUPS</b> = the maximum number of clustered duplicate points. If <tt>clustermeth</tt>
is <tt>2d</tt> this maxes out at 37.<tt> </tt>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
<br>
<center>
<table><tr><td>
Ploticus is hosted at http://ploticus.sourceforge.net</td><td> </td><td>
<a href="http://sourceforge.net/projects/ploticus"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=38453&type=12"
width="120" height="30" border="0"
alt="Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</td></tr></table>
</center>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 11, 2009.
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ed05dc5f357c49fdded780f52b150dce
>
files
>
106
