Velplot

velplot is a many faceted task for display and analysis of velocity fields - read the Miriad help file for velplot. velplot differs in its mode of operation from most other Miriad tasks in that a small portion only of the inputs are given in the usual Miriad form. The main body of the inputs are given by the user interactively after selection from an initial menu.

VELPLOT
in=data.cube Input data cube to be examined.
device=/xw Screen is the initial plot device
region=box(32,32,96,96)(5,60) Examine the centre of planes 5 to 60
log=data.log Text output where appropriate will go here

Now run velplot and the following main menu will appear:

         MAIN MENU
   Comment   Write comment into log
   List      List header and velocity information
   Integral  Integrated flux and statistics
   Options   Select plot parameters
   Pos-Vel   Plot versus position & velocity
   Spectra   Plot spectra
   Vel-map   Plot integrated velocity maps
   File      Write spectra & position-velocity file
   Read      Read spectra & position-velocity file
   Write     Write Miriad Image to disk file
   Exit      Exit from program

  Select option (type 1st character) :

This selection is not case sensitive, and only the first character is used. This is what the options are :

Comment
A comment will be written into the ASCII file. It goes like this:
   Select option (type 1st character) : c
   Enter comment > It's time I got to work
         comment > I had cereal for breakfast
         comment >
You need to get used to the velplot input style. You entered 2 lines of comment in response to the > prompt. A carriage return on the third line returned you to the velplot main menu. If you exit now and examine the file data.log you will find it contains header information from data.cube plus those two comment lines.

Also be aware that for many velplot inputs gives a carriage return/line feed after the question and you are faced with entering answers on a blank line. This can be quite disconcerting if you do not anticipate it.

List
List header and velocity information. The information is written into data.log a 4 line summary about data.cube
Integral
Integrated flux and statistics. This lists statistics for each data plane specified in the region originally selected. The headings are: plane (number), Velocity, Total Flux, Maximum, Minimum, Average and rms. Unfortunately this list is not written in to the log file.
Options
Select plot parameters. This is what happens:
   Selection (type 1st character) :o
 
      OPTIONS MENU
   Select alternative options [1/2] for the following

   Units for display [J/K]..... J
   Negative contours [Y/N]..... Y
   Plot header [Y/N]........... Y
   Write map to file [Y/N]..... N
   Absolute coordinates [Y/N].. N
   Integer plot [Y/N].......... N
   Spectra positions [Y/N]..... Y
   Fit Gaussians [Y/N]......... N
   Overlay Gauss Fits [Y/N].... Y
   Gray Scale [Y/N]............ N
   Exit from options menu
   Contour levels:  percent
    level( 1) =    15.000
    level( 2) =    30.000
    level( 3) =    45.000
    level( 4) =    60.000
    level( 5) =    75.000
    level( 6) =    90.000

  Select option (type 1st character,<cr> for options) :u
  -plot units are now Janskys

  Select option (type 1st character, <cr> for options) :e
Now the main menu will reappear. It is easy to get confused here between the main menu and this options menu that selects plot parameters.

The contour setting option is of particular interest in making contour plots. This is the equivalent of the levs input to Miriad cgdisp.

Pos-Vel
Plots a position velocity map. This is best described by walking through an example. We want a position velocity map made along the major axis of the galactic disk in data.cube. The position angle of the major axis is 40 degrees (measured north to east).

Run velplot and the main menu appears. Editorial comments below are in italics

   Select option (type 1st character) :p
   Plot intensity versus position & velocity along selected cuts
   >Type H for help, <cr> to continue :<cr>
   --- no current selection of cuts ---

   >List of cuts, RA-vel or DEC-vel ? [L]/X/Y):<cr>
Here, velplot in its usual cryptic style is giving us a choice of three options with the default option - which we chose by just hitting carriage return, is in square brackets.
   --- Enter list of pos-vel cuts to plot ---
   angles measured from north to east (0 to 180).
   >Type -n to delete cut n
         -99 to delete all
         L to list         (ie list the already chosen cuts)
         <cr> to use the current list.
   >Enter cut number, position and angle (n,x,y,pa):1,0,-60,40
