This section is meant to provide a glimpse on how to obtain images, exposure maps, source catalogues and products from a given set of calibrated event files. The following flow chart shows the main eSASS tasks that help to achieve this:
In the following, a step-by-step example of how to obtain source catalogues and products is shown. The example uses the default values for each eSASS task, and not all the task options are shown. For more specific requirements refer to the individual task pages.
1. evtool merges the input event files and creates an image in a given energy band:
$ evtool eventfiles="events1.fits events2.fits ... events7.fits" \
outfile="events_image_comb.fits" image=yes emin=0.5 emax=2.0
The output file events_image_comb.fits will have events and image extensions.
2. expmap computes the exposure map in a given energy band:
$ expmap inputdatasets="events_image_comb.fits" emin=0.5 emax=2.0 \
templateimage="events_image_comb.fits" mergedmaps="output_expmap.fits"
3. ermask creates a detection mask for the eSASS source detection chain:
$ ermask expimage="output_expmap.fits" detmask="detmask.fits"
4. erbox in local mode is the first step on the eSASS source detection chain.
$ erbox images="events_image_comb.fits" boxlist="boxlist_local.fits" emin=500 emax=2000 \
expimages="output_expmap.fits" detmasks="detmask.fits" bkgima_flag=N ecf=1
Note that bkgima_flag=N since the background map is created in the next step. An energy conversion factor (ecf) is necessary for erbox to run.
5. erbackmap creates a background map by masking sources detected by erbox:
$ erbackmap image="events_image_comb.fits" expimage="output_expmap.fits" \
boxlist="boxlist_local.fits" detmask="detmask.fits" bkgimage="bkg_map.fits" emin=500 \
emax=2000 cheesemask="cheesemask.fits"
6. erbox in map mode is the second step on the eSASS source detection chain:
$ erbox images="events_image_comb.fits" boxlist="boxlist_map.fits" expimages="output_expmap.fits" \
detmasks="detmask.fits" bkgimages="bkg_map.fits" emin=500 emax=2000 ecf=1
7. ermldet characterise the detected sources and determines source parameters:
$ ermldet mllist="mllist.fits" boxlist="boxlist_map.fits" images="events_image_comb.fits" \
expimages="output_expmap.fits" detmasks="detmask.fits" bkgimages="bkg_map.fits" \
extentmodel=beta srcimages="sourceimage.fits" emin=500 emax=2000
Note that the extended model can be either Gaussian or Beta, depending on the user necessities.
8. catprep converts the output of ermldet into the catalog file format:
$ catprep infile="mllist.fits" outfile="catalog.fits"
9. srctool derives source products (spectra, light-curves and corresponding instrumental files):
$ srctool eventfiles="events_image_comb.fits" todo=ALL srccoord="catalog.fits" \
srcreg='fk5;circle * * 60"' backreg='fk5;annulus * * 90" 120"' clobber=yes
In this case, srctool will extract all types of source and background products for all detected sources in the catalog.fits file.
2.1 How can I list the options of an eSASS tasks?
Using the plist command will give you the list of options that a given eSASS task can take, for example:
$ plist evtool
2.2 How to merge various event files?
evtool merges the input list of the file names or such list can be given in a text file:
$ evtool eventfiles="events1.fits events2.fits ... events7.fits" outfile="events_comb.fits"
or
$ evtool eventfiles="@filelist.txt" outfile="events_comb.fits"
2.3 Which flags should be applied to an event list?
The flag values can store 32 bits of information. When used as a selection mask in running evtool, the effect is that any event which has at least one of the bits in its flag will be discarded. The minimum recommended setting for the flag parameter is 0xc0000000 (hexadecimal system). This will delete all events flagged as either singly corrupt or as part of a corrupt frame. If the user wishes also to exclude events that lie outside the nominal field of view, then 0xc0008000 is the setting that will remove all 3 classes of events.
$ evtool eventfiles="events.fits" outfile="events_sel.fits" flag=0xc0008000
In addition, if the user wants to remove the identified bright pixels, then flag=0xC000F000 should be used. For more documentation on the available flags, click here.
2.4 Which pattern should be applied to an event list?
It is recommended to run evtool with the setting pattern=15. The value 15 sets a flag to retain all four of the recognized legal patterns. An expert user might want to vary this, for example, to use instead pattern=1 to select only singles, but leaving pattern at its default will pass through everything, bad patterns as well as good.
$ evtool eventfiles="events.fits" outfile="events_sel.fits" flag=0xc0008000 pattern=15
2.5 How to create an image from an event file?
evtool creates images in a given energy band, with certain rebin and size from an input event file:
$ evtool eventfiles="events.fits" outfile="events_image_comb.fits" emin=0.5 emax=2.0 \
image=yes rebin=80 size=3240
If the option events is not turned off, the events_image_comb.fits file will contain both image and events extensions.
2.6 How to re-centre a merged event file (and therefore its corresponding image)?
If a merged event file has been created using evtool (e.g. by merging several sky-tiles), one can use the radec2xy task to re-centre the merged file around the desired position:
$ radec2xy mergedfile.fits XXX.X YYY.Y
where XXX.X is the right ascension in deg, and YYY.Y is the declination in deg.
2.7 How to create an event file from a given region?
evtool can filter an input event list according to a specified region (file or expression):
$ evtool eventfiles="events.fits" outfile="events_image_comb.fits" region="fk5;circle(90,23,1.2)"
or
$ evtool eventfiles="events.fits" outfile="events_image_comb.fits" region="regionfile.reg"
The region files must be created before calling evtool with your favourite text editor, and it must contain one region per line.
2.8 How to extract an event file using good time intervals (GTIs)?
evtool can filter an input event list according to a specified time range (STDGTI extension or time range):
$ evtool eventfiles="events.fits" gti="TSTART TSTOP" outfile="events_filtered.fits"
where TSTART is the beginning of the GTI and TSTOP is the end of the GTI in seconds. TSTART and TSTOP values must be covered by the used observation.
2.9 Which good time intervals (GTIs) should I use to produce an exposure map?
The option gtitype in the task expmap specifies the type of good time intervals (GTIs) to be used for exposure map creation. The default value is GTI. If the user wishes to also exclude flared times, obtained e.g. with the task flaregti, then gtitype=FLAREGTI should be used:
$ expmap eventfiles="events.fits" gtitype=FLAREGTI outfile="events_flarefiltered.fits"
2.10 How to extract a light-curve of a point source?
One of the source products from srctool is a light curve ( todo="LC LCCORR" ) option), for example:
$ srctool eventfiles="events.fits" exttype="POINT" srccoord="fk5;99.0,-20.0" todo="LC LCCORR"
The option srccoord should include the coordinates of the source of interest within the observation. One can choose the instrument (insts option), the binning (lcpars option), energy range (lcemin and lcemax options), etc.
2.11 How to extract a spectrum/ARF/RMF for a point source?
srctool can extract the spectrum of a point source (exttype="POINT"):
$ srctool eventfiles="events.fits" exttype="POINT" srccoord="fk5;99.0,-20.0" todo="SPEC ARF RMF"
2.12 How to extract a spectrum/ARF/RMF for an extended source?
srctool can extract the spectrum of an extended source (exttype="tophat"):
$ srctool eventfiles="events.fits" exttype="tophat" srccoord="fk5;20.0,-99.0" \
todo="SPEC ARF RMF" PSFtype=none extpars=60
The extpars option depends on the value of the exttype parameter. When using a map to describe a source extent, the PSF corrections must be turned off (PSFtype=none). However, when extracting source products for relatively compact and circularly symmetric extended source, one should turn on PSF modelling, since PSF losses are likely to be important.
2.13 How do I generate an apetool sensitivity map?
The apetool sensitivity maps are 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 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 psfmaplag.
$ apetool apetool images="events_image.fits" psfmaps="psf_map.fits" psfmapflag=yes"
or in the case of many input bands:
$ apetool 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"
The parameter psfmapsampling is currently not used. PSF sizes are estimated in a grid of 21x21 pixels (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 (check the apetool documentation for the algorithm) by setting apesenseflag=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
The example above assumes that the ermldet source map represents the background against which the sensitivity map is estimated. This means that detected sources are assumed to be part of the background for the determination of the sensitivity map. It is possible to change this by substituting srcimages="source_image.fits" with srcimages="bkg_map.fits".
The parameter bkgimages is currently not used for the construction of a sensitivity map. It is nevertheless expected by apetool and should be provided.
2.14 How do I use apetool to perform aperture photometry on ermldet sources?
apetool can determine the aperture photometry for sources detected by the ermldet by setting flag apexflag=yes. Given the Maximum Likelihood catalogue produced by ermldet (mllist parameter), apetool will extract the counts, background and exposure time at the sources' positions within apertures with radii defined in units of EEF (eefextract parameter). The Source Map (srcimages 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 that used by 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 photos 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 additional aperture photometry information. The parameter apelistout can be the same as mllist, in which case the mllist file will be overwritten. The relevant apetool command:
$ 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, independently if the corresponding ermldet source catalogue contains more bands. ermldet 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
2.15 How do I use apetool to perform aperture photometry at arbitrary positions?
apetool can also determine aperture photometry at arbitrary positions by setting stackflag=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 will use the RA, DEC positions to extract counts, estimate the background and determine the mean exposure time with 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 photometry is stored to 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"
2.16 How do I use apetool to estimate upper limits?
Once aperture photometry is available it is straightforward to combine the output of apetool (counts, background, exposure time, eef) to determine upper limits.
2.17 How do I use apetool to perform stacking?
apetool provides the necessary quantities for X-ray stacking: counts, background, exposure time within user define apertures at arbitrary positions on the sky.