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.
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 optimize 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.
Load the events in the input event file eventfile, the set of input GTIs given by the extensions GTI1 to GTI7 and the input attitudes given by the extensions CORRATT1 to CORRATT7.
Start with an input set of GTIs, taken from those in GTI1-GTI7.
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.
Construct a lightcurve for 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.
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.
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.).
For each grid point, it is determined for which time bins the centre of the grid point is within the radius of the telescope (as defined by the parameter fov_radius), as the telescope scans over the field.
When computing a dynamic threshold, for each grid point a range of different threshold rates are scanned over.
The best threshold for each point is the rate which minimises the detected source rate.
The result is an array of gridsize×gridsize threshold values.
In detail, for each of these thresholds, the average background surface brightness is calculated for the above light curve bins for those bins when the rates are less than this value.
Given these background surface brightnesses, the minimum rate of a source detected using the likelihood given by the parameter source_like is determined, assuming the source has a flat extent of a size given by the parameter source_size.
If the parameter max_threshold is positive, then the threshold surface brightess rate for each grid point is forced to be at most this value.
For each bin in the 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.
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.
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.
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.
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.
Default values are given in square parentheses.
- eventfile: Name of input event file
- gtifile: Optional name of output event file. If unset, the FLAREGTI extensions are added to the input event file.
- pimin: Lower PI bound of energy range for lightcurve creation
- pimax: Upper PI bound of energy range for lightcurve creation
- mask_pimin: Lower PI bound of energy range for finding sources to mask
- mask_pimax: Upper PI bound of energy range for finding sources to mask
- xmin[-108000]: Sky pixel range for flare analysis: Xmin
- xmax: Sky pixel range for flare analysis: Xmax
- ymin[-108000]: Sky pixel range for flare analysis: Ymin
- ymax: Sky pixel range for flare analysis: Ymax
- gridsize: Number of grid points per dimension for dynamic threshold calculation
- binsize: Bin size of mask image (unit: sky pixels)
- detml: Likelihood threshold for mask creation
- timebin: Bin size for lightcurve (unit: seconds)
- source_size: Diameter of source extracton area for dynamic threshold calculation (unit: arcsec); this is the most important parameter if optimizing for extended sources
- source_like: Source likelihood for automatic threshold calculation
- fov_radius: 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: 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
- 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.
- 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 HDUs 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.
No known issues.