Search


Ploticus > Scripts >

proc lineplot

proc lineplot draws a line plot using the current data set, in the current plotting area. Options include stairstep mode, accumulation mode, instance counting mode, fill mode, rendering of individual data points, and various labeling options. To generate and plot a curve (spline, moving average, etc.) to fit a set of data points, see proc curvefit. See also the gallery lineplot examples.

By default, the drawn curve will connect only valid data points (see also gapmissing below). By default, points and connecting lines lying outside of the plotting area are displayed if possible; however clip may be specified to vertically limit the plotted line to the plotting area.

Attributes

The yfield attribute must be specified. If the data are not already ordered from low to high in X, the sort attribute must be specified.

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

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.

Rendering mode options

fill     color

If specified, the area under the curve will be filled with the given color. See also fillbleed below.

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     no | yes | small | auto | autosmall | autozero

The default is no, meaning that unplottable values encountered in lenfield will be ignored when drawing the curve (the curve will continue uninterrupted). If yes a gap will appear in the curve when unplottable values (such as missing data codes) are encountered in lenfield. small is the same as yes but leaves an extra "hangover" bit of line at each gap, which often looks better. If auto, data gaps will be detected automatically - regularity in X is assumed and a gap will appear when the distance between any two consecutive data points is larger than the distance between the first two data points (or if an unplottable value is encountered). autosmall is the same as auto but leaves an extra bit of line at each gap. autozero (2.33+) causes the line to move to Y=0 where gaps are detected. gapmissing does not give correct results when groupmode is being used.
Example: gapmissing: auto

clip     yes | no

If yes, the plotted line and any rendered points or point labels are clipped (limited) to the plotting area Y range. Default is no, allowing curve to be drawn beyond the Y minima or maxima. (X range limiting is always done, in that the curve will begin with the first in-range data point and end with the last in-range data point.) This attribute does not work with stairstep or fill.

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.

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.

Selecting data rows and controlling beginning / end of curve

select     select expression

Allows data rows to be selected for inclusion using a selection expression.
Example: @@2 = B

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.

lastx     plotvalue

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

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

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)

Legend

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. The \\n 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 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 (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.

Labeling the curve(s)

You can label the curve using the attributes in this section. You can also display and label individual data points (see following section).

label     text

A text label to be displayed near the termination point of the curve. In addition to plain text, the label can contain the embedded word @YFINAL which will give the last Y value plotted. In versions 2.40+ the label can also contain embedded data field specs (eg. @@3) that will give data field contents from the last data row that was plotted.
Example 1: label: @@YFINAL - Control Group
Example 2: label: @@3

labeldetails     textdetails

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

numbers     yes | no | textdetails

If specified as yes or with textdetails specifications, each point will be identified with its value in Y. (Where a textdetails spec is supplied, yes is implied). For stairstep curves, this value is centered between X locations. Note that the ptlabelfield attribute may be used to do this same thing.
Example 1: numbers: yes (uses the defaults)
Example 2: 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).

Data points rendering

The invididual data points may optionally be displayed as symbols lying on the curve (this can sometimes also be done using proc scatterplot).

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 fillcolor=blue

altsymbol     symboldetails
altwhen     select 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. lineplot5 is an example. A maximum of 200 data points can be displayed this way (in versions before 2.33 the limit is 100).

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

Specialized

fillbleed     h

If using fill (above) to fill the area under the curve, this attribute may be set to eliminate tiny gaps in the color fill that may be seen when rendering on some devices (reported on EPS).
Example: fillbleed: 0.005

Variables that are set by proc lineplot

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.