File: lineplot

package info (click to toggle)
ploticus-doc 2.33-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 9,392 kB
ctags: 169
sloc: pascal: 469; makefile: 63; sh: 11
file content (788 lines) | stat: -rw-r--r-- 15,333 bytes
.ig >>
<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.33 Jun'06
     </small><br><a href="../doc/scripthome.html">Scripts</a>
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH proc_lineplot PL "02-JUN-2006   PL ploticus.sourceforge.net"

.ig >>
<center>
<a href="../gallery/sar-cpu.htm"><img src="../gallery/thumbnails/sar-cpu.png" border=0></a>
</center>
.>>

\fBproc lineplot\fR draws a line plot using the
.ig >>
<a href="dataformat.html#currentds">
.>>
\0current data set,
.ig >>
</a>
.>>
in the 
.ig >>
<a href="areadef.html">
.>>
\0current plotting area.
.ig >>
</a>
.>>
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
.ig >>
<a href="curvefit.html">
.>>
\0proc curvefit.
.ig >>
</a>
.>>
See also the
.ig >>
<a href="../gallery/gall.lineplot.html">
.>>
\0gallery lineplot examples.
.ig >>
</a>
.>>
.LP
By default, the drawn curve will connect only valid data points (see also \fCgapmissing\fR below).
By default, points and connecting lines lying outside of the plotting area 
are displayed if possible; however \fCclip\fR may be specified to vertically limit the plotted line
to the plotting area.


.ig >>
<br><br><br>
.>>

.SH Attributes
The \fCyfield\fR attribute \fBmust\fR be specified.
If the data are not already ordered from low to high in X, the \fCsort\fR attribute must be specified.

.ig >>
<br><br>
.>>

.LP
\fByfield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
Data field to use for Y values.
Example: \fCyfield: 1\fR

.ig >>
<br><br>
.>>

.LP
\fBxfield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
Data field to use for X values.
If not specified, sequential unit locations in X will be used.


.ig >>
<br><br>
.>>

.LP
\fBlinedetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
.IP \0
Line details for the curve.
Example: \fClinedetails: color=red width=2.0 style=2\fR

.ig >>
<br><br>
.>>
.LP
\fBsort\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, data will be ordered on X before plotting.
This should be done if data are not already ordered in X.
Default is \fCno\fR.


.ig >>
<br><br><br>
.>>

.SH Rendering mode options
.LP
\fBfill\fR  
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="color.html">
.>>
\0color
.ig >>
</a>
.>>
.IP \0
If specified, the area under the curve will be filled with the given \fCcolor\fR.



.ig >>
<br><br>
.>>
.LP
\fBstairstep\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, curve will be drawn stairstep style, as is often seen in
life table plots.
Default is \fCno\fR.
Example: \fCstairstep: yes\fR



.ig >>
<br><br>
.>>
.LP
\fBgapmissing\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCno\fR | \fCyes\fR | \fCsmall\fR | \fCauto\fR  | \fCautosmall\fR | \fCautozero\fR
.IP \0
The default is \fCno\fR, meaning that unplottable values encountered in \fClenfield\fR will be ignored when 
drawing the curve (the curve will continue uninterrupted).
If \fCyes\fR a gap will appear in the curve when unplottable values (such as missing data codes) are encountered
in \fClenfield\fR.  \fCsmall\fR is the same as \fCyes\fR but leaves an extra "hangover" bit of line at each gap, which often looks better.
If \fCauto\fR, 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).  \fCautosmall\fR is the same as \fCauto\fR but leaves an extra bit of line at each gap.
\fCautozero\fR (2.33+) causes the line to move to Y=0 where gaps are detected.
\fCgapmissing\fR does not give correct results when \fCgroupmode\fR is being used.
.br
Example: \fCgapmissing: auto\fR


.ig >>
<br><br>
.>>
.LP
\fBclip\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, the plotted line and any rendered points or point labels are clipped 
(limited) to the plotting area Y range.  Default is \fCno\fR, 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 \fCstairstep\fR or \fCfill\fR.



.ig >>
<br><br>
.>>

