Back to eSASS task descriptions

eSASS task: SRCTOOL

eROSITA/srctool-1.61+

Scope

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

Description

SRCTOOL is the software tool used to derive source level products (spectra, light-curves and corresponding instrumental correction vectors/matrices) from calibrated eROSITA event files and their ancillary meta-data. Figure 1 gives a graphical representation of the inputs and outputs of SRCTOOL.
SRCTOOL inputs/outputs

Figure 1. An illustration of the main inputs (left side) and outputs (right side) of SRCTOOL. Inputs include calibrated event list files (including meta-data), source description files (catalogues, regions, extent models) and calibration data files (read from the CALDB). Outputs include source and background spectra, light-curves, response matrices, ancillary response files, and eventlists.

SRCTOOL is used both within the standard eSASS pipeline (operated in an automatic scripted way), and also as a user-facing tool (manually called). Hence there are a number of different modes of operation, and a variety of distinct tasks that are carried out by SRCTOOL. Not all of this functionality is necessarily used in each call of SRCTOOL, and sometimes a subset of the input parameters will have no effect.

Words of advice/caution

Input Parameters

Input files

Output files

When requested in the todo parameter, one of each of the following output file types is produced for each source specified by srccoord, and for each instrument specified in insts. An additional 'total' output, summed or averaged across the (up to) seven eROSITA telescope modules is also produced for each source.
The file naming system follows the standard eROSITA conventions.

Installation and operation

Algorithm(s)

Source extraction

The following procedure is adopted when SRCTOOL is tasked with extracting spectra and/or light-curves.

Extended source handling

eROSITA is expected to detect hundreds of thousands of extended sources (mostly galaxy clusters), therefore correct handling of extent within SRCTOOL is vital. The following procedures are implemented in SRCTOOL to handle the calculation of the effective instrumental response for extended sources.

Compact or very extended sources, which mode to use?

SRCTOOL has two main operational modes when handling extended sources, depending on whether it is instructed to correct for or to ignore PSF losses (input parameter psftype='2D_PSF' or 'NONE' respectively).

When extracting source products for relatively compact and circularly symmetric extended sources, one should turn on PSF modelling, since PSF losses are likely to be important. In this mode, SRCTOOL performs a convolution of the PSF model with the source extent model and uses this when computing the expected fraction of source light falling inside the source extraction region. The vignetting of the instrument is computed at the source centre, and assumed to be constant over the source extent. Note that these assumptions break down for strongly non-circularly symmetric sources.

For very extended, and or asymmetric sources, PSF losses are unimportant and one should turn off PSF modelling. In this mode, the vignetting function is computed across the full source extent.

Both modes depend on the user giving SRCTOOL description of the intrinsic spatial distribution of the source flux.

Handling of very large extended sources (psftype='NONE')

If psftype=NONE, then SRCTOOL does not account for PSF losses, which speeds up the processing of very large sources. If using this option, it is important to define a source model which describes the morphology of the source over the extraction region (see the exttype parameter); the default point model is not a good choice if psftype=NONE. A simple flat model can be given using the TOPHAT model. If using a tophat model, the user may want to set the extent of the tophat to be larger than the extraction region and they should ensure that the source position is correct. For a more sophisticated source model, the extmap parameter allows a user-supplied source model image.

Please note that by default any background region is extracted using the same GTIs as the source. If the source region is large, this means that only a limited part of the background region data will appear in the background region outputs. In addition, an ARF appropriate for the source region is unlikely to be appropriate for the background region if they are large and/or separated. Therefore, the user is advised to extract large background regions separately and do a joint spectral fit on the source and background spectra. When modelling spectra, please note that the BACKSCAL includes effects such as loss due to the field of view, which are also included in the ARF effective area. The appropriate area if modelling using an ARF is likely to be REGAREA (the pure geometric area), whereas if modelling without an ARF (e.g. particle background), BACKSCAL is likely appropriate.

