.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 "11-SEP-2001   PL www.sgpr.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.

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

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

.SH UNPLOTTABLE DATA
Invalid values are skipped;
the curve will be drawn to connect only the points corresponding to plottable 
values.  Points and connecting lines lying outside of the plotting area 
are displayed if possible.

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

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


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


.SH MANDATORY ATTRIBUTE
The \fCyfield\fR attribute MUST be specified.

.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
\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
\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
\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
\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
\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
\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
\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 stairstep 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).

.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 stairstep 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


.LP
\fBlastseglen\fR 
.ig >>
<a href="attributetypes.html#lenvalue">
.>>
\fI lenvalue \fR
.ig >>
</a>
.>>
.IP
When doing stairstep line plots using xfield, this may be used to
control the length of the last step segment.
If this 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
\fBstairoverbars\fR \fCyes \fR| \fCno\fR
.IP
This allows proper rendering of stairstep 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>
</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>
.>>
