MAPPLOT

Contents

• Example
• Parameters
  • General Parameters
  • Parameters for Grey-Scale or Color Images
  • Parameters for Contour Maps
  • Parameters for Ruled-Surface Plots
  • General Plotting Parameters
  • Annotation Parameters
  • Window Parameters
• Setting Windows
• Annotation
• History

$ MAPPLOT
MAPFILE="[SCRATCH]MAP.SU1"
PLOTFILE = "/XWIN"
PLEV=1
LEVS=-5,5,10,15,20,50
BEAM
TITLE = "17th iteration"
/
PLOTFILE="PLOT.LIS/VPS"
/
EXIT
/
$

General Parameters

MAPFILE = "filename"

specifies the name of the input file. Several files can be displayed in one run of MAPPLOT. The default file name is "MAP". [In VMS, a logical name assignment can be used to specify the input file, e.g., DEFINE MAP CITSCR:[TJP]MAP345.DAT.]

PLOTFILE = "filename"

specifies the device for graphics output, "/scr/tjp/plot/PS" or "/GR" or "PLOT.LIS/VERS". All plots are sent to the same device until a new value is specified for PLOTFILE. If PLOTFILE is not specified, MAPPLOT will prompt for a device specification.

NPXY = nx, ny

Use this parameter to plot several pictures on one page. nx is the number of pictures across the width of the page, ny the number vertically; e.g., NPXY=2,1 to display two maps side-by-side.

STYLE = "code"

STYLE may be "C" for a contour map, "G" for a grey-scale or color intnesity map, "CG" for both superimposed, or "S" for ruled-surface plot. [Either the equals sign or the quotation marks can be omitted, but not both.]

XRANGE = i1,i2 YRANGE = j1,j2

These two parameters control how much of the map is displayed. The values are pixel numbers, in range 1 to dimension of map. The default, obtained by XRANGE=0,0 or YRANGE=0,0 displays the whole of the map. In images made with CLEAN, MODMAP, or AIPS tasks (and probably most FITS images), the X pixel number increases from left to right and the Y pixel number increases from bottom to top; i.e., the (1,1) pixel is displayed in the lower left corner.

UNITS = string

If the image is a standard sky image with the two axes being angles on the sky (e.g., RA and DEC), this parameter can be used to force the axes to be labelled in specific units. The options are UNITS = "MAS", "MILLIARCSEC", "ARCSEC", "ARCMIN", "DEGREE", "RAD". The default (a blank string) causes MAPPLOT to choose units automatically, depending on the size of the image. If the axes are not angles on the sky, MAPPLOT will use the units specified in the image header.

SHIFT = dx,dy (default 0,0)

This parameter changes the coordinate system of the map. The image displayed is unchanged, and unshifted on the paper; however, the coordinate labels are shifted by (dx,dy). The units of dx and dy are milliarcsec. The point in the image (usually the map center) that is labelled (0,0) if SHIFT is not specified is labelled (dx,dy) when SHIFT is applied. SHIFT only applies to an image in which the axes are RA and DEC, and only when LTYPE=4 (labelling relative to center) is specified. One application of shift might be to center the coordinate system on the brightest component rather than the arbitrary map center.

Parameters for Grey-Scale or Color Images

PALETTE = number

A number of fixed pseudo-color palettes are available. The default is PALETTE=1, which produces an image with intensity mapped to grey-scale shades. The options are:

1. Grey scale, running from white to black.
2. `Rainbow': blue-green-yellow-orange-red.
3. `Heat': black to white through shades of orange and yellow.
4. `IRAF': color bands.
5. `AIPS': color bands.
6. Try it and see.

BLACK = b-level WHITE = w-level

These parameters are used when STYLE = "G" is specified. They control the range of image values that are for grey-scale or color images. (The names BLACK and WHITE only make sense for grey scale, though!) b-level and w-level are expressed as fractions of the peak brightness on the map. Pixels with values in this range are mapped onto the color palette by linear interpolation; pixels outside this range take the extreme colors. Note that BLACK may be either less than or greater than WHITE; BLACK=WHITE is not allowed.

When using PALETTE=1, the default values (BLACK=1, WHITE=0) are such that all negative and zero values are plotted white, and the maximum of the map is black. The scale can be inverted by specifying BLACK=0, WHITE=1. To accommodate negative values, you might want, say, BLACK=-1, WHITE=1. I hope to find a more user-friendly way to adjust the palette in a future version of MAPPLOT.

WEDGE

when this parameter is specified, MAPPLOT puts an annotated grey-scale or color wedge in the lower margin (if STYLE=G).

Parameters for Contour Maps

PLEV = p CLEV = c LEVS = l1,l2,l3... (up to 20 levels)