.LP
\fBaccum\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, Y values will be plotted cumulatively, effectively summing them.
Default is \fCno\fR.
Example: \fCaccum: yes\fR


.ig >>
<br><br>
.>>
.LP
\fBinstancemode\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, 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 \fCaccum: yes\fR and \fCgroupmode: yes\fR.
Not compatible with \fCyfield\fR.  Default is \fCno\fR.


.ig >>
<br><br>
.>>
.LP
\fBgroupmode\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, adjacent data rows having the same X value will be summed.
Default is \fCno\fR.  Not compatible with \fCptlabelfield\fR.


.ig >>
<br><br>
.>>
.LP
\fBstairoverbars\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes \fR| \fCno\fR
.IP \0
This allows proper rendering of \fCstairstep\fR lineplot superimposed upon
a bar graph.  It effectively shifts the line plot 0.5 units to the right.
Default is \fCno\fR.


.ig >>
<br><br><br>
.>>

.SH Selecting data rows and controlling beginning / end of curve

.LP
\fBselect\fR  
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="select.html">
.>>
\0select expression
.ig >>
</a>
.>>
.IP \0
Allows data rows to be selected for inclusion using a selection expression.
.br
Example: \fC@@2 = B\fR

.ig >>
<br><br>
.>>

.LP
\fBlinerange\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fImin\fR 
.ig >>
&nbsp; &nbsp;
.>>
[\fImax\fR]
.IP \0
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 \fCrelax_xrange\fR).
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: \fClinerange: 1\fR


.ig >>
<br><br>
.>>
.LP
\fBfirstpoint\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#plotvalue">
.>>
\0x
.ig >>
</a>
.>>
.ig >>
<a href="attributetypes.html#plotvalue">
.>>
\0y
.ig >>
</a>
.>>
.IP \0
Unconditionally specify the first point in the curve.
\fIx\fR and \fIy\fR 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.
.br
Example: \fCfirstpoint: 0 0\fR


