NAME

sxsregext - Extract Hitomi 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

The sxsregext task is a script that takes an SXS event file and region in RA/DEC or DET coordinates, and produces a spectrum, an image, and a light curve for a selection of event grades. The spectrum and light curve are extracted in detector coordinates. If the input region is in RA/DEC coordinates, the script converts the region to DET coordinates to include any pixel in the region for any of the attitude histogram bins in the exposure map that the script creates.

The required inputs to sxsregext are: (1) the SXS event file, specified by the 'infile' parameter, from which data products are to be extracted; (2) the list of resolution grades specified by the 'resolist' parameter; (3) the region file in RA/DEC or DET coordinates as specified by the 'regmode' and 'region' parameters; and, (4) an extended housekeeping (EHK) file specified by the 'ehkfile' parameter that is used to create the exposure map. If the input region is in RA/DEC coordinates ('regmode=RADEC'), the script runs the ahexpmap and ahmkregion tasks to create an output exposure map with filename given by the 'outexp' parameter, and an output region file in DET coordinates with prefix given by the 'outroot' parameter. The output region includes any pixel that falls in the input region for any of the exposure map attitude histogram bins specified by the 'delta' and 'numphi' parameters. An image, spectrum, and light curve, filtered on the list of grades, are extracted. The names of these files are formed by appending '.img', '.pha', and '.lc', respectively to the prefix given by the 'outroot' parameter. The spectrum and light curve are extracted using the newly-created output DET region file. The image is also extracted in DET coordinates but covers the entire field-of-view. If 'regmode=DET', the spectrum and light curve are extracted from the input region and no exposure map file is created. Note that the same grade selection, detector region, and exposure map file used here should be used to generate any corresponding RMF and ARF that are to be applied to the extracted spectrum.

PARAMETERS

infile = in.evt [filename]
Input SXS event file name.

regmode = RADEC [string DET|RADEC]
Coordinate system of the region file. If 'regmode=RADEC', the region file must be in FK5 (RA and DEC) format.

region = in.reg [filename]
Region file name. The format is that of a standard SAO region file.

outroot = sxsregext [string]
Root of output file names. If created, image, spectrum, and output detector regions are all given this prefix.

(extract = yes) [boolean yes|no]
If 'extract=yes', the image, light curve, and spectrum are extracted. All extracted products are filtered on grade according to the 'resolist' parameter. The spectrum and light curve are also filtered on the input region if 'regmode=DET', and the output region if 'regmode=RADEC'.

(resolist=0,1) [string 0|1|2|3|4|ALL]
List of grades (ITYPE) to select for: ITYPE=0 for grade Hp, ITYPE=1 for Mp, ITYPE=2 for Ms, ITYPE=3 for Lp, and ITYPE=4 for Ls. Multiple numerical values may be entered separated by commas (e.g., 'resolist=1,2,3'). If 'resolist=ALL', events with all grades are selected.

(teldeffile = CALDB) [filename CALDB|file name]
Input teldef file name. If this parameter is set to CALDB, this file is read from the calibration database.

outexp = sxsexpmap.fits [filename]
Name of output exposure map file. This parameter is ignored if 'regmode=DET'.

ehkfile = in.ehk [filename]
Name of input EHK (extended housekeeping) file. This parameter is ignored if 'regmode=DET'.

delta = 0.5 [double]
Attitude histogram radial increment [arcmin] for the annular (theta) grid. The nth annular region has inner and outer radii of (n-1)*delta and n*delta (the first annular region is a full circle of radius 'delta'). This parameter is ignored if 'regmode=DET'.

numphi = 4 [integer]
Number of azimuthal (phi) bins in the second annular bin. The first annular region has one azimuthal bin, the nth annular region numphi*(n-1) azimuthal bins.

badimgfile = NONE [filename NONE|file name]
Bad pixel image file name. The file should contain an image in the primary extension, with values representing the following flags: good pixels (0), calibration source pixel (1), bad pixels (2), out-of-detector (-1, NULL). This parameter is ignored if 'regmode=DET'.

pixgtifile = NONE [filename NONE|file name]
Input pixel GTI list file name containing a bin table with START, STOP, DETX, and DETY columns indicating bad time intervals for specfic pixel locations. This parameter is ignored if 'regmode=DET'.

(instmap = CALDB) [filename CALDB|file name]
Name of input instrument map file. If the parameter is set to CALDB, the file is read from the calibration database. This parameter is ignored if 'regmode=DET'.

(extended = no) [boolean yes|no]
If 'extended' is set to no the spectrum is extracted using the PI column of 'infile'; if set to yes, the PIE column is used. The relevant column must be present and populated in 'infile'.

(cleanup = yes) [boolean yes|no]
Delete temporary files if 'cleanup=yes'.

(clobber = no) [boolean yes|no]
Overwrites the existing output file if set to yes.

(chatter = 2) [integer 0|1|2|3]
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 DEFAULT|NONE|file name]
Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]
Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]
Records tool parameters in HISTORY.

EXAMPLES

  1. Extract an image (sxsdata.img), spectrum (sxsdata.pha), and light curve (sxsdata.lc) for grades Hp and Mp from the event file sxs.evt using the RADEC region sxs_wcs.reg and the EHK file sxs.ehk. Output the detector region (sxsdata.reg) used for extraction and the exposure map used to create this (sxsexpmap.fits).
  2.    sxsregext infile=sxs.evt regmode=RADEC region=sxs_wcs.reg  outroot=sxsdata outexp=sxsexpmap.fits ehkfile=sxs.ehk \
          delta=0.5 numphi=4
    
  3. Extract an image (sxsdata.img), spectrum (sxsdata.pha), and light curve (sxsdata.lc) for grade Hp only from the event file sxs.evt using the RADEC region sxs_wcs.reg and the EHK file sxs.ehk. Output the detector region (sxsdata.reg) used for extraction and the exposure map used to create this (sxsexpmap.fits).
  4.    sxsregext infile=sxs.evt regmode=RADEC region=sxs_wcs.reg  outroot=sxsdata resolist=0 outexp=sxsexpmap.fits \
          ehkfile=sxs.ehk delta=0.5 numphi=4
    
  5. Extract an image (sxsdata.img), spectrum (sxsdata.pha), and light curve (sxsdata.lc) for grades Hp and Mp from the event file sxs.evt using the detector region sxs_det.reg.
  6.    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, sxspixgti

LAST MODIFIED

August 2, 2024