GNUPLOT

An Interactive Plotting Program

Thomas Williams & Colin Kelley

Version 3.5 organized by: Alex Woo

Version 3.6a organized by: Alexander Lehmann

• John Campbell
• Robert Cunningham
• Gershon Elber
• Roger Fearick
• David Kotz
• Ed Kubaitis
• Russell Lang
• Alexander Lehmann
• Carsten Steger
• Tom Tkacik
• Jos Van der Woude
• Alex Woo

Copyright (C) 1986 - 1993 Thomas Williams, Colin Kelley

Mailing list for bug reports: bug-gnuplot@dartmouth.edu
 
 

This manual is for GNUPLOT version 3.6a

gnuplot

For help on any topic, type help followed by the name of the topic.

The new GNUPLOT user should begin by reading the introduction topic (type help introduction) and about the plot command (type help plot). Additional help can be obtained from the USENET newsgroup comp.graphics.gnuplot.

copyright
introduction
cd
clear
command line-editing
comment
environment
exit
expressions
fit
help
if
load
call
pause
plot
print
pwd
quit
replot
reread
reset
save
set-show
shell
splot
start-up
substitution
update
user-defined
bugs
list of demos

copyright

     Copyright (C) 1986 - 1993   Thomas Williams, Colin Kelley

  Permission to use, copy, and distribute this software and its
  documentation for any purpose with or without fee is hereby granted,
  provided that the above copyright notice appear in all copies and
  that both that copyright notice and this permission notice appear
  in supporting documentation.

  Permission to modify the software is granted, but not the right to
  distribute the modified code.  Modifications are to be distributed
  as patches to released version.

  This software is provided "as is" without express or implied warranty.

  AUTHORS

    Original Software:
      Thomas Williams,  Colin Kelley.

    Gnuplot 2.0 additions:
        Russell Lang, Dave Kotz, John Campbell.

    Gnuplot 3.0 additions:
        Gershon Elber and many others.

  There is a mailing list for gnuplot users. Note, however, that the
  newsgroup 
        comp.graphics.gnuplot 
  is identical to the mailing list (they
  both carry the same set of messages). We prefer that you read the
  messages through that newsgroup, to subscribing to the mailing list.
  (If you can read that newsgroup, and are already on the mailing list,
  please send a message info-gnuplot-request@dartmouth.edu, asking to be
  removed from the mailing list.)

  The address for mailing to list members is
        info-gnuplot@dartmouth.edu
  and for mailing administrative requests is 
        info-gnuplot-request@dartmouth.edu
  The mailing list for bug reports is 
        bug-gnuplot@dartmouth.edu
  The list of those interested in beta-test versions is
        info-gnuplot-beta@dartmouth.edu

introduction

         load "filename"
         cd 'dir'

Commands may extend over several input lines, by ending each line but the last with a backslash (\). The backslash must be the LAST character on each line. The effect is as if the backslash and newline were not there. That is, no white space is implied, nor is a comment terminated. Therefore, commenting out a continued line comments out the entire command (see comment).

In this documentation, curly braces ({}) denote optional arguments to many commands, and a vertical bar (|) separates mutually exclusive choices. GNUPLOT keywords or help topics are indicated by backquotes or boldface (where available). Angle brackets (<>) are used to mark replaceable tokens.

For help on any topic, type help followed by the name of the topic.

The new GNUPLOT user should begin by reading about the plot command (type help plot). Simple Plots Demo

cd

Syntax:

        cd "<directory-name>"

Examples:

        cd 'subdir'
        cd ".."

clear

command line-editing

The editing commands are as follows:

 Line-editing:

 ^B moves back a single character.
 ^F moves forward a single character.
 ^A moves to the beginning of the line.
 ^E moves to the end of the line.
 ^H and DEL delete the previous character.
 ^D deletes the current character.
 ^K deletes from current position to the end of line.
 ^L,^R redraws line in case it gets trashed.
 ^U deletes the entire line.
 ^W deletes the last word.

 History:

 ^P moves back through history.
 ^N moves forward through history.

 Left  Arrow     - same as ^B.
 Right Arrow     - same as ^F.
 Ctl Left  Arrow - same as ^A.
 Ctl Right Arrow - same as ^E.
 Up    Arrow     - same as ^P.
 Down  Arrow     - same as ^N.

 Undo            - same as ^L.
 Home            - same as ^A.
 Ctrl Home       - same as ^E.
 ESC             - same as ^U.
 Help            - help' plus return.
 Ctrl Help       - help '.

comment

environment

If GNUTERM is defined, it is used as the name of the terminal type to be used. This overrides any terminal type sensed by GNUPLOT on start up, but is itself overridden by the .gnuplot (or equivalent) start-up file (see start-up), and of course by later explicit changes.

On Unix, AmigaDOS, AtariTOS, MS-DOS and OS/2, GNUHELP may be defined to be the pathname of the HELP file (gnuplot.gih).

On VMS, the symbol GNUPLOT$HELP should be defined as the name of the help library for GNUPLOT.

On Unix, HOME is used as the name of a directory to search for a .gnuplot file if none is found in the current directory. On AmigaDOS, AtariTOS, MS-DOS and OS/2, GNUPLOT is used. On VMS, SYS$LOGIN: is used. See help start-up.

On Unix, PAGER is used as an output filter for help messages.

On Unix, AtariTOS and AmigaDOS, SHELL is used for the shell command. On MS-DOS and OS/2, COMSPEC is used for the shell command.

On AmigaDOS, GNUFONT is used for the screen font. For example: "setenv GNUFONT sapphire/14".

On MS-DOS, if the BGI interface is used, the variable BGI is used to point to the full path of the BGI drivers directory. Furthermore SVGA is used to name the Super VGA BGI driver in 800x600 res., and its mode of operation as 'Name.Mode'. E.g., if the Super VGA driver is C:\TC\BGI\SVGADRV.BGI and mode 3 is used for 800x600 res., then: 'set BGI=C:\TC\BGI' and 'set SVGA=SVGADRV.3'.

