NAME

rebingausslc - rebin an irregularly sampled light curve (such as BAT or ASM)

USAGE

rebingausslc infile outfile timedel timebinalg tstart tstop

DESCRIPTION

rebingausslc is a generic task which can rebin irregularly sampled light curves. It is particularly suited to grouping irregular monitoring observations such as Swift BAT, RXTE ASM, or long-term RXTE PCA data, into regularly sampled time bins. It can also be used for regularly sampled light curves, subject to the caveats below.

Users are able to choose two kinds of light curve binning: either uniform (equal bin sizes); or custom (user chooses each bin). Each input light curve rate sample may be a vector (eg. multiple energy bins).

The rebinning is performed by grouping all samples that fall into an output bin, and computing the weighted average using gaussian statistics. This kind of statistical weighting is usually most appropriate for background-subtracted light curves.

rebingausslc makes the following assumptions:

If the input time bins are larger than the output time bins, then this tool is not appropriate, since the problem becomes an interpolation problem.

rebingausslc does not compute partial exposure per bin. If at least one sample falls in an output bin, then the bin is considered to have full exposure. rebingausslc does not reject input bins which overlap in time, but it also does not do anything special in such a situation either. Once rebingausslc determins which input samples fall into a given output bin, the samples are averaged using gaussian statistics, assuming they are statistically independent

rebingausslc relies on the input light curve being a valid OGIP-format light curve. This means that the appropriate TIME, RATE and ERROR columns are present. The TIMEPIXR keyword is used to compute the center-time of each input sample (TIMEPIXR defaults to 0.5 if not specified). The user can specify an exposure-type column name such as EXPOSURE so that the bin width of each input sample can be specified explicitly.

PARAMETERS

infile [filename]
Input light curve file name.

outfile [filename]
Output light curve file name.

timedel = 1.0 [real]
Select an output time bin size, in the same units as the input "time" column. If timebinalg="gti", then this value should be set to 0.

timebinalg = uniform [string]
Time binning algorithm. Either "uniform", for uniform binning, or "gti" for custom time bins specified by the gtifile. Only the first character of the algorithm type needs to be specified.

tstart = INDEF [string]
Start time of the accumulation, expressed in the same time system as the input "time" column. This parameter is also allowed to be "INDEF", which causes the task to use the minimum time from the file, or "#KEYNAME" where KEYNAME is any keyword in the input file. If timebinalg="gti", then this value should be set to INDEF.

tstop = INDEF [string]
Stop time of the accumulation, expressed in the same time system as the input "time" column. This parameter is also allowed to be "INDEF", which causes the task to use the minimum time from the file, or "#KEYNAME" where KEYNAME is any keyword in the input file. If timebinalg="gti", then this value should be set to INDEF.

(gtifile = NONE) [string]
Name of custom time bin file (if timebinalg="gti"). This file should be a standard GTI file which contains one good time interval per desired output bin. The GTI should have columns START and STOP, which specify the start and stop time of each desired output bin, in the same time units as the input light curve. If timebinalg="user" this value should be set to NONE.

(timepixr = 0.5) [real]
Determines the reference point of each output time bin. A value of 0.0 indicates that the output TIME column should refer to the start of the bin; a value of 0.5 indicates the center of the bin.

(tcol = "TIME") [string]
Name of TIME column in input file.

(ratecol = "RATE") [string]
Name of RATE-like column in input file. The RATE may be a vector.

(errcol = "ERROR") [string]
Name of column in input file specifying the gaussian uncertainties of each RATE value. The ERROR must have the same vector dimension as RATE.

(expocol = "TIMEDEL") [string]
Name of column in input file specifying the exposure of each bin. The task checks for a column of this name, and if not present, then checks for a keyword of the same name.

(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 2) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 1 produces a basic summary of the task actions; chatter = 2 (default) additionally prints a summary of input parameters; chatter = 5 prints debugging information.

(history = YES) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

1. Rebin a light curve to uniform 1-day bins. This light curve spans mission elapsed time (in seconds) from 125000000 to 150000000. The rate and uncertainties columns are RATE and RATE_ERR respectively, and the exposure column is EXPOSURE.

  rebingausslc input.lc rebinned.lc 86400.0 u 125000000 150000000 \
    ratecol=RATE errcol=RATE_ERR expocol=EXPOSURE clobber=YES

2. Rebin the same light curve, but with custom time bins. The file "user.gti" contains one row for each desired time bin, giving the start and stop time of each bin.

  rebingausslc input.lc rebinned.lc 0 g 0 0 gtifile=user.gti \
    ratecol=RATE errcol=RATE_ERR expocol=EXPOSURE clobber=YES

SEE ALSO

lcurve, bincurve, rebinlc

LAST MODIFIED

Sep 2010