Master Menu

1.1 Copyright

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

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

Permission to modify the software is granted, but not the right to distribute the 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 5.0 additions:
                 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, OSX, 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 supports many types of plots in either 2D and 3D. It can draw using lines, points, boxes, contours, vector fields, surfaces, and various associated text. It also supports various specialized plot types.

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. Recent additions include interactive terminals based on wxWidgets (usable on multiple platforms), and Qt. 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 file as in the ‘load‘ command. On X11-based systems, you can use

      gnuplot {X11OPTIONS} {OPTIONS} file1 file2 ...

see your X11 documentation and ‘x11‘ in this document.

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. The options specific to gnuplot can be listed by typing

      gnuplot --help

See ‘command-line-options‘ for more details.

In sessions with an interactive plot window you can hit ’h’ anywhere on the plot for help about ‘hotkeys‘ and ‘mousing‘ features. Section ‘seeking-assistance‘ will help you to find further information, help and FAQ.

1.3 Seeking-assistance

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

          http://sourceforge.net/projects/gnuplot/support

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 on SourceForge 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

• Features introduced in version 5.4
• Features introduced in version 5.2
• Features introduced in version 5.0

1.5 Differences between versions 4 and 5

Some changes introduced in version 5 may cause certain scripts written for earlier versions of gnuplot to behave differently.

* Revised handling of input data containing NaN, inconsistent number of data columns, or other unexpected content. See Note under ‘missing‘ for examples and figures.

* Time coordinates are stored internally as the number of seconds relative to the standard unix epoch 1-Jan-1970. Earlier versions of gnuplot used a different epoch internally (1-Jan-2000). This change resolves inconsistencies introduced whenever time in seconds was generated externally. The epoch convention used by a particular gnuplot installation can be determined using the command ‘print strftime("%F",0)‘. Time is now stored to at least millisecond precision.

* The function ‘timecolumn(N,"timeformat")‘ now has 2 parameters. Because the new second parameter is not associated with any particular data axis, this allows using the ‘timecolumn‘ function to read time data for reasons other than specifying the x or y coordinate. This functionality replaces the command sequence ‘set xdata time; set timefmt "timeformat"‘. It allows combining time data read from multiple files with different formats within a single plot.

* The ‘reverse‘ keyword of the ‘set [axis]range‘ command affects only autoscaling. It does not invert or otherwise alter the meaning of a command such as ‘set xrange [0:1]‘. If you want to reverse the direction of the x axis in such a case, say instead ‘set xrange [1:0]‘.

* The call command is provides a set of variables ARGC, ARG0, ..., ARG9. ARG0 holds the name of the script file being executed. ARG1 to ARG9 are string variables and thus may either be referenced directly or expanded as macros, e.g. @ARG1. The contents of ARG0 ... ARG9 may alternatively be accessed as array elements ARGV[0] ... ARGV[ARGC]. An older gnuplot convention of referencing call parameters as tokens $0 ... $9 is deprecated.

* The optional bandwidth for the kernel density smoothing option is taken from a keyword rather than a data column. See ‘smooth kdensity‘.

1.6 Deprecated syntax

Gnuplot version 4 deprecated certain syntax used in earlier versions but provided a configuration option that allowed backward compatibility. Support for the old syntax has now been removed.

Deprecated in version 4 and removed in version 5:

      set title "Old" 0,-1
      set data linespoints
      plot 'file' thru f(x)
      plot 1 2 4               # horizontal line at y=1
      update

Current equivalent:

      TITLE = "New"
      set title TITLE offset char 0, char -1
      set style data linespoints
      plot 'file' using 1:(f(column(2)))
      plot 1 linetype 2 pointtype 4
      save fit "filename"

Deprecated in version 5

      if (defined(VARNAME)) ...
      set style increment user
      call 'script' 1.23 ABC
         (in script:  print $0, "$1", "number of args = $#")
      set fontpath
      set clabel
      fit control variables FIT_*

