Survey Definition Tool (SDT) – User Manual

Survey Definition Tool (SDT) – User Manual

Introduction

This document details the use of the Survey Definition Tool in conjunction with the UKIRT OT.  It assumes that you have acquired the software as detailed in the download page, and are ready to define your survey areas and import into a template MSB. The processes covered by this document are:

   Definition of survey areas
   Guide-star Catalog selection 
   Pointing generation and allocation of guide stars per pointing
   Saving the pointings (.sdt) file
   Merging (“Exporting”) the pointings into a template MSB

Some additional configuration information and notes on additional features are given at the end of the document.

You can download the SDT from here. Please note that the SDT has been patched and now includes a current copy of the UKIRT Observing Tool libraries so that it can run as a stand-alone application. 

Note for 07B preparation: the OT was last released in July 2007, and the SDT was released in initial form on 24-Jul-2007. Note that SDSS is now available for use in the Sloan area (but that in the 24-Jul release it does not handle secondary sources, hence you should expect of order 5% blanks in your coverage).

Defining Survey Areas

A list of rectangular and circular survey areas is defined in the Survey Areas text box. Each rectangle/circle is defined on a new line. The format is as follows.

Rectangular areas are defined in terms of two corners and a coordinate system:

  x1 y1 x2 y2 coordSys

Circular areas are defined in terms of their centre, a radius in degrees and a coordinate system:

  x1 y1 radius coordSys

where
x1 y1
x2 y2
Spherical coordinates (e.g. RA Dec, Long Lat etc).
x (x1, x2) are in H:M:S or decimal degrees (not decimal hours).
y (y1, y2) are in D:M:S or decimal degrees.

Note that you can not use a space ‘ ‘ instead of ‘:’ in H:M:S and D:M:S. ‘ ‘ is used as delimiter between the coordinates. 

Decimal numbers (e.g. 23.4) are always interpreted as degrees even if they represent the RA in FK5 or FK4. But if RA, Dec are specified as H:M:S D:M:S then the H:M:S is interpreted as hours, i.e. in FK5 and FK4 10:00:00.0 10:00:00 is the same as 150.0 10.0radiusRadius in degrees coordSysCoordinate system name: FK5, FK4, GAL, SLOAN, ECL are currently supported. 

Example

  10:20:30.0 15:00:0.0 11:20:30.0 25:00:0.0 FK5

Excluding Areas

Rectangles and circles that should be excluded from the survey can be defined by adding a backslash “\” at the beginning of the line.

A tile is excluded from the survey if its “lower right” pointing (i.e. pointing with min RA, min Dec in the tile) is inside a specified excluded rectangle/circle or inside a previously include rectangle/circle.

Example

  \ 10:50:30.0 20:00:0.0 11:10:30.0 21:30:0.0 FK5

Treatment of Overlaps into Excluded Areas

[From 05B on,] there is a parameter INCLUDE_OVERLAP in the sdt configuration file. This property specifies how excluded survey areas (specified with a leading back slash in the survey area field) are treated. If INCLUDE_OVERLAP=true is set then tiles which lie partially in included survey areas and partially in excluded survey areas are included. Otherwise (INCLUDE_OVERLAP=false) they are excluded. 

Incomplete Tiles

[As of 05B,] incomplete tiles are no longer added to the pointing list. If there are insufficient guide stars for all pawprints in a tile then the whole tile is left blank. This fixes the bug which caused tiles and MSB to be “out of step” (i.e. MSB and tile boundaries were not the same).

Selecting a catalog

There is a catalog choice box underneath the survey areas text box.

Local USNO catalog

The Survey Definition Tool can read locally installed USNO catalogs. The SDT was tested with USNO-A2.0. If you would like to use a local USNO installation then specify the path to its directory in the sdt/cfg/sdt.cfg file by editing the following entries:

# Path of the local (binary) installation of the USNO 
catalog
# (or any catalog that uses the USNO binary format 
plus acceleration files.)
# This should point to the directory containing the 
zone*.cat and zone*.acc files.
USNO_DIR=

# The SDT will use USNO_DIR_WIN 
instead of USNO_DIR if it runs under Windows
USNO_DIR_WIN=U:\\oxnaMfo\\USNO-A2.0_lt17

# Name under 
which this catalog should be added to the catalog choice box
USNO_NAME=

The USNO_NAME corresponds to the “long_name” in catalog defined in skycat.cfg files (see below) and is used in the catalog choice box.

