NAME

USAGE

DESCRIPTION

The sxsbranch task computes rates and branching ratios for each SXS event grade based on an input file or count rate. These are calculated for each pixel and for the entire array. The sxsbranch task also estimates the same quantities using the input count rate for the entire array using Poisson statistics. This task operates in three modes as follows: (1) no input file, (2) input file from simulations, and (3) input file from observations.

(1) If there is no input file ('infile=NONE'), sxsbranch internally simulates events using the 'exposure' and 'countrate' parameters, with counts distributed in the array according to the file specified by the 'pixfrac' parameter. If 'pixfrac=NONE', a uniform illumination is assumed. Times are assigned, event grades assigned, and branching ratios calculated accordingly. Time is assigned within the specified exposure by randomly drawing from one of two possible distributions, either constant ('flagburst=no') or burst-like ('flagburst=yes'). To apply the burst-like option, the following parameters must be set: 'ratburst', the ratio of peak-to-quiescent count rate; 'tburst', the burst start time relative to start of the exposure in seconds; 'trise', the (linear) rise time in seconds; and 'tdecay', the burst exponential decay time in seconds. Grades are assigned by comparing the time intervals between events with the values specified by the parameters 'dtmidhigh', 'dtlowmid', and 'dtprimary' according to the following definitions: (a) high-resolution events have no preceding or following events within 'dtmidhigh'; (b) mid-resolution events have at least one preceding or following event within 'dtmidhigh', but none within 'dtlowmid'; (c) low-resolution events have at least one preceding or following event within 'dtlowmid'; (d) primary events have no preceding event within 'dtprimary'; and (e) secondary events have at least one preceding event within 'dtprimary'. Events are categorized by grade, e.g., as high primary (Hp), low secondary (Ls), etc. The 'dtprimary' and 'dtmidhigh' parameter values are expected to be identical.

(2) If the input file is a simulated SXS event file created by heasim ('infile' parameter set to the file name, and 'filetype=sim'), sxsbranch calculates branching ratios from the events in the simulated SXS file after assigning pixel numbers and grades based on the postions and times of the events. Grades are assigned using the event time and the calculated time intervals to the preceding and following events in the same pixel, using the criteria defined above.

If 'infile=NONE' or 'filetype=sim', sxsbranch determines crosstalk events (if parameters 'ctphafrac1' and/or 'ctphafrac2' are not set to zero) from the values of the parameters 'debin', 'enrgthr', 'ctphafrac1', and 'ctphafrac2' prior to assigning grades. For simulated files, crosstalk events are induced in the nearest electrically bonded pixel if ctphafrac1*PI > (enrgthr/debin), and in the next-nearest, electrically bonded pixel if ctphafrac2*PI > (enrgthr/debin). The parameters 'ctphafrac1' and 'ctphafrac2' define the ratio of crosstalk, to original event energy; 'enrgthr' is the energy threshold above which crosstalk triggers; and, 'debin' is the width in eV of the PI bin. The maximum possible crosstalk is induced when 'enrgthr=0' (the default), or if 'infile=NONE' (since PI is not defined). Electrical proximity of pixels is determined by the calibration map file defined by the setting of the parameter 'ctelpixfile'. Crosstalk events are included when assigning grades.

(3) If the input SXS event file is from an observation ('infile' parameter set to the file name, and 'filetype=real'), sxsbranch calculates branching ratios based on the columns containing the pixels, and grade values are assigned by the on-board porcessing. Baseline and lost events are excluded from the branching ratio calculation.

For comparison with the grade distribution compiled from real or simulated events, statistical estimates are also computed and output. For these, the count rate is distributed on the array according to the file specified by the 'pixfrac' parameter. If 'pixfrac=NONE', a uniform illumination is assumed. For pixel 12, the calpixel, the rate is set to the value specified in the 'calpixrate' parameter. If 'ctphafrac1' and/or 'ctphafrac2' are greater than 0, crosstalk is calculated as described above assuming that any pixel crosstalks with all of its nearest and/or next-nearest pixels as defined by the electrical proximity map given by the parameter 'ctelpixfile'. Expected grade distributions are calculated based on the count rate per pixel, the 'dtmidhigh', 'dtlowmid', and 'dtprimary' parameters as described above, and assuming Poisson statistics.

