1.70. doVelocityCorrection

Full Name: herschel.hifi.pipeline.generic.DoVelocityCorrectionTask
Alias: doVelocityCorrection
Type: Java Task - Java Task
Import: from herschel.hifi.pipeline.generic import DoVelocityCorrectionTask

HIFI/Pipeline/Level 1 Pipeline


Corrects the frequency for the velocity of the spacecraft.

Here, a relativistic or approach is adopted except when transforming from LSR to the rest frame of the source where a non-relativistic formula is applied. By setting the parameter targetFrame you can specify what frequency scale to transform to. Once the transformation is done, the meta data field 'freqFrame' is updated accordingly. The available frames that can be transformed to are:

  • "hso" or "topocentric"

  • "geocentric"

  • "ssb" or "barycentric"

  • "lsr" or "lsrk"

  • "source"

If the 'targetFrame' parameter is not specified it is set to 'lsr' for non SSO or 'source' for SSO's. If the task succeeds the meta data item 'freqFrame' in the timeline product and the spectrum datasets is set with the target frame ("topocentric","geocentric","barycentric","lsrk","source"). At the beginning, the task checks whether the 'freqFrame'-parameter has been set and considers that as the frame the frequency scale needs to be transformed from. In case no such field is found the freqScale of the input is assumed to be the spacecraft (hso or topocentric). Depending on the initial and the target frequency frame, different velocity information is needed. Except for the velocity of the source, all this velocity information is expressed in barycentric coordinates:

  • spacecraft velocity

  • earth velocity

  • LSR velocity

This information is found in different sources:

  • in the data (spacecraft velocity) in case no 'aux' and no 'ephem' parameters has been set;

  • in the OrbitEphemerisProduct of the auxiliary context (spacecraft velocity) in case the 'aux' parameter is set to obs.auxiliary;

  • the HCSS build (velocity of earth and LSR)

  • in an ephemeris product (all SSO including the spacecraft) if the 'ephem' parameters has been set with a object of type herschel.share.fltdyn.ephem.Ephemerides

For SSO's Horizons ephemerides data is also needed for the motion of the source. - Here, an ephemerides object needs to be passed to the task. The velocity of the source (non SSO) may be expressed in different frames and/or different formulas. Actually, it is not necessarily the physical velocity of the source that is specified here but rather the redshift of the source relative to the reference frame. Depending on the formula to express the redshift, the parameter entering there has a different meaning. The available formulas to express the redshift factor:

  • optical: factor = (1+v/c)

  • radio: factor = 1 / (1-v/c)

  • redshift: factor = 1+z

  • relativistic: factor = sqrt((1+v/c)/(1-v/c))

In all cases, the parameter entering these formulas (v or z) can be passed to the task by setting the parameter 'redshift' or, equivalently, 'velocity_source'. In case no such task parameter is set and the target frame is set to 'source' a suitable parameter is looked up in the timeline product (meta data item 'redshift' or 'vlsr'). The formula to be adopted to translate the redshift parameter into a redshift factor can be specified by setting the task parameter 'redshiftType' (to optical, radio, redshift or relativistic). Again, in case no such parameter is specified a meta data parameter 'redshiftType' is looked up in the timeline product. If no redshift type information is found the default 'optical' is applied. The reference frame the redshift of the source is applied to is specified by setting the parameter 'redshiftFrame'. In case no such parameter is specified a meta data parameter 'frame' is looked up in the timeline product. If no redshift frame is specified the default 'lsr' is used. After such a redshift factor is successfully applied to the spectra the information for building it is included in the meta data.

  • 'redshift': the redshift parameter;

  • 'frame': the reference frame the redshift is expressed in;

  • 'redshiftType': type of redshift formula used to compute from the redshift parameter the redshift;

  • 'v_frame': a velocity associated with the redshift parameter computed by referring to the optical definition of the redshift.

The 3d velocity information read from the input data and used to transform the frequency scale is entered in the datasets:

  • The velocity of the spacecraft in barycentric coordinates as three columns in the datasets (velocity_hso_k).

  • For SSO's, the velocity of the source in barycentric coordinates as three columns in the datasets (velocity_sso_k).

