Facilities > VLA > Documentation > Manuals > OPT > An Overview of the Observation Preparation Tool Web Application

An Overview of the Observation Preparation Tool Web Application

« Return to page index

Observation Preparation Tool (OPT)

1. Introduction


This document describes the web-based tool to create Scheduling Blocks (SBs): machine readable instructions for radio astronomical observations using the Karl G. Jansky Very Large Array (VLA) and its WIDAR correlator.

This Observation Preparation Tool web application (OPT web application) consists of three separate tools that are used in conjunction. These are the Source Catalog Tool (SCT) to define and select positions in the sky, the instrument Resource Catalog Tool (RCT) to define and select hardware (receiver and correlator) settings, and the Observation Preparation Tool (OPT) to define and create a sequence of scans where a scan is a combination of an observing mode, a source, a resource, a time interval, and a scan intent.

This manual guides the reader through the three tools, providing adequate information and scheduling hints to create an observing schedule for observations with the VLA and how to submit the schedule to VLA operations. Considerable observing details and suggestions are collected in the VLA Guide To Observing. Additional specific guidance can be obtained through the NRAO Helpdesk.

The VLA will be observing in a mode where the observing schedule to be executed is selected from a pool of valid schedules just before the actual observations take place. This Dynamic scheduling is described in the VLA Guide To Observing. The life-cycle of the SB, some practical considerations for a higher success rate in the observing pool and, e.g., more detailed instructions for performing line observations that depend on Doppler calculations can be found there.

The Observation Preparation Tool web application (OPT) is a product of the National Radio Astronomy Observatory staff. The Karl G. Jansky Very Large Array (VLA) is operated by the National Radio Astronomy Observatory (NRAO), which is a facility of the National Science Foundation (NSF) operated under cooperative agreement by Associated Universities, Inc. (AUI).


Purpose of this Document

The purpose of this document is to provide help to the individual preparing VLA observations with the WIDAR correlator. This document consists of an introduction to the Observation Preparation Tool (OPT) web application, hints and preliminary "cookbook"-like approaches to create a successful observing schedule. This document is not suited to learn, nor intended to teach, observing strategies and good observing practices. The Observational Status SummaryVLA Guide To Observing, and other VLA documentation are great resources with further references. For more specific questions one may consult the NRAO Helpdesk.

An observing schedule using the VLA receivers, electronics and correlator is made through the OPT web application. It consists of a description of an observing run: a Scheduling Block (SB) that is made up of a sequence of observing scans. To make full use of the OPT, it may be necessary to predefine (enter) sources to be observed using the Source Catalog Tool ( SCT), and to possibly predefine the frequency and correlator settings to be used using the hardware and instrument configuration Resource Catalog Tool (RCT). This document should aid in creating source and resource lists, and creating the final observing schedule (an SB). Alternatively, if no user catalogs are defined, one can resort to observing known (calibrator) sources using standard correlator settings, although using these catalogs only may be rather restrictive in scientific discovery space.


Abbreviations Used in this Document

The OPT, SCT and RCT abbreviations were introduced in the previous section.  When referring to the OPT in the remainder of this document, 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, using '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 (Proposal Submission Tool) and TAC (Time Allocation Committee), which have some interaction or influence on what goes on in the OPT web application.

2. The Observation Preparation Tool Web Application

The OPT Web Application

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. If necessary, (re)register with an email address known to NRAO, 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, click on the Obs Prep menu tab at the top.

This will redirect you to a welcoming page containing a link to the OPT web application. In the OPT web application, you will notice the top two blue horizontal strips, one menu strip labeled File, Edit, Views and Help, and a navigation strip: NRAO > User Portal > .. and Exit. The web application opens up in the OPT (i.e., the scan sequence tool, in the navigation strip labeled as Observation Preparation), but also lets you navigate to the SCT and RCT (in the navigation strip using the links labeled Sources and Instrument Configurations, respectively). We have tried to keep the OPT, RCT and SCT tools as well as, 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 using JAVA. It should thus be available and perform similarly on most common web browsers and operating platforms. By using JAVA,  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. 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. To exit gracefully, go to File in the menu strip and choose Exit (which is typeset as FILE - EXIT from here), or find the Exit button at the right hand side of the navigation strip.

