The GPLOT User guide


CONTENTS

1 INTRODUCTION

1.1 Description of the package

If you want to use GPLOT without any delay reading this manual, you should try GPLOT recipes: Using GPLOT for the first time

GPLOT is written for those who want a lot of flexibility in creating plots and therefore are not satisfied with applications with a limited number of plot options. GPLOT is a General Plotting program based on subroutines of the plotting package PGPLOT and some specially written routines to interface with GDS (GIPSY Database System). The program enables you to plot contour- grayscale- and colour plots of GIPSY images. It plots profiles taken from a GIPSY image, reads data from file, manipulates this data (using expressions) and plots it in various ways (line diagram, histogram etc.). GPLOT labels axes with physical coordinates if the axis is related to a GIPSY set. There is a lot of flexibility in drawing these axes:

GPLOT is command driven and therefore cannot be compared with a program like CPLOT which is controlled by keywords. GPLOT has one major keyword: COMMAND= This keyword is prompted in a loop. It processes GPLOT plot commands like frame, move, etc.

1.2 Devices

GPLOT needs to know the destination of the plot output (plot device).

Such a device can be the screen, a hardcopy device or a PostScript file. If you enter a plot command without specifying the destination first, you are prompted by GPLOT with a keyword (GRDEVICE=) to specify the plot device . Pressing carriage return at GRDEVICE= will list the devices that are implemented on the machine that you are working. If you want output to screen, you can use GRDEVICE=X11, or GRDEVICE=GIDS. These are both colour devices. In most situations you will specify the device with GPLOT command device. It accepts three arguments:

  1. The device specification for the plot device. If omitted or if this argument is a question mark, GPLOT will prompt you with the keyword GRDEVICE= Pressing carriage return will generate a list with available devices.
  2. Number of subdivisions of the view surface in X direction.
  3. Number of subdivisions of the view surface in Y direction. If the view surface is divided in sub pages, the command page moves to the next sub-page and not to the next physical page. This paging applies only for plots created in world coordinates.
If you selected a hardcopy device, the plot is sent to the printer after the plot file is closed. You close the plot file with 'close' or by quitting GPLOT.

1.3 How to get help

After your device selection, GPLOT will prompt you in a loop with keyword COMMAND= This is the place to enter a GPLOT command. A list of available commands is generated with:
   COMMAND=help
Typing the help command with an argument will generate a small description (syntax, purpose, example) about all items containing that argument . More arguments can be given at a time, e.g.
   COMMAND=help move draw
will list the available information about move and draw. The '*' character is used as a wildcard. So help *labe* will list information about xlabel, ylabel and toplabel. You can obtain all available help with:
   COMMAND=help *
If you want the help results to be stored in an Ascii file on disk, use:
   COMMAND=file <filename> help 
Or if you want to store specific items (wild cards are allowed):
   COMMAND=file <filename> help item1 item2 ...
If you want to consult a part of this manual from within GPLOT, try command manual. You will be prompted with: Edit file? Press carriage return to load the manual in the editor which is defined by the environment variable EDITOR. Quit the editor in the standard way to continue with GPLOT. In the GIPSY Recipes you will find o couple of documented examples containing GPLOT macro's and plots (GIPSY Recipes: Contents)

1.4 The 'main' macro and others

After starting GPLOT, you will experience that all commands that you enter, are executed immediately so you are creating a plot interactively. These commands are stored and can be reused. In fact you are building a macro with the name main, therefore we call the current input mode the 'main' or 'execute' mode. In this mode you can play back all the recorded commands (playback) or send the current plot to the printer (hardcopy). The contents of main can be saved in a file on disk using the write command. You can edit this file and read it in GPLOT again. If you are using the same sequence of commands more than once, it can be profitable to store them in a macro. You enter this 'macro' mode by typing
   macro <name>
The commands entered in this mode are NOT executed, only stored. They are executed if you call the macro by its name in main. The macro accepts variables in its call, so macros can be used to develop your own (complicated) plot commands. You can insert and delete commands in 'macro' mode, but editing of macros can be done also (and more easily) with the edit command. It starts your local editor (defined by the environment variable EDITOR). The macros can be read from or written to a file on disk.

1.5 How to end a session

A GPLOT session is aborted with the command quit or stop. If a file or a printer was selected then at the moment of quitting, the file is closed, or the plot is sent to the printer. If you want your plot without leaving GPLOT, use the command close to obtain the same result.

1.6 A simple GPLOT session

A first interactive session: draw a very simple contour plot: You need only to type the GPLOT command (everything listed after the ! character is comment).
   <USER> gplot                         ! start gplot
   <USER> GPLOT COMMAND=device x11      ! select device
   <USER> GPLOT COMMAND=inset tothi f 1 ! input of subset of set 'tothi'
   <USER> GPLOT COMMAND=box             ! default box ==> entire subset
   <USER> GPLOT COMMAND=xscale 1.0      ! set a scale in x direction
   <USER> GPLOT COMMAND=yscale 1.0      ! set a scale in y direction
   <USER> GPLOT COMMAND=levels 2 3 4    ! contour levels
   <USER> GPLOT COMMAND=contour         ! draw the contours
   <USER> GPLOT COMMAND=frame           ! draw axis frame
   <USER> GPLOT COMMAND=move 0 0        ! move to grid position 0,0
   <USER> GPLOT COMMAND=marker          ! put a marker at this position
   <USER> GPLOT COMMAND=write main h1   ! write main to disk in 'h1'
   <USER> GPLOT COMMAND=q               ! quit GPLOT
