### Aligning Dual-Sideband Spectra

Usually, a DSBSpecFrameDSBSpecFrame will be used to describe the WCS for a 1-dimensional array of data values measured using a dual-sideband instrument. The FrameSetFrameSet for this sort of situation will typically contain two Frames: the base FrameFrame will be a simple 1-dimensional Frame describing the value used to index the data array (i.e. “pixel” coordinates) and the current Frame will be a DSBSpecFrame with values for the DSBCentreDSBCentre and IFIF attributes that match the settings of the dual side-band instrument. The MappingMapping connecting the base (pixel) Frame to the current (spectral) Frame will depend on exactly how the instrument samples the spectrum (linear, logarithmic, etc) but should always generate spectral values within the window corresponding to the value of the SideBandSideBand attribute in the DSBSpecFrame. For instance, if the SideBand attribute is set to USB, then the Mapping should generate the USB frequency (or wavelength, velocity, etc) for each pixel.

As an example, the following code creates a FrameSet that associates a radio velocity (km/s) in the LSRK standard of rest with each element in an array of 1000 data values. The velocity range -100 to 100 km/s in the LSB window (see Figure 11) is mapped linearly onto the pixel array. The spectral feature of interest is at 10 km/s (i.e. within the velocity range of the LSB window) and the IF is +5 GHz (topocentric).

177#177
The code above should generate the following screen output:
178#178

Note, changing the value of the Sideband attribute using the FrameSet pointer, as is done above, automatically causes the Mapping inside the FrameSet to be updated to include the mapping from LSB frequency to USB frequency. This automatic modification of the Mappings inside a FrameSet is described further in §14.6 and illustrated in Figure 12. It relies on the astConvertastConvert function to find the Mapping that converts values from one DSBSpecFrame to another.

Figure 12: When a FrameSet pointer is used to change the attributes of its current Frame (C) a copy of the original current Frame is first made (C') and the requested attribute changes are applied to this copy. The Mapping from the original Frame to the modified Frame is then found using the astConvert function. The modified Frame (C') is then added into the FrameSet, using the Mapping returned by astConvert (shown by the dotted arrow) to connect it to the original Frame (C). Finally, the original Frame is removed leaving the new modified Frame as the current Frame. The base Frame (B) is unchanged.
[width=0.9]sun211_figures/dsbspec2

When the astConvert function to used to find the Mapping between two DSBSpecFrames, it is sometimes appropriate for it to take account of the potentially different settings of the Sideband attribute in the two DSBSpecFrames. The above example, in which astConvert is used to modify the Mapping inside a FrameSet to accomodate a change to the Sideband attribute of the current Frame, is such a case - astConvert returns a Mapping that implements equation 1 in some form.

However, there are also cases where it is better for astConvert not to take account of differences in the settings of the Sideband attribute. For instance, if a spectral line is observed twice such that the line is in the LSB in one observation and in the USB in the other, as illustrated in Figure 13, then it would be inappropriate to take account of this difference when co-adding the two observations. In this case, a frequency in one observation should be matched to exactly the same frequency in the other observation, regardless of the difference in Sideband.

Figure 13: Two observations of a single line are made - observation 1 places the line in the LSB and observation 2 places the line in the USB.
[width=0.9]sun211_figures/dsbspec3

The AlignSideband attribute is used to determine whether any difference is Sideband setting should be taken into account when finding the Mapping between two DSBSpecFrame objects. The default for this attribute is zero, meaning that the Sideband settings are usually ignored by the astConvert and astFindframe functions (i.e. the DSBSpecFrames are aligned as if they were simple SpecFrames). The one exception is that differences in Sideband are always taken into account, regardless of the value of the AlignSideband atribute, when using astConvert to find the Mapping required to restore a FrameSet's integrity following a change to the Sideband attribute in the current Frame (as described earlier in this section).

If an attempt is made to find the Mapping between a pair of DSBSpecFrame, then the Sideband attribute will be ignored if the AlignSideband attribute is zero in either of the DSBSpecFrames. In other words, the Mapping will be determined as if both objects were simple SpecFrames rather than DSBSpecFrames. This also happens if an attempt is made to align a DSBSpecFrame with a simple SpecFrame. See §12.6 for more about how simple SpecFrames align.

If both DSBSpecFrames have non-zero AlignSideband attributes, the Mapping from one to the other is made of three parts in series:

1. A Mapping which converts the first DSBSpecFrame into its observed sideband representation (i.e. the sideband that contains the DSBCentre value). If the DSBSpecFrame already represents its observed sideband, this Mapping will be a UnitMapUnitMap.
2. A Mapping which converts from the first to the second DSBSpecFrame, treating them as if they were both basic SpecFrames. This takes account of any difference in units, standard of rest, system, etc between the two DSBSpecFrames.
3. A Mapping which converts the second DSBSpecFrame from its observed sideband representation to its current sideband. If the DSBSpecFrame currently represents its observed sideband, this Mapping will be a UnitMap.