NAME

USAGE

DESCRIPTION

The hxisgdshield Perl script extracts either light curves or spectra from the shield data of HXI or SGD.

There are three modes for the output data type: light curve (LC), spectra (SPEC), and "scan" light curve (SCAN). The mode is selected by the parameter 'outfile_type'.

In LC mode ('outfile_type=LC'), the task generates light curves summed over a given energy range, which is set by the parameter 'energybin'. The parameter 'energybin' may also be set to ALL to create light curves summed over all energy bins. The total number of energy bins varies according to the input data type. Light curves may be generated from any type of HXI or SGD shield data (see below for a description of the different data types).

In SPEC mode ('outfile_type=SPEC'), spectra are generated by summing the counts within a specified time range for each energy channel. Spectra may only be generated from histogram and gamma-ray burst data (see below for more information about these data types). The lower and upper bounds of the time range are set by the hidden parameters 'tstart' and 'tstop', respectively. The parameter 'tstart' may be set to TSTART, in which case the TSTART keyword of the input extension is used as the lower time bound. Similarly, the parameter 'tstop' may be set to TSTOP, in which case the TSTOP keyword of the input extension is used as the upper time bound. Count-type spectra are always created using the same channel definitions as the input file type. In addition, if 'deconvolve=yes', rate-type deconvolved spectra are also produced with the native instrumental channel definitions (0-4095). In this case, the counts in each channel from the input data are spread uniformly over some number of deconvolved channels, and divided by the exposure to compute the rate.

In SCAN mode ('outfile_type=SCAN'), light curves are generated from the shield data taken during the lower discriminator scan test. This mode may only be used for scalar data type (see below). The parameters 'tstart' and 'tstop' in SCAN mode have the same meaning and behavior as in SPEC mode. A housekeeping (HK) file is required for SCAN mode. Times from the TIME column in the HK file are used to create a good time interval (GTI) file. This GTI file is used to filter the light curves produced in SCAN mode, and the GTI extension is appended to the final output file. Each GTI in the file is based on a time from the HK file. The GTI START column is determined by subtracting the parameter 'gticut_pre' from each time in the HK file. Similarly, the GTI STOP column is determined by adding the parameter 'gticut_post' to the time in the HK file.

Input Data Types

Both HXI and SGD input shield FITS data come in three types: scalar (SCL) with one value in each input column, histogram (HIST) with 128 channels (numbered 0 to 127), and gamma-ray burst (GRB) data with 32 channels (numbered from 0 to 31). The different types of data are stored in different files and/or extensions. This task analyzes one type of data at a time, thus users must choose the type to analyze using the parameter 'datatype'. Once the user chooses the data type, this task automatically looks for the input data columns in the appropriate extension(s) of the input data file. FITS input data for all three data types contain multiple columns. This task creates one output light curve or spectrum FITS file for each input column, unless the user specifies particular column(s) for processing using the parameter 'columnname'.

PARAMETERS

infile = sclhist.evt [filename]

Name of input shield FITS data file.

outfile_root = scl_ [string]

Initial part of output file name. The name of each column from the input file is appended to this root to create the base name for the output file. The suffix ".lc" is used for output light curves and ".pha" for output spectra. For example, if the 'outfile_root=my_data', the output light curve file produced from the input column SH1_FBGO1 would be named my_data_SH1_FBGO1.lc.

outfile_type = LC [string LC|SPEC|SCAN]

Type of output file.

datatype = SCL [string SCL|HIST|GRB]

Data type for which the light curve or spectrum is calculated. SCL is invalid for SPEC mode. Only 'datatyp=SCL' is available for SCAN mode.

columnname = all [string]

Name of column for which a light curve or spectrum is calculated. The value may be all, or the user may specify one or more column names, with multiple column names separated by whitespace or commas. If 'columnname' is set to all, this task performs the specified calculations for each input column in the input extension. A separate output FITS file is produced for each input column selected. For example, if 'columnname' were set to SH_GRB1 for an HXI GRB light curve, one output file would be produced. If 'columnname=SH_GRB1, SH_GRB2', two output files would be produced, and if 'columnname=all', six output files would be produced for SH_GRB1 through SH_GRB6.

(energybin = all) [string]

Input energy bins for HIST or GRB light curves, expressed either as a range of channels (e.g., 'energybin=3-10') or all. This parameter is only used in LC mode. The parameter 'energybin' must be all or 1 for SCL data. HIST and GRB data have 128 channels and 32 channels, respectively. Note that the channel number starts from 0, so the last channel of HIST data is 127, not 128. To select a single bin, users must still enter a range (e.g., 'energybin=3-3') to include only bin 3. To include just the first ten channels, users should specify 'energybin=0-9'. When 'energybin=all', all the channels are used, that is, 0-127 for HIST data and 0-31 for GRB data.

(tstart = TSTART) [string]

Start time [s] for generating spectra or SCAN light curves. Set to TSTART to use the input extension's TSTART keyword. Used only in SPEC or SCAN mode.

(tstop = TSTOP) [string]

Stop time [s] for generating spectra or SCAN light curves. Set to TSTOP to use the input extension's TSTOP keyword. Used only in SPEC or SCAN mode.

(deconvolve = yes) [boolean yes|no]

If 'deconvolve=yes', deconvolved spectra with the original 4096 channels (0-4095) are generated in addition to the (convolved) spectra with 128/32 channels from HIST/GRB data. Used only in SPEC mode.

hkfile = hk.fits [filename]

Input HK file name for GTI search. Required and used only in SCAN mode.

hkext = HK_HXI1_APMU_PRM [string]

HK extension name to read for the HK file. The name varies, depending on instrument. The parameter is required and used only in SCAN mode.

(gticut_pre = 8) [integer]

Duration [s] prior to times in the HK file that are used to compute the lower limit of each GTI. Times in the HK file indicate the time of the lower discriminator threshold change. Used only in SCAN mode.

(gticut_post = 4) [integer]

Duration after times in the HK file that are used to compute the lower limit of each GTI. Times in the HK file indicate the time of the lower discriminator threshold change. Used only in SCAN mode.

(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 = 1) [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. Create all light curves for HXI1 HIST data with a selection of energy channels.

    hxisgdshield infile=HXI1_shield_data.fits outfile_root=lc outfile_type=LC datatype=HIST columnname=all \
       hkfile=NONE hkext=NONE energybin="10-100"

2. Create a spectrum and a deconvolved spectrum for HXI1 HIST data in the SH_HIST5 column.

   hxisgdshield infile=HXI1_shield_data.fits outfile_root=spec outfile_type=SPEC datatype=HIST columnname=SH_HIST5 \
      hkfile=NONE hkext=NONE

3. Create all SCAN light curves for SGD1 SCL data.

   hxisgdshield infile=SGD1_shield_data.fits outfile_root=scan outfile_type=SCAN datatype=SCL columnname=all \
      hkfile=hk.fits hkext=HK_SGD1_APMU_PRM

LAST MODIFIED