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: {sampling-range} {<iteration>} <definition> | <function> | <data source> {axes <axes>} {<title-spec>} {with <style>}

The graphical representation of each plot element is determined by the keyword with, e.g. with lines or with 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.

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.

There are four possible sets of axes available; the keyword <axes> is used to select the axes for which a particular line should be scaled. x1y1 refers to the axes on the bottom and left; x2y2 to those on the top and right; x1y2 to those on the bottom and right; and x2y1 to those on the top and left. Ranges specified on the plot command apply only to the first set of axes (bottom left).

BINARY DATA FILES:

It is necessary to provide the keyword binary after the filename. Adequate details of the file format must be given on the command line or extracted from the file itself for a supported binary filetype. In particular, there are two structures for binary files, binary matrix format and binary general format.

The binary matrix format contains a two dimensional array of 32 bit IEEE float values plus an additional column and row of coordinate values. In the using specifier of a plot command, column 1 refers to the matrix row coordinate, column 2 refers to the matrix column coordinate, and column 3 refers to the value stored in the array at those coordinates.

The binary general format contains an arbitrary number of columns for which information must be specified at the command line. For example, array, record, format and using can indicate the size, format and dimension of data. There are a variety of useful commands for skipping file headers and changing endianess. There are a set of commands for positioning and translating data since often coordinates are not part of the file when uniform sampling is inherent in the data. Unlike reading from a text or matrix binary file, general binary does not treat the generated columns as 1, 2 or 3 in the using list. Instead column 1 refers to column 1 of the file, or as specified in the format list.

There are global default settings for the various binary options which may be set using the same syntax as the options when used as part of the (s)plot <filename> binary ... command. This syntax is set datafile binary .... The general rule is that common command-line specified parameters override file-extracted parameters which override default parameters.

Binary matrix is the default binary format when no keywords specific to binary general are given, i.e., array, record, format, filetype.

General binary data can be entered at the command line via the special file name '-'. However, this is intended for use through a pipe where programs can exchange binary data, not for keyboards. There is no "end of record" character for binary data. Gnuplot continues reading from a pipe until it has read the number of points declared in the array qualifier. See binary matrix or binary general for more details.

The index keyword is not supported, since the file format allows only one surface per file. The every and using filters are supported. using operates as if the data were read in the above triplet form.

Binary File Splot Demo.

The binary keyword appearing alone indicates a binary data file that contains both coordinate information describing a non-uniform grid and the value of each grid point (see binary matrix). Binary data in any other format requires additional keywords to describe the layout of the data. Unfortunately the syntax of these required additional keywords is convoluted. Nevertheless the general binary mode is particularly useful for application programs sending large amounts of data to gnuplot.

Syntax:

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

General binary format is activated by keywords in <binary list> pertaining to information about file structure, i.e., array, record, format or filetype. Otherwise, non-uniform matrix binary format is assumed. (See binary matrix for more details.)

NB: In previous versions of gnuplot there have been some differences between the interpretation of binary data keywords by plot and splot. Where the meanings differ, one or both may change in a future gnuplot version.

Gnuplot knows how to read a few standard binary file types that are fully self-describing, e.g. PNG images. Type show datafile binary at the command line for a list. Apart from these, you can think of binary data files as conceptually the same as text data. Each point has columns of information which are selected via the using specification. If no format string is specified, gnuplot will read in a number of binary values equal to the largest column given in the <using list>. For example, using 1:3 will result in three columns being read, of which the second will be ignored. Certain plot types have an associated default using specification. For example, with image has a default of using 1, while with rgbimage has a default of using 1:2:3.

Describes the sampling array dimensions associated with the binary file. The coordinates will be generated by gnuplot. A number must be specified for each dimension of the array. For example, array=(10,20) means the underlying sampling structure is two-dimensional with 10 points along the first (x) dimension and 20 points along the second (y) dimension. A negative number indicates that data should be read until the end of file. If there is only one dimension, the parentheses may be omitted. A colon can be used to separate the dimensions for multiple records. For example, array=25:35 indicates there are two one-dimensional records in the file.

Note: Gnuplot version 4.2 used the syntax array=128x128 rather than array=(128,128). The older syntax is now deprecated.

This keyword serves the same function as array and has the same syntax. However, record causes gnuplot to not generate coordinate information. This is for the case where such information may be included in one of the columns of the binary data file.

This keyword allows you to skip sections of a binary file. For instance, if the file contains a 1024 byte header before the start of the data region you would probably want to use

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

If there are multiple records in the file, you may specify a leading offset for each. For example, to skip 512 bytes before the 1st record and 256 bytes before the second and third records

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

The default binary format is a float. For more flexibility, the format can include details about variable sizes. For example, format="%uchar%int%float" associates an unsigned character with the first using column, an int with the second column and a float with the third column. If the number of size specifications is less than the greatest column number, the size is implicitly taken to be similar to the last given variable size.

Furthermore, similar to the using specification, the format can include discarded columns via the * character and have implicit repetition via a numerical repeat-field. For example, format="%*2int%3float" causes gnuplot to discard two ints before reading three floats. To list variable sizes, type show datafile binary datasizes. There are a group of names that are machine dependent along with their sizes in bytes for the particular compilation. There is also a group of names which attempt to be machine independent.

