UKIRT OBSERVING PREPARATION

  Startup screens

The File Menus

  The science program window [tour]

 The Template Library [tour]
 Minimum schedulable blocks
 Science Program Elements
 Inheritance
 Administrative components: Scheduling and Site Quality Components, and Priorities

 Scheduling constraints
 Site quality constraints
 Using inheritance with administrative components
 Priorities

  Example - a complete science program [tour]

  Specifying Moving Objects
  Allowing for Proper Motion

  Use of the Position Editor [tour]

  IMPORTANT - Program Documentation
   Observer notes - what NOT to do
  CHECKLIST - what to look for in a typical program
  Estimates of execution time
   Saving and Submitting your Program
   Click-by-click worked example

  AND and OR Logic
  Drag and Drop
  Generating a program from a single MSB and a catalogue on file
  Usage through a firewall
   Specifying Spectroscopic Standard Stars
   Guide stars and acquisition scenarios
   (Links to) Instrument-specific Pages

    Updates in November 2007 version

    Updates in April 2006 version
    Updates in 05A version

    Updates in 04A version

  Known bugs

I. Introduction

II. The Observing Tool

Startup screens

When you run the OT (under UNIX, type ukirtot in an xterm) you will see a splash screen which gives authorship etc.; dismiss this and you will be left with the OT main window:

When starting afresh, most of the useful actions reside under the "file" menu.

File menu Item	Function
New Program	Creates a new science program. This is the first thing you'll do when starting from scratch.
New Library	Ignore this; it is for UKIRT staff use only.
Open	Read in a science program file stored locally on disk. Initially, your science program will be stored locally; only when it is complete and validated will you submit to the database.
Open...library	These entries pop open windows onto the UKIRT libraries which store recommended sequences and standard stars.

---

The File Menus

A word of caution - both the File menus and the Database menus differ between the OT main window and the Science Program window. Here are the respective file menus:

OT main window file menu	Science Program file menu

So note that (sensibly, given the ability to have more than one science program open at a time) the file menu which contains "Save" and "Save as..." is the one on the Science Program window. Similarly, the Database menu on the OT main window contains only "Fetch", while the Database menu on the Science Program window contains only "Store".

---

Tour: the Science Program window

Select "New Program" to create a new program. This produces a window like the following (click on the image for a description of the various component parts). The main areas are

1. the menu and general tool bars at the top
2. the component tool bar down the lefthand side
3. the program display panel in the middle
4. the editor panel on the right

If you don't see exactly the above when creating a science program, look under the "View" menu and alter the settings which control whether words, pictures or both are used to display the toolbars.

Initially, the only thing in your program panel is a "Science Program" line. You will add to the program later. For now, take the time to fill in its administrative details in the Science Program editor panel on the right. The most important field here is the Project ID field. You have to get this right, or you will not be able to submit your program to the summit database. Your project ID was assigned when you submitted your proposal for telescope time. It is of the form u/yys/ followed by the proposal number (yys indicate the semester - e.g. 07B). You can also find your proposal number in our web page of time allocations. Finally, note that the program itself calculates an estimate of the total time required and displays this in the administration panel.

Tour: The UKIRT Template Libraries

While it is possible to build up observing sequences from scratch, we strongly recommend that you adapt one of the many "library sequences" found in the UKIRT template libraries, which are found on the main file menu. As an example, the UIST template library window is shown below, with all the libraries in their initial non-expanded state. Click on the image for a short tour of the library contents:

Typically, setting up your UKIRT program involves opening the appropriate library, finding within it a sequence which matches your requirements, and copy/pasting or drag/dropping it into your new science program; then you are in a position to alter instrument configurations, target lists and to document the program for the observer's benefit. Refer back to the Science program window tour for the locations of the cut, copy and paste buttons (or look at the figure above, where you'll see three buttons starting with the scissors). An example of a more complete science program is given below, but first we'll introduce some of the essential building blocks.

---

Minimum Schedulable Blocks

