Xgfe Documentation

# Documentation

Xgfe is a GUI front end to the Gnuplot plotting package. It is currently developed under Linux, is written in C++, and uses the Qt v1.32 widget set.

Xgfe tries to make your life with Gnuplot a little easier. It does not currently support every option of Gnuplot, but it supports many things. The development philosophy is a tasked oriented approach. If someone requests the ability to do XYZ, then (if possible) GUI's and support will be created to do XYZ. Xgfe does offer the ability to type commands directly to Gnuplot so its full capabilities are available through the GUI.

The use of the program should be self explanatory, but a few remarks should be made on some of its features. Use this documentation or the internal docs in Gnuplot for more info.

Here is the main window:

If you have not used Gnuplot before, the basic procedure for creating a plot is very simple. The most basic case is to define a function such as sin(x) in the function edit box, click the Function checkbox, and press the Plot pushbutton. Gnuplot (and Xgfe) will provide defaults which will make a simple plot of the function. The same can be said of plotting a datafile, just type the filename in the file edit box (or use the File->Open menu to insert it for you) and press the Plot pushbutton.

For more control of the plot, the Options menu will need to be used. The Options->Datafile and Options->Function menus will provide specific options to the datafile or function respectively. The remaining menu items control options that are global to the whole plot.

The main window with edit boxes for a single file or function and common options are provided to quickly generate a simple plot. The Advanced menu provides more advanced plotting capabilities if needed. Anything beyond defining a function or datafile to plot is not necessary, and only provides more control over the plot.

A full description of the capabilities of Xgfe will now be given.

## Table of Contents

- Files and Functions
- Dummy Variables
- Plot Labels
- Plot Title
- Output Files
- Terminals
- Plot Types
- Plot Style
- Plot Size
- Bar Size
- Box Width
- Saving Gnuplot Plots
- Loading Gnuplot Plots
- Saving Xgfe Plots
- Loading Xgfe Plots
- Raw Gnu Commands
- Datafile Options (Modifiers)
- Datafile Filtering
- Legend Options
- Tics Options
- File Legend Title
- Function Legend Title
- Multiple Files
- Multiple Functions
- Curve Fitting
- Replot support
- Commands and Error Messages

### Files and Functions

Once you fire up Xgfe, you will see the main window shown above. Now you need to decide what you want to plot. If you want to plot a file, go to the File->Open menu to select the appropriate data file (or just type it in). The Filename checkbox will be automatically selected for you if the File->Open menu is used. . You can also plot a function if you so choose. Just type in the function and click the Function checkbox. If you want to plot more than one function or file, go to the Advanced menu and see the documentation on Multiple Files and Multiple Functions. You can plot a filename or function by themselves, or both at the same time (with multiple files and functions) by clicking the appropriate checkboxes.

Table of Contents

### Dummy Variables

You can enter functions in terms of the default dummy variables of X and Y, or you can specify different dummy variables in the "Variable X" and "Variable Y" input boxes. If you use different dummy variables, you must specify a range (this is consistent with running Gnuplot from the command line interface). You can also specify ranges for the Z variable if you want. If no ranges are given, Gnuplot will use defaults.

Run "help plot" in Gnuplot for more info on plotting.

Table of Contents

### Plot Labels

You can set the X, Y, and Z labels for the plots along with the offsets using the appropriate input boxes (X Label:, Y Label:, Z Label:).

Run "help xlabel", "help ylabel", or "help zlabel" in Gnuplot for more info on labels and offsets.

Table of Contents

### Plot Title

The title of the entire plot can be specified in the Title: edit box. The X and Y boxes allow adjustments to be made for its position on the plot.

Run "help title" in Gnuplot for more info.

Table of Contents

### Output Files

An output file can be specified for the plot in the Options->Output menu. If no output is specified, the output will go to the shell window where you ran Xgfe which is probably not what you want (except for the x11 terminal where this is normal). The output can be reset to stdout (which is the default) with the Options->Reset Output menu. The output file will be shown in the label at the bottom of the main window.

Type "help output" in Gnuplot for more info.

Table of Contents

### Terminals

Gnuplot allows many terminals to be specified, and Xgfe supports a subset of the more popular ones. ("More popular" is defined as by the author. If you want another terminal to be supported let me know.) The following terminals are supported:

- bfig
- corel
- dxf
- eepic
- emtex (with options)

  The default font is Roman, 10pt. Courier or Roman can be specified at sizes of 10pt, 11pt, or 12pt. Another size can be selected if your driver can handle it (e.g. dvips). The current options will be inserted into the GUI if you have changed them from the defaults previously. Type "help emtex" in Gnuplot for info on options.

- fig
- latex (with options)

  The default font is Roman, 10pt. Courier or Roman can be specified at sizes of 10pt, 11pt, or 12pt. Another size can be selected if your driver can handle it (e.g. dvips) The current options will be inserted into the GUI if you have changed them from the defaults previously. Type "help latex" in Gnuplot for info on options.

- pbm (with options)

  A font size of small, medium or large and be specified. The colormode of monochrome, gray, or color can be used. The default size of the plot is 640x480 pixels, but can be changed by entering scaling factors in the size edit boxes. The current options will be inserted into the GUI if they have changed from the defaults previously. Type "help pbm" in Gnuplot for info on options.

- postscript (with options)

  The default options are landscape, monochrome, dashed, Helvetica at 14pt, noenhanced. The default size is 10in x 7in. The mode can be landscape, portrait, or eps. The color can be monochrome or color. The line type can be dashed or solid. The font name and size can be changed, and enhanced/noenhanced can be specified, and the size of the plot can be changed by entering scaling factors in the size edit boxes. The current options will be inserted into the GUI if you have changed them from the defaults previously. Type "help postscript" in Gnuplot for info on options.

- pslatex
- pstricks
- table
- texdraw
- tgif
- tpic
- x11

The default terminal is x11. Some of the above terminals have options that can be specified. If options are available, a new window will open to allow selection of the options. When a window opens for options, the defaults are listed the first time it is opened. After the first opening the current values will be inserted into the GUI.

The terminal name will appear in the label at the bottom of the main window.

Note* These terminals were selected from the author's copy of Gnuplot 3.5. I have noticed that in my copy of 3.6 beta 340 that some of the above terminals are not available (dxf, bfig, etc). I'm not sure if the terminals are compile-time options, or if they have been removed. To see what terminals you have available, type "set terminal" in the Gnuplot window.

A check mark will appear on the currently selected terminal's menu name.

Type "help terminal" in Gnuplot for more info.

Table of Contents

### Plot Types

The default plot type is 2D plotting. To select 3D plotting, use the Options->Datafile->Type menu or the Options->Function->Type menu to select the type for files and functions. These menus also apply for multiple files and multiple functions. These menus let Xgfe decide whether to use the "plot" command for 2D plotting, or the "splot" command for 3D plotting. A check mark will appear on the currently selected option's name.

Table of Contents

### Plot Style

The default plotting style for files is points, and for functions is lines. These can be changed as needed. The following styles for files and functions are supported:

- Points
- Lines
- Linespoints
- Impulses
- Dots
- Steps
- Fsteps (data files only)
- Histeps (data files only)
- Errorbars
- Xerrorbars (data files only)
- Yerrorbars (data files only)
- Xyerrorbars (data files only)
- Boxes
- Boxerrorbars (data files only)
- Boxxyerrorbars (data files only)
- Financebars (data files only)
- Candlesticks (data files only)

A check mark will appear on the currently selected style's name.

Type "help style" in Gnuplot for more info.

Table of Contents

### Plot Size

The plot size can be specified with the Options->Plot Size menu. The numbers entered are scaling factors.

The size can be reset back to the default with the Options->Reset Size menu.

The Plot Size dialog will load the current values into the GUI.

Type "help size" in Gnuplot for more info.

Table of Contents

### Bar Size

The size of bars (tics at end of errorbars) on bar-type plotting styles can be specified under the Options->Bar Size menu. The size can be entered manually, or a synonym can be used. Small is a synonym for 0.0, large is for 1.0. If the edit box is left empty, the synonym selected will be used.

Previously defined values will be loaded into the GUI when the dialog is opened.

The size can be set back to the default by using the Options->Reset Bar Size menu.

See "help set bar" in gnuplot for more info.

Table of Contents

### Box Width

The width of boxes for the boxes and related styles can be set with the Options->Box Width menu.

Previously defined values will be loaded into the GUI when the dialog is opened.

