ploticus: proc lineplot

## proc lineplot | Welcome Gallery Handbook |
| Manual page for proc_lineplot(PL)

## DESCRIPTION

proc lineplot uses data to draw a line plot.`` The plot is drawn beginning with first data record, working to the last one.``

## FEATURES

Complete control over color, width, and dash style of line.`` Options include stairstep lines, point symbols, accumulation, and various labeling options.`` In addition, the area under the curve may be filled, and the range of the line may be controlled.``

## EXAMPLES

See the Gallery Lineplot examples

## UNPLOTTABLE DATA

By default, the drawn curve will connect only valid data points.`` However if `gapmissing` is specified, invalid values will cause a gap in the curve.`` By default, points and connecting lines lying outside of the plotting area are displayed if possible; however `clip` may be specified to limit the plotted line to 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

This proc can operate in one of these modes:

Y only (points "where they fall"):

  By specifying `yfield` but not `xfield`, Y values are plotted at consecutive unit locations in X.``

X and Y:

  By specifying both `yfield` and `xfield`, points are plotted at the X,Y locations.``

Counting of instances:

  By specifying `instancemode: yes` and `accum: yes` and no `yfield`, instances are counted, that is, a Y value of 1 is used, and the results are accumulated.``

## VARIABLES THAT ARE SET

proc lineplot will set these variables:

  XSTART and YSTART - location where the curve started, in data units.``
  XFINAL and YFINAL - location where the curve ended, in data units.``

## MANDATORY ATTRIBUTE

The `yfield` attribute MUST be specified.`` If the data are not already ordered in X, the `sort` attribute must be specified.``

## ATTRIBUTES

yfield dfield

  Data field to use for Y values.`` Example: `yfield: 1`

xfield dfield

  Data field to use for X values.`` If not specified, sequential unit locations in X will be used.``

linedetails linedetails

  Line details for the curve.`` Example: `linedetails: color=red width=2.0 style=2`

fill color

  If specified, the area under the curve will be filled with the given `color`.``

stairstep `yes` | `no`

  If `yes`, curve will be drawn stairstep style, as is often seen in life table plots.`` Default is `no`.`` Example: `stairstep: yes`

gapmissing `yes` | `small` | `no`

  If `yes` or `small`, unplottable values such as missing data codes will cause a gap in the curve.`` The default is `no` (no gap for unplottable data values).`` `small` is the same as `yes`, except that a quarter-length overhang is attached to the previous point, resulting in a smaller gap (often useful with `stairstep` curves).`` `gapmissing` does not give correct results when `groupmode` is being used.``

clip `yes` | `no`

  If `yes`, the plotted line and any rendered points or point labels are clipped (limited) to the plotting area rectangle. Does not work with `stairstep` or `fill`.``

lastseglen lenvalue

  If specified, an additional segment of length lenvalue is appended to the curve after the last plottable point.`` Originally intended to improve appearance of `stairstep` curves, it may be used in any lineplot mode.`` If lenvalue ends in `(s)` it is taken as a scaled distance; otherwise it is assumed to be an absolute distance.`` Example: `lastseglen: 3(s)`

lastx plotvalue

  If specified, the curve will be extended to this point in X unconditionally, using the most recent Y.

sort `yes` | `no`

  If `yes`, data will be ordered on X before plotting.`` This should be done if data are not already ordered in X.`` Default is `no`.``

accum `yes` | `no`

  If `yes`, Y values will be plotted cumulatively, effectively summing them.`` Default is `no`.`` Example: `accum: yes`

instancemode `yes` | `no`

  If `yes`, no Y data is used; instead each data row is counted as 1.`` This may be useful in plotting cumulative occurances over time.`` Usually used with `accum: yes` and `groupmode: yes`.`` Not compatible with `yfield`. Default is `no`.``

groupmode `yes` | `no`

  If `yes`, adjacent data rows having the same X value will be summed.`` Default is `no`. Not compatible with `ptlabelfield`.``

