eSASS task: APETOOL

Scope:

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

Description:

The APETOOL has three main functionalities:

• produce maps of the size (radius in pixels) of the Point Spread Function (PSF) across the eROSITA field-of-view (PSF maps),
• perform aperture photometry, i.e. extract source and background counts at either arbitrary user defined positions or at the positions of sources taken from a source catalogue generated by the ERMLDET task. In both cases the extraction apertures are defined in units of Encricled Energy Fraction (EEF), i.e. they have radii that include a certain fraction of the total source photons.
• generate sensitivity maps for a user-defined Poisson false-detection probability threshold (PTHRESH parameter below). These sensitivity maps describe at any given position on the eROSITA field-of-view the minimum number of counts within an aperture so that the Poisson probability of them a being bakcground fluctuation is less than the user-defined Poisson false-detection threshold. This minimum number of counts is defined for circular apertures of fixed raidus in units of EEF (user defined). The sensitivity maps can be used to estimate the probability of detecting a source with a given count-rate within the field-of-view of a given eROSITA observation.

PSF maps:

The PSF of the eROSITA is modelled using shapelet functions and their corresponding coefficients. The shapelet model, stored in an appropriate calibration file, describes how the shape of the PSF changes as function of energy and position on the eROSITA field of view. The APETOOL combines this information with the attitude file of a given observation (event file) to generate a model of the exposure-time average PSF shape. This is then used to measure the size of the PSF in pixels at different encircled energy fractions (EEF). The EEFs at which the PSF size is measured correspond to the following EEF values:

EEF = (/0.4,0.45,0.5,0.55,0.6,0.65,0.7,0.75,0.8,0.85,0.9,0.95/)

The APETOOL estimates the PSF size in a regular grid of positions on the eROSITA field-of-view. The density of the grid is a tradeoff between speed, size of the final PSFMap and an adequate description of the variations of the PSF size across the field of view. The parameter that controls the density of the grid is PSFMAPSAMPLING, however in the current version of APETOOL this is not a user-defined parameter. Instead the PSF is estimated in a regular grid of 21x21 positions along the X and Y direction. This will be changed in future version of this task.

Aperture Photometry:

In the case of aperture photometry there are two options, either extract counts at source positions defined by an ERMLDET source catalogue or at arbitrary user-defined positions. The difference between the two options is the format of the input source list. In the first case, the ERMLDET source catalogue is supplemented with aperture photometry products (see below). The resulting source catalogue can then be combined with the APETOOL sensitivity maps. The case of aperture photometry at user-defined arbitrary source positions corresponds to science applications related to e.g. X-ray stacking analysis or searches for faint X-ray emission (i.e. below the formal X-ray detection threshold) associated with counterparts selected at other wavelengths or external (non-eROSITA) X-ray catalogues. The radii of the apertures, within which counts are extracted, are expessed in EEF units, i.e. the radius that corresponds to a user-defined encircled energy fraction (for example 0.7). For arbitrary source positions it is also possible to provide extraction radii in units of arcseconds. The logical flag APEXFLAG is set to True for aperture photometry at ERMLDET source catalogue positions. The flag STACKFLAG is set to True for aperture photometry at arbitrary user-define postions.

The aperture photometry requires the estimation of the expected background level within the extraction region. The background estimation should account for the extended PSF wings of nearby sources, i.e. confusion. The approach adopted by APETOOL to address this issue is to use the SourceMap products generated by ERMLDET. These are images of the model background plus a model of the detected sources, i.e. a model of the real observations. If the user-defined aperture lies close to a bright source then the SourceMap describes (at least to the first approximiation) the elevated local background because of the presence of the bright source. There are situations in which the input position of interest lies on an ERMLDET detected source. This is the case for example of ERMLDET source positions, when one is insterested in the sources' aperture photometry. In this case using the SourceMap to measure the local background is problematic because it contains the source of interest as "background". For that reason APETOOL has the functionality to remove model sources from the SourceMap. If an input position is closer than a user-defined radius (RR) to an ERMLDET source, then APETOOL generates a model of the ERMLDET source profile and subtracts it from the SourceMap leaving behind the "background" level only. Other ERMLDET sources with angular distance from the input position larger than the user-define radius RR are left intact on the SourceMap. Both the count extraction radius and the size of the region within which sources are subtracted from the SourceMap are defined in units of the Encircled Energy Fraction of the local PSF. Defining apertures in this way has the advantage that the extracted counts will correspond to a known EEF and therefore they can be corrected to the "total" source counts, i.e. those outside the aperture. The EEF accross the eROSITA field-of-vew is stoted into the PSFMap product of APETOOL.