Create the same plot on another device, and use the saved file:
   <USER> gplot                         ! start gplot
   <USER> GPLOT GRDEVICE=gids           ! select GIDS
   <USER> GPLOT COMMAND=input h1        ! read and execute file h1

2 COMMAND SYNTAX

2.1 Commands entered manually

Commands for GPLOT are given at the GPLOT prompt:
   GPLOT COMMAND=
Everything that is entered at this prompt follows the Hermes rules, i.e. you can use COLA, default files and recall files. GPLOT does not distinguish lower and upper case commands. Commands can be abbreviated as long as the abbreviation results in an unique command. If a command is not unique then GPLOT will list which commands that are. Commands like move, draw etc. are stored in a local macro. These stored commands all have a number. The command list lists all the stored commands in the current macro together with their number. If you want to insert commands, give a command number and all the commands given from that time on will be inserted until you return to the end of the macro by typing a number that is equal to the highest line number+1, or by typing the command end. However, it is much easier to use the command edit to edit your macro. This will start your local editor (See also chapter about edit command).

2.2 Commands from file

The command input <filename> reads commands from file, executes and stores those commands in main. The file is a plain ASCII file. Valid commands are executed immediately, but reading is aborted when invalid or unknown commands are encountered. A command in a file can be split over a couple of lines. Each line, except the last, must be closed with a backslash (\) character (this differs from the manual input). All characters after a '!' character are treated as part of a comment until a newline is encountered. Here is an example of the contents of a file with GPLOT commands:
   xcolumn ellfit_R_fixcen.dat 1        ! read from column 1
   ycolumn ellfit_R_fixcen.dat 11       ! read from column 11
   excolumn ellfit_R_fixcen.dat 2
   xrange 0 9
   yrange 150 15.8                      ! box in world coords.
   xscale 0.5                           ! scale (grids/mm)
   yscale 0.2
   symbol 5                             ! a 'X' as marker
   font roman                           
   xmargin 0.5
   ymargin 0.5                          ! extra space for the axes
   justific 0.5                         ! text justification
   charheight 4.2                       ! character height
   frame                                ! draw the frame
   charheight 4.8
   points                               ! plot points in x/y column
   errorbar x -x                        ! error bars in x-direction
   move 50,-15                          ! move pen to this position.
   xlabel Radius (arcsec)               ! label x-axis
   ylabel surface brightness (30 - mag arcsec\u-2\d)
   angle 0
   justific 0
   move 65,92
   charheight 7.2
   text NGC 4736  R
   charheight 1.5
   move 65,85
   text Center pos. fixed
   charheight 2
   move 75,103                          ! position for id.
   id                                   ! user name and date

2.3 Commands defined by macro's

A macro can be build within or outside GPLOT. If you build a command macro with an external editor, then the contents can be read with: read <macroname> <filename> 'macroname' is the name of your new command and 'filename' is the name of the command definition file on disk. A percent character followed by a number will be substituted by a parameter in a call to a macro. See also 3.1 What are GPLOT macros?.

2.4 Comments in the input

Text after the '!' sign in an input line is treated as comment. If you use the internal editor to edit your commands, the comments will be lost. It is more convenient to use an external editor and the input command.

2.5 Argument separators

Usually, a space or a comma serve as argument separators. If you want to pass a string with spaces as parameter of a command that recognizes more than one parameter, enclose the string with the double quote character.
Command separators between parentheses are also skipped. For example:
   xcolumn  ( xcolumn / 4 )
is a valid expression with the parentheses. Because of this construction it is also possible to use the extended user input features such as functions to obtain numbers from descriptors, images, tables and files. Note that brackets '[]' and parentheses '()' are treated equally.

