NAME

USAGE

DESCRIPTION

The coordevt task converts event coordinates in a FITS file from one system to another; the task requires two input files. The first is a file with an existing EVENTS extension, containing a TIME column and a coordinates column. The second file is a telescope definition (teldef) file containing a COORDn keyword for each coordinate system present in the event file, and a TRTYPEn keyword defining the transformation between two pairs of existing coordinate systems. The teldef file also contains additional keywords describing each existing coordinate system (value of first pixel, scale, etc.).

The coordevt task is mission-independent and can currently process event files associated with the Swift, Suzaku, Hitomi, and XRISM missions. Please note that the default values for most of the hidden parameters defined below are mission-specific. They have been defined for Hitomi, so alternatives to some of the defaults may need to be used for the other missions that this task supports.

The coordevt task converts the lowest level coordinates present in the two input files to the highest level coordinates present in the teldef file or vice-versa (from the highest to the lowest). The transformations are carried out using double-precision floating-point variables, but the calculated coordinates are converted to integers in the output file. If the hidden parameters ('inclfloatcol' and 'inclfloatskycol') are set to yes, the task adds additional columns of unrounded event coordinates to the output file. For any transformation involving SKY coordinates, an attitude file, specified by the hidden parameter 'attfile', is required. The format of this file is specified by the hidden parameter 'attform'. The coordevt task supports attitude files with the attitude provided as either quaternions or Euler angles, but the file must contain a TIME column. For any transformation to a coordinate system lower than SKY coordinates, randomization of each event coordinate within a pixel is controlled by the value of the RANCOORD keyword in the teldef file (see description of the 'randomize' parameter below). An additional auxiliary file is required in some cases, for example, a transformation from the Hitomi HXI RAW to ACT coordinate systems. This file is specified by the hidden parameter 'dattfile' and is required to be in quaternion format.

PARAMETERS

infile = events_in.fits [filename]

Name of the input file, which must have an EVENTS extension containing a TIME column and the coordinates to be transformed.

outfile = events_out.fits [filename]

Name of the output file. This file is a copy of 'infile' with updated relevant keywords and values in the coordinate columns of the EVENTS extension. If the 'clobber' parameter is set to yes, and the parameter 'outfile' is identical to that of 'infile', the input file is updated. If destination system columns do not exist in the input file, they are created in the output file. If columns corresponding to a destination coordinate system are present in the input file, then the values are overwritten in the output file. Any coordinate system in the chain before the 'startsys' is copied, but systems after the 'stopsys' are either left intact, or filled with a null value, depending on the value of the parameter 'blankcol'. A null value is also written if the calculated value of a destination coordinate is outside the destination coordinate system range specified in the teldef file. All input file columns unrelated to coordinate transformations are unchanged and preserved in 'outfile'.

teldeffile = CALDB [string CALDB|file name]

Name of the telescope definition (teldef) file specifying the coordinate systems and transformation properties. If the parameter is set to CALDB, a teldef file for the telescope and instrument specified by the TELESCOP and INSTRUME keywords in 'infile' is read from the calibration database.

(attfile = NONE) [string NONE|IDENTITY|file name]

Name of the attitude file used in the conversion to SKY coordinates. This keyword is required for any conversion involving SKY coordinates. The attitude may be provided as either quaternions or z-y-z Euler angles, but the attitude format in the 'attfile' must match the value of the 'attform' parameter. The special value 'attfile=IDENTITY' causes the identity attitude to be substituted for actual attitudes. This attitude is represented by the quaternion [0,0,0,1] or Euler angles [0,0,0] and is equivalent to the pointing 'ra=0.0', 'dec=+90.0', 'roll=+90.0'. The 'ra' and 'dec' parameters should normally be set to 0.0 and +90.0 for the 'attfile=IDENTITY' option. In addition, in order to make SKY coordinates equal to the next-lower coordinates (typically FOC), the 'roll' parameter must be set to +90. Other values of 'roll' rotate the SKY coordinates counterclockwise with respect to FOC by roll-90 degrees. For example, setting 'roll=0.0' rotates the SKY counterclockwise by -90 degrees (clockwise by 90 degrees) with respect to FOC, such that SKYX = -FOCY and SKYY = FOCX. The 'attform' parameter is ignored if 'attfile=IDENTITY'.