You might have one USNO installation which is accessible from UNIX/Linux as well as Windows but under different path names. Both paths can be specified using USNO_DIR and USNO_DIR_WIN. This means a single SDT installation with one sdt/cfg/sdt.cfg can be used for both UNIX/Linux and Windows. Only their start-up scripts differ: sdt/bin/sdt for UNIX/Linux and sdt/bin/sdt.bat for Windows. There is a href=”http://www.nofs.navy.mil/projects/pmm/a.response”> description of how to download USNO-A2.0 via ftp but note that due to the limited speed of file access in Java using a locally installed binary USNO catalog is actually slower than using an online GAIA/SkyCat catalog. This may be fixed in the future.

GAIA/SkyCat/JSky catalogs (online and local)

By default the entries of serv_type: catalog contained in the standard skycat.cfg file were included in the skycat.cfg distributed with this SDT. Not all of them will be suitable as guide star catalogs though. These catalogs will appear in the catalog choice box of the SDT.

Adding other catalogs

In principle the SDT can read any catalog that can be read by tools such as GAIA and JSkyCat. Adding a new catalog can be done as follows:

  1. Create/copy/edit a skycat.cfg file such as ~/.skycat/skycat.cfg or sdt/cfg/skycat.cfg in this SDT distribution. 
  2. Put all the catalogs you want to use into the skycat.cfg file. 
  3. Edit the following entry in the sdt/cfg/sdt.cfg file of this SDT distribution# List of catalogs used by JSky/JSkyCat/Skycat/GAIA.
    # Do not use “~” in the path.
    jsky.catalog.skycat.config=../cfg/skycat.cfgso that the value of jsky.catalog.skycat.config is the path of the skycat.cfg you want to use. 
  4. GAIA/SkyCat/JSky catalogs can be online as well as in a local file conforming with the GAIA/SkyCat/JSky catalog convention but a local GAIA/SkyCat/JSky catalog is not the same as the local binary USNO catalog installation described above. I have not tested the use of local GAIA/SkyCat/JSky catalogs. Let me know if you have problems using them.

Generating telescope pointings and allocating guide stars

Click on the “Start” button. Two windows will pop up:

Survey Areas Display

The survey areas as defined in the survey areas text box are displayed in light green. The algorithm tries to retrieve suitable guide stars tile by tile, pointing by pointing. As soon as a guide star has been found for a pointing the pointing is displayed as pink dot. This pointing is provisional until guide stars for all the pointings in the tile have been found. Then the pointings become permanent and are displayed in black. Note that this display is scaled so for very large survey areas so that the dots representing the pointing might appear merged together.

Any changes to the Survey Areas definition in the text box will reset to the SDT and delete all the pointings created. Make sure you save your results before changing the Survey Areas.

By default the 4 WFCAM IR detectors are displayed for each of the pointings. This can be switched off by setting

WFCAM_FOOTPRINT_DISPLAY=false

in the sdt/cfg/sdt.cfg file. It is possible that you have to re-start to SDT before this comes into effect.

Autoguider footprint display

While the SDT is filling the survey areas with pointings it searches the selected catalog for suitable guide stars. The catalog entries and the autoguider footprint are displayed while this process goes on. The following colour coding is used:

Catalog entries

Autoguider footprint display background color

Guide star selection criteria

In order to select guide stars that can be used for all jitter and microstep pattern positions it is important that the AUTOGUIDER_WIDTH and AUTOGUIDER_HEIGHT specified in the sdt/cfg/sdt.cfg file are reduced accordingly:

  AUTOGUIDER_WIDTH  = total_autoguider_width - 2√2 max_xy_offset
  AUTOGUIDER_HEIGHT = total_autoguider_width - 2√2 max_xy_offset

where max_xy_offset is the same in both of the above equations. It is the maximum offset (jitter + microstep) from the telescope base position in either x or y (RA or Dec) direction (whichever is greater). Before subtracting it max_xy_offset is multiplied by 2 because the autoguider CCD is centred around the base position and its valid area must be decreased by the same amount on either side and it is additionally multiplied by √2 because the autoguider CCD is diamond shaped, i.e. AUTOGUIDER_WIDTH and AUTOGUIDER_HEIGHT are measured at an angle of 45 degrees compared to the RA, Dec coordinates in which max_xy_offset is measured.

The default settings are

  AUTOGUIDER_WIDTH  = 265.1 - 2√2 * 5.0 ≈ 250.0
  AUTOGUIDER_HEIGHT = 257.8 - 2√2 * 5.0 ≈ 243.0

This allows offsets in x and y (RA and Dec) direction of up to ±5.0 arcseconds. The values are rounded to the integer below the actual value. Using these sighly smaller values should prevent guiding on the edge of the CCD.