If STACKFLAG is True then the file containing the input source positions is provided by the parameter APELIST. This should be a fits binary table with columns "RA" (degrees, Double Precision Real Number), "DEC" (degrees, Double), "RE" (Double) and "RR" (Double). The RA, DEC columns are the J2000 sky positions of the input sources in degree units. The RE column is the radius within which counts will be extracted from the input images and SourceMaps. The RR column corresponds to the radius within which sources in the input ERMLDET sourcelist (parameter MLLIST) near the input position are removed from the corresponding SourceMap before extracting background counts. Setting RR to zero means that no ERMLDET sources will be removed from the SourceMap prior to the background extraction. Both the RE and RR can be expressed in PSF Encircled Energy Fraction, i.e. they are less than unity (i.e. fraction). Alternatively if RE, RR are larger than unity they are interpreted as radii in units of arcseconds. The binary table of input positions should be stored into the second extension of the APELIST fits file. If STACKFLAG is true the aperture photometry results are stored in a fits file with filename controlled by the parameter APELISTOUT.

If the logical flag APEXFLAG is set to True then APETOOL updates the relevant columns (see below) of the input ERMLDET source list (given by parameter MLLIST). In this case the RE and RR have the same value controled by the parameter EEFEXTRACT (see parameter list below).

For both APEXFLAG=True and STACKFLAG=True, APETOOL updates/generates the following columns of the MLLIST/APELISTOUT file:

• APE_CTS: counts at a given position (source and background) extracted from the input images within certain energy bands
• APE_BKG: background counts extracted from the ERMLDET source maps within certain energy bands.
• APE_EXP: aperture-averaged exposure map at the used-defined input positions
• APE_EEF: Encircled Energy Fraction used to define the extraction radius
• APE_RADIUS: Extraction radius in PIXELS
• APE_POIS: Poisson probability that the extracted counts (source + background) are a fluctuation of the background.

Sensitivity maps:

The sensitivity map provides an estimate of the minimum (integer) number of counts (source and background) within the extraction radius (expressed in Encircled Energy Fraction units) at a given position on the detector, so that the Poisson false detection probability is lower than a user-defined value defined by the parameter PTHRESH. The Poisson false detection probability is defined as the probability of the background fluctuating in a random fahsion to produce counts within an aperture above a given value. This probability is given by the survival function of the Poisson probability disribution and is described by the gamma funtions. The resulting sensitivity maps are consistent with the aperture photometry of ERMLDET sources. The extraction radius (in EEF units) can be viewed as a detection cell, within which sources are detected above a fixed Poisson false detection probability. A detailed description can be found in Georgakakis et al. 2008. The sensitivity map fits file includes three image extensions, (i) the sensitivity map itself, i.e. the minimum number of counts as described above at different detector positions, (ii) the expected background within the extraction radius, i.e. the integral of the ERMLDETECT SourceMap within the extraction aperture and (iii) the corresponding average exposure time (mean of the exposure map) within the extraction radius. With these three components it is possible to estimate the detection probability of a source with a given count-rate or flux. For full details see Georgakakis et al. 2008 and Ruiz et al. 2022. The resulting area or sensitivity curve is stored in the fourth (table) extension of the sensitivity map fits files. It inlcudes count rate and the corresponding area in deg2 within which a source of this count-rate can be detected. This calculation makes no assumptions about the X-ray spectral shape of the source.

Input Parameters:

• MLLIST (string) OPTIONAL/REQUIRED IF APEXFLAG=True
  • Input ERMLDET source list. If APEXFLAG=True, aperture photometry is performed at the positions listed in that catalogue. For the background estimation the SourceMap product of the ERMLDET task is used. The shapelet eROSITA PSF model is used to remove ERMLDET sources from the SourceMap that lie within distance RR (set by the parameter EEFEXTRACT) of an input position. This approach accounts for the possible contribution of nearby sources to the observed counts of the source in question. If STACKFLAG=True then the MLLIST sources are used only to remove detections from the SourceMap that lie within a distance RR of an input position.
