Converting an AXIS structure to a SpecFrame

For many years, the calibration of spectral axes has been recorded in the form of AXIS structures within the NDF. As mentioned above, each pixel axis in an NDF has an associated AXIS structure, which is a one-dimensional array containing an element for each pixel on the associated axis. The value of each element gives the `axis' value for the pixel.

Spectral axis calibration can now also be recorded in the form of a `SpecFrame'  within the WCS component. A SpecFrame is a Frame  that can describe spectral axes in many different forms (wavelength, frequency, various forms of velocity, etc.), with many different units, and measured in various rest frames. A SpecFrame `knows' how to convert between all these different forms. Let's say you have two spectra--in one the current co-ordinate Frame is a SpecFrame representing frequency in GHz as measured in the rest frame of the telescope (i.e. `topocentric frequency'), and in the other the current co-ordinate Frame is a SpecFrame representing radio velocity in km/s measured in the kinematic Local Standard of Rest. You want to overlay plots of these two spectra for comparison purposes, so you display the first using LINPLOT. This produces a plot in which the x axis is frequency measured in GHz. You then display the second spectrum, again using LINPLOT but this time specifying clear=no on the command line in order to prevent the previous plot from being erased. The SpecFrame representing radio velocity in the second spectrum automatically adjusts itself to represent the same system as the currently displayed plot (topocentric frequency in this example), so the plots can be compared directly. The conversion includes the effects of the Doppler shift caused by the differing standards of rest used by the two spectra.

So the question arises; ``How can I add a SpecFrame to my existing NDFs that only have an AXIS structure?''. This is simple to do using the WCSADD command. Let's assume you have a one-dimensional NDF called fred containing an AXIS structure holding the frequency at the centre of each pixel in units of GHz. The following command will add an appropriate SpecFrame to the WCS component of the NDF (and will also make it the current Frame):

    % wcsadd fred frame=axis maptype=unit frmtype=spec domain=SPECTRUM \
             attrs="'System=freq,Unit=GHz'"

The FRMTYPE parameter indicates that a SpecFrame should be created. The ATTRS parameter gives the attribute values to be assigned to the SpecFrame (note the quotes to protect the string from interpretation by the UNIX shell). The DOMAIN parameter is given the default domain for a SpecFrame (and should usually not be changed). The MAPTYPE and FRAME parameters indicate that this new SpecFrame should be connected to the existing AXIS Frame using a UnitMap--i.e. the frequency values held within the AXIS structure are identical to the frequency values described by the SpecFrame.

The above setting for the ATTRS parameter gives the bare minimum of information--there are several other items of information that could have been given. For instance, the above command does not indicate the standard of rest to which the frequency values refer. Neither does it indicate the source position, date of observation, or the observers geographical position (all of which may be needed to enable conversion between different standards of rest). In general you should specify as much information as you can. To do this, you can either include the extra information in the ATTRS parameter value above, or you can add the information later using WCSATTRIB. For example:

    % wcsattrib fred remap=no set Stdofrest topo
    % wcsattrib fred remap=no set RefRA '"10:12:24.2"'
    % wcsattrib fred remap=no set RefDec '"-32:10:14"'
    % wcsattrib fred remap=no set Epoch '"2003-10-2 12:13:00"'
    % wcsattrib fred remap=no set ObsLat '"N19:49:33"'
    % wcsattrib fred remap=no set ObsLon '"W155:28:47"'

These commands set new values for named attributes within the current Frame of NDF fred. These attributes are described here. The inclusion of "remap=no" is important: it tells the command to change the Frame attribute without changing the Mappings  between Frames accordingly. If the default value of "remap=yes" were used, the Mappings that connect the SpecFrame  to the other Frames within the WCS FrameSet  would be modified in order to ensure that the position of each pixel is unchanged. The default mode ("remap=yes") should be used if you already have a fully and correctly specified SpecFrame within the WCS component which you want to change to describe a different system. For instance, if you have a SpecFrame describing frequency at each pixel, and you want to change it so that it describes the corresponding wavelength at each pixel, then doing:

    % wcsattrib fred set System wave

will modify the Mapping between the pixel Frame and the SpecFrame using the relationship ``wavelength = speed of light/frequency''.

However, if you have a partially or incorrectly specified SpecFrame you should usually use "remap=no". For instance, of the above SpecFrame, which gives the frequency at each pixel, was discovered to be incorrect in that the AXIS values were actually wavelength values and not frequency at all, then you would want to correct the WCS component by changing the System attribute of the SpecFrame from "freq" to "wave". In this situation you want to leave the Mapping from the pixel Frame to the spectral Frame unchanged since the Mapping already gives the correct wavelength value (previously, but erroneously, thought to be a frequency value). So here you would do:

    % wcsattrib fred remap=no set System wave