<html> <head> <!-- This file has been generated by unroff 1.0, 03/11/09 12:56:17. --> <!-- Do not edit! --> <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 lineplot</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 lineplot</h2></td> <td align=right> <small> <a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br> Version 2.41 Mar2009 </small><br><a href="../doc/scripthome.html">Scripts</a> <td></tr></table> </td></tr> <td> <br> <br> <title>Manual page for proc_lineplot(PL)</title> </head> <body> <center> <a href="../gallery/sar-cpu.htm"><img src="../gallery/thumbnails/sar-cpu.png" border=0></a> </center> <b>proc lineplot</b> draws a line plot using the <a href="dataformat.html#currentds"> current data set, </a> in the <a href="areadef.html"> current plotting area.<tt> </tt> </a> Options include stairstep mode, accumulation mode, instance counting mode, fill mode, rendering of individual data points, and various labeling options.<tt> </tt> To generate and plot a curve (spline, moving average, etc.) to fit a set of data points, see <a href="curvefit.html"> proc curvefit.<tt> </tt> </a> See also the <a href="../gallery/gall.lineplot.html"> gallery lineplot examples.<tt> </tt> </a> <p> By default, the drawn curve will connect only valid data points (see also <tt>gapmissing</tt> below).<tt> </tt> By default, points and connecting lines lying outside of the plotting area are displayed if possible; however <tt>clip</tt> may be specified to vertically limit the plotted line to the plotting area.<tt> </tt> <br><br><br> <h2>Attributes</h2> The <tt>yfield</tt> attribute <b>must</b> be specified.<tt> </tt> If the data are not already ordered from low to high in X, the <tt>sort</tt> attribute must be specified.<tt> </tt> <br><br> <p> <b>yfield</b> <a href="attributetypes.html#dfield"> dfield </a> <dl> <dt> <dd> Data field to use for Y values.<tt> </tt> Example: <tt>yfield: 1</tt> <br><br> </dl> <p> <b>xfield</b> <a href="attributetypes.html#dfield"> dfield </a> <dl> <dt> <dd> Data field to use for X values.<tt> </tt> If not specified, sequential unit locations in X will be used.<tt> </tt> <br><br> </dl> <p> <b>linedetails</b> <a href="linedetails.html"> linedetails </a> <dl> <dt> <dd> Line details for the curve.<tt> </tt> Example: <tt>linedetails: color=red width=2.0 style=2</tt> <br><br> </dl> <p> <b>sort</b> <tt>yes</tt> | <tt>no</tt> <dl> <dt> <dd> If <tt>yes</tt>, data will be ordered on X before plotting.<tt> </tt> This should be done if data are not already ordered in X.<tt> </tt> Default is <tt>no</tt>.<tt> </tt> <br><br><br> </dl> <h2>Rendering mode options</h2> <p> <b>fill</b> <a href="color.html"> color </a> <dl> <dt> <dd> If specified, the area under the curve will be filled with the given <tt>color</tt>.<tt> </tt> See also fillbleed below.<tt> </tt> <br><br> </dl> <p> <b>stairstep</b> <tt>yes</tt> | <tt>no</tt> <dl> <dt> <dd> If <tt>yes</tt>, curve will be drawn stairstep style, as is often seen in life table plots.<tt> </tt> Default is <tt>no</tt>.<tt> </tt> Example: <tt>stairstep: yes</tt> <br><br> </dl> <p> <b>gapmissing</b> <tt>no</tt> | <tt>yes</tt> | <tt>small</tt> | <tt>auto</tt> | <tt>autosmall</tt> | <tt>autozero</tt> <dl> <dt> <dd> The default is <tt>no</tt>, meaning that unplottable values encountered in <tt>lenfield</tt> will be ignored when drawing the curve (the curve will continue uninterrupted).<tt> </tt> If <tt>yes</tt> a gap will appear in the curve when unplottable values (such as missing data codes) are encountered in <tt>lenfield</tt>. <tt>small</tt> is the same as <tt>yes</tt> but leaves an extra "hangover" bit of line at each gap, which often looks better.<tt> </tt> If <tt>auto</tt>, 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). <tt>autosmall</tt> is the same as <tt>auto</tt> but leaves an extra bit of line at each gap.<tt> </tt> <tt>autozero</tt> (2.33+) causes the line to move to Y=0 where gaps are detected.<tt> </tt> <tt>gapmissing</tt> does not give correct results when <tt>groupmode</tt> is being used.<tt> </tt> <br> Example: <tt>gapmissing: auto</tt> <br><br> </dl> <p> <b>clip</b> <tt>yes</tt> | <tt>no</tt> <dl> <dt> <dd> If <tt>yes</tt>, the plotted line and any rendered points or point labels are clipped (limited) to the plotting area Y range. Default is <tt>no</tt>, allowing curve to be drawn beyond the Y minima or maxima.<tt> </tt> (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 <tt>stairstep</tt> or <tt>fill</tt>.<tt> </tt> <br><br> </dl> <p> <b>accum</b> <tt>yes</tt> | <tt>no</tt> <dl> <dt> <dd> If <tt>yes</tt>, Y values will be plotted cumulatively, effectively summing them.<tt> </tt> Default is <tt>no</tt>.<tt> </tt> Example: <tt>accum: yes</tt> <br><br> </dl> <p> <b>instancemode</b> <tt>yes</tt> | <tt>no</tt> <dl> <dt> <dd> If <tt>yes</tt>, no Y data is used; instead each data row is counted as 1.<tt> </tt> This may be useful in plotting cumulative occurances over time.<tt> </tt> Usually used with <tt>accum: yes</tt> and <tt>groupmode: yes</tt>.<tt> </tt> Not compatible with <tt>yfield</tt>. Default is <tt>no</tt>.<tt> </tt> <br><br> </dl> <p> <b>groupmode</b> <tt>yes</tt> | <tt>no</tt> <dl> <dt> <dd> If <tt>yes</tt>, adjacent data rows having the same X value will be summed.<tt> </tt> Default is <tt>no</tt>. Not compatible with <tt>ptlabelfield</tt>.<tt> </tt> <br><br> </dl> <p> <b>stairoverbars</b> <tt>yes </tt>| <tt>no</tt> <dl> <dt> <dd> This allows proper rendering of <tt>stairstep</tt> lineplot superimposed upon a bar graph. It effectively shifts the line plot 0.5 units to the right.<tt> </tt> Default is <tt>no</tt>.<tt> </tt> <br><br><br> </dl> <h2>Selecting data rows and controlling beginning / end of curve</h2> <p> <b>select</b> <a href="select.html"> select expression </a> <dl> <dt> <dd> Allows data rows to be selected for inclusion using a selection expression.<tt> </tt> <br> Example: <tt>@@2 = B</tt> <br><br> </dl> <p> <b>linerange</b> <i>min</i> [<i>max</i>] <dl> <dt> <dd> Controls the range (in scaled units) within which the curve will be rendered.<tt> </tt> If not specified, all data points within the plotting area bounds will be rendered (see also <tt>relax_xrange</tt>).<tt> </tt> Data points falling outside this range will not be rendered.<tt> </tt> If only one value is given, it will be taken as the range minima and the maxima will be the plottable maxima.<tt> </tt> If accumulation is being done, points outside the range will contribute to the accumulated total.<tt> </tt> Example: <tt>linerange: 1</tt> <br><br> </dl> <p> <b>firstpoint</b> <a href="attributetypes.html#plotvalue"> x </a> <a href="attributetypes.html#plotvalue"> y </a> <dl> <dt> <dd> Unconditionally specify the first point in the curve.<tt> </tt> <i>x</i> and <i>y</i> are plottable values in X and Y, respectively.<tt> </tt> Often used to start a curve at (0,0) even though the data do not include (0,0) as a data point.<tt> </tt> <br> Example: <tt>firstpoint: 0 0</tt> <br><br> </dl> <p> <b>xstart</b> <a href="attributetypes.html#plotvalue"> x </a> <dl> <dt> <dd> When plotting at consecutive points in X (no <tt>xfield</tt> 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.<tt> </tt> <i>x</i> must be a plottable value in X.<tt> </tt> You can also use <tt>firstpoint</tt> (above) to do this same thing.<tt> </tt> <br><br> </dl> <p> <b>lastx</b> <a href="attributetypes.html#plotvalue"> plotvalue </a> <dl> <dt> <dd> If specified, the curve will be extended to this point in X unconditionally, using the most recent Y. <br><br> </dl> <p> <b>relax_xrange</b> <tt>yes | no</tt> <dl> <dt> <dd> Normally, only data points lying within the plotting area X range (or <tt>linerange</tt> 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.<tt> </tt> Default is <tt>no</tt>.<tt> </tt> <br><br> </dl> <p> <b>lastseglen</b> <a href="attributetypes.html#lenvalue"> lenvalue </a> <dl> <dt> <dd> If specified, an additional segment of length <i>lenvalue</i> is appended to the curve after the last plottable point.<tt> </tt> Originally intended to improve appearance of <tt>stairstep</tt> curves, it may be used in any lineplot mode.<tt> </tt> If <i>lenvalue</i> ends in <tt>(s)</tt> it is taken as a scaled distance; otherwise it is assumed to be an absolute distance.<tt> </tt> Example: <tt>lastseglen: 3(s)</tt> <br><br><br> </dl> <h2>Legend</h2> <p> <b>legendlabel</b> <a href="attributetypes.html#text"> text </a> <dl> <dt> <dd> A label to be associated with the current lineplot in the legend.<tt> </tt> <b>proc legend</b> must be executed later in order to render the legend. The <tt>\n</tt> 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+).<tt> </tt> If <a href="getdata.html"> proc getdata field names </a> are being used, the special symbol <tt>#usefname</tt> causes the field name of <tt>yfield</tt> to be automatically used as the legend label (2.04+).<tt> </tt> <br> Example: <tt>legendlabel: Northeast region</tt> <br> Example: <tt>legendlabel: #usefname</tt> <br><br> </dl> <p> <b>legendsampletype</b> <tt>symbol</tt> | <tt>line+symbol</tt> <dl> <dt> <dd> When a line with point symbols is being done, this controls the corresponding legend sample. You can choose <tt>symbol</tt> for only the symbol to be displayed in the legend, or <tt>line+symbol</tt> for both line and symbol to be displayed in the legend. Default is <tt>symbol</tt>.<tt> </tt> <br><br><br> </dl> <h2>Labeling the curve(s)</h2> You can label the curve using the attributes in this section.<tt> </tt> You can also display and label individual data points (see following section).<tt> </tt> <br><br> <p> <b>label</b> <a href="attributetypes.html#text"> text </a> <dl> <dt> <dd> A text label to be displayed near the termination point of the curve.<tt> </tt> 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.<tt> </tt> <br> Example 1: <tt>label: @@YFINAL - Control Group</tt> <br> Example 2: <tt>label: @@3</tt> <br><br> </dl> <p> <b>labeldetails</b> <a href="textdetails.html"> textdetails </a> <dl> <dt> <dd> Text details for label. Example: <tt>labeldetails: adjust=0.2,0 color=green</tt> <br><br> </dl> <p> <b>numbers</b> <tt>yes </tt>| <tt>no </tt>| <a href="textdetails.html"> textdetails </a> <dl> <dt> <dd> If specified as <tt>yes</tt> or with textdetails specifications, each point will be identified with its value in Y.<tt> </tt> (Where a textdetails spec is supplied, <tt>yes</tt> is implied).<tt> </tt> For <tt>stairstep</tt> curves, this value is centered between X locations.<tt> </tt> Note that the <tt>ptlabelfield</tt> attribute may be used to do this same thing.<tt> </tt> <br> Example 1: <tt>numbers: yes</tt> (uses the defaults) <br> Example 2: <tt>numbers: adjust=0.0,0.2 size=8</tt> <br><br> </dl> <p> <b>numbersformat</b> <a href="attributetypes.html#string"> string </a> <dl> <dt> <dd> Format to be used with the <b>numbers</b> attribute or in the <b>label</b> if @@YFINAL is used. For ordinary numbers it is a "C" printf style format specifier.<tt> </tt> Example: <tt>numbersformat: %3.1</tt> would yield numbers like 2.1.<tt> </tt> <br> If using special units in Y, <tt>numbersformat</tt> can have other values (see AXIS stubformat attribute).<tt> </tt> <br><br><br> </dl> <h2>Data points rendering</h2> <p> The invididual data points may optionally be displayed as symbols lying on the curve (this can sometimes also be done using proc scatterplot).<tt> </tt> <br><br> <p> <b>pointsymbol</b> <a href="symboldetails.html"> symboldetails </a> <dl> <dt> <dd> If specified, causes each data point to be marked with a geometric point symbol superimposed on top of the curve.<tt> </tt> Not applicable to <tt>stairstep</tt> curves.<tt> </tt> Example: <tt>pointsymbol: shape=triangle fillcolor=blue</tt> <br><br> </dl> <p> <b>altsymbol</b> <a href="symboldetails.html"> symboldetails </a> <br> <b>altwhen</b> <a href="select.html"> select expression </a> <dl> <dt> <dd> If both of these are specified, allows an alternate symbol to be used when the condition specified in <tt>altwhen</tt> is met. This may be used to highlight certain points, or to use an alternate symbol when two lines overlap.<tt> </tt> <a href="../gallery/lineplot5.htm"> lineplot5 </a> is an example.<tt> </tt> A maximum of 200 data points can be displayed this way (in versions before 2.33 the limit is 100).<tt> </tt> <br><br> </dl> <p> <b>ptlabelfield</b> <a href="attributetypes.html#dfield"> dfield </a> <dl> <dt> <dd> If specified, causes each data point to be labeled with the contents of this data field.<tt> </tt> Example: <tt>ptlabelfield: 3</tt> <br><br> </dl> <p> <b>ptlabeldetails</b> <a href="textdetails.html"> textdetails </a> <dl> <dt> <dd> Text details for point label.<tt> </tt> Example: <tt>ptlabeldetails: adjust=0.2,0 size=7 align=L</tt> <br><br> </dl> <p> <b>ptlabelrange</b> <i>min</i> [<i> max</i>] <dl> <dt> <dd> The range within which point marks, labels and number displays are to be rendered.<tt> </tt> This may be useful in suppressing point labels for X=0.<tt> </tt> If only one value is given, it will be taken as the range minima and the maxima will be the plottable maxima.<tt> </tt> If not specified, all data points will be labeled.<tt> </tt> Example: <tt>ptlabelrange 1</tt> <br><br><br> </dl> <h2>Specialized</h2> <p> <b>fillbleed</b> h <dl> <dt> <dd> If using <tt>fill</tt> (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).<tt> </tt> <br> Example: <tt>fillbleed: 0.005</tt> <br><br><br> </dl> <h2>Variables that are set by proc lineplot</h2> <b>proc lineplot</b> will set these variables: <dl> <dt> <dd> <b>XSTART</b> and <b>YSTART</b> - location where the curve started, in data units.<tt> </tt> <dt> <dd> <b>XFINAL</b> and <b>YFINAL</b> - location where the curve ended, in data units.<tt> </tt> <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 <br> <a href="../doc/Copyright.html">Copyright Steve Grubb</a> <br> <br> <center> <img src="../gallery/all.gif"> </center> </td></tr> </table> <br> <center> <table><tr><td> Ploticus is hosted at http://ploticus.sourceforge.net</td><td> </td><td> <a href="http://sourceforge.net/projects/ploticus"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=38453&type=12" width="120" height="30" border="0" alt="Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a> </td></tr></table> </center> </dl> <p><hr> Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 11, 2009. </body> </html>