• APELIST (string) OPTIONAL/REQUIRED IF STACKFLAG=True
  • Input source list with sky coordinates (Right Ascension and Declication) at which counts will be extracted. The task expects to read a binary fits table at the second fits file extension. The table should inlcude columns "RA" (degrees, Double Precision Real Number), "DEC" (degrees, Double), "RE" (Double) and "RR" (Double). The RA, DEC columns are the J2000 sky positions of the input sources in degree units. The RE column corresponds to the radius within which counts will be extracted from the input images and SourceMaps. The RR column corresponds to the radius within which ERMLDET sources (parameter MLLIST) near the input position are removed from the corresponding SourceMap before extracting background counts. The radii RE and RR are either (i) less than unity, in which case they are assumed to represent EEFs (for example 0.7) or (ii) greater than unity in which case they are interpreted as arcseconds.
• APELISTOUT (string) OPTIONAL/REQUIRED IF STACKFLAG=True or APEXFLAG=True
  • This is the fits-format filename that stores the apetool-derived quantities (extracted counts, background etc) either (i) at abritray input positions, i.e. not associated with an ERMLDET source list or (ii) at ERMLDET source positions. In the latter case the output file will be copy of the input ERMLDET source list (parmeter MLLIST) with values added in the corresponding apetool columns .
• IMAGES (string array) REQUIRED
  • Name(s) of input science image(s). All input images must have equal size and WCS headers. The files must also contain an events extension
• PSFMAPS (string array) REQUIRED
  • Names of the output PSF maps (one per input IMAGESETS)
• EXPIMAGES (string array) REQUIRED
  • Exposure maps corresponding to input images. Sizes and WCS headers must match the science images.
• DETMASKS (string array) REQUIRED
  • detection masks as created by task ermask . Sizes and WCS headers must match science images.
• BKGIMAGES (string array) OPTIONAL/REQUIRED IF APEXFLAG=True or APESENSEFLAG=True
  • Background maps as created by task erbackmap . Sizes and WCS headers must match science images
• SRCIMAGES (string array) OPTIONAL/REQUIRED IF APEXFLAG=True or APESENSEFLAG=True
  • Source model maps produced by ermldet
• APESENSEIMAGES= (string array) OPTIONAL/REQUIRED IF APESENSEFLAG=True
  • Output sensivity maps. These files have 4 extensions (i) the sensitivity map itself, i.e. the minimum number of counts as described above as a function of detector position , (ii) the expected background within the extraction radius, i.e. the integral of the ERMLDETECT source map within the extraction aperture, (iii) the average exposure time (mean of the exposure map) within the extraction radius and (iv) sensitivity curve. The latter extension is a binary table extenction that lists count rate and the corresponding area in deg2 within which a source of this count-rate can be detected. This calculation makes no assumptions on the X-ray spectral shape of the source.
• EMIN (real array) REQUIRED
  • Minimum photon energy in the input images (PI channels). The parameter is used to select energy dependent calibration data.
• EMAX (real array) REQUIRED
  • Maximum photon energy in the input images (PI channels). The parameter is used to select energy dependent calibration data.
• EINDEX (real array) REQUIRED
  • The user may wish to perform aperture photometry in a subset of the energy bands used to generate the input ermldet source list. In this case this parameter gives the correspondence between the energy band listed in ermldet and the energy bands of the the input image products provided to apetool. If for example the ermldet list has been run on four energy bands that appear in the ermldet source list in the order [0.2-0.5, 0.5-1.0, 1.0-2.0, 2.0-5.0] in keV units and aperture photometry is required only for the band [0.5-1.0, 2.0-5.0] in keV units, then one can provide as input to the apetool the image data products in the latter two energy intervals (in the order they appear above) and then let the apetool know that the input bands correspond to the 2nd and 4th energies in the ermldet source list by setting EINDEX="2 4". If EINDEX is not set it is assumed that the input energy bands appear in the same order as in the ermldet run that produced the source list.
• EEFEXTRACT (real) OPTIONAL[default value: 0.7]
  • Encircled Energy Fraction. If APEXFLAG=True, it defines the size of the radius for the extraction of counts.
• PTHRESH, (real) OPTIONAL[default value: 4e-6]
  • The Poisson false detection probability threshold. This is used for the sensitivity map calculation.
• CUTRAD (real) OPTIONAL[default value: 15]
  • Cut radius for source fitting. This parameter is used to determine the model profile of the sources on the Source Map. It should have the same value as that used in the ermldet run that produced the source map. Differences in the CUTRAD parameter between ermldet and apetool will result in erroneous backgound estimation
