An example Specdre Extension

As an example, a sensible Specdre Extension has been added to a three-dimensional NDF, which in fact is a data cube of HI 21 cm spectra taken on a grid of galactic longitudes and latitudes. Here is how hdstrace sees the file before the Extension is added:

LVCHI  <NDF>
   TITLE          <_CHAR*12>      'KAPPA - Cadd'
   DATA_ARRAY(32,37,150)  <_REAL>   -0.1216488,0.1160488,4.3972015E-02,
                                    ... 0.4012871,-7.1809769E-02,0.4626274,*
   AXIS(3)        <AXIS>          {array of structures}
   Contents of AXIS(1)
      DATA_ARRAY(32)  <_REAL>        130,130.1667,130.3333,130.5,130.6667,
                                     ... 134.6668,134.8335,135.0002,135.1668
   Contents of AXIS(2)
      DATA_ARRAY(37)  <_REAL>        17,17.16667,17.33333,17.5,17.66666,
                                     ... 22.49998,22.66665,22.83331,22.99998
   Contents of AXIS(3)
      DATA_ARRAY(150)  <_REAL>       -163.855,-162.565,-161.275,-159.985,
                                     ... 24.48488,25.77489,27.06489,28.35489

Now almost all components that can exist in a Specdre Extension are set, mostly to their default values. The only component missing is the sum of rows of a covariance matrix. This is because that structure usually must not exist: other structures can be assigned `harmless' values, but the simple existence of .COVRS makes a difference. The Extension was actually made with the editext command, which can also list a summary of the Extension:

List of Specdre Extension (v. 1.1)

Name of NDF:         /home/hme/lvchi
Spectroscopic axis:  3
Reference frame:     local standard of rest
Refractive index:    1.0000000
Reference frequency: 1420.405751786000 [10**9 Hz]
Spectroscopic values exist and are velocity [km/s].
Spectroscopic widths do exist.
First coordinates    exist and are galactic longitude [degree]
Second coordinates   exist and are galactic latitude [degree]
Covariance row sums  do not exist.
Result structure provides for 4 parameters in 1 component.

#  line name               lab freq.          type  npara  mask from     to
1  HI (21cm) LV component  1420.405751786000  Gauss     4  -.1701412E+39 -.1701412E+39

# parameter type
1 centre
2 peak
3 FWHM
4 integral

End of list.

Using hdstrace to list the NDF now yields:

LVCHI  <NDF>
   TITLE          <_CHAR*12>      'KAPPA - Cadd'
   DATA_ARRAY(32,37,150)  <_REAL>   -0.1216488,0.1160488,4.3972015E-02,
                                    ... 0.4012871,-7.1809769E-02,0.4626274,*
   AXIS(3)        <AXIS>          {array of structures}
   Contents of AXIS(1)
      DATA_ARRAY(32)  <_REAL>        130,130.1667,130.3333,130.5,130.6667,
                                     ... 134.6668,134.8335,135.0002,135.1668
   Contents of AXIS(2)
      DATA_ARRAY(37)  <_REAL>        17,17.16667,17.33333,17.5,17.66666,
                                     ... 22.49998,22.66665,22.83331,22.99998
   Contents of AXIS(3)
      DATA_ARRAY(150)  <_REAL>       -163.855,-162.565,-161.275,-159.985,
                                     ... 24.48488,25.77489,27.06489,28.35489
   MORE           <EXT>           {structure}
      SPECDRE        <SPECDRE_EXT>   {structure}
         SPECAXIS       <_INTEGER>      3                                   (1)
         RESTFRAME      <_CHAR*32>      'local standard of rest'            (2)
         INDEXREFR      <_REAL>         1                                   (3)
         FREQREF        <_DOUBLE>       1420.405751786                      (4)
         FREQUNIT       <_INTEGER>      9                                   (4)
         SPECVALS       <NDF>           {structure}
            DATA_ARRAY     <ARRAY>         {structure}                      (5)
               DATA(32,37,150)  <_REAL>       -163.855,-163.855,-163.855,
                                              ... 28.35489,28.35489,28.35489
               ORIGIN(3)      <_INTEGER>      1,1,1
 
            LABEL          <_CHAR*64>      'velocity'                       (6)
            UNITS          <_CHAR*64>      'km/s'                           (6)
         SPECWIDS       <NDF>           {structure}
            DATA_ARRAY     <ARRAY>         {structure}                      (7)
               DATA(32,37,150)  <_REAL>       1.289993,1.289993,1.289993,
                                              ... 1.290001,1.290001,1.290001
               ORIGIN(3)      <_INTEGER>      1,1,1
         COORD1         <NDF>           {structure}                         (8)
            DATA_ARRAY     <ARRAY>         {structure}
               DATA(32,37,1)  <_REAL>         130,130.1667,130.3333,130.5,
                                              ... 134.8335,135.0002,135.1668
               ORIGIN(3)      <_INTEGER>      1,1,1
            LABEL          <_CHAR*64>      'galactic longitude'
            UNITS          <_CHAR*64>      'degree'
         COORD2         <NDF>           {structure}                         (8)
            DATA_ARRAY     <ARRAY>         {structure}
               DATA(32,37,1)  <_REAL>         17,17,17,17,17,17,17,17,17,17,
                                              ... 22.99998,22.99998,22.99998
               ORIGIN(3)      <_INTEGER>      1,1,1
            LABEL          <_CHAR*64>      'galactic longitude'
            UNITS          <_CHAR*64>      'degree'
         RESULTS        <NDF>           {structure}                         (9)
            DATA_ARRAY     <ARRAY>         {structure}                     (10)
               DATA(4,1,32,37)  <_REAL>       *,*,*,*,*,*,*,*,*,*,*,*,*,*,
                                              *,*,*,*,*,*,*,*,*,*,*,*,*,*
               ORIGIN(4)      <_INTEGER>      1,1,1,1
            VARIANCE       <ARRAY>         {structure}                     (11)
               DATA(4,1,32,37)  <_REAL>       *,*,*,*,*,*,*,*,*,*,*,*,*,*,
                                              *,*,*,*,*,*,*,*,*,*,*,*,*,*
               ORIGIN(4)      <_INTEGER>      1,1,1,1
            MORE           <EXT>           {structure}                     (12)
               LINENAME(1)    <_CHAR*32>      'HI (21cm) LV component'
               LABFREQ(1)     <_DOUBLE>       1420.405751786
               COMPTYPE(1)    <_CHAR*32>      'Gauss'
               NPARA(1)       <_INTEGER>      4
               MASKL(1)       <_REAL>         *
               MASKR(1)       <_REAL>         *
               PARATYPE(4)    <_CHAR*32>      'centre','peak','FWHM','inte...'

1. The third axis of the main NDF is declared the spectroscopic axis. In fact this is the velocity axis of the data.

2. The telescope's local oscillator was controlled such that the spectrometer recorded frequency in the reference frame of the local standard of rest. Alternatively, someone could have re-calibrated the spectroscopic axis at some stage to refer to the LSR.

3. The refractive index is set to 1, which amounts to ignoring refraction for the purpose of wavelength calibration. Probably no one will ever use wavelengths for these data anyway. If this structure were missing, a value of 1 would be assumed whenever necessary.

4. The reference frequency is encoded in two numbers. Taken together they say that the velocity axis refers to a laboratory frequency of 1420.405751786 MHz.

5. Here is a data cube of the same shape as the main data. It stores the velocity axis for each sky position (l,b). Thus for each pixel in the three-dimensional data cube, there is a separate velocity value stored for the pixel centre position. In this case it is a waste of disk space since all positions have the same velocity grid. But a slit spectrum recorded with a CCD may have a shift of wavelength scales from one row to the next.

6. The cube with the spectroscopic pixel centres should have its own label and unit. As the data reduction and analysis progresses, these may change, while the main NDF's .AXIS(3) structure will in general remain untouched.

7. Here is a data cube of the same shape as that with the pixel centres, only that it stores the pixel widths. These arrays of centres and widths may exist, or not, independently of each other. Though usually the width is only useful if there is also an array of centres.

8. These two structures look similar to the cube of spectroscopic pixel centres. But these `cubes' do not extend along the spectroscopic axis. Each contains one number per spectrum. The two structures combine to give each spectrum a two-dimensional position, which may be the position on the sky, on plotting paper, or both. In this example the first spectrum is at (130,17), the second at (130.167,17) and so on. The positions thus coincide with those according to the first and second axes of the main NDF. In this case it is a waste of disk space. But in general these two structures allow for non-orthogonal and even non-linear projections from NDF axis centre space to COORD1/COORD2 space. A two-dimensional main NDF might actually be an arbitrary sequence of spectra, and still these two structures could help to sort each spectrum into its place on the sky.