Often the endianess of binary data in the file does not agree with the endianess used by the platform on which gnuplot is running. Several words can direct gnuplot how to arrange bytes. For example endian=little means treat the binary file as having byte significance from least to greatest. The options are

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

Gnuplot can support "middle" ("pdp") endian if it is compiled with that option.

For some standard binary file formats gnuplot can extract all the necessary information from the file in question. As an example, "format=edf" will read ESRF Header File format files. For a list of the currently supported file formats, type show datafile binary filetypes.

There is a special file type called auto for which gnuplot will check if the binary file's extension is a quasi-standard extension for a supported format.

Command line keywords may be used to override settings extracted from the file. The settings from the file override any defaults. See set datafile binary.

avs is one of the automatically recognized binary file types for images. AVS is an extremely simple format, suitable mostly for streaming between applications. It consists of 2 longs (xwidth, ywidth) followed by a stream of pixels, each with four bytes of information alpha/red/green/blue.

edf is one of the automatically recognized binary file types for images. EDF stands for ESRF Data Format, and it supports both edf and ehf formats (the latter means ESRF Header Format). More information on specifications can be found at

http://www.edfplus.info/specs

If gnuplot was configured to use the libgd library for png/gif/jpeg output, then it can also be used to read these same image types as binary files. You can use an explicit command

plot 'file.png' binary filetype=png

Or the file type will be recognized automatically from the extension if you have previously requested

set datafile binary filetype=auto

The following keywords apply only when generating coordinates from binary data files. That is, the control mapping the individual elements of a binary array, matrix, or image to specific x/y/z positions.

A great deal of confusion can arise concerning the relationship between how gnuplot scans a binary file and the dimensions seen on the plot. To lessen the confusion, conceptually think of gnuplot _always_ scanning the binary file point/line/plane or fast/medium/slow. Then this keyword is used to tell gnuplot how to map this scanning convention to the Cartesian convention shown in plots, i.e., x/y/z. The qualifier for scan is a two or three letter code representing where point is assigned (first letter), line is assigned (second letter), and plane is assigned (third letter). For example, scan=yx means the fastest, point-by-point, increment should be mapped along the Cartesian y dimension and the middle, line-by-line, increment should be mapped along the x dimension.

When the plotting mode is plot, the qualifier code can include the two letters x and y. For splot, it can include the three letters x, y and z.

There is nothing restricting the inherent mapping from point/line/plane to apply only to Cartesian coordinates. For this reason there are cylindrical coordinate synonyms for the qualifier codes where t (theta), r and z are analogous to the x, y and z of Cartesian coordinates.

Shorthand notation for scan=yx or scan=yxz.

When gnuplot generates coordinates, it uses the spacing described by these keywords. For example dx=10 dy=20 would mean space samples along the x dimension by 10 and space samples along the y dimension by 20. dy cannot appear if dx does not appear. Similarly, dz cannot appear if dy does not appear. If the underlying dimensions are greater than the keywords specified, the spacing of the highest dimension given is extended to the other dimensions. For example, if an image is being read from a file and only dx=3.5 is given gnuplot uses a delta x and delta y of 3.5.

The following keywords also apply only when generating coordinates. However they may also be used with matrix binary files.

Sometimes the scanning directions in a binary datafile are not consistent with that assumed by gnuplot. These keywords can flip the scanning direction along dimensions x, y, z.

When gnuplot generates coordinates based upon transposition and flip, it attempts to always position the lower left point in the array at the origin, i.e., the data lies in the first quadrant of a Cartesian system after transpose and flip.

To position the array somewhere else on the graph, the origin keyword directs gnuplot to position the lower left point of the array at a point specified by a tuple. The tuple should be a double for plot and a triple for splot. For example, origin=(100,100):(100,200) is for two records in the file and intended for plotting in two dimensions. A second example, origin=(0,0,3.5), is for plotting in three dimensions.

Similar to origin, this keyword will position the array such that its center lies at the point given by the tuple. For example, center=(0,0). Center does not apply when the size of the array is Inf.

The transpose and flip commands provide some flexibility in generating and orienting coordinates. However, for full degrees of freedom, it is possible to apply a rotational vector described by a rotational angle in two dimensions.

The rotate keyword applies to the two-dimensional plane, whether it be plot or splot. The rotation is done with respect to the positive angle of the Cartesian plane.

The angle can be expressed in radians, radians as a multiple of pi, or degrees. For example, rotate=1.5708, rotate=0.5pi and rotate=90deg are equivalent.

If origin is specified, the rotation is done about the lower left sample point before translation. Otherwise, the rotation is done about the array center.

For splot, the concept of a rotational vector is implemented by a triple representing the vector to be oriented normal to the two-dimensional x-y plane. Naturally, the default is (0,0,1). Thus specifying both rotate and perpendicular together can orient data myriad ways in three-space.

The two-dimensional rotation is done first, followed by the three-dimensional rotation. That is, if R' is the rotational 2 x 2 matrix described by an angle, and P is the 3 x 3 matrix projecting (0,0,1) to (xp,yp,zp), let R be constructed from R' at the upper left sub-matrix, 1 at element 3,3 and zeros elsewhere. Then the matrix formula for translating data is v' = P R v, where v is the 3 x 1 vector of data extracted from the data file. In cases where the data of the file is inherently not three-dimensional, logical rules are used to place the data in three-space. (E.g., usually setting the z-dimension value to zero and placing 2D data in the x-y plane.)

