.help binspec Jul93 ftools.heasarc
.ih
NAME
binspec - bins vectors by rows
.ih
USAGE
binspec infile outfile gtifile phasefile timecol column
.ih
DESCRIPTION
This task bins a requested portion of a vector column, based on an optional
good times and phases.  The binning can be specified for the entire file,
or for a subset of good rows.  The binning adds the 1st element of the
first good row to the 1st element of the 2nd good row, etc. to build up
a new vector with the same dimensions as the requested input subset.
.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 integer 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 binmode = SUM [string]
The type of binning to do.  SUM will add all requested values and output
the sum.  Currently only SUM is available.  Future enhancements will 
have MEAN and RATE options.
.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 (binrows = -1) [integer]
The number of rows to bin together for each output row.  If binrows is 
negative, the entire file is binned together (the default).  This parameter
specifies the number of good rows to bin together rather than the number of
rows in the file.  For example, if the phase information only selects every
other row of the file, the first binrows good rows will be added together
and output, rather than the first binrows of the input file (which would, in
this case, only consist of binrows/2 good rows).
.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 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 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 form 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 form 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 (outcol = " ") [string]
The name(s) of the output columns.  If blank or '-', the name of the 
requested input column(s) are used.
.le
.ls (copycol = no) [boolean]
Whether to copy the value of the other columns to the output file.  The value
of the other columns is taken to be the value of that column in the same row
as the first good input vector of a sum.
.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 write
the values to output.fits
.nf

     ft> binspec input.fits output.fits '-' '-' '-' PHAS

.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> binspec input.fits output.fits gti.fits phase.fits TIME PHAS[1-64,128-256]

.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

