# Changing HIFI frequency scales demo script
# Prepared for HIFI PSP/SDP DP workshop, ESTEC, April 8-9, 2010
#
# v0.0 CM: created
#
# ------------------------------------------------------------------------------
# For full documentation, see HIFI User Manual chapter 6
# 
# HIFI data can be represented in the intermediate frequency (IF), the upper 
# sideband frequency (USB), the lower sideband frequncy (LSB), or by velocity.
# This script demonstrates how to convert between these scales.
# 
# In practice there are two methods of altering the HIFI frequency scales: using 
# the Spectrum Explorer GUI, or from the command line. The command line tasks 
# will actually change the data, by resetting the frequency to upper/lower 
# sideband representation or velocity. The GUI only changes what is seen in the 
# SpectrumExplorer, the data themselves are unchanged.
#
# DATA:   This is a general script for any data.  Use the getObservation()
# command to load data of interest into your session.
#
# ------------------------------------------------------------------------------
# 
#
# Using the SpectrumExplorer GUI
#
# LSB/USB
#
# Activate a spectrum in a SpectrumExplorer window, right mouse click on the 
# frequency axis (the axis itself, not the title). Select "add aux axis" from 
# the axis menu and choose the frequency scale desired.  You may wish to remove
# the original axis, select that option from the "Axis" drop-down menu.
#
# Velocity
#
# Proceed as above.  Once you have a new axis (this option is not available
# from the original axis -- yet), select "set units" from the "Axis" drop-down
# menu.  Select "m/s" then "km/s", or another option.  You will need to enter 
# the reference frequency of the observation. 
#
#
#
# Change Spectral Views from the command line
#
# LSB/USB
#
# The task is called ConvertFrequencyTask. Assuming spectrum is the variable 
# name for a HifiSpectrumDataset, convert to LSB:
#
cft=ConvertFrequencyTask()
cft(sds=spectrum,to="lsbfrequency")
# 
# or USB
#
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
# before level 0.5 in the pipeline, the data do not have a frequency axis! Use 
# Level 1 or 2 HTPs
#
cft=ConvertFrequencyTask()
cft(htp=hifitimelineproduct, to='usbfrequency')
# 
# The 'lsbfrequency', and 'frequency' options convert to LSB and IF as before.
#
#
# Velocity
#
# The ConvertFreqencyTask also works to convert the frequency scale to a 
# velocity scale, once given the reference frequency and sideband.
# Here use a reference frequency of 576.268 in the LSB.
#
cft=ConvertFrequencyTask()
cft(sds=spectrum,to='velocity',reference=576.268,inupper=False)
#
# For USB use inupper=True
#
# Use to='frequency' to convert back again to IF