The basic quantum of observing, both in classical and flexible scheduling (though more natural to think of in flexing), is the "minimum schedulable block". This is the smallest part of the program which is complete, fully-reducible and thus stands alone. In most cases, an MSB will  be executed at the telescope in its entirety. For example, a target observation would be incomplete without suitable calibrations, and so one might define the smallest spectroscopic MSB as comprising the spectrum of a target, combined with sufficient flats, arcs and a standard star to be fully reducible. For efficiency, the observing system at the summit allows the observer to skip calibrations if not required (e.g. if executing a number of similar MSBs which can share an existing calibration). Note that the UKIRT template library contains MSBs, not just Observations, so you will naturally be building up from these.

You should aim to produce a science program consisting of suitably-titled MSBs. The title will appear in the query tool when observing at the telescope, so try to make your titles as descriptive as possible.

---

Science program elements

MSBs within your science program specify observing conditions, instrument configurations, telescope offset sequences and data reduction recipes for all the observations you have been given time to carry out. They do this through combinations of the following elements:

Program icon	Designated item
	An "Observation" (e.g. of a target or a standard star)
	A "Component" - in this case an Instrument component. These are used to "set scenes" (in the illustrated case, one or more instrument configurations which will apply within an Observation).
	A "Sequence" - this contains the actions undertaken in an Observation - for example, offsetting the telescope and taking data at each offset point. If you omit a Sequence, no amount of configuration components will cause anything to actually happen at the telescope.
	An "Iterator" - these cause either the instrument, or the telescope, to loop through a series of different configurations (in the case of the telescope, the loop is through Offset positions). Everything inside the iterator is repeated for each of its settings.
	An "Observe" - Each Observe causes one data file to be produced. If there's no Observe in your sequence, the telescope may well offset and the instrument may well set to a configuration, but no data will result.

Note that you will not, normally, have to insert any of the above into your program manually, because you will start from the library sequences which incorporate all the commonly-used data acquisition methods.

To read a science program you have to understand its hierarchy. An example:

Here, everything is more indented than the Science Program icon, therefore everything is part of the Science Program. By contrast, the two "dry target" MSBs are at the same indent level, so are independent of each other within the program.  The second MSB is not "expanded" - its contents are hidden pending a click on the lever to its left. Within the first MSB, and hence indented further, is an Observation,which itself contains a Target component, an Instrument component and a Sequence (all three of these are at the same indent relative to the Observation). The sequence in turn contains an offset iteratorwhich "contains" an Observe. Recall that the Sequence is just a formality, indicating that everything within it is executable. The Iterator, however, is a loop - everything within it (usually but not always this is just an Observe)is done for every setting of the telescope offset iterator. When executed at the telescope, this particular Observation sets the instrument up, moves to a target, then takes data frames at each position of an offset pattern.

---

Inheritance

The observing tool allows MSBs to inherit properties from the program environment they find themselves in. For example, if a site quality component is present at the top of a science program (as in the example above), then none of the MSBs within the program need to have a site-quality component of their own; they inherit it from this global one. Conversely, a site-quality component within an MSB "trumps" such a global component. This also applies to Target components; a target given at the top of an MSB, outside the scope of Flat, Standard and Object Observations, will apply to all three (so when the flat/arc observation is run, the telescope will slew to your science target). This may or may not be what you intend; check the logic carefully (obviously in this example you would also want to override the global target in the standard-star Observation).

Scheduling constraints

Note that most of the library MSBs do not contain scheduling constraints - this is because most programmes require the same constraints throughout. Therefore, once you have created a new program, the normal first step is to select a Scheduling Constraints component from the "Component" item on the left-hand toolbar.

Site Quality

Again, it is normal for the same site quality requirement to apply to all MSBs in a program, and so these components are not normally part of the library MSBs. The normal second step is therefore to insert one of these components into the top of the program (along with the scheduling constraints). This component is found under the "Component" list also.

Using inheritance with the administrative components

In this (schematic and incomplete) example, the site quality component at the top applies to the three MSBs which don't have their own; only "wet target" overrides this global component. To insert a Site Quality (or Scheduling Constraints) into a given MSB, expand the MSB and highlight its title line (as in the figure here), then select the required component from the "Component" list on the left hand toolbar in the Program window.

Priority

Setting priority on a given MSB. Here the first MSB in the programme has been given just below medium priority (55).

