#set TITLE = "chron prefab"
#include top

.LP
#set FILE = "prefab_chron.html#manpage"
#set TAG = "Click here to skip over examples"
#include link

.SH EXAMPLE 1 - Dates 
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../gallery/prefab_img/chron1.gif"></td></tr>
</table></center>
.>>
.LP
.nf
pl  -prefab chron  data=data14  x=1  y=2  datefmt=yy/mm/dd  xinc="1 month" \\
     stubfmt=M  xyears=yyyy  yrange="0 25"  barwidth=line  color=red  \\
     title="# hits per day"  omitweekends=yes


The data14 file:
	00/12/21 1
	00/12/22 1
	00/12/23 2
	00/12/27 1
        ...etc.


.fi
.SH EXAMPLE 2 - Dates - tabulated by week
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../gallery/prefab_img/chron2.gif"></td></tr>
</table></center>
.>>
.LP
.nf

pl  -prefab chron  data=data14  x=1  y=2  datefmt=yy/mm/dd  xinc="1 month" \\
      stubfmt=M  xyears=yyyy  color=green  tab=week  title="# hits per week"

.fi

.SH EXAMPLE 3 - Dates - tabulated by week
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../gallery/prefab_img/chron3.gif"></td></tr>
</table></center>
.>>
.LP
.nf
pl  -prefab chron  data=data19  x=2  y=1  datefmt=mmddyy  xinc="1 month" \\
	stubfmt=M  xyears=yyyy  color=green  tab=week  include2=annot \\
	title="# website visitors per week"  rectangle="1 1 4 2.5"  ygrid=yes  \\
	mode=line step=yes fill=red 

The data19 file:
  18 071301
  16 071401
  15 071501
  34 071601
  ...etc.

.fi
In the above example, notice that \fBrectangle\fR (new in 2.02) was used to set a smaller
size, and a file containing script code for the annotation is included.

#include space


.SH EXAMPLE 4 - Dates - tabulated by month
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../gallery/prefab_img/chron4.gif"></td></tr>
</table></center>
.>>
.LP
.nf


pl  -prefab chron  data=data14  x=1  y=2  datefmt=yy/mm/dd  xinc="1 month"  \\
	stubfmt=M  xyears=yyyy  color=powderblue  tab=month  tabmode=first  \\
	nearest=month  barwidth=0.2  curve=yes 


.fi

.SH EXAMPLE 5 - Datetimes - tabulated by hour
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../gallery/prefab_img/chron5.gif"></td></tr>
</table></center>
.>>
.LP
.nf

pl -prefab chron  data=data16  x=1  tab=hour  datefmt=yy/mm/dd  xinc="1 day" \\
	barwidth=line  stubfmt=MMMdd  unittype=datetime  timefld=2  \\
	title="# hits per hour"


The data16 file:
	01/09/05	09:43:35
	01/09/05	09:43:40
	01/09/05	13:15:00
	01/09/05	13:15:11
	...etc.

Note that a file such as this (data13) could also be used, and timefld
would not need to specified:
	01/09/05.09:43:35
	01/09/05.09:43:40
	01/09/05.13:15:00
	01/09/05.13:15:11
	..etc.

.fi

.SH EXAMPLE 6 - Times - tabulated by hour
.LP
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../gallery/prefab_img/chron6.gif"></td></tr>
</table></center>
.>>
.LP
.nf
pl -prefab chron  data=data15  x=1  tab=hour unittype=time xinc="1 hour" \\
	nearest=hour  barwidth=0.2  stubfmt=HHA  \\
	title="# events per hour"  color=coral


The data15 file:
	07:47:49
	07:47:52
	07:47:54
	..etc.

.fi

.LP
#set FILE = "prefabs.html#examples"
#set TAG = "How to run these examples"
#include link

.ig >>
<a name=manpage></a>
.>>

.SH DESCRIPTION
\fBchron\fR is a 
#set FILE = "prefabs.html"
#set TAG = prefab
#include link
for plotting chronological data.
Data may be expressed as
#set FILE = dates.html
#set TAG = dates
#include link
,
#set FILE = times.html
#set TAG = times
#include link
(seconds portion is optional)
,
or a combination of date and time called
#set FILE = scaleunits.html#datetime
#set TAG = datetime
#include link
\0.
\fBchron\fR can produce bar or line plots, and can plot explicit values or 
tabulate by week, month, day, hour, etc.
Time is shown along the X axis.
The data file must be in chronological order.

.LP

#include space

.SH PARAMETERS
.IP
#set FILE = "prefab_stdparms.html"
#set TAG = "Standard prefab parameters"
#include link
 are all supported except \fBerr\fR.  
\fBdata\fR and \fBx\fR are always required.
Data field \fBx\fR must contain dates, times, or datetimes.
Data field \fBy\fR may contain values.
\fBxinc\fR supports 
#set FILE = "axis.html#stubunits"
#set TAG = "constructs"
#include link
such as \fC"1 month"\fR; if only a
number is given, it is assumed to be days (the default for \fBxinc\fR is 7 days).

