UNDER CONSTRUCTION. Thank you for your patience.  Please use this ANDICAM  Phase II menu [1] 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]

		Contents
	1.	Overview
	2.	How to Create Obs Files
	2.1	Step 1: Enter Target Information
	2.2	Step 2: Enter exposure Parameters
	2.3	Step 3: Validate Entries & Save the Obs File
	2.4	Execution Time Analysis
	2.5	Name it & Save it
	2.6	Notes
	3.	Obs File Creation Form Entries
	3.1	Project Information (login)
	3.2	Step 1: Enter Target Information
	3.3	Step 2: Enter Exposure Parameters
	3.4	Step 3: Validate & Save the Obs File
	4.	Editing Existing Obs Files
	5.	Viewing/Renaming/Deleting Obs files with the Obs File Manager
	6.	Example Obs Files

 

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

SMARTS Consortium
ANDICAM Observation Template (Obs) Files

Updated: 2003 August 6

 

 

1. Overview

The ANDICAM is a 2-channel instrument with separately configurable CCD and IR cameras behind a dichroic beam splitter that can acquire simultaneous CCD and IR images. To enable efficient queue scheduling of observations, all data with ANDICAM are acquired by means of Observation Template Files (or "obs files" for short).

Obs files define the target parameters and the instrument and exposure configuration of the smallest schedulable "unit observation" that can be acquired with the ANDICAM. A "unit observation" means that the choice of filters and the base integration times for each channel are fixed, but multiple images with those filters and integration times may be acquired. Similarly, IR channel observations can be dithered between images using internal tip/tilt mirror. If observations with different filters or exposure times are required, the astronomer must create a different obs file. Some examples are described below.

Each obs file consists of the following basic blocks:

Project ID Block:
    SMARTS Project ID used to assign "ownership" of the data acquired to a particular project.

Target Block:
    Contains the target name and coordinates (RA, Dec, and Equinox). In a generic multi-target observing template, the target name and coordinates will be omitted.

Observation Block:
    Specifies the observing mode (DUAL, CCD-only, or IR-only), and the exposure parameters, as follows:

    CCD Block with the CCD observing parameters (filter, exposure time, number of images to acquire, etc.), if required.

    IR Block with the IR observing parameters (filter, exposure time, number of co-adds and sequential images, dithering parameters, etc.), if required.

While obs files have been primarily designed for efficient simultaneous CCD and IR imaging, they also provide a consistent and logical way to schedule single-channel observations (i.e., CCD-only or IR-only imaging) with ANDICAM. This allows us to simplify the suite of commands needed to take data in each of the ANDICAM's 3 modes, which in turn simplifies the work of the on-site observers and the queue manager. It also ensures that the unused detector channel is kept idle while the other is active.

A set of obs files for a given target can be executed in a specific sequence by creating an optional multi-observation script. This is most often done for complex multi-wavelength observations (e.g., UBVRI+JHK photometry), or for "survey" projects in which many targets are observed once in the same way using a set of pre-defined templates. A special web form is provided to help you create simple multi-observation scripts as part of the Phase II observing preparation process. Use of such scripts can greatly simplify the execution of your observations. Note that if you are creating multi-target obs files for survey-type projects, use of multi-observation scripts is required.

Once you have created all of the obs files (and any associated scripts) for your program, you need to submit them along with a set of detailed observing instructions to the queue manager for evaluation, scheduling, and implementation. This is done using a separate "Phase II Submission Form". See the Phase II Observing Program Electronic Submission Instructions for details [3].

back to top

2. How to Create Obs Files

Obs files are created in three steps using a multi-part web form. This form is accessed by logging into the Observing Preparation Tools pages (via the Phase II Front Page [4]) and using the Project ID assigned to your project when it was approved for implementation and scheduling.

Step 1: Enter Target Information

The first step in creating a set of obs files for a target is to specify the information for the target proper. You have two basic options:

Single Target:
    In which the obs file is to be used for a single, specific target. In this case you would enter the following information:

       1. The name of the target.
       2. The RA and Dec of the target, and the equinox of the coordinates.
       3. Indicate whether the target is a solar system object (i.e., a moving target requiring ephemerides or other time-dependent sources of coordinates).

