NAME

sxsbranch -- Compute rates and branching ratios for each SXS event grade for an input real or simulated file, or based on a count rate

USAGE

sxsbranch infile filetype outfile countrate exposure pixfrac pixmask

DESCRIPTION

'sxsbranch' computes rates and branching ratios for each SXS event grade based on the inputs (file or count rate). These are calculated for each pixel and for the entire array. 'sxsbranch' also statistically estimates the same quantities using the total rates from the input (file or rate) for the entire array using Poisson statistics. 'sxsbranch' operates in three modes: (1) no input file, (2) input simulated file, 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 randomly assigned, and event grades assigned accordingly. The branching ratio is calculated using these simulated events. There are two different supported timing distributions within the exposure: constant count rate profile ('flagburst=no') and burst-like profile ('flagburst=yes'). To simulate a burst-like lightcurve within the exposure, the following parameters also must be set: 'ratburst' is the ratio of burst-peak/quiescent count rate; 'tburst' gives the burst start time in sec after the beginning of the exposure; 'trise' is the rise time (assumed linear) in sec; and 'tdecay' is the decay time (assumed exponential) in sec. The grades are assigned by comparing the resulting time intervals between events with the time interval values in the parameters 'dtmidhigh', 'dtlowmid', and 'dtprimary': (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 at least one preceding or following event within 'dtlowmid'. (d) Primary events are defined as having no preceding event within 'dtprimary'; (e) secondary events at least one preceding event within 'dtprimary'. The outer 20 pixels may be excluded from the branching ratio calculations by setting the parameter 'pixmask=pixmask.txt'.

(2) If the input file is an SXS event file from 'heasim' (infile set to the filename of the SXS event output file simulated with 'heasim' and 'filetype=sim'), 'sxsbranch' calculates the branching ratio using the simulated SXS file. The simulated files do not have grades assigned by 'heasim'. 'sxsbranch' first considers if events are crosstalking (the option if the parameters 'ctphafrac1' and/or 'ctphafrac2' are different from zero), and subsequently assigns the grade using the event time and the calculated time intervals to the preceding and following events in the same pixel. The parameters used to calculate crosstalk are 'debin', 'enrgthr', 'ctphafrac1', and 'ctphafrac2'. These parameters are applied to all pixels. There are two crosstalk types: (a) the first occurs when an event induces crosstalk in the nearest electrical bonded pixel, (b) the second occurs when an event induces crosstalk in the next-nearest electrical bonded pixel. The first is calculated if 'ctphafrac1' is different from 0 and the event has ctphafrac1*PI > (enrgthr/debin). The second is calculated if 'ctphafrac2 'is different from 0 and the event has ctphafrac2*PI > (enrgthr /debin). The parameters 'ctphafrac1' and 'ctphafrac2' define the fraction of crosstalk energy to the original event energy, 'enrgthr' is the energy threshold above which crosstalk triggers, and 'debin' is the value of the PI bin in eV. The maximum possible crosstalk is induced for the default 'enrgthr=0'. The electrical proximity of the pixels is defined by the calibration map pixmap.fits (set by the parameter 'ctelpixfile'). Grades are calculated using the 'dtmidhigh', 'dtlowmid', and 'dtprimary' parameters as described above. The outer 20 pixels may be excluded from the branching ratio calculations by setting the parameter 'pixmask=pixmask.txt'.

3) If the input SXS event file is from an observation (infile set to the SXS event filename from an observation and 'filetype=real'), 'sxsbranch' calculates the branching ratio using this SXS observation event file. This option may be used after launch since the branching ratio calculation uses the on-board assigned grades. Baseline and lost events are excluded from the branching ratio calculation. The outer 20 pixels may be excluded from the branching ratios calculation by setting the parameter 'pixmask=pixmask.txt'.

For comparison with the grade distribution statistics compiled from real or simulated events, statistical estimates are 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 > 0 crosstalk is calculated assuming that any pixel crosstalks with all of its nearest and/or next-nearest pixels as defined by the electrical proximity calibration map pixmap.fits (set by the parameter 'ctelpixfile'). The outer 20 pixels may be excluded from the branching ratios calculation by setting the parameter 'pixmask=pixmask.txt'. The fraction of different grades in each pixel is assigned using the 'dtmidhigh', 'dtlowmid', and 'dtprimary' parameters as described above, and assuming Poisson statistics.