linerange min [max]

  Controls the range (in scaled units) within which the curve will be rendered.`` If not specified, all data points within the plotting area bounds will be rendered (see also `relax_xrange`).`` Data points falling outside this range will not be rendered.`` If only one value is given, it will be taken as the range minima and the maxima will be the plottable maxima.`` If accumulation is being done, points outside the range will contribute to the accumulated total.`` Example: `linerange: 1`

firstpoint x y

  Unconditionally specify the first point in the curve.`` x and y are plottable values in X and Y, respectively.`` Often used to start a curve at (0,0) even though the data do not include (0,0) as a data point.``
  Example: `firstpoint: 0 0`

xstart x

  When plotting at consecutive points in X (no `xfield` specified), this attribute specifies where to begin the curve. Normally this attribute is not specified and the curve begins at the plot area X minima.`` x must be a plottable value in X.`` You can also use `firstpoint` (above) to do this same thing.``

relax_xrange `yes` I `no`

  Normally, only data points lying within the plotting area X range (or `linerange` if given), are rendered. Points below the X minima, or above the X maxima, are omitted. This attribute allows this behavior can be turned off, so that all data points are rendered, even if outside the range.`` Default is `no`.``

stairoverbars `yes` | `no`

  This allows proper rendering of `stairstep` lineplot superimposed upon a bar graph. It effectively shifts the line plot 0.5 units to the right.`` Default is `no`.``

select conditional-expression

  Allows data rows to be selected for inclusion using a selection expression.``

## Attributes pertaining to labeling

label text

  A text label to be displayed near the termination point of the curve.`` last Y value plotted.`` Example: `label: @@YFINAL - Control Group`

labeldetails textdetails

  Text details for the label. Example: `labeldetails: adjust=0.2,0 color=green`

legendlabel text

  A label to be associated with the current lineplot in the legend.`` proc legend must be executed later in order to render the legend.`` If proc getdata field names are being used, the special symbol `#usefname` causes the field name of `yfield` to be automatically used as the legend label (new in 2.04).``
  Example: `legendlabel: Northeast region`
  Example: `legendlabel: #usefname`

legendsampletype `symbol` | `line+symbol`

  When a line with point symbols is being done, this controls the corresponding legend sample. You can choose `symbol` for only the symbol to be displayed in the legend, or `line+symbol` for both line and symbol to be displayed in the legend. Default is `symbol`.``

numbers `yes` | `no` | textdetails

  If specified, causes each point to be identified with its value in Y.`` For `stairstep` curves, this value is centered between X locations.``
  Example 1: `numbers: yes` (uses the defaults)
  Example 1: `numbers: adjust=0.0,0.2 size=8`

numbersformat string

  Format to be used with the numbers attribute or in the label if @@YFINAL is used. For ordinary numbers it is a "C" printf style format specifier.`` Example: `numbersformat: %3.1` would yield numbers like 2.1.``
  If using special units in Y, `numbersformat` can have other values (see AXIS stubformat attribute).``

## Attributes pertaining to data points rendering

The invididual data points may optionally be displayed in a number of ways.``

pointsymbol symboldetails

  If specified, causes each data point to be marked with a geometric point symbol superimposed on top of the curve.`` Not applicable to `stairstep` curves.`` Example: `pointsymbol: shape=triangle color=blue`

altsymbol symboldetails
altwhen conditional-expression

  If both of these are specified, allows an alternate symbol to be used when the condition specified in `altwhen` is met. This may be used to highlight certain points, or to use an alternate symbol when two lines overlap.`` gallery/lineplot5 is an example.``

ptlabelfield dfield

  If specified, causes each data point to be labeled with the contents of this data field.`` Example: `ptlabelfield: 3`

ptlabeldetails textdetails

  Text details for point label.`` Example: `ptlabeldetails: adjust=0.2,0 size=7 align=L`

ptlabelrange min [ max]

  The range within which point marks, labels and number displays are to be rendered.`` This may be useful in suppressing point labels for X=0.`` If only one value is given, it will be taken as the range minima and the maxima will be the plottable maxima.`` If not specified, all data points will be labeled.`` Example: `ptlabelrange 1`
  data display engine
  Copyright Steve Grubb

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