#set TITLE = "proc scatterplot"
#include top

.ig >>
<center>
<img src="../gallery/scatterplot0.gif">
</center>
.>>

.SH DESCRIPTION
Displays data points in one or two dimensions.

#include space
.SH FEATURES
Clustering (using a small offset) of duplicate data points.
.LP
Data points may be marked with geometric point symbols,
characters/text, or lines.
.LP
User control over point shapes, colors, sizes.
.LP
Optional labelling from data, and control of point size from data.
.LP
#set FILE = clickmap.html
#set TAG = "HTML clickmap"
#include link
support for data points.

#include space
.SH EXAMPLES
See the Gallery Scatterplot page
.ig >>
<a href="../gallery/gall.scat.html"><img src="../gallery/btn/here.gif"></a>
.>>

#include space
.SH VARIABLES THAT ARE SET
\fBNVALUES\fR = the number of in-range plottable points that were rendered.
Note: this may be used in the legendlabel.

#include space
.SH UNPLOTTABLE DATA 
\fBproc scatterplot\fR will omit data points that are not valid
or not within the plotting area.

#include space
.SH PREREQUISITES
A plotting area must be set up using \fBproc areadef\fR 
and \fBproc getdata\fR must be executed to 
access or define some data.

#include space
.SH MODES
2-dimensional (2-D) and 1-dimensional (1-D).
For 2-D scatterplots, both \fCxfield\fR and \fCyfield\fR
should be specified.
.LP
With 1-D scatterplots points are plotted along an imaginary
line.  To distribute points horizontally along Y=1 for example,
\fCylocation: 1\fR and \fCxfield\fR should be specified.
To distribute points vertically along X=5,
\fCxlocation: 5\fR and \fCyfield\fR should be specified.
.LP
Data points may be marked with geometric point symbols and/or
characters/text, or using short line segments.  
Characters/text may be a literal or it may come from a data field.  
It is also possible to have the geometric point symbols under the
control of a datafield (\fCsymfield\fR).

#include space
.SH DUPLICATE POINTS
The \fCcluster\fR attribute (which is \fBon\fR by default) causes
duplicate points to be offset slightly to form a cluster or bar, which
often gives a satisfactory visual representation of the degree
of duplicity.  
It is also possible to show duplicity using different symbol colors,
sizes or shapes (\fCdupsleg\fR).


#include space
.SH MANDATORY ATTRIBUTES
For a 2-D scatterplot both \fCxfield\fR and \fCyfield\fR must
be specified.
For a 1-D scatterplot, either \fCxfield\fR or \fCyfield\fR must
be specified.

#include space
.SH ATTRIBUTES
.LP
\fBxfield\fR 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\fI dfield \fR
.ig >>
</a>
.>>
.IP
Get X plotting values from this data field.
First field is 1.
Example: \fCxfield: 1\fR

.LP
\fByfield\fR 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\fI dfield \fR
.ig >>
</a>
.>>
.IP
Get Y plotting values from this data field.
First field is 1.
Example: \fCyfield: 1\fR

.LP
\fBxlocation\fR
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\fI locvalue \fR
.ig >>
</a>
.>>
.IP
If specified, \fBproc scatterplot\fR will operate in 1-D mode 
along Y.  The value specifies where the points will be rendered in X.

.LP
\fBylocation\fR
.ig >>
<a href="attributetypes.html#locvalue">
.>>
\fI locvalue \fR
.ig >>
</a>
.>>
.IP
If specified, \fBproc scatterplot\fR will operate in 1-D mode 
along X.  The value specifies where the points will be rendered in Y.

