6.3 Plotting your data

The basic concept in AIPS’ plotting is to use some task to create and write a device-independent plot file as a PL extension file to a cataloged image or visibility data set and then to use some device-dependent task to interpret that file for the desired output device. Plot files are not overwritten by subsequent plot tasks. Instead they make new plot files with higher “version” numbers. The device-dependent tasks include TVPL (AIPS TV devices including XAS), TKPL (Tektronix graphics devices including AIPSTEKSRV server), TXPL (line printers), and LWPLA (PostScript printer/plotters). Tasks called PRTPL, QMSPL, and CANPL support antique Versatec, QMS, and Canon printer/plotters. To plot on a PostScript printer/plotter:


to review the inputs.

> INDI n ; GETN ctn  C R

to select the disk and catalog entry to print.


to plot the mth plot file only.

> OUTFILE ’ ’ ; GO  C R

to do the plot immediately.

LWPLA offers the option to save the file for later plotting or inclusion as encapsulated PostScript in other documents. It also has options to control scaling, output paper size, width and darkness of lines, and transformation of grey-scale intensities. It can write more than one plot file at a time and can append new plots to existing output files. Multi-plot files are not “encapsulated” but may be printed and viewed with tools such as gv or ghostview. Note that PostScript files are text files and AIPS writes particularly simple PostScript so that it can be modified by the users. See HELP POSTSCRIPT for suggestions including information on deleting and adding labels and arrows and on converting the PostScript to other formats like jpg without loss of resolution.

LWPLA and all plot tasks offer some “coloring” options. These are illustrated in the color pages at the end of this chapter. The grey-scale plotting tasks, including GREYS, PCNTR, and KNTR, can now enhance the grey-scales with a transfer function and then pseudo-color them with a color table. See 6.4.3 for a short discussion of “output-function memory” tables which may be read into the above tasks or to LWPLA using the adverb OFMFILE. Lines plotted on top of grey scales (e.g., contours, polarization vectors, stars) may be “dark” when the grey scale intensity is high. LWPLA may be instructed to plot these as bright if adverb DODARK is false. All plot programs can draw lines of different types in both bright and dark forms. In LWPLA, if DOCOLOR is true, the array adverb PLCOLORS(i,j) controls the red, green, and blue colors (i = 1,2,3, resp.) of line types j = 1 – 10. The normal meanings of these types are:

  1.  Bright labeling, tick marks, surrounding lines
  2.  Bright lines, usually contours or model curves
  3.  Bright lines, usually polarization vectors
  4.  Bright lines, usually symbols such as stars, visibility samples
  5.  Dark labeling text inside plot area
  6.  Dark lines, usually contours
  7.  Dark lines, usually polarization vectors
  8.  Dark lines, usually symbols such as stars
  9.  Bright labeling outside the main plot area, e.g. titles, tick values and types, documentation
  10.  Background for the full plot

Some plot tasks have the ability to control the colors of their line drawing independent of these line types. These colors may be controlled only when making the plot file with the particular task. PCNTR and KNTR have acquired the ability to color each contour level under control of the adverb RGBLEVS. Using system RUN file SETRGBL, procedures CIRCLEVS, RAINLEVS, FLAMLEVS, and STEPLEVS are available to help you set the values of RGBLEVS. Examples are shown on the color pages at the end of this chapter. With LWPLA and these options one may prepare extremely effective displays — or hopelessly bad ones — for use in talks and, since the prices have become reasonable, even in journals. Note that most journals want color images in CMYK (cyan-magenta-yellow-black) rather than RGB; use DPARM(9) = 1 in LWPLA to get PostScript files with this color convention. Note that these two color representations usually require different “gamma” corrections; the adverb RGBGAMMA allows this control in LWPLA.