The task can be applied for spectra being expressed on the IF scale or the scale frequency scale. In order to consistently transform the spectra from IF to sky frequencies an adjusted LO frequency is added into the datasets. Actually, the original 'LoFrequency'-column is copied to a new column 'LoFrequency_measured' and the original column is adjusted. The ratio of 'LoFrequency' and 'LoFrequency_meas' corresponds to the multiplicative correction factor applied between the current reference frame the frequencies are expressed at and the reference frame of the spacecraft. For frequency switch obsering modes, the correction factor applies also to the 'LoThrow' column and, to preserve the original throw information, a copy 'LoThrow_measured' is created.


Example 1: In HIPE:
from herschel.hifi.pipeline.generic import DoVelocityCorrectionTask
doVelocityCorrection = DoVelocityCorrectionTask()
# apply (relativistic) Doppler shifts for the motion of the S/C relative to LSR, 
use the velocity information included therein:
doVelocityCorrection(htp=htp, targetFrame="LSR", aux=obs.auxiliary)
# bring it back to the HSO (spacecraft) frame:
doVelocityCorrection(htp=htp, targetFrame="HSO")
# take the velocity of S/C and earth from an ephemerides object:
# given the two files orbitFile,ephemFile
ep = herschel.share.fltdyn.ephem.Ephemerides(orbitFile,ephemFile)
doVelocityCorrection(htp=htp, ephem=ep)
# take the velocity of S/C from an ephemerides object
# and use the velocity_source as the velocity relative to LSR (in km/sec)
doVelocityCorrection(htp=htp, targetFrame="source",ephem=ep, redshift=30,redshiftFrame="LSR", redshiftType="radio"))

API details


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

The input timeline product.

String targetFrame [INPUT, OPTIONAL, default='LSR']

The target frame to transform the spectra to. Possible values are (case-insensitive)

  • hso or topocentric: the rest frame of the spacecraft

  • geocentric: the rest frame of the earth

  • ssb or barycentric: solar system barycenter

  • lsr or lsrk: Local standard of rest (J2000) - assumed that SSB moves with 20.0 km/sec towards (18h03m50.29s, +30d00'16.8") wrt LSR

  • SOURCE: Rest frame of the source.

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

Ephemeris object or 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 Doppler correction and the 3d-velocity included in the datasets (columns 'velocity_x'). If this parameter is not set the task assumes that the required velocity information is already available within the data.

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

Input parameter for computing the redshift when transforming to the rest frame of the source. It is either

  • a velocity (in km per second) when using redshiftType=optical or redshiftType=radio

  • a redshift parameter z when using redshiftType=redshift

This parameter is expressed in a reference frame given by redshiftFrame. This parameter is included in the meta data of the datasets and the timeline product as "redshiftFrame". Note that this parameter (similarly redshiftType, redshiftFrame) is only applied in observations of non-SSO's.

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

Velocity of the source used when computing the redshift if targetFrame='source'.

String redshiftType [INPUT, OPTIONAL, default="radio"]

Formula used to compute the redshift from the redshift parameter (v or z). You have the following possibilities:

  • "optical": redshift factor = 1+v/c (i.e. redshift parameter v)

  • "radio": redshift factor = 1/(1-v/c) (i.e. redshift parameter v)

  • "redshift": redshift factor = 1+z (i.e. redshift parameter z)

This parameter is included in the meta data of the datasets and the timeline product as "redshiftType".

String redshiftFrame [INPUT, OPTIONAL, default='lsr' or 'source' (for SSOs)]

The reference frame the redshift parameter is expressed in:

  • hso or topocentric

  • geocentric

  • ssb, ssbc, barycentric or heliocentric (as in HSPOT)

  • lsr or lsrk

  • source

This parameter is included in the meta data of the datasets and the timeline product as "redshiftFrame".

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. If velocity data has already been entered into the data this information is overwritten.

PipelineConfiguration params [INPUT, OPTIONAL, default=no default value]

Pipeline configuration parameters that can be passed to the task.

Boolean ignore [INPUT, OPTIONAL, default=no default value]

If set to True task is not executed.

See also


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