NAME

USAGE

DESCRIPTION

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

'coordevt' converts the lowest level coordinate 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 tool adds additional columns of unrounded event coordinates to the output file.
For any transformation involving SKY coordinate, an Attitude File, specified by the hidden parameter 'attfile', is required. The format of this file is specified by the hidden parameter 'attform'. 'coordevt' 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, each event coordinate is randomized within the pixel following the RANCOORD keyword in CALDB
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'. The format of this 'dattfile" is fixed and must be in quaternion format.

PARAMETERS

infile [string]

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

outfile [string]

Name of the output file. This file is a copy of the 'infile' with updated relevant keywords and values in the coordinate columns of the event 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 also 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 the outfile.

teldeffile [string]

Name of the Telescope Definition (TelDef), specifying the coordinate systems and transformation properties. If the parameter is set to CALDB, the default, a TelDef file for the telescope and instrument specified by the TELESCOP and INSTRUME keywords in the infile is read from the calibration database. The tool supports TelDef file format versions 0. through 0.2.

(attfile = NONE) [string]

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 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' rotates 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]

Name (or @list-of-names) of the auxiliary or "delta" attitude files needed for some coordinate transformations. The delta attitude file must be in quaternion format. A delta attitude file must be provided for each coordinate transformation of type 'SKYATT' in the teldef file, with the exception of the transformation to the SKY system. 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 needed when the parameter 'orbaber' is set to yes and an orbital aberration correction is required . Two orbit formats (VECTOR and COMPONENT) are supported. The format VECTOR is applied to Swift while the format COMPONENT is valid for Suzaku. 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 default, the conversion begins with the lowest level system present, usually 'RAW', in the teldef file as identified by the parameter 'COORD0'.

(stopsys = HIGHEST) [string]

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

(annaber = no) [string]

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

(followsun = no) [boolean]

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 (DEFAULT), 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]

'orbaber' allows to correct for orbital aberration. The allowed setting are yes, no or invert. If set to no, the default, 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', multiplies the orbital aberration correction by -1 before applying it. The 'invert' option is only used for debugging. Orbital aberration is the apparent bending of 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]

Spacecraft attitude interpolation method: LINEAR or CONSTANT. When this parameter is set to LINEAR (the default), 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]

Delta attitude interpolation method: LINEAR or CONSTANT. When this parameter is set to LINEAR (the default), 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) [real: 32.0]

Maximum time interval (in seconds) 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.

(dattdt) [real: 0.5]

Maximum time interval (in seconds) allowed to extrapolate the auxiliary attitude (specified by the keyword '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.

(chkattgap = no) [boolean]

Used only for interpolation. If set to no (the default), 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 the 'attdt' of the nearest attitude time is be set to null.

(chkdattgap = no) [boolean]

Used only for interpolation. If set to no (the default) the task always interpolates the attitude at the event time. If set to yes, event times that fall within the delta attitude time range but not within the 'dattdt' of the nearest attitude time is be 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)

Format of the attitude table. Two formats are supported. The QUAT format is a quaternion [x, y, z, real]. 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(s) of the FITS column(s) containing orbit values in the orbext extension of the orbit file. This parameter is linked to the parameter 'orbform'. The only acceptable values for 'orbcol' are: VELOCITY, VECTOR or COMPONENTS. The default is 'VELOCITY'. If 'orbform=VECTOR', then 'orbcol' is the name of the single FITS column containing the orbit values as a vector. If 'orbform=COMPONENTS', then 'orbcol' must be a string containing three comma-separated column names, specifying in order the X, Y and Z components of the orbital velocity. These columns must be scalar. Velocity must be in km/s in an Earth-Centered Inertial system.

(orbform = VECTOR) [string]

The format in which the orbital velocity is provided in the orbit file. Three formats are supported. For the VECTOR format (DEFAULT), the velocity is provided as a vector column with three elements (X, Y and Z in Earth-Centered Inertial (ECI) system). For the COMPONENT format, the velocity is provided in three separate columns. For the KEPLERIAN format, the velocity is derived from the six provided Keplerian element columns.

(randomize = TELDEF) [string]

