xmgr is an XY plotting tool for workstations or X-terminals using X. A few of its features are:
While xmgr has a convenient point-and-click interface, most parameter settings and operations are available through a command line interface (found in Files/Commands).
There are numerous popups accessible through Graphs pulldown menu that allow the manipulation of graph parameters. Most graph operations work on what is referred to as the `current graph', marked by small filled rectangles at the corners of one graph. The 10 graphs available by default in this version of xmgr are numbered from 0 to 9.
To install xmgr, refer to the document INSTALL found in the xmgr distribution. This will describe the details to successfully install xmgr.
For bug reports, comments, etc., send mail to the mailing list
acegr@admin.ogi.edu
As a last resort (don't expect an answer), send mail to
pturner@amb4.ccalmr.ogi.edu
The home of xmgr sources and documentation is ftp.ccalmr.ogi.edu [129.95.72.34] in CCALMR/pub/acegr.
The interactive xmgr program is called xmgr, if used in batch mode, grbatch. If grbatch is not found, contact your system administrator, or see the section on installation. For grbatch to work properly it is important that it be called grbatch as it is the name that distinguishes xmgr from grbatch. They are the same program, but when executed as grbatch, the X interface is not initialized and grbatch terminates at the end of execution without user intervention.
Please note that grbatch does not read the any X resource files, so that it can be run from dumb terminals and over phone lines. Don't expect resource settings used for xmgr to work for grbatch. See the section on setting defaults using a .xmgrrc file.
Example:
xmgr -autoscale x -p params.par data.datReads parameters from params.par and data from data.dat, but overrides any settings for the X axis found in the parameter file.
Example:
xmgr -arrange 2 2Creates a 2x2 matrix of graphs.
Example:
xmgr -device 2Sets the hardcopy device to PostScript portrait.
For example, to activate four graphs and read data to each graph:
xmgr -arrange 2 2 data0.dat -graph 1 data1.dat -graph 2 data2.dat -graph 3 data3.dat
This command creates 4 graphs arranged in a 2x2 matrix, and reads a file into each graph.
xmgr -netcdf t.nc -netcdfxy null y
Reads y from t.nc and loads to X the index (starting from 1).
xmgr -netcdf t.nc -netcdfxy x y -netcdfxy x1 y1
Reads x and y from t.nc, then x1 and y1 from the same file. 2 sets are created, both of type XY, one with (x, y), the other composed of (x1, y1). another example reading data from 2 CDF files:
xmgr -netcdf t.nc -netcdfxy x y -netcdf t2.nc -netcdfxy x1 y1
xmgr -wd examples mlo.dat -wd ../moredat brw.d hilo.datUnfortunately, this option not allow wild cards, as they are expanded in the current directory only.
xmgr -block block.d -bxy 1:4 -bxy 2:6will read block.d and generate 2 sets of type XY using columns 1 and 4 for the first set, and 2 and 6 for the second set.
xmgr -block block.d -type xydy -bxy 1:3:4will read block.d and generate a set of type XYDY (an XY set with error bars) using column 1 and 3 for X and Y, and column 4 for the error bars.
Read the parameter file parameter_file.
xmgr -maxcolors 18 -pexec "cmap 17,255,0,255"Sets the maximum number of colors to 18 and sets color 17 to cyan. Colors 0-15 are set to the defaults, color 16 is undefined (the actual color will vary).
The source setting stays in effect until the next -source command is given.
On startup xmgr will look for a .xmgrrc file in the users' home directory allowing changes to the default behavior of xmgr. The construction of the xmgr default file is the same as for a parameter file.
Use GXinvert to draw rubberband lines and the graph focus markers if this resource is set to True.
A boolean resource used to exchange the color indices for black and white.
Set the number of sets per graph.
Set the number of graphs.
Set the number of colors allocated. There is no support in the graphical portion of the user interface for more than 16.
Applies to the Pick set operations and allows an opportunity to accept or cancel any operation performed.
When Yes, allow double clicks on the canvas to bring up various popups depending on the location of the pointer when the double click occurs. Double clicking to the right of a graph brings up the View/Ticks popup set to the Y-axis, below the graph brings up the View/Ticks popup set to the X-axis, inside the graph brings up the files popup if no sets are active or the View/Symbols popup set to the set nearest the pointer. Double clicking above the graph brings up the View/Title-subtitle popup, to the right of the graph, the View/Legend popup.
The command line option to set this resource is -dc or -nodc.
When this resource is Yes or True, allow autoscaling to occur each time a set is read from the File/Read sets popup.
Have xmgr handle backing store if the server doesn't.
The command line option for this is -bs or -nobs.
Set the location of xmgr. This will be where help files, auxillary programs, and examples are located. If you are unable to find the location of this directory, contact your system administrator.
Set the command string to use for spooling to a PostScript printer. The default (unless changed during the build process) is "lpr -h".
Set the command string to use for printing the FrameMaker .mif format. The default (unless changed during the build process) is "cat >acegr.mif < ", i.e., output is to a file.
Set the command string to use for spooling to an HPGL capable printer or plotter.
Select the hardcopy device.
The device numbering is as follows:
Set the name of the editor to use in Data/Edit-Create set. The default is vi.
Executing xmgr as grbatch suppresses the initialization of the graphical user interface and allows hardcopy plots to be made without intervention.
Read data from disk or pipes, read variables from netCDF or HDF files, read and write plot parameters, read block data, write one or more xmgr datasets, set the current working directory, set the printer options, print (hardcopy), access the command line interpreter, describe the status of data sets, graphs and regions, and display results of computations and other operations.
Read one or more data sets. The list item at the top of the popup displays
the contents of the current directory. Select a file or directory by clicking
on the item with the right mouse button. The selection is placed in the text
item labeled `File:' and checked to see if it is a directory or a file.
Selecting a directory causes xmgr to change to the new directory and
reload the file list with the contents of the new directory. Selecting a
file does nothing until the `Accept' button is pressed or
There are 4 cases for the error bars' position with respect to the datum:
Read from: sets the source of the data, either a disk file or a pipe.
In the case of a pipe, the information provided by the file filter item is
not used, as the `file' in this case will be a command as typed at the
UNIX prompt.
Read to graph: selects a particular graph to serve as the repository
for the incoming data. The `Current' graph is the graph that has the focus,
and can be any of the available graphs. If you aren't sure which graph is
current, the locator item on the main panel displays the current graph number.
Selecting Autoscale on read: forces an autoscale of the target graph
each time a set is read.
Note: Data are read into the next available set. All data are assumed
to be delimited by tabs or blanks.
For the xy, xydx, xydy, xydxdx, xydydy, xydxdy, xyz, xyr data file formats,
sets are separated by a line containing non-numeric characters, that are
neither comment lines (lines with a '#' in column 1) nor parameter lines
(lines beginning with an `@'). Data files can have imbedded comments by
placing a `#' in the first column of the comment line. Plot parameters can
be set by placing a `@' in the first column of the line followed immediately
by the parameter name and setting. See the command line reference for a
description of plot parameters and other commands that may be placed in a
data file using the `@' character. Comment lines and parameter lines can
occur at any place in the data file, and are not used to indicate data set
separators. I recommend a single `&' on a line to use as a data set separator.
Press Accept to read the data. If the read was successful, the graph
of the data is drawn using the current plot scaling parameters. If the data
lies outside the current plotting limits, the new set(s) will not be visible
until the plotting limits are changed by autoscaling or manually through
the View/Define world popup.
Press Cancel to close the popup.
Open the Status popup to get information on the state of sets. If reading
the file generates more than 10 errors you'll be prompted by an alert requesting whether or not
you'd like to continue. These errors generally arise when an attempt is made to read a
text file - xmgr relies on the interpretive capabilities of sscanf() to parse the data.
xmgr will read data sets until there are no more sets available, after the maximum
number of sets have been used, you'll need to free some sets using the [Kill] or [Kill all]
items in the Edit/Set operations pullright.
File/Read netCDF
Select X: Select Y:
netCDF file:
Load to set:
Autoscale on read
Accept Files... Update Query Done
---------------------------------------
Enter the name of the netCDF file in the text item labelled
netCDF file: then click on "Update" (note that if -netcdf
[filename] was used on the command line, this step is not
needed, as the lists will be loaded automatically). This will
read the names of all one dimensional variables into the
two scrolled lists. The leftmost list is for X and the
rightmost for Y. There is an additional item in the X
list called INDEX (I'm hoping here that no one names a
variable INDEX, maybe I need to change this) that indicates
that for X, use the index of the Y variable (numbering
starts from 1).
Select on a variable from the X list to use for X and select
a variable from the Y list (only single selections for now).
If information about the selected variables is desired, click on
Query.
Select a set using "Load to set:" - the default is to load
to the next available set.
If things look OK, click on Accept to read the data and load
the set. Use "Autoscale on read" to set/unset autoscaling
after a successful read.
To read data from a new CDF file, enter the filename, or use
File... to scan the directory. Click on Update to freshenup
the X and Y selection lists.
Note: Presently, only sets of type XY are created.
Note: xmgr scans and replaces commas with blanks and the `D' in Fortran double
precision exponential formats with `e'.
Enter the parameter file name on the line labeled "File:", press "Accept" to read a saved
state of adjustable parameters, legends, strings, etc, to the graph selected by the `Read to
graph' cycle. As the graph number is saved in the parameter file this isn't used at the
present time.
Select the data source, either Disk or Pipe and enter the block data file name in the text
item labeled "File:" to read a data set in block data file format. The
block data file format consists of columns of data. For example,
the following is a block data file consisting of 4 columns:
After reading the file of block data, the popup will close if no errors were found, and the
Edit/Block data popup will take its place. Use the functions in the Edit/Block data
popup to create sets from the block data.
NOTE: All items are assumed delimited by spaces or tabs. There is presently a 30 column limit. Only one set of block data per session, i.e., reading another set of block data
will obliterate the previous set of block data.
Write one or all sets to disk. Select the set to write using the cycle displaying the set
numbers (there is an item for selecting all active sets). The item denoted "Format" is the
C language format string that will be used to format the data for output - the default
should work well for most cases. Enter the file name on the line labeled "File:" and
press the button marked [Accept], to write the data. The item, `Imbed parameters,'
causes xmgr to write not only the data, but the parameters describing the graph or
graphs as well.
A complete dump of the contents of xmgr may be accomplished by selecting all sets,
imbed parameters, and all active graphs. The file generated this way can then be read as
a normal data file, and should recreate the originating environment.
Select the graph from which to save the parameters. This can be the current graph, any
particular graph, or all active graphs. Enter the parameter file name on the line labeled
"Write parameters to", press "Accept" to write the current state of adjustable parameters, legends, strings, etc. A prompt will appear if the action would overwrite an existing
file. allowing the operation to be cancelled.
Perform a `Write sets' using all active sets, all active graphs, and imbed parameters. Use
this to save the current session.
Kill all sets, graphs, and annotative text, lines, and boxes. After performing this action,
it will be necessary to activate a graph using View/Graphs/Activate graphs.
Generate a hardcopy of the current plot on the device specified in the File/Printer setup
popup.
Set the hardcopy device parameters. Select the device, where to print (either the printer
or a file), and the string to use as a spooling command for the print job, or file name if
output is directed to disk. Click on the `Accept' button to make the selections above current, or `Done' to close the popup and cancel the operation. If the selection is accepted,
the next time File/Print is selected, hardcopy output will be to the selected device. Click
on the `Print' button to accept the settings and print a hardcopy.
Command driven version of the interface to xmgr. Here, commands are typed at the
`Command:' text item and executed when
Display the results of the regression routine and the output of the `Write' button in File/
Status in the monitor window.
Click on the Exit button to terminate the session with xmgr.
Create sets from block data. Select the type of set and the columns to use for each vector
of the new set. Press Accept to create the set. Note that reading block data does not
affect the scaling of the graph so when a set is created using this popup, the set may not
appear within the graph's scaling limits - use AS (Autoscale) to set the scale of the
graph if needed (or use View/Define world).
When the pointer focus is on the canvas (where the graph is drawn), there
are some shortcuts to activate several actions. They are:
To change fonts within a string preceed the font number listed below by a backslash. To
turn subscripting or superscripting on or off use \s for subscripts and \S for superscripting. Font selection is current for the remainder of the string or until the next font change.
Subscripts and superscripts remain for the remainder of the string or until \N is seen. To
print a backslash use \\. To backspace use \b. To begin underlining use \u, to stop underlining use \U. \+ increases the size of the characters and \- decreases the size of the characters.
xmgr uses the Hershey fonts to draw text on the screen, but PostScript fonts for hardcopy. There are discrepancies between the two sets of fonts and of this writing, there are
problems with the mapping of Greek and special characters.
Font # Font
Summary of other special commands
Example:
\0F\sX\N(\8e\0) = sin(\8e\0)*e\S(-X)\N*cos(\8e\0)
prints roughly FX(e) = sin(e)*e -X*cos(e)
using font 0 and e prints as epsilon from the Simplex Greek font.
NOTE:
Special characters are mapped to the keyboard, the present mapping is not very well
organized and may change.
Read netCDF
Read parameters
Read block data
1 2 3 4 5
6 7 8 9 10
11 12 13 14 15
Write sets
Write parameters
Save all
Clear all
Print
Printer setup
Command interpreter
Results
Exit
Block data
Hot keys
Fonts
Changing fonts within a string