• PSFMAPSAMPLING (real) OPTIONAL[default value: 11]
  • The size of the PSF changes reasonably slow across the field of view. For the shake of speed it is therefore possible/advised to sample the PSF at regular intervals in X and Y direction on the image of the field of view. This parameter controls the spatial sampling of the image in pixels.
• APEXFLAG (boolean) REQUIRED[default value: NO]
  • Flag to control whether aperture photometry on an input ERMLDET sourcelist should be performed or not.
• STACKFLAG (boolean) REQUIRED[default value: NO]
  • Flag to control whether aperture photometry should be performed on a user-defined input source list. If True, the parameters APELIST, APELISTOUT should also be set.
• PSFMAPFLAG (boolean) REQUIRED[default value: NO]
  • Flag that controls whether a PSF map should be produced.
• SHAPEPSF (boolean) REQUIRED[default value: NO]
  • Flag that controls whether the shapelet model for the eROSITA PSF is used. This paramater should always be set to True
• APESENSEFLAG (boolean) REQUIRED[default value: NO]
  • Flag that controls whether sensitiviry maps should be produced.

Input files:

SEE ABOVE

Output files:

• PSF Maps: The is a fits 3-dimensional image (cube) that contains the PSF sizes in a grid of positions for the EEF values 0.4,0.45,0.5,0.55,0.6,0.65,0.7,0.75,0.8,0.85,0.9,0.95.
• Sensitity Maps: The sensitivity map fits file includes three image extensions, (i) the sensitivity map itself, i.e. the minimum number of counts as described above as a function of detector position , (ii) the expected background within the extraction radius, i.e. the integral of the ERMLDETECT source map with the extraction aperture and (iii) the corresponding average exposure time (mean of the exposure map) within the extraction radius. With these three components it is possible to estimate the detection probability of a source with a given count-rate or flux. For full details see Georgakakis et al. 2008. The resulting area or sensitivity curve is stored in the fourth (table) extension of the sensitivity map fits files. It inlcudes count rate and the corresponding area in deg2 within which a source of this count-rate can be detected. This calculation makes no assumptions on the X-ray spectral shape of the source.
• Aperture Photometry Catalogue: The aperture photometry results either update the relevant columns (APE_CTS, APE_BKG, APE_EXP, APE_EEF, APE_RADIUS, APE_POIS) of the input ERMLDET source list (given by parameter MLLIST) and saves the results in the file controlled by APELISTOUT; this is the case of APEXFLAG=True. In the case of aperture photometry at arbitrary positions the results are also stored in the file with name APELISTOUT (case of STACKFLAG=True).

Examples of usage

Example 1

Generate sensitivity maps based on aperture photometry. Apertures are defined in units of Encircled Energy Fraction (EEF). The first product that needs to be generated is, therefore, a PSF map that provides a measure of the PSF size (in pixels) for different EEFs across the field of view. The creation of the PSF Map requires as input event lists. Information about the energy interval of interest to generate the correct PSF model is read from the event list header. The flag that controls the generation of PSF Maps is PSFMAPFLAG:

apetool images="events_image.fits" psfmaps="psf_map.fits" psfmapflag=yes"

In the case of multiple energy bands:

 
apetool images="events_image_01.fits events_image_02.fits events_image_03.fits" 
  psfmaps="psf_map_01.fits psf_map_02.fits psf_map_03.fits" psfmapflag=yes"

Caution: The parameter PSFMAPSAMPLING is currently not used. The PSF sizes are estimated in a grid of 21x21 positions along the X and Y axes (to be changed in future versions). The final product is a cube that contains PSF sizes in the grid above for the EEF values: 0.4,0.45,0.5,0.55,0.6,0.65,0.7,0.75,0.8,0.85,0.9,0.95. The next step is to generate a sensitivity map by setting the APESENSEFLAG to yes. The example below assumes that the sensitivity map will use an EEF of 0.65 and a Poisson False Detection Threshold of 4e-6.

apetool images="events_image.fits" \
  expimages="output_expmap.fits" bkgimages="bkg_map.fits" \
  psfmaps="psf_map.fits" srcimages="source_image.fits"\
  detmasks="detmask.fits" apesenseimages="sensitivity_map.fits" \
  apesenseflag="yes" pthresh=4e-6  eefextract=0.65

Example 2

