ploticus: proc scatterplot

## proc scatterplot | Welcome Gallery Handbook |
| Manual page for proc_scatterplot(PL)

## DESCRIPTION

Displays data points in one or two dimensions.``

## FEATURES

Clustering (using a small offset) of duplicate data points.``

Data points may be marked with geometric point symbols, characters/text, lines, or rectangles.``

User control over point shapes, colors, sizes.``

Optional labelling from data, and control of point size from data.``

HTML clickmap support for data points.``

## EXAMPLES

Gallery scatterplot examples and heatmap examples

## VARIABLES THAT ARE SET

NVALUES = the number of in-range plottable points that were rendered.`` Note: this may be used in the legendlabel.``

## UNPLOTTABLE DATA

proc scatterplot will omit data points that are not valid or not within the plotting area.``

## PREREQUISITES

A plotting area must be set up using proc areadef and proc getdata must be executed to access or define some data.``

## MODES

2-dimensional (2-D) and 1-dimensional (1-D).`` For 2-D scatterplots, both `xfield` and `yfield` should be specified.``

With 1-D scatterplots points are plotted along an imaginary line. To distribute points horizontally along Y=1 for example, `ylocation: 1` and `xfield` should be specified.`` To distribute points vertically along X=5, `xlocation: 5` and `yfield` should be specified.``

Data points may be marked with geometric point symbols and/or characters/text, or using short line segments. Rectangles may also be used.`` Characters/text may be a literal or it may come from a data field. It is also possible to have the geometric point symbols or rectangle colors controlled by a datafield (`symfield, symrangefield`).``

## DUPLICATE POINTS

The `cluster` attribute (which is on 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 (`dupsleg`).``

## MANDATORY ATTRIBUTES

For a 2-D scatterplot both `xfield` and `yfield` must be specified.`` For a 1-D scatterplot, either `xfield` or `yfield` must be specified.``

## ATTRIBUTES

xfield dfield

  Get X plotting values from this data field.`` First field is 1.`` Example: `xfield: 1`

yfield dfield

  Get Y plotting values from this data field.`` First field is 1.`` Example: `yfield: 1`

xlocation locvalue

  If specified, proc scatterplot will operate in 1-D mode along Y. The value specifies where the points will be rendered in X.``

ylocation locvalue

  If specified, proc scatterplot will operate in 1-D mode along X. The value specifies where the points will be rendered in Y.``

cluster `yes` | `no`

  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 `yes`.`` 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.``

symbol symboldetails

  If specified, a geometric point symbol will mark data points.`` This specifies the attributes of the symbols to be used.``
  Example: `symbol: style=fill shape=circle fillcolor=red`

linelen n

  If specified, data points will be displayed as lines instead of a dot or other symbol, and the lines will be of length n in absolute units.`` 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 `linedetails`.`` Line length may also be influenced using `sizefield`.`` Line direction may be explicitly controlled using `linedir`.`` Example: `linelen: 0.2`

linedir `h|v|u|r`

  Allows explicit control of direction of line, when `linelen` is used to render lines instead of dots or other symbols.`` `h` = horizontal (centered); `v` = vertical (centered); `u` = upward; `r` = rightward.`` Example: `linedir: v`

text text

  If specified, data points will be displayed using the given text, centered around the data point.`` This attribute may be used with or without a `symbol`.`` Example: `text: A`

rectangle width height `[ outline ]`

  Data points will be displayed using a rectangle centered around the data point of width data units wide and height data units high.`` If `outline` is specified, the rectangles will be outlined with a line (controllable using `linedetails`). The color of the rectangle can be controlled via a datafield (see `symfield`, `symrangefield`, and `dupsleg` below).``
  Example: `rectangle 1 1 outline`
  Example: `rectangle 0.9 0.9`

labelfield dfield

  If specified, data points will be displayed using the contents of data field dfield, 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.``
  Example: `labelfield: 4`

textdetails textdetails

  Details concerning the rendering of point labels.``
  Example: `textdetails: size=6`

linedetails linedetails

  If points are displayed using line segments (`linelen`), this attribute allows control of color, line width, etc.``

legendlabel text

  A label to be associated with the current set of points in the legend.`` proc legend must be executed later in order to render the legend. @NVALUES may be used to signify number of points rendered.`` If proc getdata field names are being used, use of the special symbols `#usexname` (or `#useyname`) causes the field name of `xfield` (or `yfield`) to be automatically used as the legend label (new in 2.04).``
  Example: `legendlabel: Group 4, N=@NVALUES`
  Example: `legendlabel: Round 2`
  Example: `legendlabel: #useyname`

verticaltext `yes` | `no`

  If `yes`, label text will be rendered vertically.`` This might be useful when labels are > 1 character long and data are close together in X.``

sizefield dfield

  Allows the size of point markers or lines to be controlled by a datafield, effectively allowing another variable to be presented.``
  If data points are marked using geometric symbols or text, the value in dfield 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 sizescale attribute may be used to scale the `sizefield` data appropriately.``
  If data points are marked using lines, the value in dfield 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.``

sizescale n

  May be used with `sizefield` 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 area 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.``

clustermethod `2d | horiz | vert | upward | rightward`

  Explicitly control the way that duplicate points will be clustered.`` Default method is `2d` for 2-D scatterplots, `horiz` for 1-D scatterplots where Y location is fixed, and `vert` for 1-D scatterplots where X location is fixed.`` `upward` and `rightward` may be used to string duplicate points upward or rightward to form little bars. `horiz` will cluster duplicate points only horizontally; `vert` will cluster duplicate points only vertically.`` An example of using `clustermethod: upward` to form rows of little bars, is snpmap1
  To represent duplicate points using different symbol colors (etc.) see `dupsleg`.``

clusterfact n

  May be used when `clustering` 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.``

clusterdiff f

  May be used when `clustering` is being done. Two values that are within f of each other will be considered duplicates eligible for clustering. Default value is 0.01.``

clustevery n

  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 nth duplicate encountered.``
  Example: `clustevery: 5` ..would result in a point having 35 duplicates represented using 7 point marks.``

dupsleg `yes | no`

  If `yes` the symbol color, size, shape, etc. will be controlled by the number of duplicate points counted.`` This uses the legend-driven technique . Each legend entry must have a `tag` that is an integer, and a symboldetails entry for `details`.`` 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: dupsleg

symfield dfield

  If specified, the symbol color, size, shape, etc. will be controlled by this data field using the legend-driven technique . If used to control symbols, symbol attributes should be given in the legend entries; if used to control rectangles, colors should be given.``
  Examples: symfld

symrangefield dfield

  Same as `symfield` above, except that numeric range comparison is used when finding the appropriate legend entry, using the legend-driven technique 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 `symrangefield` data field, that legend entry is chosen, and the point will be rendered using the symbol described in that entry.`` Examples: symrangefld and symrangefld

select conditional-expression

  May be used to select data rows for inclusion into the scatterplot.`` Example: `select: @3 = AA`

xrange low high

  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: `xrange: 0 50`

yrange low high

  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: `yrange: 0 50`

clickmapurl url template

  If generating an HTML clickmap , this specifies a url template, and causes the data points (symbol or character) to be mapped.`` This attribute usually contains one or more embedded data field references preceded by double at-sign (@@).`` See HTML clickmap for more details and examples.``
  Example: `clickmapurl: http://abc.com/mycgi?category=@@3`
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` December 10, 2002.