Handling of compact symmetric sources (psftype='2D_PSF')

  1. Interpret description of source spatial profile.
    • The user must supply srctool with a model of each source's spatial extent: ρe(Δαdeg,Δδdeg). The spatial extent model can either be expressed as a parameterised analytic expression (chosen from a short menu of standard models), or as a 3D image of the relative intensity of the source emission as a function of photon energy. In both cases the source geometry must be expressed in physical coordinates relative to the central position of the source, and aligned with the Equatorial (J2000) coordinate grid. The energy dependence of the extent model is included here for completeness, but is not expected to be needed in general.
    • Where necessary, srctool calculates a (finely) pixelized set of 2D maps (one per energy bin, e) of the source extent in equatorial coordinates: ρe(αJ2000,δJ2000)
    • The user must also provide a description of the spatial extraction region from which source photons are selected (see description below for details). srctool interprets the description of the region from the user's description, and distributes a number of evenly spaced sample points within the region. These sample points are the locations where srctool samples the instantaneous PSF.
  2. Convolve source extent model with PSF model.
    • In general, we have a PSF model that is expressed as a set of small 'maps', PSFxi,e, evaluated at discrete energies, e, and where xi describes a discrete location on the focal plane (xi=[xpix,ypix] or xi=[θφ]) where the PSF is evaluated.
    • srctool calculates a (finely) pixelized set of convolved 2D maps (one for each focal plane position xi and energy e) of the source extent in Equatorial coordinates: ρ′xi,e(αJ2000,δJ2000)
    • This is carried out separated for each of the seven eROSITA telescopes, which in general have different PSFs
    • Note that for reasons of computational efficiency, the convolution of source extent and PSF models is carried out in Fourier space, using routines from the popular fast Fourier transform library FFTW.
      Specifically, we exploit the relationship:
      • 𝔸⊗𝔹 = invFFT[FFT(𝔸)×FFT(𝔹)] ,
      where 𝔸 and 𝔹 are real 2D matrices, ⊗ is the convolution operator, FFT(),invFFT() represent the Fast Fourier Transform and its inverse, and × represents element-by-element multiplication of the (complex) matrix elements.
  3. Step through the valid GTIs, carrying out the following for each time step:
    1. Calculate the instantaneous centre and roll angle of the telescope
    2. Calculate the location of the centre of the source, xnow, and locations of sample points on the focal plane.
    3. Measure the detector map/bad pixel map at the sample points.
    4. Interpolate ρ′xnow,e from the ρ′xi,e that are closest to the current source location on the focal plane.
    5. Compute the weighted sum ΣV(xnow,e).ρ′xnow,e over all sample points, after carrying out a rotation and translation of the sample points into the PSF map to model the instantaneous alignment of the PSF on the sky. Where V(xnow,e) is the energy dependent vignetting function.
    6. Add result of e., weighted by the live time interval, to the running total.

Note that the fully correct process to calculate the instantaneous image of the source on the detector (close to the behaviour of photons in eROSITA itself) would be to first multiply the intrinsic source profile by the vignetting function and then to convolve the result by the PSF. However, for the sake of computational efficiency we make the simplifying assumption that the vignetting is uniform across the source extent, and only compute the instantaneous vignetting at the source centre. We also assume that the extent of the source is small relative to the rate at which the PSF model changes as a function of position within the focal plane. This is likely to be a reasonable assumption because very large extended sources which do not meet this criterion are likely to be analysed with the PSF model turned off (because the fraction of the total photons that are lost outside the extraction aperture due to PSF broadening is very small).

At high off-axis angles the PSF of eROSITA is much more elongated in the azimuthal direction than in the radial direction. The PSF shape varies strongly with off-axis angle, but slowly with azimuthal angle within the focal plane. The orientation of the PSF relative to the source profile and extraction region depends on the location within the focal plane. This effect is unimportant in cases where the source and extraction region are rotationally invariant. That is, either point-like sources or source with spatial profiles which have no azimuthal dependence, and extraction regions that are either circles or annuli centred on the source position. The vast majority of extended eROSITA sources will be faint, and so only a simple rotationally symmetric profile will be fitted. We have optimised the extended source handling within srctool to accommodate this case. Hence, for reasons of computational efficiency, we initially convolve the PSF and source profile over a finite grid of locations within the focal plane, and then when necessary rotate our sample points into these ρ′xnow,e using the appropriate instantaneous azimuthal angle.

Automatic generation of extraction regions

When the srcreg and/or backreg parameters are set to "AUTO" and the source description in srccoord is supplied as a CATPREP catalogue, then SRCTOOL will build the source and/or background regions automatically. Source regions are circles and the background regions are annuli, both centred on the best fitting source coordinates (RA,DEC columns). To determine the appropriate sizes of these regions, SRCTOOL takes account of the fitted number of source counts (ML_CTS_0 column), the level of the background map model at the source position (ML_BKG_0 column), the best fitting source extent model radius (from the EXT column), together with a model of the effective eROSITA PSF at the source position (averaged over the integration, and summed over all operating telescope modules). Given these source, background and PSF parameters, the following algorithm is used to determine the most appropriate sizes for the source and background regions: There are a number of hard-coded parameters associated with the AUTO computation algorithm (marked with † symbols), and are given in the table below.