.ig >>
<br><br>
.>>
.LP
\fBxstart\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#plotvalue">
.>>
\0x
.ig >>
</a>
.>>
.IP \0
When plotting at consecutive points in X (no \fCxfield\fR 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.
\fIx\fR must be a plottable value in X.
You can also use \fCfirstpoint\fR (above) to do this same thing.


.ig >>
<br><br>
.>>
.LP
\fBlastx\fR  
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#plotvalue">
.>>
\0plotvalue
.ig >>
</a>
.>>
.IP \0
If specified, the curve will be extended to this point in X unconditionally,
using the most recent Y.  



.ig >>
<br><br>
.>>
.LP
\fBrelax_xrange\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes | no\fR
.IP \0
Normally, only data points lying within the plotting area X range
(or \fClinerange\fR 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 \fCno\fR.


.ig >>
<br><br>
.>>
.LP
\fBlastseglen\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#lenvalue">
.>>
\0lenvalue
.ig >>
</a>
.>>
.IP \0
If specified, an additional segment of length \fIlenvalue\fR is appended 
to the curve after the last plottable point.
Originally intended to improve appearance of \fCstairstep\fR curves,
it may be used in any lineplot mode.
If \fIlenvalue\fR ends in \fC(s)\fR it is taken as a scaled distance;
otherwise it is assumed to be an absolute distance.
Example: \fClastseglen: 3(s)\fR

.ig >>
<br><br><br>
.>>

.SH Legend
.LP
\fBlegendlabel\fR  
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0text
.ig >>
</a>
.>>
.IP \0
A label to be associated with the current lineplot in the legend.
\fBproc legend\fR must be executed later in order to 
render the legend.  
The \fC\\n\fR 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
.ig >>
<a href="getdata.html">
.>>
\0proc getdata field names
.ig >>
</a>
.>>
are being used,
the special symbol \fC#usefname\fR causes the field name of \fCyfield\fR
to be automatically used as the legend label (2.04+).
.br
Example: \fClegendlabel: Northeast region\fR
.br
Example: \fClegendlabel: #usefname\fR

.ig >>
<br><br>
.>>

.LP
\fBlegendsampletype\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCsymbol\fR | \fCline+symbol\fR
.IP \0
When a line with point symbols is being done, this controls the corresponding
legend sample.  You can choose \fCsymbol\fR for only the symbol to be displayed
in the legend, or \fCline+symbol\fR for both line and symbol to be displayed
in the legend.  Default is \fCsymbol\fR.

.ig >>
<br><br><br>
.>>

.SH Labeling the curve(s)

.LP
\fBlabel\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0text
.ig >>
</a>
.>>
.IP \0
A text label to be displayed near the termination point of the curve.
last Y value plotted.
Example: \fClabel: @@YFINAL - Control Group\fR


.ig >>
<br><br>
.>>
.LP
\fBlabeldetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Text details for the label.  Example: \fClabeldetails: adjust=0.2,0 color=green\fR

 
.ig >>
<br><br>
.>>
.LP
\fBnumbers\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes \fR| \fCno \fR| 
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
If specified as \fCyes\fR or with textdetails specifications, each point will 
be identified with its value in Y.
(Where a textdetails spec is supplied, \fCyes\fR is implied).
For \fCstairstep\fR curves, this value is centered between X locations.
Note that the \fCptlabelfield\fR attribute may be used to do this same thing.
.br
Example 1: \fCnumbers: yes\fR (uses the defaults)
.br
Example 1: \fCnumbers: adjust=0.0,0.2 size=8\fR

.ig >>
<br><br>
.>>
.LP
\fBnumbersformat\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#string">
.>>
\0string
.ig >>
</a>
.>>
.IP \0
Format to be used with the \fBnumbers\fR attribute or in the
\fBlabel\fR if @@YFINAL is used.  
For ordinary numbers it is a "C" printf style format specifier.
Example: \fCnumbersformat: %3.1\fR would yield numbers like 2.1.
.br
If using special units in Y, \fCnumbersformat\fR can have
other values (see AXIS stubformat attribute).

.ig >>
<br><br><br>
.>>
.SH Data points rendering
.LP
The invididual data points may optionally be displayed as symbols lying on the curve
(this can sometimes also be done using proc scatterplot).

.ig >>
<br><br>
.>>
.LP
\fBpointsymbol\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
.IP \0
If specified, causes each data point to be marked with a geometric point symbol
superimposed on top of the curve.
Not applicable to \fCstairstep\fR curves.
Example: \fCpointsymbol: shape=triangle fillcolor=blue\fR

.ig >>
<br><br>
.>>
.LP
\fBaltsymbol\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="symboldetails.html">
.>>
\0symboldetails
.ig >>
</a>
.>>
.br
\fBaltwhen\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="select.html">
.>>
\0select expression
.ig >>
</a>
.>>
.IP \0
If both of these are specified, allows an alternate symbol to be used when the condition
specified in \fCaltwhen\fR is met.  This may be used to highlight
certain points, or to use an alternate symbol when two lines overlap.
.ig >>
<a href="../gallery/lineplot5.htm">
.>>
\0lineplot5
.ig >>
</a>
.>>
is an example.
A maximum of 200 data points can be displayed this way (in versions before 2.33 the limit is 100).

.ig >>
<br><br>
.>>
.LP
\fBptlabelfield\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0dfield
.ig >>
</a>
.>>
.IP \0
If specified, causes each data point to be labeled with the contents of
this data field.
Example: \fCptlabelfield: 3\fR

.ig >>
<br><br>
.>>
.LP
\fBptlabeldetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Text details for point label.
Example: \fCptlabeldetails: adjust=0.2,0 size=7 align=L\fR

.ig >>
<br><br>
.>>
.LP
\fBptlabelrange\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fImin\fR 
.ig >>
&nbsp; &nbsp;
.>>
[\fI max\fR]
.IP \0
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: \fCptlabelrange 1\fR

.ig >>
<br><br><br>
.>>

.SH Variables that are set by proc lineplot
\fBproc lineplot\fR will set these variables:
.IP \0
\fBXSTART\fR and \fBYSTART\fR - location where the curve started, in data units.
.IP \0
\fBXFINAL\fR and \fBYFINAL\fR - location where the curve ended, in data units.

.ig >>
<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 &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif"> 
</center>
</td></tr>
</table>
<br>
<center>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
.>>