At the COMMAND= prompt, text and characters can be escaped with the back quote (`) character.

3 COMMANDS RELATED TO MACROS

3.1 What are GPLOT macros?

Sometimes it is very convenient to store commands that are linked in some way in a macro. Such macros can be written to disk and read from disk and can be activated in main mode by typing their name and, if programmed, one or more parameters. Creation of a new macro is started with the command macro <macroname> or with edit <macroname>. The commands written in this mode are not executed but are stored. The use of variables is possible. In the macro you type %n where n is a number >= 1. If the macro is called with arguments in main mode, the first argument is substituted for %1, the second for %2 etc. The arguments can be text strings or numbers. Each command in a macro must be written on one line. You can spread it out over more lines, but then each line (except the last) must be closed with a back slash (\) character. Here is a short example of the use of this back slash.:
   frame
   move 0 30
   draw (cos(%8/57)*cos(%8/57)+sin(%8/57)\  ! Now continue on next line
   *sin(%8/57)*cos(%9/57)*cos(%9/57))*100\
    sin(%7/57)                              ! Note space as first char.
                                            ! (before 2nd argument)
The maximum number of macros, the maximum number of variables and the maximum length of a command are limited by internal memory only. There are 3 possibilities to create a command macro:
  1. Create with your editor the file rotcur.mac
  2. or start writing the macro with: edit rotcur
  3. or start writing the macro with: macro rotcur
Suppose you created a file with contents:
   !==================================================
   ! (rotcur.mac)
   ! Macro for plotting rotation curves
   ! parameters: 1  NGC number (without the NGC)
   !             2  Maximum radius (kpc)
   !             3  Maximum rotation velocity (km/sec)
   !
   xcolumn rot%1.dat 1
   ycolumn rot%1.dat 2
   eycolumn rot%1.dat 3
   xrange 0 %2
   yrange 0 %3
   frame
   xlabel radius (kpc)
   ylabel Rotation Velocity (km/sec)
   connect
   errorbar -y y
   move 0.5 0.9
   text NGC%1
   !==================================================
Then the macro is read and executed by:
   read rotcur
   rotcur 4344 200 300

3.2 Modification and the use of macros

If you want to delete a command in the current macro, or delete a non active macro in memory, use the command delete, which accepts:
  1. The name of a non-active macro, to delete that macro
  2. One or more line number (GIPSY input syntax), to delete corresponding lines, e.g. delete 4:7 10 to delete commands 4,5,6,7 and 10

edit

The edit command can be used while in main mode or in macro mode. It pops up the local editor (i.e. the editor set with the environment variable EDITOR e.g. setenv EDITOR /usr/local/bin/mem ) and prompts the user with a (temporary) file name. If you press carriage return, the editor loads the contents of the current macro. You can edit that contents now. If you want to abort at this point, use <ctrl> C. After editing, write the contents back to the (temporary) file. The program automatically updates the contents of the current macro. If a macro name was given, that macro will be edited. If you insert commands that cannot be stored (edit, macro, delete etc.), then GPLOT skips these commands automatically. The program also skips unknown commands, and generates a warning then. Comments are lost in this edit session.

end

The end command has two functions. If you are in insert mode, end will put you back in append mode. If you are not in insert mode, but are updating a macro (macro mode) the command end will bring you back to main mode, the mode in which a command is executed. The command close closes the plot file and releases the graphics device. If you want to stop the program, use quit or stop.

hardcopy

The command hardcopy asks for a device specification, re-executes all the stored commands, closes the plot file and send the file to the selected device. It works in main mode only. You can give a device as argument. If the device is omitted, you are prompted with the GRDEVICE= keyword. Pressing carriage return generates a list with available devices. Your selection needs not to be a real hardcopy device, it can also be a different screen device or a PostScript file.

list

The command list works for the active macro and can be given as list (without arguments) to list all the command lines or as list with line numbers following the GIPSY input syntax for integer numbers, e.g. list 4:7 10 will list lines 4,5,6,7 and 10.

read

A macro on disk has the extension '.mac'. To read it in memory, you type the command read <macroname> without the extension .mac From that moment on, the macro can be executed if you type its name in main mode. A second argument can be specified also. This must be the name of a file on disk. Example:
   read house                  !Start macro 'house', and
                               !read input from house.mac
   read stars local.txt        !Start macro stars and read
                               !input from local.txt
The second parameter can be prefixed with a pathname. Example:
   read stars /dj2/users/me/stars.mac
Another possibility is to set a path using the macdir command. GPLOT searches in the directory given by the macdir argument, for a macro. The path can contain only one path specification. If you use macdir without a parameter, the directory is set to the current directory. Example:
   macdir /dj2/users/somebody/cola/

playback

playback re-executes the commands in main. Default it does this for the previous selected device, but if you want to change the device, use playback with the name of the new device as an argument. Note that if this new device is a hardcopy device:
the plot is sent to the printer only after close or quit is typed to close the plot file.

status

status displays the status of all macros stored in memory. For each macro, the number of stored commands and the number of bytes that is allocated are listed.

write

Macros can be stored on disk with write <macroname> [<filename>]. It stores the contents of the macro with name <macroname> in a file <macroname>.mac or in <filename> if a file name was specified also. If you substitute main for <macroname>, then the contents of main will be sent to a file on disk. Usually the contents of this file will re-enter GPLOT with input and not with read.

4 USING VECTORS TO PROCESS DATA

4.1 GPLOT vectors

GPLOT vectors are variables with names va, vb, ..., vz, xcolumn, ycolumn, excolumn and eycolumn. The last four vectors are special because they are used for plotting data points, profiles, histograms etc. There are a couple of possibilities to define the contents of a vector. First, the vector name is also a GPLOT command, so, after the COMMAND= keyword, you specify the name of the vector you want to define. Then enter: Examples
va log(10):log(100):2/4
contents of column va is 1.0 1.5 2.0
excolumn deg(acos(0.3 0.5))
contents of column excolumn 72.5424 60.0
vz image(aurora freq 10, -5 -5 5 5 )
vz contains the central 121 pixel values of set ``aurora'' at FREQ=10.
xcol table(aurora p 2, ROTCUR03, VROT, 1:20)
xcolumn contains 20 values from column ``VROT'' in table ``ROTCUR03'' from set
``aurora'' at PARAM=2.
vb file(rotcur03.dat, 4, 1:20)
vb contains 20 values from column 4 in ASCII file rotcur03.dat.
xcolumn va*vb/ycolumn
Multiply the contents of vector va with vb and divide the result by the contents of ycolumn

4.2 Plotting data from file

Data can be plotted in various ways. One way is to plot a marker on positions x, y given in two arrays called xcolumn and ycolumn. One command to get data from file into such an array (f.i. xcolumn) is:
   xcolumn <filename> [n]
n is a column number that corresponds with the n-th column in file <filename>. If omitted, the first column is extracted. The file can contain empty lines or lines with the comment marker (!). Text after the comment character will not be scanned. Example:
   xcolumn radius.dat 1     !Read 1th  column from radius.dat in xcolumn
   ycolumn radius.dat 2     !Read 2th  column from radius.dat in ycolumn
   points                   !Plot the markers
Another use of the marker command is described in section 7.3 Graph Markers.

A second method to read from file is the use of the Hermes syntax for input from file:
xcolumn file(<filename>, column, row-range). As an example:

   xcolumn file(gauss.dat, 2, 2:80)
reads from file gauss.dat, the second column, rows 2 to 80. The vectors excolumn and eycolumn are used to plot errorbars with command errorbar.

4.3 Mathematical expressions

A vector can also be used in a mathematical expression thereby creating a new vector. Different vectors in an expression must have the same length, otherwise an error message is displayed. The length of the mathematical expression cannot exceed 1024 characters. The array length is limited only by memory. Variable names in an expression cannot be abbreviated.
   xcol 0:90                     !generate values 0..90 in xcolumn
   ycol sin(rad(xcolumn))        !take the sine of each entry in xcolumn

GPLOT has 4 internal vector variables which represent a special array used to plot data etc. These vectors are: xcolumn, ycolumn, excolumn and eycolumn.

4.4 List of functions (expressions for vectors & text)

You can process data in the arrays represented by xcolumn, ycolumn etc. using operators, constants and functions that are listed below (x and y are column names xcolumn, ycolumn, excolumn, eycolumn). The same perators, constants and functions can also be used in expressions embedded in text.
        abs(x)         absolute value of x
        sqrt(x)        square root of x
        sin(x)         sine of x radians
        asin(x)        inverse sine of x
        cos(x)         cosine of x radians
        acos(x)        inverse cosine of x
        tan(x)         tangent of x
        atan(x)        inverse tan of x
        atan2(x,y)     inverse tan (mod 2pi) x = sin, y = cos
        exp(x)         exponential of x
        ln(x)          natural log of x
        log(x)         log (base 10) of x
        sinh(x)        hyperbolic sine of x
        cosh(x)        hyperbolic cosine of x
        tanh(x)        hyperbolic tangent of x
        bj(n,x)        Bessel function of 1st kind, integer order
        by(n,x)        Bessel function of 2nd kind, integer order
        bi(n,x)        modified Bessel fn. of 1st kind, integer order
        bk(n,x)        modified Bessel fn. of 2nd kind, integer order
        rad(x)         convert x to radians
        deg(x)         convert x to degrees
        erf(x)         error function of x
        erfc(x)        1-error function
        max(x,y)       maximum of x and y
        min(x,y)       minimum of x and y
        sinc(x)        sin(x)/x (sinc function)
        sign(x)        sign of x (-1,0,1)
        mod(x,y)       gives remainder of x/y
        int(x)         truncates to integer
        nint(x)        nearest integer
        ranu(x,y)      generates uniform noise between x and y
        rang(x,y)      generates gaussian noise with mean x
                       and dispersion y
        ranp(x)        generates poisson noise with mean x
        ifeq(x,y,a,b)  returns a if x == y, else b
        ifne(x,y,a,b)  returns a if x != y, else b
        ifgt(x,y,a,b)  returns a if x > y, else b
        ifge(x,y,a,b)  returns a if x >= y, else b
        iflt(x,y,a,b)  returns a if x < y, else b
        ifle(x,y,a,b)  returns a if x <= y, else b
        ifblank(x,a,b) returns a if x == BLANK, else b

        available constants:
        PI             3.14159....
        C              speed of light (SI)
        H              Planck (SI)
        K              Boltzmann (SI)
        G              gravitation (SI)
        S              Stefan-Boltzman (SI)
        M              mass of sun (SI)
        P              parsec (SI)
        BLANK          Universal undefined value

        available operators:
        +              addition
        -              subtraction
        *              multiplication
        /              division
        **             power

5 PLOT COMMANDS

5.1 Plot modes (world-, mm mode)

Suppose you want a plot where the x axis has a range between -128 to 128 (in whatever units). The range in y values that you expect is -1 to 5. If you don't plan to use a GIPSY set as to define a frame, you have to use commands to set the limits first. These commands are box and xrange, yrange. The box command defines both corners that sets the limits of the frame. The other commands, xrange and yrange set the limits in horizontal and vertical directions separately. The box becomes important if a GIPSY set is used to define a plot frame. For the ranges mentioned above, one could have entered:
   box  -128 -1 128 5
      or:
   xrange -128 128
   yrange -1 5
(See also: 5.2 Scaling) Now we have specified the frame limits in so called WORLD COORDINATES. These world coordinates have only meaning to a plot if GPLOT knows how to scale the ranges with respect to the sizes of the selected output device. Scales are set with xscale and yscale (units are world-coordinates/mm) or xsize and ysize (units in mm). After you entered limits and scales you can move to a position in the plot with command move with 2 parameters given in world coordinates. If you start GPLOT you are in the plot mode that plots in world coordinates. GIPSY users are already used to world coordinates, but they call them GRIDS. If you plot axes with the axis command, you get labeled axes and these coordinate labels correspond to the world coordinates. If however a set is defined with the inset keyword, the default axis command will not write world coordinates labels but it writes physical coordinate labels instead. These physical coordinates are just grids that are converted to physical values according to a certain coordinate transformation. If you know beforehand that such labels could be plotted, then positions can also be entered as physical values, e.g.
   move * 10 12 8  * -67 8 9.6  
   or: 
   move 300000 M/S U 45
(see also description in section 5.5 Physical coordinates and units

The second plot mode that you can select is the millimeter mode. Command

   mmeter 
will bring you in this plot mode that ignores the scales that have been set and here you work in millimeters only. This can be handy if you want, for instance, to plot a text at a fixed position on paper. If you want to return to the mode with world coordinates again, use
   world
Commands tomm x y (x, y in world coordinates) and toworld x y (x, y in millimeters) convert parameters x, y to millimeters and world coordinates respectively.

5.2 Scaling

There are a number of steps that you have to carry out if you want your plot to have a certain size. The command box sets the limits of the plot. The box is given as two corners. The first two numbers are the lower left corner and the last two numbers are the upper right corner of the box. We can summarize the syntax as:
   box xlo ylo xhi yhi
Where xlo, ylo, xhi and yhi are floating numbers, the so called world coordinates. The limits can also be set separately by the xrange and yrange commands. Note that it is allowed to set lo > hi for both directions and y. Things change if the command inset was used to select a set. Then the rules are set by a GIPSY function that converts positions and you use the input syntax for boxes that you know from other GIPSY programs (using physical coordinates etc.). A restriction however is that if a set is used, the value of lo must be less than the value of hi (otherwise command box will sort the coordinates). But this can be overruled by the xrange and yrange commands. The second restriction is related to the dimensionality of the input set. For a one-dimensional (sub)set, the box command only apply for one direction. The range in the other direction has to be set with the yrange command.

After you set the limits, you must scale the plot. This can be done with:

  1. The commands xscale and yscale. Without a set, it is a number in world coordinates per millimeter. With a set, the scales can be followed by a unit. If a conversion can be made, then the scale is converted to world coordinates automatically.
    Example: xscale 2 hmssec.
  2. The commands xsize and ysize. These commands accepts a number in mm as argument and a range in world coordinates will be scaled onto a given size. In fact these commands change the values of xscale and yscale.
Note that commands that set the scaling must be used AFTER commands that set a box or a range.

5.3 Defaults set by GPLOT

If a device is opened, some (invisible) characteristics of that device are retrieved to be able to calculate a default scale and box for plotting. The default box ranges from xlo, ylo = -128, -128 to xhi, yhi = 128 128. You can change the values with the commands: box and xrange, yrange. If however, a set is known (inset command was used), the box command is more suitable because it recognizes GIPSY coordinates. The default scales are calculated in a way that the default box (= entire (sub)set after inset and if no limits were set yet) fits on your plot device. The lower left position of the device is 0,0 mm but the lower left position of the viewport is offset wrt. 0,0 mm. You can set this position with the location command (position in mm) or with the ulocation command (position in world coordinates).

There is a command that scales the current box automatically to fit on the current device. This command, autoscale, can be used after a command that sets a box. You can use it also after the inset command. If a box was not set, it will scale to fit the entire (sub)set onto the current device.

The easiest way to fit a plot onto the current device after setting a box or ranges, is using command autoscale (without parameters).

5.4 Physical coordinates and units

If a GIPSY set (with a defined coordinate system) is specified with the inset command, you are allowed to postfix the number with a unit known to the system. If for instance you want a scale in x-direction of 10 arcsec in one mm, use:
xscale 10 arcsec
Units currently known to the system are:
              DEGREE      ARCSEC      ARCMIN      RADIAN
              CIRCLE      DMSSEC      DMSMIN      DMSDEG
              HMSSEC      HMSMIN      HMSHOUR
              METER       ANGSTROM    NM          MICRON
              MM          CM          INCH        FOOT
              YARD        M           KM          MILE
              PC          KPC         MPC
              TICK        SECOND      MINUTE      HOUR
              DAY         YEAR
              HZ          KHZ         MHZ         GHZ
              M/S         MM/S        CM/S        KM/S
              K           MK
              JY          MJY
              TAU
The offset is controlled by the location command. This command accepts two numbers. These numbers are values in mm. There is a default location. With location, xscale and yscale, the transformation between mm and world coordinates is fixed.

A box defines an area in world coordinates. If an input set is 2 dimensional, the command needs 4 parameters: xlo ylo xhi yhi. If a set is one dimensional, it needs 2 parameters: xlo, xhi For box you can use the syntax for boxes as described in the GIPSY User Guide i.e. you can use a syntax like:

box PC 10 10
The box that you select in world coordinates, defines a viewport. This is a rectangular portion of the plotting surface onto which your graphs are mapped. It takes care of clipping, i.e. any parts of the image that would appear outside the viewport are suppressed. When a set is defined with the command inset, all positions can also be given in coordinates that the program can convert to units given in the set header. A position can be given in the same way as you give positions at the POS= keyword in other GIPSY applications. Examples make this more clear: Suppose you specified inset AURORA FREQ 1 which is a RA/DEC/FREQ cube. The units of RA and DEC are DEGREE. You can move the current pen position with:
   move 10 10                      ! Move to (10,10) in world coordinates.
   move PC                         ! Move to projection center in set
   move * 10 12 8  * -67 8 9.6     ! Move to RA 10h12m8s, DEC -67d8m9.6s
                                   ! in the epoch found in the header
   move *2000.0 10 12 8 *2000.0 -67 8 9.6
                                   ! Same as above but now for Epoch 2000.0
   move U 45.323 U 30.322          ! Move to physical position 45.323, 30.322
                                   ! DEGREE
   move G 45 G 45                  ! Move to this galactic lon, lat in degrees
   move E 45 E 45                  ! Move to this ecliptic lon, lat in degrees
   move S 45 S 45                  ! Move to this supergalactic lon, lat in
                                   ! degrees

   For a RA-FREQ plane you can use for instance:

   move 32 30                      ! Just grids
   move 1418.6 MHZ 30              ! A frequency and a grid
   move 300000 M/S U 45            ! A velocity and a number in axis units
Most of the plot commands accept the same arguments as their equivalents described in the PGPLOT manual. Sometimes the number of arguments or the order of the arguments is changed. For example all routines that accepts a box as argument must receive the box data as: xlo ylo xhi yhi i.e the standar GIPSY syntax for defining a frame. This differs from the documentation in the PGPLOT manual. The command help informs you about the correct syntax of the arguments.

6 ATTRIBUTES

6.1 Overview

The appearance of the primitive elements of a graphical image (lines, graph-markers, text, and area-fill) can be changed by specifying primitive attributes. The attributes, and the corresponding routines for changing them, are: Once an attribute has been changed by a call to the appropriate routine, it remains in effect for all subsequent plotting until it is changed again. If you omit parameters then these commands are in inquiry mode i.e. the will list the current value of the attribute. In addition to the inquiry mode there is a command to list the current value of each attribute and that command is plotinfo.

Each attribute command without parameters will list its current value.

6.2 Color Index

This attribute affects all the primitives: lines, graph-markers, text, and area-fill, and is controlled by the command colour or color. Devices differ considerably in their ability to draw in more than one color. On most hardcopy devices, the default color is black on a white background, while on most CRT devices, it is white (or green) on a black background. Color is selected using the command color with an integer (called the colour index ) or the name of a color. Color index 1 is the default color (name: foreground or default), and color 0 is the background color. The number of different color indices available depends on the device. On most monochrome devices, only color indices 0 and 1 are available, while some color CRT devices may permit color indices from 0 to 255. On some monochrome devices, color index can be used to select different brightnesses (intensities).
Color index 0, the background color, can be used to erase elements from a picture by overwriting them with color index 0. Note that not all devices are capable of this: e.g., Tektronix storage-tube terminals and pen-plotters cannot erase part of a displayed picture.
   Color Representations
   0    Background
   1    Foreground or Default (Black if background is white)
   2    Red
   3    Green
   4    Blue
   5    Cyan (Green + Blue)
   6    Magenta (Red + Blue)
   7    Yellow  (Red + Green)
   8    Red + Yellow (Orange)
   9    Green + Yellow
   10   Green + Cyan
   11   Blue + Cyan
   12   Blue + Magenta
   13   Red + Magenta
   14   Dark Gray
   15   Light Gray
   16-255   Undefined

6.3 Line Style

Line Style can be solid, dashed, or dotted. The attribute affects only lines, not the other primitives. It is controlled by lstyle where n is one of:
   number      name                     pattern
   ==================================================
     1       full line    
     2       long dashes             10::8
     3       dash-dot-dash-dot       8 6 1 6  8 6 1 6
     4       dotted                  1 6 1 6  1 6 1 6
     5       dash-dot-dot-dot        8 6 1 6  1 6 1 6
The line style can be adapted to one's own taste with the pattern command. Its parameters are 8 numbers which set a new line style pattern. The numbers consist of 4 pairs. The first number of each pair is the number of dots that must be plotted and the second number is the number of dots that must be skipped. The line style is reset with command lstyle 1. The parameters are floating point numbers > 0

6.4 Line Width

Line Width affects lines, graph-markers, and text. A thick-nibbed pen is simulated by tracing each line with multiple strokes offset in the direction perpendicular to the line. The line width is specified by the number of strokes. The default width is one stroke, and the maximum that may be specified is 21. The exact appearance of thick lines is device-dependent. It depends on the resolution of the device, but on hardcopy devices GPLOT attempts to make the line-width increment equal to 0.005 inches. Requesting a line-width of 10, say, should give lines that are approximately 1/20 inch thick. To change the line width, use lwidth.

6.5 Character Height

Character Height affects graph-markers and text. Character height is specified as a size in mm. The default character height is one-fortieth of the height or width of the view surface (whichever is less). To change the character height, use command charheight with a size in mm.

6.6 Character Font

Character Font affects text only. Four fonts are available. The default font (1) is simple and is the fastest to draw; the others should only be used for presentation plots on a high-resolution device or laser printer. To change the character font, use command font n where n is a number 1..4 or the name of a font. It is also possible to change the font temporarily by using escape sequences (see: 7.4 Text).
   number    name
   ===============
     1       normal
     2       roman 
     3       italic
     4       script

6.7 Fill-Area Style

Fill-Area Style can be hollow (only the outline of the polygon is drawn), or solid. To change the Fill-Area Style, use command fastyle. The polygons that are filled are made by poly and rectangle.

7 PRIMITIVES

There are four different sorts of primitive: lines, graph-markers, text, and area fill. The previous chapter explained how to change the attributes of these primitives.

7.1 Clipping

The primitives are clipped at the edge of the viewport: any parts of the image that would appear outside the viewport are suppressed. The various primitives behave slightly differently. A line is clipped where it crosses the edge of the viewport. A graph marker is plotted if the center (the point marked) lies within or on the edge of the viewport; otherwise it is suppressed. Text, which is usually used for annotation, is not clipped (except at the edge of the view surface. A filled area is clipped at the edge of the viewport.

7.2 Lines

The two commands move x y and draw x y are the primitive plotting commands. move moves the plotter pen to a specified point without drawing a line (pen up). It has two arguments: the world coordinates of the required new pen position (or a position in mm when in mm mode). draw moves the plotter pen from its current position (defined by the last call of move or draw) to a new point, drawing a straight line as it goes (pen down).

7.3 Graph Markers

A Graph Marker is a symbol, such as a cross, dot, or circle, drawn on a graph to mark a specific point. Usually the symbol used will be chosen to be symmetrical with a well-defined center. Markers are plotted in several ways:

1) Move current pen position to the wanted position with move and use marker. Example:

   move * 10 16 47.99  * 45 46 59.9     ! a set must be defined
   marker

2) Plot markers at positions stored in an Ascii file on disk. The marker positions are not stored so the contents of xcolumn etc. is unchanged. Example:

   file pos.txt has contents:

   * 10 16 47.99  * 45 46 59.9
   * 10 16 43.22  * 45 48  9.8
   * 10 16 38.44  * 45 49 19.7 ! Last of the physical coordinates
   !back to grids
   80.3 56.7

   Plot markers with:      marker pos.txt

3) Read data in the columns xcolumn, ycolumn and use command 'points' Example:

   xcolumn radius.dat 1     !Read 1th  column from radius.dat in xcolumn 
   ycolumn radius.dat 2     !Read 2th  column from radius.dat in ycolumn  
   points                   !Plot the markers
The symbol that is used as a marker is selected with symbol.

7.4 Text

The Text primitive routine is used for writing labels and titles on the image. It converts an internal computer representation of the text (ASCII codes) into readable text. A command for writing text is text, which writes a character string with current justification (justific) and angle (angle) at a specific coordinate position.

For annotation of axes, you can use the commands xlabel, ylabel, axtitle and toplabel. All the text commands may include escape sequences in the text string to be plotted. These escape sequences are character sequences that are not plotted, but are interpreted as instructions to change fonts, to draw superscripts or subscripts, draw non-ASCII characters (eg. Greek letters), etc. All escape sequences start with a backslash character (\). The following escape sequences are defined (the letter following the \ may be either upper or lower case):

Some characters have a special meaning if entered at the COMMAND= prompt. One of these characters is for example the equals sign '='. Hermes sees everything after the '=' as a new keyword. You can escape these kind of characters with the back quote (`) character.