The width can be reset to defaults with the Options->Reset Box Width menu.

See "help set boxwidth" in gnupot for more info.

Table of Contents

### Saving Gnuplot Plots

To save your plot settings and command to a file, use the File->Save Gnuplot menu. A file selection window will open up to allow you to specify the filename.

The saved file will be a human-readable text file with Gnuplot commands in it to re-create the current plot. You can then open Gnuplot from the command line and type "load plotfile.gnu" where plotfile.gnu is the saved file and Gnuplot can read this file and recreate the plot.

Type "help save" in Gnuplot for more info.

Table of Contents

### Loading Gnuplot Plots

To load a plot from a saved file, use the File->Load Gnuplot menu.

This feature is limited in its usefulness in Xgfe. Xgfe just calls Gnuplot's load function, but does not parse the saved file to fill in the appropriate options in the GUI for the existing plot.

See the sections below to save and load Xgfe plots that recreate the GUI options for a plot.

Type "help load" in Gnuplot for more info.

Table of Contents

### Saving Xgfe Plots

Xgfe can save a plot with the GUI options to a formatted text file to be read in again to recreate the plot and the GUI options. Use the File->Save Xgfe menu to save the plot.

Gnuplot will not understand this file format if you try to use the load command within Gnuplot on this file. This is a special type of file for Xgfe only.

Table of Contents

### Loading Xgfe Plots

If a plot has been previously saved with the "Save Xgfe" menu, then you can use the File->Load Xgfe menu to reload the plot and the appropriate GUI options will be set. You can then hit the Plot button to recreate the plot.

Table of Contents

### Raw Gnu Commands

Since Xgfe doesn't provide an interface to all the gory details of Gnuplot, a File->Raw Gnu menu is available. Just type in as many commands as you want in the text box and hit OK to fire off the command(s).

Table of Contents

### Datafile Options (Modifiers)

(Known as Datafile Columns/Formats in versions previous to 2.0 of Xgfe)

You can specify the options of a datafile known as datafile-modifiers in Gnuplot under the Options->Datafile->Modifiers menu. There are 4 types of options that can be specified:

1. Data Set Selection
2. Periodic Sampling
3. Columns and Format
4. Interpolation and Approximation

The Data Set Selection edit boxes correspond to the "index" keyword in Gnuplot. This allows specific data sets in a multi-set datafile to be plotted. Put the appropriate numbers in the boxes and the colons will be used to separate them as needed. All edit boxes need not be filled in. See "help index" in Gnuplot for more info.

The Periodic Sampling edit boxes correspond to the "every" keyword in Gnuplot. This allows the selection of specific, periodically sampled data points to be selected in a datafile. Put the appropriate numbers in the boxes and the colons will be used to separate them as needed. All edit boxes need not be filled in. See "help every" in Gnuplot for more info.

The Columns and Format options correspond to the "using" keyword in Gnuplot. The X,Y, and Z column input boxes are the datafile columns to select. Put one number in each box as necessary and the colons will be inserted automatically. If a scanf format is entered, it will be appended to the columns. You must surround the format with quotation marks, either single or double. The Gnuplot help mentioned that double or single quotes could be used depending on the circumstance, so it is up to the user to decide which type to use. A Raw Format input box is given in case you have a strange format you want to use. Again, put the appropriate quotation marks where they need to be. The Raw Format text is inserted into the plot command exactly as typed and all other input data is ignored. All edit boxes need not be filled in. See the Gnuplot help for the "using" command for more info.

The Interpolation and Approximation options correspond to the "smooth" keyword in Gnuplot. This allows specification of generic curve fitting to be plotted through your data points. The types supported are unique, csplines, acsplines, bezier, and sbezier. If "none" is selected, this options will not be used. See "help smooth" in Gnuplot for more info.

Previously defined values will be automatically inserted into the GUI when opened.

See "help plot datafile" in Gnuplot for more info on the datafile modifiers.

Table of Contents

### Datafile Filtering

Gnuplot has the ability to call an external program to filter a datafile before plotting. This is done by a command similar to:

    plot "< awk '$1==5 {print}' datafile.txt" ...

This is a simple one line awk filter that could be used. In this case, the external program awk with arguments is called. The only requirement is that the command be surrounded in single or double quotes, and the program output to STDOUT so Gnuplot can read the data. Any external program could be used.

