NAME

griddetect.pl - grid-based detection with emldetect

SYNOPSYS

This program should be called thrice. The first time, to ingest the list of images and exposure maps, and the grid definition: ./griddetect --ingest --imglist=mylist.txt --grid=mygrid.txt --srclist=mysrclist.fits --ccf=ccf.cif --odf=xxxxSUM.SAS

The second time to create the bkg files: ./griddetect --bkg

The third time to actually run the detection: ./griddetect --eband="05-8" --ecf=8.61e-12 --pimin=500 pimax=8000

DESCRIPTION

This program takes a number of XMM-Newton pointings, divides them according to a grid specified by the user, and repeatedly performs source detection with emldetect in all cells of the grid.

At each emldetect run, all pointings overlapping within a cell are used, but only the sources within the cells are kept. The final catalogue is the union of the sources detected in each cell.

The grid is defined by specifiying the coordinates of the cracks (i.e., the lines dividing the cells) and a rotation angle.

For more information, please see the griddetect manual and the article "The XMM-Newton survey in the H-ATLAS field" by Ranalli et al., 2015 A&A 577, 121.

PARAMETERS

--ingest

Read the list of images and exposure maps, and the grid definition. This information is processed and stored and will be used in the following runs.
--imglist=mylist.txt

Specify the image/expmap list filename.
--grid=myrgid.txt

Specify the grid definition filename.
--srclist=mysrclist.fits

Specify the input catalogue, to be used for both the background fit and the emldetect runs.
--bkg

Fit a background model to the images and exposure maps, according to the method developed for XMM-COSMOS (Cappelluti et al. 2009).
--eband="05-8"

A string describing the energy band, to be used as part of the name of file produced in the detection.
--ecf=8.6e-12

The energy conversion factor (ecf), defined as the flux (in erg/s/cm2) corresponding to a count rate of 1 s**-1.
--pimin=500 --pimax=8000

Minimun and maximum values of the energy band, in eV.

INPUT FILES

List of images and exposure maps

This should be a text file containing, in one row for each pointing, the following columns:

path of the image file
path of the exposure map
path of the unvignetted exposure map ("novign" option in eexpmap)
path of the background file

The columns should be separated by spaces (or tabs) and value should be missing. Rows can contain comments if they start with a #.

All files are checked for their existence. Images, expmaps and unvignetted expmaps have to exist in order to succesfully ingest the list. Background files are checked but it is allowed that they do not exist, because usually they will be created in the second stage with the --bkg option.

Grid definition

This should be a text file containing a series of key/value pairs, as in the following example, which defines a 3x5 grid with cracks rotated by 35 degrees with respect to the RA,Dec framework:

rotation=35   #  grid rotation in degrees (positive: clockwise)
ra_centre=53.12345    #  RA of rotation centre
dec_centre=24.6543    #  Dec of rotation centre
x=52.8        # grid boundary (along the rotated RA axis)
x=53.07       # a crack
x=53.17       # another crack
x=53.5        # grid boundary
y=24.2        # grid boundary (along the rotated Dec axis)
y=24.5        # crack
y=24.6        # crack
y=24.7        # crack
y=25          # grid boundary

If only one row (or column) is desired in the grid, then only the boundaries should be specified.

The conversion between equatorial coordinates (ra,dec) and the rotated (x,y) used here is:

x = (ra-ra_centre)*cos(rotation) - (dec-dec_centre)*sin(rotation)
y = (ra-ra_centre)*sin(rotation) + (dec-dec_centre)*cos(rotation)

Rotation, ra_centre and dec_centre are optional: in their absence, the (x,y) coordinates will be interpreted as (ra,dec).

Any number (including zero) of "x" and "y" lines can be specified in the file; however, at least one x or one y should be present.

A sample grid is present in the distribution in the file sample_grid.txt.

WORKFLOW

A typical workflow for a wide survey could be as follows (the first 8 steps are meant to prepare the input for griddetect):

correct the relative astrometry between different obsids;
obtain an input catalogue (e.g., by running ewavelet on the mosaic image);
run emosaic_prep on astrometry-corrected event files to split each obsid into individual pointings;
run mosaicfix.pl to put the coordinates in the individual pointings;
create reprojected event files, images and expmaps (e.g., using evtlist2makefile.pl and img-extractor-expmap.pl);
fix again pointing info (mosaicrefix.pl);
sum the images and expmaps over camera (addcameras.pl);
prepare the list of images/expmaps and the grid definition (see below);
ingest the list and the grid definition: griddetect --ingest --list=mylist.txt --grid=mygrid.txt
make the backgrounds: griddetect.pl --bkg
do the detection: griddetect.pl
check for sources close to the cracks;

# join the individual catalogues.

For more information I suggest any user to contact me, I'll be glad to explain more in detail how the programme works.

DEPENDENCIES

(to be filled with info from XMMSAS::Extract)

VERSION

2.1

AUTHOR

LICENSE

Affero GPL v.3.0 (full details: http://www.gnu.org/licenses/agpl-3.0.html)

This license applies to these file, to all files in the git repository, and to all packages in the XMMSAS:: and Detection:: namespaces called by this program.

HISTORY

0.1  2013/5/      Development version used for XMM-ATLAS
1.0  2014/12/10   First public version
2.0  2015/1/19    Detection over multiple bands
2.1  2016/12/18   Bug fixes

CTJChen / griddetect