All AIPS plot tasks now offer a “preview” option. If you set DOTV = TRUE when running any plot task, then the plot appears immediately on the AIPS TV display and no plot file is generated. This option allows you to make sure that the parameters of the plot are reasonable and lets you avoid making files and wasting paper for quick-look plots. Additional options allow you to control which graphics channel is used for the line drawing (GRCHAN) and to select pixel scaling of the plot at your specified location on the TV screen (TVCORN). These two options allow you to view more than one plot at a time on the TV, usually for purposes of comparison. Each graphics channel on the TV has a different color and a complementary color is used when two or more channels are on at the same point. This allows for a fairly detailed and effective comparison of plots, all of which may be captured with task TVCPS (see below). Be aware that most tasks now interpret GRCHAN = 0 as an instruction to use graphics channels 1 through 4 for line types 1 through 4 and graphics channel 8 for dark vectors. The comparison function is only achieved by specifying GRCHAN. Tasks that produce multiple plot files pause for 30 seconds at the end of each plot when DOTV = TRUE. This allows you to stop the task (TV button D), hurry it along (TV buttons B or C), or make it pause indefinitely (TV button A) until another TV button is pressed.

You can review the parameters of the plot files associated with a given image or visibility data set by typing:

> INDI n ; GETN ctn  C R

to select the disk and catalog entry to print.


to list summaries of the plot file contents.


to recover all adverb values used when making the specified plot file.

Plot files (and other “extension files”) are automatically deleted when an image is deleted by ZAP. However, large plot files should be deleted as soon as they are no longer needed:


to review the inputs required.


to set the type to PL (plot) and the version number to be deleted to m. m = -1 means all and m = 0 means the most recent (highest numbered).


to do the deletion.


to reset the version number to its default — usually advisable.

Plot files are not amenable to the FITS format and so are not written by FITTP and FITAB. They may be copied from one catalog entry to another with TACOP.

6.3.1 Plotting your visibility data


Figure 6.1: UVPLT displays of where the data were observed in the uv plane (left) and of the visibility amplitudes as a function of baseline length (right). The data on 3C336 were provided by Alan Bridle from observations made with the VLA on 6 December 1987.

The most basic plot program for visibility data is called UVPLT. It allows you to select the x and y axes of the plot from real, imaginary, amplitude, log of amplitude, phase and weight of the visibility, time, hour angle, elevation, azimuth, and parallactic angle, and projected baseline length, position angle, u, v, w, frequency, and spectral channel number. It offers all of the usual calibration and data selection options and it plots the selected points individually and/or in a controlled number of bins along the x axis. It can display multiple IFs and spectral channels at once, including averaging groups of spectral channels. For example, to plot calibrator phases as a function of time for all baselines to one antenna:


to review the inputs.

> INDI n ; GETN ctn  C R

to select the disk and catalog entry of the data set.

> BPARM = 11 , 2  C R

to plot time in hours on the x axis and phase in degrees on the y axis.

> SOURCES ’ ’ ; CALCODE ’*’  C R

to select all calibrator sources.

> XINC 4  C R

to plot only every fourth selected sample.


to do all baselines with antenna 2.

> DOTV = -1 ; GO  C R

to make a plot file of these data.

After UVPLT is running, or better, after it has finished:


to plot the latest version on a PostScript printer/plotter.

There are several other tasks to plot your visibility data. VPLOT plots all of the parameters offered by UVPLT, but one baseline at a time with multiple baselines per page (i.e., per plot file) and multiple pages per execution. CLPLT is a similar task but restricted to plotting closure phases around baselines involving 3 antennas as a function of time. CAPLT is a similar task but restricted to plotting closure amplitudes around groups of 4 baselines as a function of time. All three of these can also plot a source model (based on Clean components) as well as the observations. ANBPL can create a similar plot of amplitudes, phases, or weights converted to antenna-based quantities; this function is helpful in diagnosing problems with your data. For spectral-line users, POSSM plots visibility spectra averaged over selected baselines and time intervals. It can also plot bandpass calibration tables and the Fourier transform of visibility spectra (the auto- and cross-correlation functions). For VLBI users (primarily), FRPLT plots visibilities versus time or, more importantly, the fringe rate spectrum. To examine the statistical distribution of your data, try UVHGM which plots histograms showing the number of samples or weights versus a wide variety of parameters. Optionally, it will fit a Gaussian to the histogram and plot the result. The task UVIMG will grid visibility data into an image on a variety of axes, while the task UVHIM will make an image of a two-dimensional histogram of your uv data. All image display functions below may then be used to view the results. For example, if the axes of the histogram image are the real and imaginary parts of your data, then the image will demonstrate the amplitude and phase stability present (or missing) in your data.

