NAME

bincurve - bins vectors and outputs a light curve


USAGE

        bincurve infile outfile gtifile phasefile timecol column binsize

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.


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

binsize = INDEF [real]
The size of the time bins for the light curve. If INDEF is specified, 100 bins will be output.

lowval = INDEF [real]
The minimum value of the time to bin. A value of INDEF will search the file for the minimum time.

highval = INDEF [real]
The maximum value of the time to bin. A value of INDEF will search the file for the maximum time.

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.

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

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

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

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

(outtimecol = ' ') [string]
The name of the output time column. If blank or '-', the name of the input time column is used.

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

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

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

(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 use that value to generate a light curve with 5 second bins and write the light curves to output.fits 

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

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


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

Aug93 ftools.heasarc