Pixels may be excluded from all branching ratio calculations (pertaining to real or simulated events, as well as estimates) by specifying a pixel mask using the parameter 'pixmask'.

The sxsbranch task accounts for pileup, defined as occurring when events in a given pixel are separated by time intervals too short to be distinguished by the on-board electronics, if 'flagmerge=yes'. This is valid either for simulated (heasim) event input files, or if 'infile=NONE'. In this case, events separated in time by intervals smaller than that given by the 'dtmerge' parameter, are combined into a single event up to a total time interval given by the 'dtmax' parameter. If 'filetype=sim', the merged event energy is set equal to the sum of energies of the individual events that were merged, and the merged event is discarded if the value exceeds that given by the 'maxenergy' parameter. Crosstalk events are added and events are graded based on the event list after merging.

The ASCII file specified by 'pixfrac' has two columns. The first contains the SXS pixel number; the second the fraction of counts detected in that pixel. If set to NONE, the count distribution is uniform in all pixels. The pixfrac.txt file in the REFDATA area contains the fractional distribution of counts in the total array based on the PSF for a point source. The 'pixfrac' parameter used in the statistical estimates, and for simulating events if 'infile=NONE', may point to this file. The ASCII file specified by 'pixmask' has two columns. The first contains the SXS pixel number; the second is set to 0 if the pixel is to included in all branching ratio calculations, and 1 if it is to be excluded. The pixmask.txt file in the REFDATA area masks the outer 20 pixels. These are excluded from all branching ratio calculations and estimates when the 'pixmask' parameter points to this file.

The output of sxsbranch is a FITS file composed of two extensions with identical structure. The first extension, BRANCHEST, contains the results of the statistical estimates based on Poisson statistics. The second extension, BRANCHCALC, contains the results of calculations based on the input data file or count rate. Each extension contains a group of keywords providing the results for the full array, and columns providing the results for each pixel. The total rates are obtained considering the sum of good and crosstalk events. If the file is from an observation, rather than a simulation, the good events do not include baseline or lost events. If the file is from a simulation, the good events do not include crosstalk. The rates and branching ratios per grade are averages over the entire observation. If the input file is a simulated file from heasim, sxsbranch creates a copy of the input file, adding and filling two columns: PIXEL with the pixel number, and ITYPE with the grade (ITYPE = 0, 1, 2, 3, and 4 for Hp, Mp, Ms, Lp, and Ls GRADES, respectively). Additionally, if 'flagmerge=yes', the PILEUP column in the output events file is set to 1 for merged events, or to 0 otherwise.

PARAMETERS

infile [filename]

Name of the input event FITS file or NONE. Input files may be either the output event file from a heasim SXS simulation, or an SXS event file from an observation, as specified by the 'filetype' parameter. If set to NONE, branching ratios are calculated based on the values of the 'countrate' and 'exposure' parameters. If 'filetype' is set to sim, a copy of this file with additional PIXEL and ITYPE columns is created with the same name, but with with ".out" appended.

filetype = sim [string sim|real]

Type of input event file. Set 'filetype' to sim if 'infile' is a simulated SXS event file from heasim; set 'fileype' to real if 'infile' is from an observation. This parameter is ignored if 'infile' is set to NONE.

outfile = branch.out [filename]

Name of the output file containing the calculated, and statistically estimated, branching ratios.

countrate = 1.0 [double]

Count rate [cts/s] for the entire SXS array. This parameter is only valid if 'infile' is set to NONE.

exposure = 1000.0 [double]

Exposure time [s]. This parameter is only valid if 'infile' is set to NONE.

pixfrac = NONE [string]

Name of the ASCII file with the distribution of the fractional counts over pixels. If set to NONE, the count distribution is assumed uniform over all pixels. The distribution is used for the statistical estimates, and to distribute counts when 'infile' is set to NONE.

pixmask = NONE [string]

Name of the ASCII file used to exclude pixels in all calculations of the branching ratio. If 'pixmask' is set to NONE, all pixels are included. This parameter is valid for all calculations, and for the associated statistical estimates.

