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, but images in the inputs are not merged.

   In general, any set of eSASS event lists can be merged, but the output will be inconsistent (and the task will issue a warning) if the input lists have inconsistent filter settings from previous applications of EVTOOL parameters emin, emax, gti, flag, pattern, rawxy. A variety of header keywords are also tested for consistency.

   Note that image extensions are not merged - an image of the combined output event list must be remade from scratch, via the appropriate parameters.

   If the input lists have been projected to different sine planes (as determined from the WCS keywords corresponding the projected-coordinate columns X and Y), all events of the merged list will be reprojected to the plane of the first input list.

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).
   • RAWX, RAWY columns (via range specifications).
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. To save space, most of the extensions in the input event list(s) are optionally discardable when image output is selected.

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: FLAREGTI and HK. 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]
  • If 'yes', create a sky image from the filtered events, to be stored in the primary header-data unit of the output file. Note that the events should already have been projected to a defined sky plane via the task RADEC2XY; all that EVTOOL does is assign their precalculated X and Y values to a pixel grid. Parameters size, rebin, and center_position are used to define the size and register of the image grid.
• size (string_array) OPTIONAL [e.g. '1024 2048' or '1024' or 'auto']
  • 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 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.) The 'virtual', X/Y-value pixels have been somewhat arbitrarily given a size of 0.05 arcsec. (X/Y values appear in the 'Physical' row of a DS9 display.)
  • The default value is 3240.
  • If only one numerical value is provided, the other coordinate will be set to the same value, producing a square image.
  • 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' or 'auto']
  • 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.
  • The default value is zero.
  • 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.
• 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, events of 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, events of all energies are passed to the output.
• telid (string_array) OPTIONAL [e.g. '1 3 7']
  • Filters the TM_NR column (numbers correspond to the selected telescope ids). If left at default, all tel IDs are passed to the output.
• region (string) OPTIONAL [e.g. 'region.reg' or 'fk5;circle(90.1,23.2,1.2)']

  *** NOTE from the developer: *** the region code of evtool alas needs a lot of work. I'm hoping to get it in order before the next release, but for the moment the only region syntax I am certain does work is 'fk5;circle(<centre RA in deg>,<centre dec in deg>,<radius in deg>)'.

  Filtering with a region creates a REGION extension in the file, to record the region specification. ***NOTE*** that these extensions are NOT merged.

• 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' or 'FLAREGTI'. Each of these alternatives 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 'FLAREGTI' will AND FLAREGTIn 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

    List of flag bits

    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' - i.e., in this case such events will be included. The event lists resulting from filtering with the same flag mask but opposite values of flag_invert will be complementary - no event can be a member of both.
• 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. ***NOTE*** that use of this parameter will muck up the flag filtering record stored in the FLAGSEL keyword of the event list header, which can only accumulate non-inverted flag filter masks.
• 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).

• 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 (boolean) OPTIONAL [default: no]
  • Memory setting to read in all files at once (when true), or only subsets at the expense of multiple open/read/close calls (false), 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*, 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.
• repair_gtis (boolean) OPTIONAL [default: no]
  • Tells EVTOOL to attempt to repair any disordered GTIs it finds.

Known Issues:

• Successive filtering with different values of flag_invert will muck up the record of flag filtering stored in the FLAGSEL keyword.
• 001 and earlier data is known to contains instances of successive GTIs which overlap (defined as the stop time of GTI i being ≥ the start time of GTI i+1). Task EVTOOL will not process such files with default settings: an error message such as

  
   evtool/ranges_are_legal: **WARNING1** High bound  <blah> of range <blah> overlaps low bound  <blah> of the following.
   evtool/sanityCheck_tGTI_tab: **STOP** <name of file + GTI extension>:GTIs are not legal.
   evtool: FAILED
  

  is seen. The work-around is to set the parameter repair_gtis to 'yes'.
• REGION extensions are not merged. If any are present in the input files, they are discarded from the output.
• 8 hexadecimal digits must always be supplied to the flag parameter. If you use fewer, incorrect filtering will result.
• If you choose size='auto' but leave center_position at its default, the resulting image will be sized to contain all the events, but it will be centred on the zero coordinates of the X/Y column values, as recalculated during the event merging process (see Algorithm section below). If this zero location is significantly offset from the geometrical centre of the projected events (as may happen, since it is taken simply from the first event list), you may end up with a lot of empty space in your image. Thus it is better to choose both size and center_position as 'auto' rather than one but not the other.

Algorithm

The task merges the input event lists before applying the filtering criteria. In the merging of EVENTS tables, single examples only are retained of any multiple events having the same TIME, TM_NR, RAWX, RAWY, and PHA. (Note that this in effect is a logical OR.) Input GTI tables are merged via a logical OR. For HK-type tables, rows having the same RecordTime are reduced to a single example. For all other binary-table extensions, all columns are considered when discarding copies.

Warnings are issued if essential keywords (e.g., those that record the filter operations that have been applied to the inputs) vary across the inputs. Keywords for the output are in general taken from the first input file.

Projection of event sky locations is performed during the pipeline by task RADEC2XY. Since different members of the input event lists may have been projected to different tangent directions (defined via the TCRVLn and TCRVLm keywords, where n and m respectively are the column numbers of the X and Y columns), EVTOOL re-projects (i.e., recalculates all the X and Y values) to the direction read from the EVENTS header of the first input file.