Setting priority on all MSBs: Click the "Prioritize" button (top right of this image). This assigns a priority between 1 and 99 to all MSBs in the programme, working from the top down.

Tour: A more complete science program

The figure below shows a science program which is fairly straightforward and a reasonable approximation to what one might expect to have to set up for either classical or flexible observing. There are ways to give programs "Logic" (different combinations of MSBs, etc.) - these are discussed in "Advanced Topics" at the end of this document, and your support scientist will be happy to help with questions in this area. Most programs will not need to use this type of logic, and supplying a flat set of MSBs as in this example will be fine.

Click the image to take the tour

Moving Objects

Moving objects (excepting planets and other bodies which are accessible in the pull down menu in the Target component) are accommodated via orbital elements. The format of these elements is fairly specific. An example is given in the figure below.

Comet Tempel-1: orbital elements

Top: Orbital elements as found, in this example, on the NASA JPL NEO orbit diagrams page
Bottom: Elements specified in the Target Component Elements tab. Note the different format for Epoch and Time of Perihelion Passage, in particular.

The OT can use the Horizons database to resolve a given minor planet's name into elements. An example is given below.

Name resolution for moving objects: When "Orbital elements" is the selected Target Type, the "Resolve name" button queries the Horizons database for elements. Note that the name format is somewhat picky and you may have to use trial and error to get something that works for a particular target.

Allowing for Proper Motion

Entries for the RA and Declination proper motion rates (in milliarcseconds per year) can be made in your target component.

Proper motion entered as milliarcseconds per year in the target component. These values are taken into account when slewing the telescope.

---

Tour: Using the Position Editor

The position editor is used to set up guide stars, science field orientations (slit angles etc.) and display catalogues of sources in the field of your observations. It is started up either by clicking the "plot" button in the target component page, or by clicking the "image" button on the main toolbar, as described in the tour of the science program window, above. Click on the image below to take a tour of the position editor's facilities.

 

By default the position editor loads images from the digitized sky survey. However it can also load any FITS image with an appropriate WCS, from the File menu; this has entries for either files on disk, or URLs which point to fits files. If, for example, you want to import a SCUBA map in NDF format, convert it to FITS by using the starlink convert utility with the following arguments:

convert 
ndf2fits encoding=FITS-IRAF bitpix=32 comp=D

---

Catalogues

The OT has access to a wide variety of stellar and nonstellar catalogues, including the Guide Star Catalogue, USNO, NED etc. These are all accessible under the Position Editor's "Catalog" menu, using item "Catalogs".  Select your required catalogue (from the nearest accessible server) and the stars will be plotted on the PE display. To browse the catalogue in text form, run the Catalog...Browse function. The Browse window is shown below. If you click on a star in the PE display, the selected star will be highlighted in the table (as shown below).

The catalogue browser window. Note that the column headings are "sort" buttons - here we have elected to sort by magnitude.

---

IMPORTANT - Program Documentation

A simple program note in the note editor panel. Show to Observer has been ticked and suitable entries have been made in the four resulting text fields. If you have more than one "Show to Observer" note, the contents will be concatenated and all displayed at the summit. Since the observer will not have time to read long screeds of information during the course of observing, please make sure you do not overload them this way.

Observer notes - what NOT to do

CHECKLIST - What to look out for in a Typical Program

1. The MSB's contents represent a complete, calibratable observation of a science target. In most cases this means that all MSBs must contain Observations of a Standard Star, though these observations can be flagged as Optional (as described previously) to allow the observer to skip them if they are sure that a suitable standard already exists. Note that time observing standards from your MSBs is charged to your program, so it makes sense to use this flag !
2. The MSB is well-documented. This means that you have used both informative notes within the details of the Observations, plus "Show to Observer" notes which will give the observer a summary of what you expect. The JAC will arrange a web page with some typical data in your observing mode, but you should be as clear as possible in the notes which pop up for observers what your expectations are and whatever issues you foresee.  Your support astronomer will vet your program as it enters the database, and will veto your observations if they are insufficiently well-documented. 
3. Instrument components are consistent from observation to observation within the MSB (this is usually, though not always, the intention). Note that for most instruments, the instrument component is global to the MSB (see "Inheritance") and so does not need to be copied into each Observation.  
4. flats and arcs, if present, have all had their settings set to the default for the instrument configuration chosen (beware of making a small change, for example altering a slit width, and finding that your flats are overexposed).
5. darks, if present, have had their settings set to the detault for the instrument configuration chosen. For example, a change in the estimated magnitude of an imaging standard can change the exposure time and this must be reflected in the dark.
   