Auto-region parameters

Parameter Value Unit Environment setting
PSF energy 1.0 keV PSF_ENERGY_KEV
Radial step size (source) 1.0 arcsec RADIAL_STEPSIZE_SRC
Radial step size (background) 2.0 arcsec RADIAL_STEPSIZE_BACK
Minimum source inclusion radius 15.0 arcsec MINIMUM_SOURCE_RADIUS
Minimum source exclusion region radius. Must be smaller than the minimum exclusion distance. 5.0 arcsec MINIMUM_EXCLUDE_RADIUS
Minimum core radius of source, used when excluding regions from overlapping sources 5.0 arcsec MINIMUM_SOURCE_CORE
Minimum exclusion distance. No exclusion zones are allowed to be centred within this radius from the source. 10.0 arcsec MINIMUM_EXCLUDE_DIST
Initial source radius to background inner radius ratio 2.0 ratio INITIAL_SRC_R_TO_BACK_R1
Maximum local (surface brightness) contamination of a source's background region by its own PSF wings 5% ratio MAX_SRC_MAP_TO_BG_MAP_RATIO
Initial ratio of the geometric area of the background region to the source extraction region 10 ratio BACK_TO_SRC_AREA_RATIO
Maximum local (surface brightness) contamination of a source extraction region by a confusing source 20% ratio MAX_CONF_MAP_TO_SRC_MAP_RATIO
Maximum local (surface brightness) contamination of a background extraction region by a confusing source 10% ratio MAX_CONF_MAP_TO_BACK_MAP_RATIO
Maximum inner radius of background annulus as a multiple of the local effective PSF 99% containment radius 3 ratio MAX_RATIO_BACK_R1_TO_RADIUS_99PC
Maximum difference between inner and outer radii of background annuli 120 arcsec MAX_BACK_ANNULUS_WIDTH

Although it is not recommended except in the case of optimising this tool, these parameters values can be overridden in environment variables with names given in the table above prefixed by SRCTOOL_AUTOREG_. For example, setting SRCTOOL_AUTOREG_PSF_ENERGY_KEV with the value 2.0 will change the PSF energy to 2 keV.

Compute size of source extraction circle

Compute size of background extraction annulus

Compute regions to exclude around potentially confusing neighbouring sources

Nearby X-ray sources could potentially contaminate both the source and background spectra. To minimise the effects of such "confusing" sources, we exclude regions around each potentially contaminating source from the target source and background extraction regions.

Examples of usage

Note that the data files mentioned in the examples below are distributed with the eSASS software, and can be found in the $SASS_TESTDATA directory.

Example 1

Extract the spectrum and 20s binned light-curves (0.5-2 and 2.0-10 keV bands), and calculate the RMF, ARF and light-curve corrections for a point source located at 01:23:45.67,+01:23:45.67 (J2000), using a setup that is appropriate for data collected in the all-sky survey. Extract data from all eROSITA telescope modules (TM1..7). Extract source counts from a 60" radius circle and background from an annular region centred on the source position. Calculate ARF corrections for photons lost outside the source aperture using the standard 2D PSF model. Do not reject any flagged events. Any existing output files are not overwritten. 
   srctool eventfiles="test_SURVEY_COMPACT_POINTSRC_eventfile.fits.gz" \
           srccoord="icrs;01:23:45.67,+01:23:45.67" \
           prefix="srctool_example1/example1_" \
           suffix="_v2" \
           todo="SPEC ARF RMF LC LCCORR" \
           insts="1 2 3 4 5 6 7" \
           srcreg='icrs;circle(*,*,60.0")' \
           backreg='icrs;annulus(*,*,90.0",120.0")' \
           exttype="POINT" \
           lctype="REGULAR" \
           lcpars="20.0" \
           lcemin="0.5 2.0" \
           lcemax="2.0 10.0" \
           lcgamma="1.7" \
           tstep=0.05 \
           xgrid="0.5 1.0" \
           gtitype="GTI" \
           psftype="2D_PSF" \
           flagsel=0 \
           clobber="no"

Example 2

