fcurve HEADAS help file

NAME

fcurve -- Bin column data into a light curve

USAGE

        fcurve infile gtifile outfile timecol columns binsz lowval highval

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.

PARAMETERS

infile [filename]: The name of the FITS file and extension number to be binned.
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.
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.
timecol [string]: The name of the column containing the time (independent variable).
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.
binsz = INDEF [double]: The size of bins to use in histogram. If set equal to INDEF, 100 bins will be produced.
lowval = INDEF [double]: The lower limit for the histogram. If set equal to INDEF, the lower limit will be calculated from the data.
highval = INDEF [double]: The upper limit for the histogram. If set equal to INDEF, the upper limit will be calculated from the data.
(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.
(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.
(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 "-".
(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.
(extname = " ") [string]: The name of the FITS extname keyword to be placed in the output FITS file containing the light curve data.
(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.
(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.
(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.
(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.
(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.
(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.
(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.
(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.
(sensecase = yes) [boolean]: Whether to make the input to FCURVE case sensitive or not.
(clobber = yes) [boolean]: If true, an existing file with the same name as that specified for the output file name will be overwritten.

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.

     
          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

BUGS

The sensecase parameter only affects the time (independent) column name.

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.