'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.
sxsbranch infile=sxs_real.fits fileype=real outfile=sxsbranch.out pixfrac=pixfrac.txt pixmask=NONE ctelpixfile=pixmap.fitsCalculate 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.0Calculate 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.0Calculate 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.0001Calculate 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.0Calculate 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