NAME

xamkehk - Make an extended housekeeping (EHK) file using XRISM orbit and attitude data to construct time series columns for the housekeeping parameters

USAGE

xamkehk attfile orbfile outfile

DESCRIPTION

The xamkehk task reads satellite orbit and attitude files for a given observation and generates an extended housekeeping (EHK) file. The EHK file contains many parameters related to the attitude, SAA (South Atlantic Anomaly), cutoff rigidity, and other orbital information that are not supplied in any housekeeping, or other auxiliary file. The content of the EHK is used to screen event data.

The time coverage of the output file is based on the 'tstart' and 'tstop' input parameters (units are time in seconds, since the start of the mission). The input 'attfile' is used as the basis of the output times if 'tstart' or 'tstop' is 0 and 'reference=NONE'. These start and stop times can be extended using the 'textend' parameter, and the output columns are calculated by extrapolation if necessary. The 'bintime' parameter defines the time sampling of the output file. All times are in units of seconds.

The pointing is derived from the columns specified by the 'attform' parameter in the extension specified by the 'attcol' parameter in the file specified by the 'attfile' parameter. The column must be in the format of either a three-component Euler angle array ('attform=EULER') or a four-component quaternion ('attform=QUAT').

The orbit position is computed from the orbital elements (from columns in the 'orbext' extension from the file given by the 'orbfile' parameter). If the 'orbform' parameter is set to KEPLERIAN, these columns are A (semi-major axis), E (eccentricity), I (inclination), AN (ascending node right ascension), AP (ascending node angle), and MA (mean anomaly), unless overridden by the 'orbcol' parameter. If 'orbform' is set to COMPONENTS, the individual components of the orbital velocity are extracted from the VX, VY, and VZ columns, unless overridden by the 'orbcol' parameter. If 'orbform' is set to VECTOR, these velocity components are read from a single vector column specified by 'orbcol'.

The file corresponding to the 'teldeffile' and 'rsl_teldeffile' parameters, contain the information needed to transform between coordinates related to pointing, XRISM focal plane (FOC), and SKY coordinate systems. The telescope definition (teldef) file set by 'teldeffile' is that for the Xtend instrument, whereas the file set by 'rsl_teldeffile' corresponds to the Resolve instrument. The transformation between FOC and SKY coordinates does not depend on the instrument, however the DET to FOC conversion does, which is why both telescope definition files are needed.

This task creates an output file that includes four columns containing values of the cutoff rigidity (COR, COR2, COR3, CORTIME). The rigidity tables (in the form of geographic longitude/latitude map images) that provide data for COR2 and COR3 are specified by the 'cor2file' and 'cor3file' parameters. The map array corresponding the COR column is hardcoded in the atFunctions library. The default value of 'cor2file' specifies the the revised rigidity map used for Suzaku. The default value of 'cor3file' specifies a more recent map based on the 2015 International Geomagnetic Reference Field (IGRF) model (see https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html), extapolated to the year 2016.0. By contrast, the CORTIME column is freshly computed each time xamkehk is run using the 2020 IGRF model extrapolated to the mission elapsed time (MET) given in the TIME column, together with the instantaneous orbital position of the spacecraft. In general, CORTIME is recommended for event filtering, and the other estimates of cutoff rigidity are provided for comparison with previous missions. The 'saafile' parameter determines the origin of the calculation of the satellite position with respect to the SAA and contains the longitude and latitude of the vertices that define the SAA for each Hitomi instrument.

PARAMETERS

attfile [filename]
Input attitude file.

orbfile [filename]
Input orbit file, assumed to have the same format as Suzaku version 2 orbit files.

outfile = out.ehk [filename]
Output file in EHK format, containing a time series of quantities derived from the Hitomi instrument attitude and spacecraft orbit.

(tstart = 0.0) [double]
Start of mission time interval [s] of the output file. If either 'tstart' or 'tstop' is 0.0, the time interval is set equal to the time range of the reference file if there is one, or else to that of the attitude file.