All text related commands (axtitle, text, toplabel, xlabel & ylabel) may include an expression that will be evaluated, formatted and included in the text. Expressions are enclosed between brackets '{}'. Between these brackets there can be either the expression eg. {PI/2.0} or a format string followed by a comma followed by an expression, eg. {f.fffff,PI/2.0}. The expressions may include any symbols and functions listed in: 4.2 List of functions (expressions for vectors & text), but the use of vectors is not allowed.

Example:

   move 122 -20
   text x runs from 0 to {f.fffff,PI/2.0}

The syntax for the format string is as follows:

Here is a table with some examples of a format string:
      format    | input      |  output      |           remarks
   ================================================================================
   +eeeeee.eeee | 43345.5436 |  +4.3346e+04 | exponential format, signed conversion
   gggg.ggggg   | 34.43      |     34.430   | field width is 10
   +ffff.ff     | 23.456     |   +23.46     | signed conversion
   -ffff        | 345.87     | 346          | left justified, integer format
   -+ffff.fff   | 34.43      | +34.430      | signed, left justified
   eee.eeee     | 234.43     |        *     | field width too small for conversion
   ffff.ff      | blank      |       b      | input was a blank

7.5 Area Fill

The area Fill primitive allows the user to shade the interior of an arbitrary polygonal region. The appearance is controlled by the attributes 'fill area style' (fastyle) and 'color index' (color or colour).

