NAME

binspec - bins vectors by rows


USAGE

        binspec infile outfile gtifile phasefile timecol column

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.


PARAMETERS

infile [file name]
The name of the input FITS file (and extension number in square brackets) to be binned.

outfile [file name]
The name of the output FITS file.

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.

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.

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.

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.

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.

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

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

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

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

(gtistart = START) [string]
The name of the start column of the GTI file. This value is ignored if no GTI file is specified.

(gtistop = STOP) [string]
The name of the stop column of the GTI file. This value is ignored if no GTI file is specified.

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

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

(epoch = "PH_EPOCH") [string]
The keyword name containing the phase epoch (start time) for this phase file.

(period = "PH_PRD") [string]
The keyword name containing the period for this phase file.

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

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

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

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

(outcol = " ") [string]
The name(s) of the output columns. If blank or '-', the name of the requested input column(s) are used.

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

(copyprime = yes) [boolean]
Whether to copy the primary header and array to the output file.

(copyall = no) [boolean]
Whether to copy all other extensions from the input file to the output file.

(history = yes) [boolean]
Whether to output history records to the output file.

(sensecase = yes) [boolean]
Whether to be case sensitive for the input column names.


EXAMPLES

1. Sum all the values in the PHAS column in the file input.fits and write the values to output.fits 

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

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 

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


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.


BUGS


SEE ALSO

CATEGORY

Jul93 ftools.heasarc