We think the galactic centre is at 0,-60 arcsec with respect to the plot centre.
>Enter cut number, position and angle (n,x,y,pa):<cr> No more cuts wanted
>Enter convolving beam (major("),Minor("),pa(deg):<cr>No convolution requested
Gaussian falls to 6% at edge of array
size of convolution array: 3 pixels, 90.000 arsecs
Contour or Intensity plots ? [C]/I:<cr>
Here is where velplot can get very confusing. C and I are options for quite different functions, not like grey scale or contour options for the same plot. The function we want corresponds to the C option - hence the carriage return.
   >Enter number of windows in x and y: [1,1]: 
   <cr>
Notice a couple of things here. velplot inserted the carriage return after the prompting message and left us dangling there(slap on wrist to the programmer) but it is waiting for input so we enter return to choose the [1,1] option, i.e. single plot to the page (like nxy option in much of the rest of Miriad) so something will happen. Something does happen, the pgplot window with the position-velocity map appears on the screen. After dismissing the pgplot window we see some text about the plot on the screen and velplot continues as follows:
Another PGPLOT device ? (Y/[N])Y The last Y is our response
>Enter new PGPLOT device:pvplot.ps/ps Usual convention for a postscript plot
>Enter line width [1]:<cr> Single width lines

>Enter number of windows in x and y: [1,1]:<cr>
Now some velplot output about the plot appears on the screen. If you want several position-velocity cuts plotted on the one page you keep answering the ``Enter cut number etc'' question giving each successive cut a higher number and velplot will make a sensible choice of page layout.
Another PGPLOT device? (Y/[N])<cr> We do not want any more

Now we are finished and the main menu appears again. On exit we find the postscript file pvplot.ps in our directory.

Still in the position-velocity option, let us go back to the question

   Contour or Intensity plots ?[C]/I:
and answer I. Instead of the standard position-velocity plot we are now requesting plots of intensity versus position at position angles in certain (x,y) image planes that will be requested. This is a very different function from the standard position-velocity plot that comes from a 3-dimensional slice through the cube. So suppose we have entered 4 cuts:
   1,0,0,40
   2,100,100,30
   3,-100,-100,80
   4,500,-500,70
(to nominate an arbitrary set), the dialogue with velplot would be
Contour or Intensity plots ? [C]/I: I
How many channels ? (5 max) :3 Data from 3 channels to be plotted
Enter the channel numbers : 25,30,35 Channel numbers 25,30,35 only
Fix the scales ? Y/[N] : <cr> As before
>Enter number of windows in x and y: [2,2]: <cr>
We asked for 4 cuts but the cuts are now in the x,y planes of the specified channels. There will be 4 subplots and each subplot will have 3 lines plotted, one for each specified channel number. And now here is where it gets confusing. The PGPLOT window appears but only one of the 4 subplots.The PGPLOT window is hiding a question being asked by velplot of the form:
   >Enter name for ASCII file(<cr> to continue):
So give a carriage return and keep answering with carriage returns to the text window and watch successive subplots appear on the screen. velplot will offer the chance to make a postscript file as before and you will have to go through answering the question about the ASCII file for each subplot. Cumbersome but that is the way it is. The ASCII file would be a text list of the values in the plots , if you wanted such.

Spectra
Plot spectra. A spectrum is a plot of intensity vs position along a line parallel to the z (velocity) axis. This is an extremely useful function of velplot but quite complicated. We will explain via an example:
   Select option (type 1st character) :s

   Plot spectra at selected positions.
   (x,y) positions are in (HA,DEC) directions.
   >Type H for Help, E to Exit, <cr> to continue :<cr>
   --- no current selection of spectra ---

   >Enter G to enter a grid of positions,
          <cr> to edit or enter a list of positions :g
So we have chosen to define a grid, the most complicated option. Had we given just a carriage return we would have been offered the opportunity to make a list of positions similar to what is done for Position-Velocity plots.
   >Enter tlc (x,y), and PA of grid:
   100,200,0
So we are saying that the top left corner of the rectangular grid of positions at which we want spectra is at HA=100arcsec and DEC=200arcsec wrt to the centre of the plot. Our choice of PA=0 here means the grid has axes parallel to the x,y axes. If we had chosen PA=45 the whole grid would have been rotated through 45 degrees.
           (Grid PA is measured from N through E)
   >Enter interval(arcsec), nrows(along PA) and ncols:
   100,2,2
So we are asking for a 2 X 2 grid with 100arcsec spacing between elements.
   --- current selection of spectra ---
    spectra(1) (x,y) arcsecs: (  100.000,  200.000)
    spectra(2) (x,y) arcsecs: (  200.000,  200.000)
    spectra(3) (x,y) arcsecs: (  100.000,  100.000)
    spectra(4) (x,y) arcsecs: (  200.000,  100.000)
selection OK? ([Y]/N):<cr> Accept default- that is our list
GAUSSIAN FITS TO SPECTRA
>Enter convolving beam etc etc :<cr> We do not want a convolving beam
Another 5 lines of text are output
>Smooth spectra (H=Hanning, B=Boxcar, [None]) :<cr> No smoothing thanks
>Omit plots and Gaussian fits ? (Y/[N]) :<cr> We want the plots
>Fix scale for spectra ? (Y/[N] :<cr>
Had we said Y here we would have been offered the opportunity to set the vertical scale in Jy - like the range in cgdisp
   >Enter number of windows in x and y: [2,2]:
   <cr>
So velplot sensibly offers a 2 by 2 format for the 4 spectra we have specified. What follows next can be very confusing. The PGPLOT window appears and the first spectrum is plotted in the top left corner as expected but nothing more. Depending on your screen setup, the PGPLOT window is probably obscuring your text output and you do not see that velplot has asked
   >Continue with gaussian fit ([Y]/N) :n
and we say No because we do not want a gaussian fit. We told it that before but still we have to go through this to get all the spectral plots on the screen. The same question is asked repeatedly by velplot and we answer No each time as we watch successive subplots appear on the PGPLOT screen. Finally, after all the subplots have appeared the same question is asked yet again and when we say No the PGPLOT screen disappears and velplot continues as follows:
Another PGPLOT device? (Y/[N])Y Yes, lets get a postscript file
>Enter filename for spectra (<cr> to continue):
spectra.ps/ps Call the file spectra.ps
So now we are finished this spectrum plotting exercise. You may get the main menu again or you may be returned to Miriad and have to restart velplot if you want. spectrum.ps can now be plotted.

Another example of plotting spectra: Suppose you have a galactic disk data cube and you want to plot spectra at positions along the major axis. Then the grid needs to be collapsed into a line and rotated to the PA of the disk major axis (say 40 degrees). You think the position x,y=-1200,1000 is on the major axis toward the top-left corner of the x,y plane. You want 20 plots at 100arcsec intervals along the major axis. So the inputs to velplot/spectra would be:

   choose grid- g
   >Enter tlc (x,y), and PA of grid :
   -1200,1000,40
   >Enter interval(arcsec), nrows(along PA) and ncols:
   100,20,1

velplot would offer a 5 by 5 plot format but use only the top four rows (for the 20 plots actually 5 by 4)

Vel-map
Make plots of various moments of velocity averaged over specified velocity ranges. This works like the position-velocity option above. Type H for additional documentation. The most useful feature here is that the cursor can be used to change the plot parameters, or to plot the positions for spectra, or for position-velocity maps. These CURSOR OPTIONS are only available if a single velocity interval is selected in Vel-map. Here is what happens. The cursor appears in the PGPLOT window, and the CURSOR OPTIONS must be entered by typing a single character in the PGPLOT window. The results, or additional questions appear in the main window. It is easy to get confused here.
   >CURSOR OPTIONS: Type L to list options :

so we type L in the PGPLOT window, and in the main window we see:

    Cursor options:
    A - absolute coordinates
    C - change contour interval
    D - clear spec/pos-vel stacks
    E - exit from plot
    X - exit from plot
    G - change grayscale
    H - header label
    J - Jy contours
    K - Kelvin contours
    N - negative contours
    P - define pos-vel cut
    Q - Plot spec/pos-vel positions
    I - integral and rms in box
    B - blc for integral
    T - trc for integral
    R - replot maps
    S - Spectra position
    V - value and cursor position
    W - write out this map
   (x,y) positions are in (HA,DEC) directions.
   (Position angle is measured from N through E)
   >CURSOR OPTIONS: Type L to list options :

We can enter a spectra position with the cursor by typing S, and position-velocity cuts by typing P at any two positions along the desired cut. The lists of spectral positions and position-velocity cuts are stored and can be plotted after you return to the main menu.

Typing Cursor option B and T to define a box, followed by I, prints out the Total Flux, Maximum, Minimum, Average, and rms in the box in both Jy and Kelvin units.

Type E or X to exit from the cursor options.

Write
Write Miriad image to disk file. It does just this after prompting for a new name ie it gives you a copy of the region (or all) the input data.

File
Write file of spectra and position-velocity cuts. Suppose you have been doing pos-vel and or spectra then there will exist lists of cuts. This option enables you to save the lists to a named file so you could refer to them on a subsequent running of velplot.

Read
Read file of spectra and position-velocity cuts You saved the lists in a previous WA and now you can retrieve them.

The File and Read options allow you to have several lists of cuts and access them alternately without leaving velplot.

Miriad manager
2016-06-21