NAME

USAGE

DESCRIPTION

The PI column populated by the Hitomi pipeline has a maximum value of 32768 channels. Each channel has a width of 0.5 eV width, so that the maximum energy is 16.384 keV. However the SXS can detect and process signals with energies up to ~32 keV, and the sxsextend task allows the user to define a new channel grid and assign energies over an extended range. The new channel number values are written to the PIE column in the output file(s) specified by the 'outuffile' and 'outclfile' parameters. The extended energy grid is determined by the required 'eminin', 'dein', and 'nchanin' parameters that specify the minimum energy [eV], energy channel binwidth [eV], and number of channels, respectively. Using the default values of these parameters results in PIE values spanning a grid of 1 eV channels extending to >32 keV.

The sxsextend task is a script that may be applied to unfiltered or cleaned SXS event files. In the former case the sxsextend script starts with the unfiltered event file, runs sxspha2pi, and sxsperseus for data collected before 00:41 UT March 4th 2016, with their extended energy scale options enabled in order to calculate UPIE (extended uncorrected energy), EPIE and EPIE2 (extended energy), and PIE values and populate the corresponding columns in the output unfiltered event file specified by the 'outuffile' parameter. The script then re-screens the data based on the input settings of various GTI file parameter settings, and creates the new cleaned event file specified by the 'outclfile' parameter. In this case, an input drift file is also required. If the input event file is a cleaned event file, the 'driftfile' parameter may be set to NONE, in which case the PIE values are determined based on the energies (values in EPI2 or EPI2PER column) present in the input file.

PARAMETERS

inuffile [filename]

Input SXS event file name. This file maybe be an unfiltered (_uf.evt) or cleaned (_cl.evt) SXS event file.

outuffile [filename]

Output SXS unfiltered event file with the UPIE, EPIE, EPI2E, and PIE columns populated. If 'driftfile=NONE', UPIE=UPI, EPIE=EPI (or EPIPER), EPI2E=EPI2 (or EPI2PER), and PIE is calculated based on values of the 'inuffile' EPI2 (or EPI2PER) column.

outclfile [filename]

Output SXS filtered event file with the UPIE, EPIE, EPI2E, and PIE columns populated, based on applying event and GTI screening to the file specified by 'outuffile'.

driftfile [filename NONE|file name]

Input drift correction (gain history) file created by the sxsgain task. If set to NONE, the code uses the input file energies in the EPI2 column to calculate the PIE column, using the energy grid parameters 'eminin', 'dein', and 'nchanin'.

gtigenfile [filename NONE|file name]

Input file containing the general GTI to use if the data are re-screened. This file is archived as part of the Hitomi data for each sequence in the auxil subdirectory, and it includes time intervals when the attitude and pointing are good, and has the suffix _gen.gti. If set to NONE, no general GTI is applied in screening.

gtitelfile [filename NONE|file name]

Input file containing the good SXS telemetry GTI to use if the data are re-screened. This file is archived as part of the Hitomi data for each sequence in the sxs/event_uf subdirectory, and has the suffix _tel.gti. If set to NONE, no good telemetry GTI is applied in screening.

gtimxsfile [filename]

Input file containing the fine GTI for the modulated X-ray source (MXS) to use if the data are re-screened. This file, that is made only if the MXS was in operation during some part of the observation, is archived as part of the Hitomi data for each sequence in the sxs/event_uf subdirectory, and has the suffix _mxsfn.gti. If set to NONE, no MXS GTI is applied in screening.

gtiadroff = DEFAULT [string]

Input file containing the times when the ADR is off to use if the data are re-screened. If set to DEFAULT these are read from the GTIADROFF extension of 'inuffile' (so this must be an unfiltered, and not a cleaned, event file). If a filename is specified, the times are read from the GTI extension of that file. If a filename and extension is specified, they are read from that extension. If set to NONE, no ADR-off GTI is applied in screening.

gtimkf = DEFAULT [string]

Input file containing the GTI when the housekeeping data are within nominal ranges to use if the data are re-screened. If set to DEFAULT these are read from the GTIMKF extension of 'inuffile' (so this must be an unfiltered, and not a cleaned, event file). If a filename is specified the times are read from the GTI extension of that file. If a filename and extension is specified, they are read from that extension. If set to NONE, no MKF GTI is applied in screening.

gtiehk = DEFAULT [string]

Input file containing the GTI when the orbit-related data are within nominal ranges to use if the data are re-screened. If set to DEFAULT these are read from the GTIEHK extension of 'inuffile' (so this must be an unfiltered, and not a cleaned, event file). If a filename is specified these are read from the GTI extension of that file. If a filename and extension is specified, these are read from that extension. If set to NONE, no EHK GTI is applied in screening.

gtiextra = NONE [string]

