NAME

aberposition - Correct coordinates for aberration effects.

USAGE

aberposition ra dec time

DESCRIPTION

'aberposition' is a mission-independent tool that corrects the coordinates for aberration effects.

The task requires an initial RA and Dec (given in degrees) and a time (UTC format). To correct for orbital aberration, an orbit file is necessary. If no orbit file is specified, the correction includes only the annual correction. The task outputs the corrected RA and Dec in the 'outra' and 'outdec' parameters.

PARAMETERS

ra [real]
Input Right Ascension in degrees. This must be a value between 0 and 360.

dec [real]
Input Declination in degrees. This must be a value between -90 and +90.

time [string]
Input UTC date and time in the format "yyyy-mm-ddThh:mm:ss", e.g. "2014-08-01T12:00:00".

(orbfile = NONE) [string]
Name of the orbit file used to retrieve spacecraft velocity in Earth-Centered Inertial (ECI) Cartesian coordinates. Required for orbital aberration corrections

(annaber = no) [string]
'annaber' enables annual aberration correction. 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.

(orbaber = no) [string]
'orbaber' enables orbital aberration correction. 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 and an orbit file is required (parameter 'orbfile'). 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.

(leapsecfile = REFDATA) [string]
Name of the FITS file containing the table of leap seconds. This file is needed in order to accurately convert UTC to the time system used in the orbit file. The values for this flag can be CALDB, REFDATA or a filename If the parameter is set to CALDB, the default, the file is read from the calibration database; if REFDATA, the file is accessed in the reference data area of the HEASoft installation.

(orbext = ORBIT) [string]
Name of the FITS binary table extension of the orbit file containing the velocity vectors.

(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]
Format of the orbital velocity column or columns 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.

(outra = 0.0) [real]
The adjusted value of Right Ascension is stored in this parameter in the .par file on exit from the tool.

(outdec = 90.0 ) [real]
The adjusted value of Declination is stored in this parameter in the .par file on exit from the tool.

(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. Derive the annual aberration for a given pointing and time using the leapsecond file extracted from CALDB. Chatter set to 2 prints out the output.

      aberposition ra=161.2649625 dec=-59.68451667 time=2009-06-10T01:49:30 
      chatter=2

2. Derive the annual and orbital aberration for a given pointing and time. The orbit file has the orbit velocity stored in three separate columns.

      aberposition ra=161.2649625 dec=-59.68451667 time=2009-06-10T01:49:30 
      leapsecfile="CALDB" orbaber=yes orbfile="orbit.fits" orbcol="VX,VY,VZ" 
      orbform=COMPONENTS chatter=2

SEE ALSO

aberrator, aberattitude,

LAST MODIFIED

February 2016