exit

expressions

Complex constants may be expressed as the {<real>,<imag>}, where <real> and <imag> must be numerical constants. For example, {3,2} represents 3 + 2i; {0,1} represents i itself. The curly braces are explicitly required here.

functions
operators

functions

abs
acos
arg
asin
atan
besj0
besj1
besy0
besy1
ceil
cos
cosh
erf
erfc
exp
floor
gamma
ibeta
inverf
igamma
imag
invnorm
int
lgamma
log
log10
norm
rand
real
sgn
sin
sinh
sqrt
tan
tanh

abs

For complex arguments, abs(x) is defined as the length of x in the complex plane [i.e., sqrt(real(x)**2 + imag(x)**2) ].

acos

arg

asin

atan

besj0

besj1

besy0

besy1

ceil

cos

cosh

erf

erfc

exp

floor

gamma

ibeta

inverf

igamma

imag

invnorm

int

lgamma

log

log10

norm

rand

real

sgn

sin

sinh

sqrt

tan

tanh

operators

Parentheses may be used to change order of evaluation.

binary
unary

binary

 Symbol      Example      Explanation
  **          a**b          exponentiation
  *           a*b           multiplication
  /           a/b           division
  %           a%b         * modulo
  +           a+b           addition
  -           a-b           subtraction
  ==          a==b          equality
  !=          a!=b          inequality
  &           a&b         * bitwise AND
  ^           a^b         * bitwise exclusive OR
  |           a|b         * bitwise inclusive OR
  &&          a&&b        * logical AND
  ||          a||b        * logical OR
  ?:          a?b:c       * ternary operation

Logical AND (&&) and OR (||) short-circuit the way they do in C. That is, the second && operand is not evaluated if the first is false; the second || operand is not evaluated if the first is true.

The ternary operator evaluates its first argument (a). If it is true (non-zero) the second argument (b) is evaluated and returned, otherwise the third argument (c) is evaluated and returned.

unary

 Symbol     Example      Explanation
  -           -a          unary minus
  ~           ~a        * one's complement
  !           !a        * logical negation
  !           a!        * factorial

The factorial operator returns a real number to allow a greater range.

fit

   fit <function> <datafile> {using x:y{:dy}} <parameter file>     or
   fit <function> <datafile> {using x:y{:dy}} via <var1>, <var2>, ...

   varname = value

   varname = value       # FIXED

After each iteration step a detailed info is given about the fit's state both on the screen and on a logfile "fit.log". This file will never be erased but always appended so that the fit's history isn't lost. After each iteration step the fit may be interrupted by pressing ctrl-C (any key BUT ctrl-C under MSDOS). Then you have the possibility of stopping (and accepting the current parameter values) or continuing the fit or of executing a gnuplot command specified by an environment variable FIT_SCRIPT. E.g. a plot command or LOADing some file may be useful.

Special GNUPLOT variables:

   FIT_INDEX: This variable always contains the current data point number
              during execution starting with 1. You may use it in your fit
              function to implement multiple-branch-fits.
   FIT_SKIP:  You may specify a positive integer to always skip i data points
              during fitting. This increases execution speed by the
              price of less exact results.
   FIT_LIMIT: may be specified to change the default epsilon limit (1e-5).
              When the sum of squared residuals changes between 2 iteration
              steps by less than a factor of this number, the fit is
              considered as 'converged'.

 Environment variables:
   FIT_LOG    changes the logfile's path from './fit.log' (write permission
              is necessary).
   FIT_SCRIPT specifies a command to be executed after an user interrupt

 Examples:
   f(x) = a*x**2 + b*x + c
   fit f(x) 'measured.dat' 'start.par'
   fit f(x) 'measured.dat' using 3:7 'start.par'
   fit f(x) './data/trash.dat' using 1:2:3 via a, b, c

 SEE ALSO: update

help

        help {<topic>}

if

Syntax:

        if (<condition>) <command-line>

Examples:

     pi=3
     if (pi!=acos(-1)) pause 0 "?Fixing pi!";pi=acos(-1);show variables

     ?Fixing pi!

             Variables:
             pi = 3.14159

     if (1==2) pause 0 "Never see this";pause 0 "Or this either"

load

The load command must be the last command on the line.

Syntax:

        load "<input-file>"

Examples:

        load 'work.gnu'
        load "func.dat"

call

The call command must be the last command on the line.

Syntax:

        call "<input-file>" <parameter-0> <parm-1> ... <parm-9>

Examples:

if the file 'calltest.gp' contains the line:

    pause 0 "p0=$0 p1=$1 p2=$2 p3=$3 p4=$4 p5=$5 p6=$6 p7=x$7x"

    call 'calltest.gp' "abcd" 1.2 + "'quoted'" -- "$2"

    p0=abcd p1=1.2 p2=+ p3='quoted' p4=- p5=- p6=$2 p7=xx

pause

Syntax:

        pause <time> {"<string>"}

Note: Since pause is not part of the plot it may interact with different device drivers differently (depending upon how text and graphics are mixed).

Examples:

        pause -1    # Wait until a carriage return is hit
        pause 3     # Wait three seconds
        pause -1  "Hit return to continue"
        pause 10  "Isn't this pretty?  It's a cubic-spline."

plot

Syntax:

       plot {ranges} {<function> | {"<datafile>" {using ...}}}
                    {title} {style} {, <function> {title} {style}...}

       splot {ranges} {<function> | {"<datafile>" {index i} {using ...}}}
                    {title} {style} {, <function> {title} {style}...}