6. target list components have been set up, with guide stars in the case of faint objects
   

Estimates of Execution Time

• Observes can be set to a number of repeats; generally this is one for UKIRT instruments such as Michelle and UIST.

• Repeat iterators specify the number of times the Observes within them are carried out. 

• Observations show you the estimated time of the sequence they contain.
  

• MSBs give you the estimated time of the Observations they contain - in this case the science observation plus any calibrations observation. To be clear: this is the estimated time of that single MSB.

• Science Programs give you the estimated time of all MSBs they contain, including the number of repeats. So if you have a 1hr MSB and you set the MSB counter to 2, your MSB estimated time will be 1hr and your Science Program time will show 2hrs.

Saving and Submitting your Program

Tip: while editing your science program, its title is displayed in italics, but it switches to normal font upon saving. When you edit any component of your Science Program its title changes font to indicate that you need to save your work.

Click-by-click worked example

Action	Menus, clicks etc.	Image	Comment
Create a blank science program	Main File...New
Open the appropriate library	Main File...<library>
Insert and fill in Site Quality component	From the left tool bar in the science program window		This is the pull-down menu under the "component" button
Insert and fill in (if necessary) Scheduling constraints component	From the same components list.		The science program panel after insering the two admin components
Find a library MSB which matches your needs			We're doing a point source observation.
Copy and Paste into the program area	Highlight the appropriate MSB by clicking on it once. Then click "copy", move to the main program, highlight the item after which you want it to appear, and click "paste"		Alternatively, drag and drop - see the "Advanced Topics and Usage notes" in the main document
Fill in the administrative details in the main program window	Click on "Science Program" and use the editor panel which appears on the right		The title entered will be reflected at the top of the program display panel also. See the next step.
Give the first MSB a name	Highlight the MSB and type into the MSB editor text field.		The title entered replaces the MSB name given in the library.
Open the MSB up and enter target details	Highlight the global target component - close to the top of the MSB, then use the editor panel on the right		You can use name resolution after typing in the target name here. Beware of this in the case of extragalactic objects, where there can be big differences between, e.g. Radio and optical positions.
Set the instrument configuration	Highlight the global instrument component - usually second item in the library MSB		All UKIRT instruments have source brightness fields from which suitable settings are derived.
Default the flat and arc settings	Highlight the flat component, and click "Use defaults" in the editor pane. Then do the same for the Arc.		This is a spectroscopy-specific example but similar operations are necessary for short-wave imaging (setting the DARK exposure time).
Enter standard star name and resolve it	Highlight the standard star target info and enter the name, then resolve.		Note that since semester 03B, name resolution no longer replaces the name you entered with the Simbad name.
Set a suitable imaging-acquisition exposure time	Highlight the acquisition eye, then follow the instructions in the NOTE just above it.		This is a UIST spectroscopy-specific operation which does not apply to other observing modes or instruments.
Ensure that the Standard Star exposure time is correctly set	Highlight the UIST iterator in the sequence and select the target magnitude.		This is an iterator. It's needed because the UIST component is global to the MSB but the Standard will (usually) be brighter than the target.
Set the acquisition exposure time for the science target	As two steps above but in the Target Observation rather than the Standard Star Observation.
Check that the science target offsets are correct.			The default settings move the target by integral number of detector rows but may be too small for extended targets.
SUMMARY At this point the program is broadly ready to go, though if you click the Validation button you will find that you have forgotten to include a "Show to Observer" note, and that guide stars remain to be set up. Once those are done, you are ready to either clone the MSB into a complete program, or copy it and edit new targets in manually, or whatever else your programme demands.

III. Advanced Topics and Usage Notes

Here we outline some facilities which are either more advanced than a typical program is likely to require, or more than the beginner user might expect to use.