9. Here is a rather complex NDF structure. It is used to store and retrieve fit results. The results can be different from one sky position to the next, but there is only one set of parameters per position. The spectroscopic axis - of length 150 - is scrapped, the two positional axes - lengths 32 and 37 respectively - are retained. Inserted are the first and second axes, here of lengths 4 and 1 respectively. Don't wonder about the second axis, it is always of length 1.

   Usually the result structure will be manipulated by applications as they find it necessary to store data in it. But most of the structure can be manipulated explicitly with the command editext.

10. This should contain the values of the parameters, by default they take the bad value, which is represented here by asterisks.

11. This should contain the variances of the parameters as a measure of their uncertainties. Again, by default these values are bad.

12. The extensions to the result NDF are seven vectors. Most have one element per spectral component - in the example 1. The .PARATYPE vector has four elements, one for each parameter. The sole component provided for in the result NDF is the `LV component' of the 21 cm line. Its laboratory frequency is repeated here, the value is independent of the reference frequency above, but the same unit (MHz) is used. We obviously expect that the spectral line has the shape of a Gauss curve and we want to store four parameters describing that curve. .PARATYPE indicates the meaning of all parameters. No mask is enabled to limit the velocity range where the Gauss curve applies, i.e. .MASKL and .MASKR have the bad value.

    We might want to also store the results for a parabolic baseline fit. Then we would add a second spectral component with three parameters. The vectors that are now of length 1 would become of length 2, .PARATYPE would become of length 7. The additional second vector elements would be `baseline', bad value, `polynomial of 2nd order', 3, bad value, bad value. The fifth to seventh element of .PARATYPE could be `coeff. 0', `coeff. 1', `coeff. 2'.