- Example (click to enlarge) -
XGRAPH produces wysiwyg PostScript, PDF, and MIF (Maker Interchange Format) output for printing hard-copies, storing, and/or sharing plotted results, and for importing, graphs directly into word-processors for creating documentation, reports, and view-graphs.
XGRAPH includes the ability to specify plotting colors for multi-color plots, as well as line-thickness. It has the ability to use any column of a multi-column file as ordinate and abscissa axis. It also supports automatic resizing of its window.
Multi-column data has several values per line. Each value, or column, is separated by white-space (spaces or tabs), commas, semi-colons, or colons. Any column can be selected as the ordinate or the abscissa by the '-c' column option.
xgraph f1 -c m1 m2 -c f2Files f1 and f2 would be interpreted as one xy-pair per line files, while file2 m1 and m2 would be interpreted as multi-column files. For multi-column files, xgraph will prompt for which columns to use as the ordinate and abscissa values. A convenient way to switch the axes of a simple xy-pair file is to treat it as a multi-column file (having two columns), and use columns 2 and 1 as the abscissa and the ordinate respectively.
To plot multiple columns from a single file, list the file several times on the command line. For instance to plot columns 3 and 5 against column 2 from file xyz:
xgraph -c xyz xyz and respond when prompted with: 2 3 2 5 as the columns for the abscissa and ordinate axes respectively.To specify the column numbers on the command-line instead of being prompted interactively, use the '-columns' option. For example:
xgraph -columns 1 5 test.dat
Multiple curves can also be drawn by including data from separate data files. There is an implicit 'pen-up'-'pen-down' that breaks the connecting line between data plotted from different files.
Example, ! Two points make a straight line. ! (x,y) 0 5 2 6Blank lines are allowed anywhere.
alias xgraph '/home/chein/graph/xgraph'Then type xgraph with your data file specified on the command-line. For instance, to plot data in file f1.dat:
xgraph f1.dat
Z_in_H Button - Zoom in horizontally. Increases the horizontal axis magnification. Scales range by 0.75. Z_out_H Button - Zoom out horizontally. Decreases the horizontal axis magnification. Scales range by 1/0.75. Z_in_V Button - Zoom in vertically. Increases the vertical axis magnification. Scales range by 0.75. Z_out_V Button - Zoom out vertically. Decreases the vertical axis magnification. Scales range by 1/0.75. Pan_^ Button - Pan up. Moves graph's vertical window range upward by 25% of current range. Finer panning can be achieved by first zooming-in, then panning, and then zooming back out. Pan_< Button - Pan left. Moves graph's horizontal window range leftward by 25% of current range. Finer panning can be achieved by first zooming-in, then panning, and then zooming back out. Pan_> Button - Pan right. Moves graph's horizontal window range rightward by 25% of current range. Finer panning can be achieved by first zooming-in, then panning, and then zooming back out. Pan_v Button - Pan down. Moves graph's vertical window range downward by 25% of current range. Finer panning can be achieved by first zooming-in, then panning, and then zooming back out.
Points Button - Toggles the points-lines drawing mode between the three options: 1.) Lines only connecting points, 2.) Points identified on lines by small icons, with connecting lines. 3.) Points only identified by small icons, (no connecting lines). Annotations Button - Toggles suppress-annotations mode. By default, annotations are enabled. Pressing the annotations button disables or enables the display of any annotations embedded in the data files. ? Help Button - Causes this help file to be displayed. ReDraw Button - Forces re-draw of the display. This forces a re-read of the data files. This is useful for quickly updating the graph without changing the settings when any of the data files change. Print Button - Pops-up choosing box for sending plot directly to a printer or to a file in Postscript, PDF, or MIF formats. The default printer command and file format names are shown. The defaults can be changed in the respective dialogue boxes. Hitting return or the selected output-button sends the output to the respective printer or file. Quit Button - Quits the graph window.
Most display aspects can be changed interactively from the graph control-panel, so the command-line options are often more of a convenience. They enable the graph come up in a desired mode without pressing more buttons.
For non-interactive or script-driven usage, the command-line options are essential. They enable display modes to be set, or hardcopy print-outs to be generated, without the need of an interactive display for pressing buttons.
Below is a quick summary of the command-line options, followed by detailed descriptions of the important options.
-c If your data is arranged in columns, then you will be prompted to select individual columns. -color Specify the color that data from a file is to be drawn in. -columns - Specify columns on command-line. -sann Suppress annotations. -a Expect y values only. Generate the x values internally by a simple counter. -p Just plot points, without connecting lines. Uses tick-mark shapes of circles, squares, triangles for each successive curve. -pl Plot points with lines. This shows where the data samples were on the curves with tick-marks. -psz Specify point-size of shapes for -pl and -pl. (Default=0.1) -ps Non-Interactive PostScript output. Useful for batch script-driven jobs. -pdf Non-Interactive PDF (Portable Document Format) output. Useful for batch script-driven jobs. -mif Non-Interactive MIF word-processor output. Useful for batch script-driven jobs. -help Prints this list of options. -titles Toggle titles on graph axis. -text Put extra text on graphs. -x_range Specify X-axis range. Must be followed by two values. If specified before files, used as Soft outer limits which will be stretched if data values exceed given range. If specified before files, used as Rigid range which will restrict graph boundaries even if data exceeds given range. -y_range Specify Rigid Y-axis range. Must be followed by two values. If specified before files, used as Soft outer limits which will be stretched if data values exceed given range. If specified before files, used as Rigid range which will restrict graph boundaries even if data exceeds given range. -g Impose geometric equality of scale on both axis. -ng Specifies no grid, turns grid off. -ngrids_x - Specify number of horizontal axis grid tick-marks. -ngrids_y - Specify number of vertical axis grid tick-marks. -out_file - Specify postscript output file name. -bw When printing, make postscript for black and white printer. -lower_boundary - Position of lower graph border. -upper_boundary - Position of upper graph border. -left_boundary - Position of left graph border. -right_boundary - Position of right graph border.
Specify the horizontal axis range with:
-x_range min_x max_xwhere min_x and max_x are your desired range limits for the axis. Specify the vertical axis range as in:
-y_range min_y max_ywhere min_y and max_y are your desired range limits for the axis.
You can use these to express 'hard' or 'soft' ranges. A 'hard' range means that the graph will be clipped exactly to the specified range, regardless of whether your data covers that range or exceeds it.
A 'soft' range means that the graph will be drawn out to that range even if your data does not span that range, but if data exists outside that range, the range will be extended to include the data.
You control the 'hardness' or 'softness' of your optionally specified ranges by where you place them on the command-line. If placed first on the command-line, the range specifier is 'soft' in that it acts merely as a minimum range. Any data coming afterward that exceeds that range will expand it. If placed last on the command line, the range specifier is 'hard' in that it sets the range to the specified value regardless of what the data range was that came before it.
The axes data ranges and their 'hardness' or 'softness' are independently controlled for the X and Y axes. For instance, you can specify the X-axis range, but let the Y-axis auto-scale to the data, by simply specifying only an X-axis range, or vice-verse.
If you are using XGRAPH interactively, you can use the range specifiers to set the initial ranges. Then you can move around with the pan and zoom buttons, once you are inside the graph.
On command line: -upper_boundary <position> -lower_boundary <position> -left_boundary <position> -right_boundary <position> In file: upper_boundary = <position> lower_boundary = <position> left_boundary = <position> right_boundary = <position>where the <position> is in inches from the top of the 8.5-inch high page. Default position: upper_boundary=0.5, lower_boundary=7.0, left_boundary= 2.75, right_boundary=10.5.
Example: -ngrids_x 8Will attempt to divide the axis into 8 tick-marks. The default values are: ngrids_x = 5, ngrids_y = 7.
Command Syntax:
color = <color_choice>
Example:
color = blue
Action: The color of any lines drawn after this command will be
'blue'.
Valid color names are:
0 = black, (caution on black screen background)
1 = white, (caution on white paper printout)
2 = red,
3 = blue,
4 = green,
5 = violet,
6 = orange,
7 = yellow,
8 = pink,
9 = cyan,
10 = light-gray,
11 = dark-gray,
12 = fuchsia. (default)
You can switch back and forth between colors as many times
as you like within your files.
You can use either the color names or numbers.
You can also specify color on the command line using the -color
command-line option. With it, you can specify a separate color for
each of several files plotted from the command-line. (Any embedded
color commands will override the command-line settings.)
These take values in the form of RRBBGG, ranging from 000000 through ffffff. Where each red/blue/green color is specified as a two-digit hex value, 00 = 0-decimal (dark) through ff = 256-decimal (bright).
For example:
000000 = Jet-Black. 808080 = Gray. ffffff = Bright-White. 880000 = Medium Red. 008800 = Medium Blue.To set the environment variables, use for example:
setenv XGRAPH_BACKGROUND 005858Once set, the setting will be valid in the current shell throughout the session. (To suit personal preferences, the environment variables can be set in your .cshrc or .login files.)
These color settings will affect the screen display and PDF output-file colors. They will not affect the Postcript or MIF output-file colors. (The PDF form could be used for paper printouts or for screen display via web-pages where non-white background colors are useful. The Postscript and MIF forms are usually for paper printouts only, where non-white background colors are usually not-wanted. The B&W print option sets all objects to black for best display on non-color printers.)
The default colors are:
setenv XGRAPH_BACKGROUND 123b12 setenv XGRAPH_BORDERCOLOR 00ffff setenv XGRAPH_TEXTCOLOR d112d1
To remove the settings, use for example:
unsetenv XGRAPH_BACKGROUND unsetenv XGRAPH_BORDERCOLOR unsetenv XGRAPH_TEXTCOLOR
Command Syntax: thickness = <value> Example: thickness = 2.5 Action: The thickness of any lines drawn after this command will be 2.5-points wide. A point is defined as 1/72-inch. Note that for screen displays, dimensions are scaled such that the window size is always considered to be an 8.5x11 inch sheet of paper, regardless of the actual size of the display window. This ensures that manipulations of your graph will appear on a printout as they do on your screen. It also ensures that line widths do not vary with the range of your data, or the extent that you zoom in or out.
title_x = <any text you choose>
title_y = <any text you choose>
title = <any text you choose>
Examples:
title_x = Time (uS)
This will put 'Time (uS)' under the X-axis.
title_y = Device Name
This will put 'Device Name' to the left of the Y-axis.
title = Experiment 5: Two Search-mode Subgraphs.
This will put 'Experiment 5: Two Search-mode Subgraphs.'
across the top of the graph page.
You can turn the titles off by invoking XGRAPH with the '-titles'
option ahead of the graph name on the command line.
The -titles option has a toggling affect, as do most of the
other options, so you can turn it on-and-off several times
across the command line to plot each file with different
options.
Specifying -titles a second time on the command line will turn
the title sensitivity back on. This allows you select which files
to include titles from when you are superimposing several files.
Example 1:
xgraph -titles f1.dat -titles -f2.dat
(This will only take titles from the f2.dat file.)
Sometimes it is convenient to have a dedicated file,
that have nothing but the common titles you like to use as in:
xgraph result.dat velocity_graph.titles
The form is: annotation <X> <Y> <text> For example: anno 5.2 78.0 Second Experiment ResultsThe X-Y coordinate data are in the same coordinate system as your data (in other words, its not screen-coordinates, but data-coords.). The coordinate refers to the bottom left-hand corner of the text string.
To suppress annotations from appearing on you graph, you can use the '-sann', 'suppress annotations' command line option, or hit the Toggle-Annot button on the control panel.
To use this option, add the '-text' command-line. You embed text within your data file(s), by using the keyword 'text' followed by the inch-based coordinates of where you want it to appear on an 8.5x11 page. Then place your text on the succeeding lines. End the text entries by placing the keyword 'end_text' on an empty line. As with all other things, the keywords can be in caps or smalls or any combination thereof. An example follows:
! This is an example of embedding text within a data file. ! you might have axis titles and other things in here too. TEXT 4.5 3.2 Figure 8 - Revenue vs. Profits This text will be included on the graph when you select the '-text' option. END_TEXT ! The data may then follow or precede the text, etc.
Command Syntax: replace_y_axis <value> <string> Example: replace_y_axis 101.2 VME_bus Action: The word 'VME_bus' will appear at the vertical position corresponding to 101.2 to the left of the y-axis where the numbers would otherwise appear.
Command Syntax: replace_x_axis <value> <string> Example: replace_x_axis 11 /device_11 Action: The word '/device_11' will appear at the horizontal position corresponding to 11 under the x-axis where the x-axis numbers would otherwise appear.
You can set the environment variable XGRAPH_PRINT_COMMAND to specify the print command and favorite printer that you normally want to use. If you do, your default print-command will show-up in the print-menu. To set the variable, use for example:
setenv XGRAPH_PRINT_COMMAND "lpr -Plw1"
lpr ljet.psFile name 'ljet.ps' is the default output file name. You can specify a different name by using the -out_file command line option upon invocation, as in:
-out_file graph_3.psPostscript output would go to file 'graph_3.ps' instead of 'ljet.ps'.
You can then import the plot.mif file to your word-processor where you are free to manipulate the graph objects in any way that you choose. For instance, you can change fonts, font sizes, colors, etc.. You can also add textual annotations, with arrows to point to things, or circle or high-light particular graph features. One particularly powerful feature is the ability to stretch or shrink the whole graph, to change its aspect-ratio, or even rotate it 90-degrees. In this way you can easily put several graphs on a page with complete layout freedom.
File name 'plot.mif' is the default output file name. You can specify a different name by using the -out_file command line option upon invocation, as in:
-out_file graph_3.mifMIF output would go to file 'graph_3.mif' instead of 'plot.mif'.
To produce your graphs in PDF interactively, press the PRINT button and select PDF. To produce your graphs in PDF non-interactively, place -pdf on the xgraph command-line. By default, a file called ljet.pdf will be produced. You can view PDF files with the free Acrobat reader, acroread, from Adobe for Unix, MS-PC, Apple Macintosh, and all Linux platforms. Example. Various other PDF viewers are available. You can also send the PDF file to your printer from the PDF-viewer.
File name 'ljet.pdf' is the default output file name. You can specify a different name by using the -out_file command line option upon invocation, as in:
-out_file graph_3.pdfSee section 5.1 Background, Border, Text Colors for a discussion about setting colors specific to the PDF output files.
| Read File | - |
You can open a new file for display of its data, or add a data file
to be displayed with others already loaded, by pressing this button.
A file browser will pop-up for you to enter or select a data file
for plotting.
|
| Add Options | - | You can add or modify the command-line options while the graph is displayed. For help on available options, see Command-line Options. |
|
Eliminate Files/Options | - |
If you wish to remove a data file or option from the current display,
press this button. You will see a list of the currently loaded
files and options, where you have the opportunity to eliminate any of them.
This button, in combination with the Add Options button, can be
used to rearrange the order of the files and options. (For example,
to turn -pl points-on-lines or -c multi-column-file-mode
on before some files and off on others.)
|
|
Save Custom Graph (by copy) | - |
There are two ways to save your customizations: by copy, into ONE file,
or by reference to other files. There is a
distinct button for each method. The Save Custom Graph (by copy)
button causes all data AND customizations to be saved into one
convenient file of your choosing. This method is convenient for
archiving the results of individual experiments or data-sets.
With this, you may combine data from many files, together with your
specific annotations and explanations, into one file.
The customized graph-file can be retrieved at any later time.
It is convenient to use a naming convention for the save-file which
denotes the experiment, date, etc., to facilitate organizing large
collections of results. This method is also advantageous for
cases where you cannot be sure the constituent data-files will
remain.
You can re-load a saved file by invoking XGRAPH with just that file name.
|
|
Save Customization (by reference) | - |
As mentioned above, the Save Customizations (by reference)
button causes just your customizations to be saved in a file,
along with the include references to the data files you
are viewing. This method is convenient when you wish to view data
that is to be updated independently, or for common data that is to be
viewed from several different customization files.
You can re-load a saved file by invoking XGRAPH with just that customization file name. XGRAPH will follow all the references to load the data from the other files. You can also edit these file with a text editor. Customization files are syntactically the same as any other XGRAPH file. Their only distinction is their role.
|
| Annotate Data | - |
There are two ways to add textual annotations to your graph:
data-space relative, and page-relative.
The first attaches your annotation to the coordinates of your
plotted data, such that, after panning or zooming, your annotation
will remain in the same position relation to your data, though
it will change its position on the screen or printed page.
(Some annotations will actually disappear from view when zoomed
into a different region of a graph.)
When you press this button, a pop-up window will appear for you to enter some text. After entering your text and clicking the ok button, then click-once at the place on your graph where you wish to attach the annotation. You will see the annotation appear where you clicked. Typically, data-relative annotations are used near data features in your graph, such as identifying individual curves or inflection points. These annotations are placed with the graph borders. The second method is described next.
|
| Annotate Page | - |
As mentioned above, there are two ways to add textual annotations to your graph.
This second method attaches your annotation to the coordinates of
the printed page (or window). Its position will not be affected by any
panning or zooming of your graph data. Typically, page-relative annotations
are used to provide longer explanations about the data set, conditions,
observations, etc.. These are often placed outside the graph borders,
perhaps, above, below, or aside of the graph. The Move Border
option is particarly helpful for providing more space around the graph
to accomodate longer discussions.
When you press this button, a pop-up window will appear for you to enter some text. You will notice that it has a larger, multi-line, test-box to accomodate longer descriptions than the previous annotation mode. After entering your text and clicking the ok button, then click-once at the place in the graph window where you wish to attach the text. You will see your added text appear where you clicked.
|
| Draw-Line | - |
Often it is helpful to add a line to your graph, perhaps to better
point at something you are annotating, or to show a critical
region on your graph. Of course you could add or manipulate
lines by editing a data-file. But, you can also add such lines
interactively (visually) with this button.
(The lines so-entered will be associated with the window or page,
not the data.)
To draw a line on your graph, click the Draw-Line button. Then click-once at the spot where you want the line to begin. Release, and move the mouse to the spot where you want the line to go to. Clicking a second time at the second point will produce the line on your graph. For extra help, you will see prompts in the text-window telling you what to do at each step of the process.
|
|
Select Text: On/Off | - |
You can change the status of annotations with the Select text
buttons. The first, labeled On/Off, allows you to show or
hide selected annotations. (This includes both annotations in your
data files, as well as the ones you entered interactively.)
This button has a toggling effect on selected annotations.
That is, toggling once will cause a hidden annotation to show,
while toggling the visible annotation will cause it to become hidden.
To toggle the visibility of an annotation, click the On/Off button, and then click once on the graph near the annotation. You should see the annotation change in visibility. (To point accurately at closely-spaced annotations, remember that an annotation's sensitive spot is at the left side of the first character on it's first line.) Typically, the On/Off option is used when an overwhelming number of annotations are present and therefore supressed, but you wish to bring out a few selected ones. Consequently, this mode assumes that the supress-annotions (-sann) option must be activated. If not, this operation it will activate -sann automatically. You may see other annotations become hidden. Simply show the desired ones by toggling them On again with this button. Conversely, toggling global annotations back-on with the front-panel's Tog Anno button will cause all annotations to be displayed again. (Of course! They're still there!). But this will detract from any modified annotations. Toggling the global annotations back-off will restore your customizations.
|
|
Select Text: Move | - |
You can move any annotation or text-note by clicking the Move
button. Then click-once on the annotation you wish to select.
Release, and move the mouse to where you want to place the annotation.
Then click once more where you want the annotation placed.
You will see the annotation appear in the new location.
(The data-or-screen relative-status is unaffected by this operation.)
|
|
Select Text: Edit | - |
To modify an annotation or text-note, click the Edit
button. Then click-once on the annotation you wish to edit.
A pop-up text-window will appear with the selected annotation
inside it. After editing it, click Apply button. You will see
the modified annotation on the graph.
|
| Graph Title | - |
To add or modify a graph title, click the Graph Title
button. A pop-up text-window will appear to enter or modify your
graph title. You may then select ok or Apply.
In the former case, the graph's title change will be registered immediately,
but you will not see the graph title change on the graph until
next screen update. Selecting Apply forces an immediate
screen redraw.
|
| X-Axis Label | - |
To add or modify the X-axis (horizontal) label, click the X-axis Label
button. A pop-up text-window will appear to enter or modify the
axis label. You may then select ok or Apply.
In the former case, the label change will be registered immediately,
but you will not see the graph change on the graph until
next screen update. Selecting Apply forces an immediate
screen redraw.
|
| Y-Axis Label | - |
To add or modify the Y-axis (horizontal) label, click the Y-axis Label
button. A pop-up text-window will appear to enter or modify the
axis label. You may then select ok or Apply.
In the former case, the label change will be registered immediately,
but you will not see the graph change on the graph until
next screen update. Selecting Apply forces an immediate
screen redraw.
|
| Move Borders | - |
It is often useful to re-position the boundaries of the graph on
the screen or printed-page, to allow more space for axis label names,
or textual notes and explanations around the graph. You can move
the four borders independently by pressing the Move Borders
button. A pop-up window will appear that shows you the current border
position settings, and allows you to modify them.
The border positions are specified in inches relative to an 8.5x11 sheet of paper in landscape orientation. The positions within a screen window are directly proportioned to this as well. (Sometimes it is helpful, to avoid much trial and error, to use a ruler with a printed graph to reach good settings quickly.)
|
|
Scale X-axis Numbers | - |
Sometimes it is desired to change the units with which the axis
numbers were labeled. For example, from minutes to nano-seconds,
for volts to kilo-volts. You can change the axis-label with the
axis-label buttons. To change the X-axis numbers, click the
the Scale X-axis Numbers button. A pop-up window appears
allowing you to enter a scale factor. This will not change the
data on the graph, nor it's positioning.
For example, suppose an experiment produced data ranging from 0.00002-seconds to 0.00005-seconds. Certaintly such a span is unwieldly to express in seconds. Instead, you could change the axis label from being (units are seconds) to read (units are micro-seconds), and re-scale the x-axis numbers by 1.0e+6, to show values ranging 20-uS to 50-uS. The data and it's position on the graph will be unaffected.
|
|
Scale Y-axis Numbers | - | Similar to Scale X-axis Numbers above, but for the Y- (vertical) axis. |
See also:
