File: scatterplot

package info (click to toggle)
ploticus-doc 2.33-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 9,392 kB
ctags: 169
sloc: pascal: 469; makefile: 63; sh: 11
file content (923 lines) | stat: -rw-r--r-- 18,287 bytes
.ig >>
<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.33 Jun'06
     </small><br><a href="../doc/scripthome.html">Scripts</a>
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH proc_scatterplot PL "02-JUN-2006   PL ploticus.sourceforge.net"

.ig >>
<center>
<img src="../gallery/scatterplot0.gif">
&nbsp; &nbsp;
<img src="../gallery/heatmap0.gif">
</center>
.>>

.LP
\fBProc scatterplot\fR displays data points in one or two dimensions using the 
.ig >>
<a href="dataformat.html#currentds">
.>>
\0current data set
.ig >>
</a>
.>>
and
.ig >>
<a href="areadef.html">
.>>
\0current plotting area.
.ig >>
</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.
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.
(Unadjusted duplicate data points can appear as just one point, which may be misleading.)
Clickmap and mouseover text labels
are supported for data points.
See the
.ig >>
<a href="../gallery/gall.scat.html">
.>>
\0gallery scatterplot examples
.ig >>
</a>
.>>
and
.ig >>
<a href="../gallery/gall.heatmap.html">
.>>
\0heatmap examples.
.ig >>
</a>
.>>



.ig >>
<br><br><br>
.>>

.SH Attributes
For a 2-D scatterplot both \fCxfield\fR and \fCyfield\fR \fBmust\fR
be specified.  For conventional scatterplots you'll probably also
want to specify a particular symbol.

.ig >>
<br><br><br>
.>>

.SH Data point position
.LP
\fBxfield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
Contents of this field controls the X location of data points.
First field is 1.
Example: \fCxfield: 2\fR

.ig >>
<br><br>
.>>
.LP
\fByfield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
Contents of this field controls the Y location of data points.
First field is 1.
Example: \fCyfield: 1\fR

.ig >>
<br><br>
.>>
.LP
\fBxlocation\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\0locvalue
.ig >>
</a>
.>>
.IP \0
If specified, a 1-D distribution will be rendered, with data points to be distributed 
(before any clustering) vertically at X = \fIlocvalue\fR.
\fCyfield\fR can be used for the Y component.

.ig >>
<br><br>
.>>
.LP
\fBylocation\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\0locvalue
.ig >>
</a>
.>>
.IP \0
If specified, a 1-D distribution will be rendered, with data points to be distributed 
(before any clustering) horizontally at Y = \fIlocvalue\fR.
\fCxfield\fR can be used for the X component.


.ig >>
<br><br><br>
.>>
.SH Displaying data points using symbols
.LP
\fBsymbol\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
.IP \0
If specified, a geometric point symbol will mark data points.
This specifies the attributes of the symbols to be used.
.br
Example: \fCsymbol: style=fill shape=circle fillcolor=red\fR

.ig >>
<br><br>
.>>

.LP
\fBrectangle\fR
.ig >>
&nbsp; &nbsp;
.>>
\fIwidth  height 
.ig >>
&nbsp; &nbsp;
.>>
\fC[outline]\fR
.IP \0 \0
If specified, data points will be displayed using a rectangle centered around the data point
of \fIwidth\fR data units wide and \fIheight\fR data units high.
If \fCoutline\fR is specified, the rectangles will be outlined with a line
(controllable using \fClinedetails\fR).  The color of the rectangle can be
controlled via a datafield (see \fCsymfield\fR, \fCsymrangefield\fR, and
\fCdupsleg\fR below).
.br
Example: \fCrectangle 1 1 outline\fR
.br
Example: \fCrectangle 0.9 0.9\fR

.ig >>
<br><br>
.>>
.LP
See also the "Data-driven control" options for controlling the appearance of data points, below.


.ig >>
<br><br><br>
.>>

.SH Displaying data points using line segments
.LP
\fBlinelen\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR 
.IP \0
If specified, data points will be displayed as short line segments.
The lines segments will be of length \fIn\fR in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units.
.ig >>
</a>
.>>
The default direction of the line will
be appropriate for 1-D scatterplots; for 2-D it is horizontal.
Line color, etc. may be controlled using \fClinedetails\fR.
Line length may also be influenced using \fCsizefield\fR.
Line direction may be explicitly controlled using \fClinedir\fR.
Example: \fClinelen: 0.2\fR

.ig >>
<br><br>
.>>
.LP
\fBlinedir\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCh|v|u|r\fR
.IP \0
Allows explicit control of direction of line when displaying data points 
as line segments (\fClinelen\fR).
\fCh\fR = horizontal (centered);
\fCv\fR = vertical (centered);
\fCu\fR = upward;
\fCr\fR = rightward.
Example: \fClinedir: v\fR

.ig >>
<br><br>
.>>

.LP
\fBlinedetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
If points are displayed using line segments (\fClinelen\fR), this
attribute allows control of color, line width, etc.  Also can
be used to control outline when \fCrectangle\fR is used.

