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
- Create the extended HK file xa100050020.ehk from attitude and orbit
files xa100050020.att and xa100050020.orb.
xamkehk attfile=xa100050020.att orbfile=xa100050020.orb outfile=xa100050020.ehk
- 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.
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