plot and splot commands can be as simple as

        plot sin(x)

        splot x * y

 plot [t=1:10] [-pi:pi*2] tan(t), "data.1" using 2:3 with lines,
       t**2 with points

data-file

For plots the x value may be omitted, and for splots the x and y values may be omitted. In either case the omitted values are assigned the current coordinate number. Coordinate numbers start at 0 and are incremented for each data point read.

To specify other formats, see plot datafile using.

In the plot command, blank lines in the data file cause a break in the plot. There will be no line drawn between the preceding and following points if the plot style is lines or linespoints (see plot style). This does not change the plot style, as would plotting the data as separate curves.

This example compares the data in the file population.dat to a theoretical curve:

        pop(x) = 103*exp((1965-x)/10)
        plot [1960:1990] 'population.dat', pop(x)

        # Gnu population in Antarctica since 1965
        1965   103
        1970   55
        1975   34
        1980   24
        1985   10

Implicitly, there are two types of 3-d datafiles. If all the isolines are of the same length, the data is assumed to be a grid data, i.e., the data has a grid topology. Cross isolines in the other parametric direction (the ith cross isoline passes through the ith point of all the provided isolines) will also be drawn for grid data. (Note contouring is available for grid data only.) If all the isolines are not of the same length, no cross isolines will be drawn and contouring that data is impossible.

For splot, data files may contain more than one mesh and by default all meshes are plotted. Meshes are separated from each other, in the file, by double blank lines. To control and splot a single mesh from a multi mesh file, use the index modifier. See splot index for more.

For splot if 3-d datafile and using format (see splot datafile using) specify only z (height field), a non parametric mode must be specified. If, on the other hand, x, y, and z are all specified, a parametric mode should be selected (see set parametric) since data is defining a parametric surface.

A simple example of plotting a 3-d data file is

        set parametric
        splot 'glass.dat'

        set noparametric
        splot 'datafile.dat'

        # The valley of the Gnu.
        10
        10
        10

        10
        5
        10

        10
        1
        10

        10
        0
        10

On some computer systems with a popen function (UNIX), the datafile can be piped through a shell command by starting the file name with a '<'. For example:

        pop(x) = 103*exp(-x/10)
        plot "< awk '{print $1-1965, $2}' population.dat", pop(x)

        plot "< awk '$0 !~ /^#/ {print $1-1965, $2}' population.dat"

        plot 'population.dat' thru p(x)

using

using

Syntax:

        plot "datafile" { using { <ycol> |
                                  <xcol>:<ycol> |
                                  <xcol>:<ycol>:<ydelta> |
                                  <xcol>:<ycol>:<xdelta> |
                                  <xcol>:<ycol>:<boxwidth> |
                                  <xcol>:<ycol>:<ylow>:<yhigh> |
                                  <xcol>:<ycol>:<xlow>:<xhigh> |
                                  <xcol>:<ycol>:<xdelta>:<ydelta> |
                                  <xcol>:<ycol>:<ydelta>:<boxwidth> |
                                  <xcol>:<ycol>:<ylow>:<yhigh>:<boxwidth> |
                                  <xcol>:<ycol>:<xlow>:<xhigh>:<ylow>:<yhigh>}
                                {"<scanf string>"} } ...

        splot "datafile" { using { <xcol>:<ycol>:<zcol> | <zcol> }
                                 {"<scanf string>"} } ...

If x, y and/or z is time data (dates-times), the columns occupied by the time (any character, spaces included, is allowed in format string) counts for one column. The "scanf-string" will not work with timeseries. See also set timefmt. Time Data Demo

If yerrorbars (see also plot errorbars) are used for plots, ydelta (for example, a +/- error) should be provided as the third column, or ylow and yhigh as third and fourth columns.

If xerrorbars (see also plot errorbars) are used for plots, xdelta (for example, a +/- error) should be provided as the third column, or xlow and xhigh as third and fourth columns.

If xyerrorbars or boxxyerrorbars (see also plot errorbars) are used for plots, xlow and xhigh may be provided as third and fourth columns and ylow and yhigh may be provided as fifth and sixth columns. It is also possible to have xdelta and ydelta in the third and fourth columns, respectively.

If boxes are used for plots, the third column is used to specify the width of the box. If boxerrorbars are used, the fourth column (if "ydelta" is third col), or the fifth column (if "ylow" and "yhigh" are third and fourth cols) may be used for the box width. See boxerrorbars or set style for more details. Note that boxerrorbars is only used for data with errors in y. Each box starts at the x axis (boxxyerrorbars has different behavior). Errorbar demos.

Scanf strings override any <xcol>:<ycol>(:<zcol>) choices, except for ordering of input, e.g.,

        plot "datafile" using 2:1 "%lf%*lf%lf"

If the scanf string is omitted, the default is generated based on the <xcol>:<ycol>(:<zcol>) choices. If the using option is omitted, "%lf%lf" is used for plot ("%lf%lf%lf%lf" for errorbars plots) and "%lf%lf%lf" is used for splot.

Examples:

        plot "MyData" using "%*lf%lf%*20[^\n]%lf" with lines

        n=3;
        plot "MyData", "MyData" using n

        splot "glass.dat" using 1

Note: GNUPLOT first reads a line of the data file into a buffer and then does a

        sscanf(input_buffer, scanf_string, &x, &y{, &z});

errorbars

In the default situation, GNUPLOT expects to see three or six numbers on each line of the data file, either (x, y, ydelta), (x, y, ylow, yhigh), (x, y, xdelta), (x, y, xlow, xhigh), (x, y, xdelta, ydelta), or (x, y, xlow, xhigh, ylow, yhigh). The x coordinate must be specified. The order of the numbers must be exactly as given above. Data files in this format can easily be plotted with error bars:

        plot "data.dat" with errorbars (or yerrorbars)
        plot "data.dat" with xerrorbars
        plot "data.dat" with xyerrorbars
        plot "data.dat" with yerrorbars