Current equivalent:

      if (exists("VARNAME")) ...
      set linetype
      call 'script' 1.23 "ABC"
         (in script:  print ARG1, ARG2, "number of args = ", ARGC
      set cntrlabel
      set fit <option> <value>

Deprecated in version 5.4

      # 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

Current equivalent

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

1.7 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.8 Batch/Interactive Operation

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

Any command-line arguments are assumed to be either program options (see command-line-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.9 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‘.

In earlier versions of gnuplot, some terminal types used the values from size to control also the size of the output canvas; others did not. The use of ’set size’ for this purpose was deprecated in version 4. Almost all terminals now behave as follows:

‘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. This is consistent with the way multiplot mode has always worked.

1.10 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.11 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.12 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.13 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.14 Enhanced text mode

Many terminal types support an enhanced text mode in which additional formatting information is 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 by marking individual strings as in "set label ’x_2’ noenhanced".

 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 an accent on a letter. For the latter, it is much better to use an encoding (e.g. iso_8859_1 or utf8) that contains a large variety of 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. You can, of course, use control characters by escaping them (see below), such as ’~a{\^}’

You can escape control characters using \, e.g., \\, \{, and so on. 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.15 Environment

A number of shell environment variables are understood by ‘gnuplot‘. None of these are required, but may be useful.

GNUTERM, if defined, is used to set the terminal type on start-up. Starting with version 5.2 the entire string in GNUTERM is passed to "set term" so that terminal options may be included. E.g.

     GNUTERM="postscript eps color size 5in, 3in"

This can be overridden by the ~/.gnuplot (or equivalent) start-up file (see ‘startup‘) and of course by later explicit ‘set term‘ commands.

GNUHELP may be defined to be the pathname of the HELP file (gnuplot.gih).

On VMS, the logical name GNUPLOT$HELP should be defined as the name of the help library for ‘gnuplot‘. The ‘gnuplot‘ help can be put inside any VMS system help library.

On Unix, HOME is used as the name of a directory to search for a .gnuplot file if none is found in the current directory. Additionally gnuplot searches for $XDG_CONFIG_HOME/gnuplot/gnuplotrc which is loaded after .gnuplot. On MS-DOS, Windows and OS/2, GNUPLOT is used. On Windows, the NT-specific variable USERPROFILE is also tried. VMS, SYS$LOGIN: is used. Type ‘help 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 for the shell command.

‘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. For these drivers the font search path is controlled by the environmental variable GDFONTPATH. Furthermore, a default font for these drivers may be set via the environmental variable GNUPLOT_DEFAULT_GDFONT.

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 have the postscript terminal use custom prologue files rather than the default files. See ‘postscript prologue‘.

1.16 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 arithmetic
• Constants
• Functions
• Operators
• Summation
• Gnuplot-defined variables
• User-defined variables and functions
• Arrays

     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\n456'            # string constant (\ and n are ordinary characters)

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

 given the current extremes of cbrange.

      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.

     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"

     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        * call arg/column during `using` manipulation
      ||          |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 ]

     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

1.17 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.18 Glossary

Throughout this document an attempt has been made to maintain consistency of nomenclature. This cannot be wholly successful because as ‘gnuplot‘ has evolved over time, certain command and keyword names have been adopted that preclude such perfection. This section contains explanations of the way some of these terms are used.

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; in svga mode it is the full monitor screen.

A screen may contain one or more "plots". A plot is defined by an abscissa and an ordinate, although these need not actually appear on it, as well as the margins and any text written therein.

A plot contains one "graph". A graph is defined by an abscissa and an ordinate, although these need not actually appear on it.

A graph may contain one or more "lines". A line is a single function or data set. "Line" is also a plotting style. The word will also be used in sense "a line of text". Presumably the context will remove any ambiguity.

The lines on a graph may have individual names. These may be listed together with a sample of the plotting style used to represent them in the "key", sometimes also called the "legend".

The word "title" occurs with multiple meanings in ‘gnuplot‘. In this document, it will always be preceded by the adjective "plot", "line", or "key" to differentiate among them. A 2D graph may have up to four labeled axes. The names of the four axes are "x" for the axis along the bottom border of the plot, "y" for the axis along the left border, "x2" for the top border, and "y2" for the right border. See axes.

A 3D graph may have up to three labeled axes – "x", "y" and "z". It is not possible to say where on the graph any particular axis will fall because you can change the direction from which the graph is seen with view.

When discussing data files, the term "record" will be resurrected and used to denote 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 records. 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 inline data (see ‘datablocks‘).

1.19 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.

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

1.20 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.

With one exception, gnuplot variables are global. 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.

The single exception to this is the variable used in an iteration specifier. The scope of the iteration variable 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

1.21 linetypes, colors, and styles

In older 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 version 5 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.

Examples:

     plot sin(x) lt rgb "violet"       # one of gnuplot's named colors
     plot sin(x) lt rgb "#FF00FF"      # explicit RGB triple in hexadecimal
     plot sin(x) lt palette cb -45     # whatever color corresponds to -45
                                       # in the current cbrange of the palette
     plot sin(x) lt 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. Gnuplot version 5 allows you to specify the dot-dash pattern independent of the line color. See dashtype.

• colorspec
• dashtype
• linestyles vs 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
      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
     # This will draw an "invisible" line along the x axis
     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

      # 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

     if (GPVAL_VERSION >= 5.0) set for [i=1:9] linetype i dashtype i
     if (GPVAL_VERSION < 5.0) set termoption dashed

      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

1.22 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.

1.23 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 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.24 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 [-5:5] 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.25 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 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.26 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 do 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 the current development version.

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

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. Note: The program can be configured to look first in the current directory, but this is not recommended because it is bad security practice.

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

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

 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

      f(x) = `leastsq`

      f(x) = `run leastsq`

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

      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 the ‘using‘ filter 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‘ filter 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‘.

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 the 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.

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‘). The error bar will be drawn in the same color as the border of the box.

     3 columns:  x  y  ydelta
     4 columns:  x  y  ydelta xdelta        # boxwidth != -2
     4 columns:  x  y  ylow  yhigh          # boxwidth == -2
     5 columns:  x  y  ylow  yhigh  xdelta

The boxwidth will come from the fourth column if the y errors are given as "ydelta" and the boxwidth was not previously set to -2.0 (‘set boxwidth -2.0‘) or from the fifth column if the y errors are in the form of "ylow yhigh". The special case ‘boxwidth = -2.0‘ is for four-column data with y errors in the form "ylow yhigh". In this case the boxwidth will be calculated so that each box touches the adjacent boxes. The width will also be calculated in cases where three-column data are used.

The box height is determined from the y error in the same way as it is for the yerrorbars style—either from y-ydelta to y+ydelta or from ylow to yhigh, depending on how many data columns are provided.

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 as in 2D plots.

• 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, cos(x) with boxes

     plot 'file1' with boxes fs solid 0.25 fc 'cyan', \
          'file2' with boxes fs solid 0.50 fc 'blue', \
          'file3' with boxes fs solid 0.75 fc 'magenta', \
          'file4' with boxes fill pattern 1, \
          'file5' with boxes fill empty

     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. Additional input columns may be used to provide information such as variable line or fill color (see ‘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.

An additional (5th or 7th) input column may be used to provide variable (per-datapoint) color information (see ‘linecolor‘ and ‘rgbcolor variable‘).

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, such as the median value, on a box-and-whisker plot requires additional plot commands as in this example:

  # 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. 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‘.

For 3D plots the using specifier must contain

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

where the variable color column is options. See ‘set style circle‘ and ‘set style fill‘.

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

The result is similar to using a ‘points‘ plot with variable size points and pointstyle 7, except that the circles will scale with the x axis range. See also ‘set object circle‘ and ‘fillstyle‘.

2.9 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 major_diam
     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. 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.

By default, 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 (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. This can be changed with the ‘units‘ keyword, however.

There are three alternatives: if ‘units xy‘ is included in the plot specification, the axes will be scaled as described above. ‘units xx‘ ensures that both diameters are interpreted in units of the x axis, while ‘units yy‘ means that both diameters are interpreted 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.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 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>]

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

The second variant is to fill the area between the curve and a given axis, a horizontal or vertical line, or a point.

    filledcurves closed   ... just filled closed curve,
    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.

Notes: Not all terminal types support this plotting mode.

       The x= and y= keywords are ignored for 3 columns data plots

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.12 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.13 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.14 fillsteps

     plot <data> with fillsteps [above|below] [y=<baseline>]

The fillsteps style is only relvant 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 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.16 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 (see ‘set style fill‘).

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 column yields a box in the stack at x=1, each data value from the second specified 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, this example lists the separate columns explicitly 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

     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

2.17 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.

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.

      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 parallelipiped in the plot. The coordinates of each data point will determine the center of the parallelipiped. 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.18 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.19 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.20 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 ‘linetype‘, ‘linewidth‘, and ‘linestyle‘.

2.21 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.22 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, ...

CHANGE: Version 5.4 of gnuplot introduces a change in the syntax for plot style parallelaxes. The revised syntax allows an unlimited number of parallel axes.

     gnuplot 5.2:   plot $DATA using 1:2:3:4:5 with parallelaxes
     gnuplot 5.4:   plot for [col=1:5] $DATA using col with parallelaxes

The new syntax also 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.23 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.

2.24 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 ‘linetype‘. If no ‘using‘ spec is found in the plot command, input data columns are interpreted implicitly in the order

     x y pointsize pointtype color

Any columns beyond the first two (x and y) are optional; they correspond to additional plot properties ‘pointsize variable‘, ‘pointtype variable‘, etc.

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"

When using the keywords ‘pointtype‘, pointsize, or ‘linecolor‘ in a plot command, the additional keyword ‘variable‘ may be given instead of a number. In this case the corresponding properties of each point are assigned by additional columns of input data. Variable pointsize is always taken from the first additional column provided in a ‘using‘ spec. Variable color is always taken from the last additional column. See colorspec. If all three properties are specified for each point, the order of input data columns is thus

     plot DATA using x:y:pointsize:pointtype:color \
          with points lc variable pt variable ps variable

Note: for information on user-defined program variables, see variables.

2.25 polygons

2D plots:

     plot DATA {using 1:2} with polygons

polygons is currently treated as ‘plot with filledcurves closed‘. Each polygon may be assigned a separate color by providing a third using specifier and the keywords ‘lc variable‘ (value is interpreted as a linetype) or ‘lc rgb variable‘ (value is interpreted as a 24-bit RGB color). Only the color value from the first vertex of the polygon is used. The border line type, if any, is taken from the fill style.

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. 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. pm3d sort order and lighting are applied to the faces. It is probably always desirable to use ‘set pm3d depthsort‘.

     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.26 spiderplot

Spider plots are essentially parallel axis plots in which the axes are arranged radially rather than vertically. Such plots are sometimes called ‘rader 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.

     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.27 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.28 rgbalpha

See ‘image‘.

2.29 rgbimage

See ‘image‘.

2.30 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.31 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 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.32 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. 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‘ filter on 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.33 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.

     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.34 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.35 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‘ filter on 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.36 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.37 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.38 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.39 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 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.40 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‘.

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>

Previous versions of gnuplot performed macro-like substitution of the special tokens $0, $1, ... $9 with the literal contents of these parameters. This mechanism is now deprecated (see old-style).

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 (analogous to the older deprecated syntax). However in many cases it is more natural to use them as you would any other variable.

In parallel to the string parameters ARG1 ... ARG9, the passed parameters are stored in an array ARGV[9]. See ‘argv‘.

• argv[ ]
• Example
• old-style

     call 'routine_1.gp'  1 pi "title"

     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"

      call "<input-file>" <param-0> <param-1> ... <param-9>

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

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

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

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 the commands given as an argument string. Newline characters are not allowed within the string.

Syntax:

      eval <string expression>

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 macros for another way to execute commands from a string.

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:

      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
• multi-branch
• starting values
• 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_LIMIT - use `set fit limit <epsilon>`
    FIT_MAXITER - use `set fit maxiter <number_of_cycles>`
    FIT_START_LAMBDA - use `set fit start-lambda <value>`
    FIT_LAMBDA_FACTOR - use `set fit lambda-factor <value>`
    FIT_SKIP - use the datafile every modifier
    FIT_INDEX - See multi-branch

      FIT_LOG

      FIT_SCRIPT

     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

3.10 help

The help command displays built-in help. To specify information on a particular topic use the syntax:

      help {<topic>}

If <topic> is not specified, a short message is printed about ‘gnuplot‘. After help for the requested topic is given, a menu of subtopics is given; help for a subtopic may be requested by typing its name, extending the help request. After that subtopic has been printed, the request may be extended again or you may go back one level to the previous topic. Eventually, the ‘gnuplot‘ command line will return.

If a question mark (?) is given as the topic, the list of topics currently available is printed on the screen.

3.11 history

The ‘history‘ command prints or saves previous commands in the history list, or reexecutes a previous entry in the list. To modify the behavior of this command, see ‘set history‘.

Input lines with ‘history‘ as their first command are not stored in the command history.

Examples:

      history               # show the complete history
      history 5             # show last 5 entries in the history
      history quiet 5       # show last 5 entries without entry numbers
      history "hist.gp"     # write the complete history to file hist.gp
      history "hist.gp" append # append the complete history to file hist.gp
      history 10 "hist.gp"  # write last 10 commands to file hist.gp
      history 10 "|head -5 >>diary.gp" # write 5 history commands using pipe
      history ?load         # show all history entries starting with "load"
      history ?"set c"      # like above, several words enclosed in quotes
      hist !"set xr"        # like above, several words enclosed in quotes
      hist !55              # reexecute the command at history entry 55

3.12 if

New syntax:

      if (<condition>) { <commands>;
             <commands>
             <commands>
      } else {
             <commands>
      }

Old syntax:

      if (<condition>) <command-line> [; else if (<condition>) ...; else ...]

This version of gnuplot supports block-structured if/else statements. If the keyword ‘if‘ or ‘else‘ is immediately followed by an opening "{", then conditional execution applies to all statements, possibly on multiple input lines, until a matching "}" terminates the block. If commands may be nested.

The old single-line if/else syntax is still supported, but can not be mixed with the new block-structured syntax. See if-old.

• if-old

      pi=3
      if (pi!=acos(-1)) print "?Fixing pi!"; pi=acos(-1); print pi

      ?Fixing pi!
      3.14159265358979

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

      v=0
      v=v+1; if (v%2) print "2" ; else if (v%3) print "3"; else print "fred"

3.13 for

The ‘plot‘, ‘splot‘, ‘set‘ and unset commands may optionally contain an iteration for clause. This has the effect of executing the basic command multiple times, each time re-evaluating any expressions that make use of the iteration control variable. Iteration of arbitrary command sequences can be requested using the ‘do‘ command. Two forms of iteration clause are currently supported:

      for [intvar = start:end{:increment}]
      for [stringvar in "A B C D"]

Examples:

      plot for [filename in "A.dat B.dat C.dat"] filename using 1:2 with lines
      plot for [basename in "A B C"] basename.".dat" using 1:2 with lines
      set for [i = 1:10] style line i lc rgb "blue"
      unset for [tag = 100:200] label tag

Nested iteration is supported:

      set for [i=1:9] for [j=1:9] label i*10+j sprintf("%d",i*10+j) at i,j

See additional documentation for iteration, ‘do‘.

3.14 import

The import command associates a user-defined function name with a function exported by an external shared object. This constitutes a plugin mechanism that extends the set of functions available in gnuplot. See ‘plugins‘.

Syntax:

      import func(x[,y,z,...]) from "sharedobj[:symbol]"

Examples:

      # make the function myfun, exported by "mylib.so" or "mylib.dll"
      # available for plotting or numerical calculation in gnuplot
      import myfun(x) from "mylib"
      import myfun(x) from "mylib:myfun"    # same as above

      # make the function theirfun, defined in "theirlib.so" or "theirlib.dll"
      # available under a different name
      import myfun(x,y,z) from "theirlib:theirfun"

The program extends the name given for the shared object by either ".so" or ".dll" depending on the operating system, and searches for it first as a full path name and then as a path relative to the current directory. The operating system itself may also search any directories in LD_LIBRARY_PATH or DYLD_LIBRARY_PATH.

3.15 load

The ‘load‘ command executes each line of the specified input file as if it had been typed in interactively. Files created by the save command can later be ‘load‘ed. Any text file containing valid commands can be created and then executed by the ‘load‘ command. Files being ‘load‘ed may themselves contain ‘load‘ or call commands. See ‘comments‘ for information about comments in commands. To ‘load‘ with arguments, see call.

Syntax:

      load "<input-file>"

The name of the input file must be enclosed in quotes.

The special filename "-" may be used to ‘load‘ commands from standard input. This allows a ‘gnuplot‘ command file to accept some commands from standard input. Please see help for ‘batch/interactive‘ for more details.

On some systems which support a popen function (Unix), the load file can be read from a pipe by starting the file name with a ’<’.

Examples:

      load 'work.gnu'
      load "func.dat"
      load "< loadfile_generator.sh"

The ‘load‘ command is performed implicitly on any file names given as arguments to ‘gnuplot‘. These are loaded in the order specified, and then ‘gnuplot‘ exits.

3.16 lower

See raise.

3.17 pause

The ‘pause‘ command displays any text associated with the command and then waits a specified amount of time or until the carriage return is pressed. ‘pause‘ is especially useful in conjunction with ‘load‘ files.

Syntax:

      pause <time> {"<string>"}
      pause mouse {<endcondition>}{, <endcondition>} {"<string>"}
      pause mouse close

<time> may be any constant or floating-point expression. ‘pause -1‘ will wait until a carriage return is hit, zero (0) won’t pause at all, and a positive number will wait the specified number of seconds.

If the current terminal supports ‘mousing‘, then ‘pause mouse‘ will terminate on either a mouse click or on ctrl-C. For all other terminals, or if mousing is not active, ‘pause mouse‘ is equivalent to ‘pause -1‘.

If one or more end conditions are given after ‘pause mouse‘, then any one of the conditions will terminate the pause. The possible end conditions are ‘keypress‘, ‘button1‘, ‘button2‘, ‘button3‘, ‘close‘, and ‘any‘. If the pause terminates on a keypress, then the ascii value of the key pressed is returned in MOUSE_KEY. The character itself is returned as a one character string in MOUSE_CHAR. Hotkeys (bind command) are disabled if keypress is one of the end conditions. Zooming is disabled if button3 is one of the end conditions.

In all cases the coordinates of the mouse are returned in variables MOUSE_X, MOUSE_Y, MOUSE_X2, MOUSE_Y2. See variables.

Note: Since ‘pause‘ communicates with the operating system rather than the graphics, it may behave differently with different device drivers (depending upon how text and graphics are mixed).

Examples:

      pause -1    # Wait until a carriage return is hit
      pause 3     # Wait three seconds
      pause -1  "Hit return to continue"
      pause 10  "Isn't this pretty?  It's a cubic spline."
      pause mouse "Click any mouse button on selected data point"
      pause mouse keypress "Type a letter from A-F in the active window"
      pause mouse button1,keypress
      pause mouse any "Any key or button will terminate"

The variant "pause mouse key" will resume after any keypress in the active plot window. If you want to wait for a particular key to be pressed, you can use a loop such as:

      print "I will resume after you hit the Tab key in the plot window"
      plot <something>
      pause mouse key
      while (MOUSE_KEY != 9) {
          pause mouse key
      }

• pause mouse close

     plot <...whatever...>
     bind all "alt-End" "exit gnuplot"
     pause mouse close

3.18 plot

‘plot‘ is the primary command for drawing plots with ‘gnuplot‘. It offers many different graphical representations for functions and data. ‘plot‘ is used to draw 2D functions and data. ‘splot‘ draws 2D projections of 3D surfaces and data.

Syntax:

      plot {<ranges>} <plot-element> {, <plot-element>, <plot-element>}

Each plot element consists of a definition, a function, or a data source together with optional properties or modifiers:

      plot-element:
           {<iteration>}
           <definition> | {sampling-range} <function> | <data source>
                        | keyentry
           {axes <axes>} {<title-spec>}
           {with <style>}

The graphical representation of each plot element is determined by the keyword with, e.g. ‘with lines‘ or boxplot. See ‘plotting styles‘.

The data to be plotted is either generated by a function (two functions if in parametric mode), read from a data file, or read from a named data block that was defined previously. Multiple datafiles, data blocks, and/or functions may be plotted in a single plot command separated by commas. See ‘data‘, ‘inline data‘, functions.

A plot-element that contains the definition of a function or variable does not create any visible output, see third example below.

Examples:

      plot sin(x)
      plot sin(x), cos(x)
      plot f(x) = sin(x*a), a = .2, f(x), a = .4, f(x)
      plot "datafile.1" with lines, "datafile.2" with points
      plot [t=1:10] [-pi:pi*2] tan(t), \
           "data.1" using (tan($2)):($3/$4) smooth csplines \
                    axes x1y2 notitle with lines 5
      plot for [datafile in "spinach.dat broccoli.dat"] datafile

See also ‘show plot‘.

• axes
• binary
• data
• errorbars
• errorlines
• functions
• parametric
• ranges
• sampling
• for loops in plot command
• title
• with

      plot '<file_name>' {binary <binary list>} ...
      splot '<file_name>' {binary <binary list>} ...

      plot '<file_name>' binary skip=1024 ...

      plot '<file_name> binary record=356:356:356 skip=512:256:256 ...

              little:  least significant to greatest significance
                 big:  greatest significance to least significance
             default:  assume file endianess is the same as compiler
         swap (swab):  Interchange the significance.  (If things
                       don't look right, try this.)

  http://www.edfplus.info/specs

      plot 'file.png' binary filetype=png

      set datafile binary filetype=auto

     plot 'imagefile' binary filetype=auto flipx rotate=90deg with rgbimage

      plot '<file_name>' {binary <binary list>}
                         {{nonuniform} matrix}
                         {index <index list> | index "<name>"}
                         {every <every list>}
                         {skip <number-of-lines>}
                         {using <using list>}
                         {smooth <option>}
                         {bins <options>}
                         {volatile} {noautoscale}

      1.0 "second column" 3.0

      reset; plot '-', '-' axes x2y1
      1 1
      19 19
      e
      1 1
      19 19
      e

     plot 'DATA' using <XCOL> {:<YCOL>} bins{=<NBINS>}
          {binrange [<LOW>:<HIGH>]} {binwidth=<width>}
          {binvalue={sum|avg}

     BINWIDTH = (HIGH - LOW) / (NBINS-1)
     xmin = LOW - BINWIDTH/2
     xmax = HIGH + BINWIDTH/2
     first bin holds points with (xmin <= x < xmin + BINWIDTH)
     last bin holds points with (xmax-BINWIDTH <= x < xman)
     each point is assigned to bin i = floor(NBINS * (x-xmin)/(xmax-xmin))

     plot 'DATA" using N bins=20
     set samples 20
     plot 'DATA' using (column(N)):(1)

     set datafile separator {whitespace | tab | comma | "chars"}

     set datafile separator ";"

      plot 'file' every {<point_incr>}
                          {:{<block_incr>}
                            {:{<start_point>}
                              {:{<start_block>}
                                {:{<end_point>}
                                  {:<end_block>}}}}}

      every :::3::3    # selects just the fourth block ('0' is first)
      every :::::9     # selects the first 10 blocks
      every 2:2        # selects every other point in every other block
      every ::5::15    # selects points 5 through 15 in each block

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

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

      # Selects two float values (second one implicit) with a float value
      # discarded between them for an indefinite length of 1D data.
      plot '<file_name>' binary format="%float%*float" using 1:2 with lines

      # The data file header contains all details necessary for creating
      # coordinates from an EDF file.
      plot '<file_name>' binary filetype=edf with image
      plot '<file_name>.edf' binary filetype=auto with image

      # Selects three unsigned characters for components of a raw RGB image
      # and flips the y-dimension so that typical image orientation (start
      # at top left corner) translates to the Cartesian plane.  Pixel
      # spacing is given and there are two images in the file.  One of them
      # is translated via origin.
      plot '<file_name>' binary array=(512,1024):(1024,512) format='%uchar' \
           dx=2:1 dy=1:2 origin=(0,0):(1024,1024) flipy u 1:2:3 w rgbimage

      # Four separate records in which the coordinates are part of the
      # data file.  The file was created with a endianess different from
      # the system on which gnuplot is running.
      splot '<file_name>' binary record=30:30:29:26 endian=swap u 1:2:3

      # Same input file, but this time we skip the 1st and 3rd records
      splot '<file_name>' binary record=30:26 skip=360:348 endian=swap u 1:2:3

      plot 'file' index { <m>{:<n>{:<p>}} | "<name>" }

      plot 'file' index 4:5

      plot 'file' using 1:(column(-2)==4 ? $2 : NaN)        # very awkward
      plot 'file' using 1:2:(column(-2)) linecolor variable # very useful!

      plot 'file' index 'Population'

      smooth {unique | frequency | fnormal | cumulative | cnormal | bins
                     | kdensity {bandwidth} {period}
                     | csplines | acsplines | mcsplines | bezier | sbezier
                     | unwrap | zsort}

      plot 'data-file' using 1:2:(1.0) smooth acsplines

      sw(x,S)=1/(x*x*S)
      plot 'data_file' using 1:2:(sw($3,100)) smooth acsplines

     binwidth = <something>  # set width of x values in each bin
     bin(val) = binwidth * floor(val/binwidth)
     plot "datafile" using (bin(column(1))):(1.0) smooth frequency
     plot "datafile" using (bin(column(1))) smooth frequency  # same result

     default_bandwidth = sigma * (4/3N) ** (0.2)

     plot $DATA smooth kdensity bandwidth <value> with boxes

     plot $ANGULAR_DAT smooth kdensity period 2*pi with lines

     plot FOO using x:y:z:color smooth zsort with points lc palette

      plot 'filename' using 1:2, '' using 1:3

      plot '+' using ($1):(sin($1)):(sin($1)**2) with filledcurves

      plot sample [beta=0:2*pi] '+' using (sin(beta)):(cos(beta)) with lines

      plot $MYDATA, [t=-3:25:1] '+' using (t):(f(t))

      splot '++' using 1:2:(sin($1)*sin($2)) with pm3d
      plot '++' using 1:2:(sin($1)*sin($2)) with image

      plot 'a/very/long/filename' using 1:2, '' using 1:3, '' using 1:4

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

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

      $ gnuplot -p -e "plot '<&3', '<&4'" 3<data-3 4<data-4
      $ ./gnuplot 5< <(myprogram -with -options)
      gnuplot> plot '<&5'

      plot 'file' using <entry> {:<entry> {:<entry> ...}} {'format'}

      Height    Weight    Age
      val1      val1      val1
      ...       ...       ...

      plot 'datafile' using 3:1, '' using 3:2
      plot 'datafile' using (column("Age")):(column(1)), \
                   '' using (column("Age")):(column(2))
      plot 'datafile' using "Age":"Height", '' using "Age":"Weight"

      plot 'file' using 1:($2+$3) '%lf,%lf,%lf'

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

      %*lf        ignore a number
      %lf         read a double-precision number (x by default)
      %*20[^\n]   ignore 20 non-newline characters
      %lf         read a double-precision number (y by default)

      plot 'file' using 1:($3>10 ? $2 : 1/0)

      plot 'file' using 1:2

      column(0)   The sequential order of each point within a data set.
                  The counter starts at 0, increments on each non-blank,
                  non-comment line, and is reset by two sequential blank
                  records.  The shorthand form $0 is available.
      column(-1)  This counter starts at 0, increments on a single blank line,
                  and is reset by two sequential blank lines.
                  This corresponds to the data line in array or grid data.
                  It can also be used to distinguish separate line segments
                  or polygons within a data set.
      column(-2)  Starts at 0 and increments on two sequential blank lines.
                  This is the index number of the current data set within a
                  file that contains multiple data sets.  See index.
      column($#)  The special symbol $# evaluates to the total number of
                  columns available, so column($#) refers to the last
                  (rightmost) field in the current input line.
                  column($# - 1) would refer to the last-but-one column, etc.

      plot 'datafile' using <xcol>:<ycol>:xticlabels(3) with <plotstyle>

      splot "data" using 2:4:6:xtic(1):ytic(3):ztic(6)

      plot "data" using 1:2:xtic( $3 > 10. ? "A" : "B" )

      (x, y, ydelta),
      (x, y, ylow, yhigh),
      (x, y, xdelta),
      (x, y, xlow, xhigh),
      (x, y, xdelta, ydelta), or
      (x, y, xlow, xhigh, ylow, yhigh).

      plot 'file' with errorbars
      plot 'file' using 1:2:(sqrt($1)) with xerrorbars
      plot 'file' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars

      (x, y, ydelta),
      (x, y, ylow, yhigh),
      (x, y, xdelta),
      (x, y, xlow, xhigh),
      (x, y, xdelta, ydelta), or
      (x, y, xlow, xhigh, ylow, yhigh).

      plot 'file' with errorlines
      plot 'file' using 1:2:(sqrt($1)) with xerrorlines
      plot 'file' using 1:2:($1-$3):($1+$3):4:5 with xyerrorlines

      approx(ang) = ang - ang**3 / (3*2)
      plot sin(x) title "sin(x)", approx(x) title "approximation"

      plot sin(t),t**2
      splot cos(u)*cos(v),cos(u)*sin(v),sin(u)

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

      [{<dummy-var>=}{{<min>}:{<max>}}]
      [{{<min>}:{<max>}}]

      plot [<xrange>][<yrange>][<x2range>][<y2range>] ...

      plot [<trange>][<xrange>][<yrange>][<x2range>][<y2range>] ...

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

      plot cos(x)

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

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

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

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

      plot [:200] [-pi:]  $mydata using 1:2

      set timefmt "%d/%m/%y %H:%M"
      plot ["1/6/93 12:00":"5/6/93 12:00"] 'timedata.dat'