Master Menu ¶

1.1 Copyright ¶

    Copyright (C) 1986 - 1993, 1998, 2004, 2007  Thomas Williams, Colin Kelley
    Copyright (C) 2004-2023  various authors

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 complete modified source code. Modifications are to be distributed as patches to the released version. Permission to distribute binaries produced by compiling modified sources is granted, provided you

  1. distribute the corresponding source modifications from the
   released version in the form of a patch file along with the binaries,
  2. add special version identification to distinguish your version
   in addition to the base release version number,
  3. provide your name and address as the primary contact for the
   support of your modified version, and
  4. retain our contact information in regard to use of the base software.

Permission to distribute the released version of the source code along with corresponding source modifications in the form of a patch file is granted with same provisions 2 through 4 for binary distributions.

This software is provided "as is" without express or implied warranty to the extent permitted by applicable law.

      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.
              Gnuplot 4.0 and subsequent releases:
                 See list of contributors at head of this document.

1.2 Introduction ¶

‘Gnuplot‘ is a portable command-line driven graphing utility for Linux, OS/2, MS Windows, macOS, VMS, and many other platforms. The source code is copyrighted but freely distributed (i.e., you don’t have to pay for it). It was originally created to allow scientists and students to visualize mathematical functions and data interactively, but has grown to support many non-interactive uses such as web scripting. It is also used as a plotting engine by third-party applications like Octave. Gnuplot has been supported and under active development since 1986.

Gnuplot can generate many types of plot in 2D and 3D. It can draw using lines, points, boxes, contours, vector fields, images, surfaces, and associated text. It also supports specialized graphs such as heat maps, spider plots, polar projection, histograms, boxplots, bee swarm plots, and nonlinear coordinates.

Gnuplot supports many different types of output: interactive screen terminals (with mouse and hotkey input), direct output to pen plotters or modern printers, and output to many file formats (eps, emf, fig, jpeg, LaTeX, pdf, png, postscript, ...). Gnuplot is easily extensible to include new output modes. A recent example is support for webp animation. Mouseable plots embedded in web pages can be generated using the svg or HTML5 canvas terminal drivers.

The command language of ‘gnuplot‘ is case sensitive, i.e. commands and function names written in lowercase are not the same as those written in capitals. All command names may be abbreviated as long as the abbreviation is not ambiguous. Any number of commands may appear on a line, separated by semicolons (;). Strings may be set off by either single or double quotes, although there are some subtle differences. See ‘syntax‘ and ‘quotes‘ for more details. Example:

      set title "My First Plot";  plot 'data';  print "all done!"

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 ‘comments‘). But note that if an error occurs somewhere on a multi-line command, the parser may not be able to locate precisely where the error is and in that case will not necessarily point to the correct line.

In this document, curly braces ({}) denote optional arguments 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. In many cases, a default value of the token will be taken for optional arguments if the token is omitted, but these cases are not always denoted with braces around the angle brackets.

For built-in help on any topic, type help followed by the name of the topic or ‘help ?‘ to get a menu of available topics.

A large set of demo plots is available on the web page http://www.gnuplot.info/demo/ When run from command line, gnuplot is invoked using the syntax

      gnuplot {OPTIONS} file1 file2 ...

where file1, file2, etc. are input files as in the ‘load‘ command. Options interpreted by gnuplot may come anywhere on the line. Files are executed in the order specified, as are commands supplied by the -e option, for example

      gnuplot   file1.in   -e "reset"   file2.in

The special filename "-" is used to force reading from stdin. ‘Gnuplot‘ exits after the last file is processed. If no load files are named, ‘Gnuplot‘ takes interactive input from stdin. See help ‘batch/interactive‘ for more details. See ‘command-line-options‘ for more details, or type

      gnuplot --help

In sessions with an interactive plot window you can hit ’h’ anywhere on the plot for help about ‘hotkeys‘ and ‘mousing‘ features.

1.3 Seeking-assistance / Bugs ¶

The canonical gnuplot home page can be found at http://www.gnuplot.info

Before seeking help, please check file FAQ.pdf or the above website for a FAQ (Frequently Asked Questions) list.

Another resource for help with specific plotting problems (not bugs) is

          https://stackoverflow.com/questions/tagged/gnuplot

Bug reports and feature requests should be uploaded to the trackers at

          https://sourceforge.net/p/gnuplot/_list/tickets

Please check previous reports to see if the bug you want to report has already been fixed in a newer version.

When reporting a bug or posting a question, please include full details of the gnuplot version, the terminal type, and the operating system. A short self-contained script demonstrating the problem is very helpful.

Instructions for subscribing to gnuplot mailing lists may be found via the gnuplot development website http://sourceforge.net/projects/gnuplot

Please note that before you write to any of the gnuplot mailing lists you must first subscribe to the list. This helps reduce the amount of spam.

The address for mailing to list members is:

          gnuplot-info@lists.sourceforge.net

A mailing list for those interested in the development version of gnuplot is:

          gnuplot-beta@lists.sourceforge.net

1.4 New features in version 6 ¶

Version 6 is the latest major release in a history of gnuplot development dating back to 1986. It follows major version 5 (2015) and subsequent minor version releases 5.2 (2017) and 5.4 (2020). Development continues in a separate unreleased branch in the project git repository on SourceForge.

Some features described in this document are present only if chosen and configured at the time gnuplot is compiled from source. To determine what configuration options were used to build the particular copy of gnuplot you are running, type ‘show version long‘.

• Function blocks and scoped variables
• Special and complex-valued functions
• New plot styles
• Hulls, masks, and smoothing
• Named palettes
• New data formats
• New built-in functions and array operations
• Program control flow
• Multiplots
• New terminals and terminal options
• Watchpoints
• Week-date time support
• Other new features
• Brief summary of features introduced in version 5

     save "my_multiplot.gp"
     set multiplot
     ... various commands to generate the component plots ...
     unset multiplot
     set print "my_multiplot.gp" append
     print $GPVAL_LAST_MULTIPLOT
     unset print

1.5 Differences between versions 5 and 6 ¶

Some changes introduced in version 5 could cause certain scripts written for earlier versions of gnuplot to fail or to behave differently. There are very few such changes in version 6.

• Plot style details
• Deprecated syntax

      # use of a file containing reread to perform iteration
      N = 0;  load "file-containing-reread";
      file content:
          N = N+1
          plot func(N,x)
          pause -1
          if (N<5) reread

      do for [N=1:5] {
          plot func(N, x)
          pause -1
      }

      set dgrid3d ,,foo     # no keyword to indicate meaning of foo

      set dgrid3d qnorm foo # (example only; qnorm is not the only option)

      set style increment user

      use "set linetype" to redefine a convenient range of linetypes

      set clabel

      `set clabel "format"` is replaced by `set cntrlabel format "format"`.
      clabel is replaced by `set cntrlabel onecolor`.

      show palette fit2rgbformulae

1.6 Demos and Online Examples ¶

The ‘gnuplot‘ distribution contains a collection of examples in the ‘demo‘ directory. You can browse on-line versions of these examples produced by the png, svg, and canvas terminals at http://gnuplot.info/demos The commands that produced each demo plot are shown next to the plot, and the corresponding gnuplot script can be downloaded to serve as a model for generating similar plots.

1.7 Batch/Interactive Operation ¶

‘Gnuplot‘ may be executed in either batch or interactive modes, and the two may even be mixed together.

Command-line arguments are assumed to be either program options or names of files containing ‘gnuplot‘ commands. Each file or command string will be executed in the order specified. The special filename "-" is indicates that commands are to be read from stdin. ‘Gnuplot‘ exits after the last file is processed. If no load files and no command strings are specified, ‘gnuplot‘ accepts interactive input from stdin.

• command line options
• Examples

     -V, --version
     -h, --help
     -p, --persist
     -d, --default-settings
     -s, --slow
     -e  "command1; command2; ..."
     -c  scriptfile ARG1 ARG2 ...

      gnuplot

      gnuplot input1 input2

      gnuplot header - trailer

      gnuplot -persist -e "set title 'Sine curve'; plot sin(x)"

      gnuplot -e "a=2; s='file.png'" input.gpl

1.8 Canvas size ¶

This documentation uses the term "canvas" to mean the full drawing area available for positioning the plot and associated elements like labels, titles, key, etc. NB: For information about the HTML5 canvas terminal see ‘set term canvas‘.

‘set term <terminal_type> size <XX>, <YY>‘ controls the size of the output file, or "canvas". By default, the plot will fill this canvas.

‘set size <XX>, <YY>‘ scales the plot itself relative to the size of the canvas. Scale values less than 1 will cause the plot to not fill the entire canvas. Scale values larger than 1 will cause only a portion of the plot to fit on the canvas. Please be aware that setting scale values larger than 1 may cause problems.

Example:

      set size 0.5, 0.5
      set term png size 600, 400
      set output "figure.png"
      plot "data" with lines

These commands produce an output file "figure.png" that is 600 pixels wide and 400 pixels tall. The plot will fill the lower left quarter of this canvas.

Note: In early versions of gnuplot some terminal types used size to control the size of the output canvas. This was deprecated in version 4.

1.9 Command-line-editing ¶

Command-line editing and command history are supported using either an external gnu readline library, an external BSD libedit library, or a built-in equivalent. This choice is a configuration option at the time gnuplot is built.