Determine aperture photometry for sources detected by the ERMLDET by setting the flag APEXFLAG to True. Given the Maximum Likelihood catalogue produced by ERMLDET (MLLIST parameter), APETOOL extracts the counts, background and exposure time at the sources' positions within apertures with radii defined in units of EEF (EEFEXTRACT parameter). The SourceMap (SRCIMAGE parameter) is used to determine the local background of a given source **after** subtracting from the SourceMap the model of the source in question. For APETOOL to reproduce accurately the ERMLDET source model and subtract it from the SourceMap it needs to use the same CUTRAD parameter as the ERMLDET run that produced the SourceMap and catalogue. It is up to the user to ensure that this parameter matches the ERMLDET run input. Using the SourceMap to determine the local background means that the aperture photometry accounts for the contamination of extracted counts from photons associated with the PSF wings of nearby sources (source confusion). The aperture photometry is stored in the filename defined by the parameter APELISTOUT. It is a copy of all the information listed in mllist with the additional aperture photometry information. The parameter APELISTOUT can be the same as the MLLIST, in which case the mllist file will be overwritten. The relevant APETOOL call:

apetool mllist="mllist.fits" apelistout="mllist_ape.fits"\
  images="events_image.fits" expimages="output_expmap.fits"\
  bkgimages="bkg_map.fits" psfmaps="psf_map.fits" \
  srcimages="source_image.fits" detmasks="detmask.fits"\
  psfmapflag=no apexflag=yes emin="200" emax="600"\
  eefextract=0.65 cutrad=15 eindex="1"

The example above determines aperture photometry in a single band. If the corresponding ERMLDET source catalogue contains more bands, then APETOOL needs to know which rows of the ERMLDET source catalogue should update. The parameter EINDEX provides this information. In the example above it informs the APEtOOL that the aperture photometry corresponds to the first band in the ERMLDET catalolgue. It is of course possible to run all the bands simultaneously in which case the eindex parameter is not needed:

apetool mllist="mllist.fits" apelistout="mllist_ape.fits" \
  images="events_image_01.fits events_image_02.fits events_image_03.fits"\
  expimages="output_expmap_01.fits output_expmap_02.fits output_expmap_03.fits"\
  bkgimages="bkg_map_01.fits bkg_map_02.fits bkg_map_03.fits" \
  psfmaps="psf_map_01.fits psf_map_02.fits psf_map_03.fits" \
  srcimages="source_image_01.fits source_image_02.fits source_image_03.fits"\
  detmasks="detmask.fits" \
  psfmapflag=no apexflag=yes \
  emin="200 600 2300" \
  emax="600 2300 5000"\
  eefextract=0.65 cutrad=15

Example 3

Carry out aperture photometry at arbitrary positions by setting the STACKFLAG paramter to yes. The input file is given by the parameter APELIST and should be a fits binary table with columns RA (source's right ascension in degrees; expects double precision number), DEC (source's declication in units of degrees; expects double precision number), RE (extraction radius in EEF units; double precision), RR (source removal radius in units of EEF; double precision). The code uses the RA, DEC positions to extract counts, estimate the background and determine the mean exposure time within an aperture of radius RE. The background estimation is using the SourceMap of ERMLDET. Before estimating the background at a given input position, any detected sources (read from MLLIST) within a radius RR from the input position will be removed from the source map. The photoemetry is stored to the filename defined by the parameter APELISTOUT:

apetool mllist="mllist.fits" apelist="mllist_ape_in.fits"\
  apelistout="mllist_ape_out.fits" images="events_image.fits"\
  expimages="output_expmap.fits" bkgimages="bkg_map.fits"\
  psfmaps="psf_map.fits" srcimages="source_image.fits"\
  detmasks="detmask.fits" stackflag=yes emin="200" emax="600"\
  eefextract=0.65 cutrad=15 eindex="1"

The case of two bands (not yet fully tested):

apetool mllist="mllist.fits" apelist="mllist_ape_in.fits" apelistout="mllist_ape_out.fits"\
  images="events_image_01.fits events_image_02.fits events_image_03.fits"\
  expimages="output_expmap_01.fits output_expmap_02.fits output_expmap_03.fits"\
  bkgimages="bkg_map_01.fits bkg_map_02.fits bkg_map_03.fits"\
  psfmaps="psf_map_01.fits psf_map_02.fits psf_map_03.fits"\
  srcimages="source_image_01.fits source_image_02.fits source_image_03.fits"\
  detmasks="detmask.fits" stackflag=yes emin="200 600" emax="600 2300"\
  eefextract=0.65 cutrad=15 eindex="1 2"