Discrete data contained in a file can be displayed by specifying the name of the data file (enclosed in single or double quotes) on the plot command line.

Syntax:

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>} {volatile} {noautoscale}

The modifiers binary, index, every, skip, using, and smooth are discussed separately. In brief, binary allows data entry from a binary file, index selects which data sets in a multi-data-set file are to be plotted, every specifies which points within a single data set are to be plotted, using determines how the columns within a single record are to be interpreted, and smooth allows for simple interpolation and approximation. splot has a similar syntax, but does not support the smooth option.

The noautoscale keyword means that the points making up this plot will be ignored when automatically determining axis range limits.

TEXT DATA FILES:

Data files should contain at least one data point per record (using can select one data point from the record). Records beginning with # (and also with ! on VMS) will be treated as comments and ignored. Each data point represents an (x,y) pair. For plots with error bars or error bars with lines (see errorbars or errorlines), each data point is (x,y,ydelta), (x,y,ylow,yhigh), (x,y,xdelta), (x,y,xlow,xhigh), or (x,y,xlow,xhigh,ylow,yhigh).

In all cases, the numbers of each record of a data file must be separated by white space (one or more blanks or tabs) unless a format specifier is provided by the using option. This white space divides each record into columns. However, whitespace inside a pair of double quotes is ignored when counting columns, so the following datafile line has three columns:

1.0 "second column" 3.0

Data may be written in exponential format with the exponent preceded by the letter e or E. The fortran exponential specifiers d, D, q, and Q may also be used if the command set datafile fortran is in effect.

Only one column (the y value) need be provided. If x is omitted, gnuplot provides integer values starting at 0.

In datafiles, blank records (records with no characters other than blanks and a newline and/or carriage return) are significant.

Single blank records designate discontinuities in a plot; no line will join points separated by a blank records (if they are plotted with a line style).

Two blank records in a row indicate a break between separate data sets. See index.

If autoscaling has been enabled (set autoscale), the axes are automatically extended to include all datapoints, with a whole number of tic marks if tics are being drawn. This has two consequences: i) For splot, the corner of the surface may not coincide with the corner of the base. In this case, no vertical line is drawn. ii) When plotting data with the same x range on a dual-axis graph, the x coordinates may not coincide if the x2tics are not being drawn. This is because the x axis has been autoextended to a whole number of tics, but the x2 axis has not. The following example illustrates the problem:

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

To avoid this, you can use the fixmin/fixmax feature of the set autoscale command, which turns off the automatic extension of the axis range up to the next tic mark.

Label coordinates and text can also be read from a data file (see labels).

The every keyword allows a periodic sampling of a data set to be plotted.

In the discussion a "point" is a datum defined by a single record in the file; "block" here will mean the same thing as "datablock" (see glossary).

Syntax:

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

The data points to be plotted are selected according to a loop from <start_point> to <end_point> with increment <point_incr> and the blocks according to a loop from <start_block> to <end_block> with increment <block_incr>.

The first datum in each block is numbered '0', as is the first block in the file.

Note that records containing unplottable information are counted.

Any of the numbers can be omitted; the increments default to unity, the start values to the first point or block, and the end values to the last point or block. ':' at the end of the every option is not permitted. If every is not specified, all points in all lines are plotted.

Examples:

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

See

simple plot demos (simple.dem)

,

Non-parametric splot demos

, and

Parametric splot demos

.

This example plots the data in the file "population.dat" and a theoretical curve:

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

The file "population.dat" might contain:

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

Binary examples:

# 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

See also binary matrix.

The index keyword allows you to select specific data sets in a multi-data-set file for plotting.

Syntax:

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

Data sets are separated by pairs of blank records. index <m> selects only set <m>; index <m>:<n> selects sets in the range <m> to <n>; and index <m>:<n>:<p> selects indices <m>, <m>+<p>, <m>+2<p>, etc., but stopping at <n>. Following C indexing, the index 0 is assigned to the first data set in the file. Specifying too large an index results in an error message. If <p> is specified but <n> is left blank then every <p>-th dataset is read until the end of the file. If index is not specified, the entire file is plotted as a single data set.

Example:

plot 'file' index 4:5

For each point in the file, the index value of the data set it appears in is available via the pseudo-column column(-2). This leads to an alternative way of distinguishing individual data sets within a file as shown below. This is more awkward than the index command if all you are doing is selecting one data set for plotting, but is very useful if you want to assign different properties to each data set. See pseudocolumns, lc variable.

Example:

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

index '<name>' selects the data set with name '<name>'. Names are assigned to data sets in comment lines. The comment character and leading white space are removed from the comment line. If the resulting line starts with <name>, the following data set is now named <name> and can be selected.

Example:

plot 'file' index 'Population'

Please note that every comment that starts with <name> will name the following data set. To avoid problems it may be useful to choose a naming scheme like '== Population ==' or '[Population]'.

See also web page splot with indices demo.

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.

The skip keyword tells the program to skip lines at the start of a text (i.e. not binary) data file. The lines that are skipped do not count toward the line count used in processing the every keyword. Note that skip N skips lines only at the start of the file, whereas every ::N skips lines at the start of every data block in the file. See also binary skip for a similar option that applies to binary data files.

