Using xmgr

Execution

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.


Command line parameters

-autoscale x or y or xy
Autoscale the x axis, y axis, or both axes, overriding the settings for axes scaling and tick mark spacing given in any parameter file specified by the -p option.

Example:

xmgr -autoscale x -p params.par data.dat
Reads parameters from params.par and data from data.dat, but overrides any settings for the X axis found in the parameter file.
-noauto y or y or xy
Suppress autoscaling on the given axis (axes). Use this when a data file has embedded commands that provide axes scaling and tick mark spacing.
-arrange rows columns
Arrange graphs in column major order starting from the lower left corner in a grid rows by columns. For example, -arrange 2 2 will position the first four graphs (0, 1, 2, 3) in a 2x2 matrix of graphs starting with graph 0 in the lower left corner of the plotting surface. This function is not as complete as the similar function found in Graph/Graph operations/Arrange and gives a sightly different result.

Example:

xmgr -arrange 2 2
Creates a 2x2 matrix of graphs.
-rows rows
Arrange the first rows graphs in rows rows.
-cols columns
Arrange the first columns graphs in columns columns.
-results results_file
Write the results of regression and anything else that gets written to the results popup to file results_file.
-device device_number
Set the hardcopy device to device_number. The device numbering follows:

Example:

xmgr -device 2
Sets the hardcopy device to PostScript portrait.
-eps
Tell the PostScript driver to produce EPS.
-printfile graphics_output_file
Write the graphics output to file graphics_output_file rather than spool graphics data to a printer.
-fixed width height
-portrait
-landscape
-free
Set the dimensions of the drawing area. Presently, there is no connection between the hardcopy drivers and these settings. This means that the printer needs to be set to conform to the dimensions of the drawing area.
-batch batch_file
Execute the commands in batch_file on startup. This command line switch is not the same as executing xmgr in batch mode as grbatch.

-noask
Assume the answer is yes to all requests, This means that files will be overwritten without asking if they exist, and, if Exit is selected in the GUI, xmgr will exit abruptly. This option can be used to overwrite existing files in batch mode. Be careful.

-graph graph_number
Make graph_number the current graph. Graph_number is an integer between 0 and maxgraph-1 (by default maxgraph, the maximum number of graphs, is 10).

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.

-graphtype graph_type
Set the current graph type to graph_type. Where graph_type is one of:

-type data_set_type
The format of the next data source is data_set_type. Where data_set_type is one of xydx (XY data with error bars along X), xydy (XY data with error bars along Y), xydxdx (XY data with error bars along X of differing values), xydydy (XY data with error bars along Y of differing values), xydxdy (error bars along X and Y), xyr (a circle drawn at XY of radius R) and xyhilo (XY data with high-low open-close data). This setting remains in effect until a new format type is specified.
-ihl IHL_formatted_file
Assume IHL_formatted_file or the next source of data is in IHL format (a local format).

-nxy
The format of the next data source is X1, Y1, Y2, ..., Yn.

-xydx
The format of the next data source is X Y DX

-xydy
The format of the next data source is X Y DY

-xydxdx
The format of the next data source is X Y DX1 DX2

-xydydy
The format of the next data source is X Y DY1 DY2

-xydxdy
The format of the next data source is X Y DX DY

-xyz
The format of the next data source is X Y Z where Z is a value drawn as text at X, Y.

-xyr
The format of the next data source is X Y R, where a circle of radius R is drawn at X, Y.

-xybox
The format of the next data source is XMIN YMIN XMAX YMAX VALUE, where (XMIN, YMIN) is the lower left-hand corner of a rectangle and (XMAX, YMAX) are the upper right-hand corner of a rectangle. VALUE is an integer used to specify the color to use to fill the rectangle. To set the fill, use Graph/Symbols and set the fill style to anything but None.
-boxplot
The format of the next data source is X AVG

-ihl
The format of the next data source is in IHL format, this format leads to a data set of type XY.

-hilo
The format of the next data source is X HIGH LOW OPEN CLOSE, where a symbol denoting the open, close, the high and the low values for an observation is drawn at X.

-netcdf netCDF file
-netcdfxy [xvar or "null"] yvar
Where xvar and yvar are the names of the variables to read. if xvar == "null", then load the index of yvar. These command line options may be used to read variables from a netCDF file. For example:

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

-saveall filename
Write all active sets to filename.

-wd
Set the current working directory. This option can be used to read files from several different directories. For example:

xmgr -wd examples mlo.dat -wd ../moredat brw.d hilo.dat
Unfortunately, this option not allow wild cards, as they are expanded in the current directory only.

-image X_window_dump_file
Read the window dump file X_window_dump_file. The format is the same as generated by xwd or Frame's capture utility.

-imagexy X Y
Set the upper left-hand corner position of the image at screen coordinates (X, Y). Note that screen coordinates have as their origin the upper left-hand corner of the drawing area and positive, increasing Y points down.

-block
Assume the format of the next data file is block data. No sets are formed by reading block data, and only one set of block data is allowed in an active session. To create sets from the block data, use Edit/Block data.

-bxy col1:col2
Create sets from a previously read block data. Using -bxy col1:col2, will create a set using the current set type (default is XY) and using column col1 and column col2 from the most recently read set of block data. Col1 and col2 are integers indicating the numbers of the columns - column numbers start from 1. For example:
  xmgr -block block.d -bxy 1:4 -bxy 2:6
will 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:4
will 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.

-log x or y or xy
Set the current graph type to logarithmic depending the the string x or y or both axes by xy.

