1.62. doRadialVelocity

Full Name: herschel.hifi.pipeline.generic.DoRadialVelocityTask
Alias: doRadialVelocity
Type: Java Task - Java Task
Import: from herschel.hifi.pipeline.generic import DoRadialVelocityTask
Category

HIFI/Pipeline/Level 1 Pipeline

Description

Corrects the frequency for the radial velocity of the spacecraft and possibly of the source by using

a non-relativistic approach. Possible target rest frames to transform to are "HSO" (short for Herschel Space Observatory), "LSR" or "SOURCE" (for the rest frame of the source). Adopting a non-relativistic approach only the radial velocity is needed, i.e. only the component in direction of the pointing of the telescopse. This can be obtained from different sources:

  • from an object of type herschel.share.fltdyn.ephem.Ephemerides passed as 'ephem' parameter to the task;

  • from an auxiliary context passed as 'aux' parameter to the task;

  • from the datasets to be processed, in a column named 'velocity';

  • from the task parameter velocity or velocity_source - only to specify the velocity of the source relative to LSR, constant in time.

By default, a positive value entered as velocity_source parameter means that the source and S/C depart from each other (redshift). Note that a positive velocity found in the 'velocity' column (which is the velocity of the S/C w.r.t. LSR) has just the opposite effect. The 'LoFrequency' is also Doppler corrected when applying this task. In order to preserve the measured LoFrequency, the latter is copied to a new column called 'LoFrequency_measured'. Note that the comparison of LoFrequency and LoFrequency_measured allows to always return to the original HSO frame. For this to happen you can set the parameter reverse=True. You cannot repeatedly correct for different source velocities. In order to try another source velocity do the reverse correction first and appply the modified correction thereafter. The frame to transform to is by default LSR for non-SSO's and SOURCE for SSO's. in case you want to depart from this default (e.g. transform to the rest frame of the source for non-SSO's) you can specify that by setting the targetFrame' parameter. Note that in contrast to earlier versions (<=3.0) it is no longer sufficient to just set the velocity task parameter to have the spectra to the rest frame of the source.

Example

Example 1: In HIPE:
doRadialVelocity = DoRadialVelocityTask()
# apply the defauls - transform to the LSRk frame, assume that the radial velocity is contained in the spectra.
doRadialVelocity(htp=htp)
# transform back to the rest frame of the s/c, assume that the radial 
#velocity of the s/c is contained in the spectra.
doRadialVelocity(htp=htp, targetFrame = "source", velocity_source=10.0) # in km/sec
# transform back to the rest frame of the s/c
doRadialVelocity(htp=htp, reverse=True)
# transform to the rest frame of the source
doRadialVelocity(htp=htp, targetFrame = "source", aux=obs.auxiliary, velocity_source=10.0)
# transform to the rest frame of the source
doRadialVelocity(htp=htp, targetFrame = "source", aux=obs.auxiliary, velocity_source=10.0)

API details

Properties

HifiTimelineProduct htp [INOUT, MANDATORY, default=no default value]

The input timeline product.

String targetFrame [INPUT, MANDATORY, default=no default value]

The rest frame to transform to.

Double velocity_source [INPUT, OPTIONAL, default=no default value]

Velocity of the source (in km per second) used to transform to the rest frame of the source. Thewavescale is transformed to the rest frame of the source once targetFrame="source" and velocity_source is specifeid. The specified velocity is included as meta data to the datasets and the timeline product. Note that the velocity is positive if the source moves away.

Object ephem [INPUT, OPTIONAL, default=no default value]

Ephemeris object or and OrbitEphemeris-product from which the velocity information can be extracted. Once this parameter is set, the velocity information found in the ephemeris object is used to compute the radial velocity of the spacecraft wrt LSR (or the SSO rest frame) and the Doppler correction. The velocity computed and used here is added to the datasets (column name "velocity"). If velocity data has already been entered into the data this information is overwritten.

MapContext aux [INPUT, OPTIONAL, default=no default value]

Auxiliary context from which the OrbitEphemeris product can be extracted. This is used (once the 'ephem' parameter is not set) for computing the radial velocity of the spacecraft wrt LSR. For SSO's, the current OrbitEphemeris-product does not contain a all the planetary ephemeris data. If velocity data has already been entered into the data this information is overwritten.

Boolean reverse [INPUT, OPTIONAL, default=False]

If set to true all the Doppler-shift corrections applied so far are reverted (removed). The cumulative effect of all Doppler corrections can be obtained by comparing the tuned with the adjusted LO frequencies. In case only a single LO frequency column is found that task assumes that no correction has been applied so that there is nothing to revert. Since we assume that the original frame is 'HSO' (or topocentric) 'reverse=True' is equivalent to setting "targetFrame='HSO'".

See also

History

  • 2011-07-11 - melchior: : history added.
  • 2011-08-14 - melchior: : Renamed to DoRadialVelocityTask.