1.5 Plotting

SCHED has the ability to plot the u-v coverage and beam of sources in a schedule and to plot azimuth, elevation, hour angle, or paralactic angle against any of those quantities or against UT or GST for one to all stations in a schedule. These plots are useful for assessing the quality of the schedule. SCHED can also plot the positions of the sources in a schedule in RA and DEC and plot the positions of all other sources in the specified catalog. The latter is useful for identifying candidate calibrators. The plots can be very useful for planning observations, both at the proposal stage and as the schedule is prepared. For this use, see the section on planning and for a very simple example schedule for obtaining plots of hypothetical schedules, see the second example in the Examples section. Some of the other examples are also oriented toward planning VLBA and VLA observations.

To cause SCHED to make plots, specify PLOT somewhere in the input. Since it is unlikely that this will be desired in the final run of the program, it is best to start a plotting session interactively and then specify PLOT and use SCHedule to specify the input file. Thus, you would type (on a unix box, anyway):

sched  
plot  schedule=bv016d.key /

(substituting your file for the bv016d.key.

The plotting utilizes the PGPLOT subroutine library written by Tim Pearson used by the other Caltech Package programs and in wide use in astronomy. Be sure that the environment variables PGPLOT_DIR is set to the location of the PGPLOT libraries on your system and that PGPLOT_FONT is set the the location of the PGPLOT font files if that is different from PGPLOT_DIR.

If PLOT has been invoked, SCHED will proceed to read all of the input files, check the schedule, and do any requested optimization normally. It will write the summary file, but will not write the antenna specific files, at least until later. The summary file will be closed and can be examined while in the plotting session. This may be useful in studying details of what is being plotted.

When the plotting session begins, SCHED opens a control panel with a variety of buttons that can be clicked with the mouse. It also writes some instructions to the window in which SCHED is being run. On the control panel, the left most column has buttons that either select different control functions (items to the right will change) or cause something to happen. The latter options include actually drawing a plot (PLOT), closing the plot (CLOSE), restarting the program to read a new input file (RESTART), continuing to (FINISH) the rest of SCHED (only allowed if neither RESTART or OPTMODE=UPTIME were used), exit the program (EXIT), or revert the the older style terminal input (TERM) described below. The FILES options allows changing output from the terminal to postscript or other files and allows restriction of plots to scans with specific setup files. The OPTIONS button allows selection of colors and line widths. The AXIS button allows selection plot type and axis scales. The SOURCES button (default on wakeup) allows selection of antennas and sources. Antennas can be selected both for plotting at all and for highlighting in red. The use of the buttons should be fairly intuitive and won’t be documented extensively here. Some information included in the descriptions of the terminal input below also applies to interactive operation so it is worth reading through the documentation quickly.

Many thanks to Franco Tinarelli of Bologna for providing the code for the plot control.

Note that, if elevation is plotted against azimuth, the horizon, as specified in the stations catalog, will be plotted in addition to the tracks followed by the sources.

If the RD Plot option is selected, the location on the sky of each source in the schedule is shown. This particular plot option has acquired a number of interactive capabilities. It is possible to zoom in on a region, to look for calibrators around a target location, to show (as calibrators) all sources in the catalog, not just those listed in the schedule, and to label the source and catalog names. These capabilities should be useful in attempts to locate calibrators near reference sources. Currently, a rectangular coordinate system is used for the displays, but a more general projection scheme is under development.

Plots are made, of whatever quantities are specified, by drawing a line from the value at the beginning of each scan to the value at the end of the scan. Thus, if you have very long scans, the individual line segments may become apparent and the plot will not be an exact representation of the data that will be collected.

The RESTART option is especially interesting for experiment planning. It causes SCHED to return to the beginning of the program, read and process the input file again, and return to the plot section, remembering the current plot inputs. If the input file has been changed in any way, those changes will be reflected in the new plots. Thus scan times can be changed, new sources specified etc. This is useful, for example, in exploring the u-v coverage for various sources (much like the Caltech program HAZI) or determining the times that various sources are visible (like the Caltech program UPTIME). It is more flexible than the other programs because you have full control of the schedule so, for example, the u-v coverage from multiple snapshots can be explored. Because it is possible, by deleting some parameters from the input file, to cause SCHED to get confused about the value of some of the parameters for which only one value per project is accepted, the FINISH option is locked out after a RESTART. If a RESTART option has been used, it will be necessary to rerun the program from scratch to get final output schedules. Since you have been modifying the input file on each restart, this should not be a problem.

In older versions of SCHED or if the TERMINAL button is pressed, the plot control is from the terminal window using KEYIN input as described below. This form of input will probably be removed eventually unless there is demand to keep it.

1.5.1 Keyin Input for Plotting (obsolete)

This section describes the use of Keyin inputs to control the plotting functions. This has been superceded by the control panel scheme of inputs, but the documentation will be retained until the capability is removed.

If the TERMINAL button is pressed on the plot control panel, SCHED reverts to Keyin style input from the main window in which it is running to control the plots. First, SCHED writes a description of the possible input parameters, which are also described below, and then prompts for KEYIN style input. The user should specify any desired quantities and then type a “/”. If the user is on a machine with X windows graphics, simply taking all the defaults will cause a u-v plot of all sources and scans in the project to appear on the screen.

The inputs can be used to choose between u-v plots, xy, and Ra-Dec plots. For u-v plots, the scale can be specified and a station can be selected for which, on color displays, the baselines to that station will be highlighted (displayed in red). Also the source to be plotted can be specified. XY plots are a bit more complicated because they are more flexible. The quantity to plot on each axis can be selected, the scales specified and the station and source chosen to be one or all. See the details of the input parameters below. In addition, the plot can be restricted to scans that use one of the setup files. This can be useful for assessing band switching observations.

The input parameters are not reset between runs of the plotting. Thus the user need only specify those items that he/she wishes to change. Some of the built in KEYIN capabilities can be useful here. If you type SHOW, KEYIN will list the input variables and their current values. HELP generates a list of the variables. Also you can type SAVE filename and KEYIN will write a file with name filename in the default area containing the current parameter settings. Later, perhaps in another run of SCHED, you can type @filename to recover those parameters. The parameter file can be edited — it is a normal KEYIN input file (actually any file can be read with the @filename construct, although only up to the first “/”).

Plotting Input Parameters (Terminal):

The KEYIN inputs to the plotting section of SCHED are:

PLotfile

PLOTfile gives the output specification for the plot. As with any PGPLOT programs, it is in the form filename/device. For interactive devices, the filename need not be specified. The default device is /xs which is a good choice for X windows systems. Other devices most likely to be of interest are /ps for a postscript file and /cps for a color postscript file. See PGPLOT documentation PGPLOT documentation for other options (more will be listed here in the future). The device can be changed at any time. If it is changed, the old one will be closed and the new one opened. This allows the plot to be set up interactively, and then put out in postscript for printing.

SEtnum

When the plotting section is entered the first time, information is written to the screen about possible input options. Among the information presented is a numbered list of the setup files encountered in the input. With SEtnum, one of those setup files can be selected by number (avoids lots of typing since setup file names often include full paths and can be quite long). Then the plot will only show scans which use that setup file.

TYpe

TYpe is used to specify the type of plot. The option are UV, which is the default, XY, and RD. UV causes a plot of the spatial frequency coverage to be plotted. For now, the scale on the plot is km. An expected enhancement eventually is for this to optionally be in wavelengths. For XY plots, there are a variety of options which are specified with XAxis and YAxis, which independently specify the quantity plotted on each axis. RD requests that the locations of the sources in the schedule be plotted in Ra and Dec.

XAxis

XAxis specifies the quantity to be plotted on the horizontal axis in a TYPE=XY plot. The options are el for elevation, az for azimuth, pa for paralactic angle (for polarization), ha for hour angle, ut for universal time, and gst for Greenwich Sidereal time.

YAxis

YAxis specifies the quantity to be plotted on the vertical axis in a TYPE=XY plot. The options are el for elevation, az for azimuth, pa for paralactic angle, and ha for hour angle. If xaxis=az and yaxis=el, the antenna horizons will be plotted along with the source tracks.

XLeft and XRight

XLeft and XRight specify the minimum and maximum for the X axis plot scale. If they are not set, or are set to -9999., the axis will be autoscaled. For u-v plots, it is only necessary to specify one value, say XMax, and it will be used for all 4 limits. If more than one are specified, they are used which allows off center plots. For XY plots, the limits should be specified in the units of the plots. For the time axis, the limits should be in the form hh:mm:ss where this is the time offset since the beginning of the first day of the experiment for UT or is the GST. Note for u-v plots, traditionally, the plot has positive to the left so XLeft will be greater than XRight. For Ra-Dec plots, XLeft and XRight specify the RA range and should be in the form hh:mm:ss (eg. XL = 5:30:00).

YBottom and YTop

YBottom and YTop specify the minimum and maximum for the Y axis plot scale. If they are not set, or are set to -9999., the axis will be autoscaled. For Ra-Dec plots, YBottom and YTop specify the declination limits and should be in the form dd:mm:ss (eg. YB = -12:15:00).

SOurce

SOurce can be used to restrict the plots to a single source. The default, which can be specified at any time is ALL, which will cause all sources to be plotted.

STation

STation can be used to restrict TYPE=XY plots to one station. For TYPE=UV plots, all stations will be plotted, but all baselines to the specified station will be plotted in a contrasting color. The default, which may be specified at any time, is ALL, which will cause all stations to be plotted or not highlighted.

REstart

See the discussion above for details of the effect of REstart. In short, it causes the program to return to the beginning and reread the input, which may have changed.

FInish

FInish tells SCHED to close the plot files and produce the station specific output files. FInish is locked out after a REstart to make absolutely sure that the output files really correspond to what is in the schedule file. If REstart has been used, it will be necessary to EXit and rerun SCHED from scratch to get the station output files.

EXit

EXIT tells SCHED to close the plot files and exit. Antenna specific files will not be produced.