Multiple Targets:
    In which the obs file is to be used as a generic observing template for many different targets that will share the same detectors, filters, and exposure times. In this case, no target information need be entered.

In addition, you need to also specify the imaging mode you wish to use, which is one of:

   1. CCD-only (no IR imaging).
   2. IR-only (no CCD imaging).
   3. Dual CCD+IR Imaging (simultaneous imaging in both channels)

Once you have entered this information, hitting the "Next>" button on the form will pass you into the exposure parameter entry form.

back to top

Step 2: Enter Exposure Parameters

After entering the target info, you will be given a blank form for entering the exposure parameters for the observations. As described above, obs files are used to perform unit observations with a given instrument configuration. These units can be combined into multi-part imaging "sequences" using Prospero scripts that execute each of the separate obs files in turn.

For example, to take BVI images of an object, you would create three separate obs files, one for each of the B, V, and I filters. You would then have the on-site observers execute the obs files one at a time by hand, or create a multi-observation script to execute them in a sequence (thus reducing three execution steps into one: executing the script).

Once you have entered the exposure parameters for a given configuration, hitting the "Next>" button will then validate and analyze the entries.

Step 3: Validate Entries & Save the Obs File

You will next be shown a summary of the observation parameters you entered on the previous form along with an execution time analysis. At this point you need to review the parameters for errors. The project PI's are responsible for making sure that everything is correct before submission. You can use the browser's "Back" button to return to the exposure parameter entry form, make changes, and iterate until everything is ready before submitting the final obs file.

back to top

Execution Time Analysis

The exposure parameters you entered on the previous form are analyzed to make an estimate of the total amount of time that will be required to execute the requested exposures sequence. This estimate includes the unit integration times in each channel, number of images to be acquired, detector reset and readout times, IR mirror dithering motion overheads, etc., as appropriate. In general, the estimates are good to about 5% or so. The estimates do not, however, include instrument configuration overheads (e.g., changing filters or entering user parameters like the object name and coordinates), telescope configuration, etc. These latter will add to the total time it takes to execute your observation program. In general, instrument-related overheads add only ~10 seconds for each target/instrument change.

The estimates provided by the execution time analysis are meant to serve two purposes:

   1. To aid the proposer in optimizing 2-channel observation to minimize dead-time.
   2. To provide guidance to the queue manager in scheduling the observations.

From the proposer's perspective, the first provides a way to make sure that time that could be spent collecting more photons is not wasted because the CCD and IR operations are mismatched. For example, you might find that your first choices of integration times leave 64s of "dead time" on the IR channel while the CCD is still integrating and reading out. The web tools provided allow you to assess the impact is of adding an extra 60-second IR image to the obs files to close the gap. The web tools have been designed to make this kind of optimization exercise straightforward.

