An Overview of the Observation Preparation Tool Web Application

The OPT, SCT and RCT abbreviations were introduced in the previous section. When referring to the OPT in the remainder of this document, most of the time it is implicitly referring to the tool that creates a sequence of observing scans. On the other hand, when we refer to the OPT web application we specifically refer to the combination of tools consisting of OPT, SCT and RCT.

The use of the term (re)source is short-hand for the text source and resource: the sentence applies to both source and resource. Similarly, project (etc.) allows us to avoid having to write project, program block(s), scheduling block(s) and scan(s) which otherwise would make sentences confusing. For program block and scheduling block we will use PB and SB, respectively, or blocks when we mean either or both.

We will further use PST and PSC to refer to the Proposal Submission Tool and Proposal Selection Committee, which have some interaction or influence on what goes on in the OPT web application. Finally, we will use OSRO to indicate anything related to the Open Shared Risk Observing period, starting in the spring of 2010, for which the full capabilities of the new EVLA WIDAR correlator are not yet available.

The current (January 25, 2010) purpose of this document is to provide help to the individual preparing EVLA observations with the new WIDAR correlator during the Open Shared Risk Observing (OSRO) period. This document consists of an introduction to the new Observation Preparation Tool (OPT) web application, hints and preliminary cookbook-like approaches to create a successful observing schedule, and contacts for further assistance. This document is not suited to learn, nor intended to teach, observing strategies and good observing practices; it is assumed that the individual either has prior knowledge of this, or will educate himself/herself on this subject before finalizing an observing schedule. The Observational Status Summary and other EVLA documentation (http://science.nrao.edu/evla/) are great resources with further references. The target audience is the successful proposer at the October 2009 (or later) deadline that proposed for EVLA array observations with the WIDAR correlator during the OSRO period. Depending on progress of the WIDAR commissioning, user feedback, upgrades to the software and new capabilities, this manual on the OPT web application scheduling tool may be updated, expanded and made available for other observations in the near future.

An observing schedule using the EVLA electronics and correlator is made through the OPT, the Observation Preparation Tool web application. It consists of a description of creating an observing run, a Scheduling Block (SB), which is made up of a sequence of observing scans. To make full use of the OPT, it is usually necessary to pre-define (i.e., enter) sources to be observed using the SCT, the Source Catalog Tool, and to possibly pre-define the frequency and correlator settings to be used using the RCT, the hardware and instrument configuration “Resource Catalog Tool”. This document should aid in creating source and resource lists, and in creating the final observing schedule (a Scheduling Block). Alternatively, if no user catalogs are defined, then one can resort to observing calibrator sources using standard correlator settings, although using these catalogs only may be rather restrictive in scientific discovery space. Once familiar with the concept, one will probably recognize some similarity with the observe list, source list and user defaults as previously used in Jobserve; there are, however, major differences.

It is suggested you pay attention to the following guidelines. We list them here in some preferred order to allow you to avoid the most obvious problems. Of course you can change the order of items listed here, but so far our limited experience with this new tool indicates that the order below in general is a good way to proceed. Also, we have set up this manual to make you familiar with the tools, features, possibilities, concepts and practicalities in a relatively natural way, so that a next step becomes almost intuitive1.

1. Collect proposal information to remind yourself the details of your observing proposal. It is good to have your proposal handy; it should be available in the Proposal Submission Tool (PST; accessible from the NRAO user data base just like the OPT web application) if you have not printed a copy already. For continuum observations you will need the positions of your target sources (and calibrator sources if you specified them) and frequency bands of your observations. For spectral line observations you also need either an exact sky frequency or a combination of rest frequency, velocity and velocity reference frame information on your target sources, a bandpass calibrator and the details of the correlator configuration.
2. Collect post-proposal information and check the comments of the PSC; they may have given you advice on technical limitations on current developments, probably assigned you a technical contact person, and perhaps determined a fixed observing date and/or limited your requested observing time. As guidelines on the “EVLA returns” page may have changed in the meantime, it is also wise to reread the EVLA returns page (http://www.vla.nrao.edu/astro/ and referenced links therein). Another good resource on current information about the EVLA is the Observational Status Summary (http://science.nrao.edu/evla/proposing/obsst
3. Outline the project in terms of program/scheduling blocks as at this stage it is not completely known what information from the PST is transferred to the OPT web application (and thus fixed and read-only for you). This read-only information will likely be the project Legacy ID, PB and allocated time, and possibly (at some stage) array configurations, SBs, and (re)source catalogs.  You should at least figure out how many SBs you need and which sources with which resources you want to observe in each SB. Note that you can reuse the same SB if the only difference in SBs is having multiple observation runs of the same source/resource combinations to increase the observing time on your target source beyond the time your target is above the horizon. It is possible copy and submit multiple SBs that are the same, but it is probably easier to specify a count larger than one in the SB Details page in such a case.

The page shown directly after logging in to the OPT web application should be the OPT front page with your project tree consisting of a PB, an (empty) SB and an empty first scan. Some information on this page should be already filled out and read-only. Check this information with the information you gathered in the previous section and inform us as soon as possible if you think there is an error in any of these fields; the sooner you check this the sooner we can have it corrected, and the sooner you can start struggling with the tool... Fortunately, it most likely won’t be that complicated, but it is a good idea to allow yourself ample time to get used to the tools and to let us help you with your questions.

For the remainder of this document, we’ll guide you through the different components to create an observing schedule in the following chapters. As it seems that the RCT is the easiest (for now, which probably changes with progress in commissioning of the WIDAR correlator), we’ll start with that one. The SCT and OPT use many features or concepts that are similar to the features or concepts in the RCT, so that should help to get to know the other tools. As the OPT must use information defined both in the SCT and in the RCT, we’ll continue with a chapter on the SCT before the chapter on the OPT. The chapter after the OPT deals with some common problems we already have encountered, so check there first, e.g., if you find yourself bumped out of any of the tools.

If at any time you wish to exit, use FILE - SAVE ALL if there is work done on catalogs or projects that you want to keep. A dialog box asking whether you want to save changes if any unsaved changes remain will pop up if you exit using FILE - EXIT. Note that if you navigate from one tool to another, using the links in the “navigation strip”, your changes in the tool you are leaving will be automatically saved.

As an advance hint on user friendliness, it is a personal experience that it is convenient to keep the RCT and SCT catalogs or groups as compact as possible because you need to select from these catalogs in the OPT. That is, it is best to keep only the sources and resources you want to use in a single SB in a (group in a) catalog, and to include the calibrators from large lists (e.g. the VLA calibrator list) already in that source catalog. What is meant by this and why will become clear later on.

A project (an orange P: ; Figure 1.2) consists of at least one program block (PB, a blue PB: ), which is defined as a collection of observations for a single proposal, using a single telescope or an EVLA array configuration (or a sequence of consecutive configurations). That is, typically a PB does not extend to another allocation trimester; e.g., if you were allocated time for the A array and the CnB array, one PB would be defined for the A array and one would be reserved for the CnB array observations in a following allocation trimester. A PB is made up of at least one scheduling block (SB, a green SB: ), which consists of a sequence of scans (a radio telescope: ): combinations of a timed telescope pointing direction (a source) using a specific hardware and instrument configuration (a resource) in a specified observation mode with a specific intent. Scans may be grouped in scan loops (a looping circle: ), or loops (of loops, ..) of scan loops.

For fixed date observing, each allocated time slot will typically be equivalent to a SB. For dynamically allocated observing time, a SB is not necessarily the same as a complete observing run; one can think of an observing run as a random or specific order of several executions of a SB on the sources of interest, whether or not on the same observing day, possibly interspersed with a SB performing flux calibrations, a SB performing observations at a different frequency, etc.

Figure 1.2: The PROJECT tree consists of at least one PROGRAM BLOCK (PB); A PB is made up of at least one SCHEDULING BLOCK (SB), which consists of a sequence of SCANS with or without LOOPS of scans.

In general, SBs may be many different snippets of an observing run, i.e., groups of consecutive scans that constitute a complete observation (a PB), but an observing run may as well be defined in a single SB. It depends on what the user finds convenient; for example one can define a template calibration SB on J1331+305 that can be copied to each new PB assigned by the PSC. However, observing time typically is allocated in a multiple of 30 minute LST slots, in which case the user will probably typically schedule a PB in SBs with a maximum length of an integer number of 30 LST minutes. For the final SBs, the ones that through the OPT are submitted for observation, the duration of the observation of the SB is required to be an integer number of 30 LST minutes maximum. This is not necessary for template SBs or SBs that will not be submitted.

The front page of the Observation Preparation Tool (OPT) is is the page shown directly after redirection by the NRAO user database. The front page shown after navigating to the SCT or RCT is very similar. The web browser window is set up in four main panels (Figure 1.3):

• The menu and navigation strips at the top
• The interface feedback strip at the bottom
• The left hand side column; in the OPT it contains a collection of projects, in the SCT it contains a source search section on top and a collection of source catalogs below it, and in the RCT it contains a collection of resource catalogs (hardware/instrument settings).
• The main editing window; a project (etc.), source or resource manipulation field where most of the editing for each of the different tools occurs.

The relative sizes of these panes can be modified by dragging the dividing lines with the mouse button pressed.

The menu and navigation strips are the first and second line, respectively, at the top of the web interface with menu/navigation items written in white letters on a dark blue background.

The menu strip is used to manipulate – import/export, create/edit, save/delete – projects (etc.) and (re)sources.

The navigation strip allows one to switch between the three components (OPT, SCT, and RCT) of the scheduling software; the bold-faced name is the currently active tool and the underlined names are links to the other tools.  Note that we use Observation Preparation for the OPT, Sources for the SCT and Instrument Configurations for the RCT.

More on using the menu items can be found in following chapters.

Occasionally you may encounter the reddish colored Important message banner just below the menu and navigation strips.  We use this banner to convey anticipated downtime, emergency software updates, etc. Scheduled regular maintenance would occur on the first and third Wednesday of the month, starting at noon Mountain time (6 or 7 pm UT). A reminder for this, for example, will appear some time before the downtime in the “Important message banner” suggesting you to save your work promptly.

Figure 1.3: General layout of the Observation Preparation Tool web application page in the web browser. For the SCT, the left hand side column includes a source search tool and thus looks slightly different (see inset left).

The interface feedback strip is the strip over the full web page width at the bottom of the page. This strip is used to display feedback information such as error messages (in red font) and warning messages (in blue font) generated by the web interface when entries made through the web interface are validated. It is advised to pay attention to these messages as it may be the only indication that a schedule is faulty. A SB with errors cannot be submitted, but a SB with warnings may be submitted if the observer persists.

The left hand side column, depending on which tool is selected (OPT, SCT or RCT with their more descriptive names in the navigation strip), should have at least one project, source catalog or resource catalog visible.

• OPT (Observation Preparation).  The OPT project column should contain the program for which you were awarded observing time. If not, please let us know as soon as possible (vlahelp@nrao.edu). Other catalogs may be visible, in particular if you had previous observing programs or if you were awarded observing time for more than one project in this proposal round. Different icons in the tree depict different items:  for projects, for program blocks,  for scheduling blocks, and  for scans or  for scan loops.  When using this for the first time, the project tree should be visible all the way to the first scan level (otherwise it may only show the ). Some of the information may have been entered from the details of your proposal and should be read-only.

  A small plus-sign () icon in front of a project or catalog means that there are items defined within that item; click on it to expand and display a tree-view of these items. For example, clicking on a plus-sign icon in front of a project (orange P) will expose, or expand, a list of PBs in that project, etc. Clicking a small minus-sign () icon will hide, or collapse, all content within that item. For speed and memory reasons, not all projects are loaded into memory from the start; if there is no plus-sign associated with the project you would like to work on, simply click (highlight) the project name to load it in memory.

  Above the project list and each of the source and resource catalog lists, there is an icon menu. In the SCT case this icon menu will be located between a source search tool (on top) and the source catalog list below it. These icons can be clicked to save, cut/delete or copy/paste entire PBs, specific SBs or individual scans, or (re)source catalogs or (re)source groups. The options of this icon menu only act on the items in the tree, not on the items in the main editing window. In contrast to the small icons in front of a tree item, plus-sign and minus-sign icons in the icon menu expand or collapse the entire tree under a selected (highlighted) item. Arrow icons in the OPT, visible whenever a scan is selected, move items around in a tree. Navigating between projects, blocks and scans in the OPT is simply done by selecting (click to highlight) any such item name in the tree. Similarly one can navigate between a tool’s catalogs and groups in the left hand side column trees (in SCT and RCT).

• SCT (Sources)  At the top of the left hand side column of the SCT is an interface to search for sources. The source search is performed on a source name only in the selected source catalog (highlight it by clicking) in the list of catalogs in the bottom part. Alternatively, the source is looked up in the SIMBAD data base when the external search field and button are used. Check the alias box if you have not entered the name of the source in the selected catalog, but e.g. its 3C name. Use Advanced Search if you want to search on something else than a source name in a single catalog.

  In the bottom part of the left hand side column of the SCT, there should be at least one source catalog visible in red italics, namely source catalog VLA, containing the VLA calibrator list. There may be other source catalogs visible, in particular calibrator lists from other telescopes and catalogs that you have defined yourself. Catalogs in red italics are read-only. Small plus-sign icons mean that there are groups of sources defined within a catalog; click on it to expand and display these groups. Groups may also contain (sub)groups that can be expanded.

• RCT (Instrument Configurations)  At least one resource catalog is visible in the RCT resource catalog column, in red italics, namely resource catalog “NRAO defaults”. It currently contains the NRAO default hardware/instrument settings for OSRO continuum and spectra-polarimetry per observing band: 3 second correlator accumulation times of two 128 MHz subbands (formerly identified as IFs) using full polarization and divided in 64 channels per polarization product. Furthermore it contains WIDAR setups for pointing scans at the higher frequencies. Other resource catalogs may be visible, i.e., if any were defined previously. However, note that resources used previously for the VLA correlator cannot be used with the WIDAR correlator from now on! The same editing and navigation rules apply as for SCT catalogs, e.g., catalogs in red italics are read-only.

More on manipulating PBs, SBs and scans in the OPT, manipulating (re)source catalogs and (re)source groups, and using the source search tool can be found in following chapters.

The main editing window, or manipulation field, exposes different information fields per tool and per item type. However, the SCT and RCT in first instance both show a very similar table of catalog contents, i.e., a table of entries in the selected catalog or group. First we describe the OPT case as it is the first you will see when logging in to the OPT web application.

• OPT When a project is selected (highlighted), the main project (etc.) manipulation field will show the details of this project (and PB, SB or scan details on underlying levels). Most of this upper level information may have been entered and fixed (read-only) by the Proposal Scheduling Committee (PSC) or other NRAO staff. The information in this OPT window will be different according to the item that is selected. If instead of a project a PB is highlighted, information on array configuration (for EVLA projects) and underlying SBs appear. The information on selecting a SB is spread over three pages, each accessible via its own tab at the top of the main window (in this case SB Details with e.g. LST start time, SB Summary with e.g. a scan list, and Validate & Submit). Selecting a scan deploys another couple of tabs in the main editing window.
• SCT Selecting a source catalog or group within a source catalog in the SCT will show the sources in this catalog or group in the form of a table listing in the main source manipulation field. If the list contains more than 25 sources, this list will occupy multiple pages, which can be browsed using the page selection buttons at the top and bottom of this table in the main window. Instead of 25, one can select a higher number of entries per page at the top of the page. The source table contains a source per row with a check box, an editing icon (), a field for the source name, the coordinates and other details. The coordinate frame used for display in the table is listed above the source table, and may be re-selected. Hovering the mouse over the items in the “Details” column pops up additional source information when available.
• RCT A selected resource catalog or group within a resource catalog shows a similar table listing in the main resource manipulation field, but now with resources. Again, initially there are up to 25 entries per table  (i.e., per page) shown, and the different pages are navigable using the buttons at the bottom. The resource list contains a resource per row with a check box, an editing icon, a field for the resource name, the telescope, frequency band and back-end of the resource, and a field for user comments. This view will likely change with advances in WIDAR commissioning.

More on manipulating block and scan information, or on manipulating (re)source information can be found in following chapters.

The Observation Preparation Tool (OPT) is one of the three tools (OPT, and SCT and RCT below) of the OPT web application, and is used to schedule an observation by creating a list of scans and to generate an observing run (Scheduling Block) from that list. Each scan consists of a telescope pointing direction (selected from the SCT below) using a specific hardware and instrument configuration (selected from the RCT below) combined with an observing mode action lasting for a time interval (specified using this OPT), and typically for a specific reason, an intent. A schematic flow diagram with these components is shown in Figure 1.1.

Figure 1.1: Schematic flow diagram from an approved proposal to completion of all observations for a project. The purpose of the Observation Preparation Tool web application is to get from the proposal to the observing scripts. Flow along the gray arrows is the responsibility of NRAO. Either NRAO or the user will have to fill out the path along the flow of the white arrows. The flow along the black arrows is the responsibility of the user, using the SCT (blue box), the RCT (red box) and the OPT (green area) in the NRAO OPT web application.

The Source Catalog Tool (SCT) is the OPT web application tool that is used to specify a collection of telescope pointing directions, from which one can select when creating a list of scans in the OPT.

The Resource Catalog Tool (RCT) is the OPT web application tool that is used to specify a collection of hardware and instrument configurations, from which one can select when creating a list of scans in the OPT.

The OPT web application is started by pointing your web browser to https://my.nrao.edu/ (note the extra “s” in https for encrypted connection). It will require you to log in to the NRAO user data base, for which you probably already registered as otherwise you would not have been able to submit the proposal. (Re)Register again with an email address known to NRAO if necessary, e.g., if you are a co-investigator who did not submit the proposal. Do not use the registration owned by someone else as this will severely upset the system.

After logging in to the NRAO user data base there should be a Obs Prep menu tab. Click it!

It will redirect you to a welcoming page that will take you to the OPT web application (https://e2e.nrao.edu/opt/).  In the OPT web application, you will notice the top two bars, one with file manipulation labels (File, Edit, Help) and a navigation bar (NRAO > User Portal > ..). The web application opens up in the OPT (i.e., the scan sequence tool, in the navigation bar labeled as Observation Preparation), but also lets you navigate to the SCT and RCT (in the navigation bar using the links labeled Sources and Instrument Configurations, respectively). We have tried to keep the OPT, RCT, and SCT tools and, e.g., editing concepts as similar as possible so that the look and feel in one tool should be similar to that of the other.

Note that the OPT is a web application. It should thus be available and perform similarly on most common web browsers and operating platforms. For us the big advantage is that we can keep everybody up to date with the latest code, without having to worry about the hardware and software you use, while more and more features of the WIDAR correlator (and the EVLA receivers) are commissioned. A drawback is that it may take a while to connect and reconnect between user web browser and NRAO user data base, i.e., that operations may take longer than expected. Also, the web application has to time out at a certain point, and connections may be interrupted unexpectedly and/or inconveniently. We have a separate chapter near the end of this document on what to do in which case. To exit gracefully, go to File in the menu strip and choose Exit (which is typeset as FILE - EXIT from here).

Please, do not use the browser back button to navigate to the previous page. This may give you browser errors and might prevent you from working on your project for a few hours. Also please be patient; when you enter or click something it may take a few seconds to connect back and forth between your browser and the NRAO data base. You want to avoid clicking or entering before the previous action was completed. Be patient and watch the busy icon of your browser to cease (and sometimes even a bit longer).