.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
-->
</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>
  <a href="../doc/Welcome.html">Welcome</a> &nbsp; &nbsp;
  <a href="../gallery/index.html">Gallery</a> &nbsp; &nbsp;
  <a href="../doc/Contents.html">Handbook</a> 
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH proc_lineplot PL "14-DEC-2001   PL ploticus.sourceforge.net"

.ig >>
<center>
<img src="../gallery/lineplot0.gif">
</center>
.>>

.SH DESCRIPTION
\fBproc lineplot\fR uses data to draw a line plot.
The plot is drawn beginning with first data record, working to the last one.

.ig >>
<br><br><br>
.>>
.SH 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.

.ig >>
<br><br><br>
.>>
.SH EXAMPLES
See the Gallery Lineplot examples
.ig >>
<a href="../gallery/gall.lineplot.html"><img src="../gallery/btn/here.gif"></a>
.>>

.ig >>
<br><br><br>
.>>
.SH UNPLOTTABLE DATA
By default, the drawn curve will connect only plottable points.
However if \fCgapmissing\fR is specified, unplottable values will cause a gap in the curve.
Points and connecting lines lying outside of the plotting area 
are displayed if possible.

.ig >>
<br><br><br>
.>>
.SH PREREQUISITES
A plotting area must be set up using \fBproc areadef\fR 
and \fBproc getdata\fR must be executed to 
access or define some data.
The data must be ordered in X.

.ig >>
<br><br><br>
.>>
.SH MODES 
This proc can operate in one of these modes:
.LP
\fBY only (points "where they fall"):\fR
.IP
By specifying \fCyfield\fR but not \fCxfield\fR, Y values are plotted
at consecutive unit locations in X.
.LP
\fBX and Y:\fR
.IP 
By specifying both \fCyfield\fR and \fCxfield\fR,
points are plotted at the X,Y locations.
.LP
\fBCounting of instances:\fR
.IP 
By specifying \fCinstancemode: yes\fR and \fCaccum: yes\fR 
and no \fCyfield\fR, instances are counted, that is, a 
Y value of 1 is used, and the results are accumulated.

.ig >>
<br><br><br>
.>>
.SH VARIABLES THAT ARE SET
\fBproc lineplot\fR will set these variables:
.IP
\fBXSTART\fR and \fBYSTART\fR - location where the curve started, in data units.
.IP
\fBXFINAL\fR and \fBYFINAL\fR - location where the curve ended, in data units.

.ig >>
<br><br><br>
.>>
.SH MANDATORY ATTRIBUTE
The \fCyfield\fR attribute MUST be specified.

.ig >>
<br><br><br>
.>>
.SH ATTRIBUTES
.LP
\fByfield\fR 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\fI dfield \fR
.ig >>
</a>
.>>
.IP
Data field to use for Y values.
Example: \fCyfield: 1\fR

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

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

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


.LP
\fBstairstep\fR \fCyes\fR | \fCno\fR
.IP
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


.LP
\fBgapmissing\fR  \fCyes\fR | \fCsmall\fR | \fCno\fR
.IP
If \fCyes\fR or \fCsmall\fR, unplottable values such as missing data codes
will cause a gap in the curve.
The default is \fCno\fR (no gap for unplottable data values).
\fCsmall\fR is the same as \fCyes\fR, except that 
a quarter-length overhang is attached to the previous point, resulting in a smaller gap
(often useful with \fCstairstep\fR curves).

.LP
\fBlastseglen\fR 
.ig >>
<a href="attributetypes.html#lenvalue">
.>>
\fI lenvalue \fR
.ig >>
</a>
.>>
.IP
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

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

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

.LP
\fBinstancemode\fR \fCyes\fR | \fCno\fR
.IP
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.

.LP
\fBgroupmode\fR  \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, adjacent data rows having the same X value will be summed.
Default is \fCno\fR.  Not compatible with \fCptlabelfield\fR.

.LP
\fBlinerange\fR \fImin\fR [\fImax\fR]
.IP
Controls the range (in scaled units) within which the curve will be rendered.
Data points falling outside this range will not be rendered.
If accumulation is being done, points outside the range will contribute
to the accumulated total.
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 rendered.
Example: \fClinerange: 1\fR

.LP
\fBxstart\fR 
.ig >>
<a href="attributetypes.html#plotvalue">
.>>
\fI plotvalue \fR
.ig >>
</a>
.>>
.IP
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.

.LP
\fBstairoverbars\fR \fCyes \fR| \fCno\fR
.IP
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.

.LP
\fBselect\fR  
.ig >>
<a href="condex.html">
.>>
\fI conditional-expression \fR
.ig >>
</a>
.>>
.IP
Allows data rows to be selected for inclusion
using a selection expression.

.ig >>
<br><br><br>
.>>
.SH Attributes pertaining to labeling
.LP
\fBlabel\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI text \fR
.ig >>
</a>
.>>
.IP
A text label to be displayed near the termination point of the curve.
Label may include the special variable @YFINAL which will yield the
last Y value plotted.
Example: \fClabel: @YFINAL - Control Group\fR

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


.LP
\fBlegendlabel\fR  
.ig >>
<a href="attributetypes.html#text">
.>>
\fI text \fR
.ig >>
</a>
.>>
.IP
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.

.LP
\fBlegendsampletype\fR  \fCsymbol\fR | \fCline+symbol\fR
.IP
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.
 

.LP
\fBnumbers\fR \fCyes \fR| \fCno \fR| 
.ig >>
<a href="textdetails.html">
.>>
\fI textdetails \fR
.ig >>
</a>
.>>
.IP
If specified, causes each point to be identified with its value in Y.
For \fCstairstep\fR curves, this value is centered between X locations.
.br
Example 1: \fCnumbers: yes\fR (uses the defaults)
.br
Example 1: \fCnumbers: adjust=0.0,0.2 size=8\fR

.LP
\fBnumbersformat\fR 
.ig >>
<a href="attributetypes.html#string">
.>>
\fI string \fR
.ig >>
</a>
.>>
.IP
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 Attributes pertaining to data points rendering
.LP
The invididual data points may optionally be displayed in a number of ways.
.LP
\fBpointsymbol\fR 
.ig >>
<a href="symboldetails.html">
.>>
\fI symboldetails \fR
.ig >>
</a>
.>>
.IP
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 color=blue\fR

.LP
\fBaltsymbol\fR
.ig >>
<a href="symboldetails.html">
.>>
\fI symboldetails \fR
.ig >>
</a>
.>>
.br
\fBaltwhen\fR
.ig >>
<a href="condex.html">
.>>
\fI conditional-expression \fR
.ig >>
</a>
.>>
.IP
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">
.>>
gallery/lineplot5 
.ig >>
</a>
.>>
is an example.

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

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

.LP
\fBptlabelrange\fR \fImin\fR [\fI max\fR]
.IP
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>
</td></tr>
<td align=right>
<a href="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>
.>>