.br
.br
.IP
\fBunittype\fR specifies the type of chronological scaling.
Default is \fCdate\fR.  Allowable values are \fCtime\fR, \fCdatetime\fR and 
#set FILE = scaleunits.html#datetime
#set TAG = datetime with windowing
#include link
\0.

.br
.br
.IP
\fBmode\fR is either \fCbars\fR (the default) or \fCline\fR.

.br
.br
.IP
\fBdatefmt\fR is the 
#set FILE = dates.html
#set TAG = "date format"
#include link
you are using.  This must be specified unless 
using the default format (as set in a
#set FILE = config.html
#set TAG = "config file"
#include link
, otherwise \fCmmddyy\fR).
If plotting datetime values, \fBdatefmt\fR specifies only the date portion.
If plotting time values, \fBdatefmt\fR is ignored.

.br
.br
.IP
\fBstubfmt\fR is the 
#set FILE = dates.html
#set TAG = "date format"
#include link
or
#set FILE = times.html
#set TAG = "time format"
#include link
to be used for X axis stubs.
The defaults are \fCMMMdd\fR (date) and \fCHHa\fR (time).
You can use \fCstubvert=yes\fR to render stubs vertically.

.br
.br
.IP
\fBxyears\fR allows years to be displayed along X axis below date X stubs.  
Use \fCyy\fR for 2 digit year eg 01, \fCyyy\fR for eg '01, and \fCyyyy\fR
for eg \fC2001\fR.

.br
.br
.IP
\fBomitweekends\fR may be specified as \fCyes\fR to allow the graph to be 
drawn such that Friday is followed immediately by Monday.  Any data points
falling on a Saturday or Sunday are silently adjusted to the nearest weekday.


.br
.br
.IP
\fBtab\fR tabulates data
by \fChour\fR, \fCday\fR, \fCweek\fR, \fCmonth\fR, \fCquarter-year\fR, or \fCyear\fR.  
If a \fBy\fR data field is being used, the \fBy\fR values will be totaled;
otherwise, instances will be counted.
Tabulation is done by internally adjusting dates and then counting.

.br
.br
.IP
\fBtabmode\fR is used with \fBtab\fR.
Allowable values are \fCmid\fR and \fCfirst\fR (default is \fCmid\fR).
\fCmid\fR causes tabulations to be based on a date or time in the
middle of the interval; for \fCfirst\fR the beginning of the interval is used.
\fCmid\fR is appropriate for some types
of plots while \fCfirst\fR is better for others.

.br
.br
.IP
\fBtimefld\fR specifies a 
#set FILE = "attributetypes.html#dfield"
#set TAG = "data field"
#include link
that holds time values.  
Normally when plotting 
#set FILE = scaleunits.html#datetime
#set TAG = datetimes
#include link
, dates and times are combined into one data field, separated by a period (.).
If \fBtimefld\fR is used, however, 
dates may be in one data field (\fBx\fR) and times in another.  

.br
.br
.IP
\fBnearest\fR may be used to specify cutoffs for automatic scaling in X.
For example, \fCnearest=month\fR would cause X min and max to fall on 
month boundaries.
Allowable values are \fChour\fR, \fCday\fR, \fCmonth\fR, \fCquarter\fR, and \fCyear\fR.

.br
.br
.IP
\fBcurve\fR may be specified as \fCyes\fR or as a
#set FILE = linedetails.html
#set TAG = "linedetails value"
#include link
, and causes a moving average curve to be fit and drawn.  \fBorder\fR
(default = 5) may be used to control the number of points considered when 
computing the moving average curve (higher value = smoother curve).



.LP
If mode is \fCbars\fR:
.IP
\fBbarwidth\fR controls the width of bars
This is a value in inches,
or may be given as \fCline\fR for very thin bars.

.br
.br
.IP
\fBcolor\fR controls the 
#set FILE = color.html
#set TAG = color
#include link
of bars, if \fCmode=bars\fR.

.br
.br
.IP
\fBcrossover\fR may be specified as the value in Y where bars begin
to point downward instead of upward.  For instance, \fCcrossover=0\fR
is often useful when dealing with financial income, to show loss
using downward bars.


.LP
If mode is \fCline\fR:
.IP
\fBlinedet\fR controls the
#set FILE = linedetails.html
#set TAG = appearance details
#include link
of the line, if \fCmode=line\fR.
.br
.br
.IP
\fBstep\fR may be given as \fCyes\fR to get a stairstep line.
.br
.br
.IP
\fBfill\fR may be given as a 
#set FILE = color.html
#set TAG = color
#include link
, resulting in the area under the line being filled.
.br
.br
.IP
\fBgapmissing\fR may be specified as \fCyes\fR or \fCsmall\fR.
If \fCyes\fR, missing data will cause a gap in the line (normally
the line connects plottable points without a gap).  \fCsmall\fR is
the same as \fCyes\fR except that it leaves a small overhang.

#include space
.LP
Note: Because filter processing is applied to data as they are read,
\fBtabulate\fR cannot be set from within the data file.
If \fBtabulate\fR is used, \fBx\fR, \fBy\fR and \fBdatefmt\fR cannot
be set from within the data file.

#include bottom
