.help fcurve May92 ftools.futils
.ih
NAME
fcurve -- Bin column data into a light curve
.ih
USAGE
fcurve infile gtifile outfile timecol columns binsz lowval highval 	
.ih
DESCRIPTION
This task creates a "light curve" or rates file by binning a list of events
(typically a time ordered list of photon events detected with a particular
instrument) into a specified set of equally spaced time intervals.

The binning has 
five modes: if 'binmode' = Sum, then the output is the total of the
value of the counts; if 'binmode' = 'Rate' then the output 
is the total of the value of the counts/time; 
if 'binmode' = 'Mean' then the output is the mean value of the
binned quantity during each time interval; if 'binmode' = 'Event_sum' the total
number of events falling in each bin are recorded; and if 'binmode' = 
'Event_rate' the number of events/sec is collected.  
The bin size and time ranges
can be entered, or calculated by the program is the value is set equal to
INDEF. If the bin size is INDEF, 100 equally spaced bins will be produced.

An optional
'Good Time Intervals"  FITS file may also be specified which defines
the valid time intervals during which the instrument was on and able
to detect events.  If a particular integration bin fall completely within
a good time interval then the corresponding 'Livetime' column will be
set equal to 1.0; otherwise, 'Livetime' will give the fraction of the
time that the instrument was in an active state
and the 'binmode' and 'Error' columns in the output file will be
adjusted accordingly.

.ih
PARAMETERS
.ls infile [filename]
The name of the FITS file and extension number to be binned.
.le
.ls gtifile = [filename]
The name of the optional FITS GTI file to be used in normalization of
bin values.  If this parameter is blank, all of the times will be
considered good.
.le
.ls outfile [filename]
The name of the output FITS file containing the bin values.  If
preceed by a !, an existing file of the same name is overwritten.
.le
.ls timecol [string]
The name of the column containing the time (independent variable).
.le
.ls columns = [string]
The name of the columns in the FITS file for the parameters to be binned.
For the "Events" values for the binmode parameter this value is ignored.
.le
.ls binsz = INDEF [double]
The size of bins to use in histogram.  If set equal to INDEF, 100
bins will be produced.
.le
.ls lowval = INDEF  [double]
The lower limit for the histogram.  If set equal to INDEF, the
lower limit will be calculated from the data.
.le
.ls highval = INDEF [double]
The upper limit for the histogram. If set equal to INDEF, the
upper limit will be calculated from the data.
.le
.ls (binmode = "Rate") [string]
The mode of binning the data. Possible modes are Sum, Rate, Mean, Event_sum and
Event_rate.
Sum is a simple sum of event values. Rate is the sum divided by the active bin 
time. Mean is the mean of the value of the events for that bin. 
Event_sum counts the number of
events falling in each bin and Event_rate is the number of events/second.
.le
.ls (gticols = "START,STOP") [string]
The name of the start and stop columns in the GTI FITS file to be 
used in normalization of bin values.
.le
.ls (gtidate = MJDREF) [string]
The FITS header keyword for the GTI reference date of observation.  This
parameter may be in either julian day or dd/mm/yy or yyyy-mm-dd format, 
but must be the same format as obsdate.  It is ignored is obsdate 
is blank or "-".
.le
.ls (gtitime = ) [string]
The FITS header keyword for the GTI reference time of observation.  This
parameter is only used if obsdate is in dd/mm/yy or yyyy-mm-dd format.
.le
.ls (extname = " ") [string]
The name of the FITS extname keyword to be placed in the output FITS
file containing the light curve data.
.le
.ls (obsdate = MJDREF) [string]
The FITS header keyword for the reference date of observation.  This 
keyword may be in either julian days or in dd/mm/yy or yyyy-mm-dd 
format.  If blank (or "-"), reference time checking is ignored.
.le
.ls (obstime = ) [string]
The FITS header keyword for the reference time of observation.  This
parameter is only used if obsdate is in dd/mm/yy or yyyy-mm-dd format.
.le
.ls (outtimecol = " ") [string]
The name of the FITS "time" column used to store the bin center values. 
If blank or "-", the name of the input time column is used.
.le
.ls (outcol = " ") [string]
The name of the FITS column(s) used to store the parameter(s) values.  If this
value is blank or "-", the names of the input columns are used.
.le
.ls (outerr = " ") [string]
The name of the FITS "error" column(s) used to store the statistical error(s). 
If blank or "-", the names of the columns will be the names of the input 
parameter columns with _Err appended.  If equal to "NONE", no error columns
will be output.
.le
.ls (outlive = "Livetime") [string]
The name of the FITS "fractional integration time" column used to store 
the fractional integration time.  If blank or "-", the livetime will not
be output.
.le
.ls (copyprime = yes) [boolean]
If true, the primary array will be copied to the output file.
In addition, all keywords in the extension from which the light curve was
created from will be copied to the new extension.
.le
.ls (copyall = no) [boolean]
If true, all other extensions in the input file will be copied to the
output file.  The value of copyprime is ignored if this flag is set.
.le
.ls (sensecase = yes) [boolean]
Whether to make the input to FCURVE case sensitive or not.
.le
.ls (clobber = yes) [boolean]
If true, an existing file with the same name as that specified for the
output file name will be overwritten.
.le
.ih
EXAMPLES
1.  Bin the data in the PHA and TIME columns of the first extension of the 
FITS file data.fits into 100 second bins starting from time 5 to time 3600 and
write  lcrv.fits using the first extension of gti.fits as the gti file.
.nf

     ft> fcurve data.fits gti.fits lcrv.fits TIME PHA 100 5 3600

2.  As above, but you don't know much of anything about values of
the data in the input file, and do not have a gti file.

     ft> fcurve data.fits " " lcrv.fits TIME PHA INDEF INDEF INDEF
.fi
.ih
BUGS
The sensecase parameter only affects the time (independent) column name.
.ih
NOTES
Previously, this task included a parameter to offset the time value
by the amount of the first time in the light curve.  This functionality
has been moved into FPLOT.
.ih
SEE ALSO
fstruct, flcol, fdump, fhisto, fplot
.endhelp