A number of visibility plotting and editing tasks offer the DO3COLOR option to separate multiple IFs, spectral channels, sources, times, and the like when plotted in the same plot area. In 31DEC18, task PLOTC will make plots showing the colors used by such tasks with labels to assist in identifying which color goes with which data parameter. These plots may be saved as plot files and shown directly on the TV just as with all other plot tasks.

Two plot programs actually convert visibility data to the image plane for plotting. Observers of point objects which might vary with time either intrinsically or by scintillation (e.g., stars, masers) might wish to try DFTPL, which plots the Fourier transform of the data shifted to a selected position as a function of time. In 31DEC17, task DFTIM makes an image of such data as a function of frequency and time. VLBI spectral-line observers may need to use FRMAP, which performs imaging via fringe-rate inversion and plots the loci of possible source positions.

6.3.2 Plotting your image data

Image data may be drawn in a variety of ways including contours, grey or color levels, row tracing, and statistical. All plots are drawn with labeled tick marks although these may be suppressed with the LTYPE parameter. This LTYPE parameter is used to control the type of axis labels, the degree of extra labeling, the presence of the line giving the plot time and version, and also how metric scaling is done on the axis units. Read HELP LTYPE for details. For plots having significantly non-linear coordinate axes, e.g., wide-field images, it is sometimes useful to draw a full, non-linear coordinate grid rather than just short lines at the edges of the plot. Tasks like CNTR and even the verb TVLABEL offer this option; enter DOCIRC TRUE  C R.

Plot symbols (e.g., plus signs) may be drawn on the plots produced by CNTR, PCNTR, GREYS, KNTR and several of the other tasks mentioned below. In these tasks, the parameters which controls the plotting are STFACTOR, a scale factor for the symbols, and STVERS, a choice of the desired stars extension file. When using this option, there must be a table of “star” positions associated with the image being plotted. To create one, enter EXPLAIN STARS  C R to learn the format of the input data file and the parameters for the task. See also Appendix Z or your local equivalent for instructions on editing text files. A star file may also be created by MF2ST from a model fit file produced by task SAD (see 7.5.3 and 10.4.4). Tasks IMFIT, JMFIT, and SAD may now also produce “star” extension files directly.

Example outputs of the following three tasks are given in Figure 6.2. Contour and grey-scale plots

The most basic contour drawing task is CNTR. In addition to the usual image selection parameters, you may specify:


to tell you what you may specify.

> BLC 250 , 230  C R

to set the bottom left corner of plot at 250, 230 (in pixels with 1,1 at extreme bottom left of the image).

> TRC 300, 330  C R

to set the top right corner of plot at 300, 330.

> CLEV 0 ; PLEV 1  C R

to get contour levels at 1% of the peak image value.

> PLEV 0 ; CLEV .003  C R

to get contour levels at 3 mJy.

> LEVS -1, 1, 2, 4, 6  C R

to get actual contours at -1, 1, 2, 4, and 6 times the basic level set by PLEV or CLEV. LEVS need not be integers, but very fine subdivisions cannot be represented accurately on the plot.

N.B., if you request more than one negative level with the LEVS input, you must use commas between the negative levels. Otherwise the minus sign(s) will be treated as subtraction symbols and the desired levels will be combined into a single negative level by the AIPS language processor. BLC and TRC can be initialized conveniently from the TV display using the cursor with the TVWIN instruction (see 6.4.4). Then check:

> INP  C R

to review what you have specified.

> GO  C R

to run the task when you’re satisfied with the inputs.

This generates a plot file as an extension to your image file, with the parameters you have just specified. Watch the AIPS monitor (which, on some systems, is your terminal) to see the progress of this task. If the “number of records used” in the plot file is over 200, the contour plot will be messy (unless the field is also large). In this case, check that you have not inadvertently set PLEV or CLEV, for example, to unrealistically low values. Printing a large, messy plot file on the printer can take a considerable length of time and will inconvenience other users. Consider plotting directly on the TV first (DOTV = TRUE) to check on your selection of contours.

PCNTR plots polarization vectors on top of contours and/or grey-scales. You may make a polarized-intensity image and a polarization position-angle image from the Q and U images (see 7.1.2) or use the Q and U images themselves. Then:


to review the input parameters.

> INDI n1 ; GETN ctn1  C R

where n1 and ctn1 select the disk and catalog numbers of the image to be contoured.

> IN2DI n2 ; GET2N ctn2  C R

where n2 and ctn2 select the Q or polarized intensity image.

> IN3DI n3 ; GET3N ctn3  C R

where n3 and ctn3 select the U or position-angle image.

> IN4DI n4 ; GET4N ctn4  C R

where n4 and ctn4 select the grey-scale image.

> PCUT nn  C R

to blank out vectors less than nn in the units of polarized intensity.

> ICUT mm  C R

to blank out vectors at pixels where the total intensity (image 1) is less than mm in the units of image 1.


to convert the polarization lines to fractional polarization, dividing by the I image, before plotting.

> FACTOR xx  C R

to set the length of a vector of 1 (in units of total or fractional polarization) to xx cell widths.


to request vectors plus contours of image 1 and grey scale of image 4.

> PIXRAN Tmin,Tmax ; FUNCTYP ’ ’  C R

to scale linearly the grey-scale values from Tmin to Tmax.


to use the standard rainbow-colored OFM table to pseudo-color the grey scales.


to plot the Clean beam in the lower left corner. See HELP CBPLOT for numerous options.

> INP  C R

to review your inputs and remind you of others. Most are similar to those in CNTR and sensibly defaulted.

> GO  C R

to generate the plot file, which can then be routed to output devices via TKPL, TVPL, LWPLA etc.

Unless images 2 and 3 are of Q and U polarization, the lengths of the vectors are controlled by image 2 while the directions of them are controlled by image 3. Clearly this program can also be used for other combinations of images, so long as one of them represents an angle. PCNTR and following tasks have the option to draw an image of the Clean beam under control of adverb CBPLOT. Polarization vectors may be plotted with the color representing the angle. The value of POL3COL, if greater than zero, is that angle represented in pure red from 0 to 180 degrees. A color “spray” is plotted to calibrate the eye. The ability to plot multiple spectral planes in colored contour or polarization vectors was also added. The adverb CON3COL controls this function. The ability to select the colors of each contour level with RGBLEVS has been added. These color functions are displayed at the end of this chapter in the color pages.


PIC   PIC GREYS GREYS with contours

Figure 6.2: Contour, polarization, and grey-scale plots of an image

GREYS creates a plot file of the grey-scale intensities in the first input image plane and, optionally, a contour representation of a second input image plane. Like the other grey-scale plotting tasks, GREYS can interpret a true-color (RGB) image cube in its “true” colors. Unlike the others, it can construct the true-color image from 3 separate image planes. A sample set of inputs could be:


to review the inputs.


to specify that a “true-color” image is to be plotted.

> INDISK n1 ; GETN ctn1  C R

to select the red image.

> IN3DISK n3 ; GET3N ctn3  C R

to select the green image.

> IN4DISK n4 ; GET4N ctn4  C R

to select the blue image.

> PIXRAN Tminr,Tmaxr ; FUNCTYP ’SQ’  C R

to scale by a square-root function red values from Tminr to Tmaxr.

> APARM Tming,Tmaxg,Tminb,Tmaxb  C R

to scale green and blue values similarly over ranges Tming to Tmaxg and Tminb to Tmaxb, respectively.

> BLC 250 , 250 , 3  C R

to select the lower left corner and the plane in the first image.

> TRC 320 , 310 , 12  C R

to select the upper right corner in the first image and, with TRC(3), the plane in the second image.


to specify that contours are to be drawn.

> IN2D n2 ; GET2N ctn2  C R

to select the contour image.

> PLEV 0 ; CLEV 0.005  C R

to select 5 mJy/beam contour increments.

> LEVS -3 , -1 , 1 3 10 30 100  C R

to plot contours at -15, -5, 5, 15, 50, 150, and 500 mJy/beam.


to plot a 3-color step-wedge along the right-hand edge; 1 for along the top and 0 for no wedge.


to make the plot file.

