NAME
sxsregext - Extract SXS data products from an event file using a region and selection of grades
USAGE
sxsregext infile regmode region outroot outexp ehkfile delta numphi
DESCRIPTION
'sxsregext' is a script that takes an SXS event file and region in SKY
or DET coordinates and produces a spectrum, an image, and a lightcurve
for a selection of event grades. The spectrum and lightcurve are
extracted in detector coordinates. If the input region is in SKY
coordinates, the script converts the region to one in DET coordinates
that includes any pixel in the region for any of the attitude
histogram bins in the exposure map that the script creates.
The inputs to 'sxsregext' are: (1) an SXS event file from which data
products are to be extracted; (2) a list of resolution grades (see
'resolist' parameter); (3) a region file in SKY or DET coordinates
(see 'regmode' and 'region' parameters); and (4) an extended
housekeeping (EHK) file (see 'ehkfile' parameter) that is needed to
create the exposure map. If the input region is in SKY coordinates,
the script runs the 'ahexpmap' and 'ahmkregion' tasks to create an
output exposure map (see 'outexp' parameter), and an output region
file in DET coordinates with prefix given by the 'outroot'
parameter. The region includes any pixel that falls in the region for
any of the attitude histogram bins in the exposure map (see 'ahexpmap'
help file). An image, spectrum, and lightcurve filtered on the list of
grades, are created (see outroot parameter). If 'regmode=DET' the
spectrum and lightcurve are extracted from the input region; if
'regmode=SKY' the spectrum and lightcurve are extracted using the
newly-created output region file (also with prefix given by
'outroot'). The identical detector region, selection of grades, and
exposure map should be used to generate the RMF (see 'sxsmkrmf' help
file) and ARF (see 'aharfgen' help file). The 'ahexpmap' input
parameters 'delta' and 'numphi' that determine the resolution of the
attitude histogram are also required (see 'ahexpmap' help file).
PARAMETERS
- infile [filename]
- Input SXS event file.
- regmode [string]
- Coordinate system for the region file. This is either DET or SKY.
- region [filename]
- Region file name. The format is that of a standard SAO region file.
- outroot [string]
- Root of output file names. If created, image, spectrum, exposure
map, and output detector region are given this prefix.
- (extract = yes) [boolean]
- If yes, extract image, lightcurve, and spectrum. All extracted
products are filtered on grade according to the resolist parameter;
the spectrum and lightcurve are also filtered on the input region if
regmode=DET and the output region if regmode=SKY. The parameter must
be set to yes if regmode=DET (yes/[no]).
- (resolist=0,1) [string]
- List of grades (ITYPE). ITYPE=0 for grade Hp, ITYPE=1 for Mp,
ITYPE=2 for Ms, ITYPE=3 for Lp, ITYPE=4 for Ls. Multiple numerical
values may be entered separated by a comma, e.g resolist=1,2,3. If
'resolist' is ALL, all grades are considered.
- (teldeffile = CALDB) [filename]
- Input teldef filename.
- outexp [filename]
- Name of output exposure map file. This parameter is ignored if
regmode=DET.
- ehkfile [filename]
- Name of input EHK file. This parameter is ignored if
regmode=DET.
- delta [real]
- Size in arcmin of each off-axis annulus grid (and on-axis circle)
in the output histogram. This parameter is ignored if regmode=DET.
- numphi [integer]
- Number of azimuth (phi) bins in the first off-axis annulus at
(delta <= theta < 2 * delta). A n-th off-axis annulus has azimuth
bins of numphi * n. This parameter is ignored if regmode=DET.
- badimgfile [filename]
- Name of input bad pixel image file. The file should contain an
image in the primary extension with the following flag values: good
pixels (0), calibration source region (1), bad pixels and columns (2),
and out of the detector or area discrimination (-1, null). For the
SXI, this is simply the output of the sxiflagpix routine
('outbadimg'). This parameter is ignored if regmode=DET.
- pixgtifile [filename]
- Name of input pixel GTI list. The file contains a bin table with
columns of START, STOP, DETX, and DETY, indicating the duration and
locatiion of each partial bad pixel. This parameter is ignored if
regmode=DET.
- (instmap = CALDB) [filename]
- Name of input instrument map file. If the paramater is set to
CALDB, the file is read from the calibration database. This file is
required for the task to run. This parameter is ignored if
regmode=DET.
- (qefile = CALDB) [filename]
- Name of input quantum efficiency file. If the paramater is set to
CALDB, the file is read from the calibration database. If the
parameter is set to NONE, the task does not use this calibration
information. This parameter is ignored when 'outmaptype' is set to
EXPOSURE, or if regmode=DET.
- (contamifile = CALDB) [filename]
- Name of input contamination file. If the paramater is set to
CALDB, the file is read from the calibration database. If the
parameter is set to NONE, the task does not use this calibration
information. This parameter is ignored when 'outmaptype' is set to
EXPOSURE, or if regmode=DET.
- (obffile = CALDB) [filename]
- Name of input optical blocking file for the SXS. If the paramater
is set to CALDB, the file is read from the calibration database. If
the parameter is set to NONE, the task does not use this calibration
information. This parameter is ignored when 'outmaptype' is set to
EXPOSURE, or if regmode=DET.
- (fwfile = CALDB) [filename]
- Name of input filter wheel file for the SXS. If the parameter is
set to CALDB, the file is read from the calibration database. If the
parameter is set to NONE, the task does not use this calibration
information. This parameter is ignored when 'outmaptype' is set to
EXPOSURE, or if regmode=DET.
- (gvfile = CALDB) [filename]
- Name of input gate valve file for the SXS. If the paramater is
set to CALDB, the file is read from the calibration database. If the
parameter is set to NONE, the task does not use this calibration
information. This parameter is ignored when 'outmaptype' is set to
EXPOSURE, or if regmode=DET.
- (maskcalsrc = yes) [boolean]
- If this parameter is set to 'yes', calibration source regions are
regarded as bad pixels and excluded from the output exposure map.
This parameter is ignored when 'badimgfile' is set to NONE, or if
regmode=DET.
- (fwtype = OPEN) [string]
- Filter wheel type for the SXS (OPEN, FE55, BE, ND, or POLY) This
parameter is ignored when 'outmaptype' is set to EXPOSURE, or if
regmode=DET.
- (specmode = MONO) [string]
- Type of input energy: monochrome energy (MONO) or spectrum
(SPEC). This parameter is ignored if regmode=DET.
- (specfile) [filename]
- Name of input spectrum file. This parameter is ignored if
'specmode' is set to MONO. This parameter is ignored if regmode=DET.
- (specform = FITS) [string]
- Format of the input spectrum file (FITS or ASCII). This parameter
is ignored if 'specmode' is set to MONO. This parameter is ignored if
regmode=DET.
- (buffer = -1) [integer]
- Rows to buffer (-1=auto, 0=none, >0=numrows).
- (clobber = no) [boolean]
- Overwrites the existing output file if set to yes (yes/[no]).
- (chatter = 1) [integer]
- Chatter level for output. Set to 0 to suppress output,
or to 1, 2, or 3 for increasing the chatter of the output.
- (logfile = !DEFAULT) [string]
- Log filename. If set to DEFAULT uses the name of the task and, if
preceded by '!', overwrite the file if it exists. If set to NONE no
log file is created.
- (debug = no) [boolean]
- Diagnostic output is printed out on the screen if set to yes
(yes/[no]).
- (history = yes) [boolean]
- Records tool parameters in HISTORY ([yes]/no).
- (mode = ql) [string ql|hl|q]
- Mode to query the parameter file.
Acceptable values include: 'ql' (query and learn/remember), 'hl' (hidden and learn/remember), 'q' (query but don't remember), 'h' (hidden).
EXAMPLES
1. Extract an image (sxsdata.img), spectrum (sxsdata.pha), and lightcurve (sxsdata.lc) for grades HP and MP from event file sxs.evt. Calculate and output (sxsdata.reg) the detector region used to extract the spectrum and lightcurve using the SKY region sxs_wcs.reg and the EHK file sxs.ehk, and create the exposure map file sxsexpmap.fits.
sxsregext infile=sxs.evt regmode=SKY region=sxs_wcs.reg outroot=sxsdata outexp=sxsexpmap.fits ehkfile=sxs.ehk delta=0.5 numphi=4
2. Extract an image (sxsdata.img), spectrum (sxsdata.pha), and lightcurve (sxsdata.lc) for grade HP only from event file sxs.evt. Calculate and output (sxsdata.reg) the detector region used to extract the spectrum and lightcurve using the SKY region sxs_wcs.reg and the EHK file sxs.ehk, and create the exposure map file sxsexpmap.fits.
sxsregext infile=sxs.evt regmode=SKY region=sxs_wcs.reg outroot=sxsdata resolist=0 outexp=sxsexpmap.fits ehkfile=sxs.ehk delta=0.5 numphi=4
3. Extract an image (sxsdata.img), spectrum (sxsdata.pha), and lightcurve (sxsdata.lc) for grades HP and MP from event file sxs.evt using the detector region
sxs_det.reg.
sxsregext infile=sxs.evt regmode=DET region=sxs_det.reg outroot=sxsdata outexp=none ehkfile=none delta=0.5 numphi=4
SEE ALSO
ahmkregion, coordpnt, ahexpmap, sxsmkrmf, aharfgen, ahsxtarfgen
LAST MODIFIED
08 March 2016