(dattfile = NONE) [string NONE|IDENTITY|file name]

Name (or @list-of-names) of the auxiliary or delta attitude files necessary for some coordinate transformations. A mathematical type for each coordinate transformation is specified in the teldef file with a keyword of the form TRTYPEn. One of the possible values for these keywords is SKYATT, which signifies that the orientation of the instrument is part of the transformation. For any SKYATT transformation not involving the SKY coordinate system, a delta attitude file is required to carry out the computation. The attitudes tabulated in this file must be in quaternion format. The special value 'dattfile=IDENTITY' causes the identity quaternion to be used for all delta attitudes.

(orbfile = NONE) [string]

Name of the FITS orbit file containing the satellite orbital velocity as a function of time. This file is only necessary when the parameter 'orbaber' is set to yes, and an orbital aberration correction is required. The orbit format in the 'orbfile' file must match the value of the 'orbform' parameter.

(startsys = LOWEST) [string]

Name of the starting coordinate system of the requested conversion. When 'startsys' is set to LOWEST, the conversion begins with the lowest level system present, usually RAW, in the teldef file, as identified by the keyword COORD0.

(stopsys = HIGHEST) [string]

Name of the ending coordinate system of the conversion. If 'stopsys' is set to HIGHEST, the coordinate transformation chain ends with the highest level system, usually SKY.

(annaber = no) [string yes|no|invert]

The 'annaber' parameter allows for the correction of the annual aberration. If set to no, a correction is not applied. If set to yes, the effects of annual aberration are taken into account when calculating the SKY coordinate values. If set to invert, the task multiplies the annual aberration correction by -1 before applying it. The invert option is only used for debugging. Annual aberration is the apparent change in the direction of incident light due to the Earth's orbit around the Sun. This is at most a ~20.49 arcsec effect.

(followsun = no) [boolean yes|no]

If set to yes, 'followsun' uses the event time to compute the aberration for each event. This uses the MJDREF keyword (or pair of MJDREFI and MJFREFF keywords) along with the TIME column of the event extension to calculate absolute event times. If set to no, the aberration is calculated using the time given by the MJDOBS keyword for all events. Setting this to no is acceptable, except for very long observations.

(orbaber = no) [string yes|no|invert]

The 'orbaber' parameter allows for the correction of the orbital aberration. If set to no, the orbital aberration is not corrected. If set to yes, the effects of orbital aberration are taken into account when calculating the SKY coordinates, provided an input orbit file is specified using the parameter 'orbfile'. If set to invert, the task multiplies the orbital aberration correction by -1 before applying it. The invert option is only used for debugging. Orbital aberration is the apparent change in the direction of incident light due to the satellite's orbit around the Earth. For a satellite in low-earth orbit this is at most a ~5 arcsec effect.

(attinterp = LINEAR) [string LINEAR|CONSTANT]

Spacecraft attitude interpolation method. When this parameter is set to LINEAR, the attitude is linearly interpolated to the event time. When it is set to CONSTANT, the attitude is taken from the nearest attitude record.

(dattinterp = LINEAR) [string LINEAR|CONSTANT]

Delta attitude interpolation method. When this parameter is set to LINEAR, the delta attitude is linearly interpolated to the event time. When it is set to CONSTANT, the delta attitude is taken from the nearest attitude record.

(attdt = 32.) [double]

Maximum time interval [s] allowed to extrapolate the spacecraft attitude before the first or after the last row in the attitude file. Events beyond this time margin have their coordinates set to a null value. The parameter can also be used to control how gaps in the attitude data are handled (see 'checkattgap').

(dattdt = 0.5) [double]

Maximum time interval [s] allowed to extrapolate the auxiliary attitude (specified by the parameter 'dattfile') before the first or after the last row in the attitude file. Events beyond this time margin have their coordinates set to a null value. The parameter can also be used to control how gaps in the delta attitude data are handled (see 'checkdattgap').

(chkattgap = no) [boolean yes|no]

Used only for interpolation. If set to no, always interpolate the attitude at the event time. If set to yes, event times that fall within the sky attitude time range, but not within an amount 'attdt' of the nearest attitude time are set to NULL.

(chkdattgap = yes) [boolean yes|no]

