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.
• generates sensitivity maps for a user-defined Poisson false-detection probability. These sensitivity maps describe at any given position on the eROSITA field-of-view the minimum number of counts that detections should have. This minimum number of counts is defined for circular apertures of fixed size radius 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 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:

• 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. There is an option to remove nearby sources from the SRCMAP when extracting background counts.
• APE_EXP: mean exposure time 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 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:

• MLLIST (string) OPTIONAL/REQUIRED IF APEXFLAG=True or if STACKFLAG=True
  • Input ERMLDET source list. If APEXFLAG=True then the task peforms aperture photometry at the positions listed in that catalogue. For the background estimation the SourceMap product of the ERMLDET task is used. The source in question is first removed form the the SourceMap using the shapelet model of the PSF and then then background counts are extracted. This approach accounts for the possible contribution of nearby sources to the observed counts of the source in question.
• 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 the first extension of a binary fits 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 corresponds to the radius (expressed in PSF Encircled Energy Fraction; should be positive and less than unity) 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) within which ERMLDET X-ray detections (given by the input ERMLDET sourcelist; parameter MLLIST) near the input position are removed from the corresponding SourceMap before extracting the background counts. Caution: In the current version of APETOOL the fits extension of the binary table should be named "Joined". This will be changed in future versions.
• 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) if the input positions are read from an ermldet source list. In the latter case the output file will be copy of the input ERMLDET catalogue 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). If the flag PSFMAPFLAG (see below) is set to TRUE then the PSF map is produced as output. Othrewise the PSF map image is expected to be read in as input.
• EXPIMAGES (string array) REQUIRED
  • Exposure maps corresponding to input images. Sizes and WCS headers must match 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 APEXFLAG=True or 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 ERMLDET 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 square degrees. The latter quantity represents the area within which a source of a given count rate can be detected. This calculation makes no assumptions on the X-ray spectral shape of the source.
• EMIN (real array) REQUIRED
  • Minimum energy of photons in input images (PI channels). The parameter is used to select the energy dependent calibration data.
• EMAX (real array) REQUIRED
  • Maximum energy of photon selection in input images (PI channels). The parameter is used to select the 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 the 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 bands [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 the EINDEX parameter 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 within counts will be extracted.
• PTHRESH, (real) OPTIONAL[default value: 4e-6]
  • The Poisson False Detection Threshold to be used for the sensitivity map calculation.
• CUTRAD (real) OPTIONAL[default value: 15]
  • Cut radius for source fitting. This parameter is used to subtract sources from the SourceMap. It should have the same value as that used in the ERMLDET run that produced the SourceMap image. Differences in the CUTRAD parameter between the 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. 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).
• 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 sourcelisty. 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 made or not.
• SHAPEPSF (boolean) REQUIRED[default value: YES]
  • Flag that controls whether the shapelet model for the PSF is used or not. This parameter should always be set to True.
• APESENSEFLAG (boolean) REQUIRED[default value: NO]
  • Flag that control whether sensitivity maps should be estimated or not.

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 also stored in the file with name APELISTOUT (case of STACKFLAG=True).

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:

• 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).
• In the case of aperture photometry at arbitrary positions the input catalogue is expected to be a fits binary table. In the current version of APETOOL the fits extension of the binary table should be named "Joined". This will be changed in future versions.