AND and OR logic

Most programs will be catered for by simply creating a set of MSBs and at most specifying their relative priorities and perhaps some scheduling information. However, more complex programs can be built up using the logic provided by "AND" and "OR" folders. The basic function of these folders is as follows:

Allows you to select one or more (default is one) MSBs from a list. If the default is used, then once an MSB from the folder has been done, the rest are marked as unavailable.

Allows you to simply group MSBs together. In general, ANDs make most sense when contained within an OR folder, allowing you to have two completely separate programs (potentially with many MSBs each), only one of which gets done. For example, you may have a set of targets in two separate star-forming regions, don't need data in both but do need one region to be completed. ANDs inside an OR is the way to do this.

An example of the use of these folders:

Here, for the sake of illustration, a PI has managed to convince the TAG that there is merit in granting time to two rather different projects under the same banner. The resulting science program contains two OR folders. These do not interact with one another; completing the first OR doesn't mean that the second OR (which is at the same indent level) does not get done. All being well, the PI will obtain data on both sub-projects; the details of what they get is catered for by the AND and OR logic. Within the (simpler) second OR folder, the PI has asked for two out of three MSBs to be done. Depending on the timing, these could be Oph-elias 29 and Oph-BK44, or some other pair from the three. The important point is that once two are done, the third is marked as unavailable. Selection of the number to do is done in the OR folder's window. Within the first OR folder, the PI has required only one of three things to happen: either (i) the single MSB on NGC4594 knot 3, or (ii) one of the two programs on knots in NGC4565 or NGC4321. So the minute an MSB from the NGC4565 program is done, both the NGC4594 single MSB and the NGC4321 program is marked as invalid.

Formally:

ANDs were designed specifically to go inside ORs (to allow you to group MSBs) but are also available to group MSBs in general (to allow them to share instrument configs etc).

Folder type	Can contain
	ANDs, MSBs, Observations or general components (inheritance works in an OR folder)
	Anything except an OR or AND

Drag and drop

What happens when you drop a dragged item is indicated by an arrow symbol:

	Dropping a dragged item (for example, a target component) with the arrow pointing diagonally means that it is dropped at one indent level higher than, and therefore becomes a part of, the highlighted item (in this case, the MSB).
	Dropping a dragged item (for example, an Observation) with the arrow pointing vertically down means that it is inserted into the science program at the same indent level as the highlighted item (in this case, the MSB).

You can control which of the symbols you get by horizontal movements of the dragging cursor; in the above example, you would find that the symbol changed as the cursor was dragged past the "B" in "MSB Folder (1X)".

---

Generating a Program from a Single MSB and a Catalogue on File

Start with a science program which contains a template MSB with a blank target component (for example, a template MSB you have retrieved from the UFTI library). Your catalog file should be of the format:

PKS0106         01 08 38.771 + 01 35 00.32 RJ
3C84            03 19 48.160 + 41 30 42.10 RJ
3C120           04 33 11.096 + 05 21 15.62 RJ
PKS0438         04 40 17.180 - 43 33 08.60 RJ

Under the edit menu (in the Science Program window), there is an option called "Replicate from catalog". Choose this action and you will be asked for the location of the catalog file. Once you have done this, the OT will contact our site and after a short delay will pop up a new science program window containing multiple MSBs. So if you had an MSB with one blank target component and a catalog file with 12 sources, you will get back a science program with 12 MSBs, whose target components have been filled in using the information from your catalog.

Of course you should tweak the MSBs further, such as giving them more informative titles and tweaking the number of integrations on each source.

Usage through a firewall

Specifying Spectroscopic Standard Stars

1. Determine an RA appropriate for the mid-point of your observations by subtracting half the target observation time from your target RA.  e.g. If your target has RA of 12 34 56 and your total observation time on target is 40 minutes, then your standard should have RA ~ 12h 15m.
2. Look for a standard with the RA calculated as above and a similar Declination to your target, using either the UKIRT Standard star lists, the Standard star library in the OT, or the Gemini Standard star finder. Try to get as close as possible but at least within about 10 minutes in time for the RA and 10 degrees for the Declination.  F stars are preferable to G or A as A have strong hydrogen lines and G may have molecular bands.  A types are preferable to G if there are no suitable F stars.  

