Creating and Editing Observing Block (OB) files for LBC

Updated 13 April 2011

Getting Started with the OB GUI
Creating and Saving a Single OB

Target Package:
Observation Description:
Constrain Sets

Creating and Saving a Set of OBs
Creating OBs on-the-fly (from the LBC Control User Interface)
Editing the xml
Calibration OBs

Observations with the LBC are carried out through the LBC Control System, which reads in and executes Observing Block files (OBs). These are xml files which specify the telescope pointing, dither sequence, instrument configurations and exposure times and are read by the LBC User Control Software (see the Basic Guide to Operating LBC for more information on using the OBs). Several OBs may be strung together into an Observing Plan, though, at this time, Plans cannot be loaded and executed by the LBC Control program. Observing Plans will be ignored for now.

This document describes how to create the OB files. Usually OBs will be created individually for each target (Creating a Single OB), but, if there are a set of targets which require the same configuration but differ only in pointing, then a task to create a set of OBs can be used (Creating a Set of OBs).

OBs usually are edited by loading them into the OB Creation GUI, changing relevant parameters and then saving them as a new file, but the *.ob file can be edited with a simple text editor. The most frequently edited parameters are listed in the section on Editing the xml. Calibration OBs for biases, darks, standard stars, twilight flats and focus and collimation are collected and available in a tar file.

Getting Started with the OB GUI

The LBC team have provided an Observing Block Creation GUI to create OBs. The following is a step-by-step guide to using the OB GUI. More information can be found in the document, "GUI for LBC-OB Reference Manual" by Stefano Gallozzi. The OB GUI may be downloaded by clicking on the "Binaries" link in this table on the LBC website. It has been written for and tested on Windows and LINUX platforms, but does run also on the Mac OS.

To launch the OB GUI, go into the directory created by unzipping the file (where the GUI.jar file is) and type java –jar GUI.jar. On windows machines, double click on the GUI.jar icon.

A window should pop up with the title, Main Window. There is a set of buttons along the top which are divided by functionality into three main groups: (1) the three left-most buttons (yellow) create, delete and open Folders; (2) the five red buttons to the right of these deal with Observing Plans and are currently not used; and (3) the six green buttons after these create, open, delete, export, copy and save OBs. These are heavily used. Note that all of the buttons have text descriptions which will appear when the mouse cursor is brought to rest for about 1-2 seconds on the button. The buttons serve as shortcuts for the tasks listed in the menus (Folders, Plans, OBs) along the row above.

Creating and Saving a Single OB

The first step in creating an OB is to open the folder(directory) where the OB will be saved. If this output folder(directory) does not exist, you can create it --- either in an xterm with the 'mkdir' command or by clicking the "New Folder" button on the OB GUI and entering the Folder name and the path to it. Open this folder by clicking the "Open Folder" button, which will pop up a browse window in which you can select the folder. The name of the open folder should appear in the top panel of the OBGUI Main Window, just to the left of the red and white "power" button. The left sidebar may or may not show this folder and the parent directory (called "root"), depending on how the folder was created. Do not be concerned if the folder name does not show up correctly here.

When you are ready to save the OB, click the "save OB" button or select "Save" from the "OBs" menu. This will write out a *.ob file in the open folder.

Target Package

Entering the Bookkeeping Information

When the Main Window is open on the "Target Package" tab, you should see 6 lines at the top, underneath the heading, "Observing Block Description".

Observing Block Name: The filename of the Observing Block (OB) to be created will be taken from the Observing Block Name which should be entered here. It is advisable to avoid white space and periods (".") since filenames with these characters are either difficult to manipulate in Linux, the operating system on the observer workstations, or not able to be opened by the OB GUI. It is also recommended to keep the OB name shorter than 18 characters, since only the first 18 characters of the name entered here will be written to the header as the value of the LBCOBNAM keyword.
Target Name: The name of the object, which can have spaces, number and symbols. The target name specified here is written as the value of the header keyword OBJECT.
Class Type: The value of the header keyword IMAGETYP: object, zero, flat, dark, focus, ...
Proposal ID: Enter the ID number given to your proposal. If you do not know it, enter the PI Name. This value will be written to the PROPID keyword in the primary FITS header.
PI Name: Enter the name of the primary investigator. This value will be written to the LBCUSER keyword in the primary FITS header.
Observer: Set Observer to your partner name: inaf, az, lbtb or osurc. Either upper or lower case may be used. This value will be written to the OBSERVER keyword in the primary FITS header. In OBs to obtain calibration data (standard stars, biases, flats, darks), OBSERVER should be set to calibration. The lbtarchive from which you retrieve data requires a partner-specific login which allows you access only to data obtained by your partner group. Therefore, it is essential that the OBSERVER value is correctly entered in the OB.. See OB Preparation & Data Access for more details about the values of OBSERVER and how data from multi-partner collaborations can be retrieved by co-investigators from the different partners.

