NAME

USAGE

DESCRIPTION

'hxisgdshield' extracts either light curves or spectra from the shield data of the 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 tool 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 (HIST) and gamma-ray burst (GRB) 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' (the default), 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 (SCL) data. 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 tool 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 tool 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 tool 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 [filename]

Name of input shield FITS data file.

outfile_root [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 were 'my_data', the output light curve file produced from the input column SH1_FBGO1 would be named my_data_SH1_FBGO1.lc.

outfile_type [string]

Type of output file: LC, SPEC, or SCAN (short for "light curve", "spectrum", or "light curve for scan mode", respectively).

datatype [string]

Data type for which light curve or spectrum is caclulated: SCL, HIST, or GRB (short for "scalar", "histogram", or "burst", repectively). SCL is invalid for SPEC mode. Only SCL data is available for SCAN mode.

columnname [string]

Name of column for which light curve or spectrum is calculated. The value may be 'all' or may specify one or more column names, with multiple column names separated by whitespace or commas. If columnname is set to 'all', this tool 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 gamma ray burst (GRB) light curve, one output file would be produced. If columnname were 'SH_GRB1, SH_GRB2', two output files would be produced, and if columnname were 'all', six output files would be produced for SH_GRB1 through SH_GRB6.

(energybin) [string]

Input energy bins for HIST or GRB light curves, expressed either as a range of channels, e.g., '3-10' or the word '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 (zero), 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 in seconds 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 in seconds 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]

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 ([yes]/no).

hkfile [filename]

Input HK file name for GTI search. Required and used only in SCAN mode. In other modes, user may enter any value for this parameter including NONE.

hkext [string]

HK extension name to read. Varies depending on instrument. Required and used only in SCAN mode. In other modes, user may enter any value for this parameter including NONE.

(gticut_pre = 8) [integer]

Duration prior to times in the HK file 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 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]

Indicates whether or not to delete temporary files. Setting to 'no' may help with troubleshooting ([yes]/no).

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

    hxisgdshield.pl 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.pl 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.pl 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

February 2, 2016