If autoscaling is on, the x and/or y range will be adjusted to fit the error bars.

The using option may be used to specify how columns of the data file are to be assigned to x, y, ydelta, ylow and yhigh, xdelta, xlow and xhigh. The x column must be provided and both the x and y columns must appear before the errorbar columns. If three column numbers are given, they are x, y, and ydelta or xdelta. If four columns are given, they are x, y, ylow, and yhigh or x, y, xlow, and xhigh or x, y, xdelta, ydelta.

Examples:

        plot "data.dat" using 1:2:3:4 with errorbars (or yerrorbars)
        plot "data.dat" using 3:2:6 with xerrorbars 
        plot "data.dat" using 3:4:8:7 with xyerrorbars

See also plot using and plot style.

parametric

        plot sin(t),t**2

        splot cos(u)*cos(v),cos(u)*sin(v),sin(u)

Ranges take on a different meaning when in parametric mode. The first range on the plot command is the trange, the next is the xrange, and the last is the yrange. For splot the order is urange, vrange, xrange, yrange, and finally zrange. The following plot command shows setting the trange to [-pi:pi], the xrange to [-1.3:1.3] and the yrange to [-1:1] for the duration of the plot:

        plot [-pi:pi] [-1.3:1.3] [-1:1] sin(t),t**2

        plot sin(t),t**2 title 'Parametric example' with linespoints

ranges

Ranges may be provided on the plot and splot command line and affect only that plot, or in the set xrange, set yrange, etc., commands, to change the default ranges for future plots.

Syntax:

        [{<dummy-var> =} {<xmin> : <xmax>}] { [{<ymin> : <ymax>}] }

Both the min and max terms are optional. The ':' is also optional if neither a min nor a max term is specified. This allows '[ ]' to be used as a null range specification.

Specifying a range in the plot command line turns autoscaling for that axis off for that plot. Using one of the set range commands turns autoscaling off for that axis for future plots, unless changed later. (See set autoscale).

With time data, provide the ranges in the samme manner as in the datafile within quotes (uses the timefmt string to read the value).

Examples:

This uses the current ranges:

        plot cos(x)

        plot [-10:30] sin(pi*x)/(pi*x)

        plot [t = -10 :30]  sin(pi*t)/(pi*t)

        plot [-pi:pi] [-3:3]  tan(x), 1/x

        plot [ ] [-2:sin(5)*-8] sin(x)**besj0(x)

        plot [:200] [-pi:]  exp(sin(x))

        splot [0:3] [1:4] [-1:1] x*y

        set xrange ["1/6/93 12:00":"5/6/93 12:00"]

index

Example:

splot "data1" index 2 with points

will splot the third mesh in file data1 with points. splot with indices demo.

style

The errorbars (or yerrorbars) and xerrorbars styles are only relevant to 2-d data file plotting. It is treated like points for splots and function plots. For data plots, errorbars is like points, except that a vertical or horizontal error bar is also drawn: for each point (x,y), a line is drawn from (x,ylow) to (x,yhigh) or (xlow,y) to (xhigh,y). A tic mark is placed at the ends of the error bar. The (ylow, yhigh) or (xlow,xhigh) values are read from the data file's columns, as specified with the using option to plot. See plot errorbars for more information.

The boxes style is only relevant to 2-d plotting. Another style called boxerrorbars is also available and is only relevant to 2-d data file plotting. This style is a combination of the boxes and errorbars styles. The boxes style draws a box centred about the given x coordinate from the yaxis to the given y coordinate. The width of the box is obtained in one of three ways. First, if a data file has a fifth column, this will be used to set the width of the box. Columns 3 and 4 (for boxerrorbars) are necessary but ignored in this instance. Secondly, if a width has been set using the set boxwidth command, this will be used. Otherwise the width of each box will be calculated automatically so that it touches the adjacent boxes.

The boxes style is only relevant to 2-d plotting. It draws a box centred about the given x coordinate from the yaxis to the given y coordinate. The width of the box is obtained in one of three ways. If a data file has a third column, this will be used to set the width of the box. Otherwise, if a width has been set using the set boxwidth command, this will be used. Otherwise the width of each box will be calculated automatically so that it touches the adjacent boxes. Another style called boxerrorbars is also available and is only relevant to 2-d data file plotting. This style is a combination of the boxes and errorbars styles. The boxwidth will come from the fourth column if the y errors are in the form of "ydelta" and the boxwidth was not previously set equal to -2.0 (set boxwidth -2.0) or from the fifth column if the y errors are in the form of "ylow yhigh". The boxwidth = -2.0 is for the special case of 4-column data and the y errors are in the form of "ylow yhigh". The boxwidth will be calculated automatically so that each box touches the adjacent boxes. The width will also be automatically calculated if 3-column data is used. The boxxyerrorbars style is like the xyerrorbars option except that a box with width (xhigh-xlow) and height (yhigh-ylow) is drawn instead of a cross of that size.

For 2-d data with more than two columns, gnuplot will be picky about the allowed plot styles. For three columns only xerrorbars, boxes, errorbars (or yerrorbars), and boxerrorbars are allowed. If another plot style is used, the style will be changed to yerrorbars. The boxerrorbars style will calculate the boxwidth automatically. For four columns only xerrorbars, xyerrorbars, boxxyerrorbars, boxerrorbars, and errorbars (or yerrorbars) are allowed. An illegal plot style will be changed to yerrorbars. Five column data allows only the boxerrorbars style. An illegal style will be changed to boxerrorbars before plotting. Six and seven column data only allows the xyerrorbars and boxxyerrorbars styles. Illegal styles will be changed to xyerrorbars before plotting. Use the using option for plot to setup the correct number of columns for the style you want.

