The SpecFrame is a Frame which is specialised for representing coordinate systems which describe a position within an electro-magnetic spectrum. In this section we examine the additional properties and behaviour of a SpecFrame that distinguish it from a basic Frame (§7).
As for a SkyFrame, a SpecFrame is a Frame (§7) and also a Mapping (§5), so it inherits all the properties and behaviour of these two ancestral classes. When used as a Mapping, a SpecFrame implements a unit transformation, exactly like a basic Frame (§7.3) or a UnitMap, so this aspect of its behaviour is not of great importance.
When used as a Frame, however, a SpecFrame represents a wide range of different 1-dimensional coordinate system which can be used to describe positions within a spectrum. The options available largely mirror those described in the FITS-WCS paper III Representations of spectral coordinates in FITS (Greisen, Valdes, Calabretta & Allen).
The SpecFrame constructor function is particularly simple and a SpecFrame with default attributes is created as follows:
Such a SpecFrame would represent the default coordinate system which is heliocentric wavelength in metres (i.e. wavelength corrected to take into account the Doppler shift caused by the velocity of the observer around the sun).
Selection of a particular coordinate system is performed simply by setting a value for the SpecFrame’s (character string) System attribute. This setting is most conveniently done when the SpecFrame is created. For example, a SpecFrame representing Energy would be created by:
Note that specifying “SystemEnergy” also changes the associated Unit (from metres to Joules). This is because the default value of the SpecFrame’s Unit attribute depends on the System attribute setting.
You may change the System value at any time, although this is not usually needed. The values supported are set out in the attribute’s description in Appendix C and include a variety of velocity systems, together with frequency, wavelength, energy, wave-number, etc.
Many spectral coordinate systems have some additional free parameters which serve to identify a particular coordinate system from amongst a broader class of related coordinate systems. For example, the velocity systems are all parameterised by a rest frequency—the frequency which defines zero velocity, and all coordinate systems are qualified by a ‘standard of rest” which indicates the rest frame to which the values refer.
In AST, these free parameters are represented by additional SpecFrame attributes, each of which has a default appropriate to (i.e. defined by) the setting of the main System attribute. Each of these qualifying attributes may, however, be assigned an explicit value so as to select a particular coordinate system. Note, it is usually best to assign explicit values whenever possible rather than relying on defaults. Attribute should only be left at their default value if you “don’t care” what value is used. In certain circumstances (particularly, when aligning two Frames), a default value for an attribute may be replaced by the value from another similar Frame. Such value replacement can be prevented by assigning an explicit value to the attribute, rather than simply relying on the default.
The main SpecFrame attributes which qualify the System attribute are:
For further details of these attributes you should consult their descriptions in Appendix C and for details of the System settings for which they are relevant, see the description of the System attribute (also in Appendix C).
Note that it does no harm to assign values to qualifying attributes which are not relevant to the main System value. Any such values are stored, but are not used unless the System value is later set so that they become relevant.
The default values supplied for many SpecFrame attributes will depend on the value of the SpecFrame’s System attribute. In practice, this means that there is usually little need to specify many of these attributes explicitly unless you have some special requirement. This can be illustrated by using astShow to examine a SpecFrame, as follows:
The output from this might look like the following:
Note that the defaults (indicated by the “#” comment character at the start of the line) for attributes such as the Title, axis Labels and Unit specifiers are all set to values appropriate for the particular velocity system that the SpecFrame represents.
These choices would be appropriate for a System value of “Vopt”, but if a different System value were set, the defaults would be correspondingly different. For example, by default frequency is measured in units of GHz, not , so setting “System=freq” would change the appropriate line above from:
Of course, if you do not like any of these defaults, you may always over-ride them by setting explicit attribute values yourself. For instance, you may choose to have your frequency axis expressed in “kHz” rather than “GHz”. To do this simply set the attribute value as follows:
No error will be reported if you accidentally set an inappropriate Unit value (say "J" - Joules)—after all, AST cannot tell what you are about to do, and you may be about to change the System value to “Energy”. However, an error will be reported if you attempt to find a conversion between two SpecFrames (for instance using astConvert ) if either SpecFrame has a Unit value which is inappropriate for its System value.
SpecFrame attributes, like all other attributes, all have default value. However, be aware that for some attributes these default values can never be more than “a legal numerical value” and have no astronomical significance. For instance, the RefRA and RefDec attributes (which give the source position) both have a default value of zero. So unless your source happens to be at that point (highly unlikely!) you will need to set new values. Likewise, the RestFreq (rest frequency) attribute has an arbitrary default value of 1.0E5 GHz. Some operations are not affected by inappropriate values for these attributes (for instance, converting from frequency to wavelength, changing axis units, etc), but some are. For instance, converting from frequency to velocity requires a correct rest frequency, moving between different standards of rest requires a correct source position. The moral is, always set explicit values for as many attributes as possible.
You can use a SpecFrame to describe the spectral axis in a data cube containing two spatial axes and a spectral axis. To do this you would create an appropriate SpecFrame, together with a 2-dimensional Frame (often a SkyFrame) to describe the spatial axes. You would then combine these two Frames together into a single CmpFrame.
In the resulting CmpFrame, axis 1 will be RA, axis 2 will be Dec and axis 3 will be Frequency. If this is not the order you want, you can permute the axes using astPermAxes.
There is one potential problem with this approach if you are interested in unusually high accuracy. Conversion between different standards of rest involves taking account of the Doppler shift caused by the relative motion of the two standards of rest. At some point this involves finding the component of the relative velocity in the direction of interest. For a SpecFrame, this direction is always given by the RefRA and RefDec attributes, even if the SpecFrame is embedded within a CmpFrame as above. It would be more appropriate if this “direction of interest” was specified by the values passed into the CmpFrame on the RA and DEC axes, allowing each pixel within a data cube to have a slightly different correction for Doppler shift.
Unfortunately, the SpecFrame class cannot do this (since it is purely a 1-dimensional Frame), and so some small degree of error will be introduced when converting between standards of rest, the size of the error varying from pixel to pixel. It is hoped that at some point in the future a sub-class of CmpFrame (a SpecCubeFrame) will be added to AST which allows for this spatial variation in Doppler shift.
The maximum velocity error introduced by this problem is of the order of , where is the angular field of view, and is the relative velocity of the two standards of rest. As an example, when correcting from the observers rest frame (i.e. the topocentric rest frame) to the kinematic local standard of rest the maximum value of is about 20 , so for 5 arc-minute field of view the maximum velocity error introduced by the correction will be about 0.03 . As another example, the maximum error when correcting from the observers rest frame to the local group is about 5 over a 1 degree field of view.
Dual sideband super-heterodyne receivers produce spectra in which each channel contains contributions from two different frequencies, referred to as the “upper sideband frequency” and the “lower sideband frequency”. In the rest frame of the observer (topocentric), these are related to each other as follows:
where is a fixed frequency known as the “local oscillator frequency”. In other words, the local oscillator frequency is always mid-way between any pair of corresponding upper and lower sideband frequencies17. If you want to describe the spectral axis of such a spectrum using a SpecFrame you must choose whether you want the SpecFrame to describe or - a basic SpecFrame cannot describe both sidebands simultaneously. However, there is a sub-class of SpecFrame, called DSBSpecFrame, which overcomes this difficulty.
A DSBSpecFrame has a SideBand attribute which indicates if the DSBSpecFrame is currently being used to describe the upper or lower sideband spectral axis. The value of this attribute can be changed at any time. If you use the astConvert function to find the Mapping between two DSBSpecFrames, the setting for the two SideBand attributes will be taken into account. Thus, if you take a copy of a DSBSpecFrame, toggle its SideBand attribute, and then use astConvert to find a Mapping from the original to the modified copy, the resulting Mapping will be of the form of equation 1 (if the DSBSpecFrame has its StdOfRest attribute set to “Topocentric”).
In general, when finding a Mapping between two arbitrary DSBSpecFrames, the total Mapping is made of of three parts in series:
If an attempt is made to find the Mapping between a DSBSpecFrame and a basic SpecFrame, then the DSBSpecFrame will be treated like a basic SpecFrame. In other words, the returned Mapping will not be affected by the setting of the SideBand attribute (or any of the other attributes specific to the DSBSpecFrame class).
In practice, the local oscillator frequency for a dual sideband instrument may not be easily available to an observer. Instead, it is common practice to specify the spectral position of some central feature in the observation (commonly the centre of the instrument passband), together with an “intermediate frequency”. Together, these two values allow the local oscillator frequency to be determined. The intermediate frequency is the difference between the topocentric frequency at the central spectral position and the topocentric frequency of the local oscillator. So:
The DSBSpecFrame class uses the DSBCentre attribute to specify the central spectral position (), and the IF attribute to specify the intermediate frequency (). The DSBCentre value is given and returned in the spectral system described by the DSBSpecFrame (thus you do not need to calculate the corresponding topocentric frequency yourself - this will be done automatically by the DSBSpecFrame when you assign a new value to the DSBCentre attribute). The value assigned to the IF attribute should always be a topocentric frequency in units of Hz, however a negative value may be given to indicate that the DSBCentre value is in the upper sideband (that is, if then ). A positive value for IF indicates that the DSBCentre value is in the lower sideband (that is, if then ).
17Note, this simple relationship only applies if all frequencies are topocentric.