Entering Target Information

Target Coordinates:
RA: The RA may be entered either in the top box as decimal degrees or in the lower set of four boxes as hours, minutes, seconds, and fraction of seconds. You can tab from one field to the next, and as you do, the RA in decimal degrees will be updated in the box above. Make sure that the final value of RA in decimal degrees is correctly corresponds to the hours, minutes and decimal seconds which were entered, because it this value (decimal degrees) that is written to the output OB file and, consequently, read into the LBC User Interface and passed on from it to the telescope control system.
DEC: Similarly, DEC may also be entered either as decimal degrees or as degrees, minutes, seconds, and decimal seconds.
DEC=-90: To signal that the OB should be carried out where the telescope is currently pointing, set DEC = -90. Note that an OB set up like this (without a preset) will not be able to command dithers. When DEC = -90, RA may be anything from 0-360 deg (0-24h).
Equinox of Coordinates: Note that while there is an option to enter either 2000 or 1950 (J2000 or B1950) coordinates, the telescope control does not as yet accept B1950 coordinates. Enter only J2000 coordinates.

Rotator Tracking and Preset LBT: Insure these boxes are checked (or not checked) as you wish. For normal observations, both should be checked.

Rotator Tracking: If checked, this enables the rotator to move during the observation to compensate for field rotation and maintain the position angle. During normal observations, this should be checked.
Preset LBT: If checked, this enables the instrument to send commands to the telescope control system: among other things to slew to the target, track at the sidereal rate, dither and adjust the position of the primary mirror. For normal observations, this should be checked.

Offset and Rotation:
Position Angle: Enter the desired position angles, in degrees, for LBC-Blue and LBC-Red in the boxes to the right of BArm and RArm in the lower right part of the page. A position angle, PA = 0 degrees, corresponds to the North vector pointing up along the positive y axis, from the center of rotation on chip 2, and the East vector pointing to the left, along the negative x axis. The position angle is defined as the angle of the positive y axis from the North vector, measured from North through East.
Offset: Offsets to the target coordinates can be entered as RA and DEC offsets (in arcseconds). These offsets will not be directly written to the OB file that is generated by this GUI; only the decimal degree RA and DEC values in the "Target Coordinates" section are written to the output OB. Therefore, to implement an offset from the base position, you must click on the button just above the box for the DEC offset in order to add these offsets to the RA and DEC target coordinates.
Proper Motion: Proper motions in arcsec/yr may be entered. These are converted to radians per century, the units required by the telescope control system, before being written to the output OB. However, at this time (October 2010) LBC proper motions are not yet handled in the telescope control system; whatever is entered in these boxes is currently ignored.

Interactive Pointing:

Click on Interactive Pointing to see the outline of the detector array over an image from the Guide Star Catalog. The outline is displayed by default for all dither positions together, and the pull down menu under "Ditherings" allows you to select individual dither positions or chips. Click the magnifying glass to zoom, unzoom or return to the original size. In the bottom portion of the page, the position angle and coordinate offsets can be adjusted. Click Recenter position to update the target coordinates and position angles in the Target Package page. The option to "Download Image and Open Jsky" is not working at this time.

Observation Description

Click the Observation Description tab to display this page. In the top section, the dithering offsets are determined, and in the bottom section, the CCD Parameters and the integrations are set up.

Note that one arm is designated as Master and the other Slave. The Master arm used to be the one whose tracker images were used to guide the telescope, while those on the Slave arm were used to make small adjustments to its primary mirror. The OB gives you the opportunity to select which channel to use as Master. Since 26-March-2011, the binocular version of the LBC software has been used. In this version, guide corrections from both sides are split between the mount and both primary mirrors. The Master/Slave terminology has become obsolete, and the Master/Slave designation in the OBs is no longer relevant.

There are 8 rows per channel; each row can use a different filter or different integration time. When multiple filters (or multiple rows) are used:

Observations will always be executed with the outer loop over dither postion and inner loop over filter(over row), i.e. at the first dither position, all of the requested filters will be cycled through before the telescope is commanded to move to the next dither position.
Try to make the total times to cycle through all of the filters in the Blue and Red channels of equal duration, so that one channel is not left idle while the other is completing an observation.
Do not leave the first row blank or gaps between the rows.

Specifying the Dithering Pattern:

There are various parameters that can be set to determine the list of RA and DEC dithering offsets. The most important buttons are described below. Three important notes:

All Dithering Offsets are absolute, not relative.
Although there are 9 areas where values may be input to specify or modify the dithering pattern, these "boil down" to 3 items which are written to the GUI and read by the LBC User Interface: the Number of Dithering Offsets, and the sets of RA and DEC Dithers. After you have set up the dithering sequence, please check that the values in these boxes are what you want.

Dithering Pattern: Select a Dithering Pattern from the drop-down menu near the top middle of the window. Many patterns are available. These are described later and depicted in the plots that are linked to this page. Note that when an OB that was created using an earlier version of the OB GUI is loaded, and the number of the available dithering patterns differed between this earlier version and the current one in use, the name of the dithering Pattern that appears will not correspond to what was originally selected and used to generate the RA and DEC offsets. The RA and DEC dither offsets are what are passed on to the telescope, not the Dithering Pattern name. If such a mismatch occurs, and you know the RA and DEC offests are correct, do not click 'Calculate'.
Dith Angle: This will automatically be filled in with the LBC-Red Position Angle which was indicated in the target page. For the patterns that were developed to fill gaps or move a star from chip to chip (the 4-point, 5-point, 9-point or 10-point patterns), the intention is to offset in detector coordinates. To calculate RA and DEC offsets which will do this (move stars strictly along rows and columns) the position angle is needed. Should you wish to edit this value, click on the box after having selected a Dither Pattern which is not one of the 4-point, 5-point, 9-point or 10-point patterns. You may then reselect one of these patterns and click "Calculate" to determine the set of offsets with this new angle. User Provided patterns are already input in terms of offsets, so Dithering Angle and Scale are not relevant.
Dithering Scale: Used by the 5-point, 9-point, 10-point, Circular, Rectangular and Random Dithering Patterns to set the scale of the dither offset. Keep in mind that the gaps between chips are about 18 arcseconds wide. User Provided patterns are already input in terms of offsets, so Dithering Angle and Scale are not relevant.
Calculate: Once the Dithering Pattern is selected and the Dither Angle and Dithering Scale are set, click the "Calculate" button to calculate the set of RA and DEC dithering offsets. The boxes to the right of RA Dither and DEC Dither should be populated with a set of comma-separated numbers, one for each dither position.
Other Dithering Options... There are options available to select the "Starting Item", and to offset the entire pattern ("Offset X axis" and "Offset Y axis"), however these are seldom used.

The Dithering Patterns are described in detail below:

Random:
4-point default: designed to position the target on the center of each of the four chips. This is the pattern used in the Calibration OBs for observations of standard stars.
5-point default: in a left (5-split L) or right (5-split R) leaning 5-dice pattern to fill gaps;
9-point default: in a left (9-split L) or right (9-split R) leaning 3x3 grid to fill gaps. These have been separated into 3 sets of 3-point dithers.
10-point default: a left (10-split L) or right (10-split R) leaning 10-point grid to fill gaps.
Circular
Rectangular
User Provided: When User Provided is selected and the "Calculate" button is clicked, a browse box is opened in which you can select the ascii file which contains the custom RA and DEC offsets, in arcseconds. The format is as follows, with one offset per line and with the RA and DEC offsets separated by a semicolon:
```
  0.00; 0.00
-18.00;-36.00
 18.00; 36.00
-36.00; 18.00
 36.00;-18.00
```
None

Editing the CCD parameters:

Click "Edit CCD". This brings up a window entitled "Chip Settings".

Detectors: A check-mark in the box to the left of the chip number indicates that it will be read out. The available options are all four chips or chip 2 only.
Readout mode:Read-out mode should always be slow.
Binning:1x1 binning should always be selected. 2x2 binning is not yet offered. With the Red Channel, 2x2 binning may work, although chip-to-chip differences in the bias levels do not correspond with those for the unbinned biases, and this is not yet well understood.
Shutter:Check the box if you want the shutter to open. Shutter use is indicated by the picture on this window and on the Observation Description page.
Window Parameters:Windowing is only possible in rows, and the same settings are used for all detectors that are selected. Enter the range of rows to read out in the boxes for Minimal Y and Maximal Y. Note that Minimal X and Maximal X are always 1 and 2048. The subregion indicated applies to all chips in use.

To close the window and store your selections, click Modify Settings, not Exit! Exit will exit the window but will not modify the settings.

Setting up the integrations:

Back in the Main Window/Observation Description, set up the exposure times for each filter to be used. To enter data in the table, double-click anywhere along the header row to allow input of exposure times. Select a filter from the pulldown menu under the "filter" column. Usually you will enter the number of exposures per dither position (NExpo) and the single exposure time (SingleTExpo) in seconds. The total exposure time (TotalTExpo) is calculated as:

TotalTExpo(s) = SingleTExpo(s) x NExpo x NDitherPositions

After making changes to one of the columns, double-click on the headings of the other columns to update their values. Note that the values that are stored to the output OB file and consequently read by the LBC User Interface are: the number of exposures (Nexpo), the single exposure time (SingleTExpo) and the Filter. The total exposure time is only displayed as an aid in planning the observations.
ETC Click on the GIF in the left-most column to bring up the Exposure Time Calculator (ETC). You can use this to determine exposure times needed to reach a given signal-to-noise ratio and then fill in the table from the ETC. The ETC is also available from the LBC homepage in Rome.
Focus (engineering use only): From the Observation Description window, it is also possible to set up OBs which step through focus. This functionality is available only for OBs of Class Type FOCUS (specified in the Target Package) and is used primarily for engineering. Click on the "bull's-eye" to the right of the "Edit CCD" button and a new window will open in which you can enter the starting focus position and the offset in mm. One focus step per exposure is assumed, and the number of exposures is what was specified by NExpo. Click Modify Settings to save the information and close the window.

Constrain Sets:

This allows you to enter condition constraints for the observation, e.g. elevation~60-70 deg, photometric, high priority, seeing < 1arcsec. Be aware that these constraints are not used by the LBC Control software and observers often do not read them either; constraints should be indicated in the observing proposal.

Creating a set of OBs

To create a set of OBs which use the same configuration but differ only in pointing and position angle:

first, set the instrument configuration in the "Observation Description" tab, and

then, click the OB List button on the New Observing Block window. This opens a new window which allows you to enter the data manually or to select a file, which contains one line per target (up to 100 targets) in the following format: ob name; target name; class type; RA [dec degrees]; DEC [dec degrees]; epoch; B-Arm position angle; R-Arm position angle; Proper Motion RA; Proper Motion DEC. After the list or target data are entered, click "OK Save Them" and all of the OBs will be created and saved. Below are some lines from a sample file:

wt000001;000001;object;358.203767;-85.895506;2000.000000;0.000000;0.000000;0.000300;0.016000 
wt000002;000002;object;293.179646;-81.530525;2000.000000;0.000000;0.000000;0.023600;-0.053000 
wt000003;000003;object;185.340638;-80.061558;2000.000000;0.000000;0.000000;-0.021300;-0.008000 
wt000004;000004;object;59.302004;-76.510811;2000.000000;0.000000;0.000000;0.004300;0.039000 
wt000005;000005;object;288.589596;-77.047883;2000.000000;0.000000;0.000000;-0.000400;0.017000 
wt000006;000006;object;153.119279;-76.077500;2000.000000;0.000000;0.000000;0.004500;-0.013000 
wt000007;000007;object;13.282362;-74.651553;2000.000000;0.000000;0.000000;0.061300;0.023000 
wt000008;000008;object;233.313454;-73.543803;2000.000000;0.000000;0.000000;-0.002400;-0.010000 
wt000009;000009;object;88.769146;-72.814744;2000.000000;0.000000;0.000000;-0.009300;-0.061000 
wt000010;000010;object;302.644600;-71.642242;2000.000000;0.000000;0.000000;-0.007300;0.026000 
wt000011;000011;object;153.368129;-71.668844;2000.000000;0.000000;0.000000;-0.018600;0.024000

Creating OBs on-the-fly

It is possible to set up exposures from within the LBC User Interface. This is most useful for taking test data --- e.g. to take a single short exposure on the target field to check focus, pointing or exposure times. The data are saved and the OB is saved to the archive as fast.ob but a permanent copy is not written to the disk on the user machine - it will be overwritten the next time the interface is used.

In the LBC User Interface, click OB Execution to display that page. Click the "Create an OB" button near the top which will bring up a new window.

Under General Data, enter the target name and select the image type (Object, Zero, Dark, Flat, Illum, Fringe, Focus). The type dictates which of the entry boxes below need to be filled in (e.g. for non-focus image types, the focus increment and step boxes are greyed out).

In Telescope Pointing select the coordinate system Equatorial (Alt/Az is not yet enabled) and enter the RA, DEC and epoch. There are 3 checkboxes on the left side of this panel:

If you don’t want to command a slew but want to take the image where the telescope is currently pointing, check the box to the left of Keep Current Pointing.
Check the box to the left of Drive Telescope if you want the OB to command the telescope pointing and mirror position.
Checking the box to the left of Telescope Guiding will enable guiding with the technical chips.

