The JCMT Observing Tool


This is a general tutorial for the JCMT Observing Tool.

1. Getting started
An introduction to the Observing Tool, libraries, position editor, survey containers and frequency editor.
2. Organizing programs
How to more efficiently organize the information in an Observing Tool program.
3. The validator
Understanding the results from the Observing Tool’s internal and XML schema validation tools.


1. Getting started

If you have not already done so, unpack the tutorial tar package and change into its directory:

tar -xzf tutorial_ot.tar.gz
cd tutorial_ot

Installing the Observing Tool

Before running the Observing Tool, you must have Java installed. Please check your Java version as follows:

java -version
java version "1.8.0_121"
Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)

This should indicate that you are using Oracle’s version, “HotSpot”. The Observing Tool does not work properly with OpenJDK. If necessary, you can download the Java Development Kit (JDK, or Java Runtime Environment, JRE) from Oracle’s website.

The Observing Tool is available as a single JAR file. You should find a copy in the tutorial package, and you can also download a new copy using the following link:

If your system is not set up to automatically run JAR files, you can start it from a console as follows:

java -jar jcmtot.jar &

When the Observing Tool starts, it will connect to the OMP to check for available updates. You should see a message confirming you have the latest version at the lower right of the splash screen:

This OT is the latest version.

For more information about installing the Observing Tool, please see the full instructions.

Creating an MSB from the library

In this example we construct a science program based on MSBs from the library. For straightforward projects you can set up your program by simply taking library MSBs and customizing them to your needs.

  • Finally it is always a good idea to validate your observing program.

    If successful, you should see a message saying:

    Science Program settings are valid.
  • The position editor

    We can use the position editor to visualize the observations in an Observing Tool program. This can be useful on its own, for example to verify that offsets and angles are being applied in the direction intended, but it is even more useful if you can load a reference image. We can convert one of the maps of NGC 1333 made in the data reduction tutorial to FITS format using the Starlink convert package, for example:

    ndf2fits \
        ../tutorial_prp/reduced-scuba2-pca/s20151222_00018_850_reduced \
        ngc1333.fits \
        comp=D bitpix=-32 encoding=FITS-IRAF \
        proexts=no prohis=no

    Note that the “JSky” software used for the position editor only supports certain types of FITS files. The command above is based on the Observing Tool documentation, with the addition of proexts and prohis options to ensure extensions and history are not included (to reduce the FITS file size). In addition only certain projections, such as TAN, are supported correctly. The headers indicate that our file has this projection:

    CTYPE1  = 'RA---TAN'           / Type of co-ordinate on axis 1
    CTYPE2  = 'DEC--TAN'           / Type of co-ordinate on axis 2

    If you do not have a map available to convert, please use the ngc1333.fits file in the section_1 directory.

    We can display our FITS file into the Observing Tool's position editor as follows:

    Survey containers

    Survey containers allow you to repeat an MSB for multiple targets. In this example we will place a SCUBA-2 daisy observation in a survey container and load a target list from a file.

    If you have the latest version of Starlink installed, you will be able to use the catalog_convert script to convert a target list downloaded from Hedwig to the Observing Tool survey container format. If you have a proposal in the Hedwig system, you can download a target list using the link under the table in the Target Objects section of the proposal. Alternatively use the example in the section_1 directory of the tutorial package. You can perform the conversion as follows:

    catalog_convert --infmt hedwig --outfmt jcmt_ot_sc \
        section_1/targets.txt survey_container.txt

    This should give:

    SCIENCE NGC1333 03:28:54.000 31:16:52.00 FK5 -1 1 1
    SCIENCE IC348 03:44:18.000 32:04:59.00 FK5 -1 1 1
    SCIENCE NGC2024 05:41:41.000 -01:53:51.00 FK5 -1 1 1
    SCIENCE NGC2068 05:46:13.000 -00:06:05.00 FK5 -1 1 1

    Each line either defines a SCIENCE or REFERENCE position. Then following the name and coordinates are three numbers: position in tile (-1 for JCMT), number of repeats and priority. More information on the format of this file is available on the Observing Tool advanced topics page.

    If you do not have the catalog_convert script available you can use the survey_container.txt file in the section_1 directory.

    You can set up the survey container as follows:

    The frequency editor

    Next we will create a heterodyne setup to observe the following lines simultaneously with ʻŪʻū:

    1. CO 2–1 (USB)
    2. 13CO 2–1 (LSB)
    3. C18O 2–1 (LSB)
    4. N2D+ 3–2 (USB)

    You can do this as follows:

    Completed example

    If you would like a completed example of the science program described here, please see the file program.xml in the section_1 directory.

    2. Organizing programs

    In this section we will see two quick ways in which you can improve the organization of a science program in the Observing Tool.


    This example features a simple but very repetitive science program. The aim is simplify the program by reducing the amount of duplicate information.

    If you would like to compare your science program with a completed example, please see the file inheritance_completed.xml in the section_2 directory.

    “And” folders

    “And” folders are used to group a collection of MSBs together. The most common uses for them are organizing a program and applying common settings to a number of MSBs. When used in these ways, “and” folders do not affect the observation of MSBs inside — they are still each done individually.

    A completed copy of this example can be found in the and_folders_completed.xml file in the section_2 directory.

    3. The validator

    This example is intended to allow you to practice working through the output of the Observing Tool’s validation tool. A science program with a number of intentional errors is provided.

    Once you have finished correcting the science program, please take a look at the list of additional problems in the issues.html file in the section_3 directory. You can also compare your program with the validation_completed.xml file.