Within the OT, click on buttons in the science program elements toolbar to add the program elements defined in the following table. Click on the element name in the table to jump to further details below. The science program has a hierarchical structure; if an element cannot be added to the selected node, it appears grey in the toolbar (examples are given in the table).
| Element | Function | |
 |
Observation | Add a new observation to the science program. Available only when the science program or group are selected (see example). |
| Group | Add an observation to a new group or folder. Available only when an un-grouped observation is selected (see example). | |
| Note | Add a text note to an individual observation or the entire science program. | |
| Component | Add observing condition constraints, telescope and WFS targets or instrument configurations to an observation. Available only when an observation is selected (see example). | |
| Iterator | Add a telescope offset (dither) sequence, a repeat loop or an instrument configuration sequence to an observation. Available only when the sequence folder or another sequence iterator are selected (see example). | |
| Observe | Add observe command(s) to take science or calibration data. Available only when the sequence folder or a sequence iterator are selected (see example). The Observe Class determines how the execution time is charged and data release date. |
More guidance on the use of the science program elements is given below and in the associated links.
Observation
This is the container for everything associated with an observation. Normally the observation is the smallest schedulable element and corresponds to one telescope pointing. Each new science target, PSF or other calibration star must be defined as a separate observation. Likewise, each observation in the sequence star-object-star-object... must be a separate observation. There may be many observations within one science program.
An observation must be self-contained and possess (a) a target list, (b) an instrument component, (c) observing conditions and (d) observe command(s). Optionally it may include telescope and instrument iterator sequences and a text note.
When opening a downloaded science program for the first time, it will be populated with template observations taken from your approved Phase I proposal in the new Templates folder. The configuration information from the proposal has been added to the template observations. There is one template group for each requested configuration. Phase I targets with their associated conditions and total times are viewed by clicking on the template group node. Baseline calibration observations may be included in a separate "Baseline" folder. Draft observations for telescope scheduling are create by applying the templates to the associated targets and conditions. This is done by clicking the Apply button in the main toolbar or by selecting Templates -> Apply Templates... from the Edit or right-click menus. Updates to the templates can then be reapplied to the draft observations using the Reapply button or 'Reapply Templates...' menu option.
New observations from the Observation menu of the program elements toolbar are created with a default observing condition constraints component (note: all constraints are set to "Any"), an empty telescope targets component and an empty sequence folder.
The ordering of the observations in the science program does not convey any prioritisation. The relative importance of individual observations within a program can be set using the low/medium/high priority flags in the detailed observation component editor.
Selecting an observation in the science program viewer opens its detailed editor.
For quick review of an entire program, the observation status flag defines the colour of the observation icon in the science program:
 |
Phase II - awaiting detailed design |
 |
For review (by NGO staff) |
 |
In review (by NGO staff) |
 |
For activation (by Gemini staff) |
 |
On Hold - checked but not to be queued, e.g. waiting for ToO trigger |
 |
Prepared - Ready (for execution) |
 |
Ongoing - execution in progress |
 |
Observed - observation data taken and execution complete |
 |
