eSASS task: FLAREGTI

Scope

This document provides a description of the algorithm and instructions for the correct usage of the FLAREGTI task, part of the eSASS (the eROSITA Science Analysis Software System) suite.

Description

FLAREGTI creates good-time-intervals (GTIs) which can be used to filter flares from an event file. The task creates a combined lightcurve of the telescope modules in a selected energy band with a chosen time binning. It then creates GTIs by choosing rate thresholds which are dynamically chosen as a function of position to optimise the detection of faint sources. Alternatively, the task can be used to calculate the GTIs for a fixed rate threshold. The produced GTIs are normally written to the FLAREGTI1-7 extensions of the input FITS event file, but can be written to a separate FITS GTI file. Please note that FLAREGTI does not itself apply the produced GTIs to the input data; EVTOOL can be used to make a filtered event file.

Algorithm

The steps of the algorithm used by FLAREGTI are listed below:

1. Load the events in the input event file eventfile, the set of input GTIs given by the extensions GTI1 to GTI7 (or given by parameter gtitype) and the input attitudes given by the extensions CORRATT1 to CORRATT7.
2. Start with an input set of GTIs, taken from those in GTI1-GTI7.
3. Create an image in the rectangle given by the parameters xmin, ymin, xmax and ymax, binning by a factor of binsize, using a range in PI values between mask_pimin and mask_pimax filtering by the input GTI. Using this image, identify pixels which have a maximum-likelihood significance of detml or greater than their surroundings (measured in a surrounding 5x5 pixel box). These high-significance pixels are removed from a mask image.
4. Construct a lightcurve from the event file. Counts are summed within a time bin of timebin seconds within a nominal field of view (FoV; currently set to a radius of 37126.7 sky pixels), selecting events between a PI values of pimin and pimax, within input GTIs, excluding masked regions. The average area within each time bin is calculated by calculating the average sky area in square degrees within the FoV which are unmasked, sampling using 1 second time bins. The average exposure for all the telescope modules (TMs) within the GTIs is also calculated in each time bin. The lightcurve rate is calculated by dividing the number of counts by the area and exposure. Bins with zero area or exposure are removed from the lightcurve.
5. The area for which the mask image is defined is divided into a grid, splitting the x and y range by the value given by the parameter gridsize. Each of these grid points has a threshold lightcurve rate (actually surface brightness rate) to be computed later.
6. If the parameter threshold has a positive value, this selects a fixed surface brightness rate threshold for all time bins and grid points. Otherwise, a dynamic threshold is computed (see step 8).
7. For each grid point, individual lightcurves are constructed from those time bins where the centre of the grid point is within the field of view of the telescope (as defined by the parameter fov_radius).
8. In the dynamic threshold mode, a separate threshold rate is calculated for each grid point. The chosen threshold for each point is the rate which minimises the count rate of the faintest detectable source at that position. The result is an array of gridsize×gridsize threshold values. In detail, for a particular grid point, a range of threshold rates are examined. For each of these thresholds, the per grid-point lightcurve is filtered to exclude values above threshold, resulting in an average background surface brightness rate. With this background, the minimum count rate of a source detectable above it can be calculated, given a detection likelihood (source_like) and source size (source_size), assuming that the source is a flat disc and a flat background distribution. The chosen threshold at a grid point is the one which minimises this detectable rate.
9. If the parameter max_threshold is positive, then the threshold surface brightness rate for each grid point is forced to be at most this value.
10. For each bin in the total lightcurve, it is determined which grid point is closest to the aimpoint of the telescope. The fixed or dynamic threshold is taken for this grid point. If the lightcurve rate is less than this threshold the time interval for the time bin is included in the combined flare GTI.
11. For each telescope module the intersection of the combined flare GTI with each input GTI (taken from the GTI1-GTI7 extensions), to produce the per-module flare GTIs.
12. The process is repeated from step 3, using the output flare GTIs as the input GTIs, instead of the ones given by the GTI1-GTI7 extensions. The number of repetitions is given by the parameter mask_iter. This iteration is designed to help the detection of point sources if the input is heavily flared.
13. Write the final mask to a file with filename mask, if write_mask is set. Write the final lightcurve and threshold rates to a file with filename lightcurve, if write_lightcurve is set. Write a 2D image of the threshold rates with filename thresholdimg, if write_thresholdimg is set.
14. If the parameter gtifile is set, the output GTIs are written to the filename given. If unset, as is the default, FLAREGTI1-FLAREGTI7 extensions are added or replaced in the input event file.

Parameters

Default values are given in square parentheses.

