eSASS task: evtool

Scope

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

Description

The task EVTOOL provides three capabilities:

1. Merging several event lists. All canonical extensions are merged. Note that each input event list must cover a different range of telescope modules (TMs) — it is not permitted to merge 2 or more event lists that deal with the same TM(s).
2. Filtering the events on a subset of the columns. Filter modes available are:
   • FLAG column (via bit mask, either exclusive or inclusive).
   • PAT_TYP column (effectively via bit mask).
   • TM_NR column (via a list of desired numbers).
   • PI column (via a list of energy bounds).
   • TIME column (via a GTI specification).
   • RA, DEC columns (via a region specification).
3. Creation of FITS images. The pixel sizes on the sky, the image dimensions in pixels, and the image centre location, are all specifiable. Some auto-sizing options are also available. Most of the extensions in the input event list(s) are optionally discardable for image output.

The input eROSITA Event FITS file is expected to include the following extension types: EVENTS, GTI, BADPIX, CORRATT, and DEADCOR. In addition EVTOOL can handle the following extension types in the file as well: QUALGTI, FLAREGTI, HK, and OFFSET. NOTE: in merging the individual files, columns which were not produced/specified in the eROSITA manual will be ignored.

Input Parameters

• eventfiles (string array) REQUIRED [e.g. 'file1.fits file2.fits' alternatively '@filelist.txt']
  • Input file name or list of input file names. Alternatively provide the name of a separate list of files, which is indicated by an '@'.
• outfile (string) REQUIRED [e.g. 'outfile.fits']
  • Name of the output file.
• clobber (boolean) OPTIONAL [default: yes]
  • If the output file already exists, then setting clobber = 'yes' will cause the file to be overwritten.
• events (boolean) OPTIONAL [default: yes]
  • If 'yes', all the mergeable extensions in the input file(s) are copied to the output. If 'no' (typically, you would set this if you just want an image), all of the extensions except those needed to interpret the filtering (e.g. GTIn, REGION) are omitted from the output.
• image (boolean) OPTIONAL [default: no]
  • Converting the input eventlist into an IMAGE extension can be turned on / off ('yes' or 'no'). size, rebin, and center_position are optional parameters used to define the image.
• size (string_array) OPTIONAL [e.g. '1024 2048' or '1024']
  • This parameter is only active if the image parameter was set to 'yes'.
  • Image creation involves two types of pixels: the pixels in the final image array and the virtual pixels whose size is defined by the WCS keywords associated with the X and Y columns of the event list. The size parameter specifies the numbers in the X and Y directions of the first kind of pixel. (These are the numbers that appear in the 'Image' row of the DS9 display.)
  • If only one numerical value is provided, the other coordinate will be set to the same value.
  • If size is given as 'auto', the task will attempt to choose a value that includes all of the valid events (plus a 1% boundary). There is currently a hard-wired upper limit to size of 18000 (= 20 degrees at the standard pixel size of 80 X/Y units or 4 arcsec).
• rebin (string_array) OPTIONAL [e.g. '4 12' or '80']
  • This parameter is only active if the image parameter was set to 'yes'.
  • See the remarks about pixels in the comment on the size parameter. The rebin parameter specifies the integer number of virtual X/Y pixels to fit into a single image pixel. The default size of 80 corresponds to 4 arcsec.
  • If only one value is provided, the other coordinate will be set to the same value.
• center_position (string_array) OPTIONAL [e.g. '100 201' or '100']
  • This parameter is only active if the image parameter was set to 'yes'.
  • See the remarks about pixels in the comment on the size parameter. The center_position parameter specifies the respective values of the X and Y columns about which the image will be centred.
  • NOTE: The actual center position of the image can differ slightly from the position entered, since it is set to the closest X/Y pixel center position, to avoid aliasing differences from image to image.
  • If only one numerical value is provided, the other coordinate will be set to the same value.
  • If center_position is given as 'auto', the task will centre the image on the means of the event X and Y values.
• region (string) OPTIONAL [e.g. 'region.reg' or 'fk5;circle(90.1,23.2,1.2)']
  • Name of a region file, name of a FITS file or the expression of a single region. If a file is found the input event list will be filtered according to the region file. Valid region files can be produced e.g., with DS9.
  • Supported coordinate systems: fk5,j2000, fk4, b1950, galactic, ecliptic
  • Supported region shapes: circle, rectangle, ellipse, box
  • The arguments to region shapes can be floats or integers describing positions and sizes. They can be specified as pure numbers or using explicit formatting directives:
  • Positional arguments:
    • [num]
    • [num]d # degrees
    • [num]r # radians
    • [num]:[num]:[num] # hms for 'odd' position arguments
    • [num]:[num]:[num] # dms for 'even' position arguments
    • [num]h[num]m[num]s # explicit hms
    • [num]d[num]m[num]s # explicit dms
  • Size arguments:
    • [num]
    • [num]" # arc sec
    • [num]' # arc min
    • [num]d # degrees
    • [num]r # radians
  • NOTE that characters such as " or ' can confuse the shell if you supply a region expression directly. You should be able to use the arcsec sign " so long as you enclose the entire region string in single quotes; however I have not yet worked out a safe way to supply arcmin ' in an expression. If in doubt, create a ds9 region file instead. You can save a template file via ds9, which it is fairly straightforward to edit to your preference.