If you need to adjust any of the exposure parameters, use the "Back" button on your browser to return to the exposure parameter entry form in Step 2, make the changes, and then repeat the validation step. You can iterate as often as you like until you get things the way you want them. This way you avoid making lots of intermediate files that pile up on the disk (you can always clean up later with the Obs File Manager, but why make extra work?

It bears repeating that the estimates of execution times do not include such factors as the time required to setup the observation (e.g., setting the filters, exposure times, object names, etc.), nor do they include the computer-to-disk data-transfer times. They only provide estimates of the time it takes to perform those operations that occur from the moment the first exposure in the sequence begins until the last image is readout. All of the other configuration and data-transfer overheads cannot be predicted with any precision, the former because it depends critically on the previous configurtion of the instrument, and the latter because the inter-machine data-transfer system has a roughly factor of 4 range of transfer speeds (roughly 1Mb/sec to 4Mb/sec) governed by such ineffibles as the disk caching, how busy the up/downstream machines are, etc. As such, the queue manager has to empirically estimate any additional overheads based on past experience, and the adjust the queue schedule accordingly on subsequent nights based on how long it takes the observers to execute the program in practice (e.g., using the times reported by the nightly data logs).

Telescope pointing, target acquisition, and guide-star acquisition/lock times are not known a priori, but in general, the official estimate is to allow 3 minutes per acquisition. This is a slight overestimate, but it works out in the final accounting, since it allows for greater or lesser degrees of difficulty that the observer will have pointing, focussing, setting guide stars, etc. This is the value the queue-scheduling team uses when working out the observing program for each night.

If your program requires a lot of additional operations, e.g., many offsets around the target position between observations, it will cost you in terms of total execution time. If your program proves to be excessively costly in additional overhead, the queue manager will contact you regarding how to modify your program to make it more efficient. Not surprisingly, difficult programs are also difficult to schedule and execute, and have higher overheads. Keeping it simple is a virtue.

back to top

Name it & Save it

If everything is satisfactory, you are then asked to give the obs file a name. Each project is assigned a unique working directory for its obs files, so there is little chance your files with collide with others, though care in choosing filenames is essential. Above all else, make filenames that are simple and descriptive.

By simple, we mean you must restrict yourself to letters and numbers; no ".", "_" or other special characters. Special characters (even those technically allowed by Unix) can cause problems with the data-taking system, and if your observation fails because it has an illegal filename syntax, the fault is yours not the systems!

Similarly, a filename should reflect as much as possible the contents of the file (without being so complicated as to be unusable). For example, if the obs file is to acquire simultaneous V and H band images of a star cluster named NGC007, you might name the obs file ngc007vh. Naming it "fred001" is not just perverse, it could potentially waste a lot of time, as who knows that "fred001" means "make V+H images of NGC007".

Remember that choosing simple, unique, descriptive names will help the on-site observers execute your program. If you make complicated names that are hard to type, it will slow down the process; please keep it simple (the filenames are ultimately for them, not you). The observing managers will ask observers to resubmit observation files with more meaningful names, or change names as required if they cause execution problems.

After selecting a name, save the final obs file to your project's working directory by hitting the "Save Obs File" button at the bottom of the form. The obs file is stored on disk where you can view it later with the Obs File Manager (which also provides tools for renaming and deleting files). You will also be shown a copy of the final, saved obs file on your browser screen. We recommend that you print out your browser screen with the final version for your records.

back to top

Notes:

Safe Saving

To protect existing obs files for your project from accidental deletion, you are prevented from overwriting existing obs files with the form. If you try, the form will warn you and ask you to either (a) provide another, unique name and resubmit the form for processing, or (b) to go to the Obs File Manager and either delete or rename the existing file, and then resubmit the form again. Careful use of the "back" button on the browser lets you do this simply.

Making more than one obs file for a target

The multi-step process is designed to allow multiple iterations between any sets of forms, provided you take care to use the browser Back button and the various form buttons carefully. The target information (name and coordinates) are If you reload the form by following a link, bookmark, or other means, you will be given a blank form. By now simple web forms are familiar to most users, so this needs little detailed explanation.

Trouble? How to Get Help

No system is perfect. If you have problems using these forms please contact the SMARTS2 support personnel at Yale and describe your problem, the time it occurred, and any other info you think might help him debug things. The more feedback the better at this stage.

back to top

3. Obs File Creation Form Entries

The following are descriptions of the entries in the obs file creation forms. These entries are accessible from within the forms themselves by clicking on the highlighted item. If you have come to this page from the web form, remember use the "Back" button on your browser to continue filling out the form in progress.

Project Information (login)

On logging into the Observing Preparation Tools pages, you need to provide your name and Project ID.

Your Name

To keep track of who created the obs files for a project, we ask you to enter your name in the box provided.

Project ID

Project ID codes are assigned by the SMARTS scheduling committee when time is awarded on the SMARTS telescopes. Select your SMARTS Project ID from among the entries in the pull-down menu. If you don't know your ID number, or don't find it in the menu, contact the current queue manager or NOAO program coordinator (as appropriate) immediately.

back to top

Step 1: Enter Target Information:

The first form will ask you to enter the target name and coordinates, and the imaging mode to be used. Project PIs (or their CoIs) are responsible for entering the target name and coordinates correctly. Neither the queue manager nor the on-site observers will enter, validate or correct target names or coordinates. Although if there are problems with your coordinates, the queue manager will be in touch.

There are two types of observing template that can be created: single-target and multi-target.

Single Target

If your obs file is to be used for one, specific target, you will be creating a "single-target obs file". In this case, check the "Single Target" box, and enter the Target Name and coordinates in the boxes provided, as follows:

Target Name

Enter the target name of the object you wish to observe. This is how the target name will appear in all observing logs and FITS image headers (the OBJECT keyword). The target name you enter in step 1 is carried forward through all subsequent obs file creation steps.

You can enter up target names up to 60 characters long (including spaces), but only the first 16 characters will appear in the observing logs (all 60 will appear in the image FITS headers).

Solar System Objects

If your target is a solar system object (i.e., a moving target), be sure to check the "Solar System Object" box. You will also need to provide both approximate coordinates for the object, as well as arranging to send the queue manager ephemerides for minor bodies (asteroids and moons) separately from this form.

Target RA, Dec, & Equinox

Enter the Right Ascension, Declination, and Equinox of the target. RA should be in hh:mm:ss.s format, and Declination in dd:mm:ss format. The sign of the declination goes in the first place, thus:

            -00:00:32
            +12:12:34

etc. are valid declinations. Please do not enter decimal coordinates.

The default equinox is J2000.0 coordinates, and we would prefer that you precess coordinates to J2000.0 before entering them here. If you cannot precess the coordinates, enter the Equinox in the box provided (e.g., 1950.0 for B1950.0 coordinates; omit the "J" or "B"). Use of non-2000 coordinates is greatly discouraged, as it could be overlooked by observers working through a long target list with 99% J2000 coordinates. Give them a break and precess them, please.

If your target is a solar system object, enter approximate coordinates for the observing season to assist in queue scheduling, and remember to check the "Solar System Object" box next to the Target Name. All of the planets are already in the 1.3m telescope's control system, but for minor planets or planetary moons you will have to provide the queue manager with an accurate ephemeris. Contact the queue manager [5] for instructions on how to submit ephemerides for solar system targets.

Note: There is apparently some confusion about the precise role of these coordinates in the data-taking process. They are not actually used by the data-taking system per-se (i.e., the data-taking system does not read the coordinates from the obs file and slew the telescope). Rather, they are there for two purposes: (1) to be used by the queue-management team as the "definitive" coordinates for your target, and (2) in cases of uncertainty at the telescope the observer will consult the obs file for a particular target to verify the coordinates against what is given on their nightly observing list. This sounds non-functional, but in fact it serves to "bind" the definitive coordinates to the observation template in an unambiguous fashion.

If your observing program requires multiple pointings within or around an object because it is larger than the ANDICAM field-of-view, the situation is more complicated. Such offset pointings must be treated as separate observations because the on-site observers must enter the new field coordinates by hand into the TCS, execute the telescope offset, and setup the autoguider separately for each subfield. None of these operations may be automated by way of obs files at the present time (and may not in fact be easy or possible in the future). There are a number of ways to go about doing this, so you will need to consult with ANDICAM core team members for recommendations as this is not a normal ANDICAM observing mode.

back to top

Multiple Targets

    If you are creating a generic obs file to be used as a template for multiple targets that will share the same exposure times and filters, check this box to create a "multi-target obs file". No target name or coordinate info needs to be entered if this box is checked (and any entries you put into those boxes will be ignored by subsequent forms).

    Multi-object observing template are most often used to take observations of many different targets in a "survey" style mode (see the Phase II Instructions [3] for a discussion). This is what you would use if you had a large list of objects that only need to be observed once (or only infrequently), but with different filter settings. A multi-observation script is then used to set the Target name separately, and you will be required to submit a separate coordinate list with your Phase II instructions.

Imaging Mode

Once you have selected single- or multiple-target mode, you must select the imaging mode for the observations. This is one of:

• Dual CCD+IR Mode = simultaneous CCD and IR imaging.
• CCD-only Mode = CCD imaging only, IR channel idle.
• IR-only Mode = IR imaging only, CCD channel idle.

You may change the imaging mode used for a given template later by returning to Step 1 with the Back button on your browser. All of the stages in the form are designed to be as "re-entrant" as possible to make building sets of templates for the same object easier (no guarantees, it depends on which web browser you are using).

back to top

Step 2: Enter Exposure Parameters

Having set the target parameters (single or multiple) and the base observing mode (CCD, IR, or Dual), the second form asks you to enter the CCD and/or IR imaging exposure parameters for your target for the imaging mode selected. This includes filter selection, and setting up the dithering parameters for IR imaging.

CCD Imaging Parameters:

   CCD Filter

Select a filter from the list provided. Only one CCD filter can be specified in a given obs file. To make a series of observations through more than one CCD filter, you need to create a separate obs file for each filter.

   CCD Base Integration Time

Enter the integration time, in seconds, of a single CCD image. Integration times up to 1800s are allowed. You can integrate for longer than 1800s, but cosmic ray contamination becomes severe. There is no default integration time, and this field may not be left blank.

An integration time of 0 seconds will result in a "bias" or "zero" frame being acquired. If you do not wish to take CCD images with this obs file, back up to the target info form and select "IR-only Mode" as the Imaging Mode.

   Number of CCD Images

Select the total number of CCD images to be acquired during this observation. Each CCD image will have the base integration time entered above. The total integration time will be the base CCD integration time multiplied by the number of CCD images. Default is 1 image. The total CCD integration time will be the number of CCD images times the base integration time.

NOTE: you cannot select 0 CCD images. If you do not wish to take CCD images with this obs file, back up to the target info form and select "IR-only Mode" as the Imaging Mode.

CCD Binning

New to the 1.3m ANDICAM. The unbinned pixel scale at the CTIO 1.3m telescope is ~0.18 arcsec/pixel, necessitating that we bin the detector 2x2 pixels on-chip to get a more reasonable scale of ~0.37 arcsec/pixel.

As a consequence, CCD binning is no longer a user-selectable parameter at the 1.3m (this is a change from how we worked at the Yale 1-meter, and is not negotiable).

back to top

IR Imaging Parameters:

IR Filter

Select a filter from the list provided. Only one IR filter can be specified in a given obs file. To make a set of observations through more than one IR filter, you need to create a separate obs file for each filter.

IR Base Integration Time

Enter the integration time, in seconds, of a single IR array image. Times up to 1800s are allowed, but the background will typically saturate in a few minutes, especially at K. There is no default integration time, and this field may not be left blank.

 The minimum IR detector integration time is 4 seconds. If you enter a base integration time between 0 and 4 seconds, you will get at 4 seconds of integration anyway. Above 4 seconds, the requested integration time will be achieved. See the ANDICAM manual for an explanation.

Number of IR Images

Select the total number of IR images to be acquired by this observation. Each IR image will have the base integration time entered above. Default is 1 image. The total effective IR integration time will be the number of IR images times the base integration time.

    NOTE: You cannot select 0 IR images. If you do not wish to take IR images with this obs file, back up to the target info form and select "CCD-only Mode" as the Imaging Mode.

    Number of CoAdds per IR image

    Each IR image can be composed of a number of separate images averaged together ("co-added") in the detector control computer before being stored as a single image file on disk. Each IR CoAdd will have the base integration time entered above. For example, if you specify 5 IR images of 3 co-adds each, the instrument will acquire 15 images of the base integration time, averaging them in groups of 3, and storing them as 5 separate FITS files. Default is 1 Co-add/image.

    In general, co-adding is most useful when a target is sufficiently bright that you are restricted to very short integration times to avoid saturation, and so would need a very large number of single images to build up sufficient signal. Co-adding helps build up signal while producing a reasonable number of final image files, and with the additional benefit of a slightly reduced overhead penalty compared to taking a large number of single images. The cumulative readout noise penalty, however, is the same regardless.

back to top

Dithering:

    An internal tip-tilt mirror in the IR channel beam can be used to make small "dithering" offsets between IR images. Dithering is the standard way to reduce the effects of bad pixels and flat-field artifacts on the IR array by shifting and combining multiple images taken at slightly offset positions on the array. No dithering is done between IR Co-Adds.

    To dither between images, check the "Dither between images" box, and select scale the dithering pattern ("dither scale") from the pull-down menu. The default dither scale is 40, which corresponds to a dither throw of approximately 20 arcseconds on the CTIO 1.3m telescope. This is the dither scale used for generation of IR dome flats, so this makes the most sense to use this for most observations. Dither scales range from 10 to 100 in steps of 10 (5-50 arcsec in steps of 5 arcsec). If you want to use another dither scale, you may need to arrange for additional flat-field calibration (at a cost to your time allocation).

    The IR tip/tilt mirror dithers the image around the IR detector in a fixed hexagonal offset pattern. There are 7 dither positions: the first (1) centered on the array, and the following 6 (2-7) arranged in a lop-sided hexagon, stepped in (roughly) 120-degrees segments. The hexagon is lopsided due to the 45-degree difference between the tip/tilt actuator plane and the surface of the diagonal pickoff mirror. This pattern is repeated (modulo 7) until the total number of IR Images requested have been acquired. At the end of a dithering sequence, the mirror is returned to the home (centered) position. Tests at the telescope show that the dithering is repeatable to ~0.5 pixel (0.07 arcsec on this IR array).

    If you do not wish to dither between images, check the "No Dithering between images" box. This will keep the IR tip/tilt mirror centered during the entire obs file's IR imaging sequence.

back to top

Step 3: Validate & Save the Obs File

Once the exposure parameters have been entered in step 2, the obs file creation form generates the obs file and estimates the execution times for the CCD and/or IR images requested. You are asked to first validate your entries, using the estimated execution times to help adjust your exposure parameters to optimize your observations, and then select a filename for the obs file and save it to your project's working disk.

    IMPORTANT NOTE:
    Filenames must be kept "simple": only letters (a-z & A-Z) and numbers (0-9) are allowed. All other characters are forbidden (i.e., it cannot contain any of the following:

       "'()[]{}-+_=.,:;|\/?><~!@#$%^&*

    even though a few of these are are technically allowed by Unix!). Please remember that the observer has to type the name, sometimes many times, so think of them when you make up filenames. Difficult filenames can lead to errors and slow down observing, and will be changed by the queue management team without asking you.

Estimated Execution Times

The estimated execution times give the approximate amount of real time required to execute the requested exposures, from the first detector array reset until the end of the last detector readout (not including any instrument or telescope configuration overheads). The various data-acquisition overheads were measured during engineering runs in January/February 2003 with the new ANDICAM setup, and yield estimates based on our CCD and IR Array readout models that are accurate to within 5%. Be warned, your mileage *will* vary, so don't expend too much effort time optimizing out the last second of dead time in dual-channel observations - reality *will* have the last word. For those interested in factoring in instrument configuration overheads, at most this amounts to 10-seconds per observing template (assming change of name, filter, exposure time, etc.). Telescope pointing, target acquition, and guide-star acquisition/lock times are totally up for grabs. If your program requires a lot of hand offsets around the field, it will cost total observation execution time. If your program proves excessively costly in overhead, the queue manager will contact you regarding modification of your program.

Estimated CCD Execution Times

    This estimate takes into account:

       1. The base integration time per CCD image.
       2. The number of CCD images requested.
       3. The time required to readout the CCD (vertical and horizontal clocking times and the readout amp integration time per pixel).
       4. The number of readout amplifiers being used (2 at present, not user-selectable).
       5. The pre-exposure "setup" overhead, including array erase cycles (~6-sec independent of binning).

    For example, a single, full-frame, 2x2 binned 1024x1024 CCD image requires approximately 47 seconds over and above the base integration time to erase and readout the array. Future operation with 2-amplifier readout should reduce this to 20-odd seconds.

    Taking many short exposures incurs a greater readout "penalty" compared to taking fewer longer exposures to achieve the same total integration time. For example, a single 300 second full-frame, unbinned image will require approximately 347 seconds to execute, while dividing the 300 seconds of integration time into two (2) exposures of 150 seconds each requires 394 seconds (~14% more time). Doing three exposures of 100 seconds each would require ~441 seconds to execute (27% more time).

Estimated IR Execution Times

    This estimate takes into account the following:

       1. The base integration time per IR image (the minimum integration time is 4 seconds).
       2. The number of IR images requested.
       3. The number frames co-added per IR image requested.
       4. IR setup, readout, and post-processing (pre-read minus post-read math) overheads amounting to about 20 seconds.
       5. The tip/tilt mirror overhead if dithering between images (approx. 2 seconds/position).

    The algorithm for computing the execution time of IR images is complicated by execution latencies encountered during readout and storage due to the finite clock interval allowed in the hardware. In general, the times computed are good to 5%, although if a large number of images (>10) has been requested with a comparable number of co-adds per image, the calculator will systematically underestimate the total execution time by as much as 10% due to cumulative small latencies in the system.

back to top

Enter a Filename for the Obs File

Each ANDICAM project is assigned a private directory on the queue server for storing their observation template files.

This field asks you to provide a filename for your new obs file. The filenames of obs files should be kept simple (i.e., only letters and number: NO SPECIAL CHARACTERS), and should reflect as much as possible the contents of the file. For example, if the obs file is to acquire simultaneous V and H band images of a star cluster named NGC007, you might name the obs file ngc007vh. Including the object name in the filename like this helps to ensure relatively unique names, and makes it easy to know what file is doing what by just looking at the name. You only have to look at a few of these files, the operations staff has to handle hundreds! Give us a break, please!

Filenames are case sensitive, and may contain only letters and numbers, NO SPECIAL CHARACTERS (e.g., +, -, _, etc.) ARE ALLOWED (even though technically Unix might allow quite complex filenames). Please remember that the observers have to type them, sometimes many times a night, so complex or confusing filenames can cause problems, and will be changed to simpler names if they are crazy.

If the filename you provide will overwrite an existing obs file in your directory, you will be given a warning and asked to confirm that you really want to overwrite the existing file. Detailed instructions are provided if this occurs.

Note that the obs files will be given the .obs files extension automatically by the web forms, so do not include a file extension with the filename you type in the box provided.

back to top

Editing Existing Obs Files

Once you have a set of Obs files created, you can later go back and edit them with the Obs File Editor. This form will read in the contents of a existing Obs file and let you modify the entries, either to replace an old Obs file or to create a new Obs file using an old one as a template. In cases where readout or overhead times change substantially (e.g., in September 2000), the editor can be used to re-evaluate old Obs files and modify them to reduce deadtime in DUAL mode.

The basic entries are the same as on the Obs file creation form described above. The one potential point of confusion is if you are editing an Obs file that was originally either CCD-only or IR-only imaging mode. In these cases, the editor form provides boxes for the unused channel (after entries for the active channel). These entries will be ignored unless you decide to change the imaging mode as part of your editing session. It's easier to try than read about, trust me, you'll figure it out.

back to top

Viewing/Renaming/Deleting Obs Files with the Obs File Manager

After a while, you can get quite a collection of Obs files. To provide a way to manage these semi-sensibly, we have provided the Obs File Manager Form [6]. The file manager is a table-based web form that shows you all of the obs files that have been created for your project, and lets you view, delete, or rename individual files. This lets you clean up after making your obs files, fix ugly filenames, etc., without having to go back through the creation or editor forms.

Obs files "deleted" from the active list are moved to the wastebasket for your project, where they are held until you decide to either delete them once and for all, or to "undelete" them and return them to the active list. If there are any files in your project's wastebasket when you open up the file manager, they will appear in a separate "wastebasket table" beneath the table of active files. This is a safety feature to prevent you from accidentally deleting obs files (you can delete them, we just make you think about it first).

Editing existing obs files is not an option during the early parts of the testing phases (the file parser is not working yet), but we hope to have something working eventually.

The instructions for using the File Manager are described in a separate document [6].

back to top

Example Obs Files

Example 1: CCD-only Imaging

This is an obs file to take one 300-second CCD image of MB99018 with the I-band filter. The IR channel is kept idle during the observation (CCD-only mode).

# Prospero Observation Template File
# Created: 2003 Feb 9 [13:35:50] by saveobs.pl Version 1.5
# For: R. Pogge
#
PROJECT=OS03001
IMGTYPE=OBJECT
OBJECT=MB99018
RA=18:01:07.7
DEC=-28:31:41
EQUINOX=2000.0
MODE=CCD
#
# CCD Imaging Parameters
#
# Estimated Execution Time: 347 sec
#
CCD:
   FILTER=0 # I
   EXPTIME=300.0
   NIMGS=1
END

back to top

Example 2: IR-only Imaging

This obs file takes a sequence of five (5) 60-second images at K of a Seyfert 1 galaxy, dithering between images with a dither scale of 20 units (about 10 arcsec). The CCD channel is kept idle during this observation (IR-only mode).

# Prospero Observation Template File
# Created: 2003 Feb 7 [13:27:45] by saveobs.pl Version 1.5
# For: Rick Pogge (OSU)
#
PROJECT=OS03011
IMGTYPE=OBJECT
OBJECT=Mrk 1347 K
RA=12:39:47.3
DEC=-23:27:16.0
EQUINOX=2000.0
MODE=IR
#
#  IR Imaging Parameters
#
# Estimated Execution Time: 410 sec
#
IR:
   FILTER=3 # K
   EXPTIME=60.0
   NCOADDS=1
   NIMGS=5
   DITHER=T
   DSCALE=20
END

back to top

Example 3: Dual CCD+IR Imaging

This obs file takes simultaneous V and K-band images of 47 Tucanae, one 180-sec integration at V and three 60-sec integrations at K, dithering by a factor of 40 between IR images.

# Prospero Observation Template File
# Created: 2003 Feb 7 [13:41:59] by saveobs.pl Version 1.5
# For: bailyn
#
PROJECT=YA03001
IMGTYPE=OBJECT
OBJECT=47 tuc
RA=00:26:00
DEC=07:02:22
EQUINOX=2000.0
MODE=DUAL
#
# CCD Imaging Parameters
#
# Estimated Execution Time: 227 sec
#
CCD:
   FILTER=6 # V
   EXPTIME=180.0
   NIMGS=1
#
#  IR Imaging Parameters
#
# Estimated Execution Time: 246 sec
#
IR:
   FILTER=3 # K
   EXPTIME=60.0
   NCOADDS=1
   NIMGS=3
   DITHER=T
   DSCALE=40
END

Note that there is approximately 19 seconds of "deadtime" between the IR and CCD images. Attempting to optimize the difference by more than 10-20 seconds, however, is usually a waste as this time can easily be consumed by various system latencies that are unpredictable (some dual-channel operations must execute serially instead of in parallel).

back to top

Example 4: Multi-Target CCD+IR Imaging Template

This is a multi-target obs file used to take simultaneous V and H-band images. No target name or coordinates are given because it is to be used on a number of different targets generically. Here, we take one 180-sec integration at V and three 60-sec integrations at H, dithering by 50 units between the successive IR images.

# Prospero Observation Template File
# Created: 2003 Mar 2 [14:21:34] by saveobs.pl Version 2.0
# For: pogge
#
PROJECT=OSU-TOO
IMGTYPE=OBJECT
MODE=DUAL
#
# CCD Imaging Parameters
#
# Estimated Execution Time: 227 sec
#
CCD:
   FILTER=6 # V
   EXPTIME=180.0
   NIMGS=1
#
#  IR Imaging Parameters
#
# Estimated Execution Time: 246 sec
#
IR:
   FILTER=2 # H
   EXPTIME=60.0
   NCOADDS=1
   NIMGS=3
   DITHER=T
   DSCALE=50
END

Note that unlike all of the other example obs files shown thus far, there are no OBJECT=, RA=, DEC=, or EQUINOX= entries. This makes the obs file "generic" in the sense that it can be used for any target. Such a generic obs file can only be executed by an accompanying multi-observation script that will prompt for the target name, and run any other multi-target obs files that are part of a sequence to be executed for each target in the program. Executing it without such a script will result in either a blank object name (bad), or with the object name of the last target observed (worse). See the Phase II Instructions for details.

back to top

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: 2006 May 11 [rwp/osu]