The steps and fsteps styles is only relevant to 2-d plotting. The steps style connects consecutive points with two line segments: the first from (x1,y1) to (x2,y1) and the second from (x2,y1) to (x2,y2). The fsteps: (x1,y1) to (x1,y2) and (x1,y2) to (x2,y2). Steps Demo.

Default styles are chosen with the set function style and set data style commands.

By default, each function and data file will use a different line type and point type, up to the maximum number of available types. All terminal drivers support at least six different point types, and re-use them, in order, if more than six are required. The LaTeX driver supplies an additional six point types (all variants of a circle), and thus will only repeat after twelve curves are plotted with points.

If desired, the style and (optionally) the line type and point type used for a curve can be specified.

Syntax:

        with <style> {<linetype> {<pointtype>}}

Examples:

This plots sin(x) with impulses:

        plot sin(x) with impulses

        splot x*y w points, x**2 + y**2

        plot [ ] [-2:5] tan(x), "data.1" with l

        plot 'leastsq.dat' w i

        plot "population" with boxes

        plot 'exper.dat' w lines, 'exper.dat' w errorbars

This plots x**2 + y**2 and x**2 - y**2 with the same line type:

        splot x**2 + y**2 with line 1, x**2 - y**2 with line 1

        plot sin(x) with linesp 1 3, cos(x) with linesp 1 4

        plot "data" with points 1 3

See set style to change the default styles.

title

Syntax:

        title "<title>"

Examples:

This plots y=x with the title 'x':

        plot x

        splot "glass.dat" title 'surface of revolution'

        plot x**2 title "x^2", "data.1" t 'measured data'

Example:

       set polar
       plot my_function(x), 1 notitle

print

Syntax:

        print <expression>

pwd

Syntax:

        pwd

quit

replot

Arguments specified after a replot command will be added onto the last plot (splot) command (with an implied ',' separator) before it is repeated. replot accepts the same arguments as the plot (splot) commands except that ranges cannot be specified. See command line-editing for ways to edit the last plot (splot) command.

reread

reset

save

Syntax:

        save  {<option>} "<filename>"

saved files are written in text format and may be read by the load command.

The filename must be enclosed in quotes.

Examples:

        save "work.gnu"
        save functions 'func.dat'
        save var 'var.dat'
        save set "options.dat"

set-show

The show command shows their settings. show all shows all the settings.

angles
arrow
autoscale
border
boxwidth
clabel
clip
cntrparam
contour
data style
dgrid3d
dummy
format
function style
functions
grid
hidden3d
isosamples
key
keytitle
label
logscale
mapping
offsets
output
parametric
pointsize
polar
rrange
samples
size
style
surface
terminal
tics
time
timefmt
title
trange
urange
variables
view
vrange
xdata
xlabel
xmargin
xrange
xtics
mxtics
mytics
xdtics
xmtics
xzeroaxis
ydata
ylabel
yrange
ytics
ydtics
ymtics
yzeroaxis
zdata
zero
zeroaxis
zlabel
zrange
ztics
zdtics
zmtics

angles

Syntax:

        set angles { degrees | radians }
        show angles

arrow

Syntax:

         set arrow {<tag>} {from <sx>,<sy>{,<sz>}}
                           {to <ex>,<ey>{,<ez>}} {{no}head}
         set noarrow {<tag>}
         show arrow

Arrows outside the plotted boundaries are permitted but may cause device errors.

Examples:

To set an arrow pointing from the origin to (1,2), use:

         set arrow to 1,2

         set arrow 3 from -10,4,2 to -5,5,3

         set arrow 3 from 1,1,1 nohead

         set noarrow 2

         set noarrow

         show arrow

autoscale

When autoscaling, the plot range is automatically computed and the dependent axis (y for a plot and z for splot) is scaled to include the range of the function or data being plotted.

If autoscaling of the dependent axis (y or z) is not set, the current y or z range is used.

See set yrange or set zrange.

Autoscaling the independent variables (x for plot and x,y for splot) is a request to set the domain to match any data file being plotted. If there are no data files then autoscaling an independent variable has no effect. In other words, in the absence of a data file, functions alone do not affect the x range (or the y range if plotting z = f(x,y)).

See set xrange, or set yrange.

The behavior of autoscaling remains consistent in parametric mode, however, there are more dependent variables and hence more control over x, y, and z plot scales. In parametric mode, the independent or dummy variable is t for plots and u,v for splots. Autoscale in parametric mode, then, controls all ranges (t, u, v, x, y, and z) and allows x, y, and z to be fully autoscaled.

See set parametric.

Syntax:

        set autoscale <axes>
        set noautoscale <axes>
        show autoscale

Examples:

This sets autoscaling of the y axis. x axis autoscaling is not affected.

        set autoscale y

        set autoscale xy

        set autoscale

        set noautoscale

        set noautoscale z

parametric mode

When there is a mix of data files and functions, the xrange of the functions is selected as that of the data files if autoscale is true for x. While this keeps the behavior compatible with non-parametric plotting, it may not be retained in the future. The problem is that, in parametric mode, the x and y ranges are not as distinguishable as in the non-parametric mode and this behavior may not be the most useful.

For completeness a last command set autoscale t is accepted. However, the effect of this "scaling" is very minor. When GNUPLOT determines that the t range would be empty it makes a small adjustment if autoscaling is true. Otherwise, GNUPLOT gives an error. Such behavior may, in fact, not be very useful and the command set autoscale t is certainly questionable.

splot extends the above idea similarly. If autoscaling is set then x, y, and z ranges are computed and each axis scaled to fit the resulting data.

border

       SOUTH    0th bit
       WEST    1st bit
       NORTH   2nd bit
       EAST    3rd bit

Syntax:

        set border    (turns on all borders)
        set border 3  (only SOUTHWEST borders)
        set border 12 (only NORTHEAST borders with tics on top and right)
        set noborder
        show border

