.help bincurve Aug93 ftools.heasarc
.ih
NAME
bincurve - bins vectors and outputs a light curve
.ih
USAGE
bincurve infile outfile gtifile phasefile timecol column binsize
.ih
DESCRIPTION
This task bins a requested portion of a vector column, and creates a 
light curve based on optional good times and phases.  The subset of the
column requested is added together, and that value is used as the
value to construct a light curve with.  Note that this task has all of
the capabilities of FCURVE.
.ih
PARAMETERS
.ls infile [file name]
The name of the input FITS file (and extension number in square brackets) to
be binned.
.le
.ls outfile [file name]
The name of the output FITS file.
.le
.ls gtifile [file name]
The name and extension of the input GTI information.  A blank or '-'
indicates that no good time interval checking is desired.  The good time
intervals are assumed to be in time order.  Current maximum number of
GTIs allowed is 100.
.le
.ls phasefile [file name]
The name and extension of the input phase information.  A blank or '-'
indicates that no phase checking is desired.  This facility is not
currently available.
.le
.ls timecol = "TIME" [string]
The name of the column in the input file containing timing information.
The value of this input is ignored if no gti file is specified.  This
value is case sensitive unless the "sensecase" parameter is set to "no".
The value for time is assumed to be a double precision scalar.
.le
.ls column = "PHAS" [string]
The name of the column in the input file containing the vector to 
be binned.
The entire vector will be binned unless a subset is specified as part of the
column name, enclosed in square brackets.  For example, if the user wishes
to only bin vector elements 10-20 and 50-100 of a column named "PHAS", 
the value of column should be column = PHAS[10-20,50-100].  The current
maximum length of the vector allowed is 1024.
.le
.ls binsize = INDEF [real]
The size of the time bins for the light curve.  If INDEF is specified,
100 bins will be output.
.le
.ls lowval = INDEF [real]
The minimum value of the time to bin.  A value of INDEF will search the
file for the minimum time.
.le
.ls highval = INDEF [real]
The maximum value of the time to bin.  A value of INDEF will search the
file for the maximum time.
.le
.ls binmode = SUM [string]
The type of binning to do.  SUM will add all requested values and output
the sum.  MEAN will calculate the average of all values falling is each
bin.  RATE calculates the value/time of each bin.  EVENT_SUM will output
the total number of events which fall into the given bin, and EVENT_RATE
calculates the events per time in each time bin.
.le
.ls (rows = '-') [string]
The rows to include in the binning.  A '-' will include all rows (the default).
Single rows or groups of rows can be specified.  For example, to select rows 2,
5 to 10 and 52, enter rows = 2,5-10,52.
.le
.ls (indate = MJDREF) [string]
The keyword name containing the zero start date of the time column of the
input file.  If
the value of the keyword indate is not of the forms of dd/mm/yy or
yyyy-mm-dd, then the value
is assumed to be in terms of Julian days.  A blank or '-' will defeat zero
time checking for ALL of the input files.  The output file 
zero time is set equal
to the input file zero time, and is written in the same keyword as the input
file.
.le
.ls (intime = " ") [string]
The keyword name containing the zero start time of the time column of the
input file.  If the
value of the indate keyword in not of the forms of dd/mm/yy or
yyyy-mm-dd, this parameter is ignored.
.le
.ls (gtistart = START) [string]
The name of the start column of the GTI file.  This value is ignored if no
GTI file is specified.
.le
.ls (gtistop = STOP) [string]
The name of the stop column of the GTI file.  This value is ignored if no
GTI file is specified.
.le
.ls (gtidate = MJDREF) [string]
The keyword name containing the zero start date of the time column of the
GTI file.  If
the value of the keyword gtidate is not of the form dd/mm/yy or
yyyy-mm-dd, then the value
is assumed to be in terms of Julian days.  A blank or '-' will defeat zero
time checking for the GTI file only.
.le
.ls (gtitime = " ") [string]
The keyword name containing the zero start time of the time column of
the GTI file.  If the
value of the gtidate keyword in not of the forms of dd/mm/yy or
yyyy-mm-dd, this parameter is ignored.
.le
.ls (epoch = "PH_EPOCH") [string]
The keyword name containing the phase epoch (start time) for this phase file.
.le
.ls (period = "PH_PRD") [string]
The keyword name containing the period for this phase file.
.le
.ls (phstart = "START") [string]
The name of the phase start column.  Values in the column are assumed to
be in units of fraction of phase (i.e. between 0 and 1).
.ls (phstop = "STOP") [string]
The name of the phase stop column.  Values in the column are assumed to
be in units of fraction of phase (i.e. between 0 and 1).
.le
.ls (phdate = MJDREF) [string]
The keyword name containing the zero start date of the time related
keywords in the phase file.  If
the value of the keyword phdate is not of the form dd/mm/yy or
yyyy-mm-dd, then the value
is assumed to be in terms of Julian days.  A blank or '-' will defeat zero
time checking for the phase file only.
.le
.ls (phtime = " ") [string]
The keyword name containing the zero start time of the time related
keywords in the phase file.  If the
value of the phdate keyword in not of the form dd/mm/yy or yyyy-mm-dd, 
this parameter is ignored.
.le
.ls (outtimecol = ' ') [string]
The name of the output time column.  If blank or '-', the name of the
input time column is used.
.le
.ls (outcol = ' ') [string]
The name(s) of the output curve columns.  If blank or '-', the name(s)
will be the same as the input column names.
.le
.ls (outerr = ' ') [string]
The name(s) of the output error columns.  If blank or '-', the name(s)
will be the same as the input column names with _ERR appended.  If equal
to NONE, no error columns will be output.
.le
.ls (outlive = 'Livetime') [string]
The name of the column containing the fraction of live time in each
bin.  If blank, no livetime column will be output.
.le
.ls (copyprime = yes) [boolean]
Whether to copy the primary header and array to the output file.
.le
.ls (copyall = no) [boolean]
Whether to copy all other extensions from the input file to the output file.
.le
.ls (history = yes) [boolean]
Whether to output history records to the output file.
.le
.ls (sensecase = yes) [boolean]
Whether to be case sensitive for the input column names.
.le
.ih
EXAMPLES
1.  Sum all the values in the PHAS column in the file input.fits and use
that value to generate a light curve with 5 second bins and write
the light curves to output.fits
.nf

     ft> bincurve input.fits output.fits '-' '-' '-' PHAS 5.

.fi
2.  As above, but specify good time interval file gti.fits and phase information
file phase.fits, and only bin elements 1-64 and 128-256 of the input vector
.nf

     ft> bincurve input.fits output.fits gti.fits phase.fits TIME PHAS[1-64,128-256] 5.

.fi
.ih
NOTES:
The zero dates must all be of the same format, either julian days or dd/mm/yy
or yyyy-mm-dd, where the two digit year yy means 19yy.
.ih
BUGS

SEE ALSO

.endhelp