• gti (string_array) OPTIONAL [e.g. 'GTI' or '12312.2 313873.5']
  • Performs GTI filtering of the event list. Choices are:
    • The name of an external file containing the GTIs, which must be in an extension named 'STDGTI'.
    • Direct provision of a single GTI via a list with a start and stop time. [e.g. '12312.2 313873.5']
    • 'GTI', 'QUALGTI', 'FLAREGTI'. Each of these three filters the events with GTIs that are already stored in the event list in extensions of the given name pattern. E.g. if you select 'FLAREGTI', events of TM1 will be filtered by GTIs in extension FLAREGTI1, and so forth. Note that not only events are filtered, but all other extensions containing time columns.

      Filtering with a GTI extension of one type can also act upon another. The types have a hierarchy, in the order just given. A command to filter on any of the three types will (as well as filtering events and other extensions) apply those GTIs via a logical AND to all the GTI types that come before it in the list. E.g. setting gti to 'QUALGTI' will AND QUALGTIn with GTIn for all TM numbers n, but will not AND any FLAREGTI extensions.

• flag (string) OPTIONAL [e.g. '0x00000001']
  • This filters events based on their value of FLAG. For the bit masks used to indicate various event conditions, see

    EventFiles_doc

    The provided flag string must be in hexadecimal. Note that the default sense of the selection is exclusionary: an event with a FLAG value which has any bit set which is also set in the supplied flag mask, will be rejected. This action is reversed if parameter flag_invert is set to 'yes'.

• flag_invert (boolean) OPTIONAL [e.g. 'yes']
  • If left at default of 'no', events are discarded which have any FLAG bit set corresponding to the bits given in the user-supplied mask flag. If 'yes', events which have none of these bits set are discarded.
• pattern (integer) OPTIONAL [e.g. 1]
  • This filters events based on their value of PAT_TYP.

    The pattern parameter of EVTOOL accepts an integer in the range 1 to 15 inclusive. This is interpreted as a 4-bit mask: 1 bit for each pattern desired. It is an inclusive selection, thus e.g. pattern=5 will choose singles (bit 0) and triples (bit 2) but not doubles (bit 1) and quads (bit 3) - since 5_decimal = 0101_binary.

    If left at default, all PAT_TYP values are passed (representing good as well as bad patterns).

• telid (string_array) OPTIONAL [e.g. '1 3 7']
  • TELID filter (numbers correspond to the selected telescope ids). If left at default, all tel IDs are passed to the output.
• emin (string_array) OPTIONAL [e.g. emin='0 2.4']
  • Lower values (in keV) of energy band event filters (filters the PI column). Note that there must be a corresponding number of emax values. The maximum number of energy intervals is 9. If these two parameters are left at default, all energies are passed to the output.
• emax (string_array) OPTIONAL [e.g. emax='2.0 5.0']
  • Upper values (in keV) of energy band event filters (filters the PI column). Note that there must be a corresponding number of emin values. The maximum number of energy intervals is 9. If these two parameters are left at default, all energies are passed to the output.
• rawxy (string) OPTIONAL [e.g. 'my_mask_file.fits' or '1 384 40 65']
  • This parameter now accepts either of two style of argument: the name of a mask file, or a list of 4 values of the form 'xlo xhi ylo yhi'. If this is set, events are filtered depending on the relation of their RAWX/Y value to the provided selection. The selection is recorded in a new (or amended) bitmap filter mask in an extension 'RAWXY_SEL' of the output file. Parameters rawxy_telid and rawxy_invert modify the behaviour.

    If the name of a mask file is supplied, the file is expected to be FITS with a CCD-sized image in its primary HDU. The image should define a mask to select pixels of the CCD to pass to the output. The data type of the mask may be any FITS-standard numerical value except 8-byte integer. Non-zero values are interpreted as true, zero values as false. With parameter rawxy_invert left at its default value of 'no', true pixels are interpreted as CCD pixels to retain; vice-versa if rawxy_invert is set to 'yes'.

    If instead a list of rectangle limits is supplied, the given bounds are taken to be event-inclusive for rawxy_invert='no' and event-exclusive for rawxy_invert='yes'. Thus for example filtering with rawxy='1 384 40 65' and rawxy_invert='no' will exclude any event with RAWY<40 or RAWY>65, whereas simply flipping the value of rawxy_invert to 'yes' will exclude any event with 40≤RAWY≤65.

    If the parameter is left unset, no RAWX/Y filtering is performed.

• rawxy_telid (integer) OPTIONAL [e.g. 1]
  • The telescope ID number to which to apply the rawxy filter. Should be in the range [1-7] inclusive. If this is not explicitly set, the filter is applied to all tel IDs present in the input event lists.
• rawxy_invert (boolean) OPTIONAL [e.g. 'yes']
  • If left at default of 'no', events outside the rectangle defined by rawxy (but not those lying exactly on the rectangle boundary) are discarded. If 'yes', events inside (including those on the boundary) it are discarded.
• memset (integer) OPTIONAL [e.g. 0]
  • Memory setting to read in all files at once, or only subsets at the expense of multiple open/read/close calls, which is the default setting.
• overlap (real) OPTIONAL [e.g. 2.0]
  • Additional time, which remains after GTI filters in the auxilliary extensions, DEADCOR*, CORRAT*, HK*, OFFSET*, for each time interval. This is done in order to interpolate certain values.
• skyfield (string) OPTIONAL
  • If this is supplied, it overwrites the SKYFIELD header keyword.

Known Issues:

• TSTART and TSTOP keywords may not be written for all GTI-type extensions.
• There are bugs in the recently-added auto-scaling code which prevent it working correctly.
• Several calls to fitsio routines are not setting ierr to zero beforehand.
• The task will crash if you supply a region file that does not exist.
• The task will crash if an image is requested but the event list is empty.
• If the user calls evtool to filter an input event list for a single telid, the output list will correctly contain just the extensions for that telid, but the names of the extensions will contain '1' rather than the telid. This will e.g. lead expmap to obtain cal files for TM1 rather than for the correct TM.