Xtend data, even after standard screening, may suffer from pixels that have anomalously high counts due to non-source events, most often due to flickering pixels or cosmic-ray echo events. These pixels, hereafter referred to as anomalous pixels, should not be included in data analysis. Their exclusion should be propagated to the exposure map task (xaexpmap), which in turn informs corrections to the effective area (using the xaarfgen task). The xtdpixclip task identifies Xtend anomalous pixels inside of user-specified regions referred to as inclusion regions. A pixel is flagged as anomalous when the number of time-integrated counts is above a user-specified threshold for a given region. Only pixels inside of these inclusion regions are considered. Multiple regions may be specified, each with a corresponding count threshold. This task allows a user to, for example, specify one threshold for a source region and different thresholds for other, source-free regions. The task is typically run twice: once with 'pmode=histo' (this aids the user in selecting the thresholds by constructing distributions of number of pixels vs. counts per pixel), and again with 'pmode=apply', which applies the thresholds. After all anomalous pixels are flagged, the task generates a .fpix file which contains the flagged events in the EVENTS extension, and the list of flagged pixels in the PIXELS extension. The .fpix file can be used as input to the xaexpmap task, and the .expo file output from the latter task is input to the xaarfgen task. The xtdpixclip task also produces a "cleaned" event file that has all of the events from the anomalous pixels removed, and it is this event file that is used for subsequent science or other data analysis. The reason for anomalous numbers of counts in a pixel is not relevant for operation of this task, because selection of the thresholds is empirically based on the counts per pixel distribution. In many cases there will be a clear change in the shape of the distribution above a certain value of counts per pixel that deviates from that due to a celestial source. However, this may not always be the case, and the user must consider the trade-off between accepting some anomalous pixels vs. accepting some false positives. In such cases, an iterative approach can be pursued.
When xtdpixclip is operated with 'pmode=HISTO', the pixel groups inside the specified regions are sorted into uniform intervals of counts per pixel, producing a histogram of number of pixels vs. counts per pixel interval for each region. A FITS file is created with a name based on the 'outroot' parameter; e.g. if 'outroot=xa300036010xtd_p031100010_cl', the histogram file would be named "xa300036010xtd_p031100010_cl_xpc_hist.fits" (where xpc stands for xtdpixclip). This file contains an extension named HISTOGRAM, with columns for the lower boundary, upper boundary, and center of each counts-per-pixel bin (BINLO, BINHI, and BINCEN respectively). The columns REGION01, REGION02, etc. contain the arrays of number of pixels vs. counts per pixel interval. The number in these column names corresponds to the order of the inclusion region files as entered for the 'incregionfiles' parameter. For example, if 'incregionfiles=file1.reg,file2.reg' then column REGION01 will correspond to file1.reg and column REGION02 will correspond to file2.reg. The header of this extension contains keywords corresponding to each region column name whose value is the corresponding region file name. The data in this histogram file can be examined directly to determine a count rate threshold. Alternatively, plots of the region columns may be examined to determine a threshold visually. Simple versions of these plots are generated by this task in HISTO mode using fplot. These plots are created as .gif files and are also named based on the 'outroot' parameter; e.g. if 'outroot=xa300036010xtd_p031100010_cl', the histogram plot for the first region would be named "xa300036010xtd_p031100010_cl_xpc_reg01_hist.gif".
After determining an appropriate threshold for each region from running xtdpixclip in HISTO mode, the task should be run in 'pmode=APPLY' mode. This mode applies the thresholds to the pixels in each specified region, flagging anomalous pixels. Each event belonging to a flagged pixel ends up in the EVENTS extension of the output .fpix file. The .fpix file also has a PIXELS extension that lists all of the anomalous pixels by their DET coordinates. The .fpix file is named based on the 'outroot' parameter; e.g. 'outroot=xa300036010xtd_p031100010_cl' would produce a .fpix file named "xa300036010xtd_p031100010_cl_xpc_rmvpix.fpix" (where xpc stands for xtdpixclip). Additionally, this mode creates a cleaned event file if 'mkclean=yes'. This file is the complement of the .fpix file and is the list of events with all of the flagged events removed. This file is also named based on the 'outroot' parameter. For example, 'outroot=xa300036010xtd_p031100010_cl' would produce a cleaned events file called "xa300036010xtd_p031100010_cl_xpc_clnevt.fits".
The incregionfiles and excregionfiles parameters can also take a default value of "NONE". When using 'incregionfiles=NONE', a single, internally-generated inclusion region that covers the whole FoV of the image will be applied. If 'excregionfiles=NONE' then no exclusion regions will be applied at all. There is an exclusion region file provided in the HEADAS refdata directory called calsrc_XTD_det.reg. This file excludes the Xtend calibration sources. Users may consider using that exclusion region file if it is appropriate for their needs, but it will not be used unless specified.
Both modes ('pmode' set to HISTO or APPLY) make use of inclusion, and optionally, exclusion region files. These files must be formatted as SAO regions in detector coordinates. In APPLY mode the number of inclusion region files must match the number of threshold values in the 'thresholds' parameter. The input region files may contain multiple SAO regions. In the case of an inclusion region file having multiple regions, the threshold that corresponds to that file will be used for all regions in that file. Additionally, complicated regions that make use of multiple inclusion and exclusion regions in a single file may be used. Pixels that are inside of exclusion regions are completely ignored by the tool. This means that all events inside of an exclusion region will be listed in the cleaned events list if one is generated.
The user may specify a PI channel range by means of the energy bounds parameters 'emin' and 'emax' for the lower and upper boundary respectively (units are keV). Events outside of this range are not included in either the histogram nor the pixel flagging algorithm. Whatever energy range is used to flag anomalous pixels, the cleaned event file will have events with all energies removed from anomalous pixels. Likewise, all events that do not occur in anomalous pixels will be included in the cleaned event file, regardless of the values of 'emin' and 'emax'. The user may also specify a GTI file using the 'gtifile' parameter to filter the input event file. Events outside of the GTI are filtered out completely and are therefore not included in either the histogram nor the pixel flagging algorithm. These events will not appear in either the .fpix file nor the cleaned event file, because they are completely filtered out before those files are generated.
Note that the overlaps between the regions in different inclusion region files should be avoided if possible. If regions in two or more files overlap, the threshold for the first of the overlappling files, as ordered in 'incregionfiles', will be applied in the overlapping region or regions. Overlapping inclusion regions in the same region file get the same threshold. Exclusion regions in the 'excregionfiles' list take precedence over inclusion regions if an exclusion region in that list overlaps with an inclusion region. However, the treatment of exclusion regions overlapping with inclusion regions in the 'incregionfiles' list is more complex. In that case, an exclusion region over-rides all inclusion regions that precede it in the list.
xtdpixclip evtinfile=xa300036010xtd_p031100010_cl.evt outroot=MY300036010 pmode=HISTO \
incregionfiles="box1.reg,circle1.reg,box2.reg" excregionfiles="@exc_files.txt"
xtdpixclip evtinfile=xa300036010xtd_p031100010_cl.evt outroot=MY300036010 pmode=APPLY \
incregionfiles="box1.reg,box2.reg,circle1.reg" excregionfiles="@exc_files.txt" \
thresholds="100.0 1250.0 200.0" mkclean=yes
August 25, 2025