eSASS task: evtool

erosita/evtool-1.55

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:

Input (calibrated) eROSITA Event FITS files will be merged into a single file. Optional: image createn and/or the usage of selection criterias. 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.

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 a 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:
- size arguments:
gti (string_array) OPTIONAL [e.g. "GTI" or "12312.2 313873.5"]
- Flag to set GTI filter of the input event list to active. The provided string must either specify the GTI extension (without the telescope id), refer to an external gti file (with STDGTI extension) or provide a TSTART and TSTOP date.
flag (string) OPTIONAL [e.g. "0x00000001"]
- This allows the user to select 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 a hexcode. 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 allows the user to select 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=6 will choose doubles (bit 1) and triples (bit 2) but not singles (bit 0) and quads (bit 3) - since 6_decimal = 0110_binary.

telid (string_array) OPTIONAL [e.g. "1 3 7"]

Flag to set the TELID filter of the input event list to active. The provided numbers correspond to the selected telescope ids.

emin, emax (string_array) OPTIONAL [e.g. emin="0 2.4", emax="2.0 5.0"]

Flag to the ENERGY filter of the input event list. Both parameters have to be set in order to perform an energy selection. The provided numbers correspond to the minimum and maximum of the energy band being selected (in units of keV). The maximum number of input energy interval is 9.

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.