boxwidth

If a data file is plotted without the width being specified in the third to fifth columns, or a function is plotted, the width of each box is set by the set boxwidth command. If a width is given after the set boxwidth command then this is used as the width. Otherwise the width of each box will be calculated automatically so that it touches the adjacent boxes. Four-column data may have the width be calculated automatically if the width is first set to -2.0. Otherwise, the fourth column will be interpreted as the box width. See boxerrorbars or set style for more details.

Syntax:

         set boxwidth {<width>}
         show boxwidth

         set boxwidth
         set boxwidth -2  (4-col data)

clabel

Syntax:

        set clabel
        set noclabel
        show clabel

clip

Syntax:

        set clip <clip-type>
        set noclip <clip-type>
        show clip

The points clip type forces GNUPLOT to clip (actually, not plot at all) data points that fall within but too close to the boundaries (this is so the large symbols used for points will not extend outside the boundary lines). Without clipping points near the boundaries may look bad; try adjusting the x and y ranges.

Setting the one clip type causes GNUPLOT to plot the line segments which have only one of the two endpoints within the plotting region. Only the in-range portion of the line is drawn. The alternative is to not draw any portion of the line segment.

Some lines may have both endpoints out of range, but pass through the plotting area. Setting the two clip-type allows the visible portion of these lines to be drawn.

In no case is a line drawn outside the plotting area.

The defaults are noclip points, clip one, and noclip two.

To check the state of all forms of clipping, use

        show clip

       set clip
       set noclip

cntrparam