The SDT considers all objects with magnitudes between GUIDE_MIN_MAG and GUIDE_MAX_MAG that are not closer than GUIDE_MIN_DIST to the next object in the catalog. (See Changing the configuration.) Out of these objects it picks the brightest object. From 05B on, there is a DELTA_MAG parameter which will allow the selection of the brighter of two close stars if the magnitude difference is sufficiently large.

Suppressing guide star allocation

For testing the generation of pointings and to look at the general layout of survey areas it can be useful to switch the guide star allocation off. To do that set SKIP_GUIDE_STARS=true in the sdt/cfg/sdt.cfg file. You may have to re-start to SDT before this comes into effect.

Administrative information

The fields Title, PI, Country, Project ID are copied from the Science Program Node in the template Science Program to the Science Program Node in the generated Science Program.

Saving the results

Once the SDT has finished filling the survey areas the user is prompted to save them and the pointings to a file. This is done by using the usual “File” -> “Save” or “File” -> “Save As …” menu. A file with the suffix “*.sdt” should be used.

Interrupting the generation of telescope pointings

The generation of telescope pointings can be interrupted at any time using the “Stop” button of the online download dialog with progress bar when using an (online) GAIA/SkyCat/JSky catalog. Note that sometimes this button has to be hit repeatedly until the catalog choice box and the “Start” button in the main window become enabled again.

When the local binary USNO catalog installation is used, the “Stop” button in the main window should be used to interrupt the generation of telescope pointings.

After hitting the “Stop” button it is possible to save intermediate results to the file in the same way as described above for final results. The file can later be opened again using the “File” -> “Open” menu. The generation of telescope pointings can then be resumed where it had stopped before. A file with suffix “.sdt” should be used.

Exporting the results to MSBs for use in the Observation Preparation Tool (OT)

Refer to the online documentation for the UKIRT OT. Here we list the  operations you will need to complete to export your survey to a template MSB, and then discuss the ways in which different templates are treated by the export process. 

First, create a template MSB in the OT and save it as a Science Program. (Make sure that the MSB is directly under the Science Program node and not hidden in an “AND” or “OR” folder.) The first MSB found as a child node of the Science Program node is used as the template MSB by the SDT.

  1. In the SDT, select the “File” -> “Export to OT …” menu. 
  2. The first file selection dialog that appears is used to select the OT Science Program XML file that contains the template MSB. 
  3. The second file selection dialog allows the user to name a new OT Science Program XML file into which the generated MSBs are saved. OT Science Program files use an XML format and should be saved using the file suffix “.xml”.

NOTE the order of the file naming above. You do not need to give the name of the saved .sdt file when generating the overall programme from the template – the two file dialogues ask only for the name of the template xml file (which you should have created already) and the name of the final science programme you want generated.

Survey Containers in a template MSB

Survey Containers are used to store multiple targets which make up tiles and surveys.

A template MSB can contain a single Survey Container or multiple Survey Containers or no Survey Container at all. (In the latter case the SDT will automatically add a Survey Container to each generated MSB.)

The survey target list of a Survey Container inside a template MSB should be left as it is by the user, so that it is more or less empty apart from the one (0, 0) dummy target that is in every newly created Survey Container and that will later be removed by the SDT. The survey targets are filled in by the SDT (in the Survey Containers of the generated MSBs).

Option 1 – If there is no Survey Container in the template MSB then the SDT creates one and moves all the components other than the Scheduling Constraints and Site Quality components into the Survey Container:

Option 2 – If there is a single Survey Container in the template MSB then the SDT simply copies the whole template MSB when creating the generated MSBs and fills the Survey Container with survey targets:

It should not make much difference whether a single Survey Container is used in the template MSB or none. Putting a single Survey Container in the template MSB allows more control over how the generated MSBs will look like because the SDT will maintain the layout of the template MSB when it creates the generated MSBs. 

Template MSB with multiple Survey Containers

Template MSBs with multiple Survey Containers can be used to observe several targets with the same configuration (e.g. same filters) before changing the configuration and observing the same targets again, and so on, all within the same generated MSB (see figure below).

Automatic MSB Numbering

From 05B on, the SDT will automatically add an index number to the title of each generated MSB, to assist with identification during survey execution. For example, if the template MSB looks like this:

then the generated survey might look like this:

In this example, the seed MSB has an index number (:23) at the end of its title. If this is omitted, then numbering would commence at 1.

Additional features.

View Areas

There is an “Options” -> “View Areas” menu which allows you to view the survey areas specified in the text box without starting the process of generating the pointings and allocating the guide stars.

