JCMT Data Cube

This recipe shows how to import and display a set of spectra observed in the mm or sub-mm wavelength range of the electromagnetic spectrum with a heterodyne receiver on the James Clerk Maxwell Telescope (JCMT) in Hawaii. The example used here is an observation of emission from the C$^{18}$O  ${\rm J} = 2 \rightarrow 1$ transition in L1689B, a dense core within the molecular cloud Lynds Dark Nebula 1689. The data cube comprises a grid of 7 by 7 points on the sky, with a spectrum of 153 channels at each position. The example data are available as file l1689b.sdf. JCMT heterodyne observations are usually reduced using the SPECX package (see SUN/17[5]) and the example data are in the native SPECX data format. In SPECX terminology a collection of spectra on a grid of points on the sky is a called a `map'.

The data for L1689B have kindly been made available in advance of publication; they may not be published without the express, written permission of the observers (see Section  for details).

1. The first stage to importing a SPECX map is to convert it to a simple data cube in the standard Starlink NDF format. Application specx2ndf in the CONVERT package (see SUN/55[6]) performs this task. Proceed as follows. First type:

   convert

   to make the CONVERT applications available. Then type:

   specx2ndf  l1689b  l1689bndf

   Note that though the input SPECX map and output NDF are respectively held in files called l1689b.sdf and l1689bndf.sdf they are specified to application specx2ndf without the ` .sdf' file type.

   When displaying SPECX maps it is conventional to represent the spectral axis as a series of radial velocities computed for the rest wavelength of the line being observed and corrected to a kinematical local standard of rest. By default specx2ndf generates the spectral axis in this fashion and this is how it will be computed in the above example. However, specx2ndf allows some flexibility in how the spectral axis is represented; see the appropriate section of SUN/55 for details of the alternatives available.

2. Once the SPECX map has been converted to a simple data cube in the NDF format it can be processed and displayed with a variety of standard Starlink applications, such as those in the image processing package KAPPA (see SUN/95[8]). For example, type:

   kappa

   to make the KAPPA applications available. Then type:

   hislist  l1689bndf

   Again the file name is specified without the `.sdf' file type. This application lists the history information describing the processing which has been performed on the data. The history information appended by specx2ndf includes details of the way in which the spectral axis was computed. It is also possible to inspect the structure of the data set using hdstrace. Simply type:

   hdstrace  l1689bndf

   As usual the file name is specified without the `.sdf' file type. This facility is useful because it lists the value of much of the auxiliary information contained in the data set. hdstrace is documented in SUN/102[10]. In addition hdstrace will also work on the original SPECX map.

3. The next step is to convert the NDF format file into a file in the `native' DX format, which DX can read. This operation could be performed `on the fly' as DX reads the file. However, it is simpler to convert the file in a separate operation prior to invoking DX. The conversion is performed using application ndf2dx, which is part of SX, the Starlink enhancements to DX (see SUN/203[11]). By convention files in the native DX format have file type `.dx'. To convert the entire data cube simply type:

   $SX_DIR/ndf2dx  l1689bndf  l1689ball.dx

   Note that though the file type is not specified for the input NDF file, it should be given for the output native DX format file.

   The above example will convert the entire data cube. However, often the useful information will be contained in only a small range of radial velocities. For example, in the example map most of the useful information lies between velocity channels 65 and 85. It is possible to convert a subset of the NDF corresponding to a given range of velocity channels. For example, to convert a subset corresponding to channels 65 through to 85 type:

   $SX_DIR/ndf2dx  'l1689bndf(65:85,,)'  l1689bsub.dx

   The syntax to specify a subset of an NDF is to give the bounds of the required region inside parentheses after the file name. Unfortunately however, by default the Unix shell will attempt to interpret these parentheses. Thus, in the above example the input file name and NDF subset are enclosed in single quotes in order to prevent this behaviour and ensure they are passed correctly to ndf2dx. The use of `escape mechanisms' of this sort to prevent the premature interpretation of special characters sent to Starlink applications is discussed in SC/4[3].

4. Figure  shows a DX network to display a sequence of slices through a JCMT map. Each slice corresponds to the grid of points seen on the sky at a given radial velocity. The network is available as files jcmtslice.net and jcmtslice.cfg (jcmtslice.net is the basic network and jcmtslice.cfg is a `configuration file' which controls some aspects of its behaviour). Start DX (as described in Section ). Then proceed as follows.

   Figure: Network to display a sequence of slices through a JCMT data cube.

   
   1. Load the network. Select the `Open Program' option from the `File' menu of the main DX window. Select file jcmtslice.net. The network should now load and appear in the main window. See Section  for further details.

   2. Select the `Open All Control Panels' option from the `Windows' menu of the main DX window. Set the required file name and number of slices. (In the current example these are l1689bsub.dx and 20 respectively.) Close the `Control Panel' window.

   3. Execute the network once. Once the network has executed you will probably have to reset the display window (option `Reset' in the `Options' menu of the display window). For a more effective display select `View control' from the `Options' menu and set the `Set View' parameter to one of the `Off' options, perhaps `Off top'.

   4. Finally double click on the `Sequencer' module and click on the play button. A sequence of slices sweeping through the data cube will now be displayed.

   The network includes a `scale bar' showing how the colour displayed for each pixel in each slice corresponds to the value of the pixel. In this example the value of each pixel is the radio `brightness temperature' in $^{\circ}$Kelvin.

5. Figure  shows a network for displaying an iso-surface⁶ in a JCMT data cube. This network is available as files jcmtsurface.net and jcmtsurface.cfg (again jcmtsurface.net is the basic network and jcmtsurface.cfg is a configuration file).

   

   Much of the complexity of this network occurs because it contains an option to normalise the axes of the cube. Two of the axes correspond to positions on the sky and the third to the dispersion, usually expressed as a radial velocity computed from the rest wavelength of the line. There is no relation between the spacial and spectral axes, so the `cube' can be either very `long' or `thin' in the spectral axis compared to the spacial ones. In order to generate an effective iso-surface it often helps to `normalise' the cube so that it has unit length in each axis. Though this procedure often improves the iso-surfaces generated it makes the axes less intuitive. Hence it is made optional so that you can choose the alternative most suitable for your data.

   1. Select the `Open All Control Panels' option from the `Windows' menu of the main DX window. Set the axis units, file name and iso-surface value. In the current example suitable values of these quantities are: normalised, l1689bsub.dx and 3.5 respectively. The contour (or iso-surface) value is specified as a radio `brightness temperature' in $^{\circ}$Kelvin. Close the `Control Panel' window.

   2. Execute the network once. Once the network has executed you will probably have to reset the display window (option `Reset' in the `Options' menu of the display window). For a more effective display select `View control' from the `Options' menu and set the `Set View' parameter to one of the `Off' options, perhaps `Off top'. Re-execute the network.

   3. Use the various settings of the `Mode' option in the `View Control' window to pan, zoom and rotate the display in order to examine the iso-surface. These options are described in Section 2.3 Controlling the Appearance of an Object: the Image Window of the IBM QuickStart Guide[1].