gnuplot includes a few general-purpose routines for interpolation and approximation of data; these are grouped under the smooth option. More sophisticated data processing may be performed by preprocessing the data externally or by using fit with an appropriate model.

Syntax:

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

unique, frequency, cumulative and cnormal plot the data after making them monotonic. unwrap manipulates the data to avoid jumps of more than pi by adding or subtracting multiples of 2*pi. Each of the other routines uses the data to determine the coefficients of a continuous curve between the endpoints of the data. This curve is then plotted in the same manner as a function, that is, by finding its value at uniform intervals along the abscissa (see set samples) and connecting these points with straight line segments (if a line style is chosen).

If autoscale is in effect, the ranges will be computed such that the plotted curve lies within the borders of the graph.

If autoscale is not in effect, and the smooth option is either acspline or cspline, the sampling of the generated curve is done across the intersection of the x range covered by the input data and the fixed abscissa range as defined by set xrange.

If too few points are available to allow the selected option to be applied, an error message is produced. The minimum number is one for unique and frequency, four for acsplines, and three for the others.

The smooth options have no effect on function plots.

The acsplines option approximates the data with a "natural smoothing spline". After the data are made monotonic in x (see smooth unique), a curve is piecewise constructed from segments of cubic polynomials whose coefficients are found by fitting to the individual data points weighted by the value, if any, given in the third column of the using spec. The default is equivalent to

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

Qualitatively, the absolute magnitude of the weights determines the number of segments used to construct the curve. If the weights are large, the effect of each datum is large and the curve approaches that produced by connecting consecutive points with natural cubic splines. If the weights are small, the curve is composed of fewer segments and thus is smoother; the limiting case is the single segment produced by a weighted linear least squares fit to all the data. The smoothing weight can be expressed in terms of errors as a statistical weight for a point divided by a "smoothing factor" for the curve so that (standard) errors in the file can be used as smoothing weights.

Example:

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

The bezier option approximates the data with a Bezier curve of degree n (the number of data points) that connects the endpoints.

The csplines option connects consecutive points by natural cubic splines after rendering the data monotonic (see smooth unique).

The mcsplines option connects consecutive points by cubic splines constrained such that the smoothed function preserves the monotonicity and convexity of the original data points. FN Fritsch & RE Carlson (1980) "Monotone Piecewise Cubic Interpolation", SIAM Journal on Numerical Analysis 17: 238–246.

The sbezier option first renders the data monotonic (unique) and then applies the bezier algorithm.

The unique option makes the data monotonic in x; points with the same x-value are replaced by a single point having the average y-value. The resulting points are then connected by straight line segments.

The unwrap option modifies the input data so that any two successive points will not differ by more than pi; a point whose y value is outside this range will be incremented or decremented by multiples of 2pi until it falls within pi of the previous point. This operation is useful for making wrapped phase measurements continuous over time.

The frequency option makes the data monotonic in x; points with the same x-value are replaced by a single point having the summed y-values. To plot a histogram of the number of data values in equal size bins, set the y-value to 1.0 so that the sum is a count of occurances in that bin: Example:

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

See also

smooth.dem

The cumulative option makes the data monotonic in x; points with the same x-value are replaced by a single point containing the cumulative sum of y-values of all data points with lower x-values (i.e. to the left of the current data point). This can be used to obtain a cumulative distribution function from data. See also

smooth.dem

The cnormal option makes the data monotonic in x and normalises the y-values onto the range [0:1]. Points with the same x-value are replaced by a single point containing the cumulative sum of y-values of all data points with lower x-values (i.e. to the left of the current data point) divided by the total sum of all y-values. This can be used to obtain a normalised cumulative distribution function from data (useful when comparing sets of samples with differing numbers of members). See also

smooth.dem

The kdensity option is a way to plot a kernel density estimate (which is a smooth histogram) for a random collection of points, using Gaussian kernels. A Gaussian is placed at the location of each point in the first column and the sum of all these Gaussians is plotted as a function. The value in the second column is taken as weight of the Gaussian. To obtain a normalized histogram, this should be 1/number-of-points. By default gnuplot calculates and uses the bandwidth which would be optimal for normally distributed data.

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

This will usually be a very conservative, i.e. broad bandwidth. Alternatively, you can provide an explicit bandwidth.

plot $DATA smooth kdensity bandwidth <value> with boxes

The bandwidth used in the previous plot is stored in variable GPVAL_KDENSITY_BANDWIDTH.

There are a few filenames that have a special meaning: '', '-', '+' and '++'.

The empty filename '' tells gnuplot to re-use the previous input file in the same plot command. So to plot two columns from the same input file:

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

The special filenames '+' and '++' are a mechanism to allow the full range of using specifiers and plot styles with inline functions. Normally a function plot can only have a single y (or z) value associated with each sampled point. The pseudo-file '+' treats the sampled points as column 1, and allows additional column values to be specified via a using specification, just as for a true input file. The number of samples returned is controlled by set samples. By default samples are generated over the full range on x, but an independent sampling range can be provided immediately before the '+' (see plot sampling). Example:

plot '+' using ($1):(sin($1)):(sin($1)**2) with filledcurves plot $MYDATA, [sample=5:25] '+' using (sample):(f(sample)) with lines

Similarly the pseudo-file '++' returns 2 columns of data forming a regular grid of [x,y] coordinates with the number of points along x controlled by set samples and the number of points along y controlled by set isosamples. In parametric mode the samples are along u and v rather than along x and y. You must set xrange and yrange (or urange and vrange) before plotting '++'. Examples:

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

The special filename '-' specifies that the data are inline; i.e., they follow the command. Only the data follow the command; plot options like filters, titles, and line styles remain on the plot command line. This is similar to << in unix shell script, and $DECK in VMS DCL. The data are entered as though they are being read from a file, one data point per record. The letter "e" at the start of the first column terminates data entry. The using option can be applied to these data---using it to filter them through a function might make sense, but selecting columns probably doesn't!

'-' is intended for situations where it is useful to have data and commands together, e.g., when gnuplot is run as a sub-process of some front-end application. Some of the demos, for example, might use this feature. While plot options such as index and every are recognized, their use forces you to enter data that won't be used. For example, while

plot '-' index 0, '-' index 1 2 4 6

10 12 14 e 2 4 6

10 12 14 e

does indeed work,

plot '-', '-' 2 4 6 e 10 12 14 e

is a lot easier to type.

If you use '-' with replot, you may need to enter the data more than once. See replot, refresh.

A blank filename ('') specifies that the previous filename should be reused. This can be useful with things like

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

(If you use both '-' and '' on the same plot command, you'll need to have two sets of inline data, as in the example above.)

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

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

would plot the same information as the first population example but with years since 1965 as the x axis. If you want to execute this example, you have to delete all comments from the data file above or substitute the following command for the first part of the command above (the part up to the comma):

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

While this approach is most flexible, it is possible to achieve simple filtering with the using keyword.

On systems with an fdopen() function, data can be read from an arbitrary file descriptor attached to either a file or pipe. To read from file descriptor n use '<&n'. This allows you to easily pipe in several data files in a single call from a POSIX shell:

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

The thru keyword is deprecated.

Old syntax:

plot 'file' thru f(x)

Current syntax:

plot 'file' using 1:(f($2))

The most common datafile modifier is using. It tells the program which columns of data in the input file are to be plotted.

Syntax:

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

If a format is specified, it is used to read in each datafile record using the C library 'scanf' function. Otherwise the record is interpreted as consisting of columns (fields) of data separated by whitespace (spaces and/or tabs), but see datafile separator.

Each <entry> may be a simple column number that selects the value from one field of the input file, a string that matches a column label in the first line of a data set, an expression enclosed in parentheses, or a special function not enclosed in parentheses such as xticlabels(2).

If the entry is an expression in parentheses, then the function column(N) may be used to indicate the value in column N. That is, column(1) refers to the first item read, column(2) to the second, and so on. The special symbols $1, $2, ... are shorthand for column(1), column(2) ... The function valid(N) tests whether the value in the Nth column is a valid number.

If each column of data in the input file contains a label in the first row rather than a data value, this label can be used to identify the column on input and/or in the plot legend. The column() function can be used to select an input column by label rather than by column number. For example, if the data file contains

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

then the following plot commands are all equivalent

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"

The full string must match. Comparison is case-sensitive. To use the column labels in the plot legend, use set key autotitle columnhead.

In addition to the actual columns 1...N in the input data file, gnuplot presents data from several "pseudo-columns" that hold bookkeeping information. E.g. $0 or column(0) returns the sequence number of this data record within a dataset. Please see pseudocolumns.

An empty <entry> will default to its order in the list of entries. For example, using ::4 is interpreted as using 1:2:4.

If the using list has only a single entry, that <entry> will be used for y and the data point number (pseudo-column $0) is used for x; for example, "plot 'file' using 1" is identical to "plot 'file' using 0:1". If the using list has two entries, these will be used for x and y. See set style and fit for details about plotting styles that make use of data from additional columns of input.

'scanf' accepts several numerical specifications but gnuplot requires all inputs to be double-precision floating-point variables, so "%lf" is essentially the only permissible specifier. A format string given by the user must contain at least one such input specifier, and no more than seven of them. 'scanf' expects to see white space---a blank, tab ("\t"), newline ("\n"), or formfeed ("\f")---between numbers; anything else in the input stream must be explicitly skipped.

Note that the use of "\t", "\n", or "\f" requires use of double-quotes rather than single-quotes.

This creates a plot of the sum of the 2nd and 3rd data against the first: The format string specifies comma- rather than space-separated columns. The same result could be achieved by specifying set datafile separator comma.

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

In this example the data are read from the file "MyData" using a more complicated format:

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

The meaning of this format is:

%*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)

One trick is to use the ternary ?: operator to filter data:

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

which plots the datum in column two against that in column one provided the datum in column three exceeds ten. 1/0 is undefined; gnuplot quietly ignores undefined points, so unsuitable points are suppressed. Or you can use the pre-defined variable NaN to achieve the same result.

In fact, you can use a constant expression for the column number, provided it doesn't start with an opening parenthesis; constructs like using 0+(complicated expression) can be used. The crucial point is that the expression is evaluated once if it doesn't start with a left parenthesis, or once for each data point read if it does.

If timeseries data are being used, the time can span multiple columns. The starting column should be specified. Note that the spaces within the time must be included when calculating starting columns for other data. E.g., if the first element on a line is a time with an embedded space, the y value should be specified as column three.

It should be noted that plot 'file', plot 'file' using 1:2, and plot 'file' using ($1):($2) can be subtly different: 1) if file has some lines with one column and some with two, the first will invent x values when they are missing, the second will quietly ignore the lines with one column, and the third will store an undefined value for lines with one point (so that in a plot with lines, no line joins points across the bad point); 2) if a line contains text at the first column, the first will abort the plot on an error, but the second and third should quietly skip the garbage.

In fact, it is often possible to plot a file with lots of lines of garbage at the top simply by specifying

plot 'file' using 1:2

However, if you want to leave text in your data files, it is safer to put the comment character (#) in the first column of the text lines.

Expressions in the using clause of a plot statement can refer to additional bookkeeping values in addition to the actual data values contained in the input file. These are contained in "pseudocolumns".

column(0) The sequential order of each point within a data set. The counter starts at 0 and is reset by two sequential blank records. The shorthand form $0 is available. column(-1) This counter starts at 0 and is reset by a single blank line. This corresponds to the data line in array or grid data. column(-2) The index number of the current data set within a file that contains multiple data sets. See `index`.

Axis tick labels can be generated via a string function, usually taking a data column as an argument. The simplest form uses the data column itself as a string. That is, xticlabels(N) is shorthand for xticlabels(stringcolumn(N)). This example uses the contents of column 3 as x-axis tick labels.

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

Axis tick labels may be generated for any of the plot axes: x x2 y y2 z. The ticlabels(<labelcol>) specifiers must come after all of the data coordinate specifiers in the using portion of the command. For each data point which has a valid set of X,Y[,Z] coordinates, the string value given to xticlabels() is added to the list of xtic labels at the same X coordinate as the point it belongs to. xticlabels() may be shortened to xtic() and so on.

Example:

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

In this example the x and y axis tic labels are taken from different columns than the x and y coordinate values. The z axis tics, however, are generated from the z coordinate of the corresponding point.

Example:

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

This example shows the use of a string-valued function to generate x-axis tick labels. Each point in the data file generates a tick mark on x labeled either "A" or "B" depending on the value in column 3.

The volatile keyword in a plot command indicates that the data previously read from the input stream or file may not be available for re-reading. This tells the program to use refresh rather than replot commands whenever possible. See refresh.

Error bars are supported for 2D data file plots by reading one to four additional columns (or using entries); these additional values are used in different ways by the various errorbar styles.

In the default situation, gnuplot expects to see three, four, or six numbers on each line of the data file---either

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

The x coordinate must be specified. The order of the numbers must be exactly as given above, though the using qualifier can manipulate the order and provide values for missing columns. For example,

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

The last example is for a file containing an unsupported combination of relative x and absolute y errors. The using entry generates absolute x min and max from the relative error.

The y error bar is a vertical line plotted from (x, ylow) to (x, yhigh). If ydelta is specified instead of ylow and yhigh, ylow = y - ydelta and yhigh = y + ydelta are derived. If there are only two numbers on the record, yhigh and ylow are both set to y. The x error bar is a horizontal line computed in the same fashion. To get lines plotted between the data points, plot the data file twice, once with errorbars and once with lines (but remember to use the notitle option on one to avoid two entries in the key). Alternately, use the errorlines command (see errorlines).

The error bars have crossbars at each end unless set bars is used (see set bars for details).

If autoscaling is on, the ranges will be adjusted to include the error bars.

See also

errorbar demos.

See plot using, plot with, and set style for more information.

Lines with error bars are supported for 2D data file plots by reading one to four additional columns (or using entries); these additional values are used in different ways by the various errorlines styles.

In the default situation, gnuplot expects to see three, four, or six numbers on each line of the data file---either

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

The x coordinate must be specified. The order of the numbers must be exactly as given above, though the using qualifier can manipulate the order and provide values for missing columns. For example,

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

The last example is for a file containing an unsupported combination of relative x and absolute y errors. The using entry generates absolute x min and max from the relative error.

The y error bar is a vertical line plotted from (x, ylow) to (x, yhigh). If ydelta is specified instead of ylow and yhigh, ylow = y - ydelta and yhigh = y + ydelta are derived. If there are only two numbers on the record, yhigh and ylow are both set to y. The x error bar is a horizontal line computed in the same fashion.

The error bars have crossbars at each end unless set bars is used (see set bars for details).

If autoscaling is on, the ranges will be adjusted to include the error bars.

See plot using, plot with, and set style for more information.

Built-in or user-defined functions can be displayed by the plot and splot commands in addition to, or instead of, data read from a file. The requested function is evaluated by sampling at regular intervals spanning the independent axis range[s]. See set samples and set isosamples. Example:

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

To set a default plot style for functions, see set style function. For information on built-in functions, see expressions functions. For information on defining your own functions, see user-defined.

When in parametric mode (set parametric) mathematical expressions must be given in pairs for plot and in triplets for splot.

Examples:

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

Data files are plotted as before, except any preceding parametric function must be fully specified before a data file is given as a plot. In other words, the x parametric function (sin(t) above) and the y parametric function (t**2 above) must not be interrupted with any modifiers or data functions; doing so will generate a syntax error stating that the parametric function is not fully specified.

Other modifiers, such as with and title, may be specified only after the parametric function has been completed:

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

See also

Parametric Mode Demos.

This section describes only the optional axis ranges that may appear as the very first items in a plot command. If present, these ranges override any range limits established by a previous set range statement. For optional ranges elsewhere in a plot command that limit sampling of an individual plot component see sampling.

Syntax:

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

The first form applies to the independent variable (xrange or trange, if in parametric mode). The second form applies to dependent variables. <dummy-var> optionally establishes a new name for the independent variable. (The default name may be changed with set dummy.)

In non-parametric mode, ranges must be given in the order

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

In parametric mode, ranges must be given in the order

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

The following plot command shows setting trange to [-pi:pi], xrange to [-1.3:1.3] and yrange to [-1:1] for the duration of the graph:

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

* can be used to allow autoscaling of either of min and max. Use an empty range [] as a placeholder if necessary.

Ranges specified on the plot or splot command line affect only that one graph; use the set xrange, set yrange, etc., commands to change the default ranges for future graphs.

For time data you must provide the range in quotes, using the same format used to read time from the datafile. See set timefmt.

Examples:

This uses the current ranges:

plot cos(x)

This sets the x range only:

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

This is the same, but uses t as the dummy-variable:

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

This sets both the x and y ranges:

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

This sets only the y range:

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

This sets xmax and ymin only:

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

This sets the x range for a timeseries:

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

By default, computed functions or data generated for the pseudo-file "+" are sampled over the entire range of the plot. This range may have been specified by a prior set xrange command, by an explicit global range specifier at the very start of the plot command, or by autoscaling of the range to span data seen in all the elements of this plot command. However, individual plot components can be assigned a more restricted sampling range.

Examples:

This establishes a total range on x running from 0 to 1000 and then plots data from a file and two functions each spanning a portion of the total range:

plot [0:1000] 'datafile', [0:200] func1(x), [200:500] func2(x)

This is similar except that the total range is established by the contents of the data file. In this case the sampled functions may or may not be entirely contained in the plot:

set autoscale x plot 'datafile', [0:200] func1(x), [200:500] func2(x)

This command is ambiguous. The initial range will be interpreted as applying to the entire plot, not solely to the sampling of the first function as was probably the intent:

plot [0:10] f(x), [10:20] g(x), [20:30] h(x)

This command removes the ambiguity of the previous example by inserting the keyword sample so that the range is not applied to the entire plot:

plot sample [0:10] f(x), [10:20] g(x), [20:30] h(x)

This example shows one way of tracing out a helix in a 3D plot

splot [-2:2][-2:2] sample [h=1:10] '+' using (cos(h)):(sin(h)):(h)

If many similar files or functions are to be plotted together, it may be convenient to do so by iterating over a shared plot command.

Syntax:

plot for [<variable> = <start> : <end> {:<increment>}] plot for [<variable> in "string of words"]

The scope of an iteration ends at the next comma or the end of the command, whichever comes first. Therefore iteration does not work for plots in parametric mode.

This will plot one curve, sin(3x), because iteration ends at the comma

plot for [i=1:3] j=i, sin(j*x)

This will plot three curves because there is no comma after the definition of j

plot for [i=1:3] j=i sin(j*x)

Example:

plot for [dataset in "apples bananas"] dataset."dat" title dataset

In this example iteration is used both to generate a file name and a corresponding title.

Example:

file(n) = sprintf("dataset_%d.dat",n) splot for [i=1:10] file(i) title sprintf("dataset %d",i)

This example defines a string-valued function that generates file names, and plots ten such files together. The iteration variable ('i' in this example) is treated as an integer, and may be used more than once.

Example:

set key left plot for [n=1:4] x**n sprintf("%d",n)

This example plots a family of functions.

Example:

list = "apple banana cabbage daikon eggplant" item(n) = word(list,n) plot for [i=1:words(list)] item[i].".dat" title item(i) list = "new stuff" replot

This example steps through a list and plots once per item. Because the items are retrieved dynamically, you can change the list and then replot.

Example:

list = "apple banana cabbage daikon eggplant" plot for [i in list] i.".dat" title i list = "new stuff" replot

This is example does exactly the same thing as the previous example, but uses the string iterator form of the command rather than an integer iterator.

By default each plot is listed in the key by the corresponding function or file name. You can give an explicit plot title instead using the title option.

Syntax:

title <text> | notitle [<ignored text>] title columnheader | title columnheader(N) {at {beginning|end}}

where <text> is a quoted string or an expression that evaluates to a string. The quotes will not be shown in the key.

There is also an option that will interpret the first entry in a column of input data (i.e. the column header) as a text field, and use it as the key title. See datastrings. This can be made the default by specifying set key autotitle columnhead.

The line title and sample can be omitted from the key by using the keyword notitle. A null title (title '') is equivalent to notitle. If only the sample is wanted, use one or more blanks (title ' '). If notitle is followed by a string this string is ignored.

If key autotitles is set (which is the default) and neither title nor notitle are specified the line title is the function name or the file name as it appears on the plot command. If it is a file name, any datafile modifiers specified will be included in the default title.

The layout of the key itself (position, title justification, etc.) can be controlled by set key. Please see set key for details.

If you want the title of a plotted line to be placed immediately before or after that line in the graph itself, use at {beginning|end}. This option may be useful when plotting with lines but makes little sense for some other plot styles.

Examples:

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

plot x

This plots x squared with title "x^2" and file "data.1" with title "measured data":

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

This puts an untitled circular border around a polar graph:

set polar; plot my_function(t), 1 notitle

Plot multiple columns of data, each of which contains its own title on the first line of the file. Place the titles after the corresponding lines rather than in a separate key:

unset key set offset 0, graph 0.1 plot for [i=1:4] 'data' using i with lines title columnhead at end

Functions and data may be displayed in one of a large number of styles. The with keyword provides the means of selection.

Syntax:

with <style> { {linestyle | ls <line_style>} | {{linetype | lt <line_type>} {linewidth | lw <line_width>} {linecolor | lc <colorspec>} {pointtype | pt <point_type>} {pointsize | ps <point_size>} {fill | fs <fillstyle>} {nohidden3d} {nocontours} {nosurface} {palette}} }

where <style> is one of

lines dots steps errorbars xerrorbar xyerrorlines points impulses fsteps errorlines xerrorlines yerrorbars linespoints labels histeps financebars xyerrorbars yerrorlines surface vectors

or

boxes boxplot ellipses image boxerrorbars candlesticks filledcurves rgbimage boxxyerrorbars circles histograms rgbalpha pm3d

The first group of styles have associated line, point, and text properties. The second group of styles also have fill properties. See fillstyle. Some styles have further sub-styles. See plotting styles for details of each.

A default style may be chosen by set style function and set style data.

By default, each function and data file will use a different line type and point type, up to the maximum number of available types. All terminal drivers support at least six different point types, and re-use them, in order, if more are required. To see the complete set of line and point types available for the current terminal, type test.

If you wish to choose the line or point type for a single plot, <line_type> and <point_type> may be specified. These are positive integer constants (or expressions) that specify the line type and point type to be used for the plot. Use test to display the types available for your terminal.

You may also scale the line width and point size for a plot by using <line_width> and <point_size>, which are specified relative to the default values for each terminal. The pointsize may also be altered globally---see set pointsize for details. But note that both <point_size> as set here and as set by set pointsize multiply the default point size---their effects are not cumulative. That is, set pointsize 2; plot x w p ps 3 will use points three times default size, not six.

It is also possible to specify pointsize variable either as part of a line style or for an individual plot. In this case one extra column of input is required, i.e. 3 columns for a 2D plot and 4 columns for a 3D splot. The size of each individual point is determined by multiplying the global pointsize by the value read from the data file.

If you have defined specific line type/width and point type/size combinations with set style line, one of these may be selected by setting <line_style> to the index of the desired style.

If gnuplot was built with pm3d support, the special keyword palette is allowed for smooth color change of lines, points and dots in splots. The color is chosen from a smooth palette which was set previously with the command set palette. The color value corresponds to the z-value of the point coordinates or to the color coordinate if specified by the 4th parameter in using. Both 2D and 3D plots (plot and splot commands) can use palette colors as specified by either their fractional value or the corresponding value mapped to the colorbox range. A palette color value can also be read from an explicitly specified input column in the using specifier. See colors, set palette, linetype.

The keyword nohidden3d applies only to plots made with the splot command. Normally the global option set hidden3d applies to all plots in the graph. You can attach the nohidden3d option to any individual plots that you want to exclude from the hidden3d processing. The individual elements other than surfaces (i.e. lines, dots, labels, ...) of a plot marked nohidden3d will all be drawn, even if they would normally be obscured by other plot elements.

Similarly, the keyword nocontours will turn off contouring for an individual plot even if the global property set contour is active.

Similarly, the keyword nosurface will turn off the 3D surface for an individual plot even if the global property set surface is active.

The keywords may be abbreviated as indicated.

Note that the linewidth, pointsize and palette options are not supported by all terminals.

Examples:

This plots sin(x) with impulses:

plot sin(x) with impulses

This plots x with points, x**2 with the default:

plot x w points, x**2

This plots tan(x) with the default function style, file "data.1" with lines:

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

This plots "leastsq.dat" with impulses:

plot 'leastsq.dat' w i

This plots the data file "population" with boxes:

plot 'population' with boxes

This plots "exper.dat" with errorbars and lines connecting the points (errorbars require three or four columns):

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

Another way to plot "exper.dat" with errorlines (errorbars require three or four columns):

plot 'exper.dat' w errorlines

This plots sin(x) and cos(x) with linespoints, using the same line type but different point types:

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

This plots file "data" with points of type 3 and twice usual size:

plot 'data' with points pointtype 3 pointsize 2

This plots file "data" with variable pointsize read from column 4

plot 'data' using 1:2:4 with points pt 5 pointsize variable

This plots two data sets with lines differing only by weight:

plot 'd1' t "good" w l lt 2 lw 3, 'd2' t "bad" w l lt 2 lw 1

This plots filled curve of x*x and a color stripe:

plot x*x with filledcurve closed, 40 with filledcurve y1=10

This plots x*x and a color box:

plot x*x, (x>=-5 && x<=5 ? 40 : 1/0) with filledcurve y1=10 lt 8

This plots a surface with color lines:

splot x*x-y*y with line palette

This plots two color surfaces at different altitudes:

splot x*x-y*y with pm3d, x*x+y*y with pm3d at t