Help

The help menu displays this HTML document.

Changing the configuration

Many configuration details can be changed. They are specified in the sdt/cfg directory of this distribution. Make sure you make a copy of the original directory before changing things. Most properties are specified in the sdt/cfg/sdt.cfg file. The default settings are

BASE_TAG=Base
GUIDE_TAG=GUIDE
PRIMITIVE_PATTERN=pattern.cfg
AUTOGUIDER_WIDTH  = 265.1
AUTOGUIDER_HEIGHT = 257.8
AUTOGUIDER_ANGLE  = 45.0
USNO_DIR=
USNO_DIR_WIN=
USNO_NAME=
DEFAULT_CATALOG_LONG_NAME=USNO at ESO
jsky.catalog.skycat.config=../cfg/skycat.cfg
GUIDE_MIN_MAG  = 4.0
GUIDE_MAX_MAG  = 17.0
GUIDE_MIN_DIST = 7.0
GUIDE_QUERY_DISPLAY=true
HELP_URL = help/index.html
MSB_DURATION = 30
SKIP_GUIDE_STARS=false
WFCAM_FOOTPRINT_DISPLAY=true

An explanation of all these properties is provided in the sdt/cfg/sdt.cfg file. Of these BASE_TAG, GUIDE_TAG should remain unchanged for use with the ORAC/OMP/OT system at UKIRT. AUTOGUIDER_WIDTH, AUTOGUIDER_WIDTH, AUTOGUIDER_ANGLE may change in future versions of the SDT (to avoid guiding on the edge of the detector and depending on the exact angle but also to make sure that a guide star is still in range when jittering and microstepping) but once these values have been established they should be left unchanged for use with WFCAM. The SDT has not recently been tested with GUIDE_QUERY_DISPLAY=false. HELP_URL should probably remain unchanged although a version of this might be made available online which could be kept more up to date. In that case HELP_URL could be set to the online version.

If you want to change jsky.catalog.skycat.config make sure you know what you are doing (i.e. you have edited skycat.cfg files before).

The PRIMITIVE_PATTERN property is described below.

Note that although the files pattern.cfg and ../cfg/skycat.cfg are in the same directory (sdt/cfg) their paths have to be specified differently. PRIMITIVE_PATTERN is specified relative to the sdt/cfg directory whereas jsky.catalog.skycat.config must be specified either as an absolute path or relative to the sdt/bin directory. This allows users to specify other skycat.cfgfiles they might have on their computers. But remember not to use the “~” when specifying the ~/.skycat/skycat.cfg or ~/.skycat/skycat.cfg in your home directory. Use the full path.

Most other properties are set to ad hoc values and can be changed by users at will.

Primitive Pattern (Tile Configuration)

To change the primitive pattern (tile configuration) you can either make multiple copies of sdt/cfg/pattern.cfg, modify them and then set PRIMITIVE_PATTERN in sdt/cfg/sdt.cfg to the version you want or you can leave PRIMITIVE_PATTERN=pattern.cfg in sdt/cfg/sdt.cfg unchanged and edit sdt/cfg/pattern.cfg directly. You can edit the following parameters:

OFFSETS_X = 0 792.684
OFFSETS_Y = 0 792.684
NEXT_PATTERN_X = 3170.736
NEXT_PATTERN_Y = 3170.736

Their meaning is described in the file itself. The default values are used for a filled in WFCAM tile.

The following should remain fixed (once the final relative positions of the WFCAM detector arrays have been measured). They specify the dimensions of the bounding rectangle of a single 4-detector WFCAM footprint:

DETECTOR_GROUP_WIDTH  = 2402.568
DETECTOR_GROUP_HEIGHT = 2402.568

Missing features and known bugs

  1. Faulty backtracking display (An additional window pops up during backtracking which should display the backtracking position. It currently does not work properly most of the time but it is not particularly useful anyway. It was intended to be a debugging feature. Ignore it for now.).

OT Telescope Position Editor

You can view the WFCAM multi-detector autoguider footprints projected on a digitized sky image by using the OT Telescope Position Editor (GAIA-like tool).

  • Select a Survey Target in the in the OT’s Survey Container. 
  • Select the “Target Information” tab and click on the “Plot…” button. (Alternatively, click on the “Image” button on the Science Program window.) 
  • To see the autoguider footprint, click on the “WFCAM AG” button. 
  • To see the IR multi-detector footprint select the WFCAM instrument component in the Science Program tree, then select “View” -> “Scale” -> 0.2 from the TPE menu and finally click on the “Sci Area” button of the TPE.