8 AXIS LABELS

8.1 Label axes with physical coordinates

Physical coordinates can be plotted along an axis if a GIPSY set is known to the system. A set is given with command inset. It can be a 1 or 2 dimensional structure (or higher a dimension for extracting profiles). Note that the command box is used to set the limits for the physical axes so if you use box for a ONE dimensional structure, it defines the limits (in world- or physical coordinates) for only one axis. The second axis gets its limits with yrange. The commands xrange and yrange use the world coordinate system and do not recognize physical coordinates.

A simple recipe to plot physical coordinates is:

  1. Select graphics device (GRDEVICE= or device)
  2. Open a GIPSY set (inset)
  3. Define limits (box)
  4. Draw the frame (frame)
In this case frame is in fact a (internal) macro with the commands:
   axis bp   ! draw bottom axis and label it with physical coordinates
   axtitle   ! plot the default title for the bottom axis
   axis lp   ! The same for the left axis
   axtitle   ! plot the default title for the left axis
   axis t    ! draw top axis without any labeling
   axis r    ! same for the right axis
An axis command must be completed with an indication in which one of the four possible orientations the axis must be plotted. GPLOT distinguishes the orientations: B(ottom), T(op), L(eft) and R(ight). If you entered:
   COMMAND=axis b
then the bottom axis will be plotted without any labeling or ticks. GPLOT knows where to plot this axis because a scale is known and the limits of the axes are defined (f.i. with box). Coordinate labels can be plotted if you supplied the axis command with character 'W' for world coordinates or 'P' for physical coordinates.
If you want to write the labels as an offset, include character 'O'.
The option 'F' is to force transformations according to FITS, i.e. coordinate transformations are done with CRVAL and CDELT only.
Option 'Z' plots the labels as 10**(World coordinate).
Default, the tick marks are plotted inside the frame and the labels corresponding with these marks are plotted outside the frame. But there are ways to change this. The options 'I' (from tIck) and 'A' (from lAbel) are followed by one or two digits. The first digit indicates whether a mark or label is plotted (digit != 0) or not (digit == 0) and the second digit indicates its position. Unequal to 0 stands for inside the frame and 0 stands for outside the frame. If you want to plot the lower horizontal axis with world coordinates, with the tick marks outside the frame and no labels, use:
   COMMAND=axis bwi10a0