.ig >>
<br><br><br>
.>>

.SH Displaying data points using text
.LP
\fBtext\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0text
.ig >>
</a>
.>>
.IP \0
If specified, data points will be displayed using the
given \fItext\fR, centered around the data point.
This attribute may be used with or without a \fCsymbol\fR.
Example: \fCtext: A\fR

.ig >>
<br><br>
.>>
.LP
\fBlabelfield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
If specified, data points will be displayed using the text in data 
field \fIdfield\fR.  The text will be centered around the data point.
May not be used with symbol; in order to do datafield-driven label 
plus a symbol proc scatterplot must be invoked twice.
.br
Example: \fClabelfield: 4\fR

.ig >>
<br><br>
.>>
.LP
\fBlabelword\fR
.ig >>
&nbsp; &nbsp;
.>>
\fIstring\fR
.IP \0
A template for displaying the values rendered by \fClabelfield\fR.  
The value will be substituted in at the token @VAL.
Example:
.nf
labelfield: 2
labelword: Case @VAL
.fi

.ig >>
<br><br>
.>>
.LP
\fBtextdetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Details concerning the rendering of data point text or data point labels.
.br
Example: \fCtextdetails: size=6\fR

.ig >>
<br><br>
.>>
.LP
\fBverticaltext\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, label text will be rendered vertically.


.ig >>
<br><br><br>
.>>

.SH Data-driven sizing of data points

.LP
\fBsizefield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
If specified, the size of data point symbols, lines, or text are controlled by
this data field, effectively allowing another variable to be presented.
For symbols or text the value in \fIdfield\fR will be taken to be a character point size
(see also \fIsizescale\fR).
For line segments, the value in \fIdfield\fR
will scale the length of the lines, ie. a data value
of 2.0 doubles it and 0.5 halves it.

.ig >>
<br><br>
.>>

.LP
\fBsizescale\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
May be used with \fCsizefield\fR 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.
A value of 2.0 doubles the resulting size; 0.5 halves it.

.ig >>
<br><br><br>
.>>

.SH Data-driven color / shape / size of data points

.LP
\fBsymfield\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
If specified, the data point color, size, shape, etc. can be driven by specific data values
in this field.
This attribute uses the 
.ig >>
<a href="legendentry.html#legenddriven">
.>>
\0legend-driven technique
.ig >>
</a>
.>>
(the legend structure is used to map data values to symbol appearance specifications).
If rendering symbols, symbol attributes should be given in the legendentries \fCdetails\fR;
if rendering rectangles, colors should be given.
.br
Example: 
.ig >>
<a href="../gallery/symfld.htm">
.>>
\0symfld
.ig >>
</a>
.>>

.ig >>
<br><br>
.>>

.LP
\fBsymrangefield\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
If specified, the symbol color, size, shape, etc. can be driven by numeric data
in this field.
Similar to \fCsymfield\fR above, except that numeric range comparison is used
when finding the appropriate legend entry, using the
.ig >>
<a href="legendentry.html#legenddriven">
.>>
\0legend-driven technique
.ig >>
</a>
.>>
(the legend structure is used to map data values to symbol appearance specifications).
Legend tags must be a single numeric value.
Legend entries must be specified in numerical order by tag, from highest to lowest.
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 \fCsymrangefield\fR data field, 
that legend entry is chosen, and the point will be rendered using the symbol
described in that entry.
Examples: 
.ig >>
<a href="../gallery/symrangefld.htm">
.>>
\0symrangefld
.ig >>
</a>
.>>
and
.ig >>
<a href="../gallery/heatmap3.htm">
.>>
\0heatmap3
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.SH Displaying duplicity by clustering of data points
.LP
\fBcluster\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
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 \fCno\fR (changed in 2.33).
2-D clusters may be as large as N=38 (after this, points will overlap).
Additional attributes related to clustering are described below.
Note: If labelfield and/or sizefield are being used, clustering
will work properly only when data are presorted into X,Y order.

.ig >>
<br><br>
.>>
 
.LP
\fBclustermethod\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fC2d | horiz | vert | upward | rightward\fR
.IP \0
Explicitly control the way that duplicate points will be clustered.
.br
\fC2d\fR clusters the points evenly around the data point.
.br
\fChoriz\fR clusters the points evenly leftward and rightward.
.br
\fCvert\fR clusters the points evenly upward and downward.
.br
\fCupward\fR strings the points upward only for generating little vertical bars.
.br
\fCrightward\fR strings the points rightward only for generating little horizontal bars.
.br
Default is \fC2d\fR for 2-D scatterplots, or \fChoriz\fR or \fCvert\fR for 1-D 
scatterplots depending on orientation.
An example of using \fCclustermethod: upward\fR to form rows of little bars is 
.ig >>
<a href="../gallery/snpmap1.htm">
.>>
\0snpmap1
.ig >>
</a>
.>>
.IP \0
To represent duplicate points using different symbol colors (etc.) see \fCdupsleg\fR.

.ig >>
<br><br>
.>>