Input files containing any additional GTI to apply in re-screening the input event file. This may be a list of files or file extensions. If set to NONE, no additional GTI are used.

eminin = 0.0 [real]

Minimum energy of the extended energy channel grid [eV].

dein = 1.0 [string]

Bin width of the extended energy channel grid [eV].

nchanin = 32768 [integer]

Number of extended energy channels.

(gainfile = CALDB) [filename CALDB|file name]

Input file containing SXS gain coefficients. If the parameter is set to CALDB, the file is read from the calibration database.

(scalefile = CALDB) [filename CALDB|file name]

Input file containing SXS gain adjustments for each individual pixel. If the parameter is set to CALDB, the file is read from the calibration database.

(dgfile = REFDATA) [filename REFDATA]

Input differential gain coefficients file for sxsperseus gain adjustment. This file is read from the REFDATA area of HEAsoft and should not be changed.

(offsetfile = REFDATA) [filename REFDATA]

Input calibration pixel offsets file for sxsperseus gain adjustment. This file is read from the REFDATA area of HEAsoft and should not be changed.

(selectfile = CALDB) [filename CALDB|REFDATA|file name]

Input file with selection expressions. 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 in screening.

(leapsecfile = REFDATA) [string CALDB|REFDATA|file name]

Name of the leap second file. If the parameter is set to CALDB or REFDATA, the file in CALDB or the REFDATA area, respectively, is used.

(secphacol = PHA) [string]

Name of the column used to calculate EPI2. To account for corrections to secondary event PHA values, this should be set to the name of the column (PHA2, by default) populated by the task sxsseccor.

(method = FIT) [string FIT|AVERAGE]

Specifies the column to use from 'driftfile' in applying the drift correction. If 'method=FIT', the TEMP_FIT column is used, if 'method=AVERAGE', the TEMP_AVE column is used.

(scaleepi = no) [boolean yes|no]

If 'scaleepi=yes', the scale file specified by the parameter 'scalefile' is used to adjust the gain per pixel.

(scalegrade = 0) [string]

Grade(s) (values in input file column specifed by the 'itypecol' parameter) to apply the scaling factor per pixel to. Multiple grades maybe be specified by a comma-separated list (e.g., 'scalegrade=0,1,2'). This parameter is used only when the 'scalefile' contains two columns (PIXEL and HP). If the 'scalefile' contains four columns, the scaling factors in the row entries for each grade are used.

(itypecol = ITYPE) [string]

Column containing event grade in 'inuffile'.

(gapdt = -1.) [double]

Time interval used to define a window around events where the file specifed by 'driftfile' is not applicable (no entries for the appropriate pixel with times within this interval relative to the event time); and, in which case, EPI and PI are set to their null values. If the value of this parameter is <0, this check is skipped.

(ntemp = 3) [integer]

Number of temperatures represented in 'gainfile' to use in (ntemp-point) interpolation. This must not exceed the total number in the file.

(writetemp = no) [boolean yes|no]

If 'writetemp=yes', the pixel temperature used to assign energy for each event is written to the output event file.

(extrap = no) [boolean yes|no]

If 'extrap=yes', extrapolation is allowed when calculating temperature.

(randomize = yes) [boolean yes|no]

If 'randomize=yes', decimal randomization is applied to a PHA value (an integer) before applying the gain to derive an energy (a double-precision quantity).

(seed = 0) [integer]

Random number generator seed; uses system time for 'seed=0'.

(outrange = NULL) [string NULL|CONST|EXTRAP]

Define how to handle events with TIME outside of the 'driftfile' TIME range during sxsperseus gain adjustment. If 'outrange=NULL', assign EPIPER=EPI2PER=PI=NULL. If 'outrange=CONST', use the gain correction from the first or last time in 'driftfile'. If 'outrange=EXTRAP', linearly extrapolate the gain correction from 'driftfile'.

(expr = NONE) [string NONE|expression]

Expression applied in screening of input file 'inuffile', in addition to any specifed in 'selectfile'. If set to NONE, no additional screening is applied.

(label = PIXELALL3) [string]

Screening expression label in 'selectfile' to use for creating GTI in screening of 'inuffile'. This parameter is ignored if 'selectfile=NONE'. Multiple labels may be applied using a comma-separated list.

(cleanup = yes) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(buffer = -1) [integer -1|0|N]

Rows to buffer (-1=auto, 0=none, N>0=numrows).

(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. Assign PIE using the default extended energy grid and the energies already assigned in the cleaned input event file.

  sxsextend inuffile=sxs_eventcl.evt outuffile=sxs_eventclext.evt outclfile=NONE driftfile=NONE gtigenfile=NONE \
  gtitelfile=NONE gtimxsfile=NONE gtiadroff=NONE gtimkf=NONE gtiehk=NONE label=NONE 

SEE ALSO

LAST MODIFIED