Inactive - observation not needed, not to be queued, does not contain an observation log |
Groups and Folders
Observations can be organized into either scheduling groups or organizational folders. Observations in scheduling groups will be executed sequentially (see details of the hierarchical structure for more execution information). When this is done, the group becomes the smallest schedulable entity. The standard rules of Baseline calibrations apply. For example, if two observations with class Nighttime Partner Calibration are included in a group (say they are before and after telluric stars) with one science observation, then only one of the standards will be executed if the total integration time on the science target is less than the time for which two baseline standards are required. In general, all observations with classes Science or Nighttime Program Calibration will be done unless instructions to the contrary are provided in a Scheduling Note. Folders are merely organizational structures. Science and Calibration-class observations in folders will be scheduled and executed independently.
With an observation selected in the program viewer, click on the Group button to add the observation to a new group. Clicking the Group icon will reveal a menu with the options Scheduling Group and Organizational Folder. Select the type of group that you want to create and the selected observation will become a member of this group. To change the type of group, select the top level of the group and then change the type from the Group Type menu (see below). The Group Name can also be edited from the group component.
Changing the Group Type to Organizational Folder will also change the group icon to a folder so that groups and folders can be easily distinguished. An example program with both groups and folders is given below.
Observations can be added to existing groups or folders in two ways: (a) select the observation and drag-and-drop it onto the group/folder element or (b) select the observation, cut (or copy) it, select the group and paste the observation. (You can use the cut, copy and paste buttons on the main toolbar, menu bar edit item, or the right-click menu).
To un-group an observation, drag-and-drop it onto the top-level science program.
You cannot manually delete (i.e. cut) a group. The group disappears when it no longer contains any observations.
Notes
A text note can be added to provide explanatory information such as the intention behind a particular offset sequence or target acquisition instructions.Notes can be added to the top-level science program, to groups and to individual observations. You can add as many notes as you like.
Selecting a note in the science program viewer opens its detailed editor. This allows you to change the name (e.g. to "acquisition instructions") and add text.
Notes come in two flavors, regular notes for general information and scheduling notes for any additional information related to how the program/group/observation should be scheduled. Requested airmass or hour angle constraints should be put here (see below).
Components
There are three types of components that together define the base, static configuration of an observation: observing conditions, targets and instruments. A valid observation must contain one (and only one) of each.
Observing Conditions Component
The observing conditions component is used to defined the observing constraints for that observation. Selecting this component in the science program viewer displays the four weather constraints (image quality, sky background, cloud cover, and water vapor) as well as new elevation and timing window constraints in the editor. If the science program has been downloaded from Gemini Observatory, each observation will already contain the constraint set specified in your approved Phase I proposal. In general, you may relax the observing conditions but you may not change to better conditions than approved by the ITAC without obtaining approval via a change request. The translation between the percentile bins and actual conditions is given in the observing condition webpages.
By default there is no elevation constraint since this maximizes schedulability. Use of these constraints is equivalent to a change to better conditions constraints than approved by the ITAC, therefore approval must be granted via the change request procedure before the elevation constraints can be modified. Include justification for why the elevation constraint is needed in the change request. An example of an observation that would use these constraints is one using GMOS that needs to restrict the hour angles so that the position angle of the slit(s) is close to the parallactic angle. Before making the request, be also sure to use the elevation plot feature to check that the requested constraints are reasonable and allow the observation to be scheduled. After the approval is granted then you should edit the constraint type and values as appropriate.
The timing window constraints may be added for any observation that must be observed at a particular time. The timing windows are the periods when the observation can be scheduled. An observation will only be scheduled in one of these windows at a time until it is observed. If an observation can only be done at one time, then the window should not repeat. A given observation will only be observed in one of the timing windows. Therefore, monitoring programs will need to define separate observations for each repeat visit.
The Timing Windows table is shown at the right. At the bottom of the table are four action buttons to Add (+), Import, Remove (x), and Edit. Pressing the green "+" button will open the Timing Window Editor (shown to the right below the table) which allows manually adding timing windows. Pressing the "import" icon will open a window to select the file to import. The Remove button will remove the selected windows, and the Edit button allows modifying an existing window.
When Importing Timing Windows from an ASCII text file the windows are specified one per line. The first two columns are the starting UT date and time, the third column is the duration (HH:MM), the fourth column is the (optional) number of repetitions, and the final column is the (optional) period (HH:MM:SS) of the repetitions. A duration of 0 indicates that the window is open forever, and -1 repetitions indicates that the window repeats forever. Click here to download the demo input file used to create the timing windows listed in the table.
If any observation within a scheduling group has timing constraints, then the constraints apply to the entire group. If observations within groups have different constraints, then the most restrictive set is used.
Target Component
The target component is used to defined the science and wavefront sensor co-ordinates. This component defines the static configuration; the offset iterator (described below) allows mosaic/dither/nod patterns to be constructed around it.
If the science program has been downloaded from Gemini Observatory each observation will already contain the targets specified in your approved Phase I proposal. If the observation is of a new target, the observation element is created with an empty telescope targets component and the science program viewer displays a placeholder (RA:00:00:00.00 Dec: 00:00:00.0 HMS Deg (J2000)) until an object name is given. Selecting the (named) targets component in the science program viewer opens up its editor (see more details about the target component editor).
Instrument Component
There are instrument components for each available facility instrument. An instrument component must be included in each observation and defines the static configuration. Instrument iterators, described below, allow you to modify the instrument configuration (e.g. cycle through filters) as part of an observation.
To add an instrument component, select the observation within the science program viewer, click on the component element in the toolbar and select the desired instrument. Selecting the specified instrument component in the science program viewer opens its detailed editor; more details are available for the following instruments:
* Retired instruments
If you wish to change information from that contained in your Phase I proposal please read the change request instructions.
Iterator
Observation components (described above) are used to define the base, static configuration of an observation. However, to perform any even mildly complex observation, iterators are required. Iterators are placed in the sequence node of an observation and are used to define the series of actions that will be performed to collect the data. The sequence folder is automatically created whenever a new observation is created.
There are three types of iterator available: repeat sequence, telescope offset sequence and instrument sequence. There is (to be) one instance of the instrument sequence iterator for each facility instrument. All of the iterators are optional (but extremely useful). The sequence folder may contain no more than one instrument and one offset sequence iterator. To add an iterator select the sequence folder in the science program viewer, click on the iterator element in the toolbar and select the desired sequence type.
The offset and instrument iterators allow you to change in a single step any configurable attributes of an item. For instance, with the NIRI iterator you can set up a series of iteration steps each of which simultaneously changes the selected filter, exposure time and number of coadds. Selecting the specified iterator in the science program viewer opens its detailed editor; more information is available for the following iterators:
| General Iterators: | Gemini North: | Gemini South: |
| Offset iterator | NIRI iterator | T-ReCS iterator* |
| GPOL iterator (incomplete) | GMOS iterator | GMOS iterator |
| Michelle iterator* | Acquisition Camera iterator (incomplete) | |
| NIFS iterator | GSAOI iterator | |
| GNIRS iterator | FLAMINGOS-2 iterator | |
*Retired instruments
Iterators can be nested, much like nested loops in a programming language. For each step of the top-level iterator the nested iterator cycles through all of its values. See the science program structure for more details about nested iterators.
The repeat iterator simply loops over the subsequent elements the specified number of times.
The sequence node, which serves as the root of the iterator sub-tree, has a special feature that allows you to check your work. Selecting the sequence folder in the science program viewer displays the sequence as a table, a list of actions, and as a timeline. The sequence is re-calculated whenever you change iterators or observe elements.
Starting with the 2008A OT the default sequence view is a table showing the dynamic (changing) elements at each step in the sequence.
Tree view with corresponding sequence summary table.
All significant overheads should be included in the timeline and planned time calculations, though we continually strive to refine them. Note that only a single acquisition per observation is include. Extra overhead must be included if the observations is long (more than about 2 hours duration) and will probably need more than one acquisition.
Observe
The observe elements are the only ones that actually take data. This includes (a) data on the sky, (b) bias and dark datasets (with the detector blanked off or shutter closed) and (c) flat-field and arc datasets using the facility calibration unit.
Selecting an observe element in the science program viewer opens its detailed editor. Each observe command takes one dataset. A dataset is one file and may contain multiple frames within the multi-extension FITS structure depending on the specific instrument (e.g. the number of coadds, if supported and not coadded within the instrument,whether it has multiple detectors etc.). Each observe is shown separately in the sequence list and timeline.
For example, NIRI coadds exposures internally to create one frame containing the average signal (currently it gives the sum, but ignore that for now). Specifying a NIRI observation with 60s exposures, 3 coadds/observe and 5 observes would create 5 datasets (files) each containing one science frame which is the average of 3 * 60s exposures.
Setting the number of observes to N is equivalent to putting the observe element within a repeat iterator with N repeats.
By definition, an observe element must be at the tip (leaf node) of every branch of the observation hierarchy for that branch to take any data (think of it as a "print" statement in a computer program).
Each Observe type (normal science Observes and bias, dark, flat/arc Observes) has an Observe Class associated with it. The class determines time charging, observation planning and data distribution. The Observe classes and associated charging are:
| Observe Class | Charge to |
| Science | Program |
| Nighttime Program Calibration | Program |
| Nighttime Partner Calibration | Partner |
| Acquisition | Program |
| Acquisition Calibration | Partner |
| Daytime Calibration | No Charge |
For schedule planning purposes only, the entire observation is given an Observe class based upon the classes of the Observes it contains. The actual Observe class determines the time charging.
To make observation definition quicker, the classes default to specific values depending on the Observe type that is added to an observation:
| Observe | Default Observe Class (Charge) |
| Observe | Science (Program) |
| Flat | Nightime Partner or Program Calibration, depends on the instrument |
| Arc | Nighttime Partner or Program Calibration, depends on the instrument |
| Night Baseline GCAL | Nighttime Partner Calibration (Partner) |
| Day Baseline GCAL | Daytime Calibration (No Charge) |
| Manual Bias | Daytime Calibration (No Charge) |
| Manual Dark | Daytime Calibration (No Charge) |
| Manual Flat/Arc | Nighttime Partner Calibration (Partner) |
These defaults are reasonable in most circumstances but will need to be changed manually by the PI in certain cases. The two most common general cases are: (a) standard star observations should have their Observe Class changed from Science to Nighttime Partner Calibration if they are a baseline calibration or to Nighttime Program Calibration if they are a special calibration, (b) acquisition observations should have their Observe Classes set to Acquisition or Acquisition Cal. as appropriate and (c) any arcs or flats that are not mixed with science observations and can therefore be taken during the day should be changed to Daytime Calibration.
The total planned time, the times charged to the program, the partner, and "not charged", and the elapsed time (normally the sum of the charged times) arenow shown for each observation and for the program. The planned time includes the time for only the first acquisition.