Chapter 18. Unit conversions

Table of Contents

18.1. Converting to velocity and other frequency scales or frames
18.1.1. Changing frequency scale to USB, LSB, IF or velocity
18.1.2. Use of the Local Oscillator (LO) Frequency
18.1.3. Changing frequency rest frame with doVelocityCorrection
18.1.4. The meaning of velocities found in data and metadata
18.2. Flux conversions

Last updated: 6 February, 2015

18.1. Converting to velocity and other frequency scales or frames

18.1.1. Changing frequency scale to USB, LSB, IF or velocity

The "x-axis" of spectra can be converted into other units (frequency, velocity, wavelength) using the general task, convertWavescale. The convertWavescale task uses the RADIO convention in converting to or from velocity.

There is also a task specifically for HIFI data, the ConvertFrequencyTask, which works on a HifiSpectrumDataset and on a HifiTimelineProduct. This can be used to convert between the USB, LSB, and IF scale and also to convert to velocity.

Converting Frequency Scales.

Assuming spectrum is the variable name for a HifiSpectrumDataset with the frequency scale of the data expressed as IF frequencies, you can convert to the lower sideband frequency scale as follows:

cft=ConvertFrequencyTask()
cft(sds=spectrum,to="lsbfrequency")

Of course, it is also possible to convert to the upper sideband. To achieve this, the keyword is "usbfrequency".

cft(sds=spectrum, to='usbfrequency')

To convert back to the IF, use:

cft(sds=spectrum, to='frequency')

The ConvertFrequencyTask works equally well on the HifiTimelineProduct itself. In this case, all the internal HifiSpectrumDatasets are converted. Note that this is not something you should do in the early stages (i.e. before Level 0.5) of the HIFI pipeline. For example, on a Level 1 HifiTimelineProduct:

cft=ConvertFrequencyTask()
cft(htp=hifitimelineproduct, to='frequency')
[Note] Note

Direct application of the ConvertFrequencyTask changes the data listed in the spectrum. Conversion back to the original IF scale is possible, just use the to ='frequency' option.

Conversion to Velocity.

The ConvertFreqencyTask also works to convert the frequency scale to a velocity scale once given the reference frequency. By default, the RADIO velocity convention is used, but the OPTICAL and RELATIVISTIC conventions are available too.

cft=ConvertFrequencyTask()
cft(sds=spectrum,to='velocity', reference=576.268, inupper=False)

In the above example, you need to specify the reference frequency in GHz (the rest frequency of the line, for example). You also need to specify whether this reference frequency is for the upper (inupper =True) or lower (inupper =False) sideband. The 'inupper' parameter is always used, even for taking a spectrum already in USB or LSB frequencies to velocity; the default value is inupper=True. So if your line is in LSB and you go to velocity, be sure to explicitly set inupper=False.

Summary.

to= Description Other keywords necessary
frequency Converts to the Intermediate Frequency scale in MHz. None
usbfrequency Converts to the Upper side band Frequency scale in GHz. None
lsbfrequency Converts to the lower side band Frequency scale in GHz. None
velocity Converts to radial velocity (km/s) relative to reference frequency (RADIO convention) reference=reference frequency (GHz), inupper=(True or False)
radio-vel Converts to radial velocity (km/s) relative to reference frequency (RADIO convention) reference=reference frequency (GHz), inupper=(True or False)
optical-vel Converts to radial velocity (km/s) relative to reference frequency (OPTICAL convention) reference=reference frequency (GHz), inupper=(True or False)
relativistic-vel Converts to radial velocity (km/s) relative to reference frequency (RELATIVISTIC convention) reference=reference frequency (GHz), inupper=(True or False)

18.1.2. Use of the Local Oscillator (LO) Frequency

Going from the IF scale to LSB or USB requires an LO frequency. To be explicit,

Bands 1-5:

USB: SKY = LO + IF

LSB: SKY = LO - IF

Bands 6-7:

USB: SKY = LO + Fconv - IF

LSB: SKY = LO - Fconv + IF

where Fconv is 10404.7 MHz (H-pol) or 10403.2 MHz (Vpol).

The convertFrequency Task demonstrated above makes use of the 'LoFrequency' data column in the spectrum. During the Level 1 pipeline, the doVelocityCorrection Task multiplies both the LoFrequency and frequency_X (where X is the subband number) columns by a Doppler factor to take them into the LSRk frame of reference (or the SOURCE frame for Solar System targets). If you add these columns together, you will have SKY frequencies already in the final frame of reference. So the meaning of the column 'LoFrequency' depends on the level in which it is found:

  • Levels 0 and 0.5

    Column 'LoFrequency' is the actual, instrumental LO setting.

  • Levels 1 and 2

    • 'science' datasets

      Column 'LoFrequency_measured' is the actual, instrumental LO setting.

      Column 'LoFrequency' is the LO Frequency multiplied by a Doppler factor to put it in the reference frame specified in metadatum freqFrame (SPECSYS)

    • non-'science' datasets

      Column 'LoFrequency' is the actual, instrumental LO setting.

  • Level 2.5

    For point modes, same as Level 2.

    In mapping modes, the cubes don't have such columns, though there is a metadatum 'loFrequency', description 'The LO frequency of the source phase', which is the actual instrumental LO frequency. In addition, there are copies of the Level 2 products alongside the cubes, in which you will find the columns described for Level 2

    In spectral scans, there are no such columns. However, the values from the Level 2 Doppler-corrected 'LoFrequency' column are copied into metadata with names such as 'loFreq1','loFreq2', etc.