Used only for interpolation. If set to no, the task interpolates the attitude at the event time. If set to yes, event times that fall within the delta attitude time range, but not within an amount 'dattdt' of the nearest attitude time are set to NULL.

(attext = ATTITUDE) [string]

Name of the FITS attitude file extension containing satellite attitude data.

(attcol = QPARAM) [string]

Name of the FITS column containing attitude values as a vector in the 'attext' extension of the attitude table.

(attform = QUAT) [string QUAT|EULER]

Format of the attitude table. Two formats are supported: the QUAT format is a quaternion [x, y, z, real] and the EULER format is a z-y-z Euler angle trio [phi, theta, psi] in degrees.

(orbext = ORBIT) [string]

Name of the FITS orbit file extension containing satellite orbit data.

(orbcol = VELOCITY) [string]

Name of the FITS columns containing orbital velocity values in the 'orbext' extension of the orbit file. If 'orbform=VECTOR', 'orbcol' is a string containing the name of the FITS column of velocity vectors. If 'orbform=COMPONENTS', 'orbcol' is a string containing three comma-separated column names, specifying in order the x, y, and z components of the orbital velocity (e.g., 'orbcol=VX,VY,VZ'). If 'orbform=KEPLERIAN', 'orbcol' is a string containing six comma-separated column names, specifying the Keplerian orbital elements semi-major axis, eccentricity, inclination, longitude of the ascending node, argument of periapsis, and mean anomaly at epoch, respectively (e.g., 'orbcol=A,E,I,AN,AP,MA').

(orbform = VECTOR) [string VECTOR|COMPONENTS|KEPLERIAN]

The format in which the orbital velocity is provided in the orbit file. For the VECTOR format, the velocity is provided as a vector column with three elements (vx, vy, and vz in the Earth-Centered Inertial (ECI) system). For the COMPONENT format, the velocity in the ECI system is provided in three separate columns. For the KEPLERIAN format, six separate columns contain the six Keplerian elements for the orbit solution.

(randomize = teldef) [string teldef|yes|no]

If this parameter is set to no, coordevt assumes that each event occurred at the center of its coordinate pixel. If 'randomize=teldef', randomization depends on the keyword RANCOORD in the teldef file (RANCOORD = NONE disables randomization). If 'randomize=yes', the coordinates from system 'randsys' (see below) onward are calculated assuming a random location within the 'randsys' system pixel. This parameter only controls randomization in transformations previous to the transformation to the SKY system.

(seed = 2) [integer]

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

(randsys = teldef) [string]

Name of the starting coordinate system for which randomization is performed, if enabled by the 'randomize' parameter. If 'randsys=teldef', then the value of the RANCOORD keyword in the teldef file specifies this system.

(randscalesys = teldef) [string]

Name of the coordinate system that determines the scale of the randomization. The position of each event is randomized over an area the size of a pixel in the specified coordinate system. If 'randscalesys=teldef', the value of the RAN_SCAL keyword in the teldef file is used; but if the RAN_SCAL keyword does not exist in the teldef file, the value of the 'randsys' parameter is used. In general, 'randsys' and 'randscalsys' do not have to be the same coordinate system.

(infileext = EVENTS) [string]

Name of the 'infile' extension containing the event table.

(timecol = TIME) [string]

Name of the FITS column in the event table containing time values.

(inclfloatcol = no) [boolean yes|no]

If this parameter is set to yes, an additional column of unrounded coordinate values is included in the output event file for each coordinate of each system after the 'startsys' system. Enabling this parameter is useful for stringing multiple coordevt runs together (e.g., convert RAW to DET in one run and DET to SKY in a second run) without loss of precision due to the normal rounding of coordinates. Use 'startwithfloat' set to yes for runs after the first so that the unrounded coordinates from the previous coordevt run are used as the starting coordinate values for a subsequent run. Rounded coordinate columns are written regardless of the value of this parameter. Unrounded SKY coordinate columns are included if either 'inclfloatcol' or 'inclfloatskycol' is set to yes.

(inclfloatskycol = no) [boolean yes|no]

If this parameter is set to yes, an additional column of unrounded coordinate values is included in the output event file for each SKY coordinate. Rounded SKY coordinate columns are included regardless of the value of this parameter. Unrounded SKY coordinate columns are included if either 'inclfloatcol' or 'inclfloatskycol' is set to yes.

(floatcolsuffix = _FLOAT) [string]

This parameter sets the suffix used in all unrounded coordinate column names. For example, if the rounded coordinate column name is DETX and 'floatcolsuffix=_FLOAT', then the corresponding unrounded coordinate column name is DETX_FLOAT. This parameter is used only when either 'inclfloatcol' or 'inclfloatskycol' is set to yes.

(startwithfloat = no) [boolean yes|no]

This parameter is set to yes in order to use the unrounded coordinate column values (e.g., floating-point values from DETX_FLOAT and DETY_FLOAT columns) as the starting coordinate columns. The 'inclfloatcol' parameter must be set to yes for 'startwithfloat' to have an effect. When either 'inclfloatcol' or 'startwithfloat' is disabled, rounded coordinate values (e.g., integer values from DETX and DETY columns) are used as the starting coordinate values. This parameter enables multi-step transformations to be done in two separate runs of coordevt.

(blankcol = yes) [boolean yes|no]

This parameter controls the treatment of coordinate columns in the output file for coordinate systems higher than 'stopsys'. The behavior depends on whether such columns already exist in the input file. If they are present, and 'blankcol=yes', they are filled with null values. If they are absent, and 'blankcol=yes', they are created and filled with null values. If they are present, and 'blankcol=no', they are not changed. If they are absent, and 'blankcol=no', they are not created.

The following seven parameters are used to specify default null values in the processing.

Null values may appear for several reasons, including the following:

1. The event time cannot be matched to a row of an attitude file within the time margin.
2. The coordinate columns subsequent to the coordinate system specified by 'stopsys' coordinates are set to NULL if 'blankcol=yes'.
3. If an output column already exists in the input file and TNULL for that column is specified in the event file header, the existing TNULL keyword is copied to the output column. If however, the output column does not exist in the input file or the column exists, but does not have an associated TNULL keyword, then the appropriate null value parameter is used.

(btnull = 255) [integer]

This parameter sets the null integer value for any output unsigned byte (TFORM = 1B) coordinate columns that are missing, or lack the TNULL keyword in the input event file.

(itnull = -999) [integer]

This parameter sets the null integer value for any output short integer (TFORM = 1I) coordinate columns that are missing, or lack the TNULL keyword in the input event file.

(jtnull= -999) [integer]

This parameter sets the null integer value for any output long integer (TFORM = 1J) coordinate columns that are missing, or lack the TNULL keyword in the input event file.

(ktnull = -999) [integer]

This parameter sets the null integer value for any output long integer (TFORM = 1K) coordinate columns that are missing, or lack the TNULL keyword in the input event file.

(sbtnull = 255) [integer]

This parameter sets the null integer value for any output signed byte (TFORM = 1B with TZERO = -128) coordinate columns that are missing, or lack the TNULL keyword in the input event file. The specified null value is the value to be stored in the FITS file, not the value in the signed domain.

(uitnull = -999) [integer]

This parameter sets the null integer value for any output unsigned short integer (TFORM = 1I with TZERO = 32768) coordinate columns that are missing, or lack the TNULL keyword in the input event file. The specified null value is the value to be stored in the FITS file, not the value in the unsigned domain.

(ujtnull = -999) [integer]

This parameter sets the null integer value for any output unsigned long integer (TFORM = 1J with TZERO = 2147483648) coordinate columns that are missing, or lack the TNULL keyword in the input event file. The specified null value is the value to be stored in the FITS file, not the value in the unsigned domain.

(ra = -999.99999) [double]

The right ascension [degrees] of the center of the SKY coordinate images. If 'ra' is outside the range 0 to 360 degrees inclusive, as is the case for the default value, the 'ra' value is read from the event header of the input file. First the keyword RA_NOM is searched, then RA_PNT. If neither keyword is found, coordevt exits with an error.

(dec = -999.99999) [double]

The declination [degrees] of the center of the SKY coordinate images. If 'dec' is outside the range -90 to +90 degrees inclusive, as is the case for the default value, the 'dec' value is read from the event header of the input file. First the keyword DEC_NOM is searched, then DEC_PNT. If neither keyword is found, coordevt exits with an error.

(roll = 0.0) [double]

The roll angle [degrees] about the center of the SKY coordinate system. The roll angle is the angle measured counterclockwise from Celestial North to the positive SKY Y axis.

