Examples

Let us continue with some examples of usage of these tasks.

• cginit initialises a PGPLOT device. Its only input is the keyword device. Most interactive PGPLOT devices are ephemeral, so that cginit is not useful for them. However, the PGPLOT /xs X window is persistent, so cginit is useful for it.

• cgdisp can display (simultaneously) contours, pixel map representations (i.e. images or ``grey scales''), vectors and boxes (pixels are displayed as filled [positive values] or hollow [negative values] boxes with size proportional to the pixel value) on a PGPLOT device. Up to three contour plots, one pixel map, one vector plot and one box plot may be displayed in multi-panel plots of multi-channel images. It also offers a ``mask'' image type, which is not displayed, but its blanking mask is applied to all the images that are. cgdisp can also display labelled overlay locations (plotted as boxes, stars, circles, ellipses, lines or see-through) which may be specified from an ASCII text file.

  We will just give a few examples of some common things that you might like to do with it.

  1. In the first example, cgdisp bins an image up by 2 pixels in the x and y directions, and then displays the image as a pixel map representation on a persistent X window. The transfer function wedge is drawn to the right and then you enter the interactive cursor driven fiddle loop. cgdisp then draws some overlay crosses on the plot (the overlay file format is described in the help file) and draws the beam size in the bottom right corner of the plot. The plot is annotated with useful information at the bottom and all four axes are labelled in arcsecond offsets from the reference pixel.

     CGDISP
     in=cena.icln	Input image
     type=pixel	Display as a pixel map
     region=quarter	Display central quarter of image
     xybin=2	Bin up image spatially
     chan	Unset; no channels to bin
     slev	Unset; no contours
     levs1	Unset
     levs2	Unset
     levs3	Unset
     range=#,#	Intensity range or unset for full range
     vecfac	Unset
     boxfac	Unset
     device=/xs	PGPLOT device; persistent X window here
     nxy=1	One plot per page
     labtyp=arcsec,arcsec	Label with offset arcseconds
     options=full,beambr,wedge,fiddle,trlab	Full plot annotation,
     	draw beam in BRC
     	Draw wedge, interactive fiddle
     	label top and right axes too
     lines=1,2	Linewidths for labels and overlays
     break	Unset; no contours
     csize=1,1,0.8	Set overlay character size to 0.8
     scale	Unset to fill page
     olay=stars.txt	Text file containing overlays

  2. The second example contours channels in the velocity range -100 to 100 km/s from two 3-D images (cubes); each channel is put on a separate sub-plot (but both cubes go on the same sub-plot) on the page and annotated with its velocity. Only every third pixel from the central 40 by 60 arcsec is displayed. The two cubes must have the same axis descriptors; i.e. the same axis dimensions and increments etc. The selected channels are binned up such that five channels are averaged together. However, the increment between the start group of each set of binned channels is 10. Thus, the displayed channel width will be one half of the displayed channel increment (they could of course be equal if you wish). The first cube is contoured via percentage levels, the second via absolute levels. The second cube's contours are drawn with a thicker linewidth. The two cubes could be from different spectral-lines, for example.

     Finally, a histogram equalised pixel map representation of a continuum image is overlaid on each channel sub-plot. As the output file is a disk file (a colour post-script file) we have used the range keyword to specify the desired lookup table (rainbow colours; fourth argument of keyword) and transfer function (histogram equalisation; third argument of keyword). Alternatively, we could still have used the interactive fiddle to do these things as the dialogue is keyboard driven for non-interactive devices. In fact, if we had set a transfer function via the range keyword and then invoked the interactive fiddle, we could have applied another transfer function to the already histogram equalised image !

     The options keyword is used to ask for an intensity wedge so that the map of colour to intensity can be seen. It is also used to ask for a full coordinate grid on the plot instead of just ticks as well as to annotate the plot with information about the images. Finally it is also used to ask for the value of the third axis (usually velocity or frequency) to be written in the corner of each subplot.

     When you ask cgdisp to display a mix of 2-D and 3-D images, the region (keyword region) that you specify applies equally to the first two dimensions of all images. However, any third axis region information that you give (e.g. region=image(10,120)) applies only to the 3-D images, and is ignored for the 2-D image. Finally, if you ask for more sub-plots than can be fitted on the page, then the task will advance to a new page (you will be prompted to hit the carriage return key if you are plotting on an interactive device) when needed.

     CGDISP
     in=oh.cube,hcn.cube,cont.icln	Input images; two cubes and continuum
     type=c,c,p	Two contours and a pixel map
     region=arcsec,kms,box(-20,-30,20,30)(-100,100)	Display central 40 by 60 arcsec
     	and -100 to 100 km/s
     xybin=3,1,3,1	Display every third pixel
     chan=10,5	Increment is 10 channels, width is 5 channels
     slev=p,1,a,0.05	Percentage and absolute levels for cubes
     levs1=-5,5,10,30,50,80	Percentage levels for first cube
     levs2=-3,3,10,20,30	Absolute levels (by 0.05 for second cube)
     levs3	Unset
     range=0,0,heq,2	Ask for histogram equalised display of
     	image with rainbow lookup table
     	between min and max.
     vecfac	Unset; no vectors
     boxfac	Unset
     device=plot/cps	PGPLOT device; disk postscript file here
     nxy=4,3	4 and 3 sub-plots in x and y directions
     labtyp=hms,dms	RA and DEC labelling
     options=wedge,grid,3val,full	Wedge, grid, velocity labels &
     	full page annotation
     lines=1,2	Linewidths for cubes 1 and 2
     break	Unset
     csize=1,0.7	Character sizes for axis and velocity labels
     scale	Unset to fill page
     olay	Unset for no overlays

  3. This third example shows how to display a position-velocity image. You could produce such an image by reordering a cube with reorder into velocity-x-y order. You could then look at one or several planes of this cube. Normally, cgdisp tries to display with equal x and y scales. This equality is worked out using the linear axis descriptors. Equal scales are meaningless when displaying unlike axes, so you should set options=unequal.

     CGDISP
     in=neon.vxy	Input vxy cube
     type=p	Display as a pixel map
     region=image(1,16)	Select first 16 planes, say
     xybin	Unset for all spatial pixels
     chan	Unset for all spectral pixels
     slev	Unset
     levs1	Unset
     levs2	Unset
     levs3	Unset
     range=#,#	Image intensity range or unset for full range
     vecfac	Unset
     boxfac	Unset
     device=/xs	X window
     nxy=4,4	16 sub-plots on the page
     labtyp=relkms,arcsec	Relative velocity and arcsecond labelling
     options=unequal	Unequal scales in x and y
     lines	Unset
     break	Unset
     csize	Unset
     scale	Unset
     olay	Unset

  4. This fourth example is a polarimetry display. It is common practice to display these images by way of a pixel map representation and/or contours for the total intensity, and vectors for the (fractional) polarised intensity at the specified position angles. The length of the vectors are proportional to the (fractional) polarised intensity. Here is an example of how to do this sort of polarimetric plot, where in this case the total intensity is displayed as both contours and a grey scale. The contours are displayed as multiples of the rms of the noise (you input the rms) in this case, although you can also use percentage-of-the-peak contours (this is controlled by the slev keyword - see the help file). You may need to fiddle with the keyword vecfac which allows you to scale the lengths of the vectors, and also specifies whether you draw a vector for each pixel or leave some of them out. The default is to draw a vector every second pixel and to scale the vectors so that the longest one takes up 1/20 of the plot. You can display any combination of the images (e.g. vectors only), but you must give both the vector position angle and amplitude images.

     CGDISP
     in=0823.fp,0823.pa0,0823.i,0823.i	Input images, order unimportant
     type=amp,ang,c ,p	Image types
     region=arcsec,box(-30,-30,30,30)	Display central 60 by 60 arcsec region
     xybin	Unset
     chan	Unset
     slev=a,#	Contour levels are to be multiplied by
     	the specified number; use the noise rms
     levs1=-5,-3,3,5,10,30,50,100	Contour levels
     levs2	Unset
     levs3	Unset
     range=#,#	Image intensity range or unset for full range
     vecfac=#	Defaults may be OK, or may require fiddling
     boxfac	Unset
     device=plot/ps	Postscript file
     nxy=1	One plot per page
     labtyp=hms,dms	Label with RA and DEC, say
     options=full,beambl	Full plot annotation, draw beam in BLC
     lines=1,2	Linewidth for contours and vectors
     break	Unset
     csize	Unset or fiddle with
     scale	Unset to fill page
     olay	Unset for no overlays

  5. The final example is also polarimetry display. Displaying rotation measure images as a pixel map is sometimes unsatisfying, as the sign changes, if any, can be hard to see. Similarly, contours can be pretty useless as the RM distribution is often very unsmooth. cgdisp offers the image type ``box'' whereupon each pixel is displayed as a small box. Positive pixel values are shown as a solid box, and negative pixel values as a frame only. The size of the box is proportional to the values of the pixel, so that this method is not so useful if you have RMs close to zero. By default, the boxes are scaled so that there is a little gap between adjacent boxes. You can control the boz sizes with the keyword boxfac which gives an extra scale factor to multiply the box widths. This keyword also gives the x and y increments (in pixels) across the image at which to plot the boxes.

     In this example, we also overlay contours of total intensity. In addition, a global blanking mask is applied to both images.

     CGDISP
     in=0823.i,0823.rm,0823.msk	Input images, order unimportant
     type=con,box,mask	Image types
     region=quarter	Display central quarter
     xybin	Unset
     chan	Unset
     slev=a,#	Contour levels are to be multiplied by
     	the specified number; use the noise rms
     levs1=-5,-3,3,5,10,30,50,100	Contour levels
     levs2	Unset
     levs3	Unset
     range	Unset
     vecfac=#	Defaults may be OK, or may require fiddling
     boxfac=1,3,3	Self scale box widths, and plot boxes
     	every 3 pixels in x and y
     device=plot/ps	Postscript file
     nxy=1	One plot per page
     labtyp=hms,dms	Label with RA and DEC, say
     options=full,beambl	Full plot annotation, draw beam in BLC
     lines=1,2	Linewidth for contours and vectors
     break	Unset
     csize	Unset or fiddle with
     scale	Unset to fill page
     olay	Unset for no overlays

