Xmgr: usage

# 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:
  - 1 .. PostScript landscape
  - 2 .. PostScript portrait
  - 3 .. FrameMaker .mif landscape
  - 4 .. FrameMaker .mif portrait
  - 5 .. HPGL landscape
  - 6 .. HPGL portrait
  - 7 .. InterLeaf landscape
  - 8 .. InterLeaf portrait
  - 9 .. PSTeX include
  - 10 .. PSTeX landscape
  - 11 .. PSTeX portrait

  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.
  - -free - allow the drawing area to be resized (no scrollbars will appear).
  - -fixed width height - set the drawing area to have dimensions width and height
  - -portrait - set the drawing area to be 8.5x11 in portrait.
  - -landscape - set the drawing area to be 8.5x11 in landscape.
-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:

  - xy linear scaling along both x and y.
  - logx linear scaling in y, log scaling in x.,
  - logy linear scaling in x, log scaling in y.
  - logxy log scaling in both x and y.
  - bar vertical bar chart.
  - hbar horizontal bar chart.
  - stackedbar vertical stacked bar chart.
  - stackedhbar horizontal stacked bar chart.
-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:

  - disk - Data file is on disk.
  - pipe - Read from a pipe.
  - stdin - xmgr is in a pipe, read from standard input.

  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:

- XMgr.invertDraw: False

  Use GXinvert to draw rubberband lines and the graph focus markers if this resource is set to True.

- XMgr.reverseVideo: False

  A boolean resource used to exchange the color indices for black and white.

- XMgr.maxSets: 30

  Set the number of sets per graph.

- XMgr.maxGraphs: 10

  Set the number of graphs.

- XMgr.maxColors: 17

  Set the number of colors allocated. There is no support in the graphical portion of the user interface for more than 16.

- XMgr.verifyAction: No

  Applies to the Pick set operations and allows an opportunity to accept or cancel any operation performed.

- XMgr.allowDoubleClick: Yes

  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.

- XMgr.autoscaleOnRead: No

  When this resource is Yes or True, allow autoscaling to occur each time a set is read from the File/Read sets popup.

- XMgr.backingstore: No

  Have xmgr handle backing store if the server doesn't.

  The command line option for this is -bs or -nobs.

- XMgr.freeColors: True

  See documentation for the command line option `-nofreecolors`. Using that command line switch is equivalent to setting this resource to false.

- XMgr.tearOffModel: XmTEAR_OFF_ENABLED

  Regulates whether pulldown menus have the tear-off behavior

- XMgr.allowRedraw: Yes

  Controls whether or not xmgr redraws its canvas after each operation. The corresponding command line options are -redraw and -noredraw.

- XMgr.allowStatusRedraw: Yes

  Controls whether or not xmgr redraws its canvas after each set operation in the status window. This takes effect only if allowStatusRedraw is on. The corresponding command line options are -statusredraw and -nostatusredraw.

- XMgr.noAsk: No

  Controls whether or not xmgr generates a warning before overwriting existing files. The corresponding command line option is -noask.

- XMgr.logWindow: No

  Controls whether or not xmgr opens the log window on startup. The corresponding command line options are -logwindow and -nologwindow.

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).

- XMgr*fileMenu.open Open...
- XMgr*fileMenu.save Save
- XMgr*fileMenu.saveAs Save as...
- XMgr*fileMenu.describe Describe...
  - XMgr*readMenu.sets Sets...
  - XMgr*readMenu.netCDF NetCDF...
  - XMgr*readMenu.parameters Parameters...
  - XMgr*readMenu.blockData Block data...
  - XMgr*readMenu.image Image...
  - XMgr*writeMenu.sets Sets...
  - XMgr*writeMenu.parameters Parameters...
- XMgr*fileMenu.clearAll Clear all
- XMgr*fileMenu.print Print
- XMgr*fileMenu.printerSetup Printer setup...
- XMgr*fileMenu.exit Exit

- XMgr*dataMenu.status Status...
- XMgr*dataMenu.results Results...
- XMgr*dataMenu.commands Commands...
  - XMgr*transformationsMenu.evaluateExpression Evaluate expression...
  - XMgr*transformationsMenu.loadValues Load values...
  - XMgr*transformationsMenu.loadEvaluate Load & evaluate...
  - XMgr*transformationsMenu.histograms Histograms...
  - XMgr*transformationsMenu.fourierTransforms Fourier transforms...
  - XMgr*transformationsMenu.runningAverages Running averages...
  - XMgr*transformationsMenu.regression Regression...
  - XMgr*transformationsMenu.nonLinearFit Non-linear curve fitting...
  - XMgr*transformationsMenu.differences Differences...
  - XMgr*transformationsMenu.seasonalDifferences Seasonal differences...
  - XMgr*transformationsMenu.integration Integration...
  - XMgr*transformationsMenu.correlation Cross/auto correlation...
  - XMgr*transformationsMenu.interpolation Interpolation...
  - XMgr*transformationsMenu.splines Splines...
  - XMgr*transformationsMenu.samplePoints Sample points...
  - XMgr*transformationsMenu.pruneData Prune data...
  - XMgr*transformationsMenu.digitalFilter Digital filter...
  - XMgr*transformationsMenu.linearConvolution Linear convolution...
  - XMgr*transformationsMenu.geometricTransforms Geometric transforms...
  - XMgr*transformationsMenu.featureExtraction Feature extraction...
