NAME

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

USAGE

ahmkehk attfile orbfile outfile

DESCRIPTION

The ahmkehk task reads satellite orbit and attitude files for a given observation and generates an expanded housekeeping (EHK) file. The EHK file contains many parameters related to the attitude, SAA, 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 parameter 'teldeffile', along with the values given by the 'optaxis' parameter, contain the information needed to transform between coordinates related to pointing, Hitomi focal plane (FOC), and SKY coordinate systems. The telescope definition (teldef) file set by 'teldeffile' is that for a fiducial instrument defined as the SXI for Hitomi. The transformation between FOC and SKY coordinates does not depend on the instrument. The 'optaxis' parameter is a comma-delimited list of the Hitomi optical axes of the four Hitomi imaging instruments, in FOC coordinates. The order of the eight numbers required is HXI1 (FOCX), HXI1 (FOCY), HXI2 (FOCX), HXI2 (FOCY), SXI (FOCX), SXI (FOCY), SXS (FOCX), and SXS (FOCY).

The task ahmkehk creates an output file that includes three columns that store values of the cutoff rigidity (COR, COR2, COR3). 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. By default, for COR2, this is the same data used for Suzaku, and for COR3 is a recalculation based on the International Geomagnetic Reference Field (IGRF) model that was updated 2015 (see https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html), and calculated for year 2016.0. 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. For the HXI, ahmkehk also includes an additional screening definition stored in the column SAA2. The content of SAA2 is calculated using a different definition of the SAA, whose longitute and latitude vertices are also in the 'saafile' CALDB file.

PARAMETERS

attfile = in.att [filename]
Input attitude file.

orbfile = in.orb [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 teldef file giving the coordinate systems of the SXI instrument, used to obtain SKY to FOC coordinate transformation parameters. If set to CALDB, the file is read from the calibration database.

(optaxis = 1215.5,1215.5,1215.5,1215.5,1215.5,1215.5,1215.5,1215.5) [string]
X and Y optical axis coordinates in FOC coordinates for HXI1, HXI2, SXI, and SXS instruments, in that order.

(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 ah000506304.ehk from attitude and orbit files ah000506304.att.gz and ah000506304.orb.gz.
  2.    ahmkehk attfile=ah000506304.att.gz orbfile=ah000506304.orb.gz outfile=ah000506304.ehk
    
  3. Create the extended HK file ah000506304.ehk from attitude and orbit files ah000506304.att.gz and ah000506304.orb.gz, using the quaternion column QPARAM in the attitude file.
  4.    ahmkehk attfile=ah000506304.att.gz orbfile=ah000506304.orb.gz outfile=ah000506304.ehk attcol=QPARAM attform=QUAT
    

SEE ALSO

ahfilter, aemkehk makefilter, xrtfilter

LAST MODIFIED

February 22, 2024