'sxsbranch' can simulate pileup defined as occurring when events in a given pixel separated by small intervals cannot be distinguished, if the 'flagmerge' parameter is set to 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 there is a 'heasim' input file, the energy of the merged event 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.

(a) The pixfrac.txt file is used in the statistical estimates, and for simulating events if 'infile=none'. The file contains the distribution fraction of the counts in the total array based on the PSF. (b) The pixmap.fits file is used when including crosstalk in calculating branching ratios for 'filetype=sim' or 'infile=none', as well as for the associated statistical estimates. The file contains information on the electrical proximity of the pixels necessary to define crosstalk among pixels. (c) The pixmask.txt is used to exclude pixels from the calculation when calculating branching ratios, and for the associated statistical estimates.

The output of 'sxsbranch' is a FITS file with 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, 4 for HP, MP, MS, LP, LS, respectively). Additionally, if 'flagmerge=yes' the PILEUP column in the output events file is set to 1 for merged events and 0 otherwise.

PARAMETERS

infile [file]
Name of the input event FITS file. This file is either the output event file from a heasim SXS simulation, or an event file from an observation. Infile may be set to NONE when the branching ratio is calculated using the value input in the parameters countrate and exposure. If filetype is set to sim, an event file with added PIXEL and ITYPE columns is created with this name and ".out" appended.

filetype [string]
Type of the input event file. Set fileype to sim if the infile is a simulated event file from heasim; set fileype to real if the infile is from an observation. This parameter is not used if infile is set to NONE.

outfile [file]
Name of the output sxsbranch file with the branching ratio calculation.

countrate [real]
Count rate [ct/s] for the entire array. This parameter is only valid if infile is set to NONE.

exposure [real]
Exposure time [s] for the entire array. This parameter is only valid if infile is set to NONE.

pixfrac [string]
Name of the ASCII file with the distribution of the fractional counts in the pixels. The file has two columns. The first contains the SXS pixel number. The second contains the fraction of counts that fall in each pixel. If set to NONE, the count distribution is uniform in all pixels. This is used for the statistical estimates, and to distribute counts when infile is set to NONE.

pixmask [string]
Name of the ASCII file to exclude pixels in all calculations of the branching ratio. The file has two columns. The first contains the SXS pixel number. The second is set either to 0 or 1 to include or exclude pixels in the calculation, respectively. If pixmask is set to NONE all pixels are included. This parameter is valid for all calculations, as well as for the associated statistical estimates.

(ctelpixfile = CALDB) [file]
Name of the FITS file with the SXS electrical pixel map. The file contains the mapping of how the pixels are wired and therefore the pixels that are nearest and next nearest when considering crosstalk. If the parameter is set to CALDB, the file is read from the calibration database.

(dtprimary = 69.92) [string]
Time interval [ms] used to distinguish primary from secondary events in the grade calculation. The value is set to 69.92 ms and corresponds to the current on-board software setting. It should not be modified. If the parameter is set to CALDB, the file is read from the calibration database.

(dtmidhigh = 69.92) [string]
Time interval [ms] used to distinguish mid- from high-res. The value is set to 69.92 ms and corresponds to the current on-board software setting. It should not be modified. If the parameter is set to CALDB, the file is read from the calibration database.

(dtlowmid = 17.95) [string]
Time interval [ms] used to distinguish low- from mid-res. The value is set to 17.95 ms and corresponds to the current on-board software setting. It should not be modified. If the parameter is set to CALDB, the file is read from the calibration database.

(calpixrate = 6.0) [real]
Count rate in [cts/s] in the SXS calibration pixel (pixel 12). This parameter is only used for statistical estimates. The default value is 6.0 count/sec.

(ctphafrac1 = 0.006) [real]
Energy ratio of the nearest electrically bonded pixels to the original, due to crosstalk. This parameter is used for statistical estimates, and 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 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.001) [real]
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 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) [real]
Value in eV to convert a PI channel bin to energy. This parameter is only valid if filetype is set to sim. The conversion of PI to energy is used in the crosstalk calculation. The current value for the output of heasim should be set to 1 eV.

