ANDICAM Multi-Observation Scripts Instructions

UNDER CONSTRUCTION. Thank you for your patience.  Please use this ANDICAM  Phase II menu for now.

SMARTS Consortium
Creating ANDICAM Multi-Observation Scripts

Updated: 2003 March 1

Table of Contents:

    * Overview
    * How to Create Multi-Observation Scripts
          o Step 1: Select Obs files to execute
          o Step 2: Prompt for Target Name?
          o Step 3: Enter the Script Filename
    * Example Multi-Observation Scripts

Overview

The ANDICAM is a 2-channel instrument with separately configurable CCD and IR cameras fed by a dichroic beam splitter. To enable efficient queue scheduling of observations, all ANDICAM data are acquired by means of Observation Template Files (or "obs files" for short) prepared by the astronomer. Obs files define "unit observations", specifying the instrument, detector, and target parameters and configurations needed to acquire a single observation.

In addition, astronomers can create simple Multi-Observation Scripts that are used to execute a sequence of obs files for a single target. There are two basic uses of Multi-Observation Scripts:

Complex Synoptic Observations:

    A "synoptic" program is here defined as one in which you wish to observe a relatively small number of targets many times over a long period of time. A "complex" synoptic program is one in which the target is to be observed through a number of different filters in a specific sequence. In this case, you would create separate single-target obs files for each exposure-time and filter combination required for a given target (and do so for each of your targets). After your obs files have been created, you make a set of multi-observation scripts that would be used to execute each of these obs files in the preferred sequence each time, including repeats, for each target. Examples are given below.

    Note that for standard single-target obs files, multi-observation scripts are optional, and should only be done if the observations are of particular complexity (e.g., many different exposure/filter combinations that must be executed in a particular sequence or a pattern of repeat observations required in a single continguous sequence). Don't make and submit multi-observation scripts if you don't really need them, as they do complicate the Phase II submission process, and are inappropriate for execution of just 1 or 2 single-target obs files.

Survey Observations:

    A "survey" project is broadly defined as one in which you wish to observe a number of targets in the same way in many filters only once (or at most a couple of times). In this case, having to create a number of separate single-target obs files for all of the targets quickly becomes a burden for both the astronomer (who has to create them all) and for the observers (who have to keep them organized). The "one obs file per observation per target" mode that works well for synoptic programs is clearly impractical for even medium-sized survey projects, especially if you want to observe each target in many filters.

    A better solution is to create a small set of generic multi-target obs files that contain exposure and filter settings, but do not specify the targets or their coordinates. A multi-observation script would then be created to execute these generic obs files for all of your targets, and the script would include the option to prompt the observer to enter the target name. Thus a single multi-observation script and a small set of generic obs files stands in for many separate obs files. The trade-off is that you must standardize exposure times, or divide your program into "long" and "short" exposure sequences and provide sets of generic obs files and associated multi-osbservation scripts for each. The examples section below discusses some strategy issues (a simple observing program is more likely to get executed than a very complex one). A separate target list with coordinates would be submitted with the Phase II instructions to round out your program submission.

    For submission of survey-style projects, use of multi-target obs files and multi-observation scripts is mandatory.

In general, multi-observation scripts are not useful if you have relatively simple programs (at most one or two obs files per target). The gain in using them comes with large numbers of targets, or large numbers of observations per target that must come in a specific sequence.

This document describes how to create multi-observation scripts for your observing program, and gives worked examples.

[Contents]
How to Create Multi-Observation Scripts

Multi-observation scripts are created using a webform accessed by logging into the Observing Preparation Tools pages (via the Phase II front page), and using the Project ID assigned to your project when it was approved for implementation and scheduling. Scripts are created after you have created the obs files for your program. Once you have made your multi-observation scripts, you will submit them along with your obs files as part of the Phase II Observing Program Submission.

There are two basic types of multi-observation script:

   1. Single-Target Scripts that execute a set of single-target obs files in a particular sequence, including repeats.

   2. Multi-Target Scripts that execute a set of generic multi-target obs files in a specific sequence for many different targets, each time prompting the observer to enter the target name.

Step 0: Create the set of observing template files

Multi-observation scripts are created after you create your basic set of observing template files for your program. If there are no obs files, the script creation form will not have anything to work with.

Step 1: Select obs files to execute

Each multi-observation script may execute up to 10 obs files in sequence. This includes repeat observations of a given obs file. the form presents you with a set of 10 pull-down boxes, the menu containing a list of all of the obs files you have currently in your project's working directory on this server.