• The task cgcurs is similar to cgdisp except that it is less flexible in terms of what it can display, but it does offer an interactive capability with the cursor. You can read image pixel locations and values, compute statistics over a region defined by the cursor, and define polygonal spatial regions that can be output into a text file for use in other tasks (using the region=@file facility). In addition, cgcurs can be used to generate text files in a format suitable (almost) for input to cgdisp and cgspec as overlay files.

  cgcurs only displays pixel maps or contour plots, and only one image at a time. You can invoke all of cgcurs' cursor options in the one run if you wish. You can also display many channels in the same way as cgdisp; in this case, the cursor options are invoked after each sub-plot (channel) is drawn. The following example shows how to display all pixels in the x direction, but only every third pixel in the y direction (who knows why you might do this), activate the interactive lookup table fiddler, read some image values with the cursor, mark their locations on the plot, and output them into a text file (called `cgcurs.cur') for use as an overlay file in cgdisp. In addition, the option to evaluate some statistics in a region defined by the cursor is also activated.

  CGCURS
  in=neon.mom0	Input image
  type=p	Display as a pixel map
  region=arcsec,box(-10,-10,10,10)	Display central 20 by 20 arcsec
  xybin=1,1,3,1	Pick out every third y pixel
  chan	Unset
  slev	Unset
  levs	Unset
  range=#,#	Image intensity range or unset for full range
  device=/xs	PGPLOT device; must be interactive
  nxy=1	Just one plot
  labtyp=arcsec,arcsec	Offset arcsecond labelling
  options=fiddle,curs,stats,mark,log,cgdisp	Fiddle, cursor and statistics options
  csize	Unset

• The task cgslice allows you to generate 1-D cuts (slices) through a 2-D image and then fit Gaussians to these slices. You can define many slices with the cursor or input their positions via a text file. In addition, you can display many channels from an image, and generate slices differently from each channel. Like cgcurs, cgslice only displays one image (which could be 3-D of course) at a time via a pixel map or a contour plot. You can save the slice locations, values and model fits in text files.

  In the example, we make slices from 9 channels of a cube, one channel at a time. We then fit Gaussians plus a baseline to them and output the fits into a text file.

  CGSLICE
  in=1333.icln	Input image
  type=p	Display as a pixel map
  region=quarter(1,9)	Display central quarter of
  	first 9 channels
  xybin	Unset
  chan	Unset
  slev	Unset
  levs	Unset
  range=#,#	Image intensity range or unset for full range
  xrange	Auto x-range scaling
  yrange	Auto y-range scaling
  device=/xs	PGDISP server
  nxy=3,3	9 plots on the page
  labtyp=hms,dms	RA and DEC labelling
  options=fit,base	Fit gaussian plus baseline
  csize	Unset
  posin	Define slices with cursor
  posout	Do not save slice locations
  valout	Do not save slice values
  modout=1333.model	Save Gaussian fits in this file