(enrgthr = 0) [real]
Energy threshold, in 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]
Flag to merge events separated in time by intervals smaller than that given by the dtmerge parameter. This parameter is valid if infile is set to NONE or if filetype is set to sim. Consecutive events separated in time by less than dtmerge in a given pixel are combined into a single event up to a total time interval given by the dtmax parameter, and discarded if the sum of their energies exceeds the value given by the maxenergy parameter. Crosstalk events are added, and events are graded based on the event list after merging. If filetype is set to sim, the PILEUP column in the output events file is set to 1 for such merged events and 0 otherwise (yes/[no]).

(dtmerge= 2.0) [real]
Time interval [ms] within which consecutive events are merged. This parameter is valid if infile is set to NONE or if filetype is set to sim, and flagmerge is set to yes. Must be less than dtlowmid, and reflect the limitations of the on-board electronics to distinguish events within dtmerge.

(dtmax = 12.0) [real]
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. If events arrive separated in time by less than the interval defined by dtmerge, dtmax defines the maximum total time interval within which events are merged.

(maxenergy = 15.0) [real]
Maximum energy, in keV, for merged events. Merged events created from events with total summed energy greater than this 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]
Flag to distribute the count rate as a burst-like lightcurve. This parameter is only valid for infile is set to NONE. If set to yes, event times are distributed as a burst profile lightcurve defined by the parameters ratburst, tburst, trise, and tdecay. If set to no, the count distribution is uniform within the exposure (yes/[no]).

(ratburst = 30.0) [real]
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) [real]
Start time of the burst in sec after the beginning of the exposure. This parameter is only valid if infile is set to NONE and flagburst is set to yes.

(trise = 3.0) [real]
Rise time in sec for the burst profile. The rise time 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) [real]
Decay time in sec for the burst profile. The decay time is assumed exponential. This parameter is only valid if infile is set to NONE and flagburst is set to yes.

(tstart = 0.0) [real]
Time since 2014 [s] 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]
Rows to buffer (-1=auto, 0=none, >0=numrows)

(clobber = no) [boolean]
Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]
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]
Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]
Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]
Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string ql|hl|q]
Mode to query the parameter file. Acceptable values include: "ql (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).(Optional)

EXAMPLES

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 ctelpixfile=pixmap.fits
Calculate the branching for a simulated event file, 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 ctelpixfile=pixmap.fits ctphafrac1=0.0 \
  ctphafrac2=0.0 calpixrate=0.0
  
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 X the original energy exceeds a 10 eV threshold, and to next-nearest-bonded pixels if 0.0005 X the original energy exceeds 10 eV.
  sxsbranch infile=sim.fits fileype=sim outfile=outfile=sxsbranch.out pixfrac=pixfrac.txt pixmask=none ctelpixfile=pixmap.fits ctphafrac1=0.00125 \
  ctphafrac2=0.0005 debin=1.0 enrgthr=0.0
Calculate the branching based on a constant count rate of 100 cts/sec and an exposure of 1 ksec (no input file), 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 100 1000 pixfrac=pixfrac.txt pixmask=none ctelpixfile=pixmap.fits ctphafrac1=0.001 \
  ctphafrac2=0.0001
Calculate the branching based on a count rate of 100 cts/sec and an exposure of 1 ksec. The counts are distributed as a point source, and follow a burst-like light curve with 1 second risetime, 10 second 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 100 1000 pixfrac=pixfrac.txt pixmask=none ctelpixfile=pixmap.fits ctphafrac1=0.001 \
  ctphafrac2=0.0001 flagburst=yes ratburst=100.0 tburst=0.0 trise=1.0 tdecay=10.0
Calculate the branching for a simulated event file with 1 eV PI channel widths, merging events separated 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 exceed 15 keV.
  sxsbranch infile=sim.fits fileype=sim outfile=sxsbranch.out pixfrac=pixfrac.txt pixmask=none ctelpixfile=pixmap.fits ctphafrac1=0.0 ctphafrac2=0.0 \
  calpixrate=0.0 debin=1.0 flagmerge=yes dtmax=30.0 maxenergy=15.0
  

SEE ALSO

heasim, sxsflagpix, sxssecid

LAST MODIFIED

2017 March 20