Users are (almost) never satisfied with the default labeling. Therefore GPLOT provides a lot of control for this labeling. The step size for major ticks is controlled by axdelta. The first position to be labeled (contains most detailed position information) is set by axpos. The number of minor tick intervals (not number of ticks) is set by axminors. The format of the labels is given by axformat. For world coordinates you use formats like ffff.ff, but for physical coordinates along spatial axes, there are the dms.s, hms.s formats. GPLOT determines which part of the position information in the label is redundant and removes that part. But if somebody wants to write a certain part in every label, capitals can be used. For instance:
   COMMAND=axformat hMs
will always plot the minute information in a label.

For each kind of axis there is a suitable default. After the axis command, you can use the axtitle command to plot a title. Without argument, axtitle writes a default title at a suitable position near the last plotted axis. If an argument is supplied, this argument will be your title. For the exact syntax and options, use the help command.

8.2 Plotting a physical coordinate grid (extended ticks)

When the character 'e' is part of the axis command, the ticks will be extended until a border of the box is reached. To get a completely filled grid, use the 'e' option for all axis and make sure that you use the same axpos and axdelta for opposite axes. You can change the step size between positions with the cgstep command.

9 MISCELLANEOUS TECHNIQUES

9.1 OVERLAYS

9.1.1 Overlays in general

