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