Do not use the browser back button to navigate to the previous page. This may give browser errors that 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). If you continue to have problems, contact us through the NRAO Helpdesk.


The OPT, SCT, and RCT Tools

The Observation Preparation Tool (OPT) is one of the three tools (OPT, and SCT and RCT) 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) 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 arrow. 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 list supplied in the PST will be transferred to the SCT for approved proposals; in the future this will happen for non-standard resources supplied in the PST as well but for now they have to be created in the RCT by the user.

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.


Projects, Program Blocks, & Scheduling Blocks

A project (an orange P: Project; Figure 1.2) consists of at least one program block (PB, a blue PB: Program Block), which is defined as a collection of observations for a single proposal using a single VLA array configuration. That is, typically a PB does not extend to another allocation semester; e.g., if you were allocated time for the A array and the B array, one PB would be defined for the A array and one would be reserved for the B array observations, perhaps in a following semester. You may also find PBs for the same array configuration but with time allocations split over different scheduling priorities. A PB is made up of at least one scheduling block (SB, a green SB: Scheduling Block), which consists of a sequence of scans (a radio telescope: 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: Scan Loop), or loops (of loops, ..) of scan loops.

For fixed date observing, each allocated time slot will typically be equivalent to an SB. For dynamically allocated observing time, an SB is not necessarily the same as a complete observation; a complete observation is when all data on the target(s) has been obtained. This may be a single SB or a random or specific order of several executions of SBs on the sources of interest, whether or not on the same observing day, possibly interspersed with an SB performing flux calibrations, an SB performing observations at a different frequency, etc.

OPT Figure 1.2

Figure 1.2: The project (P) 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 and what is smart given the scheduling priority; for example one can define a template SB containing the scans when starting with the flux density calibrator J1331+3030 (3C286) that can be copied to each new PB assigned by the TAC.


Page Layout of the OPT Tools

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 and a collection of source catalogs, 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.

Figure 1.3: General layout of the OPT 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 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, cut/paste – 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 later 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., suggesting you to postpone or finish your work promptly.

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 (red font) and warning messages (blue font) generated 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. Blank warning messages and some messages at the beginning of an SB (pertaining to on-source time of setup scans) can be ignored. An SB with errors cannot be submitted, but a SB with warnings may be submitted if the observer persists. Please note that the interface feedback strip may include a scroll bar when there are more warnings and errors to display than fit directly on the visible part of the pane.

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 using the NRAO Helpdesk. 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: Project for projects, Program Block for program blocks, Scheduling Block for scheduling blocks, and Radio Telescope for scans or Scan Loop for scan loops.  When using this for the first time, it may only show the Project; a project tree would be visible all the way to the first scan level with consecutive mouse clicks on the item names in the tree. Some of the information may have been entered from the details of your proposal and should be read-only.

    A small plus-sign (xpnd) 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 ( Project, orange P) will expose, or expand, a list of PBs in that project, etc. Clicking a small minus-sign (clps) 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 or SB you would like to work on, simply click the project name to load it in memory.

    At the top of the left hand side window, there is an icon menu. These icons can be clicked to cut/delete or copy/paste entire PBs, specific SBs, individual scans, (re)source catalogs, or (re)source groups. The options of this icon menu act only 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 tree under a selected (highlighted) item. Arrow icons 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, below the icon menu, 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, e.g., using a cone search on a position with a flux density limit.

    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, e.g., 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. The VLA catalog also contains subgroups 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 wide band (continuum) and spectra-polarimetry per observing band. Furthermore it contains WIDAR setups for pointing scans for observing at the higher frequencies. Other resource catalogs may be visible, i.e., if any were previously defined. 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 later 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 manipulation field will show the details of this project (and PB, SB or scan details on underlying levels). Most of this upper level information has been transferred from the PST or entered by NRAO staff, in particular the total allocated observing time. Investigators not on the original proposal but involved in the observing or data reduction can be added to the project here at any time. The information in this OPT window will be different according to the item that is selected. If a PB is highlighted, information on array configuration  and underlying SBs appear, with the time allocated to that PB. When SBs are executed, the execution block table summarizes the dynamic scheduling starting conditions. The information on selecting a SB is spread over four pages, each accessible via its own tab at the top of the main window: Information (with SB name, count, LST start range and conditions), Reports (with resource, source and scan summary listings), Validate & Submit and Executions. There is also a Bulk Scan Edit tab that will be explained later. 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 table. The source table contains a source per row with a check box, an editing icon (Edit Source), 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 or Aliases column pops up additional source information when available. Finally, clicking on the Sky Map icon opens a new browser tab with detailed information on the sky and VLA calibrator sources surrounding up to ten degrees around the position of that source.
  • 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, frequency band, visibility integration time, AC/BD bandwidth, AC/BD center frequencies, back-end of the resource, and a field for user comments.

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