Suppose you want a gray scale plot of set 1 and contours of set 2 and the two sets have overlap in area:
  1. Create the gray scale plot first (For a hardcopy you can overlay contours over a gray scale plot but not vv.)
  2. Use inset command again to load a new set.
  3. You can select a new box at this point with box, or use command overbox to calculate a box for the overlay so that this overlay fits into the frame of your previous set. Note that overbox uses coordinate transformations. You have to check yourself whether rotation and projection are the same for both sets.
  4. Use command overlay on to adjust the scales etc.
  5. Draw contours of this second set.
For examples see : GPLOT recipes: A black and white panel

9.1.2 The colour plot with colour bar

A user has a two dimensional set of which he want a colour plot with contours and a separate colour bar at the right of the plot. GIDS must run and some colour lut must be available (f.i. display the set in a GIDS window and set up colours to your own taste). Note that GIDS is only used to adjust colours etc. and cannot be the hardcopy colour device that you have to select. For an example see: GPLOT recipes: Creating a simple colour plot

9.1.3 Overlays in GIDS

A displayed image in GIDS can have an overlay (f.i. with a frame) by selecting GIDS as device with the command device gids//append (the "append" is because you want to keep the original displayed image and not clear the current device). Use command gids after this to obtain all necessary info for scaling etc. If, however, you want a hardcopy of the result, you need an external screendump program. A better colour plot is made using the method as described in 9.1.2.