(ctelpixfile = CALDB) [filename CALDB|file name]

Name of the FITS file with the SXS electrical pixel map. The file contains information on how the pixels are wired, and therefore which pixels are considered nearest and next-nearest when considering crosstalk. If the parameter is set to CALDB, the file is read from a file in the calibration database, CalDB.

(dtprimary = CALDB) [string]

Time interval [ms] used to distinguish primary from secondary events in the grade calculation. The default value corresponds to the current on-board software setting; it should not be modified. If the parameter is set to CALDB, the value is read from a file in the CalDB.

(dtmidhigh = CALDB) [string]

Time interval [ms] used to distinguish mid- from high-resolution events. The default value corresponds to the current on-board software setting; it should not be modified. If the parameter is set to CALDB, the value is read from a file in the CalDB.

(dtlowmid = CALDB) [string]

Time interval [ms] used to distinguish low- from mid-resolution events. The default value corresponds to the current on-board software setting; it should not be modified. If the parameter is set to CALDB, the value is read from a file in the CalDB.

(calpixrate = 6.0) [double]

Count rate [cts/s] in the SXS calibration pixel (pixel 12). This parameter is only used for statistical estimates.

(ctphafrac1 = 0.0) [double]

Energy ratio of crosstalk to original event energy for nearest electrically bonded pixels. This parameter is used for statistical estimates, or if 'infile' is set to NONE or 'filetype' is set to sim. For the latter, events of energy E are assumed to induce crosstalk in the nearest electrically bonded pixels if ctphafrac1*E > enrgthr. For the statistical estimate of branching ratios, or if 'infile' is set to NONE, this crosstalk is considered if ctphafrac1 > 0, since energy is irrelevant to the procedure.

(ctphafrac2 = 0.0) [double]

Energy ratio of the next-nearest electrically bonded pixels to the original, due to crosstalk. This parameter is used for statistical estimates, or if 'infile' is set to NONE or 'filetype' is set to sim. For the latter, events of energy E are assumed to induce crosstalk in next-nearest electrically bonded pixels if ctphafrac2*E > enrgthr. For the statistical estimate of branching ratios, or if 'infile' is set to NONE, this crosstalk is considered if ctphafrac2 > 0, since energy is irrelevant to the procedure.

(debin = 0.5) [double]

Value of energy bin width [eV] that converts PI channel bin to energy used in the crosstalk calculation. This parameter is only valid if 'filetype=sim'.

(enrgthr = 0) [double]

Energy threshold [eV]. This parameter is only valid if 'filetype' is set to sim. Events of energy E are assumed to induce crosstalk in adjacent pixels if ctphafrac1*E > enrgthr, and next-nearest pixels if ctphafrac2*E > enrgthr.

(flagmerge = no) [boolean yes|no]

If set to yes, events separated in time by intervals smaller than that given by the 'dtmerge' parameter are merged, up to a maximum total time interval set by the 'dtmax' parameter. This parameter is only valid if 'infile' is set to NONE or if 'filetype' is set to sim.

(dtmerge= 2.0) [double]

Time interval [ms] within which consecutive events are merged. Must be less than 'dtlowmid' This parameter is valid if 'infile' is set to NONE, or if 'filetype' is set to sim and 'flagmerge' is set to yes.

(dtmax = 12.0) [double]

Maximum time [ms] within which consecutive events are merged. This parameter is valid if 'infile' is set to NONE, or if 'filetype' is sim and 'flagmerge' is set to yes.

(maxenergy = 15.0) [double]

Maximum energy [keV] for merged events. Merged events created from events with total summed energy greater than 'maxenergy' are discarded. This parameter is valid if 'infile' is set to NONE, or if 'filetype' is set to sim and 'flagmerge' is set to yes.

(flagburst = no) [boolean yes|no]

Flag to distribute the count rate based on a burst-like light curve defined by the parameters 'ratburst', 'tburst', 'trise', and 'tdecay'. If set to no, the count distribution is uniform within the exposure. This parameter is only valid for 'infile=NONE'.

(ratburst = 30.0) [double]

Ratio of the burst peak rate to the quiescent rate. This parameter is only valid if 'infile' is set to NONE and 'flagburst' is set to yes.

(tburst = 10.0) [double]

Start time [s] of the burst relative to start of the exposure. This parameter is only valid if 'infile' is set to NONE and 'flagburst' is set to yes.

(trise = 3.0) [double]

Rise time [s] for the burst profile. The burst rise is assumed to be linear. This parameter is only valid if 'infile' is set to NONE and 'flagburst' is set to yes.

(tdecay = 60.0) [double]

Decay time [s] for the burst profile. The burst profile is assumed to be an exponential function of time. This parameter is only valid if 'infile' is set to NONE and 'flagburst' is set to yes.

(tstart = 0.0) [double]

Time [s] since CALDB reference time (first valid date and time), to use for CALDB query if 'infile' is set to NONE.

(seed = 0) [integer]

Random number generator seed; uses system time for 'seed=0'.

(buffer = -1) [integer -1|0|N]

Rows to buffer (-1=auto, 0=none, N>0=number of rows).

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records task parameters in HISTORY.

EXAMPLES

1. Calculate the branching for the real SXS event file sxs_real.fits, writing the output to sxsbranch.out. For purposes of the semi-analytic estimate, distribute the source counts as a point source.

   sxsbranch infile=sxs_real.fits fileype=real outfile=sxsbranch.out pixfrac=pixfrac.txt pixmask=NONE 

2. Calculate the branching for a simulated event file with 1 eV PI channel widths, ignoring crosstalk in the branching calculations and estimates, and the calpixel in the estimates. Mask the outer 20 pixels from the calculations and estimates.

   sxsbranch infile=sim.fits fileype=sim outfile=sxsbranch.out pixfrac=pixfrac.txt pixmask=pixmask.txt \ 
      ctphafrac1=0.0 ctphafrac2=0.0 calpixrate=0.0 debin=1.0 

3. Calculate the branching for a simulated event file with 1 eV PI channel widths, including crosstalk in the branching calculations and estimates, and the calpixel in the estimates. For the simulated event list, crosstalk events are added to nearest-bonded pixels if (0.00125 * the original energy) exceeds a 10 eV threshold, and to next-nearest-bonded pixels if (0.0005 * the original energy) exceeds 10 eV.

   sxsbranch infile=sim.fits fileype=sim outfile=sxsbranch.out pixfrac=pixfrac.txt pixmask=NONE \ 
      ctphafrac1=0.00125 ctphafrac2=0.0005 debin=1.0 enrgthr=10.0

4. Calculate the branching based on a constant count rate of 100 cts/s and an exposure of 1 ks, where the counts are distributed as a point source. Include all possible crosstalk in the branching calculations and estimates.

   sxsbranch infile=NONE fileype=NONE outfile=sxsbranch.out countrate=100 exposure=1000 pixfrac=pixfrac.txt \
      pixmask=NONE ctphafrac1=0.001 ctphafrac2=0.0001

5. Calculate the branching based on a count rate of 100 cts/s and an exposure of 1 ks. The counts are distributed as a point source and follow a burst-like light curve with 1 s rise time, 10 s decay time, and burst-to-quiescent ratio of 100. The burst begins at the beginning of the exposure.

   sxsbranch infile=NONE fileype=NONE outfile=sxsbranch.out countrate=100 exposure=1000 pixfrac=pixfrac.txt \
      pixmask=NONE ctphafrac1=0.001 ctphafrac2=0.0001 flagburst=yes ratburst=100.0 tburst=0.0 \ 
      trise=1.0 tdecay=10.0

6. Calculate the branching for a simulated event file with 1 eV PI channel widths, merging events separate in time by less than 2 ms up to a maximum total interval of 30 ms, discarding events where the sum of the energies of the merged events exceeds 20 keV.

   sxsbranch infile=sim.fits fileype=sim outfile=sxsbranch.out pixfrac=pixfrac.txt pixmask=NONE \
      ctphafrac1=0.0 ctphafrac2=0.0 calpixrate=0.0 debin=1.0 flagmerge=yes dtmerge=2.0 \
      dtmax=30.0 maxenergy=20.0

SEE ALSO

LAST MODIFIED