3. Before You Begin


The following guidelines, in somewhat preferred order, allow to avoid the most obvious problems and 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 intuitive.

  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 PST if you do have a printed copy already. You will need the positions of your target sources and calibrator sources for flux density, delay/bandpass and gain calibration. Resource information for wide band continuum observations includes the frequency bands of your observation. For spectral line observations you need either an exact sky frequency or a combination of rest frequency, velocity and velocity reference frame information on your target sources, and the details of the correlator configuration.
  2. Check the project, in the OPT labeled with the project code, in terms of program/scheduling blocks entered by NRAO staff. This read-only information will likely be the project name, PB and allocated time, array array configurations, and scheduling priorities. Source catalogs will be created with the PST information provided but make sure that the positions are transferred correctly and to sufficient accuracy for your science. Resource catalogs will have been made but be left empty at this stage. The NRAO Helpdesk is available to clarify any confusions.


After Logging into the OPT Web Application

Projects do not appear in the OPT directly after the disposition letters are sent. They are created a few months later, about a month before the reconfiguration to the first possible array configuration of the observations. 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 and an (empty) SB. 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 creating SBs. 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.

The remainder of this document will guide you through the different components to create an SB/observing schedule. The SCT is the easiest and most logical to start with. The RCT and OPT use many features or concepts that are similar to the features or concepts in the SCT and thus need not be addressed again. As the OPT must use information defined both in the SCT and in the RCT, a chapter on the RCT is placed before the chapter on the OPT.

If at any time you wish to exit, use FILE - EXIT or the Exit button on the top right hand side of any of the tools. Please do not exit the tool by closing the web browser or browser tab before exiting properly, with either of the exit options, as this will keep your session alive and will create problems accessing (read: approving) your SB for some hours.

As an advance hint on user friendliness, experience has shown 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 observation in a catalog and to include the calibrators from large lists (e.g. the VLA calibrator list) already in that source catalog, with perhaps a different, more descriptive name. What is meant by this and why will become clear later on.


    4. Suggestions, Help, and Contact

    The remainder of this document concentrates on a hands-on cookbook-like detailed description of the OPT, SCT and RCT.  If you find yourself stuck and need help with the tools, if you have excessive problems with web interface issues, or if you just need some hints or pointers for optimal user convenience, we can be contacted through the NRAO Helpdesk.

    As much of this information may be new to you, please do not wait until the last moment to schedule your observations!

    The same holds when asking for help. If possible, we suggest that you start at least two weeks before your planned observations, allowing enough time to address any scheduling problems or other issues.