(tstop = 0.0) [double]
End of mission time interval [s] of the output file. If either 'tstart' or 'tstop' is 0.0, the time interval is set equal to the time range of the reference file if there is one, or else to that of the attitude file.

(bintime = 1.0) [double]
Time sampling interval [s] of the output file. This parameter is not relevant if a reference file is used to supply the time points (see parameter 'reference').

(textend = 0.0) [double]
Time [s] added to the beginning and end of the output file time interval, preceding 'tstart' and following 'tstop'.

(reference = NONE) [filename NONE|file name]
Reference file supplying the actual time points to be calculated for the output file, overriding 'tstart' and 'tstop'; the 'bintime' parameter is not relevant when a reference file is supplied. If set to NONE, the start and stop times are obtained either from the input parameters 'tstart' and 'tstop', or they supplied by the input attitude file.

(timecol = TIME) [string]
Name of the column containing mission time in the reference file.

(attext = ATTITUDE) [string]
Name of the extension in the attitude file ('attfile') with pointing information.

(attform = EULER) [string EULER|QUAT]
Format of the input attitude column in the 'attext' extension of 'attfile'.

(attcol = EULER) [string]
Name of the input attitude column in the 'attext' extension of 'attfile'.

(teldeffile = CALDB) [filename CALDB|file name]
Name of the Xtend teldef file giving the coordinate systems of the XTD instrument, used to obtain higher coordinate transformation parameters. If set to CALDB, the file is read from the calibration database.

(rsl_teldeffile = CALDB) [filename CALDB|file name]
Name of the Resolve teldef file giving the coordinate systems of the RSL instrument, used to obtain higher coordinate transformation parameters. If set to CALDB, the file is read from the calibration database.

(cor2file = CALDB) [filename CALDB|file name]
Name of the file that provides the cutoff rigidity as a function of terrestrial coordinates used to fill the COR2 column. If set to CALDB, the file used for Suzaku is read from the calibration database.

(cor3file = CALDB) [filename CALDB|file name]
Name of the file that provides the cutoff rigidity as a function of terrestrial coordinates used to fill the COR3 column. If set to CALDB, the file calculated for the year 2016.0, based on the IGRF 2015 data (https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html), is read from the calibration database.

(saafile = CALDB) [filename CALDB|file name]
Name of the file which contains the vertices that define the SAA for each instrument. If set to CALDB, the file is read from the calibration database.

(leapsecfile = REFDATA) [filename REFDATA|CALDB|file name]
Name of the file giving the table of leap seconds. If set to CALDB or REFDATA, the file is read from the calibration database or the REFDATA area, respectively.

(orbext = ORBIT) [string]
Name of the extension in the orbit file ('orbfile') containing the orbital data.

(orbcol = A,E,I,AN,AP,MA) [string]
Name of the input orbit column in the 'orbext' extension of 'orbfile'.

(orbform = KEPLERIAN) [string VECTOR|COMPONENTS|KEPLERIAN]
Format of the input orbit velocity column in the 'orbext' extension of 'orbfile'.

(buffer = -1) [integer -1|0|N]
Rows to buffer (-1=auto, 0=none, N>0=number of rows).

(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 task parameters in HISTORY.

EXAMPLES

  1. Create the extended HK file xa100050020.ehk from attitude and orbit files xa100050020.att and xa100050020.orb.
  2.    xamkehk attfile=xa100050020.att orbfile=xa100050020.orb outfile=xa100050020.ehk
    
  3. Create the extended HK file xa100050020.ehk from attitude and orbit files xa100050020.att and xa100050020.orb, using the quaternion column QPARAM in the attitude file.
  4.    xamkehk attfile=xa100050020.att orbfile=xa100050020.orb outfile=xa100050020.ehk attcol=QPARAM attform=QUAT
    

SEE ALSO

xafilter, aemkehk makefilter, xrtfilter

LAST MODIFIED

February 22, 2024