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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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:
A check mark will appear on the currently selected style's name.
Type "help style" in Gnuplot for more info.
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.
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.
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.
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.
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.
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.
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.
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).
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:
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.
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.
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
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", locationpairs 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.
3D Rotation Options
To enter the 3D plot rotation options click on
Options->3D Plots->Rotation. This will open a dialog
box to enter the rotation options. The two slider bars are used to set
the rotation about the X axis and Z axis. When a 3D plot is first
drawn, the coordinate orientation is the same as a 2D plot. The
default is to rotate about the horizontal X axis by 60 degrees and the
vertical Y axis by 30 degrees in order to show the Z axis part of the
plot. The sliders allow control over the valid range of rotation about
each axis. The Plot Scaling edit box controls the scaling of the
entire plot (default = 1), and the Z Axis Scaling edit box controls
the scaling of the Z axis (default = 1). The Defaults pushbutton can
be used to set the options back to their defaults.
See "help set view" in the Gnuplot help for more info.
3D Tics Level Option
In order to view the 3D Tics Level options click on
Options->3D Plots->Tics Level. This options controls
the height of the Z=0 level above the X-Y plane in 3D plots as a
fraction of the Z-range. In other words, this option controls the
height of the plot above the X-Y plane. The default is 0.5 and can be
changed with the edit box.
See "help set ticslevel" in Gnuplot for more info.
3D Hidden Line Removal
In order to turn off the display of hidden lines in 3D plots, click on
Options->3D Plots->Hidden Line Removal. This is a
toggle to turn off and on the display of hidden lines. The default is
to display hidden lines. When Hidden Line Removal is turned on, the
menu item will have a checkmark beside it. This value is toggled each
time it is clicked.
See "help hidden3d" in Gnuplot for more info.
3D Isolines
In order to control the number of isolines (isosamples) plotted for a
3D surface plot, click on Options->3D
Plots->Isolines. The default is to display 10 isolines in the
U and V directions on the surface. These numbers can be changed with
the edit boxes in the dialog window that is opened. A Defaults
pushbutton is provided to reset the defaults back to 10.
See "help isosamples" in Gnuplot for more info.
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.
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.
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.
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.
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.
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.
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.