(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. Transformation of Hitomi/SXI RAW coordinates to ACT, DET, and FOC. For this transformation, there is no need for an attitude file. The teldef file is given specifically; CalDB is not used. Without specifying 'stopsys=FOC', the parameter 'stopsys' would have the default value SKY, and an attitude file would be required. Because the default for 'blankcol' is yes, and the SKY coordinate system is higher than FOC, the SKY coordinates are filled in with null.

   coordevt infile=ah100044010sxi_p0112004e0_cl.evt outfile=ah-sxi-coordevt-out.evt \
      teldeffile=ah_sxi_teldef_20140101v003.fits stopsys=FOC clobber=yes

2. Transformation of some Suzaku data (taking an example from the archive, sequence number 508011020) from RAW to SKY. The user needs to specify the format ('attcol' and 'attform') because the attitude file for this mission is not in quaternion format, which is the default.

    
   coordevt attfile=ae508011020.att attform=EULER attcol=EULER startsys=RAW stopsys=SKY clobber=yes \
      infile=ae508011020xi0_0_3x3n066l_cl.evt outfile=ae508011020 teldeffile=ae_xi0_teldef_20080303.fits

3. Basic transformation from RAW to SKY coordinates, using the teldef file from the calibration database. The pointing direction is set with the 'ra', 'dec', and 'roll' parameters.

    
   coordevt infile=input.fits outfile=outfile.fits teldeffile=CALDB attfile=attitude.fits \
      ra=0.0 dec=90.0 roll=90.0 clobber=yes

4. Transformation from ACT to FOC coordinates, using a user-specified teldef file. Since there is no transformation to SKY, an attitude file does not need to be provided.

    
   coordevt infile=input.fits outfile=outfile.fits teldeffile=teldef.fits \
      startsys=ACT stopsys=FOC clobber=yes

5. Transformation from SKY to RAW coordinates, using the teldef file from the calibration database. The pointing direction is read from keywords in 'infile'.

   coordevt infile=input.fits outfile=outfile.fits teldeffile=CALDB attfile=attitude.fits \
      startsys=HIGHEST stopsys=LOWEST clobber=yes

6. Transformation from RAW to SKY coordinates, using the teldef file from the calibration database. The pointing direction is read from keywords in 'infile'. Floating point columns are output to 'outfile'. Randomization is disabled and both annual and orbital aberration are enabled. This requires the user to provide an orbit file. The orbit is specified by Keplerian orbital elements with column names A, E, I, AN ,AP, and MA. The 'followsun' option is also enabled.

   coordevt infile=input.fits outfile=outfile.fits teldeffile=CALDB attfile=attitude.fits \
      orbfile=orbit.fits orbform=keplerian orbcol="A,E,I,AN,AP,MA" inclfloatcol=yes \
      randomize=no annaber=yes followsun=yes orbaber=yes clobber=yes

7. Example of a two-stage transformation. In the first pass, coordinates are transformed from RAW to DET, and floating-point values are saved. In the second pass, the floating-point values are used as the starting point to transform from DET to SKY.

   coordevt infile=input.fits outfile=outfile1.fits teldeffile=CALDB stopsys=DET inclfloatcol=yes clobber=yes
   coordevt infile=outfile1.fits outfile=outfile2.fits teldeffile=CALDB attfile=attitude.fits startsys=DET \
      inclfloatcol=yes startwithfloat=yes clobber=yes

8. Transformation in which the input files have non-standard formats, extensions, and column names. A user-named log file is specified for capturing a log of the run.

   coordevt infile=input.fits outfile=input.fits teldeffile=CALDB attfile=attitude.fits orbfile=orbit.fits \
      clobber=yes annaber=yes followsun=yes orbaber=yes infileext=MY_EVENTS timecol=MY_TIME \
      attext=GOOD_ATTITUDE attcol=WHATEVER attform=EULER orbext=SATELLITE orbcol="V1,V2,V3" orbform=COMPONENTS \
      logfile=special.log 

9. Transformation using the identity attitude.

   coordevt infile=input.fits outfile=output.fits teldeffile=CALDB attfile=IDENTITY clobber=yes

SEE ALSO

NOTES

The design of this task is based on coordinator in the attitude package.

LAST MODIFIED