Guide stars and acquisition scenarios

Instrument-Specific Pages

IV. Release-Specific Notes

Updates in November 2007 version

• New standards for Y band (UFTI & UIST)
  
• Corrected display of IRPOL orientation in the position editor
• In the UIST spectroscopy template library, slides in the offset iterator for point source spectroscopy now move the source into the upper half of the array, where the array sensitivity (QE) is slightly higher.
  

Updates in April 2006 version

• Assorted fixes to Science Program Validation.

• CGS4 and UIST slit position angles are rounded to a single decimal place.

• Upgrade to JSky 2.5

• It is no longer possible to accidently put sequences before components causing invalid XML to be produced.

• Copying survey containers get properly cloned.

• Changes to the X-offsets of RA get applied as [ X-offset x cos( Dec ) ]

• When targetting, the RA and Dec no longer get corrupted causing drift.

• Initial removal of ODB and OM code.

• Removal of SERVER options on the command line as part of ODB code removal.

• XML Science Programs can now be opened from the command-line.

• When opening files locally, the default working directory is the directory the user is in when the OT started.

• Removal of OMP as an option as it is now the default, as a result the OT no longer supports SGML.

Updates in 05A version

• WFCAM components have been added.  This includes a WFCAM instrument component, and WFCAM calibration eye, microstep iterators and DR recipe components.

• Survey container added. This allows you to specify multiple targets in a single container.  This component also allows you to elect to only observe some number from the list of targets.  While it is primarily for use with the Survey Definition Tool, it can also be used on its own. It can either be placed at the top level of a science program  similar to an MSB), in which case it can contain at most 1 MSB (acting as an MSB iterator); or it can be placed inside an MSB and can contain any number of observations (acting as a target iterator).

• The target component now allows you to create "named skies".  That is,  at the bottom of the target component where you used to be able to select "GUIDE", you can now also add "SKY" and/or "SKY_GUIDE".  The sky position can input as either an absolute value, or as an offset from the  base.  If you don't want to use it, don't - in which case you can treat sky "eyes" just as you used to.  However, using them does allow some additional functionality (described below).  Each sky position specified will be called SKYn, where n is an integer starting at 0. Similarly there is a SKY_GUIDE which will allow you to guide on a patch of sky.  Again, this is primarily useful for survey work.

• The sky "eye" has changed to support the named skys.  If you don't specify a named sky in the target, this will have exactly the same behaviour as the old sky eye, though it will look different.  If you do specify a named sky, the GUI allows you to select which sky you want to observe.  Depending on how you defined the sky, its behaviour is somewhat different.  If you specify an absolute sky position, you will always go to that position.  If you specify it as an offset, then the three checkboxes on the user interface come into play.  These give you the following options:

• MSB's marked as REMOVED can now be UNREMOVED and their count is maintained.

• On the site quality component, a better explanation of the cloud and moon constraints is given, and a new constraint, J-Band sky brightness, is added.

• The 150 l/mm disperser has been removed from CGS4

• The chop settings tab on the target component has been disabled.

• Validation now uses an XML schema.  There may be some side-effects of this change which we have yet to uncover, and user feedback will be appreciated. Since this is a web service any changes will not require a new OT release.

• More than 1 observer note can now be specified (but they can not be put inside a sequence). At the summit, these notes are concatenated.
  

• Offset positions are now displayed around the position of the guide star as well as around the target. This helps when deciding whether a guide star will fall into an inaccessible area  Guide star offsets are displayed in blue. Highlight the offset iterator to display these offsets.

Updates in 04A version

• Time estimates now report both total time and time without calibrations (estimated time)

• Improved schema validation for both telescopes. Validation is now performed against the TOML schema over the web (Note:
  Failure of validation does not indicate that submission will fail). Note that to validate against the most recent criteria requires you to have a working network connection.
  
• Improved layout on various components - now requires at least Java version 1.4.1
• On start-up, we now check to ensure that the correct version of Java is being used
• On submission and retrieval to/from the database, pressing 'enter' after the password now behaves the same as pressing the "Commit" button.
  

Known Bugs