This page provides a simple guide to the basic eROSITA-DE data reduction and analysis. The eROSITA-DE Data Release 1 (DR1) consists of calibrated event lists, images, exposure maps, background maps, source products, upper limits etc (click here for further details). This cookbook is similar to the one in the Early Data Release (EDR) site. The analysis that can be performed with the eROSITA Science Analysis Software System (eSASS) includes extraction of images and source spectra, creation of exposure, background and sensitivity maps, performing source detection, etc. In comparison with eSASS4EDR, eSASS4DR1 includes several improvements and bug fixes in the different tasks (see here for further details).
On this page
apetool
sensitivity map? apetool
to perform aperture photometry on ermldet
sources? apetool
to perform aperture photometry at arbitrary positions? apetool
to estimate upper limits? apetool
to perform stacking? flaregti
work on a merged event file? apetool
gives negative values in the column ap_background_countsThis section provides a glimpse on how to obtain images, exposure maps, source catalogues and source 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"
See further remarks on the usage of expmap
in this topic.
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 catalogue file format:
$ catprep infile="mllist.fits" outfile="catalogue.fits"
9. srctool
derives source products (spectra, light-curves and corresponding instrumental files):
$ srctool eventfiles="events_image_comb.fits" todo=ALL srccoord="catalogue.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 catalogue.fits file
.
Using the plist
command will give you the list of options that a given eSASS task can take, for example:
$ plist evtool
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"
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, i.e., events=no
, the events_image_comb.fits
file will contain both image and events extensions.
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.
Note that radec2xy
works only with event lists, not with images.
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.
Note that evtool
in eSASS4DR1 only accepts the radius (or size) of the region in decimal degrees, without extra characters. For example, if you want to
extract a region with a radius of 30 arcmin, you should write 0.5, not 0.5d or 30'.
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.
The FLAG
values can store 32 bits of information. It is easier to visualise them in binary, for example:
0xc00f7f30 translates to 0b 1100 0000 0000 1111 0111 1111 0011 0000
whereas
0xC0040010 translates to 0b 1100 0000 0000 0100 0000 0000 0001 0000
When used as a selection mask in evtool
, the effect is that any event which has at least one of the bits in its FLAG
will be discarded. The bits are assigned to various problems and conditions.
In the examples above, the first one discards many more events than the second. Both will get rid of events that have the following bits set:
BIT_TRAILING_EVENT = 4 BIT_PRECEDING_MIP = 18 BIT_CORRUPT_EVENT = 30 BIT_CORRUPT_FRAME = 31
Note that to work out the bit number, you begin at the right-hand edge of the binary number, call that position bit 0, and then work left. Doing this, you see that the first bit of 0xC0040010
which is set is the 4th bit. The top selection, 0xc00f7f30
, in addition, will discard events that have the following bits set:
BIT_NEXT_TO_BORDER = 5 BIT_NEXT_TO_ONBOARD_BADPIX = 8 BIT_NEXT_TO_BRIGHT_PIX = 9 BIT_NEXT_TO_DEAD_PIX = 10 BIT_NEXT_TO_BADCOL = 11 BIT_ON_FLICKERING = 12 BIT_ON_BADPIX = 13 BIT_ON_BADCOL = 14 BIT_OUTSIDE_QUALGTI = 16 BIT_OUTSIDE_GTI = 17 BIT_PRECEDING_MIP = 18 BIT_MIP_ASSOCIATED = 19
All the available FLAGS are described here.
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.
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"
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.
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 psfmapflag
.
$ apetool images="events_image.fits" psfmaps="psf_map.fits" psfmapflag=yes"
or in the case of many input 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"
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. The sensitivity maps generated by apetool
can be used to, e.g., reconstrunct the number count distribution of X-ray source populations. This is demonstrated in jupyter notebook scripts made available as part of the eSASS4DR1 under <my eSASS path>/eSASS4DR1/eSASS/scripts/apetool
.
apetool
to perform aperture photometry on ermldet
sources? apetool
can determine the aperture photometry for sources detected by
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 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 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 be updated. 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
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"
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. The basic equations can be found in Ruiz et al. If you find these equations useful please cite Ruiz et al., MNRAS 511, 4265 (2022). The calculation of upper limits using the apetool
products is demonstrated in the jupyter notebook script APETOOL_UpperLimit.ipynb
made available as part of the eSASS4DR1 under eSASS4DR1/eSASS/scripts/apetool
.
apetool
to perform stacking? apetool
provides the necessary quantities for X-ray stacking: counts, background, exposure time within user defined apertures at arbitrary positions on the sky.
The eSASS4DR1 package offers a task or option to barycenter eROSITA data. This task is called ebarycen
. Read the documentation carefully to learn how to use this task. ebarycen
can be also used on EDR data.
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 0xE000F000
(hexadecimal system). This will delete all events flagged as either singly corrupt or as part of a corrupt frame, and events that lie outside the nominal field of view. This is the used flag in the 010 data processing of DR1.
$ evtool eventfiles="events.fits" outfile="events_sel.fits" flag=0xE000F000
Note that evtool
can only accept a single flag mask at a time, i.e. something like FLAG > 0xE000F00 && FLAG < 0xC0040010
is not allowed. For more documentation on the available flags, click here.
The released DR1 event files already have pattern=15
applied. 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 it will let pass through everything, bad patterns as well as good ones.
$ evtool eventfiles="events.fits" outfile="events_sel.fits" flag=0xE000F000 pattern=1
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"
expmap?
Most likely one wants to produce an exposure map that matches an event image. However, the expmap
task version available in eSASS4DR1 contains some caveats and can prevent to obtain the right exposure map. Here is a list of things to watch for:
expmap
with --withdetmaps='yes'
. The default value for this parameter is 'no'
. All the available FLAGS are described here. expmap
with --withfilebadpix='yes'
. The default value for this parameter is 'no'
. expmap
parameter --gtitype
the name of the extension you (last) used to filter your events. flaregti
work on a merged event file? It is possible to run flaregti
on a larger patch of the sky made from merged sky tiles. However, it is required that the xmin/ymin/xmax/ymax
parameters cover the range of sky coordinates that the merged event file contains. It is also advised to scale gridsize=18
by the approximate number of sky tiles on each axis.
For extended source analysis, it is also recommended to increase the source_size
parameter on flaregti
(e.g., to the arcmin scale).
Some eSASS tasks, like expmap
and ermldet
, produce a lot of terminal output when running. One can just redirect the output to /dev/null
, or set the environment variable SASS_VERBOSITY=sparse
. This last option should remove most of the output, though unfortunately it also removes any progress information. There is also an quiet option SASS_VERBOSITY=quiet
. This should be used carefully, if a given task fails then it will be difficult to trace back the problem unless the options are back to usual values.
The data processing version of the eRASS1 data is 010, while the version of EDR is 001. The eSASS4DR1 package corrects data processing issues and improves the different tasks. Therefore, eSASS4DR1 is an upgrade of eSASS4EDR. evtool
might have some issues working on 001 data. It is recommended to use the evtool
's option:
repair_gtis = yes
evtool
version does not accept a region that used to work on the eSASS4EDR version Indeed, the new evtool
version (v2.29.1) in eSASS4DR1 only accepts the radius (or size) of the region in decimal degrees without extra characters. For example, if you want to extract a region with a radius of 30 arcmin, you should write 0.5, not 0.5d or 30'.
Most of the eSASS4DR1 tasks accept compressed (*.gz) FITS files as input. Moreover, they can write their outputs as compressed FITS files as well. However, the tasks radec2xy
and flaregti
update the input event files, so these two task cannot work on compressed FITS files.
As discussed here, the eRASS1 data is organised in sky tiles of 3.6×3.6 square degrees in size. Some of those tiles have data with shared rights, i.e., between the German and the Russian consortiums. The calibrated event lists and the other data products that are released only contain X-ray photons and data that belong to eROSITA-DE. These products can be identified by their file name, which start with "eb01"
(see here for the file naming scheme). However, suppose you decide to produce your own data products from these shared-rights calibrated event lists. In that case, you will find that the produced images and exposure maps seem inconsistent, for example:
This discrepancy is due to the task expmap
, which currently contains no machinery for excluding sky areas based on the ownership event flags.
As discussed here, the eRASS1 data is organized in sky tiles of 3.6×3.6 square degrees in size. However, the sky tiles event lists contain photons beyond the 20 arcmin overlap between sky tiles. If you use evtool
to create images out of a single sky tile or multiple sky tiles and use the option size=auto
, then the final image will contain all photons that exist in the event list. The following image shows this issue. For example,
You have to be careful when cross-checking with other data products provided in eRODat. For example, exposure and background maps have a size of 3.6×3.6 square degrees.
apetool
gives negative values in the column ap_background_counts For a small fraction of sources (~0.07%; a total of 726) in the eRASS Main v1.1 catalog, apetool
estimates negative background values. This issue mainly occurs in the case of sources with nearby companions who are fit simultaneously by ermldet
.
apetool
's approach for estimating the background is that for each source in the input ermldet
catalog a source PSF model is constructed, which is then subtracted from the source map (generated by ermldet
). The resulting source map should, in principle, contain only the background level (plus any contribution from nearby sources) at the position of the source in question. However, it is sometimes the case that there is a mismatch between the ermldet
positions and the ones used to construct the source model. This is because ermldet
first produces a model of the PSF at the putative source position and then fits the source photon distribution. During the fitting process, the output centroid position may change, but the source PSF model is not updated when producing the source map.
apetool
then reads the new source position and produces a model of the PSF for that new position. Sometimes, this discrepancy may lead to slightly different PSF models and residuals when subtracting the apetool
PSF from the ermldet
source map. Such residuals tend to be more frequent in the case of nearby sources, presumably because this is when ermldet
finds larger source centroid offsets.
The eSASS4DR1 package provides a DEMO script, i.e. a python script that runs the different eSASS tasks. This script demonstrates how to obtain images and exposure maps in different energy bands from a calibrated event lists, how to run the source detection chain, and how to produce source products (i.e. light curves, spectra, etc.). See this page to check the location of this DEMO script on your eSASS4DR1 installation.
If by executing the demoscript you get the following error:
dyld: Library not loaded: @rpath/libhdutils_6.??.dylib
(where ?? is the HEASOFT version you have installed on your computer), it means that the python installation you are using cannot run the script. It is recommended to use python v3.10 in this case.