flaregti

erosita/flaregti-1.6

Summary:

Description:

Create flare good-time-interval (FLAREGTI) extensions which can be used to filter flares from a dataset. By default these extensions are added to or replace those in the input event file (eventfile), but the gtifile parameter allows them to be placed in a separate file. A fixed threshold flare rate (in the band pimin to pimax) can be specified using the threshold parameter, otherwise it is dynamically determined for each time bin. A FLAREGTI[1-7] extension is created for each detector, containing the unflared intervals for the input intervals (taken from the GTI[1-7] HDUs in the event file).

Bright sources are masked before the light curve is created. An image of the event file is created using binsize pixels between PI values of mask_pimin and mask_pimax. Pixels with a significance greater than detml compared to the surrounding 5x5 pixels are masked out to create a mask image. By default, this mask image (included areas are 1, and excluded 0) is written to mask, with an image with the same binning in the second HDU.

The lightcurve between PI pimin and pimax in timebin time bins is created from unmasked sky pixels. To compute a rate per unit area, the unmasked field of view area is calculated in each time bin and the GTI of the time bin is used, with no vignetting correction.

For the dynamic threshold computation, the sky region is divided into gridsize by gridsize regions. For each grid point, those lightcurve bins are examined for when the aim point of the telescope is within fov_radius radius. To calculate the count rate threshold for a particular time bin, the grid point nearest the telescope pointing position is chosen. The threshold which minimizes the flux of a source of size source_size which can be detected above the average background rate with likelihood source_like is used. If max_threshold is set, then the automatic threshold rates are forced to be less than this value.

To improve the detection of point sources, the creation of a mask, lightcurve and the calculation of thresholds is repeated by mask_iter iterations, where the GTI obtained in the previous iteration is used for the creation of the mask image. This can be set to 1 to disable the repetition.

Parameters:

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[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
• 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 extracton 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):

Output files:

• eventfile(flaregtiX): FLAREGTI HDUs are appended/replaced in the input event file if the gtifile parameter is not set.
• gtifile: Output file where FLAREGTI HDUs will be written, if set. File is completely overwritten.
• 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.

Examples:

• flaregti events.fits
  Perform automatic flare detection using a dynamic threshold. FLAREGTIx extensions are appended or replace those in the event file.
• flaregti events.fits gtifile=flaregti.fits threshold=30
  Filter periods with a rate greater than 30 cts/s/deg^2, writing the FLAREGTIx extensions to flaregti.fits.