- XMgr*dataMenu.pointOperations Point operations...
  - XMgr*setOperationsMenu.pickOperations Pick operations...
  - XMgr*setOperationsMenu.activate Activate...
  - XMgr*setOperationsMenu.deactivate De-activate...
  - XMgr*setOperationsMenu.reactivate Re-activate...
  - XMgr*setOperationsMenu.setLength Set length...
  - XMgr*setOperationsMenu.changeType Set type...
  - XMgr*setOperationsMenu.copy Copy...
  - XMgr*setOperationsMenu.move Move...
  - XMgr*setOperationsMenu.dropPoints Drop points...
  - XMgr*setOperationsMenu.join Join...
  - XMgr*setOperationsMenu.split Split...
  - XMgr*setOperationsMenu.kill Kill...
  - XMgr*setOperationsMenu.killAll Kill all
  - XMgr*setOperationsMenu.Sort Sort...
  - XMgr*setOperationsMenu.reverse Reverse...
  - XMgr*setOperationsMenu.coalesce Coalesce...
  - XMgr*setOperationsMenu.swap Swap...
  - XMgr*setOperationsMenu.pack Pack...
- XMgr*transformationsMenu.editCreateSet Edit/create set...
  - XMgr*regionOpearationsMenu.define Define...
  - XMgr*regionOpearationsMenu.evaluate Evaluate...
  - XMgr*regionOpearationsMenu.clear Clear...
  - XMgr*regionOpearationsMenu.extractPoints Extract points...
  - XMgr*regionOpearationsMenu.extractSets Extract sets...
  - XMgr*regionOpearationsMenu.deletePoints Delete points...
  - XMgr*regionOpearationsMenu.killSets Kill sets...
  - XMgr*regionOpearationsMenu.reportOn Report on...
  - XMgr*regionOpearationsMenu.areaPerimeter Area/perimeter...
  - XMgr*graphOperationsMenu.activate Activate...
  - XMgr*graphOperationsMenu.copy Copy...
  - XMgr*graphOperationsMenu.swap Swap...
  - XMgr*graphOperationsMenu.kill Kill...
  - XMgr*graphOperationsMenu.focus Focus...
  - XMgr*graphOperationsMenu.show Show...
  - XMgr*graphOperationsMenu.setType Set type...
  - XMgr*graphOperationsMenu.arrange Arrange...
  - XMgr*graphOperationsMenu.overlay Overlay...
  - XMgr*graphOperationsMenu.invertFlipAxes Invert/flip axes...
- XMgr*transformationsMenu.blockData Block data...
- XMgr*transformationsMenu.hotLinks Hot links...

- XMgr*plotMenu.worldScaling World scaling...
- XMgr*plotMenu.viewport Viewport...
- XMgr*plotMenu.autoscale Autoscale...
- XMgr*plotMenu.titles Titles...
- XMgr*plotMenu.tickLabelsMarks Tick labels/tick marks...
- XMgr*plotMenu.frame Frame...
- XMgr*plotMenu.symbols Symbols...
- XMgr*plotMenu.errorBars Error bars...
- XMgr*plotMenu.legends Legends...
- XMgr*plotMenu.stringsThings Strings & things...
- XMgr*plotMenu.timeStamp Time stamp...

- XMgr*optionsMenu.page Page...
  - XMgr*viewMenu.locatorBar Locator bar
  - XMgr*viewMenu.statusBar Status bar
  - XMgr*viewMenu.toolBar Tool bar
  - XMgr*viewMenu.setLocatorFixedPoint Set locator fixed point
  - XMgr*viewMenu.clearLocatorFixedPoint Clear locator fixed point
  - XMgr*viewMenu.locatorProps Locator props...
- XMgr*optionsMenu.draw Draw...
- XMgr*optionsMenu.workingDirectory Working directory...
- XMgr*optionsMenu.misc Misc...

- XMgr*helpMenu.onContext On context
- XMgr*helpMenu.userGiude User Guide
- XMgr*helpMenu.faq FAQ
- XMgr*helpMenu.changes Changes
- XMgr*helpMenu.comments Comments
- XMgr*helpMenu.about About...

## Environment variables

- GR_HOME

  Set the location of xmgr. This will be where help files, auxiliary programs, and examples are located. If you are unable to find the location of this directory, contact your system administrator.

- GR_PS_PRSTR

  Set the command string to use for spooling to a PostScript printer. The default (unless changed during the build process) is "lpr -h".

- GR_MIF_PRSTR

  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.

- GR_HPGL_PRSTR

  Set the command string to use for spooling to an HPGL capable printer or plotter.

- GR_HDEV

  Select the hardcopy device.

  The device numbering is as follows:

  - 1. PostScript landscape
  - 2. PostScript portrait
  - 3. FrameMaker interchange format (.mif) landscape
  - 4. FrameMaker interchange format (.mif) portrait.
  - 5. HPGL landscape
  - 6. HPGL portrait
  - 7. Interleaf landscape
  - 8. Interleaf portrait
  - 9. PSTeX include
  - 10. PSTeX landscape
  - 11. PSTeX portrait

- GR_EDITOR

  Set the name of the editor to use in Data/Edit-Create set. If the editor must run in a terminal, the terminal must explicitly be provided. The default value is "xterm -e vi".

## 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.