Xgfe has support for external filtering of datafiles under the Options->Datafile->Filtering menu. This window works for the single file specified in the main window. Multiple files have tab for the same support in the Multiple Files dialog.

The filtering dialog has an edit box to enter the filtering command, and radio buttons are provided to select single or double quotes to be used to surround the filter syntax. Xgfe will automatically insert the "<" character for you.

Push buttons are provided to insert the current filename selected in the main window, or insert a new filename from a file selection dialog if need be.

If a previous filter has been specified, it will be reloaded into the GUI.

Table of Contents

### Legend Options

Legend options are specified by the Options->Legend menu. The two radio buttons key and nokey turn the legend on and off respectively. The Position checkboxes allow the position of the legend to be specified. You can fine tune the legend position by entering x,y,z coordinates in the edit boxes. There are dropdown boxes for text justification, reverse/noreverse, and box/nobox around the legend. The box linetype can be specified, the curve sample length, vertical spacing between multiple lines, a width increment to specify more space around elements before the box around the legend is drawn, and a title for the legend. When the dialog is first opened, the defaults are listed. If new values have been specified before, they will be reloaded. If you want all values to be set back to defaults, just hit the Defaults button.

See "help key" in the Gnuplot help for more info

Table of Contents

### Tics Options

The tics options for xtics, ytics, ztics, x2tics, and y2tics can be set by using the Options->Tics menu.

The tics window is a tabbed dialog where each tab is a different kind of tic. You can turn tics on or off by using the appropriate radio buttons. The location of border/axis, mirroring of mirror/nomirror and rotation of rotate/norotate can be set with the combo boxes.

The tics position can be set in one of two ways: start/increment/end, or by typing in text labels and their positions. Choose the appropriate radio button for the type you want to use.

For the start/increment/end style, you can fill in only the edit boxes you need and Gnuplot will assume defaults for the others.

The labels/position type is set by entering:

    "label", location

pairs into the edit box. Anything entered in this edit box will be fed to Gnuplot exactly as typed, so make sure the syntax is correct.

The defaults will be loaded in the GUI the first time it is opened, and previously defined values will be set if it has been used before. Xgfe by default turns xtics and ytics on, with ztics, x2tics, and y2tics turned off.

See "help set xtics" in Gnuplot for more info.

Table of Contents

### File Legend Title

If you are using a legend, the default title is the filename or function beside the linetype. Gnuplot allows you to specify a user supplied string for the title. This title for the single file in the main window can be specified using the Options->Datafile->Legend Title menu.

When you first open the dialog window, the default checkbox is selected. If you don't want the file to appear in the legend, check the notitle box. To supply your own title, enter it in the edit box and uncheck whichever checkbox is selected. For example, if you enter your own title, but leave the default button checked, your new title will not appear. In other words, the checkboxes have precedent over the edit box for titles.

If you have previously supplied your own title, it will be recalled the next time you open the File Legend Title window.

Note to power users: According to the Gnuplot help, you can specify backslash escaped characters to be interpreted by Gnuplot and other strange things to be used in the title. According to what you want to do, you may need to specify the string with double or single quotes. Xgfe will always specify the string with double quotes which may not be what you want. I suggest that you save the plot to a file and edit it by hand if you need work around this functionality.

See "help plot title" in the Gnuplot help for more info.

Table of Contents

### Function Legend Title

The operation of setting the legend title for the single function in the main window is exactly the same as described in the File Legend Title section. The only difference is that you select the Options->Function->Legend Title menu under the Options menu.

See "help plot title" in the Gnuplot help for more info.

Table of Contents

### Multiple Files

(was under Options menu in versions previous to 2.0 of Xgfe)

The main window of Xgfe has a single edit box for specifying a single file and a single function. If you want to plot several files click on Advanced->Multiple Files to open the multiple file dialog window. This window will allow you to specify many files to plot along with the appropriate options for files. This is a tabbed dialog that also allows the datafile-modifiers to be specified as well as an external filtering program for the current file.

To insert a new file into the list, click the New File button. This will open a file selection window for you to select a file. Once you have selected a file, it will be inserted into the dropdown file list. Now you can specify all the appropriate options which are already documented. (Plot Style, File Legend Title, Datafile Options (Modifiers) , Datafile Filtering)

If you want to delete a file, just hit the Delete File button and the current file will be removed from the list (this will not delete it from your hard drive, only the list).

When you insert a new file, the default arguments will be specified in the GUI. If you change any options on any tab, you must hit the Apply button to save those changes.

You can use the dropdown list box to view any of the files and its options you have inserted into the list.

Once you have specified multiple files, be sure to select the Multiple Files checkbox on the main window before plotting so they will actually get plotted!

If you have previously selected multiple files and open this window again, it will reload those files into the list. They may be inserted in a different order that you specified before. The internal data structure I use does not guarantee that you can get the files back in the same order as you put them in. I hope this doesn't cause any problems for you. If it does, let the author know.

To select 2D or 3D plotting, use the Options->Datafile->Type menu as documented earlier.

Press the Close button to close the dialog.

There is no arbitrary limit imposed by Xgfe on the number of files you can plot. However, there is a limitation to the length of the command you send to Gnuplot. Xgfe doesn't know this limit, so it will happily generate the correct command to plot all of the specified files (and functions too). I haven't tested this limitation to see how many files as a practical matter can be specified.

I've read on the Gnuplot newsgroup that the length of the input buffer for Gnuplot can be increased in the source code and recompiled. I've not looked into this so if you have a problem, this may be a solution.

Table of Contents

### Multiple Functions

The window to plot multiple functions can be found under the Advanced->Multiple Functions menu. The operation of this window is very similar to the Multiple Files menu except the options are different and not as numerous.

To insert a new function into the list, enter it in the edit box and hit the Add Function button (or hit ENTER). This will insert the function into the dropdown list with the default arguments. You can then select the style and legend title you wish to use for the current function (legend title operation is exactly the same for the single function legend title window). As with the Multiple Files window, you must hit the Set Options button to save any changes to the options of the current function in the list box.

If you want to delete the current function from the list you press the Delete Function button.

Once you have specified multiple functions, be sure to select the Multiple Functions checkbox on the main window before plotting so they will actually get plotted!

To select 2D or 3D plotting, use the Options->Function->Type menu.

Table of Contents

### Curve Fitting

Curve fitting is available by clicking on the Advanced->Curve Fitting menu. This will not actually plot anything, it will just find the correct values for various parameters in a given function in fitting to data in a datafile.

The function to fit will be entered in the Function: edit boxes. Place the function name and value in the edit boxes on either side of the = sign. For the function f(x)=a*x+b, put f(x) in the first box and a*x+b in the second. This will allow Xgfe to define the function and use the function name in the fit command.

A datafile must be specified to use in the curve fit. Enter the name in the Data file: edit box, or use the pushbutton Get to use a file selection window.

The x and y variable names and/or ranges can be specified and will be used as documented in the Dummy Variables section above. These values can be left blank.

The parameters to vary in the curve fit can be specified in a file, or as a comma separated list. Choose the appropriate radio button to select the needed method. For example: for the function f(x)=a*x+b, the value a,b can be specified in the comma separated list box. If a parameter file is to be used, you can use the Get pushbutton to use a file selection window to get the filename, or just type it in yourself.

The special variables of Fit Limit, and Fit Max Iterations can be specified if needed. These can be left blank.

The Datafile Modifiers (aka Options) can be specified for the datafile as documented in the Datafile Options (Modifiers) section above.

Press the Fit pushbutton in the Main tab once the appropriate options have been specified to do the curve fit. The progress of the fit and final values of the parameters will be displayed in the shell window where you started Xgfe.

See "help fit" in Gnuplot for more info.

Table of Contents

### Replot Support

The normal procedure for working with Xgfe is to set the appropriate options, select a datafile or function, and hit the Plot button to plot. The Replot button issues the "replot" command to append the new file/function/both to the existing plot.

See "help replot" in the Gnuplot help for more info.

Table of Contents

### Commands and Error Messages

In the shell window you ran Xgfe from, the plotting commands issued will be printed so you can see what is going on behind the scenes. This can't be turned off at this time. If there are any errors, they will be printed to the shell window. If there is any confusion over an error message, check Gnuplot's online help, the net, or the comp.graphics.apps.gnuplot newsgroup.

Table of Contents

Back to home

Last modified: Sun Jun 7 15:00:52 CDT 1998