The Plotter

The Plotter#

GUI Features#

When GBTIDL is first started it does not show the plotter screen, but the first time a command is issued that uses the plotter, it will appear. The figure below identifies the parts of the plotter GUI.

You can manipulate the view using either command line procedures or the buttons on the plotter screen. Control buttons are positioned along the top menu bar, and status indicators are along the bottom.

Buttons for manipulating the plotter view and their equivalent commands:

  • File: The file menu is used to print the plot or to write the data to an ASCII file. The available options are:

    • Print…: Print the screen (this allows you to choose your printer and print options)

    • Write PS: Save the plot to a postscript file

    • Write ASCII: Write the data to an ASCII file

    • Exit: Exit the plotter

  • Options: The Options menu includes the following capabilities:

    • Crosshair: Toggles the cursor between a crosshair style and a pointer style. The crosshair is useful for reading x and y values off the plot.

    • Zeroline: Toggles a horizontal line at y=0 on the plot.

    • Toggle Histogram: Switches between histogram-style and connected-points style plots.

    • Toggle Region Boxes: Affects region boxes that were created using the setregion command.

    • Clear Marks: Clears all the markers you have made on the plotter.

    • Clear Vertical Lines: Clears lines you have added to the plotter.

    • Clear Overlays: Clears spectra overlaid on the original.

    • Toggle Overlays: Toggles the display of any overlays without affecting the scaling of the axes.

    • Clear Annotations: Clears all textual annotations on the plotter, including the results of Gaussian fits shown on the plot.

    • Set Voffset=Vsource: Sets the offset velocity equal to the source velocity obtained from the header.

    • Set Voffset=0: Sets the offset velocity to zero.

    • Set Voffset: Prompts the users for a new offset velocity.

  • LeftClick: This menu lets you choose the behavior of the left mouse button. The options are:

    • Null: A left click does nothing.

    • Position: A left click will print the x and y coordinates of the cursor on the terminal screen.

    • Marker: A left click places a marker on the plot and displays the x and y coordinates of that marker.

    • Vline: A left click places a vertical line on the plot and displays the x and y coordinates of the click point.

  • X-axis units: This button can be used to specify the desired x-axis units. The button’s label is the current x-axis units. The options are:

    • Channels, Hz, kHz, MHz, GHz, m/s, or km/s

  • Reference Frame: This button provides options for changing the velocity frame of reference. The button’s label is the current velocity frame of reference. You can choose:

    • TOPO: Topocentric - the observed (sky) frame

    • LSR: Local standard of rest (kinematic)

    • LSD: Local standard of rest (dynamic)

    • GEO: Geocentric

    • HEL: Heliocentric

    • BAR: Barycentric

    • GAL: Galactocentric

  • Velocity Definition: This button can be used to set the velocity definition. The button’s label is the current velocity definition. Options are:

    • Radio, Optical, or True (Relativistic)

  • Abs: This button allows you to choose whether to display the x axis in absolute units or relative to the center of the band.

  • Unzoom: This button unzooms the plotter one step at a time. That is, if you have zoomed the plot three times successively, clicking this button once will return you to the zoom parameters applied after the second zoom. Clicking it twice more will return you to the full unzoomed scale. This button is grayed out when fully unzoomed. For more information on zooming methods, see the section on zooming below.

  • Auto Update: This setting controls whether or not the plotter automatically responds to commands. The feature is described in the next section.

  • Print: The print button sends the plot, as displayed in the plotter, immediately to the default printer as set in the !g.printer variable. If you want to specify a printer, use the print option under the File button.

Auto Update (Freeze/Unfreeze)#

The Auto Update feature determines how the plotter responds to data processing commands. With Auto Update on, a command that changes the PDC will trigger the plotter to update with the new result. With Auto Update off, the plotter is only updated in response to a show command. In most cases, you will want the auto update turned on (unfreeze) so the show command is not required at each step. However, setting it off can be useful for faster processing of data in scripts because plotting the spectra during intermediate steps can be time consuming. From the command line, use freeze or unfreeze to turn the auto-update off or on, respectively. For example:

unfreeze                        ; Turn on auto updates
getrec,1                        ; Get some data - note the plot updates
hanning                         ; The plot updates after the smooth operation
freeze                          ; Turn off auto-updates
for i=101,200 do begin & $      ; This loop will be faster
    getrec,i & $                ; since the plots are not updating
    accum & $
end
ave
show                            ; Now the plot updates
unfreeze                        ; back to the usual setting

Zooming#

Zooming in on a plot can be accomplished in several ways. One is to use the middle mouse button on the plotter, clicking twice to specify the corners of the new zoom box. To unzoom, click the Unzoom button at the top of the plotter, or simply type unzoom. The Unzoom button takes you back to the previous zoom settings, so several clicks may be necessary to return to the full scale. However, typing unzoom in the terminal window will bring you back to the original unzoomed spectra, no matter how many times you zoomed. If you wish to cancel a zoom after the first middle mouse click, click the right mouse button.

Zooming may also be accomplished with the setxy procedure. When used with no parameters, this procedure places a stretchable box on the plot and allows it to be positioned before executing the zoom. Instructions for its use are printed to the screen when the procedure is invoked. Alternatively, you can specify the desired zoom range from the command line using:

setxy, x1, x2, y1, y2.

A third zooming method is to specify minimum and maximum x- or y-axis values using the commands setx or sety. You can then either specify the minimum and maximum x- or y-range using parameters, or omit the parameters and use the cursor to set the range. The commands freex and freey can be used to autoscale the x- or y-axis without unzooming the other axis. For example, freey will show the full y-range of the data without changing the current x-range.

Printing Spectra and Creating Postscript Plots#

Generating postscript plots can be difficult in IDL. In GBTIDL, we have simplified the process with the write_ps procedure. This procedure will generate a postscript file that reproduces the plot as shown on the plotter. The postscript rendition will include overlays, show the zero line if it is turned on, show any annotations created with the annotate procedure, display any markers or vlines placed on the plot, and the axis ranges are accurately reproduced. However, the write_ps procedure cannot know about any other IDL primitives that may have been used to draw on the GBTIDL plotter, so any IDL primitive plot commands will not be reproduced.

Generating ASCII Data#

The command write_ascii can be used to write data to an ASCII file. The command takes a single parameter, the name of the ASCII file to be generated.

The table command is useful for printing the x and y coordinates of a few specific points to the terminal screen. For example

GBTIDL -> table, brange=1.66, erange=1.67

will list the data values for points between x = 1.66 GHz and x = 1.67 GHz for the PDC:

Scan:     79             W3OH 2005-06-28 +04 10 20.0
                         Ta
        GHz-LSR          YY
       1.6699992   -0.14701117
       1.6699962   -0.10967928
       1.6699931   -0.13311513
       1.669990    -0.10884448
           . .
           . .
           . .
       1.6600114   -0.013062999
       1.6600084    0.023651161
       1.6600053    0.011518455
       1.6600022   -0.013523553

Annotating the Display#

You can place text on the plot using the annotate procedure. This command takes three parameters: the x and y coordinates, and the text. You can also choose to include a color specifier and font size, as well as specify normalized coordinates (/normal). Example:

annotate, 6, 9, ’This is an annotation’, color=!orange, charsize=2.0

Other Plotter Procedures#

The following table lists some of the command line procedures relevant to the plotter. Full descriptions of these procedures are available in the GBTIDL User Reference or via the usage command.

Procedure

Action

show

Displays the spectrum

oshow

Display a spectrum as an overlay

gbtoplot

Used to plot arbitrary (x,y) values on the GBTIDL plotter.

chan, freq, velo, setxunit

Sets the X-axis units

setx, sety, setxy

Sets the X- and/or Y-axis scale

unzoom

Retrieve previous zoom settings

freex, freey

Auto scale one axis without affecting the range of the other.

freexy

Auto scale both axes

histogram

Toggle between histogram-style and connected-points

annotate

Place some text on the plot

crosshair

Toggle the crosshair cursor on/off

write_ascii

Write the data to an ASCII file

write_ps

Write the plot to a postscript file

zline

Toggle the zero-line on/off

bdrop, edrop

Hide channels at beginning/end of the spectrum

showregion

Turn on or off the display of baseline region boxes

click

Prompt user to click on the plot, and return info on the click location

clearannotations, clearvlines, clearoplots, clearoshows, clearovers, clearmarks, toggleovers

Clear various types of overlays

clear

Clear everything from the plotter

setabsrel, setframe, setveldef, setvoffset

Set the velocity definition and rest frame, and offsets

setmarker, vline

Place markers and lines on the plot

chantox, xtochan

Convert between X-axis units and channel number

freeze, unfreeze

Turn Auto Update off or on

reshow

Re-draw everything known to the plotter

Colors#

GBTIDL has built-in color definitions in global variables called !black, !red, !orange, !green, !forest, !yellow, !cyan, !blue, !magenta, !purple, !gray, and !white. Many of the plotter commands take a color as an optional parameter. For example, the color of the spectral line can be changed like this:

show, color=!blue