Setting rest frequency and frame in CASA tasks
==============================================

S.T.Myers 2008-10-21

There are a number of tasks that need to set the rest frequency for a
line to be used for velocity frame calculations.  The most pressing
is for plotxy, but imaging needs this also.  This should be done in
a unified manner across the package.

Proposed Syntax
---------------

To be used in all tasks that need to set rest frequency.  This should
be propagated back to the sdtasks.  Note that in MS the freq/frame
info is in the SOURCE table, which is indexed from the FIELD table.
There is provision for a list of lines.

I propose we allow only a single setting via the parameters.  If you
want to plot different SPW with different lines, you will need to 
do separate plotxy runs (with overplotting or multipanel as
necessary). Otherwise specification will be difficult and may
require lists or a syntax.

restfreq -- 
        options: (str) '' a frequency quanta or transition name
        default: currently set rest frequency and frame in MS
                 see measures for known lines, e.g.
                   me.linelist() to list lines
                   me.me.spectralline to get frequency
	example: restfreq='1420405751.786Hz' 21cm HI frequency
                 restfreq='HI'               21cm HI transition name
                 restfreq='115.2712GHz'      CO line

Sub-parameters (if restfreq is non-blank):

frame -- frequency frame for spectral axis
        options: (str) 'LSRK','REST','TOPO','LSRD','BARY',
                 'GEO','GALACTO','LGROUP','CMB'
        default: currently set frequency frame in MS
                 see measures (me.frequency) for description

doppler -- doppler mode
        options: (str) 'RADIO','Z','RATIO','BETA','GAMMA',
                 'OPTICAL','TRUE','RELATIVISTIC'
        default: currently set doppler system in MS
                 see measures (me.doppler) for description
 

Short-Term Development
----------------------

Patch 3 - plotxy: 
          Implement above with only frequency quanta in restfreq (or
          maybe the transitions currently known in measures), and
          only LSRK frame in RADIO doppler system (could leave out the
          sub-parameters for now)

Patch 4 - measures:
          Add other transitions to measures me.linelist or provide
          same capabilities as in the ASAP linecatalog or in 
          splatalogue. In particular note the mm and submm transitions
          are needed.

          plotxy: add frame and doppler options

          clean: add restfreq, frame, doppler options
   
Single-Dish
-----------

For reference, here is what we currently have in sdtasks from ASAP:

frame -- frequency frame for spectral axis
        options: (str) 'LSRK','REST','TOPO','LSRD','BARY',
                 'GEO','GALACTO','LGROUP','CMB'
        default: currently set frame in scantable
        WARNING: frame='REST' not yet implemented
doppler -- doppler mode
        options: (str) 'RADIO','OPTICAL','Z','BETA','GAMMA'
        default: currently set doppler in scantable
 
Note that the rest frequency is currently set by toolkit, e.g.
Cookbook A.3.10:
  sel=sd.selector()
  sel.setifs(0)
  scans.set_selection(sel)
  scans.set_restfreqs([45490258000.0,45590258000.0,45690258000.0])
to give 3 rest-freqs to a single IF, though only the first one is
used according to the documentation.

There is access to the ASAP line catalog in the system, see A.3.9.2
in cookbook.