Syntax:

 set cntrparam { { linear | cubicspline | bspline } |
    points <n> |
    order <n>  |
    levels { [ auto ] <n> |
    discrete <z1>,<z2>, ... |
    incremental {<start>, <incr>{, <end>} } }

    set cntrparam bspline
    set cntrparam points 7
    set cntrparam order 10
    set cntrparam levels auto 5                   # 5 automatic levels
    set cntrparam levels discrete .1,1/exp(1),.9  # 3 discrete at .1,.37,.9
    set cntrparam levels incremental  0,.1,.4
    # 5 incremental levels at 0, .1, .2, .3 and .4
    set cntrparam levels 10
    # sets n = 10 retaining current setting of auto, discr. and
    # increment's start and increment value, while changing end
    set cntrparam levels incremental 100,50
    # set start = 100 and increment = 50, retaining n levels

linear, cubicspline, bspline - Controls type of approximation or interpolation. If linear, then the contours are drawn piecewise linear, as extracted from the surface directly. If cubicspline, then piecewise linear contours are interpolated to form a somewhat smoother contours, but which may undulate. The third option is the uniform bspline, which only approximates the piecewise linear data but is guaranteed to be smoother.

points - Eventually all drawings are done with piecewise linear strokes. This number controls the number of points used to approximate a curve. Relevant for cubicspline and bspline modes only.

order - Order of the bspline approximation to be used. The bigger this order is, the smoother the resulting contour. (Of course, higher order bspline curves will move further away from the original piecewise linear data.) This option is relevant for bspline mode only. Allowed values are integers in the range from 2 (linear) to 10.

levels - Number of contour levels, 'n'. Selection of the levels is controlled by 'auto' (default), 'discrete', and 'incremental'. For 'auto', if the surface is bounded by zmin and zmax then contours will be generated from zmin+dz to zmax-dz in steps of size dz, where dz = (zmax - zmin) / (levels + 1). For 'discrete', contours will be generated at z = z1, z2 ... as specified. The number of discrete levels is limited to MAX_DISCRETE_LEVELS, defined in plot.h to be 30. If 'incremental', contours are generated at <n> values of z beginning at <start> and increasing by <increment>. Contours Demo and contours with User Defined Levels.

contour

Syntax:

        set contour { base | surface | both }
        set nocontour

See also set cntrparam for the parameters that affect the drawing of contours. Contours Demo and contours with User Defined Levels.

data style

Syntax:

        set data style
        show data style
        set data style <style-choice>

dgrid3d

Syntax:

        set dgrid3d {,{<row_size>}{,{<col_size>}{,<norm>}}}
        set nodgrid3d

       set dgrid3d 10,10,2
       set dgrid3d ,,4

By default this option is disabled. When enabled, 3d data read from a file is always treaded as a scattered data set. A grid with dimensions derived from a bounding box of the scattered data and size as specified by the row/col_size above is created for plotting and contouring. The grid is equally spaced in x and y while the z value is computed as a weighted average of the scattered points distance to the grid points. The closer the scatter points to a grid point are the more effect they have on that grid point. The third, norm, parameter controls the "meaning" of the distance, by specifying the distance norm. This distance computation is optimized for powers of 2 norms, specifically 1, 2, 4, 8, and 16, but any nonnegative integer can be used.

This dgrid3d option is a simple low pass filter that converts scattered data to a grid data set. More sophisticated approaches to this problem exists and should be used as a preprocess to and outside gnuplot if this simple solution is found inadequate. Dgrid3d Demo.

dummy

        set dummy t
        plot sin(t), cos(t)

        set dummy <dummy-var>{,<dummy-var>}
        show dummy

        set dummy u,v
        set dummy ,s

The set parametric command also changes the dummy variables (to t for plot and u,v for splots).

format

Syntax:

        set format {<axes>} {"<format-string>"}
        show format

For plot newlines (\n) is accepted in the xaxis format string, and for splot newlines is allowed for both x- and yaxis format strings.

See also set xtics and set ytics for more control over tic labels.

function style

Syntax:

        set function style
        show function style
        set function style <style-choice>

functions

Syntax:

        show functions

grid

Syntax:

        set grid {mxtics OR mytics}
        set nogrid
        show grid

hidden3d

When this flag is set both the surface hidden portion and possibly its hidden contours (see set contour) as well as the hidden grid will be removed. Labels and arrows are always visible and are unaffected by this command.

Each surface has its hidden parts removed with respect to itself and to other surfaces, if more than one surface is plotted. This mode is meaningful when surfaces are plotted using line style drawing only.

Syntax:

        set hidden3d
        set nohidden3d
        show hidden3d

isosamples

The isoline density of surfaces may be changed by the set isosamples command. By default, sampling is set to 10 isolines per u or v axis. A higher sampling rate will produce more accurate plots, but will take longer. This parameter has no effect on data file plotting.

Syntax:

        set isosamples <iso_1> {,<iso_2>}
        show isosamples

When a surface plot is being done without the removal of hidden lines, set samples also has an effect on the number of points being evaluated. See set samples.

key

Syntax:

        set key
        set key <x>,<y>{,<z>}
        set key <keyword> {<keyword> {<justification>}}
        set nokey
        show key

Some or all of the key may be outside of the plot boundary, although this may interfere with other labels and may cause an error on some devices. If you use the keywords outside or below, gnuplot makes space for the keys and the plot becomes smaller. Putting keys outside to the right, they occupy as few colums as possible, and putting them below, as many culumns as possible (depending of the length of the labels). Thus stealing as little space from the plot as possible.

Examples:

This places the key at the default location:

        set key

        set nokey

        set key 2,3.5,2

        set key below

        set key left bottom Left

        set key

keytitle

Syntax:

        set keytitle "<string>"

label

Syntax:

         set label {<tag>} {"<label_text>"} {at <x>,<y>{,<z>}}
                           {<justification>}
         set nolabel {<tag>}
         show label

By default, the text is placed flush left against the point x,y,z. To adjust the way the label is positioned with respect to the point x,y,z, add the parameter <justification>, which may be left, right or center, indicating that the point is to be at the left, right or center of the text. Labels outside the plotted boundaries are permitted but may interfere with axes labels or other text.

If one (or more) axis is timeseries, the coordiate should be given as a quoted time string according to the timefmt-format string. See set {x,y,z}data and set timefmt.

Examples:

To set a label at (1,2) to "y=x" use:

         set label "y=x" at 1,2

         set label 3 "y=x^2" at 2,3,4 right

         set label 3 center

         set nolabel 2

         set nolabel

         show label

         set label "Harvest" at "25/8/93",1

logscale

Syntax:

        set logscale <axes> <base>
        set nologscale <axes>
        show logscale

Examples:

To enable log scaling in both x and z axes:

       set logscale xz

       set logscale y 2

       set nologscale z

mapping

        set mapping { cartesian | spherical | cylindrical }

        x = cos( theta ) * cos( phi )
        y = sin( theta ) * cos( phi )
        z = sin( phi )

        x = cos( theta )
        y = sin( theta )
        z = z

offsets

Syntax:

        set offsets <left>, <right>, <top>, <bottom>
        show offsets

output

Syntax:

        set output {"<filename>"}
        show output

On machines with popen functions (UNIX), output can be piped through a shell command if the first letter of the filename is '|'. For instance,

Syntax:

        set output "|lpr -Plaser filename"
        set output "|lp -dlaser filename"

parametric

In 2-d plotting, a parametric function is determined by a pair of parametric functions operating on a parameter. An example of a 2-d parametric function would be plot sin(t),cos(t) (which defines a circle).

For 3-d plotting, the surface is described as x=f(u,v), y=g(u,v), z=h(u,v). Therefore a triplet of functions are required. An example of 3-d parametric function would be cos(u)*cos(v),cos(u)*sin(v),sin(u) (which defines a sphere). It takes three parametric function specifications in terms of the parametric dummy arguments to describe a single graph.

The total set of possible plots is a superset of the simple f(x) style plots, since the two (three) functions can describe the x and y (and z) values to be computed separately. In fact, plots of the type t,f(t) (u,v,f(u,v)) are equivalent to those produced with f(x) when the x values are computed using the identity function as the first function.

Note that the order the parametric functions are specified is xfunction, yfunction (and zfunction) and that each operates over the common parametric domain.

Also, the set parametric function implies a new range of values. Whereas the normal f(x) and f(x,y) style plotting assume an xrange and yrange (and zrange), the parametric mode additionally specifies a trange, urange, and vrange. These ranges may be set directly with set trange, set urange and set vrange, or by specifying the range on the plot or splot commands. Currently the default range for these parametric variables is [-5:5]. Setting the ranges to something more meaningful is expected.

pointsize

Please note that the pointsize setting is not supported with all terminal types.

polar

The command set nopolar changes the meaning of the plot back to the default rectangular coordinate system. The range of x is changed from whatever it was to [-10:10].

The set polar command is not supported for splots. See the set mapping command for similar functionality for splots.

While in polar coordinates the meaning of an expression in x is really r = f(x), where x is an angle of rotation. The xrange controls the domain (the angle) of the function, and the yrange controls the range (the radius). The plot is plotted in a rectangular box, and the x and y axes are both in units of the radius. Thus, the yrange controls both dimensions of the plot output. The tics and units are written along the axes rather than at the left and bottom. These unit are offset by <rmin> specified by the rrange (See set rrange). It is not possible to specify different output dimensions in the x or y directions. The yrange can be used to shift the plot diagonally to display only the first or third quadrants.

Syntax:

        set polar
        set nopolar
        show polar

        set polar
        plot x*sin(x)
        plot [-2*pi:2*pi] [-3:3] x*sin(x)

rrange

This range may also be specified on the plot command line when in polar mode.

Syntax:

        set rrange [{<rmin> : <rmax>}]

Both the <rmin> and <rmax> terms are optional. Anything omitted will not be changed, so

        set rrange [:10]

samples

Syntax:

        set samples <samples_1> {,<samples_2>}
        show samples

When a surface plot is being done without the removal of hidden lines, the value of samples specifies the number of samples that are evaluated per iso line. Each iso-v line will have <sample_1> samples and each iso-u line will have <sample_2> samples. If you only specify <samples_1>, <samples_2> will be set to the same value as <samples_1>. See also set isosamples.

size

Syntax:

        set size {<xscale>,<yscale>}
        show size

Examples:

To set the size to normal size use:

        set size

        set size 0.5,0.5

        set size 0.721,1.0

        show size

style

The errorbars (or yerrorbars), xerrorbars, xyerrorbars styles are only relevant to 2-d data file plotting. It is treated like points for splots and function plots. For data plots, errorbars is like points, except that a vertical or horizontal error bar is also drawn: for each point (x,y), a line is drawn from (x,ylow) to (x,yhigh) or (xlow,y) to (xhigh,y). A tic mark is placed at the ends of the error bar. The (ylow, yhigh) or (xlow,xhigh) values are read from the data file's columns, as specified with the using option to plot. See plot errorbars for more information.

The boxes style is only relevant to 2-d plotting. It draws a box centred about the given x coordinate from the yaxis to the given y coordinate. The width of the box is obtained in one of three ways. If a data file has a third column, this will be used to set the width of the box. Otherwise, if a width has been set using the set boxwidth command, this will be used. Otherwise the width of each box will be calculated automatically so that it touches the adjacent boxes. Another style called boxerrorbars is also available and is only relevant to 2-d data file plotting. This style is a combination of the boxes and errorbars styles. The boxwidth will come from the fourth column if the y errors are in the form of "ydelta" and the boxwidth was not previously set equal to -2.0 (set boxwidth -2.0) or from the fifth column if the y errors are in the form of "ylow yhigh". The boxwidth = -2.0 is for the special case of 4-column data and the y errors are in the form of "ylow yhigh". The boxwidth will be calculated automatically so that each box touches the adjacent boxes. The width will also be automatically calculated if 3-column data is used. The boxxyerrorbars style is like the xyerrorbars option except that a box with width (xhigh-xlow) and height (yhigh-ylow) is drawn instead of a cross of that size.

For 2-d data with more than two columns, gnuplot will be picky about the allowed plot styles. For three columns only xerrorbars, boxes, errorbars (or yerrorbars), and boxerrorbars are allowed. If another plot style is used, the style will be changed to yerrorbars. The boxerrorbars style will calculate the boxwidth automatically. For four columns only xerrorbars, xyerrorbars, boxxyerrorbars, boxerrorbars, and errorbars (or yerrorbars) are allowed. An illegal plot style will be changed to yerrorbars. Five column data allows only the boxerrorbars style. An illegal style will be changed to boxerrorbars before plotting. Six and seven column data only allows the xyerrorbars and boxxyerrorbars styles. Illegal styles will be changed to xyerrorbars before plotting. Use the using option for plot to setup the correct number of columns for the style you want.

The steps and fsteps styles is only relevant to 2-d plotting. The steps style connects consecutive points with two line segments: the first from (x1,y1) to (x2,y1) and the second from (x2,y1) to (x2,y2). The fsteps: (x1,y1) to (x1,y2) and (x1,y2) to (x2,y2).

Default styles are chosen with the set function style and set data style commands. See plot style for information about how to override the default plotting style for individual functions.

Syntax:

        set function style <style>
        set data style <style>
        show function style
        show data style

surface

Syntax:

        set surface
        set nosurface
        show surface

terminal

Syntax:

        set terminal {<terminal-type>}
        show terminal

Use set output to redirect this output to a file or device.

Several terminals have additional options. For example, see dumb, iris4d, hpljii or postscript.

aifm
atari ST
dumb
epson
gpic
hpljii
latex
imagen
linux
iris4d
mf
mif
nec-cp6
pbm
pcl5
postscript
enhanced postscript
pslatex
fig
regis
table
uniplex
windows

aifm

Syntax:

        set terminal aifm {<color>}
                                {"<fontname>"} {<fontsize>}

Also, since AI does not really support multiple pages, multiple graphs will be output directly on one another. However, each graph will be grouped individually, making it easy to separate them inside AI (just pick them up and move them).

Examples:

        set term aifm
        set term aifm 22
        set size 0.7,1.4
        set term aifm color "Times-Roman" 14

atari ST

Examples:

       set terminal atari 4 # (use small (6x6) font)
       set terminal atari 6 0 # (set monochrome screen to white on black)
       set terminal atari 13 0 fff f00 f0 f ff f0f ff0
       # (set first eight colors to black, white, green, blue, cyan, \
         purple, and yellow and use large font (8x16).)

dumb

Syntax:

        set terminal dumb {<xsize> <ysize>}

Examples:

        set term dumb
        set term dumb 79 49 # VGA screen--why would anyone want to do that?

epson

       copy file /b lpt1:

gpic

A simple graph can be formatted using

     groff -p -mpic -Tps file.pic > file.ps.

   set ylab '@space 0 int from 0 to x alpha ( t ) roman d t@'

   gpic filename.pic | geqn -d@@ -Tps | groff -m[macro-package] -Tps
        > filename.ps

   .PS 8.0
   x=0;y=3
   copy "figa.pic"
   x=5;y=3
   copy "figb.pic"
   x=0;y=0
   copy "figc.pic"
   x=5;y=0
   copy "figd.pic"
   .PE

One can also achieve the same thing by the command

  set term pic x y

  .PS 6.0
  copy "trig.pic"
  .PE

hpljii

Syntax:

        set terminal hpljii {<resolution>}
        set terminal hpdj   {<resolution>}

Example:

        set terminal hpljii 150

latex

Options are: Fonts:

      default          (Roman 10 point)
      courier
      roman

      gnuplot> set term latex courier 5

imagen

Options