It is known that even cleaned XRISM Resolve data carry anomalous low-resolution secondary (Ls) events that are not due to a celestial X-ray source, and it is also known that the distributions of events amongst the five grades (apparent branching ratios) show anomalous behavior. In particular, there are discrepancies between observed and predicted branching ratios, which should be energy-independent, but the latter expectation is often not observed. Grade distribution depends on count rate in a given pixel, and due to the complex point-spread function (PSF) of XRISM, every pixel can have a unique grade distribution. In bright, time-variable sources, there is complex variability of the grade distribution in every pixel. The rslbratios tool calculates a variety of diagnostics that can help to form a mitigation strategy for the analysis of data for a given observation. In particular, the tool calculates:
(1) Temporal variability of grade fractions and count rates separated by grade, per pixel, and for a specified group of pixels. (2) Time-averaged count rates by grade, and branching ratios, along with theoretical corresponding predicted quantities. (3) Grade-separated images of counts and grade fractions, time-averaged and integrated over energy. (4) Three special grade ratio functions vs. energy that, when considered together, help to determine a mitigation strategy for creating Resolve RMFs that minimize systematic errors in the absolute effective area. (5) Quantification and preview of the effect of rise-time and proximity screening on spectra. (6) Proximity of the maximum total count rate per Resolve quadrant to the PSP limit.
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'. Note: 'dtprimary' and 'dtmidhigh' are always the same value. The rslbratios task calculates the branching ratios and count rates based on the ITYPE column (in a Resolve event file), which is assigned by on-board processing.
The rslbratios task can work with either a screened Resolve event file or an unfiltered Resolve event file. The type of file being used should be set by the 'filetype' parameter. If the 'filetype' paramater is set to 'uf', the file will be checked for whether the total count rate approaches the PSP limit within a user specified perecentage, supplied by the parameter 'pspthresh'. If the 'filetype' parameter is set to 'cl', the file will not be checked for PSP limit violations. The total count rate is calculated per quadrant and is compared to the product of the 'psplim' parameter and the 'pspthresh' parameter. This accomodates different outcomes for different quadrants; for example, one quadrant may approach the PSP limit, while the other quadrants do not. If a quadrant's count rate exceeds the previously mentioned product, the user will be notified by a terminal output message and a WARNING message in the log. This is an indication that further screening or investigation should be done, but it may not always be possible to mitigate the PSP limit threshold from being exceeded. The 'psplim' value should not be changed from the default (50 cts/s) under normal operation. It is made available as a parameter to further investigate the effects of fine tuning the PSP limit.
For comparison with the time-averaged and energy-averaged grade distribution compiled from real events, theoretical predictions are also computed. The predictions can be directly compared with the corresponding observed quantities for all of the pixels except the ones specified in the pixlist parameter. For pixel 12, the calibration pixel, the rate is always set to 0. Expected grade distributions are calculated based on the count rate per pixel, using the 'dtmidhigh', 'dtlowmid', and 'dtprimary' parameters, and assuming Poisson statistics.
The string specified by 'pixlist' should contain pixel values ranging from 0 to 35, separated by commas. Every pixel that is listed in the string will be excluded from the task. For example, if you want to exclude pixels 1-8, then 'pixlist' should be pixlist="1,2,3,4,5,6,7,8". Note that 'pixlist' in other XRISM sofware tasks is an inclusion list.
Proximity screening rejects events that are closer together in time than frame events, so the number of false positives increases as the source count rate increases. Rise-time screening can still leave non-source events present. Therefore, the user may want to preview the effects of these screening recipes before committing to formally applying them to make spectra for analysis, and the rslbratios tool facilitates this. The rslbratios task will check whether the file input event file has undergone rise time and proximity screening, and create spectra when it detects that that rise time and/or proximity screening has not been done. It will also create a difference spectrum between the screened and unscreened data so that the differences may be examined more precisely. The rise-time selection expression is specified by the input parameter 'risetmexpr'. Setting 'risetmexpr=standard' applies the expression that is recommended in XRISM data analysis guides:
(((PI>=600)&&((RISE_TIME+0.00075*DERIV_MAX)>46)&&((RISE_TIME+0.00075*DERIV_MAX)<58)&&(ITYPE<4))||(ITYPE==4))
The task checks whether the same expression specified by 'risetmexpr' has already been applied to the input
event file. The rise-time screened file spectrum is compared to that from the original input event file, and if
there are differences, a difference spectrum is generated.
The proximity screening expression applied by the task is:
(STATUS[4]==b0)
The proximity-screened spectrum is compared to that from the original event input file, and if
there are differences, a difference spectrum is generated.
Finally, both rise-time and proximity screening are applied to the input event file. The screened file spectrum is compared to that from the original input event file, and if there are differences, a difference spectrum is generated.
There are a variety of output files that are created by the rslbratios task. The names of the output files all start with the 'outroot' string input parameter, followed by an underscore. Additionally, many of the output file names will also contain a string that represents the energy band, if one is provided (energy band is set by the 'eband' parameter). The files are listed below, accompanied by a brief description of what each file contains. The examples below will use the default, 'outroot = branch', and an energy band of 2.5 to 10 keV ('eband=2.5-10').
(1) branch_2p5keVto10keV_brVpxcnt.fits:
This file contains each grade's branching
ratio, each grade's time-averaged event rate, and the overall time-averaged event rate
for each pixel. All quantities are tabulated as a function of pixel ID number. This file contains 5 extensions.
FULLBAND_LSREAL is derived from the event file with no energy band restriction
(i.e., events of all energies in the file are included), and assuming all Ls events are real. Similarly,
FULLBAND_LSFALSE is derived from the event file with no energy band restriction but
assumes all Ls events are false. PRED_FULLBAND_LSREAL contains predicted quantities
based on Poisson statistics, for the full band, assuming that all Ls events are real. EBAND_LSREAL is
derived from the event file with the input energy band restriction, and assuming all
Ls events are real. EBAND_LSFALSE is derived from the event file with the input
energy band restriction, and assuming all Ls events are false.
(2) branch_2p5keVto10keV_pcntVgeom.fits:
This file tabluates quantities as a function
of geometrical pixel ID number. The geometrical pixel ID lays out the Resolve
pixels linearly, in a manner that is more harmonious with the PSF than the regular
pixel ID. The geometrical pixel ID list first starts with the central four pixels,
after which pixels in the middle ring are listed in a counter-clockwise order,
finally followed by the outer pixels, again listed in a counter-clockwise order.
This file contains each grade's event rate, each grade's branching ratio, and the total
event rate for each pixel, where the pixel number is given by the geometrical pixel ID.
The geometrical pixel number mapping to the regular pixel ID is given in the table below.
The output file branch_2p5keVto10keV_pcntVgeom.fits contains 5 extensions,
similar to branch_2p5keVto10keV_brVpxcnt.fits. Please see the branch_2p5keVto10keV_brVpxcnt.fits
description above for the contents of each extension.
geometic ID | regular ID geometric ID | regular ID
0 | 0 18 | 19
1 | 17 19 | 21
2 | 18 20 | 23 -corner
3 | 35 21 | 24
4 | 13 -corner, inner ring start 22 | 26
5 | 10 23 | 34
6 | 20 24 | 32
7 | 22 -corner 25 | 30 -corner
8 | 25 26 | 29
9 | 33 27 | 27
10 | 31 -corner 28 | 1
11 | 28 29 | 3
12 | 2 30 | 5 -corner
13 | 4 -corner 31 | 6 -corner
14 | 7 32 | 8
15 | 15 33 | 16
16 | 11 -outer ring start 34 | 14
17 | 9 35 | 12
(3) branch_2p5keVto10keV_hist.fits:
This file contains the grade fraction and number
of counts for each grade for the group of selected pixels (i.e., all pixels not listed in
'pixlist'). Each row corresponds to a grade, and lists three quantities per grade, all
averaged over time and energy: (1) full energy-band integration of the input event data,
(2) theoretical predicted values, (3) restricted energy-band integration of the input
event data. The first extension contains the grade fraction information, and the second
extension contains the absolute counts.
(4) branch_full_lc.fits, branch_gradeFrac_lc.fits, branch_pix_lc.fits:
These are three light curve files that are generated if 'lcurve=yes'. These files are tabulated as
a function of time, but cannot be used by any downstream HEASoft software designed for
light curves, such as lcurve.
The bin width (in seconds) for the light curves may be set by the 'lcbin' parameter.
The branch_full_lc.fits file contains each grade's count rate for the full array, except for
the pixels listed in 'pixlist'. The branch_gradeFrac_lc.fits file contains the grade fraction
for each pixel, for all of the event grades. The branch_pix_lc.fits file contains the count
rate for each pixel, for all of the event grades. Each file has two extensions. The first
extension has no energy band restriction, while the second extension has an energy band
restriction set by the 'eband' parameter.
(5) branch_HpFrac.gif, branch_MpFrac.gif, branch_MsFrac.gif, branch_LpFrac.gif, branch_LsFrac.gif:
These files, one for each grade,
contain a plot of the specified grade fraction vs. time for the entire array (exlcuding the
pixels in 'pixlist'). They are
derived from the branch_gradeFrac_lc.fits file, so they will only be made if the light curve
files are made (setting 'lcurve = yes'). To change the bin width in these plots, you must
change the bin width of the light curve files by setting the 'lcbin' parameter.
(6) branch_2p5keVto10keV_pixMap.img, branch_2p5keVto10keV_NoLspixMap.img:
These files contain images of pixel maps in DET
coordinates, for the time-averaged grade fractions, and the absolute counts by grade,
derived from the input events file. The file with the string 'NoLs' in the name
has grade fractions that do not include Ls events. In both files there are images
for both the full energy band and the energy-band restricted data. For
example, the first 4 images in the files have extension names HPCOUNTS, HPFRAC, HPCOUNTS_EBAND,
and HPFRAC_EBAND. Overall, there are 20 or 16 images in the file with and without Ls events respectively
(4 images for each grade). Pixel 12 is located in the lower left corner of these images.
(7) branch_rmf_diagnostics.fits:
Theoretically, the grade branching ratios should
be indepedent of energy. However, real Resolve data show that this is not the case,
in general, partly due to the presence of non-source Ls events. However, the latter
are not the only cause of anomalous branching ratio behavior. Since the normalization
of the net Resolve effective area for a spectrum of a given grade is affected by
anomalous branching ratio behavior, some mitigation is required to select an optimal
energy-band regime that minimizes inclusion of anomalous behavior. The file
branch_rmf_diagnostics.fits (and the corresponding .gif file) helps to select such an
energy band that can be used to filter an event file that can be input to the tool
rslmkrmf in order to mitigate impact on the net effective area.
The file branch_rmf_diagnostics.gif shows three key grade ratio diagnostics vs.
energy: The black curve is Ls/Hp, the red curve is Hp/(Hp+Mp+Ms+Lp) and the blue curve
is Hp/(Hp+Mp+Ms+Lp+Ls). This file is derived from branch_rmf_diagnostics.fits. The
Ls/Hp line corresponds to the LS/HP column in branch_rmf_diagnostics.fits, the
Hp/(Hp+Mp+Ms+Lp) curve corresponds to the HP/TOTNOLS column, and the Hp/(Hp+Mp+Ms+Lp+Ls)
curve corresponds to the HP/TOT column.
The file branch_rmf_diagnostics.pco contains the plotting instructions and can be
edited and used to generate a "custom" clean plot in PLT (e.g., using fplot).
(8) Spectral Files:
There are four spectral files that can be made
by running the rslbratios task. These files are not in a format that can be
used by any downstream HEASoft software that is designed for spectra such as
XSPEC, or other spectral fitting tools. The spectra are binned to 5 eV bins, and
the center energy of bin number N is [2.5 + (5*(N-1))] eV, where N=1 to 6000. These
files are all derived from Hp events only.
(8a) branch_Hp_spectrum.fits:
This file contains the spectrum from the input event file,
with no additional screening applied.
(8b) branch_rise_Hp_spectra.fits:
This file is created if the input event file
has not already had rise-time screening applied.
The first extension contains the spectrum derived from the
input file with rise-time screening applied, and the second
extension contains the difference between the spectra made without and with
rise-time screening.
(8c) branch_prox_Hp_spectra.fits:
This file is created if the input event file
has not already had proximity screening applied (see expression
given earlier). The first extension contains the spectrum derived from the
input file with the standard proximity screening applied, and the second
extension contains the difference between the spectra made without and with
the standard proximity screening.
(8d) branch_rise_prox_Hp_spectra.fits:
This file is created if the input event file
has not already had rise-time and proximity screening applied.
The first extension contains the spectrum derived from
the input file with rise-time and proximity screening applied,
and the second extension contains the difference between the spectra made
without and with rise-time and proximity screening.
(((PI>=600)&&((RISE_TIME+0.00075*DERIV_MAX)>46)&&((RISE_TIME+0.00075*DERIV_MAX)<58)&&(ITYPE<4))||(ITYPE==4))
rslbratios infile=xa100050020rsl_p0px1000_uf.evt filetype=uf outroot=branch eband="NONE" lcurve=no
rslbratios infile=xa100050020rsl_p0px1000_cl.evt filetype=cl outroot=branch eband="NONE" lcurve=no
rslbratios infile=xa100050020rsl_p0px1000_cl.evt filetype=cl outroot=branch eband="NONE" lcurve=yes
rslbratios infile=xa100050020rsl_p0px1000_cl.evt filetype=cl outfile=branch eband=2-10 lcurve=yes lcbin=50.0
rslbratios infile=xa100050020rsl_p0px1000_uf.evt filetype=uf outfile=branch eband=2-10 lcurve=yes\ lcbin=50.0 pspthresh=0.95
rslbratios infile=xa100050020rsl_p0px1000_uf.evt filetype=uf outfile=branch eband=2-10 lcurve=yes\ lcbin=50.0 pixlist="0,17,18,35" pspthresh=0.95