.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
-->
</STYLE>
<title>ploticus: chron prefab</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>chron prefab</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 chron_prefab PL "17-SEP-2001   PL www.sgpr.net"

.LP
.ig >>
<a href="prefab_chron.html#manpage">
.>>
\0Click here to skip over examples
.ig >>
</a>
.>>

.SH EXAMPLE 1 - Dates 
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../prefabs/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="../prefabs/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="../prefabs/chron3.gif"></td></tr>
</table></center>
.>>
.LP
.nf


pl  -prefab chron  data=data14  x=1  y=2  datefmt=yy/mm/dd  xinc="14 days" \\
     stubfmt=MMMdd  stubvert=yes  tab=week  tabmode=first  mode=line  ygrid=yes \\
     step=yes  linedet="color=redorange width=2"  xrange="01/04/08 01/09/01"  \\
     yrange="0 40"  title="# hits per week"

.fi


.SH EXAMPLE 4 - Dates - tabulated by month
.ig >>
<center><table cellpadding=2><tr>
<td><img src="../prefabs/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="../prefabs/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="../prefabs/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
.ig >>
<a href="prefabs.html#examples">
.>>
\0How to run these examples
.ig >>
</a>
.>>

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

.SH DESCRIPTION
\fBchron\fR is a 
.ig >>
<a href="prefabs.html">
.>>
\0prefab
.ig >>
</a>
.>>
for plotting chronological data.
Data may be expressed as
.ig >>
<a href="dates.html">
.>>
\0dates
.ig >>
</a>
.>>
,
.ig >>
<a href="times.html">
.>>
\0times
.ig >>
</a>
.>>
(seconds portion is optional)
,
or a combination of date and time called
.ig >>
<a href="scaleunits.html#datetime">
.>>
\0datetime
.ig >>
</a>
.>>
\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

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

.SH PARAMETERS
.IP
.ig >>
<a href="prefabs.html#std">
.>>
\0standard prefab parameters
.ig >>
</a>
.>>
 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 
.ig >>
<a href="axis.html#stubunits">
.>>
\0constructs
.ig >>
</a>
.>>
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 
.ig >>
<a href="scaleunits.html#datetime">
.>>
\0datetime
.ig >>
</a>
.>>
\0.

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

.br
.br
.IP
\fBdatefmt\fR is the 
.ig >>
<a href="dates.html">
.>>
\0date format
.ig >>
</a>
.>>
you are using.  This must be specified unless 
using the default format (as set in a
.ig >>
<a href="config.html">
.>>
\0config file
.ig >>
</a>
.>>
, 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 
.ig >>
<a href="dates.html">
.>>
\0date format
.ig >>
</a>
.>>
or
.ig >>
<a href="times.html">
.>>
\0time format
.ig >>
</a>
.>>
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 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0data field
.ig >>
</a>
.>>
that holds time values.  
Normally when plotting 
.ig >>
<a href="scaleunits.html#datetime">
.>>
\0datetimes
.ig >>
</a>
.>>
, 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
.ig >>
<a href="linedetails.html">
.>>
\0linedetails value
.ig >>
</a>
.>>
, 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 
.ig >>
<a href="color.html">
.>>
\0color
.ig >>
</a>
.>>
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
.ig >>
<a href="linedetails.html">
.>>
\0appearance
.ig >>
</a>
.>>
of the line, if \fCmode=line\fR.
.br
.br
\fBstep\fR may be given as \fCyes\fR to get a stairstep line.


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

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