Updated: 2003 August 6
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:
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.
[Contents]
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) 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:
In addition, you need to also specify the imaging mode you wish to use, which is one of:
Once you have entered this information, hitting the "Next>" button on the form will pass you into the exposure parameter entry form.
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.
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.
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:
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.
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.
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.
On logging into the Observing Preparation Tools pages, you need to provide your name and Project ID.
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.
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).
-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 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.
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 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.
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).
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.
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.
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.
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).
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.
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.
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).
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.
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.
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.
[Contents]
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.
[Contents]
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. 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.
[Contents]
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 ENDExample 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 ENDExample 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 ENDNote 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).
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 ENDNote 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.
[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.