If you want to take a series of dithered images, in the Dithering section check the box to the left of Enable and then enter the number of images to take under Number of Positions and either a single number, to specify the radius of a circular dither pattern (in arcseconds) where the first position is the center and the subsequent positions are equally spaced along the circumference; or a series of RA,DEC offsets (arcseconds) in which commas separate the RA and DEC offsets and semi-colons separate the pairs for each dither position.

Finally, in either the Blue Channel, Red Channel or both sections, enter the observing configuration. Checking the box to the left of enable will enable the channel. Checking the box to the left of Limit to FOV center will cause it to read out only the upper 2048 rows of chip 2. Position angle can be set. If left blank, the rotator will not be commanded to move but will remain in its current position. If the image type is focus, then boxes for initial focus value, focus increment, number of focus images in series, and final focus will be activated. Hitting tab moves from box to box and updates the values. The filter, detector integration time (Exp), number of integrations (Num) are entered in the next line. Total time is calculated automatically. If filter is left blank, then no filter move is commanded and the data will be taken with whatever filter is currently in the beam. For bias images, Exp is fixed to 0. When finished entering these values, click more to write this line to the box below. Multiple observations, using different filters, integration times and number of integrations can be written to the OB – enter the data and click more. These will be added to the list in the box below. To remove an observation, select it from the list in the box, and enter 0 for Ndit and then click more.

Review the fields, especially that the Drive Telescope, Keep Current Pointing and Telescope Guiding boxes are checked as you wish, and then click the downward pointing arrow at the bottom of the page to upload the OB to the OB execution page.

Editing the xml file

Any text editor can be used to edit an existing .ob file by hand. Following is a list of the most frequently changed parameters and brief descriptions or definitions of these:

ClassType: object,focus, flat, bias, dark
TEC_RA and TEC_DEC: RA and DEC in decimal degrees and J2000. DEC=-90 signals that the OB will be carried out where the telescope is currently pointing.
Tracking: indicates whether the Rotator Tracking is on (1) or off (0).
Telescope: if equal to 1 enables slew, tracking and mirror control from OB.
WYMIN and WYMAX: Set different from 1 and 4608 if only a subset of rows is to be readout.
LBCUSER The value of LBCUSER, which should be the PI Name, is written to the keyword LBCUSER of the primary FITS header.
OBSERVER The value of OBSERVER is written to the keyword OBSERVER of the primary FITS header. Current values can be (upper or lowercase): inaf,lbtb, osurc,az,calib.

RotAngle_B: The position angle for the observation.
FocusStartPosition, NExpo, FocusOffset: For ClassType focus OBs, these are the starting focus value, the number of exposures and the focus step between each one. Typical values for FocusOffset are 0.1 for a coarse focus and 0.05 for the fine focus.
Chip1B, Chip2B , Chip3B , Chip4B: Insure these are 1 if that chip is to be used and 0 if not. Focus sequences typically use only chip 2.
ShutterB: 0 if shutter is to remain closed; 1 if shutter is to be opened.
FilterNumber_B: Number of observation configurations to cycle through (usually each with a different filter).
FilterName: U-BESSEL,B-BESSEL,V-BESSEL, r-SLOAN, g-SLOAN, SDT_Uspec
SingleExpoTime: Exposure time in seconds
Nexpo: the number of exposures per dither position at a given filter. Each image is saved as a separate file. Usually 1 except for focus sequences.

Calibration OBs

A set of generic calibration OBs have been collected and are available in the tar file, Calib_OBs.tar, which you may download and edit as necessary. The top directory, Calib_OBs, contains the following subdirectories. README.txt files within each subdirectory describe the contents. These are linked below for convenience.

BIASDARK: OBs to take a series of biases and a series of darks. Note that these cannot be combined in one OB, because there is only one IRAF 'imagetyp' (OBJECT, FLAT, BIAS, DARK,...) allowed per OB. README.txt
FOCUS: two OBs used to obtain extra-focal pupil images.README.txt
SKYFLAT: These skyflat OBs which are set up to dither at five positions about the current pointing (dec = -90) will no longer dither. The OB must contain a valid set of coordinates in order to dither. The observer must either enter coordinates into these, or generate a sky flat OB using the mkskyflat script, available in this Mkskyflat1.tar file. For more information on how to use mkskyflat.pl and the approximate exposure time scaling between filters, see the mkskyflat_README file.
STANDARDS: for standard stars.README.txt
SUPERFOC. These 'superfoc' OBs step through focus and are usually not used during observing, unless the filter focus offset needs to be re-determined.README.txt

Instruments & Operations