Back to eSASS task descriptions




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).


The APETOOL has three main functionalities:

PSF maps:

The PSF of the eROSITA is modeled using shapelet functions and their corresponding coefficients. This 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 is combines this information with the attitude file of a given observations (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:

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 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 still no used. 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 (i) either extract counts at source positions defined by an ERMLDET source catalogue, (ii) 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) and enables the combination of the source catalogue 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 apertures, within which counts are extracted, are expessed in terms of EEF, i.e. the radius that corresponds to a user-defined encircled energy fraction. The choice between the two aperture-photometry options is controlled by the logical flags APEXFLAG (True for aperture photometry at ERMLDET source catalogue positions) and STACKFLAG (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 in principle take into account nearby sources. They eROSITA PSF is broad and therefore photons associated with the extended wings of the PSF may enter the apertures of neighboring sources and contaminate their extracted counts (source confusion). The approach adopted by the APETOOL to address this issue is to use the SourceMap products generated by the ERMLDET. These are images of the model background plus model-profiles of the detected sources, i.e. a model-reconstruction of the real observations. If the user-defined aperture lies close to an X-ray detection then the SourceMap describes (at least to the first approximiation) the local background level because of the presence of the nearby sources. There can be situations however that the user wishes to use the source-free background level from SourceMap. This is the case for example of ERMLDET source positions, when one is insterested in estimating the sources' (aperture) photometry via APETOOL. For this particular application, the positions at which the aperture photometry is to be estimated coincide with the positions of the ERMLDET X-ray detections. Using the SourceMap to measure the local background is therefore problematic because it contains the source of interest as "background". For that reason the APETOOL has the functionality to remove individual sources from the SourceMap. It generates the model-profile of the source of interest and then simply subtracts it from the SourceMap leaving behind the source-free background level only. It is emphasised that this process only modifies the background map in the locality of individual detections. The area over which the SourceMap is modified is controlled by providing a radius (in units of PSF EEF). Any X-ray detections on the SourceMap that lie within this radius (off a given central position) will be removed. In the case of aperture photometry of ERMLDET sources the radius for excluding sources is the same as the radius for extracting photon counts. It is reiterated that all apertures 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 APETOOL retains the knowledge EEF accross the eROSITA field-of-vew using the PSFMap product.

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. In the current version of APETOOL the fits extension of the binary table should be named "Joined". This will be changed in future versions. The RE column corresponds to the radius (expressed in PSF Encircled Energy Fraction; should be positive and less than unity; i.e. a fraction) within which counts will be extracted from the input images and SourceMaps. The RR column corresponds to the radius (expressed in PSF Encircled Energy Fraction; should be less than unity; i.e. fraction) within which sources (given by the input ERMLDET sourcelist; parameter MLLIST) near the input position are removed from the the corresponding SourceMap before extracting background counts. The contribution to the background estimation of sources outside that radius allows accounting for source confusion effects. Setting this parameter to zero means that no sources will be removed from the SourceMap prior to the background extraction. The aperture photometry results either update the relevant columns (see below) of the input ERMLDET source list (given by parameter MLLIST; this is the case of APEXFLAG=True) or are stored in a fits file with filename controlled by the parameter APELISTOUT (case of STACKFLAG=True). In both cases of the aperture extraction mode the apetool updates/generates the following columns of the MLLIST/APELISTOUT file:

Sensitivity maps:

The sensitivity map provides an estimate of the minimum 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) should be considered as the 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 output 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 ERMLDET 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. The resulting area or sensitivity curve is stored in the fourth (table) extension of the sensitivity map fits files. It lists the count rate and the corresponding area in square degrees 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.

Input Parameters:

Input files:


Output files:

Examples of usage

Example 1

Generate sensitivity maps that are based on aperture photometry. Apertures are defined in units of Encircled Energy Fraction (EEF). The first product that needs to be generated is 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 the event lists only. 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 aase 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: 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 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 yes. 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 Source Map (SRCIMAGE parameter) is used to determine the local background of a given source **after** subtracting from the Source Map the model of the source in question. For APEtool to reproduce accurately the ERMLDET source model and subtract it from the Source Map it needs to use the same CUTRAD parameter as the ERMLDET run that produced the Source Map and catalogue. It is up to the user to ensure that this parameter matches the ERMLDET run input. Using the source map 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 energy band. If the corresponding ERMLDET source catalogue contains more bands, then the 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). In the current version of APETOOL the fits extension of the binary table should be named "Joined". This will be changed in future versions. The code will use 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 source map 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"

Known Issues: