C Copyright (C) 1986 - 1993, 1998, 1999, 2000, 2001, 2004 Thomas Williams, Colin Kelley et al.

C

1 Gnuplot

?gnuplot

^<h2 align="center"> An Interactive Plotting Program </h2>

^<p align="center"> Thomas Williams & Colin Kelley</p>

^<p align="center"> Version 6 organized by Ethan A Merritt</p>

^<p align="center">Major contributors (alphabetic order):<br>

^<br>

^ Hans-Bernhard Broeker, John Campbell,<br>

^ Robert Cunningham, David Denholm,<br>

^ Gershon Elber, Roger Fearick,<br>

^ Carsten Grammes, Lucas Hart, Lars Hecking,<br>

^ Péter Juhász, Thomas Koenig, David Kotz,<br>

^ Ed Kubaitis, Russell Lang, Timothée Lecomte,<br>

^ Alexander Lehmann, Alexander Mai, Bastian Märkisch,<br>

^ Tatsuro Matsuoka, Ethan A Merritt, Petr Mikulík,<br>

^ Hiroki Motoyoshi, Carsten Steger, Shigeharu Takeno,<br>

^ Tom Tkacik, Jos Van der Woude,<br>

^ James R. Van Zandt, Alex Woo, Johannes Zellner<br>

^</p>

^<p align="center"> Copyright (C) 1986 - 1993, 1998 - 2004 Thomas Williams, Colin Kelley<br>

^ Copyright (C) 2004 - 2023 various authors</p>

^<p align="center"> Mailing list for comments: <tt>[email protected]</tt><br>

^ Gnuplot <a href="http://gnuplot.info"> home page </a><br>

^ Issue trackers: &nbsp;

^<a href="https://sourceforge.net/p/gnuplot/bugs"> bugs </a> &nbsp;&nbsp;

^<a href="https://sourceforge.net/p/gnuplot/feature-requests"> feature requests </a>

^<p align="center"> This manual was originally prepared by Dick Crawford</p>

^<!-- end of titlepage -->

2 Copyright

?copyright

?license

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

Copyright (C) 2004-2023 various authors

Permission to use, copy, and distribute this software and its

documentation for any purpose with or without fee is hereby granted,

provided that the above copyright notice appear in all copies and

that both that copyright notice and this permission notice appear

in supporting documentation.

Permission to modify the software is granted, but not the right to

distribute the complete modified source code. Modifications are to

be distributed as patches to the released version. Permission to

distribute binaries produced by compiling modified sources is granted,

provided you

1. distribute the corresponding source modifications from the

released version in the form of a patch file along with the binaries,

2. add special version identification to distinguish your version

in addition to the base release version number,

3. provide your name and address as the primary contact for the

support of your modified version, and

4. retain our contact information in regard to use of the base software.

Permission to distribute the released version of the source code along

with corresponding source modifications in the form of a patch file is

granted with same provisions 2 through 4 for binary distributions.

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

to the extent permitted by applicable law.

AUTHORS

Original Software:

Thomas Williams, Colin Kelley.

Gnuplot 2.0 additions:

Russell Lang, Dave Kotz, John Campbell.

Gnuplot 3.0 additions:

Gershon Elber and many others.

Gnuplot 4.0 and subsequent releases:

See list of contributors at head of this document.

2 Introduction

?introduction

?

`Gnuplot` is a portable command-line driven graphing utility for Linux, OS/2,

MS Windows, macOS, and many other platforms. The source code is copyrighted

but freely distributed (i.e., you don't have to pay for it). It was originally

created to allow scientists and students to visualize mathematical functions

and data interactively, but has grown to support many non-interactive uses

such as web scripting. It is also used as a plotting engine by third-party

applications like Octave. Gnuplot has been supported and under active

development since 1986.

Gnuplot can generate many types of plot in 2D and 3D. It can draw using lines,

points, boxes, contours, vector fields, images, surfaces, and associated text.

It also supports specialized graphs such as heat maps, spider plots, polar

projection, histograms, boxplots, bee swarm plots, and nonlinear coordinates.

Gnuplot supports many different types of output: interactive screen terminals

(with mouse and hotkey input), direct output to pen plotters or modern

printers, and output to many file formats (eps, emf, fig, jpeg, LaTeX, pdf, png,

postscript, ...). Gnuplot is easily extensible to include new output modes.

A recent example is support for webp animation. Mouseable plots embedded in

web pages can be generated using the svg or HTML5 canvas terminal drivers.

The command language of `gnuplot` is case sensitive, i.e. commands and

function names written in lowercase are not the same as those written in

capitals. All command names may be abbreviated as long as the abbreviation is

not ambiguous. Any number of commands may appear on a line, separated by

semicolons (;). Strings may be set off by either single or double quotes,

although there are some subtle differences. See `syntax` and `quotes` for

more details. Example:

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

Commands may extend over several input lines by ending each line but the last

with a backslash (\). The backslash must be the _last_ character on each

line. The effect is as if the backslash and newline were not there. That

is, no white space is implied, nor is a comment terminated. Therefore,

commenting out a continued line comments out the entire command

(see `comments`). But note that if an error occurs somewhere on a multi-line

command, the parser may not be able to locate precisely where the error is

and in that case will not necessarily point to the correct line.

In this document, curly braces ({}) denote optional arguments and a vertical

bar (|) separates mutually exclusive choices. `Gnuplot` keywords or `help`

topics are indicated by backquotes or `boldface` (where available). Angle

brackets (<>) are used to mark replaceable tokens. In many cases, a default

value of the token will be taken for optional arguments if the token is

omitted, but these cases are not always denoted with braces around the angle

brackets.

For built-in help on any topic, type `help` followed by the name of the topic

or `help ?` to get a menu of available topics.

A large set of demo plots is available on the web page

^ <a href="http://www.gnuplot.info/demo/">

http://www.gnuplot.info/demo/

^ </a>

When run from command line, gnuplot is invoked using the syntax

gnuplot {OPTIONS} file1 file2 ...

where file1, file2, etc. are input files as in the `load` command.

Options interpreted by gnuplot may come anywhere on the line. Files are

executed in the order specified, as are commands supplied by the -e option,

for example

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

The special filename "-" is used to force reading from stdin. `Gnuplot` exits

after the last file is processed. If no load files are named, `Gnuplot` takes

interactive input from stdin. See help `batch/interactive` for more details.

See `command-line-options` for more details, or type

gnuplot --help

In sessions with an interactive plot window you can hit 'h' anywhere on the

plot for help about `hotkeys` and `mousing` features.

2 Seeking-assistance / Bugs

?help-desk

?faq

?FAQ

?bugs

?seeking-assistance

The canonical gnuplot home page can be found at

^ <a href="http://www.gnuplot.info">

http://www.gnuplot.info

^ </a>

Before seeking help, please check file FAQ.pdf or the above website for a

^ <a href="http://www.gnuplot.info/faq/">

FAQ (Frequently Asked Questions) list.

^ </a>

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

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

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

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

Please check previous reports to see if the bug you want to report has

already been fixed in a newer version.

When reporting a bug or posting a question, please include full details

of the gnuplot version, the terminal type, and the operating system.

A short self-contained script demonstrating the problem is very helpful.

Instructions for subscribing to gnuplot mailing lists may be

found via the gnuplot development website

^ <a href="http://sourceforge.net/projects/gnuplot">

http://sourceforge.net/projects/gnuplot

^ </a>

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:

[email protected]

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

[email protected]

2 New features in version 6

?new version_6

?new

?version

Version 6 is the latest major release in a history of gnuplot development

dating back to 1986. It follows major version 5 (2015) and subsequent

minor version releases 5.2 (2017) and 5.4 (2020). Development continues

in a separate unreleased branch in the project git repository on SourceForge.

Some features described in this document are present only if chosen and

configured at the time gnuplot is compiled from source. To determine what

configuration options were used to build the particular copy of gnuplot you

are running, type `show version long`.

3 Function blocks and scoped variables

?new function blocks

This version of gnuplot introduces a mechanism for invoking a block of

standard gnuplot commands as a callable function. A function block can

accept from 0 to 9 parameters and returns a value. Function blocks can be

used to calculate and assign a new value to a variable, to combine with other

functions and operators, or to perform a repetitive task preparing data.

There are three components to this mechanism.

See `local`, `scope`, `function blocks`, `return`.

#start

#b The `local` qualifier allows optional declaration of a variable or array

## whose scope is limited to the duration of execution of the program unit in

## which it is found. These units currently include execution of a

## `load` or `call` statement, function block evaluation, and the code block

## in curly brackets following an `if`, `else`, `do for`, or `while` statement.

## If the name of a local variable duplicates the name of a global variable,

## the global variable is shadowed until exit from the local scope.

#b The `function` command declares a named function block (effectively an

## array of strings) containing gnuplot commands. When the function block

## is invoked, commands are executed successively until the end of the block

## or until a `return` command is encountered.

#b The `return <expression>` command terminates execution of a function block.

## The result of evaluating <expression> is returned as the value of the

## function. Anywhere outside a function block `return` acts like `exit`.

#end

Please see `function_block.dem` for an example of using this mechanism

to define and plot a non-trivial function that is too complicated for a

simple one-line definition `f(x) = ...`.

3 Special and complex-valued functions

?new math

Gnuplot 6 provides an expanded set of complex-valued functions and updated

versions of some functions that were present in earlier versions.

#start

#b New: Riemann zeta function with complex domain and range. See `zeta`.

#b Updated lower incomplete gamma function with improved domain and precision.

## Complex arguments accepted.

## See `igamma`.

#b New upper incomplete gamma function (real arguments only).

## See `uigamma`.

#b Updated incomplete beta function with improved domain and precision.

## See `ibeta`.

#b New function for the inverse incomplete gamma function.

## See `invigamma`.

#b New function for the inverse incomplete beta function.

## See `invibeta`.

#b New complex function LambertW(z,k) returns the kth branch of multivalued

## function W_k(z).

^<br>

## Note that the older function lambertw(x) = real(LambertW( real(z), 0 )).

## See `LambertW`.

#b New complex function lnGamma(z).

## Note that existing function lgamma(x) = real(lnGamma(real(z)).

## See `lnGamma`.

#b Complex function conj(z) returns the complex conjugate of z.

#b Synchrotron function F(x), see `SynchrotronF`.

#b acosh(z) domain extended to cover negative real axis.

#b asin(z) asinh(z) improved precision for complex arguments.

#b Predefined variable I = sqrt(-1) = {0,1} for convenience.

^<br>

## This is useful because gnuplot does not accept {a,b} as a valid complex

## constant but does accept (a + b*I) as a valid complex expression.

#end

Additional special functions are supported if a suitable external

library is found at build time. See `special_functions`.

#start

#b Complex Bessel functions Iν(z), Jν(z), Kν(z), Yν(z) of order ν (real)

## with complex argument z. See `BesselK`.

#b Complex Hankel functions H1ν(z), H2ν(z) of order ν with complex z.

## See `BesselH1`.

#b Complex Airy functions Ai(z), Bi(z).

#b Complex exponential integral of order n. See `expint`.

#b Fresnel integrals C(x) and S(x). See `FresnelC`.

#b Function `VP_fwhm(sigma,gamma)` returns the full width at half maximum

## of the Voigt profile. See `VP`, `VP_fwhm`.

#end

3 New plot styles

?new styles

#start

#b The plot style `with surface` works in 2D polar coordinates to produce

## a solid-fill gridded representation of the plane, colored by weighted

## contributions from an arbitrary set of input points. This is analogous to

## the use of `dgrid3d` and style `with pm3d` to produce a 3D gridded surface.

## See `set polar grid` and `polar heatmap`.

#b New 2D plot style `with sectors` is an alternative to generating a full

## polar gridded surface. For each input data point it generates a single

## annular wedge in a conceptual polar grid. Unlike polar mode `with surface`

## it can be used in either a polar or cartesian coordinate graph.

#b New 2D plot style `with hsteps` allows construction of step-like plots with

## a variety of representations in addition to those offered by existing styles

## `steps`, `histeps`, `fsteps`, and `fillsteps`. See `hsteps`.

#b Plot style `with lines` now has a filter option `sharpen`. This filter

## detects spikes in a function plot that appear truncated in the output

## because the peak lies between two x-coordinates at which the function has

## been sampled. It adds a new sample point at the location of each such peak.

## See `filters`.

#b Although it is not strictly speaking a new plot style, the combination

## of the concave hull filter with along-path smoothing of filled areas

## allows creation of 'blobby region' plots showing, for example,

## the extents of overlapping data clusters. See `concavehull`.

#b 3D plot style `with pm3d` accepts an optional modifier `zclip [zmin:zmax]`

## that selects only a slice of the full surface. Successive plots with

## incremental changes to the clipping limits can be used to animate a

## cross-sectional cutaway view in 3D or to create a filled area contour map.

## This is automated by a new plot style `with contourfill`, that is

## particularly useful in 2D projection. See `set contourfill`.

#end

D polargrid 4

DB

D windrose 1

D sectors 4

DB

D sharpen 1

D iris 2

DB

D contourfill 4

DB

D logic_timing 1

D rank_sequence 1

3 Hulls, masks, and smoothing

?new hulls

#start

#b A cluster of 2D points can be replaced by its bounding polygon using the

## new filter `convexhull`. A path-smoothed bounding curve can be plotted

## as a filled area using "convexhull smooth path with filledcurves".

## See `convexhull`.

#b An alternative experimental filter `concavehull` generates a bounding

## polygon that is not necessarily convex; instead it forms a χ-shape

## determined by a characteristic length parameter that controls the degree

## of concavity. This essentially draws a blob around the data points.

## See `concavehull`.

#b A convex hull or other polygon can be used as a mask to display only

## selected portions of a pm3d surface or an image plot.

## See new plot style `with mask` (defines a mask) and keyword `mask`

## (applies the mask to a subsequent plot component).

#b curve smoothing using along-path cubic splines suitable for closed curves

## or for 2D curves that are not monotonic on x. See `smooth path`.

## This allows smoothing of hulls and masks.

#b cubic spline smoothing of 3D lines. See `splot smooth csplines`

#b Smoothing options apply to plotting `with filledcurves` {above|below|between}.

#b New keyword `period` for smoothing periodic data. See `smooth kdensity`.

#end

D convex_hull 2

D mask_pm3d 3

D smooth_path 2

3 Named palettes

?new colormaps

#start

#b The current palette can be saved to a named colormap for future use.

## See `set colormap`.

#b pm3d and image plots can specify a previously saved palette by name.

## This permits the use of multiple palettes in a single plot command.

## See `colorspec palette`.

#b Named palette colormaps can be manipulated as arrays of 32-bit ARGB

## color values. This permits addition of alpha-channel values or other

## modifications not easily specified in a `set palette` command.

#b There is a new predefined color scheme `set palette viridis`.

#b Palettes read from a file or datablock (`set palette file`) may be specified

## either using fractional color components or 24-bit packed RGB values.

#end

D named_palettes 4

D viridis 1

3 New data formats

?new data_formats

#start

#b The `sparse matrix=(cols,rows)` option to `plot` and `splot` generates

## a uniform pixel grid into which individual pixel values may be loaded in

## any order. This is useful for plotting heat maps from incomplete data.

## See `sparse`.

#b During input of non-uniform matrix data, column(0) now returns the linear

## ordering of matrix elements. I.e. for element A[i,j] in an MxN matrix A,

## column(0)/M gives the row index i, and column(0)%M gives the column index j.

#end

3 New built-in functions and array operations

?new built-in functions

#start

#b `palette(z)` returns the current RGB palette color mapping z into cbrange.

#b `rgbcolor("name")` returns the 32bit ARGB value for a named color.

#b `index( Array, element )` returns the first index `i` for which

## Array[i] is equal to element. See `arrays`.

#b User-defined functions allow an array as a parameter.

^<br>

## Example: dot(A,B) = sum [i=1:|A|] A[i]*B[i]

#b Array slices are generated by appending a range to the array name.

## Array[n] is single element. Array[n:n+5] is a six element slice of

## the original array. See `arrays`, `slice`.

#b `split("string", "separator")` unpacks the fields in a string into

## an array of strings. See `split`.

#b `join(array, "separator")` is the complement to `split`. It concatenates

## the elements of a string array into a single string with field separators.

## See `join`.

#b `stats <non-existent file>` yields a testable value. See `stats test`.

#b `stats $vgrid` finds min/max/mean/stddev of voxels in grid

#end

3 Program control flow

?control flow

#start

#b New syntax `if ... else if ... else ...`

#b XDG base directory conventions for configuration preferences are supported.

## The program reads initial commands from $XDG_CONFIG_HOME/gnuplot/gnuplotrc.

## Session command history is saved to $XDG_STATE_HOME/gnuplot_history.

## If these files are not found, $HOME/.gnuplot and $HOME/.gnuplot_history

## are used as in previous gnuplot versions.

#b `unset warnings` suppresses output of warning messages to the console.

#b Exception handling for the "fit" command. Control always returns to the

## next line of input, even in the case of fit errors. On return, FIT_ERROR is

## non-zero if an error occurred. This allows scripted recovery from a bad fit.

## See `fit error_recovery`.

#end

3 New terminals and terminal options

?new terminals

#start

#b New terminals `kittygd` and `kittycairo` provide in-window graphics for

## terminal emulators that support the kitty protocol. Kitty is an alternative

## to sixel graphics that offers full 24-bit RGB color. See `kittycairo`.

#b New terminal `block` for text-mode pseudo-graphics uses Unicode

## block or Braille characters to offer improved resolution compared

## to the `dumb` or `caca` terminals.

#b New terminal `webp` generates a single frame or an animation sequence

## using webp encoding. Frames are generated using pngcairo, then

## encoded through the WebPAnimEncoder API exported by libwebp and libwebpmux.

#b Terminals that use the same window for text entry and graphical display,

## including `dumb`, `sixel`, `kitty`, and `block`, now respond to keyboard

## input during a `pause mouse` command. While paused, they interpret keystrokes

## in the same way that a mousing terminal would. See `pseudo-mousing`.

## For example the left/right/up/down arrow keys change the view angle of 3D

## plots and perform incremental pan/zoom steps for 2D plots.

#end

3 Watchpoints

?new watchpoints

Watchpoints are target values associated with individual plots in a graph.

As that plot is drawn, each component line segment is monitored to see if

its endpoints bracket the target value of a watchpoint coordinate (x, y, or z)

or function f(x,y). If a match is found, the [x,y] coordinates of the

match point are saved for later use. See `watchpoints`.

Possible uses include

#start

#b Find the intersection points of two curves

#b Find zeros of a function

#b Find and notate where a dependent variable (y or z) or function f(x,y)

## crosses a threshold value

#b Use the mouse to track values along multiple plots simultaneously

#end

3 Week-date time support

?new week-date time

The Covid-19 pandemic of 2020/2021 generated increased interest in plotting

epidemiological data, which is often tabulated using a "week date" reporting

convention. Deficiencies with gnuplot support for this convention were

remedied and the support for week-date time was extended.

#start

#b Time specifier format %W has been brought into accord with the

## ISO 8601 week date standard.

#b Time specifier format %U has been brought into accord with the

## CDC/MMWR week date standard.

#b New function `tm_week(time, std)` returns ISO or CDC standard week of year.

#b New function `weekdate_iso(year, week, day)` converts ISO standard week date

## to calendar time.

#b New function `weekdate_cdc(year, week, day)` converts CDC standard week date

## to calendar time.

#end

D epi_data 1

3 Other new features

?new features

#start

#b `Time units for setting major and minor tics.`

## Both major and minor tics along a time axis now accept tic intervals given

## in units of minutes/hours/days/weeks/months/years.

## See `set xtics`, `set mxtics time`.

#b The character sequence $# in a `using` specifier evaluates to the total

## number of columns available in the current line of data. For example

## "plot FOO using 0:(column($# - 1))" plots the last-but-one field of each row.

#b keyword `binvalue=avg` plots the average, rather than the sum, of binned data.

#b `set colorbox bottom` places a horizontal color box underneath the plot

## rather than a vertical box on the right.

#b Improved rendering of intersecting pm3d surfaces - overlapping surface tiles

## are split into two pieces along the line of intersection so that tiles

## from one surface do not incorrectly protrude though the other surface.

#b User-controlled spotlight added to the pm3d lighting model.

## See `set pm3d spotlight`.

#b New options to force total key width and number of columns. See `key layout`.

#b `set pm3d border retrace` draws a border around each pm3d quadrangle in the

## same color as the filled area. In principle this should have no visible

## effect, but it prevents some display modes like glitchy pdf or postscript

## viewers from introducing aliasing artifacts.

#b `set isotropic` adjusts the axis scaling in both 2D and 3D plots such that

## the x, y, and z axes all have the same scale.

#b Change: Text rotation angle is not limited to integral degrees.

#b Special (non-numerical) linetypes `lt nodraw`, `lt black`, `lt bgnd`

## See `special_linetypes`.

#b Data-driven color assignments in histogram plots. See `histograms colors`.

#b The position of the key box can be manually tweaked by specifying an

## offset to be added to whatever position the program would otherwise use.

## See `set key offset`.

#end

3 Brief summary of features introduced in version 5

?new version_5

?version_5

4 Features introduced in 5.4

?new version_5 version_5.4

?version_5 version_5.4

#start

#b Expressions and functions use 64-bit integer arithmetic. See `integer`

#b 2D plot styles `polygons`, `spiderplot`, `arrows`

#b 3D plot styles `boxes`, `circles`, `polygons`, `isosurface` and

## other representations of gridded voxel data

#b Data preprocessing filter `zsort`

#b Construction of customized keys using `keyentry`

#b New LaTeX terminal pict2e supersedes older terminals `latex`, `emtex`, `eepic`,

## and `tpic`. The older terminals are no longer built by default

#b `set pixmap` imports a png/jpeg/gif image as a pixmap that can be scaled and

## positioned anywhere in a plot or on the page

#b Enhanced text mode accepts \U+xxxx (xxxx is a 4 or 5 character hexadecimal)

## as representing a Unicode code point that is converted to the corresponding

## UTF-8 byte sequence on output

#b Revised syntax for `with parallelaxes` allows convenient iteration inside the

## plot command, similar to plot styles `histogram` and `spiderplot`

#end

4 Features introduced in 5.2

?new version_5 version_5.2

?version_5 version_5.2

#start

#b Nonlinear coordinate systems (see `set nonlinear`)

#b Automated binning of data (see `bins`)

#b 2D beeswarm plots. See `set jitter`

#b 3D plot style `zerrorfill`

#b 3D lighting model provides shading and specular highlighted (see `lighting`).

#b Array data type, associated commands and operators. See `arrays`.

#b New terminals `sixelgd`, `domterm`

#b New format descriptors tH tM tS handle relative times (interval lengths).

## See `time_specifiers`.

#end

4 Features introduced in 5.0

?new version_5 version_5.0

?version_5 version_5.0

#start

#b Terminal independent dash types.

#b The default sequence of colors used for successive elements in a plot is

## more easily distinguished by users with color-vision defects.

#b New plot types `with parallelaxes`, `with table`.

#b Hypertext labels activated by a mouse-over event.

#b Explicit sampling ranges in 2D and 3D function plots and pseudofiles

## '+' and '++'.

#b Plugin support through new command `import` that attaches a user-defined

## function name to a function provided by an external shared object.

#end

2 Differences between versions 5 and 6

Some changes introduced in version 5 could cause certain scripts written

for earlier versions of gnuplot to fail or to behave differently.

There are very few such changes in version 6.

3 Deprecated syntax

?deprecated syntax

Deprecated in version 5.4, removed in 6.0

# 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

}

Deprecated in version 5.4, removed in 6.0

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

Current equivalent

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

Deprecated in version 5.0, removed in 6.0

set style increment user

Current equivalent

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

Deprecated in version 5.0, removed in 6.0

show palette fit2rgbformulae

2 Demos and Online Examples

?demos

?online examples

?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

^ <a href="http://gnuplot.info/demos/">

http://gnuplot.info/demos

^ </a>

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.

2 Batch/Interactive Operation

?batch/interactive

`Gnuplot` may be executed in either batch or interactive modes, and the two

may even be mixed together.

Command-line arguments are assumed to be either program options or names

of files containing `gnuplot` commands.

Each file or command string will be executed in the order specified.

The special filename "-" is indicates that commands are to be read from stdin.

`Gnuplot` exits after the last file is processed. If no load files and no

command strings are specified, `gnuplot` accepts interactive input from stdin.

3 command line options

?command-line-options

?batch/interactive command-line-options

Gnuplot accepts the following options on the command line

-V, --version

-h, --help

-p, --persist

-d, --default-settings

-s, --slow

-e "command1; command2; ..."

-c scriptfile ARG1 ARG2 ...

-p tells the program not to close any remaining interactive plot windows

when the program exits.

-d tells the program not to execute any private or system initialization

(see `initialization`).

-s tells the program to wait for slow font initialization on startup.

Otherwise it prints an error and continues with bad font metrics.

-e "command" tells gnuplot to execute that single command before continuing.

-c is equivalent to -e "call scriptfile ARG1 ARG2 ...". See `call`.

3 Examples

?batch/interactive examples

To launch an interactive session:

gnuplot

To execute two command files "input1" and "input2" in batch mode:

gnuplot input1 input2

To launch an interactive session after an initialization file "header" and

followed by another command file "trailer":

gnuplot header - trailer

To give `gnuplot` commands directly in the command line, using the "-persist"

option so that the plot remains on the screen afterwards:

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

To set user-defined variables a and s prior to executing commands from a file:

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

2 Canvas size

?canvas size

?canvas

?set term size

This documentation uses the term "canvas" to mean the full drawing area

available for positioning the plot and associated elements like labels,

titles, key, etc. NB: For information about the HTML5 canvas terminal

see `set term canvas`.

`set term <terminal_type> size <XX>, <YY>` controls the size of the output

file, or "canvas". By default, the plot will fill this canvas.

`set size <XX>, <YY>` scales the plot itself relative to the size of the

canvas. Scale values less than 1 will cause the plot to not fill the entire

canvas. Scale values larger than 1 will cause only a portion of the plot to

fit on the canvas. Please be aware that setting scale values larger than 1

may cause problems.

Example:

set size 0.5, 0.5

set term png size 600, 400

set output "figure.png"

plot "data" with lines

These commands produce an output file "figure.png" that is 600 pixels wide

and 400 pixels tall. The plot will fill the lower left quarter of this canvas.

Note: In early versions of gnuplot some terminal types used `set size`

to control the size of the output canvas. This was deprecated in version 4.

2 Command-line-editing

?line-editing

?editing

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

@start table - first is interactive cleartext form

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

#\begin{tabular}{|cl|} \hline

#\multicolumn{2}{|c|}{Command-line Editing Commands} \\ \hline \hline

#Character & Function \\ \hline

# & \multicolumn{1}{|c|}{Line Editing}\\ \cline{2-2}

#\verb~^B~ & move back a single character.\\

#\verb~^F~ & move forward a single character.\\

#\verb~^A~ & move to the beginning of the line.\\

#\verb~^E~ & move to the end of the line.\\

#\verb~^H~ & delete the previous character.\\

#\verb~DEL~ & delete the current character.\\

#\verb~^D~ & delete current character. EOF if line is empty.\\

#\verb~^K~ & delete from current position to the end of line.\\

#\verb~^L~ & redraw line in case it gets trashed.\\

#\verb~^U~ & delete the entire line. \\

#\verb~^W~ & delete previous word. \\

#\verb~^V~ & inhibits the interpretation of the following key as editing command. \\

#\verb~TAB~ & performs filename-completion. \\ \hline

# & \multicolumn{1}{|c|}{History} \\ \cline{2-2}

#\verb~^P~ & move back through history.\\

#\verb~^N~ & move forward through history.\\

#\verb~^R~ & starts a backward-search.\\

%c l .

%Character@Function

%_

%@Line Editing

%^B@move back a single character.

%^F@move forward a single character.

%^A@move to the beginning of the line.

%^E@move to the end of the line.

%^H@delete the previous character.

%DEL@delete the current character.

%^D@delete current character. EOF if line is empty.

%^K@delete from current position to the end of line.

%^L@redraw line in case it gets trashed.

%^U@delete the entire line.

%^W@delete previous word.

%_

%^V@inhibits the interpretation of the following key as editing command.

%TAB@performs filename-completion.

%_

%@History

%^P@move back through history.

%^N@move forward through history.

%^R@starts a backward-search.

@end table

^<table align="center" border="1" rules="groups" frame="hsides" cellpadding="3">

^<colgroup>

^ <col align="center">

^ <col align="left">

^</colgroup>

^<thead>

^<tr> <th>Character</th> <th>Function</th></tr>

^</thead>

^<tbody>

^<tr> <td></td> <th>Line Editing</th></tr>

^<tr> <td><tt>^B</tt></td> <td>move back a single character.</td></tr>

^<tr> <td><tt>^F</tt></td> <td>move forward a single character.</td></tr>

^<tr> <td><tt>^A</tt></td> <td>move to the beginning of the line.</td></tr>

^<tr> <td><tt>^E</tt></td> <td>move to the end of the line.</td></tr>

^<tr> <td><tt>^H</tt></td> <td>delete the previous character.</td></tr>

^<tr> <td><tt>DEL</tt></td> <td>delete the current character.</td></tr>

^<tr> <td><tt>^D</tt></td> <td>delete current character. EOF if line is empty</td></tr>

^<tr> <td><tt>^K</tt></td> <td>delete from current position to the end of line.</td></tr>

^<tr> <td><tt>^L</tt></td> <td>redraw line in case it gets trashed.</td></tr>

^<tr> <td><tt>^U</tt></td> <td>delete the entire line.</td></tr>

^<tr> <td><tt>^W</tt></td> <td>delete previous word.</td></tr>

^<tr> <td><tt>^V</tt></td> <td>inhibits the interpretation of the following key as editing command.</td></tr>

^<tr> <td><tt>TAB</tt></td> <td>performs filename-completion.</td></tr>

^</tbody>

^<tbody>

^<tr> <th></th> <th>History</th></tr>

^<tr> <td><tt>^P</tt></td> <td>move back through history.</td></tr>

^<tr> <td><tt>^N</tt></td> <td>move forward through history.</td></tr>

^<tr> <td><tt>^R</tt></td> <td>starts a backward-search.</td></tr>

^</tbody>

^</table>

2 Comments

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

2 Coordinates

?coordinates

=axes

The commands `set arrow`, `set key`, `set label` and `set 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 `set xyplane`); `screen`

specifies the screen area (the entire area---not just the portion selected by

`set 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 `set xdata` and `set timefmt`. `Gnuplot` will also accept an integer

expression, which will be interpreted as seconds relative to 1 January 1970.

2 Datastrings

?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

=columnheader

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 `set datafile columnheaders` or

`set key autotitle columnhead`.

See `labels`, `using xticlabels`, `plot title`, `using`, `key autotitle`.

2 Enhanced text mode

?enhanced text

?enhanced

?text_markup

?markup

?bold

?italic

Many terminal types support an enhanced text mode in which additional

formatting information can be embedded in the text string. For example, "x^2"

will write x-squared as we are used to seeing it, with a superscript 2.

This mode is selected by default when you set the terminal, but may be

toggled afterward using "set termoption [no]enhanced", or disabled for

individual strings as in `set label "x_2" noenhanced`.

Note: For output to TeX-based terminals (e.g. cairolatex, pict2e, pslatex,

tikz) all text strings should instead use TeX/LaTeX syntax. See `latex`.

@start table - first is interactive cleartext form

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)

#\begin{tabular}{|clll|} \hline

#\multicolumn{4}{|c|}{Enhanced Text Control Codes} \\ \hline

#Control & Example & Result & Explanation \\ \hline

#\verb~^~ & \verb~a^x~ & $a^x$ & superscript\\

#\verb~_~ & \verb~a_x~ & $a_x$ & subscript\\

#\verb~@~ & \verb~a@^b_{cd}~ & $a^b_{cd}$ &phantom box (occupies no width)\\

#\verb~&~ & \verb~d&{space}b~ & d\verb*+ +b & inserts space of specified length\\

#\verb|~| & \verb|~a{.8-}| & $\tilde{a}$ & overprints '-' on 'a', raised by .8\\

#\verb~ ~ & \verb~ ~ & ~ ~ & times the current fontsize\\

#\verb| | & \verb|{/Times abc}| & {\rm abc} & print abc in font Times at current size\\

#\verb| | & \verb|{/Times*2 abc}| & \Large{\rm abc} & print abc in font Times at twice current size\\

#\verb| | & \verb|{/Times:Italic abc}| & {\it abc} & print abc in font Times with style italic\\

#\verb| | & \verb|{/Arial:Bold=20 abc}| & \Large\textsf{\textbf{abc}} & print abc in boldface Arial font size 20\\

#\verb|\U+| & \verb|\U+221E| & $\infty$ & Unicode point U+221E INFINITY\\

%c c l .

C ugly - doc2ms uses @ for column separator, but here we

C need @ in table, so end and restart the table !

%.TE

%.TS

%center box tab ($) ;

%c c l .

%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

@end table

^<table align="center" border="1" rules="groups" frame="hsides" cellpadding="3">

^<colgroup>

^ <col align="center">

^ <col align="center">

^ <col align="left">

^</colgroup>

^<thead>

^<tr> <th>Control</th> <th>Examples</th> <th>Explanation</th></tr>

^</thead>

^<tbody>

^<tr> <td><tt> ^ </tt></td> <td><tt>a^x</tt></td> <td>superscript</td></tr>

^<tr> <td><tt> _ </tt></td> <td><tt>a_x</tt></td> <td>subscript</td></tr>

^<tr> <td><tt> @ </tt></td> <td><tt> @x</tt> or <tt>a@^b_{cd}</tt></td> <td>phantom box (occupies no width)</td></tr>

^<tr> <td><tt> &amp;</tt></td> <td><tt> &amp;{space}</tt></td> <td>inserts space of specified length</td></tr>

^<tr> <td><tt> ~ </tt></td> <td><tt> ~a{.8-}</tt></td> <td>overprints '-' on 'a', raised by .8<br>times the current fontsize</td></tr>

^</tbody>

^</table>

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}}}