9.2 Plotting profiles

Suppose, you want a profile in frequency (velocity) direction extracted from the set n3198h has with axes RA, DEC, FREQ. Then the input can be:
  1. inset n3198h and with profile you are prompted to give: Profile from (RA1,DEC1,FREQ1) to (RA2,DEC2,FREQ2): (Keep RA1=RA2, DEC1=DEC2) The program will find out which axis is the profile axis.
  2. inset n3198h f 10:100 Because you entered a profile direction profile will prompt: Give position in (RA,DEC):
  3. inset n3198h ra 0 dec 0 You specified a profile in frequency direction. Command profile will prompt: Profile from (FREQ1) to (FREQ2):
A GPLOT definition of a profile is a plot of image values as function of position along a line. You always start with the input of your set (or subset). If your input has dimension n, then the line must be given as XY where X is (x1, x2,...xn) and Y is (y1, y2,....yn). You use the command profile for this. profile calculates the data along the line and profdatastores the values in xcolumn and ycolumn. The image values are always stored in ycolumn. If the profile is aligned to one of the subset axes then xcolumn will contain the GRIDS along this axis, else, xcolumn will contain the numbers 0 to number of points in profile minus one. See also:

9.3 Creating histograms

Histograms are made with commands histogram and histobin. histogram plots a histogram of UNBINNED data and uses 10 bins as default. If you want n number of bins, use histogram n. where n is greater than 0, but less than 200. The range set by command minmax, is divided into n equal bins. The height of each bin is determined by the program.

histobin plots a histogram of values with data in xcolumn along the ordinate, and data in ycolumn along the abscissa. Bin width is spacing between X values. If the xcolumn values denote the center of the bin, use histobin yes. If the xcolumn values denote the lower edge (in x) of the bin, use histobin no. The default value is yes. Here is an example of a histogram with binned data.

   xcolumn 1:1600        ! Position of center of the bin
   xrange 1 1600         ! Range in x values
   xscale 20             ! Scale in x
   ycolumn hallo.dat     ! Read the heights from file
   yrange 0 10
   yscale 0.2
   axis bw               ! Plot axes etc.
   axtitle intensity
   axis lw
   axtitle counts
   axis t
   axis r
   histobin yes          ! Plot the histogram. The x-values are the
                         ! center of the bin.

9.4 Polarisation vectors in plots

see:

10 RECIPES

11 GPLOT COMMAND DESCRIPTION


GIPSY