.LP
\fBclusterfact\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIf\fR
.IP \0
May be used when \fCclustering\fR is being done.  The clustering offset distance
will be multiplied by \fIf\fR.
A value of 2.0 spreads clustered points out more, and 0.5 spreads them out less.

.ig >>
<br><br>
.>>

.LP
\fBclusterdiff\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIf\fR
.IP \0
May be used when \fCclustering\fR is being done.  Two values
that are within \fIf\fR 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units (inches)
.ig >>
</a>
.>>
of each other will be considered duplicates
eligible for clustering.  Default value is \fC0.001\fR.  

.ig >>
<br><br>
.>>

.LP
\fBclustevery\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
With clustering, normally every duplicate point is offset from all
the others, which may become cluttered and ineffective with large numbers of duplicates.
This attribute may be used to offset 
only for every \fIn\fRth duplicate encountered.
.br
Example: \fCclustevery: 5\fR   ..would result in a point having 35 duplicates
represented using 7 point marks.

.ig >>
<br><br><br>
.>>
.SH Displaying duplicity by data point color

.LP
\fBdupsleg\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
If \fCyes\fR, 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
.ig >>
<a href="legendentry.html#legenddriven">
.>>
\0legend-driven technique
.ig >>
</a>
.>>
(the legend structure is used to map data values to appearance specifications).
Each legend entry must have a \fCtag\fR that is an integer.
If you're rendering symbols, supply 
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
for the legendentry \fCdetails\fR; supply a 
.ig >>
<a href="color.html">
.>>
\0color
.ig >>
</a>
.>>
if rendering rectangles.
Legend entries must be specified in numerical order by tag, from highest to lowest.
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).
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.
Example: 
.ig >>
<a href="../gallery/dupsleg.htm">
.>>
\0dupsleg
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.SH Selecting certain data points

.LP
\fBselect\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="select.html">
.>>
\0select expression
.ig >>
</a>
.>>
.IP \0
May be used to select data rows for inclusion into the scatterplot.
.br
Example: \fCselect: @@3 = AA\fR

.LP
\fBxrange\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIlow high\fR
.IP \0
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.
Example: \fCxrange: 0 50\fR

.LP
\fByrange\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIlow high\fR
.IP \0
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.
Example: \fCyrange: 0 50\fR

.ig >>
<br><br><br>
.>>

.SH Legend

.LP
\fBlegendlabel\fR  
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0text
.ig >>
</a>
.>>
.IP \0
A label to be associated with the current set of points in the legend.
\fBproc legend\fR must be executed later in order to 
render the legend.  \fB@NVALUES\fR may be used to signify number of
points rendered.
The \fC\\n\fR 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+).
If
.ig >>
<a href="getdata.html">
.>>
\0proc getdata field names
.ig >>
</a>
.>>
are being used, use of
the special symbols \fC#usexname\fR (or \fC#useyname\fR) causes the field name of \fCxfield\fR (or \fCyfield\fR)
to be automatically used as the legend label (2.04+).
.br
Example: \fClegendlabel: Group 4, N=@NVALUES\fR
.br
Example: \fClegendlabel: Round 2\fR
.br
Example: \fClegendlabel: #useyname\fR

.ig >>
<br><br><br>
.>>

.SH Clickmap and mouseover
.LP
Note: clickmap is not supported when data points are displayed using line segments.

.LP
\fBclickmapurl\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIurl-template\fR
.IP \0
If generating an
.ig >>
<a href="clickmap.html">
.>>
\0HTML clickmap
.ig >>
</a>
.>>
, this specifies a url template, and
causes the data points (symbol or character) to be mapped.
This attribute usually contains one or more embedded
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0data field references
.ig >>
</a>
.>>
preceded by double at-sign (@@).
See
.ig >>
<a href="clickmap.html">
.>>
\0HTML clickmap
.ig >>
</a>
.>>
for more details and examples.
.br
Example: \fCclickmapurl: http://abc.com/mycgi?category=@@3\fR

.ig >>
<br><br>
.>>

.LP
\fBclickmaplabel\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIlabel-template\fR
.IP
If generating a
.ig >>
<a href="clickmap.html">
.>>
\0client-side clickmap,
.ig >>
</a>
.>>
this specifies a template for building mouseover text labels.
.br
Example: \fCclickmaplabel: @@3 (@@4)\fR

.LP
\fBclickmaplabeltext\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0multiline text
.ig >>
</a>
.>>
.IP \0
Same as \fCclickmaplabel\fR but multiline text.  Must be terminated with a blank line.



.ig >>
<br><br><br>
.>>

.SH Variables that are set by proc scatterplot
.LP
\fBNVALUES\fR = the number of in-range plottable points that were rendered.
Note: this may be used in the legendlabel.
.ig >>
<br><br>
.>>
.LP
\fBMAXDUPS\fR = the maximum number of clustered duplicate points.  If \fCclustermeth\fR
is \fC2d\fR this maxes out at 37.

.ig >>
<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 &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif"> 
</center>
</td></tr>
</table>
<br>
<center>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
.>>