-parameter parameter_file
-p parameter_file

Read the parameter file parameter_file.

-pexec parameter_string
Interpret parameter_string as a parameter setting.

-result result_file
Write results from regression to result_file

-rvideo
Exchange the color indices for black and white.

-mono
Limit colors to black and white, affects the display only.

-dc
Allow double click canvas operations, overriding any application default setting.

-nodc
Disallow double click canvas operations.

-redraw
Redraw the entire page if xmgr receives an Expose event.

-noredraw
Do not redraw the entire page when Expose events are received.

-statusredraw
Redraw the entire page after each command in the status window.

-nostatusredraw
Do not redraw the entire page after each command in the status window.

-maxcolors number_of_colors
Set the maximum number of colors allocated. For example:
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).

-freecolors
Attempt to free colors which are assigned a different colormap entry. See -nofreecolors below. This is the default behavior.

-nofreecolors
Doesn't attempt to free colors which are assigned a different colormap entry. Use this if one of the colors you use is the same as one of the button or border colors and you subsequently change that color. This shouldn't be a problem unless you're really unlucky. Using this switch can cause you to eat up all the colors in your colormap if you change colors a lot during a session. This is equivalent to setting the X resource XMgr.freeColors to false.

-world xmin ymin xmax ymax
Set the scaling of the axes for the current graph. The X axis will run from (xmin, xmax) the Y axis from (ymin, ymax)

-view xmin ymin xmax ymax
Set the viewport of the current graph to a rectangle described by (xmin, ymin) and (xmax, ymax).

-source data_source
Set source for the next data file, the argument takes on the following values:

The source setting stays in effect until the next -source command is given.

-pipe
Read from standard input and plot each set when the end of the set is seen. Use the -pipe option to monitor the results coming from a model or other data stream.

-npipe
Read data from named pipe. This option can be used to display data in real-time, but in contrast with the simple pipe option, xmgr's graphic user interface remains responsive to your actions while displaying the data.

-remove
Erase the most recently read file. Use this option when using xmgr to read a temporarily constructed file that is not needed once read. Note that this option does not request confirmation.

-legend load
For each data set read, make the set legend label the same as the filename the data set originated.

-seed seed_value
Initialize the random number generator using seed seed_value. This value is used in a call to the math library function srand48().

-GXinvert
-GXxor
GXinvert and GXxor set the type of graphics operation used to draw rubberband lines and draw the graph focus markers. In a color-mapped display, the xor of a source and destination pixel may not generate a color visible on the drawing area. The default is to use xor to draw rubberband lines, if the lines don't show, try -GXinvert. This draw mode can be set via X resource settings (see below).

-maxsets number_of_sets
Set the maximum number of data sets per graph. Number_of_sets must be greater than 30. If -maxsets is used in conjunction with -maxgraph, then the -maxsets setting must precede the -maxgraph setting.

-maxgraph number_of_graphs
Set the maximum number of graphs per session. Number_of_graphs must be greater than 10. If -maxgraph is used in conjunction with -maxsets, then -maxsets must precede the use of -maxgraph.

-maxboxes number_of_boxes
Set the maximum number of boxes.

-maxstr number_of_strings
Set the maximum number of strings.

-maxlines number_of_lines
Set the maximum number of lines.

-nonl
Activate the Non-linear curve fitting module. WARNING, this module is a prototype and should not be used for analysis.

-digit
Activate the Digitizing module. WARNING, this module is a prototype and should not be used for analysis.

-usage
Display a brief explanation of command line settings

data_files
The files or commands in the case of a pipe from which data are read.

Setting xmgr defaults

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.


Setting xmgr X defaults

The following X resource settings are supported:

It is also possible to customize menus by assigning key accelerators to any item.
The list below describes the menu labels and related X resources. For example, in order to make xmgr popup the Non-linear curve fitting by pressing Control+F, you would add the following two lines

XMgr*transformationsMenu.nonLinearFit.acceleratorText: Ctrl+F
XMgr*transformationsMenu.nonLinearFit.accelerator: Ctrl<Key>f

to your .Xresources file (the file which is read when an X session starts; it could be .Xdefaults, .Xsession or some other file - ask your system administrator when in doubt).


Environment variables


Batch printing

Executing xmgr as grbatch suppresses the initialization of the graphical user interface and allows hardcopy plots to be made without intervention.


PSTeX format

PSTeX format is a way to combine Postscript output with LaTeX's superior mathematical formatting ability and symbol set. PSTeX format produces 2 files, an encapsulated Postscript file and a LaTeX file which has the commands to read in the EPS file and superimpose on top of it any text you want formatted by LaTeX.

Any text beginning with the sequence "\L" is assumed to be a LaTeX command and will not be present in the EPS file. The EPS file will have the suffix ".pstex" while the suffix for a LaTeX included file is ".pstex_t" and for a complete LaTeX file is ".tex". An included file is meant to be read into a LaTeX document by the "\input" LaTeX command while a complete file may be processed by LaTeX as is. The PSTeX portrait and landscape devices produce complete files in the appropriate orientation. The file produced by the include device is always in a portrait orientation and it is a trivial matter to rotate the graph if desired by the file which reads in the ".pstex_t" file.

Note: This format may only be written to a file as it must be further processed and may not be sent directly to the printer.

If a legend label contains LaTeX code, the legend width must be selected manually through the "Legends" popup as xmgr does not process LaTeX commands and cannot determine the width of the output of such.

The LaTeX package "graphics" is required or another one with similar functionality.