When GREYS has finished, run LWPLA to view the plot file. Note that LWPLA has a variety of options which control the plotting and scaling of the grey-scale images without having to rerun GREYS. In this example case, you should remember to set FUNCTYPE = ’ ’ and DPARM = 0 (or at least the first 4 values to 0) in LWPLA to avoid additional scaling. You may wish to color the labeling, contours, and background with DOCOLOR=1 and PLCOLORS with LWPLA. The procedure TVCOLORS will set PLCOLORS to match the TV graphics-plane colors; DEFCOLOR will set PLCOLORS to the standard TV colors even in the absence of a TV display. See examples on the color pages at the end of this chapter.

There are two other contour drawing tasks which offer additional options. KNTR is able to draw multiple contour, polarization, and/or grey-scale images in a single plot file, primarily to show multiple planes of a spectral-line cube; see 8.5.4. KNTR uses a different, and probably superior, method of drawing the contour lines. It also can use color to represent different spectral channels and/or polarization angles or simply different colors for the different contour levels. CCNTR is virtually identical to CNTR except that it can draw extra symbols on the plot representing the locations and intensities of source model components found in CC (Clean component) or MF (model fit Gaussians from SAD, see 7.5.3 and 10.4.4). Row tracing plots



Figure 6.3: Row plots of an image with (bottom, PROFL) and without (top, PLROW) perspective

There are a number of tasks which plot rows directly. Two of these are for use with single image planes while others are more intended for use with, e.g., spectral-line data cubes transposed into velocity-ra-dec order. Of the former, PLROW is the simpler. It makes a plot file of all selected rows in an image plane. Each row is plotted as a slice offset a bit from the previous row. Low intensities which are “obscured” by foreground (i.e., lower row number) bright features are blanked to keep the plot readable. Example inputs would be:


to review the inputs.

> INDISK n ; GETN ctn  C R

to select the image on disk n catalog slot ctn.

> BLC 100 ; TRC 300  C R

to select the sub-image from (100, 100) to (300, 300).

> YINC 3  C R

to plot only every 3rd row.

> PIXRANGE -0.001 0.050  C R

to clip intensities outside the range -1 to 50 mJy.

> OFFSET 0.002  C R

to set the intensity scaling such that 2 mJy separates rows of equal intensity.

> INP  C R

to check the inputs.

> GO  C R

to run PLROW.


to display the plot file on the laser printer after PLROW has finished.

The plot files produced by PLROW are a simple, special case of those produced by PROFL. This task makes a plot file of a “wire-mesh” representation of an image plane complete with user-controlled viewing angles and correct perspective. Enter EXPLAIN PROFL  C R for a full description. Both of these tasks are especially useful where the signal-to-noise ratio is high and examples of them are given in Figure

In Chapter 8 we discuss the computation and use of “slices,” one-dimensional profiles interpolated along any line in an image plane. Once a slice has been computed, it may be plotted by SL2PL on the TV or into a device-independent plot file.

Three other row-plotting tasks, PLCUB, ISPEC, and BLSUM, are designed primarily for spectral-line and other data “cubes” (see 8.5.4 and 8.6). PLCUB makes one or more plot files showing the intensities in each selected row. The row subplots are positioned in a matrix in the coordinates of the 2nd and 3rd axes of the cube. ISPEC averages rectangular areas in each plane of a cube and plots the resulting spectrum. It can also save the output in a SLice file. RSPEC does the same except that it plots the robust rms in each plane rather than the data. RSPEC has options to write out a signal-to-noise image and/or a text file of channel weights as well. BLSUM can plot spectra from irregular regions selected on the TV with a “blotch” algorithm. Miscellaneous image plots


Figure 6.4: Plots of statistical parameters of an image.

IMVIM allows a variety of image comparisons by plotting the pixel values of one image against the pixel values of another image. The special options include binning the values (and plotting symbols proportional to the number of samples in a bin) and shifting one of the images in x and/or y with respect to the other. The former reduces large scatter diagrams to more manageable sets of numbers while the latter allows cross-correlation functions to be developed.