.LP
\fBcluster\fR  \fCyes\fR | \fCno\fR
.IP
If yes, data will be sorted on X,Y and duplicate data points 
will be detected and offset slightly to show duplicity.  
The default is \fCyes\fR.
Clusters may be as large as N=36 (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.

.LP
\fBsymbol\fR 
.ig >>
<a href="symboldetails.html">
.>>
\fI symboldetails \fR
.ig >>
</a>
.>>
.IP
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


.LP
\fBlinelen\fR \fIn\fR
.IP
If specified, data points will be displayed as lines of length
\fIn\fR in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\fI absolute units \fR
.ig >>
</a>
.>>
 .  The 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.
Example: \fClinelen: 0.2\fR

.LP
\fBtext\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI text \fR
.ig >>
</a>
.>>
.IP
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

.LP
\fBlabelfield\fR 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\fI dfield \fR
.ig >>
</a>
.>>
.IP
If specified, data points will be displayed using
the contents of data field \fIdfield\fR, 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

.LP
\fBtextdetails\fR 
.ig >>
<a href="textdetails.html">
.>>
\fI textdetails \fR
.ig >>
</a>
.>>
.IP
Details concerning the rendering of point labels.
.br
Example: \fCtextdetails: size=6\fR

.LP
\fBlinedetails\fR 
.ig >>
<a href="linedetails.html">
.>>
\fI linedetails \fR
.ig >>
</a>
.>>
.IP
If points are displayed using line segments (\fClinelen\fR), this
attribute allows control of color, line width, etc.


.LP
\fBlegendlabel\fR  
.ig >>
<a href="attributetypes.html#text">
.>>
\fI text \fR
.ig >>
</a>
.>>
.IP
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.
.br
Example: \fClegendlabel: Group 4, N=@@NVALUES\fR
 

.LP
\fBverticaltext\fR \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, label text will be rendered vertically.
This might be useful when labels are > 1 character long
and data are close together in X.

.LP
\fBsizefield\fR 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\fI dfield \fR
.ig >>
</a>
.>>
.IP
Allows the size of point markers or lines to be controlled by
a datafield, effectively allowing another variable to be presented.
.IP
If data points are marked using geometric symbols or text,
the value in \fIdfield\fR will cause the marks to correspond
to character point sizes.  For example, a data value
of 10 would yield a data point mark 10 points in height.
The \fIsizescale\fR attribute may be used to scale the
\fCsizefield\fR data appropriately.
.IP
If data points are marked using lines, the value in \fIdfield\fR
will scale the length of the lines.  For example, a data value
of 1.0 would leave the line length unchanged, while 2.0 would
double it and 0.5 would halve it.

.LP
\fBsizescale\fR \fIn\fR
.IP
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.  
It assumes the symbol is a circle and scales the \fIarea\fR rather than
the diameter or radius.
A value of 1.0 would leave the size unchanged, 
while 2.0 would double the resulting size,
and 0.5 would halve it.

.LP
\fBclustermethod\fR \fC2d | horiz | vert | upward | rightward\fR
.IP
Explicitly control the way that duplicate points will be clustered.
Default method is \fC2d\fR for 2-D scatterplots, \fChoriz\fR for 1-D scatterplots
where Y location is fixed, and \fCvert\fR for 1-D scatterplots
where X location is fixed.
\fCupward\fR and \fCrightward\fR may be used to string duplicate points upward
or rightward to form little bars.  \fChoriz\fR will cluster duplicate points
only horizontally; \fCvert\fR will cluster duplicate points only vertically.
An example of using \fCclustermethod: upward\fR to form rows of little bars,
is 
#set FILE = "../gallery/snpmap1.htm"
#set TAG = "snpmap1"
#include link
.IP
To represent duplicate points using different symbol colors (etc.) see \fCdupsleg\fR.

.LP
\fBclusterfact\fR \fIn\fR
.IP
May be used when \fCclustering\fR is being done.  The clustering offset distance
will be multiplied by this
amount.  A value of 1.0 would leave the clustering offsets unchanged,
while 2.0 would spread clustered points out more, and 0.5 would
spread them out less.

.LP
\fBclusterdiff\fR \fIf\fR
.IP
May be used when \fCclustering\fR is being done.  Two values
that are within \fIf\fR of each other will be considered duplicates
eligible for clustering.  Default value is 0.01.

.LP
\fBclustevery\fR  \fIn\fR
.IP
With clustering, normally every duplicate point is offset from all
the others,
which may not be effective if there are large numbers of duplicate points.
In order to reduce the clutter, 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.

.LP
\fBdupsleg\fR \fCyes | no\fR
.IP
If \fCyes\fR the symbol color, size, shape, etc. will be controlled by the number of duplicate points counted.
This uses the
#set FILE = "legendentry.html#legenddriven"
#set TAG = "legend-driven technique"
#include link
\0.  Each legend entry must have a \fCtag\fR that is an integer, 
and a 
#set FILE = symboldetails.html
#set TAG = "symboldetails"
#include link
entry for \fCdetails\fR.
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: 
#set FILE = "../gallery/dupsleg.htm"
#set TAG = "dupsleg"
#include link

.LP
\fBsymfield\fR
#set FILE = "attributetypes.html#dfield"
#set TAG = "dfield"
#include link
.IP
If specified, the symbol color, size, shape, etc. will be controlled by this data field
using the 
#set FILE = "legendentry.html#legenddriven"
#set TAG = "legend-driven technique"
#include link
\0.
Example: 
#set FILE = "../gallery/symfld.htm"
#set TAG = "symfld"
#include link

.LP
\fBsymrangefield\fR
#set FILE = "attributetypes.html#dfield"
#set TAG = "dfield"
#include link
.IP
Same as \fCsymfield\fR above, except that numeric range comparison is used
when finding the appropriate legend entry, using the
#set FILE = "legendentry.html#legenddriven"
#set TAG = "legend-driven technique"
#include link
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.
Example: 
#set FILE = "../gallery/symrangefld.htm"
#set TAG = "symrangefld"
#include link

.LP
\fBselect\fR 
.ig >>
<a href="condex.html">
.>>
\fI conditional-expression \fR
.ig >>
</a>
.>>
.IP
May be used to select data rows for inclusion into the scatterplot.
Example: \fCselect: @@3 = AA\fR

.LP
\fBxrange\fR \fIlow high\fR
.IP
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 \fIlow high\fR
.IP
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

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

#include bottom