If this parameter is set to 'no', 'coordevt' assumes that each event occurred at the center of its coordinate pixel. If 'randomize=TELDEF', the default, 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 is 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 = 0) [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, as long as randomization is enabled by the 'randomize' parameter. If 'randsys=TELDEF', the value of the RANCOORD keyword (if present)in the TELDEF file specifies this system.

(randscalesys = TELDEF) [string]

Name of the coordinate system whose pixels determine the size of the randomization if randomization is enabled by the 'randomize' parameter. If 'randscalesys=TELDEF', the value of the 'RAN_SCAL' keyword, if it exists, in the TELDEF file is used. If the 'RAN_SCAL' keyword does not exist in the TELDEF file, the value of the 'randsys' parameter is used. 'randsys' and 'randscalsys' may not 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]

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 of 'inclfloatcol' or 'inclfloatskycol' is set to 'yes'.

(inclfloatskycol = no) [boolean]

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 of 'inclfloatcol' or 'inclfloatskycol' is set to 'yes'.

(floatcolsuffix = _FLOAT) [string]

This parameter sets the suffix used in all unrounded coordinate column names. 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 of 'inclfloatcol' or 'inclfloatskycol' is set to 'yes'.

(startwithfloat = no) [boolean]

This parameter is set to 'yes' 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 of 'inclfloatcol' or 'startwithfloat' is disabled, rounded coordinate values (e.g., integer values from DETX and DETY columns) are used as the starting coordinate values. Enabling this parameter is used for debugging.

(blankcol = yes) [boolean]

This parameter is set to 'yes' to fill the coordinate columns after the 'stopsys' coordinate system with NULL values. If blankcol is set to no, such columns is not changed. The behavior is somewhat different depending on what coordinate columns already exist in the input file. If columns for coordinates beyond the 'stopsys' coordinate system exist in the input file, then when 'blankcol=yes', their values are replaced with NULL values and when 'blankcol=no', their values are copied to the output file unchanged. If, however, such columns do not already exist in the input file, then they are created and filled with NULL values when 'blankcol=yes', but not created if 'blankcol=no'.

The following seven parameters are used to specify default null value 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' is enabled 3. If an output column already exists in the input file and TNULL for that column is specified in the event file header, then 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.000) [real]

The Right Ascension in decimal degrees of the center of the SKY coordinate images. If ra is outside 0 <= ra <= 360 deg, as with 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, then coordevt exits with an error.

(dec = -999.000) [real]

The declination in decimal degrees of the center of the SKY coordinate images. If ra is outside -90 <= dec <= +90 deg, as with 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, then coordevt exits with an error.

(roll = 0.0) [real]

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

(buffer = -1) [integer]

Rows to buffer (-1=auto, 0=none, >0=numrows).

(clobber = no) [boolean]

Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]

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]

Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]

Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]

Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string]

Mode to query the parameter file. Acceptable values include: "ql (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

1. Transformation of Hitomi SXI data from RAW to FOC coordinates. For this transformation, there is no need for an attitude file. The teldef file is given specifically in this example and not using CALDB. Note that without specifying stopsys=FOC, the default would be "SKY" and an attitude file would be required.

coordevt infile=ah020150521sxi_a003030201.evt.gz outfile=ah-sxi-coordevt-out.evt
telfedfile="caldb/data/hitomi/sxi/bcf/teldef/ah_sxi_teldef_20140101v08.fits" 
stopsys=FOC  clobber=yes

2. Transformation of Suzaku data (taking an example from the archive, observation number ae508011020)from RAW to SKY. Users need to specify the format (flags attcol and attform) because the attitude file for this mission is not in the quaternion format (the default for Hitomi) assumed otherwise.

    
coordevt attfile=ae508011020.att attform=EULER attcol=EULER startsys=RAW 
stopsys=SKY clobber=yes infile=./508011020/xis/event_cl/ae508011020xi0_0_3x3n066l_cl.evt
outfile=ae508011020  teldeffile=./caldb/data/suzaku/xis/bcf/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 keywords.

    
      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 need not 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 the 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 the infile. Floating point columns are output to the outfile. Randomization is disabled and both annual and orbital aberration are enabled. This requires the user to provide an orbit file. The followsun option is also enabled.

      coordevt infile="input.fits" outfile="outfile.fits" teldeffile="CALDB" 
      attfile="attitude.fits" orbitfile="orbit.fits" inclfloatcol=yes randomize=no 
      annaberration=yes followsun=yes orbaberration=yes clobber=yes

       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

       coordevt infile="input.fits" outfile="input.fits" teldeffile="CALDB" 
       attfile="attitude.fits" orbitfile="orbit.fits" clobber="yes" annaberration=yes 
       followsun=yes orbaberration=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" 

       coordevt infile="input.fits" outfile="output.fits" teldeffile="CALDB" 
       attfile="IDENTITY" ra=0.0 dec=90.0 roll=90.0

SEE ALSO

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

LAST MODIFIED