LEVS specifies up to 20 contour levels in units of the contour interval. The contour interval may be specified as EITHER a percentage of the peak (PLEV), or in the units of the map (CLEV). CLEV is only used if PLEV is zero. If you do not specify LEVS (or specify all zero values), the program will use default values of +/- 1, 2, 4, 8, ..., 512. In conjunction with the default value of PLEV (5%), this gives contours at +/- 5, 10, 20, 40, 80% of maximum. Negative contours are dashed. If you make more than one plot in a single run of MAPPLOT, and you want to draw fewer contours than in the previous plot, you will have to specify dummy zero values for LEVS to override the levels established previously; e.g.,

First run: 5 levels: LEVS = 1,5,10,15,20

Second run: 3 levels: LEVS = 1,25,50,0,0

If you do not specify the extra ",0,0" the levels used will be 1,25,50,15,20.

Parameters for Ruled-Surface Plots

ANGLE = x

specifies the elevation angle (in degrees) from which the surface is to be viewed. The default is 25 degrees. 0 gives a profile, 90 gives a plan view (not very useful).

General Plotting Parameters

FONT = n

specifies the font to be used for annotating the plot (1 = normal, 2 = roman, 3 = italic, 4 = script); default = 1.

LINEWIDTH = n

specifies the linewidth to be used when plotting. The default (1) is recommended for most devices; 2 or 3 gives good results on laser printers.

CONTLW = n

specifies the linewidth to be used for contours (if a different value from LINEWIDTH is required).

COLORS = c1, c2, c3, c4, c5, c6

specifies the color indices to be used for (1) annotation, (2) positive contours, (3) negative contours, (4) grey-scale, (5) upper surface of STYLE=S plots, (6) lower surface of STYLE=S plots. The defaults are 9, 1, 2, 1, 5, 2 which normally makes negative contours red. Specify 1,1,1,1,1,1 to produce a monochrome plot (black on white or white on black).

Annotation Parameters

LTYPE = n

specifies how the plot is to be labeled: specify:

• LTYPE=1 for an unlabeled rectangular border.
• LTYPE=2 for a border plus labels (title etc).
• LTYPE=4 (default) for a border plus title plus coordinate labeling relative to the center of the image.
• LTYPE=6 for border plus title plus labeling with pixel numbers.

[Other values for LTYPE used by the AIPS task CNTR are not implemented in MAPPLOT.]

BEAM

if this parameter is specified, the elliptical FWHM contour of the restoring beam will be drawn in the lower left corner of the plot; this does not apply to MEM maps and other images which do not have restoring beams.

BPOS = x,y

if this parameter is not specified, the beam ellipse (requested by parameter BEAM) is drawn in the lower-left corner of the plot; BPOS can be specified to control where the ellipse is plotted. The beam will be centered at position (x,y) in the map coordinate system (usually the coordinates are milliarcsec).

CHARSIZE = x1, x2

specifies the character size to be used in annotating the plot, as a multiple of the default size. The first number is used for axis labels, title, etc.; the second number is used for the additional annotation at the bottom of the page. The defaults are 1.0, 0.6. Size 1.0 gives characters that are about 1/40 of the height of the plot.

MARK = x, y, symbol