The editing commands of the built-in version are given below. Please note that the action of the DEL key is system-dependent. The gnu readline and BSD libedit libraries have their own documentation.

      `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    deletes the previous character.
      DEL   deletes the current character.
      ^D    deletes current character, sends EOF if the line is empty.
      ^K    deletes from current position to the end of line.
      ^L    redraws line in case it gets trashed.
      ^U    deletes the entire line.
      ^W    deletes previous word.
      ^V    inhibits the interpretation of the following key as editing command.
      TAB   performs filename-completion.

      `History`:

      ^P    moves back through history.
      ^N    moves forward through history.
      ^R    starts a backward-search.

1.10 Comments ¶

The comment character ‘#‘ may appear almost anywhere in a command line, and ‘gnuplot‘ will ignore the rest of that line. A ‘#‘ does not have this effect inside a quoted string. Note that if a commented line ends in ’\’ then the subsequent line is also treated as part of the comment.

See also ‘set datafile commentschars‘ for specifying a comment character for data files.

1.11 Coordinates ¶

The commands ‘set arrow‘, ‘set key‘, ‘set label‘ and object allow you to draw something at an arbitrary position on the graph. This position is specified by the syntax:

      {<system>} <x>, {<system>} <y> {,{<system>} <z>}

Each <system> can either be ‘first‘, ‘second‘, ‘polar‘, ‘graph‘, ‘screen‘, or ‘character‘.

‘first‘ places the x, y, or z coordinate in the system defined by the left and bottom axes; ‘second‘ places it in the system defined by the x2,y2 axes (top and right); ‘graph‘ specifies the area within the axes—0,0 is bottom left and 1,1 is top right (for splot, 0,0,0 is bottom left of plotting area; use negative z to get to the base—see xyplane); ‘screen‘ specifies the screen area (the entire area—not just the portion selected by size), with 0,0 at bottom left and 1,1 at top right. ‘character‘ coordinates are used primarily for offsets, not absolute positions. The ‘character‘ vertical and horizontal size depend on the current font.

‘polar‘ causes the first two values to be interpreted as angle theta and radius r rather than as x and y. This could be used, for example, to place labels on a 2D plot in polar coordinates or a 3D plot in cylindrical coordinates.

If the coordinate system for x is not specified, ‘first‘ is used. If the system for y is not specified, the one used for x is adopted.

In some cases, the given coordinate is not an absolute position but a relative value (e.g., the second position in ‘set arrow‘ ... ‘rto‘). In most cases, the given value serves as difference to the first position. If the given coordinate belongs to a log-scaled axis, a relative value is interpreted as multiplier. For example,

      set logscale x
      set arrow 100,5 rto 10,2

plots an arrow from position 100,5 to position 1000,7 since the x axis is logarithmic while the y axis is linear.

If one (or more) axis is timeseries, the appropriate coordinate should be given as a quoted time string according to the timefmt format string. See xdata and timefmt. ‘Gnuplot‘ will also accept an integer expression, which will be interpreted as seconds relative to 1 January 1970.

1.12 Datastrings ¶

Data files may contain string data consisting of either an arbitrary string of printable characters containing no whitespace or an arbitrary string of characters, possibly including whitespace, delimited by double quotes. The following line from a datafile is interpreted to contain four columns, with a text field in column 3:

  1.000 2.000 "Third column is all of this text" 4.00

Text fields can be positioned within a 2-D or 3-D plot using the commands:

  plot 'datafile' using 1:2:4 with labels
  splot 'datafile' using 1:2:3:4 with labels

A column of text data can also be used to label the ticmarks along one or more of the plot axes. The example below plots a line through a series of points with (X,Y) coordinates taken from columns 3 and 4 of the input datafile. However, rather than generating regularly spaced tics along the x axis labeled numerically, gnuplot will position a tic mark along the x axis at the X coordinate of each point and label the tic mark with text taken from column 1 of the input datafile.

  set xtics
  plot 'datafile' using 3:4:xticlabels(1) with linespoints

There is also an option that will interpret the first entry in a column of input data (i.e. the column heading) as a text field, and use it as the key title for data plotted from that column. The example given below will use the first entry in column 2 to generate a title in the key box, while processing the remainder of columns 2 and 4 to draw the required line:

  plot 'datafile' using 1:(f($2)/$4) with lines title columnhead(2)

Another example:

  plot for [i=2:6] 'datafile' using i title "Results for ".columnhead(i)

This use of column headings is automated by columnheaders or ‘set key autotitle columnhead‘. See labels, ‘using xticlabels‘, title, ‘using‘, ‘key autotitle‘.

1.13 Enhanced text mode ¶

Many terminal types support an enhanced text mode in which additional formatting information can be embedded in the text string. For example, "x^2" will write x-squared as we are used to seeing it, with a superscript 2. This mode is selected by default when you set the terminal, but may be toggled afterward using "set termoption [no]enhanced", or disabled for individual strings as in ‘set label "x_2" noenhanced‘.

Note: For output to TeX-based terminals (e.g. cairolatex, pict2e, pslatex, tikz) all text strings should instead use TeX/LaTeX syntax. See ‘latex‘.

 Control      Examples        Explanation
  ^           a^x             superscript
  _           a_x             subscript
  @           @x or a@^b_{cd} phantom box (occupies no width)
  &           &{space}        inserts space of specified length
  ~           ~a{.8-}         overprints '-' on 'a', raised by .8
                              times the current fontsize
  {/Times abc}                print abc in font Times at current size
  {/Times*2 abc}              print abc in font Times at twice current size
  {/Times:Italic abc}         print abc in font Times with style italic
  {/Arial:Bold=20 abc}        print abc in boldface Arial font size 20
  \U+         \U+221E         Unicode point U+221E (INFINITY)

The markup control characters act on the following single character or bracketed clause. The bracketed clause may contain a string of characters with no additional markup, e.g. 2^{10}, or it may contain additional markup that changes font properties. Font specifiers MUST be preceded by a ’/’ character that immediately follows the opening ’{’. If a font name contains spaces it must be enclosed in single or double quotes.

Examples: The first example illustrates nesting one bracketed clause inside another to produce a boldface A with an italic subscript i, all in the current font. If the clause introduced by :Normal were omitted the subscript would be both italic and boldface. The second example illustrates the same markup applied to font "Times New Roman" at 20 point size.

     {/:Bold A_{/:Normal{/:Italic i}}}
     {/"Times New Roman":Bold=20 A_{/:Normal{/:Italic i}}}

The phantom box is useful for a@^b_c to align superscripts and subscripts but does not work well for overwriting a diacritical mark on a letter. For that purpose it is much better to use an encoding (e.g. utf8) that contains letters with accents or other diacritical marks. See encoding. Since the box is non-spacing, it is sensible to put the shorter of the subscript or superscript in the box (that is, after the @).

Space equal in length to a string can be inserted using the ’&’ character. Thus

        'abc&{def}ghi'

would produce

        'abc   ghi'.

The ’~’ character causes the next character or bracketed text to be overprinted by the following character or bracketed text. The second text will be horizontally centered on the first. Thus ’~a/’ will result in an ’a’ with a slash through it. You can also shift the second text vertically by preceding the second text with a number, which will define the fraction of the current fontsize by which the text will be raised or lowered. In this case the number and text must be enclosed in brackets because more than one character is necessary. If the overprinted text begins with a number, put a space between the vertical offset and the text (’~{abc}{.5 000}’); otherwise no space is needed (’~{abc}{.5—}’). You can change the font for one or both strings (’~a{.5 /*.2 o}’—an ’a’ with a one-fifth-size ’o’ on top—and the space between the number and the slash is necessary), but you can’t change it after the beginning of the string. Neither can you use any other special syntax within either string. Control characters must be escaped, e.g. ’~a{.8\^}’ to print â. See ‘escape sequences‘ below.

Note that strings in double-quotes are parsed differently than those enclosed in single-quotes. The major difference is that backslashes may need to be doubled when in double-quoted strings.

The file "ps_guide.ps" in the /docs/psdoc subdirectory of the gnuplot source distribution contains more examples of the enhanced syntax, as does the demo ‘enhanced_utf8.dem‘

• escape sequences

1.14 Environment ¶

A number of shell environment variables are understood by ‘gnuplot‘. None of these are required.

GNUTERM, if defined, is passed to "set term" on start-up. This can be overridden by a system or personal initialization file (see ‘startup‘) and of course by later explicit ‘set term‘ commands. Terminal options may be included. E.g.

     bash$ export GNUTERM="postscript eps color size 5in, 3in"

GNUHELP, if defined, sets the pathname of the HELP file (gnuplot.gih).

Initialization at start-up may search for configuration files $HOME/.gnuplot, and $XDG_CONFIG_HOME/gnuplot/gnuplotrc. On MS-DOS, Windows and OS/2, files in GNUPLOT or USERPROFILE are searched. For more details see ‘startup‘.

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

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

FIT_SCRIPT may be used to specify a ‘gnuplot‘ command to be executed when a fit is interrupted—see fit. FIT_LOG specifies the default filename of the logfile maintained by fit.

GNUPLOT_LIB may be used to define additional search directories for data and command files. The variable may contain a single directory name, or a list of directories separated by a platform-specific path separator, eg. ’:’ on Unix, or ’;’ on DOS/Windows/OS/2 platforms. The contents of GNUPLOT_LIB are appended to the loadpath variable, but not saved with the save and ‘save set‘ commands.

Several gnuplot terminal drivers access TrueType fonts via the gd library (see ‘fonts‘). For these terminals GDFONTPATH and GNUPLOT_DEFAULT_GDFONT may affect font selection.

The postscript terminal uses its own font search path. It is controlled by the environmental variable GNUPLOT_FONTPATH.

GNUPLOT_PS_DIR is used by the postscript driver to search for external prologue files. Depending on the build process, gnuplot contains either a built-in copy of those files or a default hardcoded path. You can use this variable to have the postscript terminal use custom prologue files rather than the default prologue files. See ‘postscript prologue‘.

1.15 Expressions ¶

In general, any mathematical expression accepted by C, FORTRAN, Pascal, or BASIC is valid. The precedence of these operators is determined by the specifications of the C programming language. White space (spaces and tabs) is ignored inside expressions.

Note that gnuplot uses both "real" and "integer" arithmetic, like FORTRAN and C. Integers are entered as "1", "-10", etc; reals as "1.0", "-10.0", "1e1", 3.5e-1, etc. The most important difference between the two forms is in division: division of integers truncates: 5/2 = 2; division of reals does not: 5.0/2.0 = 2.5. In mixed expressions, integers are "promoted" to reals before evaluation: 5/2e0 = 2.5. The result of division of a negative integer by a positive one may vary among compilers. Try a test like "print -5/2" to determine if your system always rounds down (-5/2 yields -3) or always rounds toward zero (-5/2 yields -2).

The integer expression "1/0" may be used to generate an "undefined" flag, which causes a point to be ignored. Or you can use the pre-defined variable NaN to achieve the same result. See ‘using‘ for an example.

Gnuplot can also perform simple operations on strings and string variables. For example, the expression ("A" . "B" eq "AB") evaluates as true, illustrating the string concatenation operator and the string equality operator.

A string which contains a numerical value is promoted to the corresponding integer or real value if used in a numerical expression. Thus ("3" + "4" == 7) and (6.78 == "6.78") both evaluate to true. An integer, but not a real or complex value, is promoted to a string if used in string concatenation. A typical case is the use of integers to construct file names or other strings; e.g. ("file" . 4 eq "file4") is true.

Substrings can be specified using a postfixed range descriptor [beg:end]. For example, "ABCDEF"[3:4] == "CD" and "ABCDEF"[4:*] == "DEF" The syntax "string"[beg:end] is exactly equivalent to calling the built-in string-valued function substr("string",beg,end), except that you cannot omit either beg or end from the function call.

• Complex values
• Constants
• Functions
• operators
• summation
• Gnuplot-defined variables
• User-defined variables and functions
• arrays

     set palette model HSV start 0.3 defined (0 0 1 1, 1 1 1 1)
     set cbrange [-pi:pi]
     set cbtics ("-π" -pi, "π" pi)
     set pm3d corners2color c1
     E0(z) = exp(-z)/z
     I = {0,1}
     splot '++' using 1:2:(abs(E0(x+I*y))):(arg(E0(x+I*y))) with pm3d

     1 -10 0xffaabb        # integer constants
     1.0 -10. 1e1 3.5e-1   # floating point constants
     {1.2, -3.4}           # complex constant
     "Line 1\nLine 2"      # string constant (\n is expanded to newline)
     '123\na\456'          # string constant (\ and n are ordinary characters)

     plot FOO using 1:( trim(strcol(3)) eq "A" ? $2 : NaN )

 mapped to z given the current extremes of cbrange.

    H1(nu,z) = J(nu,z) + iY(nu,z)
    H2(nu,z) = J(nu,z) - iY(nu,z)

      rand(0)     returns a pseudo random number in the open interval (0:1)
                  generated from the current value of two internal
                  32-bit seeds.
      rand(-1)    resets both seeds to a standard value.
      rand(x)     for integer 0 < x < 2^31-1 sets both internal seeds
                  to x.
      rand({x,y}) for integer 0 < x,y < 2^31-1 sets seed1 to x and
                  seed2 to y.

     time = weekdate_iso( year, week [, day] )

     # Plot data from a file with column 1 containing ISO weeks
     #     Week     cases  deaths
     #     2020-05    432       1
     calendar_date(w) = weekdate_iso( int(w[1:4]), int(w[6:7]) )
     set xtics time format "%b\n%Y"
     plot FILE using (calendar_date(strcol(1))) : 2   title columnhead

     time = weekdate_cdc( year, week [, day] )

     set datafile columnheader
     plot for [i=2:4] DATA using 1:i title columnhead(i)

     # Treat an unrecognized bin value as contributing some constant
     # prior expectation to the bin total rather than ignoring it.
     plot DATA using 1 : (valid(2) ? $2 : prior) smooth unique

      print words("\"double quotes\" or 'single quotes'")   # 3

      print words("Alexis' phone doesn't work") # 4

      s = "Keep \"'single quotes'\" or '\"double quotes\"'"
      print word(s, 2) # 'single quotes'
      print word(s, 4) # "double quotes"

    t1 = split( "A B C D" )
    t2 = split( "A B C D", " ")
    t3 = split( "A;B;C;D", ";")

    t4 = split( "A;B; C;D", "; " )

    array A = ["A", "B", , 7, "E"]
    print join(A,";")
          A;B;;;E

     plot FOO using 1:( trim(strcol(3)) eq "A" ? $2 : NaN )

    Symbol      Example    Explanation
      -           -a          unary minus
      +           +a          unary plus (no-operation)
      ~           ~a        * one's complement
      !           !a        * logical negation
      !           a!        * factorial
      $           $3        * data column in `using` specifier
      ||          |A|         cardinality of array A

    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           less than
      <=          a<=b          less than or equal to
      >           a>b           greater than
      >=          a>=b          greater than or equal to
      <<          0xff<<1       left shift unsigned
      >>          0xff>>2       right shift unsigned
      &           a&b         * bitwise AND
      ^           a^b         * bitwise exclusive OR
      |           a|b         * bitwise inclusive OR
      &&          a&&b        * logical AND
      ||          a||b        * logical OR
      =           a = b         assignment
      ,           (a,b)         serial evaluation
      .           A.B           string concatenation
      eq          A eq B        string equality
      ne          A ne B        string inequality

    Symbol       Example      Explanation
      ?:          a?b:c     ternary operation

      f(x) = 0<=x && x<1 ? sin(x) : 1<=x && x<2 ? 1/x : 1/0
      plot f(x)

      plot 'file' using 1:( $4<0 ? 1/0 : ($2+$3)/2 )

      sum [<var> = <start> : <end>] <expression>

      print sum [i=1:10] i
          55.
      # Equivalent to plot 'data' using 1:($2+$3+$4+$5+$6+...)
      plot 'data' using 1 : (sum [col=2:MAXCOL] column(col))

     GRAPH_X = (X - GPVAL_X_MIN) / (GPVAL_X_MAX - GPVAL_X_MIN)
     GRAPH_Y = (Y - GPVAL_Y_MIN) / (GPVAL_Y_MAX - GPVAL_Y_MIN)
     SCREEN_X = GPVAL_TERM_XMIN + GRAPH_X * (GPVAL_TERM_XMAX - GPVAL_TERM_XMIN)
     SCREEN_Y = GPVAL_TERM_YMIN + GRAPH_Y * (GPVAL_TERM_YMAX - GPVAL_TERM_YMIN)
     FRAC_X = SCREEN_X * GPVAL_TERM_SCALE / GPVAL_TERM_XSIZE
     FRAC_Y = SCREEN_Y * GPVAL_TERM_SCALE / GPVAL_TERM_YSIZE

      <func-name>( <dummy1> {,<dummy2>} ... {,<dummy12>} ) = <expression>

      <variable-name> = <constant-expression>

      w = 2
      q = floor(tan(pi/2 - 0.1))
      f(x) = sin(w*x)
      sinc(x) = sin(pi*x)/(pi*x)
      delta(t) = (t == 0)
      ramp(t) = (t > 0) ? t : 0
      min(a,b) = (a < b) ? a : b
      comb(n,k) = n!/(k!*(n-k)!)
      len3d(x,y,z) = sqrt(x*x+y*y+z*z)
      plot f(x) = sin(x*a), a = 0.2, f(x), a = 0.4, f(x)

      file = "mydata.inp"
      file(n) = sprintf("run_%d.dat",n)

      NaN = GPVAL_NaN
      pi  = GPVAL_pi

      a = 10
      if (exists("a")) print "a is defined"
      if (!exists("b")) print "b is not defined"

      set label GPFUN_sinc at graph .05,.95

     array A[6]
     A[1] = 1
     A[2] = 2.0
     A[3] = {3.0, 3.0}
     A[4] = "four"
     A[6] = A[2]**3
     array B[6] = [ 1, 2.0, A[3], "four", , B[2]**3 ]
     array C = split("A B C D E F")

     do for [i=1:6] { print A[i], B[i] }
         1 1
         2.0 2.0
         {3.0, 3.0} {3.0, 3.0}
         four four
         <undefined> <undefined>
         8.0 8.0

     array A[200]
     do for [i=1:200] { A[i] = sin(i * pi/100.) }
     plot A title "sin(x) in centiradians"

     plot A using (real(A[$1])) : (imag(A[$1]))
     plot A using 2:3

     dot(A,B) = (|A| != |B|) ? NaN : sum [i=1:|A|] A[i] * B[i]

     T = split("A B C D E F")
     U = T[3:4]
     print T
        [ "A", "B", "C", "D", "E", "F" ]
     print U
        [ "C", "D" ]
     print index( T, "D" )
        4

    array A = [ 4.0, 4, "4" ]
    print index( A, 4 )
          2
    print index( A, 2.+2. )
          1
    print index( A, "D4"[2:2] )
          3

1.16 Fonts ¶

Gnuplot does not provide any fonts of its own. It relies on external font handling, the details of which unfortunately vary from one terminal type to another. Brief documentation of font mechanisms that apply to more than one terminal type is given here. For information on font use by other individual terminals, see the documentation for that terminal.

Although it is possible to include non-alphabetic symbols by temporarily switching to a special font, e.g. the Adobe Symbol font, the preferred method is now to choose UTF-8 encoding and treat the symbol like any other character. Alternatively you can specify the unicode entry point for the desired symbol as an escape sequence in enhanced text mode. See encoding, ‘unicode‘, locale, and ‘escape sequences‘.

• cairo (pdfcairo, pngcairo, epscairo, wxt terminals)
• gd (png, gif, jpeg, sixel terminals)
• postscript (also encapsulated postscript *.eps)

     set term pdfcairo font "sans,12"
     set term pdfcairo font "Times,12"
     set term pdfcairo font "Times-New-Roman,12"

     set term png tiny

     set term png font "arial"
     set term png font "/usr/local/fonts/ttf/arial.ttf"
     set term png font "Helvetica"
     set term png font "/usr/local/fonts/pfa/Helvetica.pfa"

     set term png font "arial,11"

     set term postscript eps font "Times-Roman,12"

     set term postscript eps font "Garamond-Premier-Pro-Italic"

1.17 Glossary ¶

As ‘gnuplot‘ has evolved over more than 30 years, the meaning of certain words used in commands and in the documentation may have diverged from current common usage. This section explains how some of these terms are used in ‘gnuplot‘.

The term "terminal" refers to an output mode, not to the thing you are typing on. For example, the command ‘set terminal pdf‘ means that subsequent plotting commands will produce pdf ouput. Usually you would want to accompany this with a ‘set output "filename"‘ command to control where the pdf output is written.

A "page" or "screen" or "canvas" is the entire area addressable by ‘gnuplot‘. On a desktop it is a full window; on a plotter, it is a single sheet of paper.

When discussing data files, the term "record" denotes a single line of text in the file, that is, the characters between newline or end-of-record characters. A "point" is the datum extracted from a single record. A "block" of data is a set of consecutive records delimited by blank lines. A line, when referred to in the context of a data file, is a subset of a block. Note that the term "data block" may also be used to refer to a named block of inline data (see ‘datablocks‘).

1.18 inline data and datablocks ¶

There are two mechanisms for embedding data into a stream of gnuplot commands. If the special filename ’-’ appears in a plot command, then the lines immediately following the plot command are interpreted as inline data. See special-filenames. Data provided in this way can only be used once, by the plot command it follows.

The second mechanism defines a named data block as a here-document. The named data is persistent and may be referred to by more than one plot command. Example:

     $Mydata << EOD
     11 22 33 first line of data
     44 55 66 second line of data
     # comments work just as in a data file
     77 88 99
     EOD
     stats $Mydata using 1:3
     plot $Mydata using 1:3 with points, $Mydata using 1:2 with impulses

Data block names must begin with a $ character, which distinguishes them from other types of persistent variables. The end-of-data delimiter (EOD in the example) may be any sequence of alphanumeric characters.

For a parallel mechanism that stores executable commands rather than data in a named block, see ‘function blocks‘.

The storage associated with named data blocks can be released using ‘undefine‘ command. ‘undefine $*‘ frees all named data and function blocks at once.

1.19 iteration ¶

gnuplot supports command iteration and block-structured if/else/while/do constructs. See if, ‘while‘, and ‘do‘. Simple iteration is possible inside ‘plot‘ or ‘set‘ commands. See ‘plot for‘. General iteration spanning multiple commands is possible using a block construct as shown below. For a related new feature, see the summation expression type. Here is an example using several of these new syntax features:

      set multiplot layout 2,2
      fourier(k, x) = sin(3./2*k)/k * 2./3*cos(k*x)
      do for [power = 0:3] {
          TERMS = 10**power
          set title sprintf("%g term Fourier series",TERMS)
          plot 0.5 + sum [k=1:TERMS] fourier(k,x) notitle
      }
      unset multiplot

Iteration is controlled by an iteration specifier with syntax

     for [<var> in "string of N elements"]

or

     for [<var> = <start> : <end> { : <increment> }]

In the first case <var> is a string variable that successively evaluates to single-word substrings 1 to N of the string in the iteration specifier. In the second case <start>, <end>, and <increment> are integers or integer expressions.

The scope of the iteration variable is private to that iteration. See ‘scope‘. You cannot permanently change the value of the iteration variable inside the iterated clause. If the iteration variable has a value prior to iteration, that value will be retained or restored at the end of the iteration. For example, the following commands will print 1 2 3 4 5 6 7 8 9 10 A.

     i = "A"
     do for [i=1:10] { print i; i=10; }
     print i

1.20 linetypes, colors, and styles ¶

In very old gnuplot versions, each terminal type provided a set of distinct "linetypes" that could differ in color, in thickness, in dot/dash pattern, or in some combination of color and dot/dash. These colors and patterns were not guaranteed to be consistent across different terminal types although most used the color sequence red/green/blue/magenta/cyan/yellow. You can select this old behaviour via the command ‘set colorsequence classic‘, but by default gnuplot now uses a terminal-independent sequence of 8 colors.

You can further customize the sequence of linetype properties interactively or in an initialization file. See ‘set linetype‘. Several sample initialization files are provided in the distribution package.

The current linetype properties for a particular terminal can be previewed by issuing the ‘test‘ command after setting the terminal type.

Successive functions or datafiles plotted by a single command will be assigned successive linetypes in the current default sequence. You can override this for any individual function, datafile, or plot element by giving explicit line properties in the plot command.

Examples:

     plot "foo", "bar"                 # plot two files using linetypes 1, 2
     plot sin(x) linetype 4            # use linetype color 4

In general, colors can be specified using named colors, rgb (red, green, blue) components, hsv (hue, saturation, value) components, or a coordinate along the current pm3d palette. The keyword ‘linecolor‘ may be abbreviated to ‘lc‘.

Examples:

     plot sin(x) lc rgb "violet"       # use one of gnuplot's named colors
     plot sin(x) lc rgb "#FF00FF"      # explicit RGB triple in hexadecimal
     plot sin(x) lc palette cb -45     # whatever color corresponds to -45
                                       # in the current cbrange of the palette
     plot sin(x) lc palette frac 0.3   # fractional value along the palette

See colorspec, colornames, ‘hsv‘, palette, cbrange. See also monochrome.

Linetypes also have an associated dot-dash pattern although not all terminal types are capable of using it. You can specify the dot-dash pattern independent of the line color. See dashtype.

• colorspec
• dashtype
• linestyles vs linetypes
• special linetypes

      ... {linecolor | lc} {"colorname" | <colorspec> | <n>}
      ... {textcolor | tc} {<colorspec> | {linetype | lt} <n>}
      ... {fillcolor | fc} {<colorspec> | linetype <n> | linestyle <n>}

      rgbcolor "colorname"    # e.g. "blue"
      rgbcolor "0xRRGGBB"     # string containing hexadecimal constant
      rgbcolor "0xAARRGGBB"   # string containing hexadecimal constant
      rgbcolor "#RRGGBB"      # string containing hexadecimal in x11 format
      rgbcolor "#AARRGGBB"    # string containing hexadecimal in x11 format
      rgbcolor <integer val>  # integer value representing AARRGGBB
      rgbcolor variable       # integer value is read from input file
      palette frac <val>      # <val> runs from 0 to 1
      palette cb <value>      # <val> lies within cbrange
      palette z
      palette <colormap>      # use named colormap rather than current palette
      variable                # color index is read from input file
      bgnd                    # background color
      black

     # This will erase a section of the canvas by writing over it in the
     # background color
     set term wxt background rgb "gray75"
     set object 1 rectangle from x0,y0 to x1,y1 fillstyle solid fillcolor bgnd
     # Draw an "invisible" line at y=0, erasing whatever was underneath
     plot 0 lt bgnd

      # Use the third column of data to assign colors to individual points
      plot 'data' using 1:2:3 with points lc variable

      # A single data file may contain multiple sets of data, separated by two
      # blank lines.  Each data set is assigned as index value (see index)
      # that can be retrieved via the `using` specifier `column(-2)`.
      # See `pseudocolumns`.  This example uses to value in column -2 to
      # draw each data set in a different line color.
      plot 'data' using 1:2:(column(-2)) with lines lc variable

      ... {lc|fc|tc} palette {z}
      ... {lc|fc|tc} palette frac <fraction>
      ... {lc|fc|tc} palette cb <fixed z-value>
      ... fc palette <colormap>

      # Place colored points in 3D at the x,y,z coordinates corresponding to
      # their red, green, and blue components
      rgb(r,g,b) = 65536 * int(r) + 256 * int(g) + int(b)
      splot "data" using 1:2:3:(rgb($1,$2,$3)) with points lc rgb variable

      dashtype N          # predefined dashtype invoked by number
      dashtype "pattern"  # string containing a combination of the characters
                          # dot (.) hyphen (-) underscore(_) and space.
      dashtype (s1,e1,s2,e2,s3,e3,s4,e4)  # dash pattern specified by 1 to 4
                          # numerical pairs <solid length>, <emptyspace length>

      # Two functions using linetype 1 but distinguished by dashtype
      plot f1(x) with lines lt 1 dt solid, f2(x) with lines lt 1 dt 3

     plot f(x) dt 3            # use terminal-specific dash pattern 3
     plot f(x) dt ".. "        # construct a dash pattern on the spot
     plot f(x) dt (2,5,2,15)   # numerical representation of the same pattern
     set dashtype 11 (2,4,4,7) # define new dashtype to be called by index
     plot f(x) dt 11           # plot using our new dashtype

     # define a new line style with terminal-independent color cyan,
     # linewidth 3, and associated point type 6 (a circle with a dot in it).
     set style line 5 lt rgb "cyan" lw 3 pt 6
     plot sin(x) with linespoints ls 5          # user-defined line style 5

     plot f(x) with linespoints lt nodraw pointinterval -3

1.21 layers ¶

A gnuplot plot is built up by drawing its various components in a fixed order. This order can be modified by assigning some components to a specific layer using the keywords ‘behind‘, ‘back‘, or ‘front‘. For example, to replace the background color of the plot area you could define a colored rectangle with the attribute ‘behind‘.

     set object 1 rectangle from graph 0,0 to graph 1,1 fc rgb "gray" behind

The order of drawing is

     behind
     back
     the plot itself
     the plot legend (`key`)
     front

Within each layer elements are drawn in the order

     grid, axis, and border elements
     pixmaps in numerical order
     objects (rectangles, circles, ellipses, polygons) in numerical order
     labels in numerical order
     arrows in numerical order

In the case of multiple plots on a single page (multiplot mode) this order applies separately to each component plot, not to the multiplot as a whole.

An exception to this is that several TeX-based terminals (e.g. pslatex, cairolatex) accumulate all text elements in one output stream and graphics in a separate output stream; the text and graphics are then combined to yield the final figure. In general this leaves each text element either completely behind or completely in front of the graphics.

1.22 mouse input ¶

Many terminals allow interaction with the current plot using the mouse. Some also support the definition of hotkeys to activate pre-defined functions by hitting a single key while the mouse focus is in the active plot window. It is even possible to combine mouse input with ‘batch‘ command scripts, by invoking the command ‘pause mouse‘ and then using the mouse variables returned by mouse clicking as parameters for subsequent scripted actions. See ‘bind‘ and ‘mouse variables‘. See also the command ‘set mouse‘.

• bind
• Mouse variables

      bind {allwindows} [<key-sequence>] ["<gnuplot commands>"]
      bind <key-sequence> ""
      reset bind

    bind a "replot"
    bind "ctrl-a" "plot x*x"
    bind "ctrl-alt-a" 'print "great"'
    bind Home "set view 60,30; replot"
    bind all Home 'print "This is window ",MOUSE_KEY_WINDOW'

    bind "ctrl-a"          # shows the binding for ctrl-a
    bind                   # shows all bindings
    show bind              # show all bindings

    bind "ctrl-alt-a" ""   # removes binding for ctrl-alt-a
                             (note that builtins cannot be removed)
    reset bind             # installs default (builtin) bindings

  v=0
  bind "ctrl-r" "v=v+1;if(v%2)set term x11 noraise; else set term x11 raise"

    ctrl-alt-a == CtRl-alT-a
    ctrl-alt-a != ctrl-alt-A

    ctrl, alt, shift (only valid for Button1 Button2 Button3)

   "BackSpace", "Tab", "Linefeed", "Clear", "Return", "Pause", "Scroll_Lock",
   "Sys_Req", "Escape", "Delete", "Home", "Left", "Up", "Right", "Down",
   "PageUp", "PageDown", "End", "Begin",

   "KP_Space", "KP_Tab", "KP_Enter", "KP_F1", "KP_F2", "KP_F3", "KP_F4",
   "KP_Home", "KP_Left", "KP_Up", "KP_Right", "KP_Down", "KP_PageUp",
   "KP_PageDown", "KP_End", "KP_Begin", "KP_Insert", "KP_Delete", "KP_Equal",
   "KP_Multiply", "KP_Add", "KP_Separator", "KP_Subtract", "KP_Decimal",
   "KP_Divide",

   "KP_1" - "KP_9", "F1" - "F12"

   "Button1" "Button2" "Button3" "Close"

      plot 'something'
      pause mouse
      if (exists("MOUSE_BUTTON")) call 'something_else'; \
      else print "No mouse click."

      plot 'something'
      pause mouse keypress
      print "Keystroke ", MOUSE_KEY, " at ", MOUSE_X, " ", MOUSE_Y

1.23 Persist ¶

Many gnuplot terminals (aqua, pm, qt, x11, windows, wxt, ...) open separate display windows on the screen into which plots are drawn. The ‘persist‘ option tells gnuplot to leave these windows open when the main program exits. It has no effect on non-interactive terminal output. For example if you issue the command

     gnuplot -persist -e 'plot sinh(x)'

gnuplot will open a display window, draw the plot into it, and then exit, leaving the display window containing the plot on the screen. You can also specify ‘persist‘ or ‘nopersist‘ when you set a new terminal.

     set term qt persist size 700,500

Depending on the terminal type, some mousing operations may still be possible in the persistent window. However operations like zoom/unzoom that require redrawing the plot are not possible because the main program has exited. If you want to leave a plot window open and fully mouseable after creating the plot, for example when running gnuplot from a script file rather than interactively, see ‘pause mouse close‘.

1.24 Plotting ¶

There are four ‘gnuplot‘ commands which actually create a plot: ‘plot‘, ‘splot‘, replot, and refresh. Other commands control the layout, style, and content of the plot that will eventually be created. ‘plot‘ generates 2D plots. ‘splot‘ generates 3D plots (actually 2D projections, of course). replot reexecutes the previous ‘plot‘ or ‘splot‘ command. refresh is similar to replot but it reuses any previously stored data rather than rereading data from a file or input stream.

Each time you issue one of these four commands it will redraw the screen or generate a new page of output containing all of the currently defined axes, labels, titles, and all of the various functions or data sources listed in the original plot command. If instead you need to place several complete plots next to each other on the same page, e.g. to make a panel of sub-figures or to inset a small plot inside a larger plot, use the command multiplot to suppress generation of a new page for each plot command.

Much of the general information about plotting can be found in the discussion of ‘plot‘; information specific to 3D can be found in the ‘splot‘ section.

‘plot‘ operates in either rectangular or polar coordinates – see ‘set polar‘. ‘splot‘ operates in Cartesian coordinates, but will accept azimuthal or cylindrical coordinates on input. See mapping.

‘plot‘ also lets you use each of the four borders – x (bottom), x2 (top), y (left) and y2 (right) – as an independent axis. The axes option lets you choose which pair of axes a given function or data set is plotted against. A full complement of ‘set‘ commands exists to give you complete control over the scales and labeling of each axis. Some commands have the name of an axis built into their names, such as xlabel. Other commands have one or more axis names as options, such as ‘set logscale xy‘. Commands and options controlling the z axis have no effect on 2D graphs.

‘splot‘ can plot surfaces and contours in addition to points and/or lines. See isosamples for information about defining the grid for a 3D function. See datafile for information about the requisite file structure for 3D data. For contours see ‘set contour‘, cntrlabel, and cntrparam.

In ‘splot‘, control over the scales and labels of the axes are the same as with ‘plot‘ except that there is also a z axis and labeling the x2 and y2 axes is possible only for pseudo-2D plots created using ‘set view map‘.

1.25 Plugins ¶

The set of functions available for plotting or for evaluating expressions can be extended through a plugin mechanism that imports executable functions from a shared library. For example, gnuplot versions through 5.4 did not provide a built-in implementation of the upper incomplete gamma function Q(a,x). You could define an approximation directly in gnuplot like this:

      Q(a,x) = 1. - igamma(a,x)

However this has inherently limited precision as igamma(a,x) approaches 1. If you need a more accurate implementation, it would be better to provide one via a plugin (see below). Once imported, the function can be used just as any other built-in or user-defined function in gnuplot. See import.

The gnuplot distribution includes source code and instructions for creating a plugin library in the directory demo/plugin. You can modify the simple example file ‘demo_plugin.c‘ by replacing one or more of the toy example functions with an implementation of the function you are interested in. This could include invocation of functions from an external mathematical library.

The demo/plugin directory also contains source for a plugin that implements Q(a,x). As noted above, this plugin allows earlier versions of gnuplot to provide the same function uigamma as version 6.

     import Q(a,x) from "uigamma_plugin"
     uigamma(a,x) = ((x<1 || x<a) ? 1.0-igamma(a,x) : Q(a,x))

1.26 Scope of variables ¶

Gnuplot variables are global except in the special cases listed below. There is a single persistent list of active variables indexed by name. Assignment to a variable creates or replaces an entry in that list. The only way to remove a variable from that list is the ‘undefine‘ command.

Exception 1: The scope of the variable used in an iteration specifier is private to that iteration. You cannot permanently change the value of the iteration variable inside the iterated clause. If the iteration variable has a value prior to iteration, that value will be retained or restored at the end of the iteration. For example, the following commands will print 1 2 3 4 5 6 7 8 9 10 A.

     i = "A"
     do for [i=1:10] { print i; i=10; }
     print i

Exception 2: The parameter names used in defining a function are only placeholders for the actual values that will be provided when the function is called. For example, any current or future values of x and y are not relevant to the definition shown here, but A must exist as a global variable when the function is later evaluated:

     func(x,y) = A + (x+y)/2.

Exception 3: Variables declared with the ‘local‘ command. The ‘local‘ qualifier (new in version 6) allows optional declaration of a variable or array whose scope is limited to the execution of the code block in which it is found. This includes ‘load‘ and call operations, evaluation of a function block, and the code in curly brackets that follows an if, ‘else‘, ‘do for‘, or ‘while‘ condition. If the name of a local variable duplicates the name of a global variable, the global variable is shadowed until exit from the local scope. EXPERIMENTAL: As currently implemented the scope of a local variable extends into functions called from the code block it was declared in; this includes call, ‘load‘, and function block invocation. This will probably change in the future so that the scope is strictly confined to the declaring code block.

1.27 Start-up (initialization) ¶

When gnuplot is run, it first looks for a system-wide initialization file ‘gnuplotrc‘. The location of this file is determined when the program is built and is reported by loadpath. The program then looks in the user’s HOME directory for a file called ‘.gnuplot‘ on Unix-like systems or ‘GNUPLOT.INI‘ on other systems. (OS/2 will look for it in the directory named in the environment variable ‘GNUPLOT‘; Windows will use ‘APPDATA‘). On Unix-like systems gnuplot additionally checks for the file $XDG_CONFIG_HOME/gnuplot/gnuplotrc.

1.28 String constants, string variables, and string functions ¶

In addition to string constants, most gnuplot commands also accept a string variable, a string expression, or a function that returns a string. For example, the following four methods of creating a plot all result in the same plot title:

      four = "4"
      graph4 = "Title for plot #4"
      graph(n) = sprintf("Title for plot #%d",n)

      plot 'data.4' title "Title for plot #4"
      plot 'data.4' title graph4
      plot 'data.4' title "Title for plot #".four
      plot 'data.4' title graph(4)

Since integers are promoted to strings when operated on by the string concatenation operator (’.’ character), the following method also works:

      N = 4
      plot 'data.'.N title "Title for plot #".N

In general, elements on the command line will only be evaluated as possible string variables if they are not otherwise recognizable as part of the normal gnuplot syntax. So the following sequence of commands is legal, although probably should be avoided so as not to cause confusion:

      plot = "my_datafile.dat"
      title = "My Title"
      plot plot title title

• substrings
• string operators
• string functions
• string encoding

     eos = strlen(file)
     if (file[eos-3:*] eq ".dat") {
         set output file[1:eos-4] . ".png"
         plot file
     }

     if ("A"."B" eq "AB") print "TRUE"

 set encoding utf8
 utf8string = "αβγ"
 strlen(utf8string) returns 3 (number of characters, not number of bytes)
 utf8string[2:2] evaluates to "β"
 strstrt(utf8string,"β") evaluates to 2

1.29 Substitution and Command line macros ¶

When a command line to gnuplot is first read, i.e. before it is interpreted or executed, two forms of lexical substitution are performed. These are triggered by the presence of text in backquotes (ascii character 96) or preceded by @ (ascii character 64).

• Substitution of system commands in backquotes
• Substitution of string variables as macros
• String variables, macros, and command line substitution

      set label "generated on `date +%Y-%m-%d` by `whoami`" at 1,1
      set timestamp "generated on %Y-%m-%d by `whoami`"

      FILES = split( "`ls -1`" )

      style1 = "lines lt 4 lw 2"
      style2 = "points lt 3 pt 5 ps 2"
      range1 = "using 1:3"
      range2 = "using 1:5"
      plot "foo" @range1 with @style1, "bar" @range2 with @style2

      plot "foo" using 1:3 with lines lt 4 lw 2, \
           "bar" using 1:5 with points lt 3 pt 5 ps 2

      C = "pi"
      if (exists(C)) print C," = ", @C

     A = "c=1"
     @A

     A = "c=1"; @A   # will not expand to c=1

      filename = "mydata.inp"
      lines = ` wc --lines @filename | sed "s/ .*//" `

      mycomputer = "`uname -n`"

       machine_id = "uname -n"
       mycomputer = "`@machine_id`"  # doesn't work!!

      machine_id = sprintf('"`uname -n`"')
      mycomputer = @machine_id

1.30 Syntax ¶

Options and any accompanying parameters are separated by spaces whereas lists and coordinates are separated by commas. Ranges are separated by colons and enclosed in brackets [], text and file names are enclosed in quotes, and a few miscellaneous things are enclosed in parentheses.

Commas are used to separate coordinates on the ‘set‘ commands ‘arrow‘, ‘key‘, and ‘label‘; the list of variables being fitted (the list after the ‘via‘ keyword on the fit command); lists of discrete contours or the loop parameters which specify them on the cntrparam command; the arguments of the ‘set‘ commands dgrid3d, dummy, isosamples, offsets, origin, samples, size, ‘time‘, and view; lists of tics or the loop parameters which specify them; the offsets for titles and axis labels; parametric functions to be used to calculate the x, y, and z coordinates on the ‘plot‘, replot and ‘splot‘ commands; and the complete sets of keywords specifying individual plots (data sets or functions) on the ‘plot‘, replot and ‘splot‘ commands.

Parentheses are used to delimit sets of explicit tics (as opposed to loop parameters) and to indicate computations in ‘using‘ specifiers of the fit, ‘plot‘, replot and ‘splot‘ commands.

(Parentheses and commas are also used as usual in function notation.)

Square brackets are used to delimit ranges given in ‘set‘, ‘plot‘ or ‘splot‘ commands.

Colons are used to separate extrema in ‘range‘ specifications (whether they are given on ‘set‘, ‘plot‘ or ‘splot‘ commands) and to separate entries in the ‘using‘ specifier of the ‘plot‘, replot, ‘splot‘ and fit commands.

Semicolons are used to separate commands given on a single command line.

Curly braces are used in the syntax for enhanced text mode and to delimit blocks in if/then/else statements. They are also used to denote complex numbers: {3,2} = 3 + 2i.

• quote marks

      "This is the first line of text.\nThis is the second line."

                       This is the first line of text.
                          This is the second line.

      'This is the first line of text.\nThis is the second line.'

          This is the first line of text.\nThis is the second line.

1.31 Time/Date data ¶

‘gnuplot‘ supports the use of time and/or date information as input data. This feature is activated by the commands ‘set xdata time‘, ‘set ydata time‘, etc.

Internally all times and dates are converted to the number of seconds from the year 1970. The command timefmt defines the default format for all inputs: data files, ranges, tics, label positions – anything that accepts a time data value defaults to receiving it in this format. Only one default format can be in effect at a given time. Thus if both x and y data in a file are time/date, by default they are interpreted in the same format. However this default can be replaced when reading any particular file or column of input using the ‘timecolumn‘ function in the corresponding ‘using‘ specifier.

The conversion to and from seconds assumes Universal Time (which is the same as Greenwich Standard Time). There is no provision for changing the time zone or for daylight savings. If all your data refer to the same time zone (and are all either daylight or standard) you don’t need to worry about these things. But if the absolute time is crucial for your application, you’ll need to convert to UT yourself.

Commands like xrange will re-interpret the integer according to timefmt. If you change timefmt, and then ‘show‘ the quantity again, it will be displayed in the new timefmt. For that matter, if you reset the data type flag for that axis (e.g. xdata), the quantity will be shown in its numerical form.

The commands ‘set format‘ or ‘set tics format‘ define the format that will be used for tic labels, whether or not input for the specified axis is time/date.

If time/date information is to be plotted from a file, the ‘using‘ option _must_ be used on the ‘plot‘ or ‘splot‘ command. These commands simply use white space to separate columns, but white space may be embedded within the time/date string. If you use tabs as a separator, some trial-and-error may be necessary to discover how your system treats them.

The ‘time‘ function can be used to get the current system time. This value can be converted to a date string with the strftime function, or it can be used in conjunction with ‘timecolumn‘ to generate relative time/date plots. The type of the argument determines what is returned. If the argument is an integer, ‘time‘ returns the current time as an integer, in seconds from 1 Jan 1970. If the argument is real (or complex), the result is real as well. The precision of the fractional (sub-second) part depends on your operating system. If the argument is a string, it is assumed to be a format string, and it is passed to strftime to provide a formatted time/date string.

The following example demonstrates time/date plotting.

Suppose the file "data" contains records like

      03/21/95 10:00  6.02e23

This file can be plotted by

      set xdata time
      set timefmt "%m/%d/%y"
      set xrange ["03/21/95":"03/22/95"]
      set format x "%m/%d"
      set timefmt "%m/%d/%y %H:%M"
      plot "data" using 1:3

which will produce xtic labels that look like "03/21".

Gnuplot tracks time to millisecond precision. Time formats have been modified to match this. Example: print the current time to msec precision

     print strftime("%H:%M:%.3S %d-%b-%Y",time(0.0))
     18:15:04.253 16-Apr-2011

See ‘time_specifiers‘, ‘set xtics time‘, ‘set mxtics time‘.

1.32 Watchpoints ¶

Support for watchpoints is present only if your copy of gnuplot was built with configuration option –enable-watchpoints. This feature is EXPERIMENTAL [details may change in a subsequent release version].

Syntax:

      plot FOO watch {x|y|z|F(x,y)} = <value>
      plot FOO watch mouse

      set style watchpoints nolabels
      set style watchpoints label <label-properties>

      unset style watchpoints      # return to default style

      show watchpoints    # summarizes all watches from previous plot command

A watchpoint is a target value for the x, y, or z coordinate or for a function f(x,y). Each watchpoint is attached to a single plot within a ‘plot‘ command. Watchpoints are tracked only for styles ‘with lines‘ and linespoints. Every component line segment of that plot is checked against all watchpoints attached the plot to see whether one or more of the watchpoint targets is satisfied at a point along that line segment. A list of points that satisfy the the target condition ("hits") is accumulated as the plot is drawn.

For example, if there is a watchpoint with a target y=100, each line segment is checked to see if the y coordinates of the two endpoints bracket the target y value. If so then some point [x,y] on the line segment satisfies the target condition y = 100 exactly. This target point is then found by linear interpolation or by iterative bisection.

Watchpoints within a single plot command are numbered successively. More than one watchpoint per plot component may be specified. Example:

     plot DATA using 1:2 smooth cnormal watch y=0.25 watch y=0.5 watch y=0.75

Watchpoint hits for each target in the previous plot command are stored in named arrays WATCH_n. You can also display a summary of all watchpoint hits from the previous plot command; see watchpoints.

     gnuplot> show watchpoints
     Plot title:     "DATA using 1:2 smooth cnormal"
       Watch 1 target y = 0.25         (1 hits)
               hit 1   x 49.7  y 0.25
       Watch 2 target y = 0.5          (1 hits)
               hit 1   x 63.1  y 0.5
       Watch 3 target y = 0.75         (1 hits)
               hit 1   x 67.8  y 0.75

Smoothing: Line segments are checked as they are drawn. For unsmoothed data plots this means a hit found by interpolation will lie exactly on a line segment connecting two data points. If a data plot is smoothed, hits will lie on a line segment from the smoothed curve. Depending on the quality of the smoothed fit, this may or may not be more accurate than the hit from the unsmoothed data.

Accuracy: If the line segment was generated from a function plot, the exact value of x such that f(x) = y is found by iterative bisection. Otherwise the coordinates [x,y] are approximated by linear interpolation along the line segment.

• watch mouse
• watch labels

     set style watchpoint labels point pt 6 ps 2 boxstyle 1
     set style textbox 1 lw 0.5 opaque
     plot for [i=1:N] "file.dat" using 1:(column(i)) watch mouse

     set y2tics format "%.2f°"
     set style watchpoint labels point pt 6
     plot FOO axes x1y2 watch mouse

2.1 arrows ¶

The 2D ‘arrows‘ style draws an arrow with specified length and orientation angle at each point (x,y). Additional input columns may be used to provide variable (per-datapoint) color information or arrow style. It is identical to the 2D style vectors except that each arrow head is positioned using length + angle rather than delta_x + delta_y. See vectors.

     4 columns:  x  y  length  angle

The keywords ‘with arrows‘ may be followed by inline arrow style properties, a reference to a predefined arrow style, or ‘arrowstyle variable‘ to load the index of the desired arrow style for each arrow from a separate column.

‘length‘ > 0 is interpreted in x-axis coordinates. -1 < ‘length‘ < 0 is interpreted in horizontal graph coordinates; i.e. |length| is a fraction of the total graph width. The program will adjust for differences in x and y scaling or plot aspect ratio so that the visual length is independent of the orientation angle.

‘angle‘ is always specified in degrees.

• arrowstyle variable

     set style arrow 1 head nofilled linecolor "blue" linewidth 0.5
     set style arrow 2 head filled linecolor "red" linewidth 1.0
     # column 5 is expected to contain either 1 or 2,
     # determining which of the two previous defined styles to use
     plot DATA using 1:2:3:4:5 with arrows arrowstyle variable

2.2 Bee swarm plots ¶

"Bee swarm" plots result from applying jitter to separate overlapping points. A typical use is to compare the distribution of y values exhibited by two or more categories of points, where the category determines the x coordinate. See the jitter command for how to control the overlap criteria and the displacement pattern used for jittering. The plots in the figure were created by the same plot command but different jitter settings.

     set jitter
     plot $data using 1:2:1 with points lc variable

2.3 boxerrorbars ¶

The boxerrorbars style is only relevant to 2D data plotting. It is a combination of the boxes and yerrorbars styles. It requires 3, 4, or 5 columns of data. An additional (4th, 5th or 6th) input column may be used to provide variable (per-datapoint) color information (see ‘linecolor‘ and ‘rgbcolor variable‘).

     3 columns:  x  y  ydelta
     4 columns:  x  y  ydelta xdelta         (xdelta <= 0 means use boxwidth)
     5 columns:  x  y  ylow  yhigh  xdelta   (xdelta <= 0 means use boxwidth)

The boxwidth will come from the fourth column if the y errors are given as "ydelta" or from the fifth column if they are in the form of "ylow yhigh". If xdelta is zero or negative, the width of the box is controlled by the value previously given for boxwidth. See boxwidth.

A vertical error bar is drawn to represent the y error in the same way as for the yerrorbars style, either from y-ydelta to y+ydelta or from ylow to yhigh, depending on how many data columns are provided. The line style used for the error bar may be controlled using ‘set bars‘. Otherwise the error bar will match the border of the box.

DEPRECATED: Old versions of gnuplot treated ‘boxwidth = -2.0‘ as a special case for four-column data with y errors in the form "ylow yhigh". In this case boxwidth was adjusted to leave no gap between adjacent boxes. This treatment is retained for backward-compatibility but may be removed in a future version.

2.4 boxes ¶

In 2D plots the boxes style draws a rectangle centered about the given x coordinate that extends from the x axis, i.e. from y=0 not from the graph border, to the given y coordinate. The width of the box can be provided in an additional input column or controlled by boxwidth. Otherwise each box extends to touch the adjacent boxes.

In 3D plots the boxes style draws a box centered at the given [x,y] coordinate that extends from the plane at z=0 to the given z coordinate. The width of the box on x can be provided in a separate input column or via boxwidth. The depth of the box on y is controlled by boxdepth. Boxes do not automatically expand to touch each other.

• 2D boxes
• 3D boxes

     2 columns:  x  y
     3 columns:  x  y  x_width

      set boxwidth 0.9 relative
      set style fill solid 1.0
      plot 'file.dat' with boxes

      set style fill pattern
      plot sin(x) with boxes fc 'blue', cos(x) with boxes fc 'gold'

     3 columns:  x  y  z
     4 columns:  x  y  z  [x_width or color]
     5 columns:  x  y  z  x_width  color

     splot 'blue_boxes.dat' using 1:2:3 fc "blue"
     splot 'rgb_boxes.dat' using 1:2:3:4 fc rgb variable
     splot 'category_boxes.dat' using 1:2:3:4:5 lc variable

2.5 boxplot ¶

Boxplots are a common way to represent a statistical distribution of values. Quartile boundaries are determined such that 1/4 of the points have a value equal or less than the first quartile boundary, 1/2 of the points have a value equal or less than the second quartile (median) value, etc. A box is drawn around the region between the first and third quartiles, with a horizontal line at the median value. Whiskers extend from the box to user-specified limits. Points that lie outside these limits are drawn individually.

Examples

    # Place a boxplot at x coordinate 1.0 representing the y values in column 5
    plot 'data' using (1.0):5

    # Same plot but suppress outliers and force the width of the boxplot to 0.3
    set style boxplot nooutliers
    plot 'data' using (1.0):5:(0.3)

By default only one boxplot is produced that represents all y values from the second column of the using specification. However, an additional (fourth) column can be added to the specification. If present, the values of that column will be interpreted as the discrete levels of a factor variable. As many boxplots will be drawn as there are levels in the factor variable. The separation between these boxplots is 1.0 by default, but it can be changed by ‘set style boxplot separation‘. By default, the value of the factor variable is shown as a tic label below (or above) each boxplot.

Example

    # Suppose that column 2 of 'data' contains either "control" or "treatment"
    # The following example produces two boxplots, one for each level of the
    # factor
    plot 'data' using (1.0):5:(0):2

The default width of the box can be set via ‘set boxwidth <width>‘ or may be specified as an optional 3rd column in the ‘using‘ clause of the plot command. The first and third columns (x coordinate and width) are normally provided as constants rather than as data columns.

By default the whiskers extend from the ends of the box to the most distant point whose y value lies within 1.5 times the interquartile range. By default outliers are drawn as circles (point type 7). The width of the bars at the end of the whiskers may be controlled using ‘set bars‘ or errorbars.

These default properties may be changed using the boxplot command. See boxplot, ‘bars‘, boxwidth, ‘fillstyle‘, candlesticks.

2.6 boxxyerror ¶

The boxxyerror plot style is only relevant to 2D data plotting. It is similar to the xyerrorbars style except that it draws rectangular areas rather than crosses. It uses either 4 or 6 basic columns of input data. An additional (5th or 7th) input column may be used to provide variable (per-datapoint) color information (see ‘linecolor‘ and ‘rgbcolor variable‘).

     4 columns:  x  y  xdelta  ydelta
     6 columns:  x  y  xlow  xhigh  ylow  yhigh

The box width and height are determined from the x and y errors in the same way as they are for the xyerrorbars style—either from xlow to xhigh and from ylow to yhigh, or from x-xdelta to x+xdelta and from y-ydelta to y+ydelta, depending on how many data columns are provided.

The 6 column form of the command provides a convenient way to plot rectangles with arbitrary x and y bounds.

The interior of the boxes is drawn according to the current fillstyle. See ‘set style fill‘ and boxes for details. Alternatively a new fillstyle may be specified in the plot command.

2.7 candlesticks ¶

The candlesticks style can be used for 2D data plotting of financial data or for generating box-and-whisker plots of statistical data. The symbol is a rectangular box, centered horizontally at the x coordinate and limited vertically by the opening and closing prices. A vertical line segment at the x coordinate extends up from the top of the rectangle to the high price and another down to the low. The vertical line will be unchanged if the low and high prices are interchanged.

Five columns of basic data are required:

      financial data:   date  open  low  high  close
      whisker plot:     x  box_min  whisker_min  whisker_high  box_high

The width of the rectangle can be controlled by the boxwidth command. For backwards compatibility with earlier gnuplot versions, when the boxwidth parameter has not been set then the width of the candlestick rectangle is taken from ‘set errorbars <width>‘.

Alternatively, an explicit width for each box-and-whiskers grouping may be specified in an optional 6th column of data. The width must be given in the same units as the x coordinate.

An additional (6th, or 7th if the 6th column is used for width data) input column may be used to provide variable (per-datapoint) color information (see ‘linecolor‘ and ‘rgbcolor variable‘).

By default the vertical line segments have no crossbars at the top and bottom. If you want crossbars, which are typically used for box-and-whisker plots, then add the keyword ‘whiskerbars‘ to the plot command. By default these whiskerbars extend the full horizontal width of the candlestick, but you can modify this by specifying a fraction of the full width.

The usual convention for financial data is that the rectangle is empty if (open < close) and solid fill if (close < open). This is the behavior you will get if the current fillstyle is set to "empty". See ‘fillstyle‘. If you set the fillstyle to solid or pattern, then this will be used for all boxes independent of open and close values. See also errorbars and financebars. See also the candlestick and finance demos.

Note: To place additional symbols or lines on a box-and-whisker plot requires additional plot components. The first example below uses a second component that squashes the candlestick onto a single line placed at the median value.

  # Data columns:X Min 1stQuartile Median 3rdQuartile Max
  set errorbars 4.0
  set style fill empty
  plot 'stat.dat' using 1:3:2:6:5 with candlesticks title 'Quartiles', \
       ''         using 1:4:4:4:4 with candlesticks lt -1 notitle

  # Plot with crossbars on the whiskers, crossbars are 50% of full width
  plot 'stat.dat' using 1:3:2:6:5 with candlesticks whiskerbars 0.5

See boxwidth, errorbars, ‘set style fill‘, and boxplot.

2.8 circles ¶

The circles style plots a circle with an explicit radius at each data point. The radius is always interpreted in the units of the plot’s horizontal axis (x or x2). The scale on y and the aspect ratio of the plot are both ignored. If the radius is not given in a separate column for each point it is taken from ‘set style circle‘. In this case the radius may use graph or screen coordinates.

Many combinations of per-point and previously set properties are possible. For 2D plots these include

    using x:y
    using x:y:radius
    using x:y:color
    using x:y:radius:color
    using x:y:radius:arc_begin:arc_end
    using x:y:radius:arc_begin:arc_end:color

By default a full circle will be drawn. The result is similar to using a ‘points‘ plot with variable size points and pointtype 7, except that the circles scale with the x axis range. It is possible to instead plot arc segments by specifying a start and end angle (in degrees) in columns 4 and 5.

A per-circle color may be provided in the last column of the using specifier. In this case the plot command must include a corresponding variable color term such as ‘lc variable‘ or ‘fillcolor rgb variable‘.

See ‘set style circle‘, ‘set object circle‘, and ‘set style fill‘.

For 3D plots the using specifier must contain

    splot DATA using x:y:z:radius:color

where the variable color column is optional.

Examples:

    # draws circles whose area is proportional to the value in column 3
    set style fill transparent solid 0.2 noborder
    plot 'data' using 1:2:(sqrt($3)) with circles, \
         'data' using 1:2 with linespoints

    # draws Pac-men instead of circles
    plot 'data' using 1:2:(10):(40):(320) with circles

    # draw a pie chart with inline data
    set xrange [-15:15]
    set style fill transparent solid 0.9 noborder
    plot '-' using 1:2:3:4:5:6 with circles lc var
    0    0    5    0    30    1
    0    0    5   30    70    2
    0    0    5   70   120    3
    0    0    5  120   230    4
    0    0    5  230   360    5
    e

2.9 contourfill ¶

Contourfill is a 3D plotting style used to color a pm3d surface in slices along the z axis. It can be used in 2D projection (‘set view map‘) to create 2D contour plots with solid color between contour lines. The slice boundaries and the assigned colors are both controlled using contourfill. See also ‘pm3d‘, ‘zclip‘.

This style can be combined with ‘set contours‘ to superimpose contour lines that bound the slices. Care must be taken that the slice boundaries from contourfill match the contour bounaries from cntrparam.

     # slice boundaries determined by ztics
     # coloring set by palette mapping the slice midpoint z value
     set pm3d border retrace
     set contourfill ztics
     set ztics -20, 5, 20
     set contour
     set cntrparam cubic levels increment -20, 5, 20
     set cntrlabel onecolor
     set view map
     splot g(x,y) with contourfill, g(x,y) with lines nosurface

2.10 dots ¶

The dots style plots a tiny dot at each point; this is useful for scatter plots with many points. Either 1 or 2 columns of input data are required in 2D. Three columns are required in 3D.

For some terminals (post, pdf) the size of the dot can be controlled by changing the linewidth.

     1 column    y         # x is row number
     2 columns:  x  y
     3 columns:  x  y  z   # 3D only (splot)

2.11 ellipses ¶

The ellipses style plots an ellipse at each data point. This style is only relevant for 2D plotting. Each ellipse is described in terms of its center, major and minor diameters, and the angle between its major diameter and the x axis.

     2 columns: x y
     3 columns: x y diam  (used for both major and minor axes)
     4 columns: x y major_diam minor_diam
     5 columns: x y major_diam minor_diam angle

If only two input columns are present, they are taken as the coordinates of the centers, and the ellipses will be drawn with the default extent (see ‘set style ellipse‘). The orientation of the ellipse, which is defined as the angle between the major diameter and the plot’s x axis, is taken from the default ellipse style (see ‘set style ellipse‘).

If three input columns are provided, the third column is used for both diameters. The orientation angle defaults to zero.

If four columns are present, they are interpreted as x, y, major diameter, minor diameter. Note that these are diameters, not radii. If either diameter is negative, both diameters will be taken from the default set by ‘set style ellipse‘.

An optional 5th column may specify the orientation angle in degrees. The ellipses will also be drawn with their default extent if either of the supplied diameters in the 3-4-5 column form is negative.

In all of the above cases, optional variable color data may be given in an additional last (3th, 4th, 5th or 6th) column. See colorspec.

‘units keyword:‘ If ‘units xy‘ is included in the plot specification, the major diameter is interpreted in the units of the plot’s horizontal axis (x or x2) while the minor diameter in that of the vertical axis (y or y2). If the x and y axis scales are not equal, the major/minor diameter ratio will no longer be correct after rotation. ‘units xx‘ interprets both diameters in units of the x axis. ‘units yy‘ interprets both diameters in units of the y axis. In the latter two cases the ellipses will have the correct aspect ratio even if the plot is resized. If ‘units‘ is omitted from the plot command, the setting from ‘set style ellipse‘ will be used.

Example (draws ellipses, cycling through the available line types):

    plot 'data' using 1:2:3:4:(0):0 with ellipses

See also ‘set object ellipse‘, ‘set style ellipse‘ and ‘fillstyle‘.

2.12 filledcurves ¶

The filledcurves style is only used for 2D plotting. It has three variants. The first two variants require either a single function or two columns (x,y) of input data, and may be further modified by the options listed below.

Syntax:

    plot ... with filledcurves [option]

where the option can be one of the following

    closed
    {above|below} x1 x2  y r=<a> xy=<x>,<y>
    between

The first variant, ‘closed‘, treats the curve itself as a closed polygon. This is the default if there are two columns of input data.

    filledcurves closed   ... just filled closed curve,

The second variant is to fill the area between the curve and a given axis, a horizontal or vertical line, or a point. This can be further restricted to filling the area above or below the specified line.

    filledcurves x1       ... x1 axis,
    filledcurves x2       ... x2 axis, etc for y1 and y2 axes,
    filledcurves y=42     ... line at y=42, i.e. parallel to x axis,
    filledcurves xy=10,20 ... point 10,20 of x1,y1 axes (arc-like shape).
    filledcurves above r=1.5  the area of a polar plot outside radius 1.5

The third variant fills the area between two curves sampled at the same set of x coordinates. It requires three columns of input data (x, y1, y2). This is the default if there are three or more columns of input data. If you have a y value in column 2 and an associated error value in column 3 the area of uncertainty can be represented by shading. See also the similar 3D plot style ‘zerrorfill‘.

    3 columns:  x  y  yerror

    plot $DAT using 1:($2-$3):($2+$3) with filledcurves, \
         $DAT using 1:2 smooth mcs with lines

The ‘above‘ and ‘below‘ options apply both to commands of the form

    ... filledcurves above {x1|x2|y|r}=<val>

and to commands of the form

    ... using 1:2:3 with filledcurves below

In either case the option limits the filled area to one side of the bounding line or curve.

Zooming a filled curve drawn from a datafile may produce empty or incorrect areas because gnuplot is clipping points and lines, and not areas.

If the values <x>, <y>, or <a> are outside the drawing boundary they are moved to the graph boundary. Then the actual fill area in the case of option xy=<x>,<y> will depend on xrange and yrange.

• fill properties

     plot 'data' with filledcurves fc "cyan" fs solid 0.5 border lc "blue"

2.13 financebars ¶

The financebars style is only relevant for 2D data plotting of financial data. It requires 1 x coordinate (usually a date) and 4 y values (prices).

     5 columns:   date  open  low  high  close

An additional (6th) input column may be used to provide variable (per-record) color information (see ‘linecolor‘ and ‘rgbcolor variable‘).

The symbol is a vertical line segment, located horizontally at the x coordinate and limited vertically by the high and low prices. A horizontal tic on the left marks the opening price and one on the right marks the closing price. The length of these tics may be changed by errorbars. The symbol will be unchanged if the high and low prices are interchanged. See errorbars and candlesticks, and also the finance demo.

2.14 fillsteps ¶

     plot <data> with fillsteps {above|below} {y=<baseline>}

The fillsteps style is only relevant to 2D plotting. It is exactly like the style steps except that the area between the curve and the baseline (default y=0) is filled in the current fill style. The options ‘above‘ and ‘below‘ fill only the portion to one side of the baseline. Note that in moving from one data point to the next, both steps and fillsteps first trace the change in x coordinate and then the change in y coordinate. See steps.

2.15 fsteps ¶

The fsteps style is only relevant to 2D plotting. It connects consecutive points with two line segments: the first from (x1,y1) to (x1,y2) and the second from (x1,y2) to (x2,y2). The input column requires are the same as for plot styles ‘lines‘ and ‘points‘. The difference between fsteps and steps is that fsteps traces first the change in y and then the change in x. steps traces first the change in x and then the change in y.

See also steps demo.

2.16 histeps ¶

The histeps style is only relevant to 2D plotting. It is intended for plotting histograms. Y-values are assumed to be centered at the x-values; the point at x1 is represented as a horizontal line from ((x0+x1)/2,y1) to ((x1+x2)/2,y1). The lines representing the end points are extended so that the step is centered on at x. Adjacent points are connected by a vertical line at their average x, that is, from ((x1+x2)/2,y1) to ((x1+x2)/2,y2). The input column requires are the same as for plot styles ‘lines‘ and ‘points‘.

If autoscale is in effect, it selects the xrange from the data rather than the steps, so the end points will appear only half as wide as the others. See also steps demo.

2.17 heatmaps ¶

Several of gnuplot’s plot styles can be used to create heat maps. The choice of which style to use is dictated by the type of data.

Pixel-based heat maps all have the property that each pixel in the map corresponds exactly to one original data value. The pixel-based image styles require a regular rectangular grid of data values; see ‘with image‘. However it is possible to handle missing grid values (see ‘sparse‘) and it is also possible to mask out only a portion of the grid for display (see masking). Unless there are a large number of grid elements, it is usually good to render each rectangular element separately (‘with image pixels‘) so that smoothing or lossy compression is not applied to the resulting "image".

A polar equivalent to image pixel-based heat maps can be generated using 2D plot style sectors. Each input point corresponds to exactly one annular sector of a polar grid, equivalent to a pixel. Unlike the polar grid surface option described below, any number of individual grid sectors may be provided. This plot style can be used in either polar or cartesian coordinate plots to place polar sectors anywhere on the graph. The figure here shows two halves of a polar heat map displaced across the origin by +/- Δx on a cartesian coordinate plot. See sectors.

If the data points do not constitute a regular rectangular grid, they can often be used to fit a gridded surface by interpolation or by splines. Alternatively a point-density function can be mapped onto a gridded plane or smooth surface. See dgrid3d. The gridded surface can then be plotted as a pm3d surface (see masking example). In this case the points on the heat map do not retain a one-to-one correspondence with the input data. I.e. the validity of the heat map represenation is only as good as the gridded approximation. The demo collection has examples of generating 2D heatmaps from a set of points heatmap_points.dem

If your copy of gnuplot was built with the –enable-polar-grid option, polar coordinate data points can be used to generate a 2D polar heat map in which each "pixel" corresponded to a pre-determined range of theta and r. See ‘set polar grid‘ and ‘with surface‘. This process is exactly analogous to the use of dgrid3d and ‘with pm3d‘ except that it operates in 2D polar coordinate space.

2.18 histograms ¶

The histograms style is only relevant to 2D plotting. It produces a bar chart from a sequence of parallel data columns. Each element of the ‘plot‘ command must specify a single input data source (e.g. one column of the input file), possibly with associated tic values or key titles. Four styles of histogram layout are currently supported.

      set style histogram clustered {gap <gapsize>}
      set style histogram errorbars {gap <gapsize>} {<linewidth>}
      set style histogram rowstacked
      set style histogram columnstacked
      set style histogram {title font "name,size" tc <colorspec>}

The default style corresponds to ‘set style histogram clustered gap 2‘. In this style, each set of parallel data values is collected into a group of boxes clustered at the x-axis coordinate corresponding to their sequential position (row #) in the selected datafile columns. Thus if <n> datacolumns are selected, the first cluster is centered about x=1, and contains <n> boxes whose heights are taken from the first entry in the corresponding <n> data columns. This is followed by a gap and then a second cluster of boxes centered about x=2 corresponding to the second entry in the respective data columns, and so on. The default gap width of 2 indicates that the empty space between clusters is equivalent to the width of 2 boxes. All boxes derived from any one column are given the same fill color and/or pattern; however see the subsection ‘histograms colors‘.

Each cluster of boxes is derived from a single row of the input data file. It is common in such input files that the first element of each row is a label. Labels from this column may be placed along the x-axis underneath the appropriate cluster of boxes with the ‘xticlabels‘ option to ‘using‘.

The errorbars style is very similar to the ‘clustered‘ style, except that it requires additional columns of input for each entry. The first column holds the height (y value) of that box, exactly as for the ‘clustered‘ style.

     2 columns:        y yerr          bar extends from y-yerr to y+err
     3 columns:        y ymin ymax     bar extends from ymin to ymax

The appearance of the error bars is controlled by the current value of errorbars and by the optional <linewidth> specification.

Two styles of stacked histogram are supported, chosen by the command ‘set style histogram {rowstacked|columnstacked}‘. In these styles the data values from the selected columns are collected into stacks of boxes. Positive values stack upwards from y=0; negative values stack downwards. Mixed positive and negative values will produce both an upward stack and a downward stack. The default stacking mode is ‘rowstacked‘.

The ‘rowstacked‘ style places a box resting on the x-axis for each data value in the first selected column; the first data value results in a box a x=1, the second at x=2, and so on. Boxes corresponding to the second and subsequent data columns are layered on top of these, resulting in a stack of boxes at x=1 representing the first data value from each column, a stack of boxes at x=2 representing the second data value from each column, and so on. All boxes derived from any one column are given the same fill color and/or pattern (see ‘set style fill‘).

The ‘columnstacked‘ style is similar, except that each stack of boxes is built up from a single data column. Each data value from the first specified data column yields a box in the stack at x=1, each data value from the second specified data column yields a box in the stack at x=2, and so on. In this style the color of each box is taken from the row number, rather than the column number, of the corresponding data field.

Box widths may be modified using the boxwidth command. Box fill styles may be set using the ‘set style fill‘ command.

Histograms always use the x1 axis, but may use either y1 or y2. If a plot contains both histograms and other plot styles, the non-histogram plot elements may use either the x1 or the x2 axis.

One additional style option ‘set style histogram nokeyseparators‘ is relevant only to plots that contain multiple histograms. See newhistogram for additional discussion of this case.

Examples: Suppose that the input file contains data values in columns 2, 4, 6, ... and error estimates in columns 3, 5, 7, ... This example plots the values in columns 2 and 4 as a histogram of clustered boxes (the default style). Because we use iteration in the plot command, any number of data columns can be handled in a single command. See ‘plot for‘.

      set boxwidth 0.9 relative
      set style data histograms
      set style histogram cluster
      set style fill solid 1.0 border lt -1
      plot for [COL=2:4:2] 'file.dat' using COL

This will produce a plot with clusters of two boxes (vertical bars) centered at each integral value on the x axis. If the first column of the input file contains labels, they may be placed along the x-axis using the variant command

      plot for [COL=2:4:2] 'file.dat' using COL:xticlabels(1)

If the file contains both magnitude and range information for each value, then error bars can be added to the plot. The following commands will add error bars extending from (y-<error>) to (y+<error>), capped by horizontal bar ends drawn the same width as the box itself. The error bars and bar ends are drawn with linewidth 2, using the border linetype from the current fill style.

      set errorbars fullwidth
      set style fill solid 1 border lt -1
      set style histogram errorbars gap 2 lw 2
      plot for [COL=2:4:2] 'file.dat' using COL:COL+1

This shows how to plot the same data as a rowstacked histogram. Just to be different, the plot command in this example lists the separate columns individually rather than using iteration.

      set style histogram rowstacked
      plot 'file.dat' using 2, '' using 4:xtic(1)

This will produce a plot in which each vertical bar corresponds to one row of data. Each vertical bar contains a stack of two segments, corresponding in height to the values found in columns 2 and 4 of the datafile. Finally, the commands

      set style histogram columnstacked
      plot 'file.dat' using 2, '' using 4

will produce two vertical stacks, one for each column of data. The stack at x=1 will contain a box for each entry in column 2 of the datafile. The stack at x=2 will contain a box for each parallel entry in column 4 of the datafile.

Because this interchanges gnuplot’s usual interpretation of input rows and columns, the specification of key titles and x-axis tic labels must also be modified accordingly. See the comments given below.

      set style histogram columnstacked
      plot '' u 5:key(1)            # uses first column to generate key titles
      plot '' u 5 title columnhead  # uses first row to generate xtic labels

Note that the two examples just given present exactly the same data values, but in different formats.

• newhistogram
• automated iteration over multiple columns
• histogram color assignments

     newhistogram {"<title>" {font "name,size"} {tc <colorspec>}}
                  {lt <linetype>} {fs <fillstyle>} {at <x-coord>}

      set style histogram  cluster
      plot newhistogram "Set A", 'a' using 1, '' using 2, '' using 3, \
           newhistogram "Set B", 'b' using 1, '' using 2, '' using 3

      plot newhistogram "Set A" lt 4, 'a' using 1, '' using 2, '' using 3, \
           newhistogram "Set B" lt 4, 'b' using 1, '' using 2, '' using 3

       set style histogram cluster
       set style data histogram
       set style fill solid 1.0 border -1
       set xtic 1 offset character 0,0.3
       plot newhistogram "Set A", \
            'file.dat' u 1 t 1, '' u 2 t 2, \
            newhistogram "Set B" at 8, \
            'file.dat' u 2 t 2, '' u 2 t 2

      set style histogram columnstacked
      plot for [i=3:8] "datafile" using i title columnhead

     file(i) = sprintf("file_%03d.dat",i)
     array Category = ["A", "B", "C", "D", "E", "F"]
     color(c) = index(Category, strcol(c))
     set style data histogram
     plot for [i=1:8] file(i) using 2:(color(1)) linecolor variable

2.19 image ¶

The ‘image‘, rgbimage, and rgbalpha plotting styles all project a uniformly sampled grid of data values onto a plane in either 2D or 3D. The input data may be an actual bitmapped image, perhaps converted from a standard format such as PNG, or a simple array of numerical values. These plot styles are often used to produce heatmaps. For 2D heatmaps in polar coordinates, see ‘set polar grid‘.

This figure illustrates generation of a heat map from an array of scalar values. The current palette is used to map each value onto the color assigned to the corresponding pixel. See also ‘sparse‘.

      plot '-' matrix with image
      5 4 3 1 0
      2 2 0 0 1
      0 0 0 1 0
      0 1 2 4 3
      e
      e

Each pixel (data point) of the input 2D image will become a rectangle or parallelepiped in the plot. The coordinates of each data point will determine the center of the parallelepiped. That is, an M x N set of data will form an image with M x N pixels. This is different from the pm3d plotting style, where an M x N set of data will form a surface of (M-1) x (N-1) elements. The scan directions for a binary image data grid can be further controlled by additional keywords. See ‘binary keywords flipx‘, ‘keywords center‘, and ‘keywords rotate‘.

Image data can be scaled to fill a particular rectangle within a 2D plot coordinate system by specifying the x and y extent of each pixel. See ‘binary keywords dx‘ and ‘dy‘. To generate the figure at the right, the same input image was placed multiple times, each with a specified dx, dy, and origin. The input PNG image of a building is 50x128 pixels. The tall building was drawn by mapping this using ‘dx=0.5 dy=1.5‘. The short building used a mapping ‘dx=0.5 dy=0.35‘.

The ‘image‘ style handles input pixels containing a grayscale or color palette value. Thus 2D plots (‘plot‘ command) require 3 columns of data (x,y,value), while 3D plots (‘splot‘ command) require 4 columns of data (x,y,z,value).

The rgbimage style handles input pixels that are described by three separate values for the red, green, and blue components. Thus 5D data (x,y,r,g,b) is needed for ‘plot‘ and 6D data (x,y,z,r,g,b) for ‘splot‘. The individual red, green, and blue components are assumed to lie in the range [0:255]. This matches the convention used in PNG and JPEG files (see filetype). However some data files use an alternative convention in which RGB components are floating point values in the range [0:1]. To use the rgbimage style with such data, first use the command ‘set rgbmax 1.0‘.

The rgbalpha style handles input pixels that contain alpha channel (transparency) information in addition to the red, green, and blue components. Thus 6D data (x,y,r,g,b,a) is needed for ‘plot‘ and 7D data (x,y,z,r,g,b,a) for ‘splot‘. The r, g, b, and alpha components are assumed to lie in the range [0:255]. To plot data for which RGBA components are floating point values in the range [0:1], first use the command ‘set rgbmax 1.0‘.

If only a single data column is provided for the color components of either rgbimage or rgbalpha plots, it is interpreted as containing 32 bit packed ARGB data using the convention that alpha=0 means opaque and alpha=255 means fully transparent. Note that this is backwards from the alpha convention if alpha is supplied in a separate column, but matches the ARGB packing convention for individual commands to set color. See colorspec.

• transparency
• image pixels

      plot 'data' with image pixels

2.20 impulses ¶

The impulses style displays a vertical line from y=0 to the y value of each point (2D) or from z=0 to the z value of each point (3D). Note that the y or z values may be negative. Data from additional columns can be used to control the color of each impulse. To use this style effectively in 3D plots, it is useful to choose thick lines (linewidth > 1). This approximates a 3D bar chart.

     1 column:   y
     2 columns:  x  y     # line from [x,0] to [x,y]  (2D)
     3 columns:  x  y  z  # line from [x,y,0] to [x,y,z] (3D)

2.21 labels ¶

The labels style reads coordinates and text from a data file and places the text string at the corresponding 2D or 3D position. 3 or 4 input columns of basic data are required. Additional input columns may be used to provide properties that vary point by point such as text rotation angle (keywords ‘rotate variable‘) or color (see ‘textcolor variable‘).

     3 columns:  x  y  string    # 2D version
     4 columns:  x  y  z  string # 3D version

The font, color, rotation angle and other properties of the printed text may be specified as additional command options (see ‘set label‘). The example below generates a 2D plot with text labels constructed from the city whose name is taken from column 1 of the input file, and whose geographic coordinates are in columns 4 and 5. The font size is calculated from the value in column 3, in this case the population.

  CityName(String,Size) = sprintf("{/=%d %s}", Scale(Size), String)
  plot 'cities.dat' using 5:4:(CityName(stringcolumn(1),$3)) with labels

If we did not want to adjust the font size to a different size for each city name, the command would be much simpler:

  plot 'cities.dat' using 5:4:1 with labels font "Times,8"

If the labels are marked as hypertext then the text only appears if the mouse is hovering over the corresponding anchor point. See hypertext. In this case you must enable the label’s ‘point‘ attribute so that there is a point to act as the hypertext anchor:

  plot 'cities.dat' using 5:4:1 with labels hypertext point pt 7

The labels style can also be used in place of the ‘points‘ style when the set of predefined point symbols is not suitable or not sufficiently flexible. For example, here we define a set of chosen single-character symbols and assign one of them to each point in a plot based on the value in data column 3:

  set encoding utf8
  symbol(z) = "∙□+⊙♠♣♡♢"[int(z):int(z)]
  splot 'file' using 1:2:(symbol($3)) with labels

This example shows use of labels with variable rotation angle in column 4 and textcolor ("tc") in column 5. Note that variable color is always taken from the last column in the ‘using‘ specifier.

  plot $Data using 1:2:3:4:5 with labels tc variable rotate variable

2.22 lines ¶

The ‘lines‘ style connects adjacent points with straight line segments. It may be used in either 2D or 3D plots. The basic form requires 1, 2, or 3 columns of input data. Additional input columns may be used to provide information such as variable line color (see ‘rgbcolor variable‘).

2D form (no "using" spec)

   1 column:   y     # implicit x from row number
   2 columns:  x y

3D form (no "using" spec)

   1 column:   z     # implicit x from row, y from index
   3 columns:  x y z

See also ‘linetypes‘, ‘linewidth‘, and ‘linestyle‘.

2.23 linespoints ¶

The linespoints style (short form ‘lp‘) connects adjacent points with straight line segments and then goes back to draw a small symbol at each point. Points are drawn with the default size determined by pointsize unless a specific point size is given in the plot command or a variable point size is provided in an additional column of input data. Additional input columns may also be used to provide information such as variable line color. See ‘lines‘ and ‘points‘.

Two keywords control whether or not every point in the plot is marked with a symbol, ‘pointinterval‘ (short form ‘pi‘) and ‘pointnumber‘ (short form ‘pn‘).

‘pi N‘ or ‘pi -N‘ tells gnuplot to only place a symbol on every Nth point. A negative value for N will erase the portion of line segment that passes underneath the symbol. The size of the erased portion is controlled by pointintervalbox.

‘pn N‘ or ‘pn -N‘ tells gnuplot to label only N of the data points, evenly spaced over the data set. As with ‘pi‘, a negative value for N will erase the portion of line segment that passes underneath the symbol.

2.24 masking ¶

The plotting style ‘with mask‘ is used to define a masking region that can be applied to pm3d surfaces or to images specified later in the same ‘plot‘ or ‘splot‘ command. Input data is interpreted as a stream of [x,y] or [x,y,z] coordinates defining the vertices of one or more polygons. As in plotting style polygons, polygons are separated by a blank line. If the mask is part of a 3D (splot) command then a column of z values is required on input but is currently not used for anything.

If a mask definition is present in the plot command, then any subsequent image or pm3d surface in the same command can be masked by adding the keyword ‘mask‘. If no mask has been defined, this keyword is ignored.

This example illustrates using the convex hull circumscribing a set of points to mask the corresponding region of a pm3d surface.

   set table $HULL
   plot $POINTS using 1:2 convexhull
   unset table

   set view map
   set multiplot layout 1,2
   splot $POINTS using 1:2:3 with pm3d, \
         $POINTS using 1:2:(0) nogrid with points
   splot $HULL using 1:2:(0) with mask, \
         $POINTS using 1:2:3 mask with pm3d
   unset multiplot

The ‘splot‘ command for the first panel renders the unmasked surface created by dgrid3d from the original points and then the points themselves, in that order. The ‘splot‘ command for the second panel renders the masked surface. Note that definition of the mask must come first (plot ‘with mask‘), followed by the pm3d surface it applies to (plot style ‘with pm3d‘ modified by the ‘mask‘ keyword). A more complete version of this example is in the demo collection mask_pm3d.dem

Although it is not shown here, a single mask can include multiple polygonal regions.

The masking commands are EXPERIMENTAL. Details may change in a future release.

2.25 parallelaxes ¶

Parallel axis plots can highlight correlation in a multidimensional data set. Individual columns of input data are each associated with a separately scaled vertical axis. If all columns are drawn from a single file then each line on the plot represents values from a single row of data in that file. It is common to use some discrete categorization to assign line colors, allowing visual exploration of the correlation between this categorization and the axis dimensions.

Syntax:

    set style data parallelaxes
    plot $DATA using col1{:varcol1} {at <xpos>} {<line properties}, \
         $DATA using col2, ...

The ‘at‘ keyword allows explicit placement of the parallel vertical axes along the x axis as in the example below. If no explicit x coordinate is provide axis N will be placed at x=N.

     array xpos[5] = [1, 5, 6, 7, 11, 12]
     plot for [col=1:5] $DATA using col with parallelaxes at xpos[col]

By default gnuplot will automatically determine the range and scale of the individual axes from the input data, but the usual ‘set axis range‘ commands can be used to customize this. See paxis.

2.26 Polar plots ¶

Polar plots are generated by changing the current coordinate system to polar before issuing a plot command. The option ‘set polar‘ tells gnuplot to interpret input 2D coordinates as <angle>,<radius> rather than <x>,<y>. Many, but not all, of the 2D plotting styles work in polar mode. The figure shows a combination of plot styles ‘lines‘ and filledcurves. See ‘set polar‘, rrange, ‘set size square‘, theta, ttics.

Polar heatmaps can be generated using plot style ‘with surface‘ together with ‘set polar grid‘.

     set size square
     set angle degrees
     set rtics
     set grid polar
     set palette cubehelix negative gamma 0.8
     set polar grid gauss kdensity scale 35
     set polar grid theta [0:190]
     plot DATA with surface, DATA with points pt 7

2.27 points ¶

The ‘points‘ style displays a small symbol at each point. The command pointsize may be used to change the default size of all points. The point type defaults to that of the linetype. See ‘linetypes‘. If no ‘using‘ spec is found in the plot command, input data columns are interpreted implicitly in the order ‘x y pointsize pointtype color‘ as described below.

The first 8 point types are shared by all terminals. Individual terminals may provide a much larger number of distinct point types. Use the ‘test‘ command to show what is provided by the current terminal settings.

Alternatively any single printable character may be given instead of a numerical point type, as in the example below. You may use any unicode character as the pointtype (assumes utf8 support). See ‘escape sequences‘. Longer strings may be plotted using plot style labels rather than ‘points‘.

     plot f(x) with points pt "#"
     plot d(x) with points pt "\U+2299"

• variable point properties

     # Input data provides [x,y] in columns 1:2
     # point size is given in column 5
     # RGB color is given as hexadecimal value in column 4
     # all points use pointtype 7
       plot DATA using 1:2:5:4 with points lc rgb variable ps variable pt 7

    textrotation : pointsize : pointtype : color

2.28 polygons ¶

2D plots:

     plot DATA {using 1:2} with polygons

polygons is treated as ‘plot with filledcurves closed‘ except that each polygon’s border is rendered as a closed curve even if its first and last points are not the same. The border line type is taken from the fill style. The input data file may contain multiple polygons separated by single blank lines. Each polygon can be assigned a separate fill color by providing a third using specifier and the keywords ‘fc variable‘ (value is interpreted as a linetype) or ‘fc rgb variable‘ (value is interpreted as a 24-bit RGB color). Only the color value from the first vertex of the polygon is used.

3D plots:

     splot DATA {using x:y:z} with polygons
           {fillstyle <fillstyle spec>}
           {fillcolor <colorspec>}

polygons uses pm3d to render individual triangles, quadrangles, and larger polygons in 3D. These may be facets of a 3D surface or isolated shapes. The code assumes that the vertices lie in a plane. Vertices defining individual polygons are read from successive records of the input file. A blank line separates one polygon from the next.

The fill style and color may be specified in the splot command, otherwise the global fillstyle from ‘set style fill‘ is used. Due to limitations in the pm3d code, a single border line style from border is applied to all 3D polygons. This restriction may be removed in a later gnuplot version, which will impose a distinction between the linecolor and fillcolor properties.

Each polygon may be assigned a separate fill color by providing a fourth using specifier and the keywords ‘fc variable‘ (value is interpreted as a linetype) or ‘fc rgb variable‘ (value is interpreted as a 24-bit RGB color). Only the color value from the first vertex of the polygon is used.

pm3d sort order and lighting are applied to the faces. It is probably always desirable to use ‘set pm3d depthorder‘.

     set xyplane at 0
     set view equal xyz
     unset border
     unset tics
     set pm3d depth
     set pm3d border lc "black" lw 1.5
     splot 'icosahedron.dat' with polygons \
           fs transparent solid 0.8 fc bgnd

2.29 rgbalpha ¶

See ‘image‘.

2.30 rgbimage ¶

See ‘image‘.

2.31 sectors ¶

The 2D plotting style sectors renders one annular segment ("sector") for each line of input data. The shape of each sector is described by four required data values. An additional pair of data values can be included to specify the origin of the annulus this sector is taken from. A per-sector color may be provided in an additional column.

The plot style itself can be used in either cartesian or polar mode (‘set polar‘). The units and interpretation for the azimuth and the sector angle are controlled using angles and theta.

Columns 1 and 2 specify the azimuth (theta) and radius (r) of one corner of the sector. Columns 3 and 4 specify the angular and radial extents of the sector ("sector_angle" and "annular_width"). Columns 5 and 6, if present, specify the coordinates of the center of the annulus (default [0,0]). The interpretation is [x,y] in cartesian mode and [theta,r] in polar mode.

Syntax:

    plot DATA {using specifier} {units xy | units xx | units yy}

using specifier

    4 columns: azimuth radius sector_angle annular_width
    5 columns: azimuth radius sector_angle annular_width color
    6 columnd: azimuth radius sector_angle annular_width center_x center_y
    7 columns: azimuth radius sector_angle annular_width center_x center_y color

Note that if the x and y axis scales are not equal, the envelope of the full annulus in x/y coordinates will appear as an ellipse rather than a circle. The annulus envelope and thus the apparent sector annular width can be adjusted to correct for unequal axis scales using the same mechanism as for ellipses. Adding ‘units xx‘ to the command line causes the sector to be rendered as if the current x axis scale applied equally to both x and y. Similarly ‘units yy‘ causes the sector to be rendered as if the current y axis scale applied equally to both x and y. See isotropic, ‘set style ellipse‘.

Plotting with sectors can provide polar coordinate equivalents for the cartesian plot styles boxes (see wind rose figure), boxxyerror and ‘image pixels‘ (see example in heatmaps). Because sector plots are compatible with cartesian mode plot layout, multiple plots can be placed at different places on a single graph, which would not be possible for other polar mode plot styles.

An example of using sectors to create a wind rose in shown here. Other applications include polar heatmaps, dial charts, pie/donut charts, and annular error boxes for data points in polar coordinates. Worked examples for all of these are given in the sectors demo.

2.32 spiderplot ¶

Spider plots are essentially parallel axis plots in which the axes are arranged radially rather than vertically. Such plots are sometimes called ‘radar charts‘. In gnuplot this requires working within a coordinate system established by the command spiderplot, analogous to ‘set polar‘ except that the angular coordinate is determined implicitly by the parallel axis number. The appearance, labelling, and tic placement of the axes is controlled by paxis. Further style choices are controlled using spiderplot, ‘set grid‘, and the individual components of the plot command.

Because each spider plot corresponds to a row of data rather than a column, it would make no sense to generate key entry titles in the normal way. Instead, if a plot component contains a title the text is used to label the corresponding axis. This overrides any previous ‘set paxis n label "Foo"‘. To place a title in the key, you can either use a separate ‘keyentry‘ command or extract text from a column in the input file with the ‘key(column)‘ using specifier. See ‘keyentry‘, ‘using key‘.

In this figure a spiderplot with 5 axes is used to compare multiple entities that are each characterized by five scores. Each line (row) in $DATA generates a new polygon on the plot.

     $DATA << EOD
              A      B      C      D      E      F
     George  15     75     20     43     90     50
     Harriet 40     40     40     60     30     50
     EOD
     set spiderplot
     set style spiderplot fs transparent solid 0.2 border
     set for [p=1:5] paxis p range [0:100]
     set for [p=2:5] paxis p tics format ""
     set             paxis 1 tics font ",9"
     set for [p=1:5] paxis p label sprintf("Score %d",p)
     set grid spiderplot
     plot for [i=1:5] $DATA using i:key(1)

• newspiderplot

     # One polygon with 10 vertices
     plot for [i=1:5] 'A' using i, for [j=1:5] 'B' using j
     # Two polygons with 5 vertices
     plot for [i=1:5] 'A' using i, newspiderplot, for [j=1:5] 'B' using j

2.33 steps ¶

The steps style is only relevant to 2D plotting. It 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 input column requires are the same as for plot styles ‘lines‘ and ‘points‘. The difference between fsteps and steps is that fsteps traces first the change in y and then the change in x. steps traces first the change in x and then the change in y. To fill the area between the curve and the baseline at y=0, use fillsteps. See also steps demo.

2.34 surface ¶

The plot style ‘with surface‘ has two uses.

In 3D plots, ‘with surface‘ always produces a surface. If a 3D data set is recognizable as a mesh (grid) then by default the program implicitly treats the plot style ‘with lines‘ as requesting a gridded surface, making ‘with lines‘ a synonym for ‘with surface‘. However the command ‘set surface explicit‘ suppresses this treatment, in which case ‘with surface‘ and ‘with lines‘ become distinct styles that may be used in the same plot.

If you have points in 3D that are not recognized as a grid, you may be able to fit a suitable grid first. See dgrid3d.

In 2D polar mode plots, ‘with surface‘ is used to produce a solid fill gridded represention of the data. Generation of the surface is controlled using the command ‘set polar grid‘.

2.35 vectors ¶

The 2D vectors style draws a vector from (x,y) to (x+xdelta,y+ydelta). The 3D vectors style is similar, but requires six columns of basic data. In both cases, an additional input column (5th in 2D, 7th in 3D) may be used to provide variable (per-datapoint) color information. (see ‘linecolor‘ and ‘rgbcolor variable‘). A small arrowhead is drawn at the end of each vector.

     4 columns:  x  y  xdelta  ydelta
     6 columns:  x  y  z  xdelta  ydelta  zdelta

The keywords "with vectors" may be followed by inline arrow style properties, by reference to a predefined arrow style, or by a request to read the index of the desired arrow style for each vector from a separate input column. See the first three examples below.

Examples:

     plot ... using 1:2:3:4 with vectors filled heads
     plot ... using 1:2:3:4 with vectors arrowstyle 3
     plot ... using 1:2:3:4:5 with vectors arrowstyle variable
     splot 'file.dat' using 1:2:3:(1):(1):(1) with vectors filled head lw 2

Notes: You cannot mix the ‘arrowstyle‘ keyword with other line style qualifiers in the plot command. An additional column of color values is required if the arrow style includes ‘lc variable‘ or ‘lc rgb variable‘.

splot with vectors is supported only for ‘set mapping cartesian‘. ‘set clip one‘ and ‘set clip two‘ affect vectors drawn in 2D. See ‘set clip‘ and ‘arrowstyle‘.

See also the 2D plot style ‘with arrows‘ that is identical to vectors except that each arrow is specified using x:y:length:angle.

2.36 xerrorbars ¶

The xerrorbars style is only relevant to 2D data plots. xerrorbars is like ‘points‘, except that a horizontal error bar is also drawn. At each point (x,y), a line is drawn from (xlow,y) to (xhigh,y) or from (x-xdelta,y) to (x+xdelta,y), depending on how many data columns are provided. The appearance of the tic mark at the ends of the bar is controlled by errorbars. The clearance between the point and the error bars is controlled by pointintervalbox. To have the error bars pass directly through the point with no interruption, use pointintervalbox. The basic style requires either 3 or 4 columns:

     3 columns:  x  y  xdelta
     4 columns:  x  y  xlow  xhigh

An additional input column (4th or 5th) may be used to provide variable color. This style does not permit variable point properties.

2.37 xyerrorbars ¶

The xyerrorbars style is only relevant to 2D data plots. xyerrorbars is like ‘points‘, except that horizontal and vertical error bars are also drawn. At each point (x,y), lines are drawn from (x,y-ydelta) to (x,y+ydelta) and from (x-xdelta,y) to (x+xdelta,y) or from (x,ylow) to (x,yhigh) and from (xlow,y) to (xhigh,y), depending upon the number of data columns provided. The appearance of the tic mark at the ends of the bar is controlled by errorbars. The clearance between the point and the error bars is controlled by pointintervalbox. To have the error bars pass directly through the point with no interruption, use pointintervalbox. Either 4 or 6 input columns are required.

     4 columns:  x  y  xdelta  ydelta
     6 columns:  x  y  xlow  xhigh  ylow  yhigh

If data are provided in an unsupported mixed form, the ‘using‘ specifier of the ‘plot‘ command should be used to set up the appropriate form. For example, if the data are of the form (x,y,xdelta,ylow,yhigh), then you can use

      plot 'data' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars

An additional input column (5th or 7th) may be used to provide variable color. This style does not permit variable point properties.

2.38 xerrorlines ¶

The xerrorlines style is only relevant to 2D data plots. xerrorlines is like linespoints, except that a horizontal error line is also drawn. At each point (x,y), a line is drawn from (xlow,y) to (xhigh,y) or from (x-xdelta,y) to (x+xdelta,y), depending on how many data columns are provided. The appearance of the tic mark at the ends of the bar is controlled by errorbars. The basic style requires either 3 or 4 columns:

     3 columns:  x  y  xdelta
     4 columns:  x  y  xlow  xhigh

An additional input column (4th or 5th) may be used to provide variable color. This style does not permit variable point properties.

2.39 xyerrorlines ¶

The xyerrorlines style is only relevant to 2D data plots. xyerrorlines is like linespoints, except that horizontal and vertical error bars are also drawn. At each point (x,y), lines are drawn from (x,y-ydelta) to (x,y+ydelta) and from (x-xdelta,y) to (x+xdelta,y) or from (x,ylow) to (x,yhigh) and from (xlow,y) to (xhigh,y), depending upon the number of data columns provided. The appearance of the tic mark at the ends of the bar is controlled by errorbars. Either 4 or 6 input columns are required.

     4 columns:  x  y  xdelta  ydelta
     6 columns:  x  y  xlow  xhigh  ylow  yhigh

If data are provided in an unsupported mixed form, the ‘using‘ specifier of the ‘plot‘ command should be used to set up the appropriate form. For example, if the data are of the form (x,y,xdelta,ylow,yhigh), then you can use

      plot 'data' using 1:2:($1-$3):($1+$3):4:5 with xyerrorlines

An additional input column (5th or 7th) may be used to provide variable color. This style does not permit variable point properties.

2.40 yerrorbars ¶

The yerrorbars (or errorbars) style is only relevant to 2D data plots. yerrorbars is like ‘points‘, except that a vertical error bar is also drawn. At each point (x,y), a line is drawn from (x,y-ydelta) to (x,y+ydelta) or from (x,ylow) to (x,yhigh), depending on how many data columns are provided. The appearance of the tic mark at the ends of the bar is controlled by errorbars. The clearance between the point and the error bars is controlled by pointintervalbox. To have the error bars pass directly through the point with no interruption, use pointintervalbox.

     2 columns:  [implicit x] y ydelta
     3 columns:  x  y  ydelta
     4 columns:  x  y  ylow  yhigh

Additional input columns may be used to provide information such as variable point size, point type, or color.

See also errorbar demo.

2.41 yerrorlines ¶

The yerrorlines (or ‘errorlines‘) style is only relevant to 2D data plots. yerrorlines is like linespoints, except that a vertical error line is also drawn. At each point (x,y), a line is drawn from (x,y-ydelta) to (x,y+ydelta) or from (x,ylow) to (x,yhigh), depending on how many data columns are provided. The appearance of the tic mark at the ends of the bar is controlled by errorbars. Either 3 or 4 input columns are required.

     3 columns:  x  y  ydelta
     4 columns:  x  y  ylow  yhigh

Additional input columns may be used to provide information such as variable point size, point type, or color.

See also errorbar demo.

2.42 3D plots ¶

3D plots are generated using the command ‘splot‘ rather than ‘plot‘. Many of the 2D plot styles (points, images, impulse, labels, vectors) can also be used in 3D by providing an extra column of data containing z coordinate. Some plot types (pm3d coloring, surfaces, contours) must be generated using the ‘splot‘ command even if only a 2D projection is wanted.

• surface plots
• 2D projection (set view map)
• PM3D plots

2.43 Fence plots ¶

Fence plots combine several 2D plots by aligning their Y coordinates and separating them from each other by a displacement along X. Filling the area between a base value and each plot’s series of Z values enhances the visual impact of the alignment on Y and comparison on Z. There are several ways such plots can be created in gnuplot. The simplest is to use the 5 column variant of the ‘zerrorfill‘ style. Suppose there are separate curves z = Fi(y) indexed by i. A fence plot is generated by ‘splot with zerrorfill‘ using input columns

     i y z_base z_base Fi(y)

2.44 isosurface ¶

This 3D plot style requires a populated voxel grid (see vgrid, vfill). Linear interpolation of voxel grid values is used to estimate fractional grid coordinates corresponding to the requested isolevel. These points are then used to generate a tessellated surface. The facets making up the surface are rendered as pm3d polygons, so the surface coloring, transparency, and border properties are controlled by ‘set pm3d‘. In general the surface is easier to interpret visually if facets are given a thin border that is darker than the fill color. By default the tessellation uses a mixture of quadrangles and triangles. To use triangle only, see isosurface. Example:

     set style fill solid 0.3
     set pm3d depthorder border lc "blue" lw 0.2
     splot $helix with isosurface level 10 fc "cyan"

2.45 Zerrorfill ¶

Syntax:

     splot DATA using 1:2:3:4[:5] with zerrorfill {fc|fillcolor <colorspec>}
                {lt|linetype <n>} {<line properties>}

The ‘zerrorfill‘ plot style is similar to one variant of the 2D plot style filledcurves. It fills the area between two functions or data lines that are sampled at the same x and y points. It requires 4 or 5 input columns:

     4 columns:  x  y  z  zdelta
     5 columns:  x  y  z  zlow  zhigh

The area between zlow and zhigh is filled and then a line is drawn through the z values. By default both the line and the fill area use the same color, but you can change this in the splot command. The fill area properties are also affected by the global fill style; see ‘set style fill‘.

If there are multiple curves in the splot command each new curve may occlude all previous curves. To get proper depth sorting so that curves can only be occluded by curves closer to the viewer, use ‘set pm3d depthorder base‘. Unfortunately this causes all the filled areas to be drawn after all of the corresponding lines of z values. In order to see both the lines and the depth-sorted fill areas you probably will need to make the fill areas partially transparent or use pattern fill rather than solid fill.

The fill area in the first two examples below is the same.

     splot 'data' using 1:2:3:4 with zerrorfill fillcolor "grey" lt black
     splot 'data' using 1:2:3:($3-$4):($3+$4) with zerrorfill
     splot '+' using 1:(const):(func1($1)):(func2($1)) with zerrorfill
     splot for [k=1:5] datafile[k] with zerrorfill lt black fc lt (k+1)

This plot style can also be used to create fence plots. See ‘fenceplots‘.

2.46 Animation ¶

Any of gnuplot’s interactive terminals (qt win wxt x11 aqua) can be used to display an animation by plotting successive frames from the command line or from a script.

Several non-mousing terminals also support some form of animation. See ‘term sixelgd‘, ‘term kittycairo‘.

Two terminals can save an animation to a file for later playback locally or by embedding it a web page. See ‘term gif animate‘, ‘term webp‘.

Example:

     unset border; unset tics; unset key; set view equal xyz
     set pm3d border linecolor "black"

     set term webp animate delay 50
     set output 'spinning_d20.webp'
     do for [ang=1:360:2] {
         set view 60, ang
         splot 'icosahedron.dat' with polygons fc "gold"
     }
     unset output

3.1 Break ¶

The ‘break‘ command is only meaningful inside the bracketed iteration clause of a ‘do‘ or ‘while‘ statement. It causes the remaining statements inside the bracketed clause to be skipped and iteration is terminated. Execution resumes at the statement following the closing bracket. See also ‘continue‘.

3.2 cd ¶

The ‘cd‘ command changes the working directory.

Syntax:

      cd '<directory-name>'

The directory name must be enclosed in quotes.

Examples:

      cd 'subdir'
      cd ".."

It is recommended that Windows users use single-quotes, because backslash [\] has special significance inside double-quotes and has to be escaped. For example,

      cd "c:\newdata"

fails, but

      cd 'c:\newdata'
      cd "c:\\newdata"

work as expected.

3.3 call ¶

The call command is identical to the ‘load‘ command with one exception: the name of the file being loaded may be followed by up to nine parameters.

     call "inputfile" <param-1> <param-2> <param-3> ... <param-9>

Gnuplot now provides a set of string variables ARG0, ARG1, ..., ARG9 and an integer variable ARGC. When a call command is executed ARG0 is set to the name of the input file, ARGC is set to the number of parameters present, and ARG1 to ARG9 are loaded from the parameters that follow it on the command line. Any existing contents of the ARG variables are saved and restored across a call command.

Because the parameters ARG1 ... ARG9 are stored in ordinary string variables they may be dereferenced by macro expansion. However in many cases it is more natural to use them as you would any other variable.

In parallel with the string representation of parameters ARG1 ... ARG9, the parameters themselves are stored in an array ARGV[9]. See ‘ARGV‘.

DEPRECATED: Versions prior to 5.0 performed macro-like substitution of the special tokens $0, $1, ... $9 with the literal contents of <param-1> ... That older mechanism is no longer supported.

EXPERIMENTAL: Function blocks (new in this version) provide a more flexible alternative to call. See ‘function blocks‘.

• ARGV[ ]
• Example

     call 'routine_1.gp'  1 pi "title"

     ARGC = 3
     ARG1 = "1"         ARGV[1] = 1.0
     ARG2 = "3.14159"   ARGV[2] = 3.14159265358979...
     ARG3 = "title"     ARGV[3] = "title"

     Call site
         MYFILE = "script1.gp"
         FUNC = "sin(x)"
         call MYFILE FUNC 1.23 "This is a plot title"
     Upon entry to the called script
         ARG0 holds "script1.gp"
         ARG1 holds the string "sin(x)"
         ARG2 holds the string "1.23"
         ARG3 holds the string "This is a plot title"
         ARGC is 3
     The script itself can now execute
         plot @ARG1 with lines title ARG3
         print ARG2 * 4.56, @ARG2 * 4.56
         print "This plot produced by script ", ARG0

     gnuplot -persist -c "script1.gp" "sin(x)" 1.23 "This is a plot title"

3.4 clear ¶

The clear command erases the current screen or output device as specified by terminal and output. This usually generates a formfeed on hardcopy devices.

For some terminals clear erases only the portion of the plotting surface defined by size, so for these it can be used in conjunction with multiplot to create an inset.

Example:

      set multiplot
      plot sin(x)
      set origin 0.5,0.5
      set size 0.4,0.4
      clear
      plot cos(x)
      unset multiplot

Please see multiplot, size, and origin for details.

3.5 Continue ¶

The ‘continue‘ command is only meaningful inside the bracketed iteration clause of a ‘do‘ or ‘while‘ statement. It causes the remaining statements inside the bracketed clause to be skipped. Execution resumes at the start of the next iteration (if any remain in the loop condition). See also ‘break‘.

3.6 Do ¶

Syntax:

      do for <iteration-spec> {
           <commands>
           <commands>
      }

Execute a sequence of commands multiple times. The commands must be enclosed in curly brackets, and the opening "{" must be on the same line as the ‘do‘ keyword. This command cannot be used with old-style (un-bracketed) if/else statements. See if. For examples of iteration specifiers, see iteration. Example:

      set multiplot layout 2,2
      do for [name in "A B C D"] {
          filename = name . ".dat"
          set title sprintf("Condition %s",name)
          plot filename title name
      }
      unset multiplot

See also ‘while‘, ‘continue‘, ‘break‘.

3.7 evaluate ¶

The evaluate command executes gnuplot commands contained in a string or in a function block. Newline characters are not allowed within the string.

     evaluate "commands in a string constant"
     evaluate string_valued_function( ... arguments ... )
     evaluate $functionblock( ... arguments ... )

This is especially useful for a repetition of similar commands.

Example:

      set_label(x, y, text) \
        = sprintf("set label '%s' at %f, %f point pt 5", text, x, y)
      eval set_label(1., 1., 'one/one')
      eval set_label(2., 1., 'two/one')
      eval set_label(1., 2., 'one/two')

Please see ‘function blocks‘ and macros for other mechanisms that construct or execute strings containing gnuplot commands.

3.8 exit ¶

     exit
     exit message "error message text"
     exit status <integer error code>

The commands exit and quit, as well as the END-OF-FILE character (usually Ctrl-D) terminate input from the current input stream: terminal session, pipe, or file input (pipe). If input streams are nested (inherited ‘load‘ scripts), then reading will continue in the parent stream. When the top level stream is closed, the program itself will exit.

The command ‘exit gnuplot‘ will immediately and unconditionally cause gnuplot to exit even if the input stream is multiply nested. In this case any open output files may not be completed cleanly. Example of use:

      bind "ctrl-x" "unset output; exit gnuplot"

The command ‘exit error "error message"‘ simulates a program error. In interactive mode it prints the error message and returns to the command line, breaking out of all nested loops or calls. In non-interactive mode the program will exit.

When gnuplot exits to the controlling shell, the return value is not usually informative. This variant of the command allows you to return a specific value.

     exit status <value>

See help for ‘batch/interactive‘ for more details.

3.9 fit ¶

The fit command fits a user-supplied real-valued expression to a set of data points, using the nonlinear least-squares Marquardt-Levenberg algorithm. There can be up to 12 independent variables, there is always 1 dependent variable, and any number of parameters can be fitted. Optionally, error estimates can be input for weighting the data points.

The basic use of fit is best explained by a simple example where a set of measured x and y values read from a file are used to be modeled by a function y = f(x).

      f(x) = a + b*x + c*x**2
      fit f(x) 'measured.dat' using 1:2 via a,b,c
      plot 'measured.dat' u 1:2, f(x)

Syntax:

      fit {<ranges>} <expression>
          '<datafile>' {datafile-modifiers}
          {{unitweights} | {y|xy|z}error | errors <var1>{,<var2>,...}}
          via '<parameter file>' | <var1>{,<var2>,...}

Ranges may be specified to filter the data used in fitting. Out-of-range data points are ignored. The syntax is

      [{dummy_variable=}{<min>}{:<max>}],

analogous to ‘plot‘; see ranges.

<expression> can be any valid ‘gnuplot‘ expression, although the most common is a previously user-defined function of the form f(x) or f(x,y). It must be real-valued. The names of the independent variables are set by the dummy command, or in the <ranges> part of the command (see below); by default, the first two are called x and y. Furthermore, the expression should depend on one or more variables whose value is to be determined by the fitting procedure.

<datafile> is treated as in the ‘plot‘ command. All the datafile modifiers (‘using‘, every,...) except smooth are applicable to fit. See datafile.

The datafile contents can be interpreted flexibly by providing a ‘using‘ qualifier as with plot commands. For example to generate the independent variable x as the sum of columns 2 and 3, while taking z from column 6 and requesting equal weights:

      fit ... using ($2+$3):6

In the absence of a ‘using‘ specification, the fit implicitly assumes there is only a single independent variable. If the file itself, or the using specification, contains only a single column of data, the line number is taken as the independent variable. If a ‘using‘ specification is given, there can be up to 12 independent variables (and more if specially configured at compile time).

The ‘unitweights‘ option, which is the default, causes all data points to be weighted equally. This can be changed by using the ‘errors‘ keyword to read error estimates of one or more of the variables from the data file. These error estimates are interpreted as the standard deviation s of the corresponding variable value and used to compute a weight for the datum as 1/s**2.

In case of error estimates of the independent variables, these weights are further multiplied by fitting function derivatives according to the "effective variance method" (Jay Orear, Am. J. Phys., Vol. 50, 1982).

The ‘errors‘ keyword is to be followed by a comma-separated list of one or more variable names for which errors are to be input; the dependent variable z must always be among them, while independent variables are optional. For each variable in this list, an additional column will be read from the file, containing that variable’s error estimate. Again, flexible interpretation is possible by providing the ‘using‘ qualifier. Note that the number of independent variables is thus implicitly given by the total number of columns in the ‘using‘ qualifier, minus 1 (for the dependent variable), minus the number of variables in the ‘errors‘ qualifier.

As an example, if one has 2 independent variables, and errors for the first independent variable and the dependent variable, one uses the ‘errors x,z‘ qualifier, and a ‘using‘ qualifier with 5 columns, which are interpreted as x:y:z:sx:sz (where x and y are the independent variables, z the dependent variable, and sx and sz the standard deviations of x and z).

A few shorthands for the ‘errors‘ qualifier are available: ‘yerrors‘ (for fits with 1 column of independent variable), and ‘zerrors‘ (for the general case) are all equivalent to ‘errors z‘, indicating that there is a single extra column with errors of the dependent variable.

‘xyerrors‘, for the case of 1 independent variable, indicates that there are two extra columns, with errors of both the independent and the dependent variable. In this case the errors on x and y are treated by Orear’s effective variance method.

Note that ‘yerror‘ and ‘xyerror‘ are similar in both form and interpretation to the yerrorlines and xyerrorlines 2D plot styles.

With the command ‘set fit v4‘ the fit command syntax is compatible with ‘gnuplot‘ version 4. In this case there must be two more ‘using‘ qualifiers (z and s) than there are independent variables, unless there is only one variable. ‘gnuplot‘ then uses the following formats, depending on the number of columns given in the ‘using‘ specification:

      z                           # 1 independent variable (line number)
      x:z                         # 1 independent variable (1st column)
      x:z:s                       # 1 independent variable (3 columns total)
      x:y:z:s                     # 2 independent variables (4 columns total)
      x1:x2:x3:z:s                # 3 independent variables (5 columns total)
      x1:x2:x3:...:xN:z:s         # N independent variables (N+2 columns total)

Please beware that this means that you have to supply z-errors s in a fit with two or more independent variables. If you want unit weights you need to supply them explicitly by using e.g. then format x:y:z:(1).

The dummy variable names may be changed when specifying a range as noted above. The first range corresponds to the first ‘using‘ spec, and so on. A range may also be given for z (the dependent variable), in which case data points for which f(x,...) is out of the z range will not contribute to the residual being minimized.

Multiple datasets may be simultaneously fit with functions of one independent variable by making y a ’pseudo-variable’, e.g., the dataline number, and fitting as two independent variables. See multi-branch.

The ‘via‘ qualifier specifies which parameters are to be optimized, either directly, or by referencing a parameter file.

Examples:

      f(x) = a*x**2 + b*x + c
      g(x,y) = a*x**2 + b*y**2 + c*x*y
      set fit limit 1e-6
      fit f(x) 'measured.dat' via 'start.par'
      fit f(x) 'measured.dat' using 3:($7-5) via 'start.par'
      fit f(x) './data/trash.dat' using 1:2:3 yerror via a, b, c
      fit g(x,y) 'surface.dat' using 1:2:3 via a, b, c
      fit a0 + a1*x/(1 + a2*x/(1 + a3*x)) 'measured.dat' via a0,a1,a2,a3
      fit a*x + b*y 'surface.dat' using 1:2:3 via a,b
      fit [*:*][yaks=*:*] a*x+b*yaks 'surface.dat' u 1:2:3 via a,b

      fit [][][t=*:*] a*x + b*y + c*t 'foo.dat' using 1:2:3:4 via a,b,c

      set dummy x1, x2, x3, x4, x5
      h(x1,x2,x3,x4,s5) = a*x1 + b*x2 + c*x3 + d*x4 + e*x5
      fit h(x1,x2,x3,x4,x5) 'foo.dat' using 1:2:3:4:5:6 via a,b,c,d,e

After each iteration step, detailed information about the current state of the fit is written to the display. The same information about the initial and final states is written to a log file, "fit.log". This file is always appended to, so as to not lose any previous fit history; it should be deleted or renamed as desired. By using the command ‘set fit logfile‘, the name of the log file can be changed.

If activated by using ‘set fit errorvariables‘, the error for each fitted parameter will be stored in a variable named like the parameter, but with "_err" appended. Thus the errors can be used as input for further computations.

If ‘set fit prescale‘ is activated, fit parameters are prescaled by their initial values. This helps the Marquardt-Levenberg routine converge more quickly and reliably in cases where parameters differ in size by several orders of magnitude.

The fit may be interrupted by pressing Ctrl-C (Ctrl-Break in wgnuplot). After the current iteration completes, you have the option to (1) stop the fit and accept the current parameter values, (2) continue the fit, (3) execute a ‘gnuplot‘ command as specified by ‘set fit script‘ or the environment variable ‘FIT_SCRIPT‘. The default is replot, so if you had previously plotted both the data and the fitting function in one graph, you can display the current state of the fit.

Once fit has finished, the fit command may be used to store final values in a file for subsequent use as a parameter file. See fit for details.

• adjustable parameters
• short introduction
• error estimates
• control
• error recovery
• multi-branch
• starting values
• time data
• tips

      varname = value

      varname = value       # FIXED

     z=a*sin(c*x) + b*cos(c*x).

      FIT_NDF = Number of degrees of freedom
      FIT_WSSR = Weighted sum-of-squares residual
      FIT_STDFIT = sqrt(WSSR/NDF)
      FIT_P = p-value

      FIT_LOG

      FIT_SCRIPT

     do for [i=1:5] {
         DATA = sprintf("Data_%05d.dat", i)
         fit f(x) DATA via a,b,c
         if (FIT_ERROR || !FIT_CONVERGED) {
             print "Fit failed for ", DATA
             continue
         }
         set output sprintf("dataset_%05.png", i)
         plot DATA, f(x)
         unset output
     }

     f(x,y) = (y==0) ? a*exp(-x/tau) : b*exp(-x/tau)
     fit f(x,y) 'datafile' using  1:-2:2:3  via a, b, tau

     T(x) = a + b*x + c*x*x
     set xdata time
     fit T(x) 'hits.dat' using 1:3 via a,b,c

     set xdata time       # data format "27-02-2023 12:00:00 measurement"
     timefmt  = "%d-%m-%Y %H:%M:%S"
     set timefmt timefmt
     t0 = strptime( timefmt, "27-02-2023 00:00:00" )
     fit T(x) 'temperature.dat' using ($1-t0):3 via a,b,c

     set timefmt "%tH:%tM:%tS"
     fit T(x) 'temperature.dat' using 2:3 via a,b,c

3.10 function blocks ¶

The ‘function‘ command signals the definition of a here-document containing a named block of gnuplot code that can be called as a function. As with data blocks, the name of a function block must begin with a ’$’. Up to nine named parameters may be specified as part of the definition. These names may be used inside the function block as local variables. See ‘local‘ and ‘scope‘.

Once the function block is defined, you can invoke it by name anywhere that a normal function could be used. If the return value is not relevant, the function block may be invoked by an "evaluate" command rather than as part of an assignment expression.

Example:

     function $sinc(arg) << EOF
         if (arg == 0) { return 1.0 }
         return sin(arg) / arg
     EOF

     gnuplot> plot $sinc(x) with lines title "sinc(x) as a function block"

It is not necessary to specify a list of named arguments to a function block at the time it is declared. The number and values of arguments to the function passed from the command line can be be accessed from inside the function block as an integer variable ARGC and a corresponding array ARGV[ARGC]. See ‘ARGV‘. This allows defining a function block that can operate on a variable number of arguments. Unlike loading a file via a call statement, arguments are not repackaged as string variables (e.g. ARG1).