The instrumental IF frequencies are not preserved after Level 0.5. They can be recreated most easily by repipeling with doVelocityCorrection turned off, or by using doVelocityCorrection and convertFrequency.

There are metadata, which are observing mode dependent, appearing throughout the observation context derived from these LoFrequency data columns.

Metadatum Description Comment
LoFreqAvg Average LO frequency Doppler-corrected to freqFrame (SPECSYS) Average of the LoFrequecy column after doVelocityCorrection
loFrequency Actual local oscillator frequency For observations with a fixed instrumental LO
loFreqMax Max LO frequency of the spectral scan Doppler-corrected to freqFrame (SPECSYS) Doppler-corrected max LO frequency for Spectral Scan observations
loFreqMin Min LO frequency of the spectral scan Doppler-corrected to freqFrame (SPECSYS) Doppler-corrected min LO frequency for Spectral Scan observations
loFrequencyEnd Actual end local oscillator frequency Instrumental LO in Spectral Scan observations
loFrequencyStart Actual start local oscillator frequency Instrumental LO in Spectral Scan observations
obsFreqLsbMax Observed max frequency for LSB in freqFrame (SPECSYS) Max observed Doppler-corrected sky frequency for the LSB for Point and Mapping observations
obsFreqLsbMin Observed min frequency for LSB in freqFrame (SPECSYS) Min observed Doppler-corrected sky frequency for the LSB for Point and Mapping observations
obsFreqUsbMax Observed max frequency for USB in freqFrame (SPECSYS) Max observed Doppler-corrected sky frequency for the USB for Point and Mapping observations
obsFreqUsbMin Observed min frequency for USB in freqFrame (SPECSYS) Min observed Doppler-corrected sky frequency for the USB for Point and Mapping observations
obsFreqMax Observed max frequency in freqFrame (SPECSYS) Max observed Doppler-corrected sky frequency for Spectral Scan observations
obsFreqMin Observed min frequency in freqFrame (SPECSYS) Min observed Doppler-corrected sky frequency for Spectral Scan observations

18.1.3. Changing frequency rest frame with doVelocityCorrection

By default, the Level 2 spectra are in the LSRk rest frame (or the source frame for solar system targets). The doVelocityCorrection Task can be used to change the rest frame to one of 'topocentric' (spacecraft), 'geocentric', 'barycentric' (close to heliocentric), 'lsrk', and 'source'. Chapter 25 describes how these transformations are done.

For example, to transform all Level 2 products to the spacecraft rest frame:

 level2 = obs.getLevel2()
 refs = level2.refs
 for ref in refs:
     htp=level2.refs[ref].product
     doVelocityCorrection(htp=htp,targetFrame="topocentric")

Because of the way referencing works inside observation contexts, the original data are now changed. Along with the frequency axes, the 'LoFrequency' column is transformed to the spacecraft frame and now matches 'LoFrequency_measured':

 print htp.meta['freqFrame']
 {description="Standard of rest for spectral axis", string="topocentric"}
 print htp.refs['box_001'].product['0001']['LoFrequency_measured'].data - htp.refs['box_001'].product['0001']\
 ['LoFrequency'].data[0.0]

18.1.4. The meaning of velocities found in data and metadata

After application of doVelocityCorrection, three data columns appear in spectra: 'velocity_hso_1', 'velocity_hso_2', and 'velocity_hso_3'. These are the three components of the spacecraft velocity in the barycentric rest frame computed for the midpoint of the integration. To preserve HIFI frequency calibration accuracy, this velocity is necessarily better than 1 m/s accurate.

There are metadata read and written by doVelocityCorrection, some of which come from the original observing proposal.

Metadatum Description Comment
vlsr "Velocity in the frame of reference" From the proposal: source redshift
redshiftFrame "Reference frame of redshift" From the proposal: reference frame for source redshift
redshiftType "Type of redshift: optical, radio, redshift" From the proposal: definition of redshift ('vlsr') parameter
freqFrame (SPECSYS) "Standard of rest for spectral axis" dovelocityCorrection read/write: ref frame of associated dataset

There are some other metadata not used by HIFI, here listed for completeness:

Metadatum Description Comment
radialVelocity (VFRAME) "Spacecraft velocity along the l-of-s of the telescope wrt the LSR" This is computed by the RadialVelocityTask using the spacecraft orbital ephemeris for the mid-time of the observation (metadata (startDate + endDate)/2). Note the sign, it is positive if the spacecraft is moving toward the source. This value is used in the SPIRE and PACS pipelines to convert frequencies from topocentric to the LSR rest frame. Both use the RADIO convention: freq = freqRest * (1 - Vrad/C)
velocityDefinition (VELDEF) "The velocity definition and frame" Current value is 'RADI-LSR'. It reflects the way radialVelocity is used to compute LSR frequencies from topocentric.
frame "Frame of reference for Vlsr" Ignore it. It is a leftover from previous versions of the HSPOT proposal software.