A single point on the image can be identified with a graph marker, centered on the point. The image point is specified by (x,y) in the image coordinate system (e.g., arcsec). The marker shape is specified by `symbol': the number of a PGPLOT graph marker in range 1-32.

TITLE = "Line1","Line2"

two text strings to be written above the plot (outside the frame). In both lines you may use the following codes to insert information as desired:

• %D replaced by: observation date (dd/mm/yy)
• %E replaced by: epoch (yyyy.yy)
• %F replaced by: frequency (with units)
• %S replaced by: source name (FITS OBJECT)
• %T replaced by: telescope or array name (FITS TELESCOP)
• %W replaced by: wavelength (with units)
• %Z replaced by: object redshift (value of input parameter Z)
• %% replaced by: '%'

The default is TITLE = "", "%s %t %f %d", i.e, the upper line is blank, and the lower line gives source name, telescope name, frequency, and date. If you just want to omit the telescope name, try TITLE = "","%s %f %d". You can do more complicated things, e.g., TITLE = "Source %s observed on %d", "with array %t at %w". You can also use the PGPLOT codes for changing font, e.g. TITLE = "\frSource = \fi%s","".

TOPLEFT = "Text"
TOPRIGHT = "Text"
BOTLEFT = "Text"
BOTRIGHT = "Text"

Arbitrary text strings can be written in the corners of the plot (inside the frame). The %-codes described under TITLE are active in these parameters also.

LABEL1 = x, y, "Text"

if specified, the supplied text string (up to 48 characters) is written in the plot with its lower left corner at coordinate position (x,y). Up to eight such labels can be written by specifying parameters LABEL1, LABEL2, LABEL3, ... LABEL8. Note that the units of the (x,y) coordinates must be those in which MAPPLOT labels the map. Thus for LTYPE=6, they are pixels; for other values of LTYPE, they are angular coordinates (usually milliarcsec). For surface plots, (x,y) are measured from (0,0) in the lower left corner to (1,1) in the upper right corner.

Z, H0, Q0, BARLENGT

If requested, a linear scale bar is drawn in the lower right corner of the map. This is controlled by the parameters Z, H0, Q0, and BARLENGT. If Z is not specified (or is zero or negative) no scale bar is drawn:

• Z : redshift of object (e.g., 0.518)
• H0 : Hubble constant, km/s/Mpc (default 100)
• Q0 : deceleration parameter (default 0.5)
• BARLENGT : length of scale bar in pc (default: chosen automatically) (will be rounded to integer)

Example: Z = 0.518 H0 = 100 Q0 = 0.5 BAR = 50

NOTITLE

this parameter suppresses the axis labels (Relative R.A. etc.).

ANNOT

this parameter controls the annotation that appears at the bottom of the page. ANNOT=1 (the default) requests full annotation; ANNOT=0 suppresses the file name and date and time (which should be omitted in a plot designed for publication); ANNOT=-1 suppresses the annotation entirely.

OPAQUE

If this parameter is specified (with no value or a non-negative value), the annotation that is written on top of the image (e.g., with TOPLEFT) is ``opaque'': it erases underlying parts of the image. This may make annotation easier to read if the underlying image is complex.

Overlaying Plots

OVERLAY (default -1)

If this parameter is specified with a positive or zero value, or no value, then the current image is plotted on top of the previous image in the same coordinate frame, shifting the image as necessary to align the two coordinate systems. OVERLAY is reset to the default (-1, no overlay) for each group of parameters. OVERLAY must not be specified on the first plot (there is nothing to overlay). If SHIFT is used with OVERLAY, the image is actually shifted relative to the coordinate frame.

  MAP = map1.fits		! name of first image file
  PLOT = /xw
  /				! first image is displayed as usual
  OVERLAY			! request an overlay image
  MAP = map2.fits		! name of second image file
  COLOR(2) = 7			! request different color for contours
  SHIFT = -2.3,1.2		! shift the center of this image to
				! coincide with that of the first image
				! (some trial and error may be needed)
  TITLE = "",""			! suppress title and annotation
  ANNOT = -1
  /				! second image is displayed as an overlay

Window Parameters

LRTB = x1,x2,y1,y2,...

a list of up to 80 numbers, representing 20 rectangular windows. These are defined in exactly the same way as for CLEAN. If LRTB is provided (i.e., non-zero) MAPPLOT will draw the windows on the plot.

SETWINDOW

specify this switch to request interactive window editing. (Do not specify it with a hardcopy device or a batch job.) If SETWINDOW is specified (i.e., a value greater than or equal to zero, or no value), then after drawing the plot MAPPLOT will go into interactive mode. In this mode, you can add new windows or delete some or all of those specified via LRTB.

To delete a window, position the cursor in the window and type D (or click the middle mouse button on a workstation). MAPPLOT erases the window outline by overwriting in black. If the cursor is in more than one window, only one (a random one) will be deleted.

To add a window, position the cursor at one corner and type A (or click the left button); then position it at the opposite corner and type A again (or click the left button again). MAPPLOT draws the outline of the window.

To exit from this mode, type X or click the right mouse button. You are returned to MAPPLOT parameter input, with the new window list set as the default. You can see the current windows by typing SHOW LRTB. The current windows are also saved in a file called lrtb.par, in KEYIN format. This file can be input to CLEAN or MAPPLOT by typing "@lrtb".

Alternatively, exit by typing S (save). In this case, you will be asked to supply a file name.

To exit without writing a file or updating the windows, type Q (quit).

Annotation

The annotation at the top of the plot consists of the two lines of text supplied with parameter TITLE, left justified. The first line is blank by default, and the second contains the object name (FITS parameter OBJECT), the telescope name (FITS parameter TELESCOP), the frequency, and the date of observation (FITS parameter DATE-OBS).

The annotation at the bottom of the page consists of four or five lines of text giving:

1. The maximum of the image, in the image units (e.g., Jy/beam).
2. The contour levels in percent of the maximum (these are the contours actually plotted; contours that were requested but not plotted because they fall outside the range of the image are not listed).
3. The FWHM dimensions and position angle of the "clean beam" (if appropriate).
4. The file name of the image.
5. The version of MAPPLOT, username, date and time.

Up to four "legends" can be written within the frame of the plot, in the upper left, upper right, lower left, and lower right corners. The text for these legends can be supplied with parameters TOPLEFT, TOPRIGHT, BOTLEFT, and BOTRIGHT. By default, both these strings are blank. It is also possible to write labels at specific places within the frame using the LABEL1, LABEL2, LABEL3, ... LABEL8 parameters.

If the image header includes the clean beam parameters, the FWHM contour of the clean beam will be drawn on the plot if the parameter BEAM is specified. By default, the beam is drawn in the lower left corner of the plot. To place the beam at some other position, use parameter BPOSITION=x,y: x and y are the coordinates of the center of the beam in the coordinate system of the image (typically milliarcsec, with x increasing from right to left and y increasing from bottom to top).

History