The GPLOT User guide
CONTENTS
1 INTRODUCTION
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:
- The start position of the label which is plotted first (the label
containing the most complete coordinate information) can be preset.
- Values for the step size (distance between major ticks) and the number
of minor intervals can be chosen.
- You can specify a format for the coordinate labels.
- Coordinates can be plotted as world coordinates (also called grids),
or as physical coordinates (if a GIPSY set is specified).
- Ticks can be extended and connected to form a grid overlay.
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.
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:
- 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.
- Number of subdivisions of the view surface in X direction.
- 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.
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)
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.
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.
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
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).
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?.
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.
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
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:
- Create with your editor the file rotcur.mac
- or start writing the macro with: edit rotcur
- 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
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:
- The name of a non-active macro, to delete that macro
- 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
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:
- A valid GIPSY expression for an array of floating point numbers, see
also
Number Input
- Filename and column number (non standard)
- A legal mathematical expression containing the names of other
vectors
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
|
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.
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.
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
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.
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:
- 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.
- 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.
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).
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
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:
- Color Index (colour, color)
- Line Style (lstyle)
- Line Width (lwidth)
- Character Height: (charheight)
- Character Font: (font)
- Fill-area Style: (fastyle)
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.
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
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
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.
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.
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
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.
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.
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).
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.
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):
- \u -- start a superscript, or end a subscript;
- \d -- start a subscript, or end a superscript (note that
\u and \d must always be used in pairs);
- \b -- backspace (\ie, do not advance text pointer after
plotting the previous character);
- \\ -- backslash character (\);
- \A -- Angstrom symbol;
- \gx -- greek letter corresponding to roman letter x;
- \fn -- switch to Normal font (1);
- \fr -- switch to Roman font (2);
- \fi -- switch to Italic font (3);
- \fs -- switch to Script font (4);
- \(nnnn) -- character number n (1 to 4 decimal digits);
the closing parenthesis may be omitted if the next character is neither
a digit nor ')'. This makes a number of special characters (eg,
mathematical, musical, astronomical, and cartographical symbols)
available.
See GIPSY Recipes book: Hershey symbols
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:
- flag(s)
- Zero or more flags, in any order, which modify the
meaning of the conversion specification. The flag
characters and their meanings are:
- - The result of the conversion is left-
justified within the field.
- + The result of a signed conversion always
begins with a sign, "+" or "-".
- string
- Characters, some with special meaning.
If the string (f.i. FFFFF.FF or gggg.gg or wwwww)
contains no dot, the number of characters specify
a minimum field width. For an output field, if the
converted value has fewer characters than the field
width, it is padded on the left (or right, if the
left-adjustment flag, - has been given) to the field
width.
If the string contains a dot, the total number of
characters including the dot is the minimum field width
and the number of characters after the dot is the
precision.
The characters are used to determine the conversion
type. If the string contains an:
- 'e' or 'E'
The floating-point-number argument is
printed in the style [-]drddde+dd,
where there is one digit before the
radix character, and the number of
digits after it is equal to the
precision. The E conversion character
produces a number with E introducing
the exponent instead of e. The
exponent always contains at least two
digits. However, if the value to be
printed requires an exponent greater
than two digits, additional exponent
digits are printed as necessary.
- 'g' or 'G'
The floating-point-number argument is
printed in style f or e (or int style E
n the case of a G conversion
character), with the precision
specifying the number of significant
digits. The style used depends on the
value converted; style e is used only
if the exponent resulting from the
conversion is less than -4 or greater
than or equal to the precision.
- others
Strings without 'e', 'E', 'g' and 'G'
indicate a floating point conversion.
The floating point number argument is
printed in decimal notation in the
style [-]dddrddd, where the number of
digits after the radix character, r, is
equal to the precision specification.
- If the result of a conversion is longer than the
field width, an asterisk is returned. If the
input number is a blank, a 'b' is returned.
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
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
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:
- Select graphics device (GRDEVICE= or device)
- Open a GIPSY set (inset)
- Define limits (box)
- 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
- (b = Orientation is bottom)
- (w = World coordinates (grids) only, no physical labels)
- (i10 = plot tick marks, outside frame)
- (a0 = do not plot any labels)
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.
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
Suppose you want a gray scale plot of set 1 and contours of set 2
and the two sets have overlap in area:
- Create the gray scale plot first (For a hardcopy you can overlay
contours over a gray scale plot but not vv.)
- Use inset command again to load a new set.
- 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.
- Use command overlay on to adjust the scales etc.
- Draw contours of this second set.
For examples see :
GPLOT recipes: A black and white panel
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
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.
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:
- 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.
- inset n3198h f 10:100
Because you entered a profile direction profile will prompt:
Give position in (RA,DEC):
- 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:
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.
see:
