NAME
rslbranch - Computes rates and branching ratios for each XRISM Resolve event
grade for a real or simulated input file, or based on a count rate
USAGE
rslbranch infile filetype outfile countrate exposure pixfrac pixmask
DESCRIPTION
The rslbranch task computes rates and branching ratios for each Resolve
event grade, based on an input file or count rate. These are
calculated for each pixel and for the entire array. The rslbranch
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'), the rslbranch task 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 Resolve event file created by
heasim ('infile' parameter set to the file name, and 'filetype=sim'),
the rslbranch task calculates branching ratios from the events in the
simulated Resolve 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', the rslbranch task 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 Resolve event file is from an observation ('infile'
parameter set to the file name, and 'filetype=real'), the rslbranch task
calculates branching ratios based on the columns containing the
pixels, and grade values are assigned by the on-board
processing. 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 rslbranch 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 the parameter
'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 Resolve pixel number; the second the fraction of counts
detected in that pixel. If set to NONE, the count distribution is
uniform over 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 Resolve pixel number; the second is set to
0 if the pixel is to be 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 the rslbranch task 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, the rslbranch task 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 Resolve simulation, or a Resolve 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
".out" appended to the output file name.
- filetype = sim [string sim|real]
- Type of input event file. Set 'filetype' to sim if 'infile' is a
simulated Resolve 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 Resolve 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 Resolve 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 Resolve 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=sim' and
'flagmerge=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=sim'
and 'flagmerge=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=sim' and 'flagmerge=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=NONE' and 'flagburst=yes'.
- (tburst = 10.0) [double]
- Start time [s] of the burst relative to start of the
exposure. This parameter is only valid if 'infile=NONE' and
'flagburst=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=NONE' and
'flagburst=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=NONE' and 'flagburst=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 = 2) [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
- Calculate the branching for a real Resolve event file (OBSID 100050020),
writing the output to rslbranch.out. For purposes of
the semi-analytic estimate, distribute the source counts as a point source.
rslbranch infile=xa100050020rsl_p0px1010_uf.evt filetype=real outfile=rslbranch.out pixfrac=pixfrac.txt pixmask=NONE
- 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.
rslbranch infile=sim.fits filetype=sim outfile=rslbranch.out pixfrac=pixfrac.txt pixmask=pixmask.txt \
ctphafrac1=0.0 ctphafrac2=0.0 calpixrate=0.0 debin=1.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 * the original energy) exceeds a 10 eV threshold, and to next-nearest-bonded pixels if (0.0005 * the original energy) exceeds 10 eV.
rslbranch infile=sim.fits filetype=sim outfile=rslbranch.out pixfrac=pixfrac.txt pixmask=NONE \
ctphafrac1=0.00125 ctphafrac2=0.0005 debin=1.0 enrgthr=10.0
- 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.
rslbranch infile=NONE filetype=NONE outfile=rslbranch.out countrate=100 exposure=1000 pixfrac=pixfrac.txt \
pixmask=NONE ctphafrac1=0.001 ctphafrac2=0.0001
- 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.
rslbranch infile=NONE filetype=NONE outfile=rslbranch.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
- 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.
rslbranch infile=sim.fits filetype=sim outfile=rslbranch.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
heasim,
rslflagpix,
rslsecid
LAST MODIFIED
August 5, 2024