• eventfile: Name of input event file
• gtifile[none]: Optional name of output GTI file. If unset, the FLAREGTI extensions are added to the input event file.
• pimin[200]: Lower PI bound of energy range for lightcurve creation
• pimax[10000]: Upper PI bound of energy range for lightcurve creation
• mask_pimin[200]: Lower PI bound of energy range for finding sources to mask
• mask_pimax[10000]: Upper PI bound of energy range for finding sources to mask
• xmin[-108000]: Sky pixel range for flare analysis: Xmin
• xmax[108000]: Sky pixel range for flare analysis: Xmax
• ymin[-108000]: Sky pixel range for flare analysis: Ymin
• ymax[108000]: Sky pixel range for flare analysis: Ymax
• gtitype[GTI]: Input GTI type
• gridsize[18]: Number of grid points per dimension for dynamic threshold calculation
• binsize[1200]: Bin size of mask image (unit: sky pixels)
• detml[10]: Likelihood threshold for mask creation
• timebin[20]: Bin size for lightcurve (unit: seconds)
• source_size[25]: Diameter of source extraction area for dynamic threshold calculation (unit: arcsec)
• source_like[10]: Source likelihood for automatic threshold calculation
• fov_radius[30]: FoV radius used when computing a dynamic threshold (unit: arcmin)
• threshold[-1.]: Flare threshold; dynamic if negative (unit: counts/deg^2/sec)
• max_threshold[-1.]: Maximum threshold rate, if positive (unit: counts/deg^2/sec). If set this forces the threshold to be this rate or less.
• write_mask[yes]: Write mask image?
• mask[mask.fits]: Name of optional output mask image
• mask_iter[3]: Number of repetitions of source masking and GTI creation
• write_lightcurve[yes]: Write lightcurve?
• lightcurve[lightcurve.fits]: Name of optional output lightcurve
• write_thresholdimg[no]: Whether to write a FITS threshold image
• thresholdimg[threshold.fits]: Name of threshold image

Input files

• eventfile(EVENTS, GTIx, and CORRATTx extensions): The task takes a standard eROSITA events file, using the EVENTS extension to construct the lightcurves, the GTIx extensions as the input GTIs and the CORRATTx extensions to calculate the pointing location of the telescope.

Output files

• eventfile(FLAREGTIx): FLAREGTI HDUs are appended/replaced in the input event file if the gtifile parameter is not set.
• gtifile (STDGTIx): Output file where FLAREGTI Has will be written, if set. File is completely overwritten. The GTIs are written with HDU names of STDGTI1-STDGTI7.
• mask (primary, image): Image containing masked pixels, if write_mask is set. Pixels with 1 are included, while 0 pixels are excluded. A second IMAGE HDU is written to this file containing an image of the region in the mask energy band.
• lightcurve (LIGHTCRV): Lightcurve table, written if write_lightcurve is set. Columns include the time (TIME; excluding bins outside the input GTIs), the number of counts in the bin (COUNTS), the rate (RATE; cts/s/deg^2), the threshold rate for the time bin (THRESHOLD; cts/s/deg^2), exposure (EXPOSURE; s), area (AREA; deg^2), average X position (X) and average Y position (Y). Also included in the table is the FILTRATE column which contains the rate, but with bins completely excluded by the FLAREGTIs marked as -1.
• thresholdimg: Image of the threshold rate values, with the same dimensions as the mask image.

Notes

• The sky coordinate range given is increased in each direction by the radius of the field of view and the scan speed within half a time bin.
• The default sky pixel coordinate range (xmin, ymin, xmax, ymax) is designed for a single sky tile. If processing merged sky tiles, the range should be increased. It is also recommended to increase the number of grid points similarly (gridsize).
• The parameter which affects the sensitivity of the flare detection most is source_size. If making images, or if interested in extended sources, the user can try values such as 50 or 100 to better filter lower-level flares.
• Although there is a simple point source masking routine in FLAREGTI, bright point sources will not be completely masked due to the PSF. Therefore the filtering may remove periods when brighter sources increase in flux. This effect can be reduced by using a narrower range in PI values to select the energies where the telescope has less effective area (e.g. pimin=5000).
• If the user merges data from separate tiles or sky positions together, care should be taken if FLAREGTI is applied. If the tool is run on separate tiles, the produced GTIs may be inconsistent on adjoining sides of adjacent tiles. Therefore, if the data are filtered, then merged with EVTOOL, flares could be put back into the data near a tile edge that were removed in one of the tiles. The currently recommended procedure is to first merge the tile event files with EVTOOL, reproject the events to a common coordinate system with RADEC2XY, apply FLAREGTI to the merged file, then filter the GTIs with EVTOOL.

Examples

• 	flaregti events.fits
        

  Perform automatic flare detection using a dynamic threshold. FLAREGTIx extensions are appended or replace those in the event file. The lightcurve is written to the file lightcurve.fits and the mask image is written to mask.fits.

• 	flaregti events.fits gtifile=flaregti.fits threshold=30
        

  Filter periods with a rate greater than 30 cts/s/deg^2, writing the STDGTIx extensions to flaregti.fits.

Known issues

1. The xmin/xmax/ymin/ymax parameter values are forced to be within the data range of the X and Y columns in the event files, as given by the TLMIN and TLMAX header keywords. If these keywords are not present, they are forced to be ±108000. In this eSASS release, RADEC2XY can be used to make these header keywords reflect the actual data range. Please note that they may be removed by EVTOOL.
2. Separate FLAREGTI-produced GTI files cannot be applied to event files by EVTOOL in this eSASS release.