The obs files you select will be executed in the order selected, top to bottom in the form. Blank selections are ignored). If you wish to execute a given obs file twice in sequence, it must be selected twice.

Step 2: Prompt for Target Name?

If the obs files selected above are generic multi-target obs files that do not contain target names or coordinates, then your script will need to prompt the observer to enter the target name before the obs files are executed. Check the box to create a prompt in the script. If you omit this, no object name will be put into the image headers or observing logs, making it impossible to know what was observed.

If instead your script is executing standard single-target obs files, leave this box unchecked. If you do check it, the observer will have to type something at the prompt, and then what is typed will be overridden by what is in the subsequent obs files.

Step 3: Enter the script filename

Finally, you need to provide a unique filename for your multi-observation script. It should be descriptive of the obs files it contains, and should be unique to your project insofar as possible, so generic names like "myscript" or "script1" are discouraged. Filenames that conflict with other programs will be renamed at the discretion of the queue manager.

The filename you give must not have a file extension appended. A file extension (.pro) will be automatically assigned by the system, and has a specific meaning to the data-taking system. Adding a file extension could result in a script that cannot execute.

Example Multi-Observation Scripts

Example 1: Multi-Filter Synpotic Observations

In this example, the program is to make nightly observations of the microlensing source OB03018. Two obs files have been prepared

    ob03018ih
    ob03018vh

and each night the target is to be observed in the sequence

    I+H
    V+H
    I+H

Using the form you would make 3 obs file selections, in order

    ob03018ih
    ob03018vh
    ob03018ih

and leave the other 7 entries blank.

Since this is a set of single-target observations, you would leave the "Prompt for Target Name?" check box blank, as having the observer type in the target name would be redundant and a waste of time, since the target name in the obs files proper would override whatever they type.

Since this script is for a specific target, you would select a simple filename, the target itself:

    ob03018

Which choice keeps the book-keeping simple for all concerned.

Example 2: Stellar Photometry Survey

This program is to acquire UBVRI and JHK images of a set of 200 low-mass stars from the 2MASS catalog. Since all of the stars are of comparable brightness, the same exposure times can be used for each star for the various filters. Since the H and K observations will take longer than J, we will double them up, taking J only with the most efficient R filter. The resulting set of 5 multi-target obs files is:

   2masslm_uk
   2masslm_bk
   2masslm_vh
   2masslm_ih
   2masslm_rj

Here we have used "2masslm" as the base name (for "2MASS Low Mass") and specified the filters used in each obs files.

Using the form you would make 5 obs file selections, in order

   2mass_uk
   2mass_bk
   2mass_vh
   2mass_rj
   2mass_ih

so that the optical imaging is acquired in the order UBVRI, and leave the other 5 entries blank.

Since this is a set of multi-target obs files, you would check the "Prompt for Target Name?" box. The observer will be prompted to enter the target name each time he/she executes the script.

Because this script is for many targets, a generic but suggestive name would be:

    2masslm

this choice is the same as the "root name" of the obs files, making the association between them, and the program proper, clear.

Example 3: Multiple Targets, but long & short exposures

In this example, you have a large number of quasars from the LBQS, but about half the targets require relatively long exposures (e.g., 300s at V) whiel the others are brighter targets that would saturate in this time and can be observed with shorter exposures (e.g., 120s at V).

To handle this situation, you would create two sets of obs files, first a set of "long" observations templates:

    lbqs_l_vh
    lbqs_l_rh
    lbqs_l_ij

and a parallel set of "short" observation templates

    lbsq_s_vh
    lbsq_s_rh
    lbsq_s_ij

You then divide your sample into "long" and "short" targets, and create two multi-object scripts:

    lbqs_long
    lbqs_short

to execute the long and short sequences, respectively. In both cases, you need to makes sure you check the "Prompt for Target Name?" box so that the quasar's name is correctly entered by the observer.

As a general point of strategy, fine-tuning exposure times is a waste of time. If you really think one object has to have 320s at V and another 280s, then you will have to create separate single-target obs files for them. Since this places a greater book-keeping burden on the observers, it will cut into the observing efficiency, and it will require you to create each of the individual obs files. The on-site observers will not fine-tune obs files, and they will not edit obs files on the fly. That cuts too deeply into the observing efficiency. Inefficient Phase II programs will be returned to the astronomer with instructions for revision if it is felt that they will have to high of an impact on observing efficiency.

[Contents]

If you came here from one of the entry forms, use the "BACK" button on your browser to return to the obs file generation form in progress.

Updated: 2003 March 1 [rwp/osu]