Extract the spectrum and calculate the RMF and ARF for a relatively compact symmetric extended source located at 01:23:45.67,+01:23:45.67 (J2000), using a setup that is appropriate for data collected in a pointed-mode observation (i.e. attitude changes slowly w.r.t. the tstep param). Do not calculate new source GTIs (assume that the input GTIs are valid). Extract data from just the TM1 and TM2 eROSITA telescope modules. Extract source counts from a 200" radius circle and background from a circular region offset from the source position. Model the source extent with a tophat profile, with radius 180". Reject any flagged events. Any existing output files are overwritten. 
   srctool eventfiles="test_POINTING_COMPACT_TOPHAT_eventfile.fits.gz" \
           srccoord="icrs;01h23m45.67s,+01d23m45.67s" \
           prefix="srctool_example2/example2_" \
           suffix="_v7" \
           todo="SPEC ARF RMF NOSRCGTI" \
           insts="1 2" \
           srcreg='icrs;circle * * 200.0"' \
           backreg='icrs;circle 01:23:45.67,+01:40:00.0,200.0"'\
           exttype="TOPHAT" \
           extpars="180.0" \
           tstep=0.05 \
           xgrid="0.5 1.0" \
           gtitype="GTI"  \
           psftype="2D_PSF" \
           flagsel=255 \
           clobber="yes"

Example 3

Extract source products for objects in a CATPREP catalogue, allowing SRCTOOL to compute the extraction regions automatically. Compute light-curves for four broad energy bins. 
   srctool eventfiles="test_SURVEY_CATALOGUE_BETA_eventfile.fits.gz" \
           srccoord="test_SURVEY_CATALOGUE_BETA_catprep.fits.gz" \
           prefix="srctool_example3/example3_" \
           suffix="_autoreg" \
           todo="SPEC ARF RMF LC LCCORR" \
           insts="1 2 3 4 5 6 7" \
           srcreg='AUTO' \
           backreg='AUTO'\
           lctype="SRCGTI-" \
           lcemin="0.5 1.0 2.0 5.0" \
           lcemax="1.0 2.0 5.0 10.0" \
           lcgamma="1.9" \
           tstep=0.05 \
           xgrid="1.0 2.0" \
           clobber="yes"

Example 4

Extract the spectrum and calculate the RMF and ARF for a large extended source located at 01:23:45.67,+01:23:45.67 (J2000), using a setup that is appropriate for data collected in a pointed-mode observation (i.e. attitude changes slowly w.r.t. the tstep param). Weight the computed response using the supplied source map. Do not calculate new source GTIs (assume that the input GTIs are valid). Extract data from just the TM2 and TM5 eROSITA telescope modules. Extract source counts from a 300" radius circle and background from a circular region offset from the source position. Do not apply corrections for PSF losses. Any existing output files are overwritten. 
   srctool eventfiles="test_POINTING_VEXTENDED_MAP_eventfile.fits.gz" \
           srccoord="icrs;01 23 45.67,+01 23 45.67" \
           prefix="srctool_example4/example4_" \
           suffix="_v4" \
           todo="SPEC ARF RMF NOSRCGTI" \
           insts="2 5" \
           srcreg='icrs;circle * * 0.25d' \
           backreg='icrs;circle 01:23:45.67,+01:46:00.0,300.0"'\
           exttype="MAP" \
           extmap="test_VEXTENDED_MAP_extentmap.fits.gz" \
           tstep=5.0 \
           xgrid="2.0 2.0" \
           gtitype="GTI"  \
           psftype="NONE" \
           clobber="yes"

Notes

Useful eROSITA parameters (all numbers approximate)

FOV diameter 1.03 deg
Focal length 1.60 m
Number of telescope modules 7
Detector format 384•384 pixels
Pixel size 75•75μm2
Pixel scale 9.6 arcsec pix-1
Plate scale 7.8 μm arcsec-1
Sub-pixel coordinate grid ~0.064 arcsec
Photon location accuracy ~2 arcsec
Valid event patterns singles, doubles, triples, quadruples
Full energy range 0.1-15.0 keV
Useful energy range 0.3-10.0 keV
Energy resolution 65eV@1keV, 135eV@6keV (E/ΔE~15-50)
Typical observing pattern (Ecl. equator) 6 scans source-1 season-1
Total number of 6-month seasons 8
Time for one scan around a great circle 4 hours
Nominal scan speed 90 deg hour-1
1.5 deg min-1
1.5 arcmin s-1
90 arcsec s-1
Time for scan to cross full FOV 41.2 s
CCD Frame time 50 ms
CCD Frame transfer time 130 μs
Distance scanned in one CCD frame-time 4.5 arcsec
0.5 detector pixel
Cross-scan precession rate
at Ecliptic equator 		360 deg/(365 days•24 hrs/4 hrs)
0.167 deg scan-1
10 arcmin scan-1
600 arcsec scan-1
multiply the above by cos(β) at other Ecliptic latitudes

Known issues