IMEAN prints the mean, rms, and extrema inside or OUTSIDE a user-specified window in an image. It also prints the intensity at, and rms of, the noise peak in the histogram and returns these values as adverbs to AIPS. Beginning with 31DEC12, it also returns an array in which TRIANGLE(i) is the brightness level above which there are i per cent of the image pixels. This is often useful in setting PIXRANGE for optical images. Optionally, IMEAN plots histograms of image intensities over the window using a user-specified number of summing cells over a user-specified range of intensities. Optionally, it also plots the fit to the noise peak on the user-specified histogram. An example of this is also shown in Figure 6.4.

6.3.3 Plotting your table data


Figure 6.5: Slice and table plots.

TAPLT is a very general task to plot information from AIPS table extension files. It can plot a histogram of a function of the values in one or two columns of the table and it can plot a function of one or two columns against another function of another one or two columns. The latter can be summed or averaged in bins or have every point plotted. At first blush, the inputs seem rather complicated, but the results may well justify some effort to understand them. For example, to plot Clean component fluxes as a function of radius from the image center:


to review the inputs.

> INDISK n ; GETN ctn  C R

to select the image on disk n catalog slot ctn.

> INEXT ’CC’ ; XINC 1  C R

to select every row in the Clean components file.


to select all rows in the table.

> APARM = 2 , 1, 3 , 1 , 16 , 1 , 1  C R

to plot the modulus of columns 2 and 3 on the x axis (i.e.∘ --------
  Δ2x + Δ2y ) and column 1 on the y axis (i.e., component flux).

> BPARM = 0 ; CPARM = 0  C R

to use self-scaling of the plot and no scaling of the column values.


to plot the fluxes on the TV screen.

You may need to set the scaling with BPARM after seeing the preview plot in order, for example, to bring out the details in the low-level components.

There are a few tasks intended to make plotting specific kinds of tables rather easier. SNPLT plots calibration, solution, system temperature and EVLA SysPower tables for selected antennas as a function of time, antenna elevation, hour angle, azimuth, or sidereal time. It will make several plots per page (one antenna per plot) and multiple pages if needed, or you can plot the most discrepant value over all antennas in a single plot. In one execution, polarizations and IFs may be plotted on separate plots or together on the same plots, optionally separated by color. In 31DEC12, SNPLT also has the option to separate sources by color instead. In 31DEC13, you can also plot multiple parameter types in the same execution. SNIFS is similar to SNPLT but is intended to compare solutions at different IFs, plotting the IF on the x axis with a variety of binning options.

POSSM will plot bandpass tables when APARM(8) is set to 2. Values 3 – 8 plot bandpass-like tables from BLCHN (BD) and PCAL (PD antenna polarization and CP source polarization). POSSM can also do multiple plots per page with all the usual data selection adverbs. BPLOT also plots BP and the other similar tables tables, with multiple times for one antenna or multiple antennae for one time on each plot. Combined with difference and coloring options, this allows close comparison of bandpasses as functions of time or antenna. WETHR plots the data in a WX weather table including parameters computed from those data such as relative humidity. FGPLT plots the times of selected flags from a flag table.

6.3.4 Plotting miscellaneous information

There are a few other tasks which create plot files, but which do not fit into the categories above. The most general of these is PLOTR which can plot up to 30 sets of (x,y) points input from a text file with coloring options. Task PCHIS also reads a text file to produce a histogram plot of the values in any selected column of the file. CONPL is a task which plots AIPS convolving functions (used by various uv-data gridding tasks such as IMAGR) and their Fourier transform, expected signal-to-noise ratio, or convolution with a user-specified Gaussian. IRING integrates an image in concentric annuli about the user-specified object center with specified major axis position angle and inclination. The results may be placed in a plot file for later display. GAL calculates the orientation and rotation curve parameters of a galaxy from an image of the predominant velocities. The observed rotation curve is plotted together with the fitted model curve. LOCIT fits antenna location corrections to SN tables; the residual phases may be plotted as a function of sample number.

There are several tasks which create RGB cubes for later display by tasks such as GREYS and KNTR. These include RGBMP which does a weighted sum of the planes of a data cube, HUINT which uses two images as hue and intensity to construct an RGB cube, and TVHUI which interactively uses three images as intensity, hue, and saturation to construct an RGB cube by a different algorithm. Task SCLIM will scale and clip image planes to be used as inputs to LAYER, which produces an RGB cube from the colored sum of up to 10 input image planes using a complicated and general algorithm.