XISEXPMAPGEN (May 2007)         suzaku.xis         XISEXPMAPGEN (May 2007)

NAME
    xisexpmapgen -- create detector mask image and exposure map for XIS

USAGE
    xisexpmapgen outfile phafile attitude

DESCRIPTION

    'xisexpmapgen' creates the XIS detector mask image and exposure map.
    The detector mask image usually contains 1 or 0 for its pixel values,
    where unused pixels, e.g. bad columns, SCI rows, hot/flickering pixels,
    and the 55Fe calibration source area, are set to 0 and others are 1,
    based on the user specification of the pixel quality, with parameters:
    'pixq_min', 'pixq_max', 'pixq_and', and 'pixq_eql'. See help file of
    'xisputpixelquality' for the detail of the definition of the pixel
    quality, or STATUS column of the event file. One may specify the optional
    'hotpixfiles' parameter to read hot pixels from the HOTPIXELS extension
    in the DarkInit and DarkUpdate FITS files. The image sometimes
    holds the pixel value between 0 to 1 in the window option. This detector
    mask image can be used for the 'detmask' image of 'xissimarfgen'.
    The detector mask is written in the primary image of the 'outfile'.

    The exposure map contains exposure time in unit of second for its pixel
    values in the sky coordinates. The jitter of the spacecraft attitude
    during the observation is considered. The exposure map is written in
    the 1st extension image of the 'outfile'. If 'attitude=none', only the
    detector mask is written in the primary image. The observation period
    is extracted from the TIME column of the EVENTS extension, or the GTI
    extension of the spectrum file, specified by 'phafile' parameter.
    If the optional 'gtifile' parameter is specified, 'xisexpmapgen' read the
    observation period from the 'gtifile', which is set to 'none' by default.
    
    The observation mode is read from header keywords in the primary
    extension of 'phafile'. e.g. WINOPT, WIN_ST, WIN_SIZ, CI, SCIN, SCIYn.
    The reference coordinates of the exposure map are also read from the
    RA_NOM and DEC_NOM keywords of 'phafile'.

PARAMETERS

outfile [file name]
    Name of output exposure map file.

phafile [file name]
    Name of the input spectrum or event file to get observation mode.

attitude [file name]
    Name of input attitude file,
    or 'NONE' only to calculate the detector mask image.

(gtifile = none) [file name]
    Name of input GTI file, or 'NONE' to read from the 'phafile'.

(teldef=CALDB) [file name]
    Name of input teldef file,
    or 'CALDB' to automatically read from the calibration database.
    The name is ae_<ins>_teldef_YYYYMMDD.fits
    where <ins> is a string set to xi0, xi1, xi2, xi3 indicating
    the sensor and YYYYMMDD is the release date.

(aberration = yes) [boolean]
    Correct aberration due to parallax,
    i.e. the revolution of the Earth around the Sun.

(clobber = yes) [boolean]
    Overwrite output file if exists.

(enable_pixq = yes) [boolean]
    Enable the pixel quality selection with parameters:
    'pixq_min', 'pixq_max', 'pixq_and', and 'pixq_eql'.

(hotpixfiles = none) [file name]
    Names of input hot pixel files. Hot pixels excluded onboard XIS-DE is
    stored in the DarkInit and DarkUpdate files in the XIS trend archive.
    Multiple file names can be specified by the comma/SPACE/TAB/semicolon
    separated list, or '@FILELIST' to read the file names from an indirect
    file of FILELIST.

(badcolumfile = CALDB) [filename]
    Input file that describes the XIS bad columns and flickering pixels,
    or 'CALDB' to automatically read from the calibration database.
    The name is ae_<ins>_badcolum_YYYYMMDD.fits
    where <ins> is a string set to xi0, xi1, xi2, xi3 indicating
    the sensor and YYYYMMDD is the release date.

(calmaskfile = CALDB) [filename]
    Input file that describes the irradiation area of 55Fe calibration source
    on the XIS CCD, or 'CALDB' to read from the calibration database.
    The name is ae_<ins>_calmask_YYYYMMDD.fits
    where <ins> is a string set to xi0, xi1, xi2, xi3 indicating
    the sensor and YYYYMMDD is the release date.

(pixq_min = 0) [real]
    Minimum value of allowed pixel quality.

(pixq_max = 524287) [real]
    Maximum value of allowed pixel quality.

(pixq_and = 65536) [real]
    Bit AND mask for pixel quality. The default value of 65536 is set to
    remove the 55Fe calibration source area.

(pixq_eql = 0) [real]
    Allowed pixel quality after bit AND mask.
    The pixel quality, equivalent to the STATUS column of event files,
    are selected as:
	pixq_min <= STATUS && STATUS <= pixq_max &&
        (STATUS & pixq_and) == pixq_eql

(anl_verbose = 1) [integer]
    ANL verbose level (-1:full, 0:minimum).

(anl_profile = yes) [boolean]
    Enable ANL module profiling.

(num_event = -1) [integer]
    number of frames (-1=all,0=exit).

(event_freq = 1000) [integer]
    Frame number printout frequency.

(chatter = 2) [integer]
    message chatter level (0:min,2:norm,5:max).

EXAMPLES

1.  Create an exposure map 'xis1_exp.img' using an input spectrum file
    'xis1_src.pi' and an input attitude file 'suzaku.att',
    with the default CALDB files and the default pixel quality selection.

    % xisexpmapgen xis1_exp.img xis1_src.pi suzaku.att

2.  Create only the detector mask image 'xis1_detmask.img'
    using an input event file 'xis1_src.evt'.

    % xisexpmapgen xis1_detmask.img xis1_src.evt none

3.  Create an exposure map 'xis1_exp.img' using an input event file
    'xis1_src.evt', an input attitude file 'suzaku.att', hot pixel files
    of xis1_din000.fff & xis1_dun000.fff, and GTI file of xis1.gti,
    including the 55Fe calibration source area.

    % xisexpmapgen xis1_exp.img xis1_src.evt suzaku.att \
                   hotpixfiles=xis1_din000.fff,xis1_dun000.fff \
                   gtifile=xis1.gti pixq_and=0

SEE ALSO

AUTHOR

    Y.ISHISAKI (TMU), and the XIS team.

LAST MODIFIED

    May 2007