\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gnuplot.info
@settitle Gnuplot: An Interactive Plotting Program
@setchapternewpage odd
@c %**end of header
@c define the command and options indeces
@defindex cm
@defindex op
@defindex tm
@dircategory Math
@direntry
* GNUPLOT: (gnuplot). An Interactive Plotting Program
@end direntry
@ifnottex
@node Top, gnuplot, (dir), (dir)
@top Master Menu
@end ifnottex
@example
GNUPLOT
An Interactive Plotting Program
Thomas Williams & Colin Kelley
Version 4.3 organized by:
Hans-Bernhard Broeker, Ethan A Merritt, and others
Copyright (C) 1986 - 1993, 1998, 2004 Thomas Williams, Colin Kelley
Copyright (C) 2004 - 2008 various authors
Mailing list for comments: gnuplot-info@@lists.sourceforge.net
Mailing list for bug reports: gnuplot-bugs@@lists.sourceforge.net
This manual was originally prepared by Dick Crawford
Version 4.3 - 21 May 2008
Major contributors (alphabetic order):
@end example
@c ^ An Interactive Plotting Program
@c ^
Thomas Williams & Colin Kelley
@c ^
Version 4.2 organized by Hans-Bernhard Broeker and others
@c ^
Major contributors (alphabetic order):
@itemize @bullet
@item
Hans-Bernhard Broeker
@item
John Campbell
@item
Robert Cunningham
@item
David Denholm
@item
Gershon Elber
@item
Roger Fearick
@item
Carsten Grammes
@item
Lucas Hart
@item
Lars Hecking
@item
Thomas Koenig
@item
David Kotz
@item
Ed Kubaitis
@item
Russell Lang
@item
Alexander Lehmann
@item
Alexander Mai
@item
Ethan A Merritt
@item
Petr Mikulik
@item
Carsten Steger
@item
Tom Tkacik
@item
Jos Van der Woude
@item
Alex Woo
@item
James R. Van Zandt
@item
Johannes Zellner
@end itemize
@c ^ Copyright (C) 1986 - 1993, 1998 - 2004 Thomas Williams, Colin Kelley
@c ^ Mailing list for comments: gnuplot-info@@lists.sourceforge.net
@c ^ Mailing list for bug reports: gnuplot-bugs@@lists.sourceforge.net
@c ^
@c ^
This manual was prepared by Dick Crawford
@c ^
Last revised: February 2007
@c ^
@menu
* gnuplot::
* plotting_styles::
* Commands::
* Terminal_types::
* Graphical_User_Interfaces::
* Bugs::
* Concept_Index::
* Command_Index::
* Options_Index::
* Function_Index::
* Terminal_Index::
@end menu
@node gnuplot, plotting_styles, Top, Top
@chapter gnuplot
@menu
* Copyright::
* Introduction::
* Seeking-assistance::
* New_features_introduced_in_version_4.3::
* Backwards_compatibility::
* Batch/Interactive_Operation::
* Command-line-editing::
* Comments::
* Coordinates::
* Datastrings::
* Enhanced_text_mode::
* Environment::
* Expressions::
* Glossary::
* linetype::
* mouse_input::
* Plotting::
* Start-up::
* String_constants_and_string_variables::
* Substitution_and_Command_line_macros::
* Syntax::
* Time/Date_data::
@end menu
@node Copyright, Introduction, gnuplot, gnuplot
@section Copyright
@cindex copyright
@cindex license
@example
Copyright (C) 1986 - 1993, 1998, 2004, 2007 Thomas Williams, Colin Kelley
@end example
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
@example
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.
@end example
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.
@example
AUTHORS
@end example
@example
Original Software:
Thomas Williams, Colin Kelley.
@end example
@example
Gnuplot 2.0 additions:
Russell Lang, Dave Kotz, John Campbell.
@end example
@example
Gnuplot 3.0 additions:
Gershon Elber and many others.
@end example
@example
Gnuplot 4.0 additions:
See list of contributors at head of this document.
@end example
@node Introduction, Seeking-assistance, Copyright, gnuplot
@section Introduction
@cindex introduction
@c ?
`gnuplot` is a command-driven interactive function and data plotting program.
syntax:
@example
gnuplot @{X11OPTIONS@} @{OPTIONS@} file1 file2 ...
@end example
Generic X11 options, if any, must come first. See your X11 documentation.
If you are not using X11, ignore this. 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.
Example:
@example
gnuplot file1.in -e "reset" file2.in
@end example
The special filename "-" is used to force reading from stdin. `gnuplot` exits
after the last file is processed. If no load files are named, `gnuplot` takes
interactive input from stdin. See help `batch/interactive` for more details.
The options specific to gnuplot can be listed by typing
@example
gnuplot --help
@end example
`gnuplot` is case sensitive (commands and function names written in lowercase
are not the same as those written in CAPS). 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. Examples:
@example
load "filename"
cd 'dir'
@end example
Many `gnuplot` commands have multiple options. Version 4 is less sensitive
to the order of these options than earlier versions, but some order-dependence
remains. If you see error messages about unrecognized options, please try
again using the exact order listed in the documentation.
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 @ref{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 @ref{help} followed by the name of the topic
or `help ?` to get a menu of available topics.
The new `gnuplot` user should begin by reading about `plotting` (if in an
interactive session, type `help plotting`).
See the simple.dem demo, also available together with other demos on the web page
@uref{http://www.gnuplot.info/demo/,http://www.gnuplot.info/demo/
}
@node Seeking-assistance, New_features_introduced_in_version_4.3, Introduction, gnuplot
@section Seeking-assistance
@cindex help-desk
@cindex seeking-assistance
@c ^
There is a mailing list for `gnuplot` users. Note, however, that the
newsgroup
@example
comp.graphics.apps.gnuplot
@end example
is identical to the mailing list (they both carry the same set of messages).
We prefer that you read the messages through the newsgroup rather than
subscribing to the mailing list. Instructions for subscribing to gnuplot
mailing lists may be found via the gnuplot development website on SourceForge
@uref{http://sourceforge.net/projects/gnuplot,http://sourceforge.net/projects/gnuplot
}
The address for mailing to list members is:
@example
gnuplot-info@@lists.sourceforge.net
@end example
Bug reports and code contributions should be uploaded to the trackers at
@example
http://sourceforge.net/projects/gnuplot
@end example
The list of those interested in beta-test versions is:
@example
gnuplot-beta@@lists.sourceforge.net
@end example
There is also the canonical (if occasionally out-of-date) gnuplot web page at
@uref{http://www.gnuplot.info,http://www.gnuplot.info
}
Before seeking help, please check the
@uref{http://www.gnuplot.info/faq/,FAQ (Frequently Asked Questions) list.
}
When posting a question, please include full details of the version of
`gnuplot`, the machine, and operating system you are using. A _small_ script
demonstrating the problem may be useful. Function plots are preferable to
datafile plots. If email-ing to gnuplot-info, please state whether or not
you are subscribed to the list, so that users who use news will know to email
a reply to you. There is a form for such postings on the WWW site.
@node New_features_introduced_in_version_4.3, Backwards_compatibility, Seeking-assistance, gnuplot
@section New features introduced in version 4.3
@cindex new-features
Gnuplot version 4.3 offers many new features introduced since the preceding
official version 4.2. This section lists major additions and gives a partial
list of changes and minor new features. For a more exhaustive list, see the
NEWS file.
@menu
* Internationalization::
* Transparency::
* Volatile_Data::
* Canvas_size::
* New_plot_elements::
* New_or_revised_terminal_drivers::
* New_smoothing_algorithms::
@end menu
@node Internationalization, Transparency, New_features_introduced_in_version_4.3, New_features_introduced_in_version_4.3
@subsection Internationalization
Gnuplot 4.3 contains significantly improved support for locale settings and for
UTF-8 character encodings. See @ref{locale}, @ref{encoding}, @ref{decimalsign}.
@node Transparency, Volatile_Data, Internationalization, New_features_introduced_in_version_4.3
@subsection Transparency
Gnuplot now supports transparent objects in several ways. Any object or plot
element that uses a fill style can be assigned a value from fully opaque to
fully transparent. Image or matrix data can be plotted with an alpha channel
using the new plot style @ref{rgbalpha}. See `fillstyle`, @ref{rgbalpha}.
@node Volatile_Data, Canvas_size, Transparency, New_features_introduced_in_version_4.3
@subsection Volatile Data
The new command @ref{refresh} is similar to @ref{replot} except that it uses the
previously-stored input data values rather than rereading the input data file.
Mouse operations (zoom, rotate) will automatically use @ref{refresh} rather than
@ref{replot} if the input data stream is marked `volatile`. Piped or in-line data
is automatically treated as volatile. See @ref{refresh}, `plot datafile volatile`.
@node Canvas_size, New_plot_elements, Volatile_Data, New_features_introduced_in_version_4.3
@subsection Canvas size
@c ?canvas size
@cindex canvas
@c ?set term size
In earlier versions of gnuplot, some terminal types used the values from
@ref{size} to control also the size of the output canvas; others did not.
The use of 'set size' for this purpose was deprecated in version 4.2.
In version 4.3 almost all terminals now behave as follows:
`set term size , ` controls the size of the output
file, or "canvas". Please see individual terminal documentation for allowed
values of the size parameters. By default, the plot will fill this canvas.
`set size , ` 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 on some terminal types.
The major exception to this convention is the PostScript driver, which
by default continues to act as it has in earlier versions. Be warned that
the next version of gnuplot may change the default behaviour of the
PostScript driver as well.
Example:
@example
set size 0.5, 0.5
set term png size 600, 400
set output "figure.png"
plot "data" with lines
@end example
These commands will produce an output file "figure.png" that is 600 pixels
wide and 400 pixels tall. The plot will fill the lower left quarter of this
canvas. This is consistent with the way multiplot mode has always worked,
however it is a change in the way the png driver worked for single plots in
version 4.0.
@node New_plot_elements, New_or_revised_terminal_drivers, Canvas_size, New_features_introduced_in_version_4.3
@subsection New plot elements
@cindex circles
@cindex ellipse
@cindex polygon
The @ref{object} command can now be used to define fixed circles, ellipses, and
polygons as well as rectangles. There is a corresponding new plot style
@ref{circles}. See `circle` @ref{ellipse} @ref{polygon}.
@node New_or_revised_terminal_drivers, New_smoothing_algorithms, New_plot_elements, New_features_introduced_in_version_4.3
@subsection New or revised terminal drivers
Two new drivers based on the cairo and pango libraries are included,
`pngcairo` and `pdfcairo`. These are alternatives to the older libgd-based
png driver and the older PDFLib-based pdf driver. The figures in the pdf
version of this manual were prepared using the pdfcairo terminal driver.
@node New_smoothing_algorithms, , New_or_revised_terminal_drivers, New_features_introduced_in_version_4.3
@subsection New smoothing algorithms
@cindex kdensity
@cindex cumulative
New smoothing algorithms have been added for both 2- and 3-dimensional plots.
`smooth kdensity` and `smooth cumul` can be used with `plot` to draw
smooth histograms and cumulative distribution functions, resp. For use
with `splot` several new smoothing kernels have been added to @ref{dgrid3d}.
See @ref{smooth} @ref{dgrid3d}.
@node Backwards_compatibility, Batch/Interactive_Operation, New_features_introduced_in_version_4.3, gnuplot
@section Backwards compatibility
@c ?backwards compatibility
@cindex compatibility
Gnuplot version 4.0 deprecated certain syntax used in earlier versions, but
continued to recognize it. This is now under the control of a configuration
option, and can be disabled as follows:
@example
./configure --disable-backwards-compatibility
@end example
Notice: Deprecated syntax items may be disabled permanently in some future
version of gnuplot.
One major difference is the introduction of keywords to disambiguate complex
commands, particularly commands containing string variables. A notable issue
was the use of bare numbers to specify offsets, line and point types.
Illustrative examples:
Deprecated:
@example
set title "Old" 0,-1
set data linespoints
plot 1 2 4 # horizontal line at y=1
@end example
New:
@example
TITLE = "New"
set title TITLE offset char 0, char -1
set style data linespoints
plot 1 linetype 2 pointtype 4
@end example
@node Batch/Interactive_Operation, Command-line-editing, Backwards_compatibility, gnuplot
@section Batch/Interactive Operation
@cindex batch/interactive
`gnuplot` may be executed in either batch or interactive modes, and the two
may even be mixed together on many systems.
Any command-line arguments are assumed to be either program options (first
character is -) or names of files containing `gnuplot` commands. The option
-e "command" may be used to force execution of a gnuplot command. 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.
Both the @ref{exit} and @ref{quit} commands terminate the current command file and
`load` the next one, until all have been processed.
Examples:
To launch an interactive session:
@example
gnuplot
@end example
To launch a batch session using two command files "input1" and "input2":
@example
gnuplot input1 input2
@end example
To launch an interactive session after an initialization file "header" and
followed by another command file "trailer":
@example
gnuplot header - trailer
@end example
To give `gnuplot` commands directly in the command line, using the "-persist"
option so that the plot remains on the screen afterwards:
@example
gnuplot -persist -e "set title 'Sine curve'; plot sin(x)"
@end example
To set user-defined variables a and s prior to executing commands from a file:
@example
gnuplot -e "a=2; s='file.png'" input.gpl
@end example
@node Command-line-editing, Comments, Batch/Interactive_Operation, gnuplot
@section Command-line-editing
@cindex line-editing
@cindex editing
@cindex command-line-editing
Command-line editing and command history are supported using either the
external gnu readline 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. The gnu
readline library has its own documentation.
@example
`Line-editing`:
@end example
@example
^B moves back a single character.
^F moves forward a single character.
^A moves to the beginning of the line.
^E moves to the end of the line.
^H and DEL delete the previous character.
^D deletes the current character.
^K deletes from current position to the end of line.
^L,^R redraws line in case it gets trashed.
^U deletes the entire line.
^W deletes from the current word to the end of line.
@end example
@example
`History`:
@end example
@example
^P moves back through history.
^N moves forward through history.
@end example
@node Comments, Coordinates, Command-line-editing, gnuplot
@section Comments
@cindex comments
Comments are supported as follows: a `#` may appear in most places in a line
and `gnuplot` will ignore the rest of the line. It will not have this effect
inside quotes, inside numbers (including complex numbers), inside command
substitutions, etc. In short, it works anywhere it makes sense to work.
See also `set datafile commentschars` for specifying comment characters in
data files. Note that if a comment line ends in '\' then the subsequent
line is also treated as a comment.
@node Coordinates, Datastrings, Comments, gnuplot
@section Coordinates
@cindex coordinates
@cindex axes
The commands @ref{arrow}, `set key`, `set label` and @ref{object} allow you
to draw something at an arbitrary position on the graph. This position is
specified by the syntax:
@example
@{@} , @{@} @{,@{@} @}
@end example
Each can either be `first`, `second`, `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 second 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 @ref{ticslevel}); `screen`
specifies the screen area (the entire area---not just the portion selected by
@ref{size}), with 0,0 at bottom left and 1,1 at top right; and `character`
gives the position in character widths and heights from the bottom left of
the screen area (screen 0,0), `character` coordinates depend on the chosen
font size.
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 @ref{arrow} ... `rto`). In
most cases, the given value serves as difference to the first position.
If the given coordinate resides in a logarithmic axis the value is
interpreted as factor. For example,
@example
set logscale x
set arrow 100,5 rto 10,2
@end example
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 @ref{timefmt} format string.
See @ref{xdata} and @ref{timefmt}. `gnuplot` will also accept an integer
expression, which will be interpreted as seconds from 1 January 2000.
@node Datastrings, Enhanced_text_mode, Coordinates, gnuplot
@section Datastrings
@cindex 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 sample line from a datafile is interpreted to contain four
columns, with a text field in column 3:
@example
1.000 2.000 "Third column is all of this text" 4.00
@end example
Text fields can be positioned within a 2-D or 3-D plot using the commands:
@example
plot 'datafile' using 1:2:4 with labels
splot 'datafile using 1:2:3:4 with labels
@end example
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.
@example
set xtics
plot 'datafile' using 3:4:xticlabels(1) with linespoints
@end example
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:
@example
plot 'datafile' using 1:(f($2)/$4) title 2 with lines
@end example
This option must come immediately after the 'using' clause, if any. E.g.:
@example
plot 'datafile' title 2 linetype 5 # OK
plot 'datafile' using 1:2 title 2 linetype 5 # OK
plot 'datafile' using 1:2 linetype 5 title "FOO" # OK
plot 'datafile' using 1:2 linetype 5 title 2 # fails
@end example
See @ref{labels}, `using xticlabels`, @ref{title}, @ref{using}.
@node Enhanced_text_mode, Environment, Datastrings, gnuplot
@section Enhanced text mode
@c ?enhanced text
@cindex enhanced
Many terminal types support an enhanced text mode in which additional
formatting information is embedded in the text string. For example, "x^2"
will write x-squared as we are used to seeing it, with a superscript 2.
This mode is normally selected when you set the terminal, e.g.
"set term png enhanced", but may also be toggled afterward using
"set termoption enhanced", or by marking individual strings as in
"set label 'x_2' noenhanced".
@example
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 example
Braces can be used to place multiple-character text where a single character
is expected (e.g., 2^@{10@}). To change the font and/or size, use the full form:
@{/[fontname][=fontsize | *fontscale] text@}. Thus @{/Symbol=20 G@} is a 20 pt
GAMMA and @{/*0.75 K@} is a K at three-quarters of whatever fontsize is currently
in effect. (The '/' character MUST be the first character after the '@{'.)
The phantom box is useful for a@@^b_c to align superscripts and subscripts
but does not work well for overwriting an accent on a letter. For the latter,
it is much better to use an encoding (e.g. iso_8859_1 or utf8) that contains
a large variety of letters with accents or other diacritical marks. See
@ref{encoding}. Since the box is non-spacing, it is sensible to put the shorter
of the subscript or superscript in the box (that is, after the @@).
Space equal in length to a string can be inserted using the '&' character.
Thus
@example
'abc&@{def@}ghi'
@end example
would produce
@example
'abc ghi'.
@end example
The '~' character causes the next character or bracketed text to be
overprinted by the following character or bracketed text. The second text
will be horizontally centered on the first. Thus '~a/' will result in an 'a'
with a slash through it. You can also shift the second text vertically by
preceding the second text with a number, which will define the fraction of the
current fontsize by which the text will be raised or lowered. In this case
the number and text must be enclosed in brackets because more than one
character is necessary. If the overprinted text begins with a number, put a
space between the vertical offset and the text ('~@{abc@}@{.5 000@}'); otherwise
no space is needed ('~@{abc@}@{.5---@}'). You can change the font for one or
both strings ('~a@{.5 /*.2 o@}'---an 'a' with a one-fifth-size 'o' on top---and
the space between the number and the slash is necessary), but you can't
change it after the beginning of the string. Neither can you use any other
special syntax within either string. You can, of course, use control
characters by escaping them (see below), such as '~a@{\^@}'
You can access special symbols numerically by specifying \character-code (in
octal), e.g., @{/Symbol \245@} is the symbol for infinity. This does not work
for multibyte encodings like UTF-8, however. In a UTF-8 environment, you
should be able to enter multibyte sequences implicitly by typing or otherwise
selecting the character you want.
You can escape control characters using \, e.g., \\, \@{, and so on.
But be aware that strings in double-quotes are parsed differently than those
enclosed in single-quotes. The major difference is that backslashes may need
to be doubled when in double-quoted strings.
Examples (these are hard to describe in words---try them!):
@example
set xlabel 'Time (10^6 @{/Symbol m@}s)'
set title '@{/Symbol=18 \\362@@_@{/=9.6 0@}^@{/=12 x@}@} \\
@{/Helvetica e^@{-@{/Symbol m@}^2/2@} d@}@{/Symbol m@}'
@end example
The file "ps_guide.ps" in the /docs/psdoc subdirectory of the gnuplot source
distribution contains more examples of the enhanced syntax.
@node Environment, Expressions, Enhanced_text_mode, gnuplot
@section Environment
@cindex environment
A number of shell environment variables are understood by `gnuplot`. None of
these are required, but may be useful.
If GNUTERM is defined, it is used as the name of the terminal type to be
used. This overrides any terminal type sensed by `gnuplot` on start-up, but
is itself overridden by the .gnuplot (or equivalent) start-up file
(see `start-up`) and, of course, by later explicit changes.
GNUHELP may be defined to be the pathname of the HELP file (gnuplot.gih).
On VMS, the logical name GNUPLOT$HELP should be defined as the name of the
help library for `gnuplot`. The `gnuplot` help can be put inside any system
help library, allowing access to help from both within and outside `gnuplot`
if desired.
On Unix, HOME is used as the name of a directory to search for a .gnuplot
file if none is found in the current directory. On AmigaOS,
MS-DOS, Windows and OS/2, GNUPLOT is used. On Windows, the NT-specific
variable USERPROFILE is tried, too. VMS, SYS$LOGIN: is used. Type `help
start-up`.
On Unix, PAGER is used as an output filter for help messages.
On Unix and AmigaOS, SHELL is used for the @ref{shell} command. On
MS-DOS and OS/2, COMSPEC is used for the @ref{shell} command.
FIT_SCRIPT may be used to specify a `gnuplot` command to be executed when a
fit is interrupted---see @ref{fit}. FIT_LOG specifies the default filename of the
logfile maintained by fit.
GNUPLOT_LIB may be used to define additional search directories for data
and command files. The variable may contain a single directory name, or
a list of directories separated by a platform-specific path separator,
eg. ':' on Unix, or ';' on DOS/Windows/OS/2/Amiga platforms. The contents
of GNUPLOT_LIB are appended to the @ref{loadpath} variable, but not saved
with the @ref{save} and `save set` commands.
Several gnuplot terminal drivers access TrueType fonts via the gd library.
For these drivers the font search path is controlled by the environmental
variable GDFONTPATH. Furthermore, a default font for these drivers may be
set via the environmental variable GNUPLOT_DEFAULT_GDFONT.
The postscript terminal uses its own font search path. It is controlled by
the environmental variable GNUPLOT_FONTPATH. The format is the same as for
GNUPLOT_LIB. The contents of GNUPLOT_FONTPATH are appended to the @ref{fontpath}
variable, but not saved with the @ref{save} and `save set` commands.
GNUPLOT_PS_DIR is used by the postscript driver to use external prologue
files. Depending on the build process, gnuplot contains either a builtin
copy of those files or simply a default hardcoded path. Use this variable
to test the postscript terminal with custom prologue files. See
`postscript prologue`.
@node Expressions, Glossary, Environment, gnuplot
@section Expressions
@cindex expressions
In general, any mathematical expression accepted by C, FORTRAN, Pascal, or
BASIC is valid. The precedence of these operators is determined by the
specifications of the C programming language. White space (spaces and tabs)
is ignored inside expressions.
Complex constants are expressed as @{,@}, where and
must be numerical constants. For example, @{3,2@} represents 3 + 2i; @{0,1@}
represents 'i' itself. The curly braces are explicitly required here.
@cindex division
Note that gnuplot uses both "real" and "integer" arithmetic, like FORTRAN and
C. Integers are entered as "1", "-10", etc; reals as "1.0", "-10.0", "1e1",
3.5e-1, etc. The most important difference between the two forms is in
division: division of integers truncates: 5/2 = 2; division of reals does
not: 5.0/2.0 = 2.5. In mixed expressions, integers are "promoted" to reals
before evaluation: 5/2e0 = 2.5. The result of division of a negative integer
by a positive one may vary among compilers. Try a test like "print -5/2" to
determine if your system chooses -2 or -3 as the answer.
The integer expression "1/0" may be used to generate an "undefined" flag,
which causes a point to ignored; the `ternary` operator gives an example.
Or you can use the pre-defined variable NaN to achieve the same result.
@cindex NaN
The real and imaginary parts of complex expressions are always real, whatever
the form in which they are entered: in @{3,2@} the "3" and "2" are reals, not
integers.
Gnuplot can also perform simple operations on strings and string variables.
For example, the expression ("A" . "B" eq "AB") evaluates as true, illustrating
the string concatenation operator and the string equality operator.
A string which contains a numerical value is promoted to the corresponding
integer or real value if used in a numerical expression. Thus ("3" + "4" == 7)
and (6.78 == "6.78") both evaluate to true. An integer, but not a real or
complex value, is promoted to a string if used in string concatenation.
A typical case is the use of integers to construct file names or other strings;
e.g. ("file" . 4 eq "file4") is true.
Substrings can be specified using a postfixed range descriptor [beg:end].
For example, "ABCDEF"[3:4] == "CD" and "ABCDEF"[4:*] == "DEF"
The syntax "string"[beg:end] is exactly equivalent to calling the built-in
string-valued function substr("string",beg,end), except that you cannot
omit either beg or end from the function call.
@menu
* Functions::
* Operators::
* Gnuplot-defined_variables::
* User-defined_variables_and_functions::
@end menu
@node Functions, Operators, Expressions, Expressions
@subsection Functions
@c ?expressions functions
@cindex functions
@opindex functions
The functions in `gnuplot` are the same as the corresponding functions in
the Unix math library, except that all functions accept integer, real, and
complex arguments, unless otherwise noted.
For those functions that accept or return angles that may be given in either
degrees or radians (sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
atan2(x) and arg(z)), the unit may be selected by @ref{angles}, which
defaults to radians.
@menu
* abs::
* acos::
* acosh::
* arg::
* asin::
* asinh::
* atan::
* atan2::
* atanh::
* EllipticK::
* EllipticE::
* EllipticPi::
* besj0::
* besj1::
* besy0::
* besy1::
* ceil::
* cos::
* cosh::
* erf::
* erfc::
* exp::
* floor::
* gamma::
* ibeta::
* inverf::
* igamma::
* imag::
* invnorm::
* int::
* lambertw::
* lgamma::
* log::
* log10::
* norm::
* rand::
* real::
* sgn::
* sin::
* sinh::
* sqrt::
* tan::
* tanh::
* gprintf::
* sprintf::
* strlen::
* strstrt::
* substr::
* strftime::
* strptime::
* system::
* word::
* words::
* column::
* defined::
* exists::
* stringcolumn::
* timecolumn::
* tm_hour::
* tm_mday::
* tm_min::
* tm_mon::
* tm_sec::
* tm_wday::
* tm_yday::
* tm_year::
* valid::
* elliptic_integrals::
* Random_number_generator::
@end menu
@node abs, acos, Functions, Functions
@subsubsection abs
@c ?expressions functions abs
@c ?functions abs
@cindex abs
@findex abs
The `abs(x)` function returns the absolute value of its argument. The
returned value is of the same type as the argument.
For complex arguments, abs(x) is defined as the length of x in the complex
plane [i.e., sqrt(real(x)**2 + imag(x)**2) ].
@node acos, acosh, abs, Functions
@subsubsection acos
@c ?expressions functions acos
@c ?functions acos
@cindex acos
@findex acos
The `acos(x)` function returns the arc cosine (inverse cosine) of its
argument. `acos` returns its argument in radians or degrees, as selected by
@ref{angles}.
@node acosh, arg, acos, Functions
@subsubsection acosh
@c ?expressions functions acosh
@c ?functions acosh
@cindex acosh
@findex acosh
The `acosh(x)` function returns the inverse hyperbolic cosine of its argument
in radians.
@node arg, asin, acosh, Functions
@subsubsection arg
@c ?expressions functions arg
@c ?functions arg
@cindex arg
@findex arg
The `arg(x)` function returns the phase of a complex number in radians or
degrees, as selected by @ref{angles}.
@node asin, asinh, arg, Functions
@subsubsection asin
@c ?expressions functions asin
@c ?functions asin
@cindex asin
@findex asin
The `asin(x)` function returns the arc sin (inverse sin) of its argument.
`asin` returns its argument in radians or degrees, as selected by @ref{angles}.
@node asinh, atan, asin, Functions
@subsubsection asinh
@c ?expressions functions asinh
@c ?functions asinh
@cindex asinh
@findex asinh
The `asinh(x)` function returns the inverse hyperbolic sin of its argument in
radians.
@node atan, atan2, asinh, Functions
@subsubsection atan
@c ?expressions functions atan
@c ?functions atan
@cindex atan
@findex atan
The `atan(x)` function returns the arc tangent (inverse tangent) of its
argument. `atan` returns its argument in radians or degrees, as selected by
@ref{angles}.
@node atan2, atanh, atan, Functions
@subsubsection atan2
@c ?expressions functions atan2
@c ?functions atan2
@cindex atan2
@findex atan2
The `atan2(y,x)` function returns the arc tangent (inverse tangent) of the
ratio of the real parts of its arguments. @ref{atan2} returns its argument in
radians or degrees, as selected by @ref{angles}, in the correct quadrant.
@node atanh, EllipticK, atan2, Functions
@subsubsection atanh
@c ?expressions functions atanh
@c ?functions atanh
@cindex atanh
@findex atanh
The `atanh(x)` function returns the inverse hyperbolic tangent of its
argument in radians.
@node EllipticK, EllipticE, atanh, Functions
@subsubsection EllipticK
See `elliptic integrals`.
@node EllipticE, EllipticPi, EllipticK, Functions
@subsubsection EllipticE
See `elliptic integrals`.
@node EllipticPi, besj0, EllipticE, Functions
@subsubsection EllipticPi
See `elliptic integrals`.
@node besj0, besj1, EllipticPi, Functions
@subsubsection besj0
@c ?expressions functions besj0
@c ?functions besj0
@cindex besj0
@findex besj0
The `besj0(x)` function returns the j0th Bessel function of its argument.
@ref{besj0} expects its argument to be in radians.
@node besj1, besy0, besj0, Functions
@subsubsection besj1
@c ?expressions functions besj1
@c ?functions besj1
@cindex besj1
@findex besj1
The `besj1(x)` function returns the j1st Bessel function of its argument.
@ref{besj1} expects its argument to be in radians.
@node besy0, besy1, besj1, Functions
@subsubsection besy0
@c ?expressions functions besy0
@c ?functions besy0
@cindex besy0
@findex besy0
The `besy0(x)` function returns the y0th Bessel function of its argument.
@ref{besy0} expects its argument to be in radians.
@node besy1, ceil, besy0, Functions
@subsubsection besy1
@c ?expressions functions besy1
@c ?functions besy1
@cindex besy1
@findex besy1
The `besy1(x)` function returns the y1st Bessel function of its argument.
@ref{besy1} expects its argument to be in radians.
@node ceil, cos, besy1, Functions
@subsubsection ceil
@c ?expressions functions ceil
@c ?functions ceil
@cindex ceil
@findex ceil
The `ceil(x)` function returns the smallest integer that is not less than its
argument. For complex numbers, @ref{ceil} returns the smallest integer not less
than the real part of its argument.
@node cos, cosh, ceil, Functions
@subsubsection cos
@c ?expressions functions cos
@c ?functions cos
@cindex cos
@findex cos
The `cos(x)` function returns the cosine of its argument. `cos` accepts its
argument in radians or degrees, as selected by @ref{angles}.
@node cosh, erf, cos, Functions
@subsubsection cosh
@c ?expressions functions cosh
@c ?functions cosh
@cindex cosh
@findex cosh
The `cosh(x)` function returns the hyperbolic cosine of its argument. @ref{cosh}
expects its argument to be in radians.
@node erf, erfc, cosh, Functions
@subsubsection erf
@c ?expressions functions erf
@c ?functions erf
@cindex erf
@findex erf
The `erf(x)` function returns the error function of the real part of its
argument. If the argument is a complex value, the imaginary component is
ignored. See @ref{erfc}, @ref{inverf}, and @ref{norm}.
@node erfc, exp, erf, Functions
@subsubsection erfc
@c ?expressions functions erfc
@c ?functions erfc
@cindex erfc
@findex erfc
The `erfc(x)` function returns 1.0 - the error function of the real part of
its argument. If the argument is a complex value, the imaginary component is
ignored. See `erf`, @ref{inverf}, and @ref{norm}.
@node exp, floor, erfc, Functions
@subsubsection exp
@c ?expressions functions exp
@c ?functions exp
@cindex exp
@findex exp
The `exp(x)` function returns the exponential function of its argument (`e`
raised to the power of its argument). On some implementations (notably
suns), exp(-x) returns undefined for very large x. A user-defined function
like safe(x) = x 0 and x in [0:1]. If the arguments are
complex, the imaginary components are ignored.
@node inverf, igamma, ibeta, Functions
@subsubsection inverf
@c ?expressions functions inverf
@c ?functions inverf
@cindex inverf
@findex inverf
The `inverf(x)` function returns the inverse error function of the real part
of its argument. See `erf` and @ref{invnorm}.
@node igamma, imag, inverf, Functions
@subsubsection igamma
@c ?expressions functions igamma
@c ?functions igamma
@cindex igamma
@findex igamma
The `igamma(a,x)` function returns the normalized incomplete gamma
function of the real parts of its arguments, where a > 0 and x >= 0.
The standard notation is P(a,x), e.g. Abramowitz and Stegun (6.5.1),
with limiting value of 1 as x approaches infinity. If the arguments
are complex, the imaginary components are ignored.
@node imag, invnorm, igamma, Functions
@subsubsection imag
@c ?expressions functions imag
@c ?functions imag
@cindex imag
@findex imag
The `imag(x)` function returns the imaginary part of its argument as a real
number.
@node invnorm, int, imag, Functions
@subsubsection invnorm
@c ?expressions functions invnorm
@c ?functions invnorm
@cindex invnorm
@findex invnorm
The `invnorm(x)` function returns the inverse cumulative normal (Gaussian)
distribution function of the real part of its argument. See @ref{norm}.
@node int, lambertw, invnorm, Functions
@subsubsection int
@c ?expressions functions int
@c ?functions int
@cindex int
@findex int
The `int(x)` function returns the integer part of its argument, truncated
toward zero.
@node lambertw, lgamma, int, Functions
@subsubsection lambertw
@c ?expressions functions lambertw
@c ?functions lambertw
@cindex lambertw
@findex lambertw
The lambertw function returns the value of the principal branch of
Lambert's W function, which is defined by the equation (W(z)*exp(W(z))=z.
z must be a real number with z >= -exp(-1).
@node lgamma, log, lambertw, Functions
@subsubsection lgamma
@c ?expressions functions lgamma
@c ?functions lgamma
@cindex lgamma
@findex lgamma
The `lgamma(x)` function returns the natural logarithm of the gamma function
of the real part of its argument. If the argument is a complex value, the
imaginary component is ignored.
@node log, log10, lgamma, Functions
@subsubsection log
@c ?expressions functions log
@c ?functions log
@cindex log
@findex log
The `log(x)` function returns the natural logarithm (base `e`) of its
argument. See @ref{log10}.
@node log10, norm, log, Functions
@subsubsection log10
@c ?expressions functions log10
@c ?functions log10
@cindex log10
@findex log10
The `log10(x)` function returns the logarithm (base 10) of its argument.
@node norm, rand, log10, Functions
@subsubsection norm
@c ?expressions functions norm
@c ?functions norm
@cindex norm
@findex norm
The `norm(x)` function returns the cumulative normal (Gaussian) distribution
function of the real part of its argument. See @ref{invnorm}, `erf` and @ref{erfc}.
@node rand, real, norm, Functions
@subsubsection rand
@c ?expressions functions rand
@c ?functions rand
@cindex rand
@findex rand
`rand(0)` returns a pseudo random number in the interval [0:1] generated
@example
from the current value of two internal 32-bit seeds.
@end example
`rand(-1)` resets both seeds to a standard value.
`rand(x)` for x>0 sets both seeds to a value based on the value of x.
`rand(@{x,y@})` for x>0 sets seed1 to x and seed2 to y.
@node real, sgn, rand, Functions
@subsubsection real
@c ?expressions functions real
@c ?functions real
@cindex real
@findex real
The `real(x)` function returns the real part of its argument.
@node sgn, sin, real, Functions
@subsubsection sgn
@c ?expressions functions sgn
@c ?functions sgn
@cindex sgn
@findex sgn
The `sgn(x)` function returns 1 if its argument is positive, -1 if its
argument is negative, and 0 if its argument is 0. If the argument is a
complex value, the imaginary component is ignored.
@node sin, sinh, sgn, Functions
@subsubsection sin
@c ?expressions functions sin
@c ?functions sin
@cindex sin
@findex sin
The `sin(x)` function returns the sine of its argument. `sin` expects its
argument to be in radians or degrees, as selected by @ref{angles}.
@node sinh, sqrt, sin, Functions
@subsubsection sinh
@c ?expressions functions sinh
@c ?functions sinh
@cindex sinh
@findex sinh
The `sinh(x)` function returns the hyperbolic sine of its argument. @ref{sinh}
expects its argument to be in radians.
@node sqrt, tan, sinh, Functions
@subsubsection sqrt
@c ?expressions functions sqrt
@c ?functions sqrt
@cindex sqrt
@findex sqrt
The `sqrt(x)` function returns the square root of its argument.
@node tan, tanh, sqrt, Functions
@subsubsection tan
@c ?expressions functions tan
@c ?functions tan
@cindex tan
@findex tan
The `tan(x)` function returns the tangent of its argument. `tan` expects
its argument to be in radians or degrees, as selected by @ref{angles}.
@node tanh, gprintf, tan, Functions
@subsubsection tanh
@c ?expressions functions tanh
@c ?functions tanh
@cindex tanh
@findex tanh
The `tanh(x)` function returns the hyperbolic tangent of its argument. @ref{tanh}
expects its argument to be in radians.
@node gprintf, sprintf, tanh, Functions
@subsubsection gprintf
@c ?expressions functions gprintf
@c ?functions gprintf
`gprintf("format",x)` applies gnuplot's own format specifiers to the single
variable x and returns the resulting string. If you want standard C-language
format specifiers, you must instead use `sprintf("format",x)`.
See `format specifiers`.
@node sprintf, strlen, gprintf, Functions
@subsubsection sprintf
@c ?expressions functions sprintf
@c ?functions sprintf
@cindex sprintf
@findex sprintf
`sprintf("format",var1,var2,...)` applies standard C-language format specifiers
to multiple arguments and returns the resulting string. If you want to
use gnuplot's own format specifiers, you must instead call `gprintf()`.
For information on sprintf format specifiers, please see standard C-language
documentation or the unix sprintf man page.
@node strlen, strstrt, sprintf, Functions
@subsubsection strlen
@c ?expressions functions strlen
@c ?functions strlen
@cindex strlen
@findex strlen
`strlen("string")` returns the number of characters in the string.
@node strstrt, substr, strlen, Functions
@subsubsection strstrt
@c ?expressions functions strstrt
@c ?functions strstrt
@cindex strstrt
@findex strstrt
`strstrt("string","key")` searches for the character string "key" in "string"
and returns the index to the first character of "key". If "key" is not found,
returns 0. Similar to C library function strstr except that it returns an
index rather than a string pointer. strstrt("hayneedlestack","needle") = 4.
@node substr, strftime, strstrt, Functions
@subsubsection substr
@c ?expressions functions substr
@c ?functions substr
@cindex substr
@findex substr
@cindex substring
`substr("string",beg,end)` returns the substring consisting of characters
beg through end of the original string. This is exactly equivalent to the
expression "string"[beg:end] except that you do not have the option of
omitting beg or end.
@node strftime, strptime, substr, Functions
@subsubsection strftime
@c ?expressions functions strftime
@c ?functions strftime
@cindex strftime
@findex strftime
`strftime("timeformat",t)` applies the timeformat specifiers to the time t
given in seconds since the year 2000.
See `time_specifiers` and @ref{strptime}.
@node strptime, system, strftime, Functions
@subsubsection strptime
@c ?expressions functions strptime
@c ?functions strptime
@cindex strptime
@findex strptime
`strptime("timeformat",s)` reads the time from the string s using the
timeformat specifiers and converts it into seconds since the year 2000.
See `time_specifiers` and @ref{strftime}.
@node system, word, strptime, Functions
@subsubsection system
@c ?expressions functions system
@c ?functions system
@cindex system
@cmindex system
`system("command")` executes "command" using the standard shell and returns
the resulting character stream from stdout as string variable.
One optional trailing newline is ignored.
This can be used to import external functions into gnuplot scripts using
'f(x) = real(system(sprintf("somecommand %f", x)))'.
@node word, words, system, Functions
@subsubsection word
@c ?expressions functions word
@c ?functions word
@cindex word
@findex word
@cindex word
@findex word
`word("string",n)` returns the nth word in string. For example,
`word("one two three",2)` returns the string "two".
@node words, column, word, Functions
@subsubsection words
@c ?expressions functions words
@c ?functions words
@cindex words
@findex words
@cindex words
@findex words
`words("string")` returns the number of words in string. For example,
`words(" a b c d")` returns the 4.
@node column, defined, words, Functions
@subsubsection column
@c ?expressions functions column
@c ?functions column
@cindex column
@findex column
`column(x)` may be used only in expressions as part of @ref{using} manipulations
to fits or datafile plots. It evaluates to the numerical value of the contents
of column x. See @ref{using}.
@node defined, exists, column, Functions
@subsubsection defined
@c ?expressions functions defined
@c ?functions defined
@cindex defined
@findex defined
`defined(X)` [DEPRECATED] returns 1 if a variable named X has been defined, otherwise
it returns 0.
@node exists, stringcolumn, defined, Functions
@subsubsection exists
@c ?expressions functions exists
@c ?functions exists
@cindex exists
@findex exists
The argument to exists() is a string constant or a string variable;
if the string contains the name of a defined variable, the function returns 1.
Otherwise the function returns 0.
@node stringcolumn, timecolumn, exists, Functions
@subsubsection stringcolumn
@c ?expressions functions stringcolumn
@c ?functions stringcolumn
@cindex stringcolumn
@findex stringcolumn
@c ?expressions functions strcol
@c ?functions strcol
@cindex strcol
`stringcolumn(x)` may be used only in expressions as part of @ref{using} manipulations
to fits or datafile plots. It returns the content of column x as a string variable.
See @ref{using}.
@node timecolumn, tm_hour, stringcolumn, Functions
@subsubsection timecolumn
@c ?expressions functions timecolumn
@c ?functions timecolumn
@cindex timecolumn
@findex timecolumn
`timecolumn(x)` may be used only in expressions as part of @ref{using}
manipulations to fits or datafile plots. See @ref{using}.
It reads the data starting at that column as a time/date value and
returns its value in gnuplot's internal time representation of
"seconds since the millennium".
To find the right @ref{timefmt} string to use, @ref{timecolumn} searches for a
@ref{using} specification with the same column number as its argument.
If one is found, @ref{timefmt} pattern of the target axis for this specifier
is used. Otherwise, @ref{timecolumn} chooses the x axis @ref{timefmt} per default.
@node tm_hour, tm_mday, timecolumn, Functions
@subsubsection tm_hour
@c ?expressions tm_hour
@findex tm_hour
@c ?functions tm_hour
@cindex tm_hour
@findex tm_hour
The @ref{tm_hour} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the hour (an integer in the range 0--23) as a real.
@node tm_mday, tm_min, tm_hour, Functions
@subsubsection tm_mday
@c ?expressions tm_mday
@findex tm_mday
@c ?functions tm_mday
@cindex tm_mday
@findex tm_mday
The @ref{tm_mday} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the day of the month (an integer in the range 1--31)
as a real.
@node tm_min, tm_mon, tm_mday, Functions
@subsubsection tm_min
@c ?expressions tm_min
@findex tm_min
@c ?functions tm_min
@cindex tm_min
@findex tm_min
The @ref{tm_min} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the minute (an integer in the range 0--59) as a real.
@node tm_mon, tm_sec, tm_min, Functions
@subsubsection tm_mon
@c ?expressions tm_mon
@findex tm_mon
@c ?functions tm_mon
@cindex tm_mon
@findex tm_mon
The @ref{tm_mon} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the month (an integer in the range 0--11) as a real.
@node tm_sec, tm_wday, tm_mon, Functions
@subsubsection tm_sec
@c ?expressions tm_sec
@findex tm_sec
@c ?functions tm_sec
@cindex tm_sec
@findex tm_sec
The @ref{tm_sec} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the second (an integer in the range 0--59) as a real.
@node tm_wday, tm_yday, tm_sec, Functions
@subsubsection tm_wday
@c ?expressions tm_wday
@findex tm_wday
@c ?functions tm_wday
@cindex tm_wday
@findex tm_wday
The @ref{tm_wday} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the day of the week (an integer in the range 0--6) as
a real.
@node tm_yday, tm_year, tm_wday, Functions
@subsubsection tm_yday
@c ?expressions tm_yday
@findex tm_yday
@c ?functions tm_yday
@cindex tm_yday
@findex tm_yday
The @ref{tm_yday} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the day of the year (an integer in the range 1--366)
as a real.
@node tm_year, valid, tm_yday, Functions
@subsubsection tm_year
@c ?expressions tm_year
@findex tm_year
@c ?functions tm_year
@cindex tm_year
@findex tm_year
The @ref{tm_year} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the year (an integer) as a real.
@node valid, elliptic_integrals, tm_year, Functions
@subsubsection valid
@c ?expressions functions valid
@c ?functions valid
@cindex valid
@findex valid
`valid(x)` may be used only in expressions as part of @ref{using} manipulations
to fits or datafile plots. See @ref{using}.
@node elliptic_integrals, Random_number_generator, valid, Functions
@subsubsection elliptic integrals
@c ?expressions functions elliptic integrals
@c ?functions elliptic integrals
@c ?elliptic integrals
@cindex elliptic integrals
@findex elliptic integrals
The `EllipticK(k)` function returns the complete elliptic integral of the first
kind, i.e. the definite integral between 0 and pi/2 of the function
`(1-(k*sin(p))**2)**(-0.5)`. The domain of `k` is -1 to 1 (exclusive).
The `EllipticE(k)` function returns the complete elliptic integral of the
second kind, i.e. the definite integral between 0 and pi/2 of the function
`(1-(k*sin(p))**2)**0.5`. The domain of `k` is -1 to 1 (inclusive).
The `EllipticPi(n,k)` function returns the complete elliptic integral of the
third kind, i.e. the definite integral between 0 and pi/2 of the function
`(1-(k*sin(p))**2)**(-0.5)/(1-n*sin(p)**2)`. The parameter `n` must be less
than 1, while `k` must lie between -1 and 1 (exclusive). Note that by
definition EllipticPi(0,k) == EllipticK(k) for all possible values of `k`.
@node Random_number_generator, , elliptic_integrals, Functions
@subsubsection Random number generator
@c ?expressions random
@c ?functions random
@cindex random
Some older versions of gnuplot used rand(x>0) to produce sequential
pseudo-random numbers. The current behavior is as follows:
@example
`rand(0)` returns a pseudo random number in the interval [0:1] generated
from the current value of two internal 32-bit seeds.
`rand(-1)` resets both seeds to a standard value.
`rand(x)` for x>0 sets both seeds to a value based on the value of x.
`rand(@{x,y@})` for x>0 sets seed1 to x and seed2 to y.
@end example
@node Operators, Gnuplot-defined_variables, Functions, Expressions
@subsection Operators
@c ?expressions operators
@cindex operators
The operators in `gnuplot` are the same as the corresponding operators in the
C programming language, except that all operators accept integer, real, and
complex arguments, unless otherwise noted. The ** operator (exponentiation)
is supported, as in FORTRAN.
Parentheses may be used to change order of evaluation.
@menu
* Unary::
* Binary::
* Ternary::
@end menu
@node Unary, Binary, Operators, Operators
@subsubsection Unary
@c ?expressions operators unary
@c ?operators unary
@cindex unary
The following is a list of all the unary operators and their usages:
@example
Symbol Example Explanation
- -a unary minus
+ +a unary plus (no-operation)
~ ~a * one's complement
! !a * logical negation
! a! * factorial
$ $3 * call arg/column during @ref{using} manipulation
@end example
@cindex factorial
@cindex negation
@cindex one's complement
@cindex operator precedence
(*) Starred explanations indicate that the operator requires an integer
argument.
Operator precedence is the same as in Fortran and C. As in those languages,
parentheses may be used to change the order of operation. Thus -2**2 = -4,
but (-2)**2 = 4.
The factorial operator returns a real number to allow a greater range.
@node Binary, Ternary, Unary, Operators
@subsubsection Binary
@c ?expressions operators binary
@c ?operators binary
The following is a list of all the binary operators and their usages:
@example
Symbol Example Explanation
** a**b exponentiation
* a*b multiplication
/ a/b division
% a%b * modulo
+ a+b addition
- a-b subtraction
== a==b equality
!= a!=b inequality
< a= a>=b greater than or equal to
& a&b * bitwise AND
^ a^b * bitwise exclusive OR
| a|b * bitwise inclusive OR
&& a&&b * logical AND
|| a||b * logical OR
= a = b assignment
, (a,b) serial evaluation
. A.B string concatenation
eq A eq B string equality
ne A ne B string inequality
@end example
@cindex bitwise operators
@cindex string operators
@cindex modulo
@cindex exponentiation
(*) Starred explanations indicate that the operator requires integer
arguments.
Capital letters A and B indicate that the operator requires string arguments.
Logical AND (&&) and OR (||) short-circuit the way they do in C. That is,
the second `&&` operand is not evaluated if the first is false; the second
`||` operand is not evaluated if the first is true.
Serial evaluation occurs only in parentheses and is guaranteed to proceed
in left to right order. The value of the rightmost subexpression is returned.
@node Ternary, , Binary, Operators
@subsubsection Ternary
@c ?expressions operators ternary
@c ?operators ternary
@cindex ternary
There is a single ternary operator:
@example
Symbol Example Explanation
?: a?b:c ternary operation
@end example
The ternary operator behaves as it does in C. The first argument (a), which
must be an integer, is evaluated. If it is true (non-zero), the second
argument (b) is evaluated and returned; otherwise the third argument (c) is
evaluated and returned.
The ternary operator is very useful both in constructing piecewise functions
and in plotting points only when certain conditions are met.
Examples:
Plot a function that is to equal sin(x) for 0 >diary.gp" # write 5 history commands using pipe
history ?load # show all history entries starting with "load"
history ?"set c" # like above, several words enclosed in quotes
hi !reread # execute last entry starting with "reread"
hist !"set xr" # like above, several words enclosed in quotes
hi !hi # guess yourself :-))
@end example
On systems which support a popen function (Unix), the output of history can be
piped through an external program by starting the file name with a '|', as one
of the above examples demonstrates.
@node if, iteration, history, Commands
@section if
@c ?commands if
@cindex if
@cmindex if
The @ref{if} command allows commands to be executed conditionally.
Syntax:
@example
if () [; else if () ...; else ...]
@end example
will be evaluated. If it is true (non-zero), then the command(s)
of the will be executed. If is false (zero), then
the entire is ignored until the next occurrence of `else`.
Note that use of `;` to allow multiple commands on the same line will
_not_ end the conditionalized commands.
Examples:
@example
pi=3
if (pi!=acos(-1)) print "?Fixing pi!"; pi=acos(-1); print pi
@end example
will display:
@example
?Fixing pi!
3.14159265358979
@end example
but
@example
if (1==2) print "Never see this"; print "Or this either"
@end example
will not display anything.
else:
@example
v=0
v=v+1; if (v%2) print "2" ; else if (v%3) print "3"; else print "fred"
@end example
(repeat the last line repeatedly!)
See @ref{reread} for an example of how @ref{if} and @ref{reread} can be used together to
perform a loop.
@node iteration, load, if, Commands
@section iteration
@cindex iteration
@cmindex iteration
The `plot`, `splot`, `set` and @ref{unset} commands may optionally contain an
iteration clause. This has the effect of executing the basic command
multiple times, each time re-evaluating any expressions that make use of the
iteration control variable. Two forms of iteration clause are currently
supported:
@example
for [intvar = start:end@{:increment@}]
for [stringvar in "A B C D"]
@end example
Examples:
@example
plot for [filename in "A.dat B.dat C.dat"] filename using 1:2 with lines
plot for [basename in "A B C"] basename.".dat" using 1:2 with lines
set for [i = 1:10] style line i lc rgb "blue"
unset for [tag = 100:200] label tag
@end example
See additional documentation for @ref{iteration}.
@node load, lower, iteration, Commands
@section load
@c ?commands load
@cindex load
@cmindex load
The `load` command executes each line of the specified input file as if it
had been typed in interactively. Files created by the @ref{save} command can
later be `load`ed. Any text file containing valid commands can be created
and then executed by the `load` command. Files being `load`ed may themselves
contain `load` or @ref{call} commands. See `comments` for information about
comments in commands. To `load` with arguments, see @ref{call}.
Syntax:
@example
load ""
@end example
The name of the input file must be enclosed in quotes.
The special filename "-" may be used to `load` commands from standard input.
This allows a `gnuplot` command file to accept some commands from standard
input. Please see help for `batch/interactive` for more details.
On some systems which support a popen function (Unix), the load file can be
read from a pipe by starting the file name with a '10 ? $2 : 1/0)
@end example
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.
@cindex NaN
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 @ref{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
@example
plot 'file' using 1:2
@end example
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.
@c ^ See also the web page
@uref{http://www.gnuplot.info/demo/using.html,Feeble using demos.
}
@noindent --- PSEUDOCOLUMNS ---
@cindex pseudocolumns
@c ?commands plot datafile using pseudocolumns
@c ?plot datafile using pseudocolumns
@c ?datafile using pseudocolumns
@c ?using pseudocolumns
Expressions in the @ref{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".
@example
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 @ref{index}.
@end example
@noindent --- USING TITLE ---
@c ?using title
@c ?plot using title
The first entry of a column of the input data file can be used as a string
to provide the plot title in the key box. The column containing specified
is independent of the column[s] used for the plot itself.
@example
plot 'data' using 1:($2/$3) title column(N)
@end example
In this case the entry in the first row of column N will be used for the
key entry of the plot constructed from dividing column 2 by column 3.
The entry in the first row of columns 2 and 3 will be ignored.
@noindent --- XTICLABELS ---
@cindex xticlabels
@c ?using xticlabels
@c ?plot using xticlabels
A column of the input data file can be used to label axis tic marks.
The format of such a plot command is
@example
plot 'datafile' using ::xticlabels() with
@end example
Tic labels may be read for any of the plot axes: x x2 y y2 z.
The `ticlabels()` specifiers must come after all of the data
coordinate specifiers in the @ref{using} portion of the command.
For each data point which has a valid set of X,Y[,Z] coordinates,
the text field found in column 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()`.
Example:
@example
splot "data" using 2:4:6:xtic(1):ytic(3):ztic(6)
@end example
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.
@noindent --- X2TICLABELS ---
@c ?using x2ticlabels
@c ?plot using x2ticlabels
See `plot using xticlabels`.
@noindent --- YTICLABELS ---
@c ?using yticlabels
@c ?plot using yticlabels
See `plot using xticlabels`.
@noindent --- Y2TICLABELS ---
@c ?using y2ticlabels
@c ?plot using y2ticlabels
See `plot using xticlabels`.
@noindent --- ZTICLABELS ---
@c ?using zticlabels
@c ?plot using zticlabels
See `plot using xticlabels`.
@node errorbars, errorlines, data, plot
@subsection errorbars
@c ?commands plot errorbars
@c ?commands splot errorbars
@c ?plot errorbars
@c ?splot errorbars
@cindex errorbars
Error bars are supported for 2D data file plots by reading one to four
additional columns (or @ref{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
@example
(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).
@end example
The x coordinate must be specified. The order of the numbers must be
exactly as given above, though the @ref{using} qualifier can manipulate the order
and provide values for missing columns. For example,
@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
@end example
The last example is for a file containing an unsupported combination of
relative x and absolute y errors. The @ref{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 @ref{errorlines}).
The error bars have crossbars at each end unless @ref{bars} is used
(see @ref{bars} for details).
If autoscaling is on, the ranges will be adjusted to include the error bars.
See also
@uref{http://gnuplot.sourceforge.net/demo/mgr.html,errorbar demos.
}
See @ref{using}, @ref{with}, and @ref{style} for more information.
@node errorlines, parametric, errorbars, plot
@subsection errorlines
@c ?commands plot errorlines
@c ?commands splot errorlines
@c ?plot errorlines
@c ?splot errorlines
@cindex errorlines
Lines with error bars are supported for 2D data file plots by reading
one to four additional columns (or @ref{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
@example
(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).
@end example
The x coordinate must be specified. The order of the numbers must be
exactly as given above, though the @ref{using} qualifier can manipulate
the order and provide values for missing columns. For example,
@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
@end example
The last example is for a file containing an unsupported combination
of relative x and absolute y errors. The @ref{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 @ref{bars} is used
(see @ref{bars} for details).
If autoscaling is on, the ranges will be adjusted to include the error bars.
See @ref{using}, @ref{with}, and @ref{style} for more information.
@node parametric, ranges, errorlines, plot
@subsection parametric
@c ?commands plot parametric
@c ?commands splot parametric
@c ?plot parametric
@c ?splot parametric
When in parametric mode (`set parametric`) mathematical expressions must be
given in pairs for `plot` and in triplets for `splot`.
Examples:
@example
plot sin(t),t**2
splot cos(u)*cos(v),cos(u)*sin(v),sin(u)
@end example
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 @ref{with} and @ref{title}, may be specified only after the
parametric function has been completed:
@example
plot sin(t),t**2 title 'Parametric example' with linespoints
@end example
See also
@uref{http://www.gnuplot.info/demo/param.html,Parametric Mode Demos.
}
@node ranges, iteration_, parametric, plot
@subsection ranges
@c ?commands plot ranges
@c ?commands splot ranges
@c ?plot ranges
@c ?splot ranges
@cindex ranges
The optional ranges specify the region of the graph that will be displayed.
Syntax:
@example
[@{=@}@{@{@}:@{@}@}]
[@{@{@}:@{@}@}]
@end example
The first form applies to the independent variable (@ref{xrange} or @ref{trange}, if
in parametric mode). The second form applies to the dependent variable
@ref{yrange} (and @ref{xrange}, too, if in parametric mode). is a new
name for the independent variable. (The defaults may be changed with @ref{dummy}.) The optional and terms can be constant expressions or *.
In non-parametric mode, the order in which ranges must be given is @ref{xrange}
and @ref{yrange}.
In parametric mode, the order for the `plot` command is @ref{trange}, @ref{xrange},
and @ref{yrange}. The following `plot` command shows setting the @ref{trange} to
[-pi:pi], the @ref{xrange} to [-1.3:1.3] and the @ref{yrange} to [-1:1] for the
duration of the graph:
@example
plot [-pi:pi] [-1.3:1.3] [-1:1] sin(t),t**2
@end example
Note that the x2range and y2range cannot be specified here---@ref{x2range}
and @ref{y2range} must be used.
Ranges are interpreted in the order listed above for the appropriate mode.
Once all those needed are specified, no further ones must be listed, but
unneeded ones cannot be skipped---use an empty range `[]` as a placeholder.
`*` can be used to allow autoscaling of either of min and max. See also
@ref{autoscale}.
Ranges specified on the `plot` or `splot` command line affect only that
graph; use the @ref{xrange}, @ref{yrange}, etc., commands to change the
default ranges for future graphs.
With time data, you must provide the range (in the same manner as the time
appears in the datafile) within quotes. `gnuplot` uses the @ref{timefmt} string
to read the value---see @ref{timefmt}.
Examples:
This uses the current ranges:
@example
plot cos(x)
@end example
This sets the x range only:
@example
plot [-10:30] sin(pi*x)/(pi*x)
@end example
This is the same, but uses t as the dummy-variable:
@example
plot [t = -10 :30] sin(pi*t)/(pi*t)
@end example
This sets both the x and y ranges:
@example
plot [-pi:pi] [-3:3] tan(x), 1/x
@end example
This sets only the y range, and turns off autoscaling on both axes:
@example
plot [ ] [-2:sin(5)*-8] sin(x)**besj0(x)
@end example
This sets xmax and ymin only:
@example
plot [:200] [-pi:] exp(sin(x))
@end example
This sets the x range for a timeseries:
@example
set timefmt "%d/%m/%y %H:%M"
plot ["1/6/93 12:00":"5/6/93 12:00"] 'timedata.dat'
@end example
@node iteration_, title, ranges, plot
@subsection iteration
@c ?commands plot iteration
@c ?commands splot iteration
@c ?plot iteration
@c ?splot iteration
@cindex iteration
@cmindex iteration
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:
@example
plot for [ = : @{:@}]
plot for [ in "string of words"]
@end example
Examples:
@example
file(n) = sprintf("dataset_%d.dat",n)
splot for [i=1:10] file(i) title sprintf("dataset %d",i)
plot for [dataset in "apples bananas"] dataset."dat" title dataset
@end example
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. In this
example it is used both to generate a file name and a corresponding title.
Example:
@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
@end example
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:
@example
list = "apple banana cabbage daikon eggplant"
plot for [i in list] i.".dat" title i
list = "new stuff"
replot
@end example
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.
@node title, with, iteration_, plot
@subsection title
@c ?commands plot title
@c ?commands splot title
@c ?plot title
@c ?splot title
A line title for each function and data set appears in the key, accompanied
by a sample of the line and/or symbol used to represent it. It can be
changed by using the @ref{title} option.
Syntax:
@example
title "" | notitle [""]
@end example
where is the new title of the line and must be enclosed in quotes.
The quotes will not be shown in the key. A special character may be given as
a backslash followed by its octal value ("\345"). The tab character "\t" is
understood. Note that backslash processing occurs only for strings enclosed
in double quotes---use single quotes to prevent such processing. The newline
character "\n" is not processed in key entries in either type of string.
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. See `datastrings`.
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 @ref{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.
Examples:
This plots y=x with the title 'x':
@example
plot x
@end example
This plots x squared with title "x^2" and file "data.1" with title
"measured data":
@example
plot x**2 title "x^2", 'data.1' t "measured data"
@end example
This puts an untitled circular border around a polar graph:
@example
set polar; plot my_function(t), 1 notitle
@end example
@node with, , title, plot
@subsection with
@c ?commands plot with
@c ?commands splot with
@c ?commands plot style
@c ?commands splot style
@c ?plot with
@c ?plot style
@c ?splot with
@c ?splot style
@cindex style
@opindex style
@cindex with
Functions and data may be displayed in one of a large number of styles.
The @ref{with} keyword provides the means of selection.
Syntax:
@example
with @{ @{linestyle | ls @}
| @{@{linetype | lt @}
@{linewidth | lw @}
@{linecolor | lc @}
@{pointtype | pt @}
@{pointsize | ps @}
@{fill | fs @}
@{nohidden3d | nocontours@}
@{palette@}@}
@}
@end example
where is one of
@example
lines dots steps errorbars xerrorbar xyerrorlines
points impulses fsteps errorlines xerrorlines yerrorbars
linespoints labels histeps financebars xyerrorbars yerrorlines
vectors
@end example
or
@example
boxes candlesticks image circles
boxerrorbars filledcurves rgbimage
boxxyerrorbars histograms rgbalpha pm3d
@end example
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 @ref{test}.
If you wish to choose the line or point type for a single plot,
and 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 @ref{test} to display the types available for your terminal.
You may also scale the line width and point size for a plot by using
and , which are specified relative to the default
values for each terminal. The pointsize may also be altered
globally---see @ref{pointsize} for details. But note that both
as set here and as set by @ref{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 to
the index of the desired style.
If gnuplot was built with @ref{pm3d} support, the special keyword @ref{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 @ref{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 @ref{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 @ref{using} specifier.
See `colors`, @ref{palette}, `linetype`.
The keyword `nohidden3d` applies only to plots made with the `splot` command.
Normally the global option @ref{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.
The keywords may be abbreviated as indicated.
Note that the `linewidth`, @ref{pointsize} and @ref{palette} options are not supported
by all terminals.
Examples:
This plots sin(x) with impulses:
@example
plot sin(x) with impulses
@end example
This plots x with points, x**2 with the default:
@example
plot x w points, x**2
@end example
This plots tan(x) with the default function style, file "data.1" with lines:
@example
plot [ ] [-2:5] tan(x), 'data.1' with l
@end example
This plots "leastsq.dat" with impulses:
@example
plot 'leastsq.dat' w i
@end example
This plots the data file "population" with boxes:
@example
plot 'population' with boxes
@end example
This plots "exper.dat" with errorbars and lines connecting the points
(errorbars require three or four columns):
@example
plot 'exper.dat' w lines, 'exper.dat' notitle w errorbars
@end example
Another way to plot "exper.dat" with errorlines (errorbars require three
or four columns):
@example
plot 'exper.dat' w errorlines
@end example
This plots sin(x) and cos(x) with linespoints, using the same line type but
different point types:
@example
plot sin(x) with linesp lt 1 pt 3, cos(x) with linesp lt 1 pt 4
@end example
This plots file "data" with points of type 3 and twice usual size:
@example
plot 'data' with points pointtype 3 pointsize 2
@end example
This plots file "data" with variable pointsize read from column 4
@example
plot 'data' using 1:2:4 with points pt 5 pointsize variable
@end example
This plots two data sets with lines differing only by weight:
@example
plot 'd1' t "good" w l lt 2 lw 3, 'd2' t "bad" w l lt 2 lw 1
@end example
This plots filled curve of x*x and a color stripe:
@example
plot x*x with filledcurve closed, 40 with filledcurve y1=10
@end example
This plots x*x and a color box:
@example
plot x*x, (x>=-5 && xt.gp'
@end example
@node set-show, shell, save, Commands
@section set-show
@c ?commands set
@c ?commands show
@cindex set
@cindex show
@c ?show all
The `set` command can be used to set _lots_ of options. No screen is
drawn, however, until a `plot`, `splot`, or @ref{replot} command is given.
The `show` command shows their settings; `show all` shows all the settings.
Options changed using `set` can be returned to the default state by giving the
corresponding @ref{unset} command. See also the @ref{reset} command, which returns
all settable parameters to default values.
If a variable contains time/date data, `show` will display it according to
the format currently defined by @ref{timefmt}, even if that was not in effect
when the variable was initially defined.
@cindex iteration
@cmindex iteration
The `set` and @ref{unset} commands may optionally contain an iteration clause.
See @ref{iteration}.
@menu
* angles::
* arrow::
* autoscale::
* bars::
* bind_::
* bmargin::
* border::
* boxwidth::
* clabel::
* clip::
* cntrparam::
* color_box::
* colornames::
* contour::
* data_style::
* datafile::
* decimalsign::
* dgrid3d::
* dummy::
* encoding::
* fit_::
* fontpath::
* format_::
* function_style::
* functions::
* grid::
* hidden3d::
* historysize::
* isosamples::
* key::
* label::
* lmargin::
* loadpath::
* locale::
* logscale::
* macros::
* mapping::
* margin::
* mouse::
* multiplot::
* mx2tics::
* mxtics::
* my2tics::
* mytics::
* mztics::
* object::
* offsets::
* origin::
* output::
* parametric_::
* plot_::
* pm3d::
* palette::
* pointsize::
* polar::
* print_::
* rmargin::
* rrange::
* samples::
* size::
* style::
* surface::
* table::
* terminal::
* termoption::
* tics::
* ticslevel::
* ticscale::
* timestamp::
* timefmt::
* title_::
* tmargin::
* trange::
* urange::
* variables::
* version::
* view::
* vrange::
* x2data::
* x2dtics::
* x2label::
* x2mtics::
* x2range::
* x2tics::
* x2zeroaxis::
* xdata::
* xdtics::
* xlabel::
* xmtics::
* xrange::
* xtics::
* xyplane::
* xzeroaxis::
* y2data::
* y2dtics::
* y2label::
* y2mtics::
* y2range::
* y2tics::
* y2zeroaxis::
* ydata::
* ydtics::
* ylabel::
* ymtics::
* yrange::
* ytics::
* yzeroaxis::
* zdata::
* zdtics::
* zzeroaxis::
* cbdata::
* cbdtics::
* zero::
* zeroaxis::
* zlabel::
* zmtics::
* zrange::
* ztics::
* cblabel::
* cbmtics::
* cbrange::
* cbtics::
@end menu
@node angles, arrow, set-show, set-show
@subsection angles
@c ?commands set angles
@c ?commands show angles
@c ?set angles
@c ?show angles
@cindex angles
@opindex angles
@c ?commands set angles degrees
@c ?set angles degrees
@c ?angles degrees
@cindex degrees
By default, `gnuplot` assumes the independent variable in polar graphs is in
units of radians. If `set angles degrees` is specified before `set polar`,
then the default range is [0:360] and the independent variable has units of
degrees. This is particularly useful for plots of data files. The angle
setting also applies to 3D mapping as set via the @ref{mapping} command.
Syntax:
@example
set angles @{degrees | radians@}
show angles
@end example
The angle specified in `set grid polar` is also read and displayed in the
units specified by @ref{angles}.
@ref{angles} also affects the arguments of the machine-defined functions
sin(x), cos(x) and tan(x), and the outputs of asin(x), acos(x), atan(x),
atan2(x), and arg(x). It has no effect on the arguments of hyperbolic
functions or Bessel functions. However, the output arguments of inverse
hyperbolic functions of complex arguments are affected; if these functions
are used, `set angles radians` must be in effect to maintain consistency
between input and output arguments.
@example
x=@{1.0,0.1@}
set angles radians
y=sinh(x)
print y #prints @{1.16933, 0.154051@}
print asinh(y) #prints @{1.0, 0.1@}
@end example
but
@example
set angles degrees
y=sinh(x)
print y #prints @{1.16933, 0.154051@}
print asinh(y) #prints @{57.29578, 5.729578@}
@end example
See also
@uref{http://www.gnuplot.info/demo/poldat.html,poldat.dem: polar plot using @ref{angles} demo.
}
@node arrow, autoscale, angles, set-show
@subsection arrow
@c ?commands set arrow
@c ?commands unset arrow
@c ?commands show arrow
@c ?set arrow
@c ?unset arrow
@c ?show arrow
@cindex arrow
@opindex arrow
@cindex noarrow
Arbitrary arrows can be placed on a plot using the @ref{arrow} command.
Syntax:
@example
set arrow @{@} @{from @} @{to|rto @}
@{ @{arrowstyle | as @}
| @{ @{nohead | head | backhead | heads@}
@{size ,@{,@}@}
@{filled | empty | nofilled@}
@{front | back@}
@{ @{linestyle | ls @}
| @{linetype | lt @}
@{linewidth | lw smallerfile.ps
@end example
If pm3d map has been plotted from rectangular gridded data with an output
to a postscript file, then it is possible to reduce the file size even more
by the enclosed awk script `pm3dConvertToImage.awk`. Usage:
@example
awk -f pm3dConvertToImage.awk smallerfile.ps
@end example
You may manually change the postscript output from gray to color and vice
versa and change the definition of .
@node pointsize, polar, palette, set-show
@subsection pointsize
@c ?commands set pointsize
@c ?commands show pointsize
@c ?set pointsize
@c ?show pointsize
@cindex pointsize
@opindex pointsize
The @ref{pointsize} command scales the size of the points used in plots.
Syntax:
@example
set pointsize
show pointsize
@end example
The default is a multiplier of 1.0. Larger pointsizes may be useful to
make points more visible in bitmapped graphics.
The pointsize of a single plot may be changed on the `plot` command.
See @ref{with} for details.
Please note that the pointsize setting is not supported by all terminal
types.
@node polar, print_, pointsize, set-show
@subsection polar
@c ?commands set polar
@c ?commands unset polar
@c ?commands show polar
@c ?set polar
@c ?unset polar
@c ?show polar
@cindex polar
@opindex polar
@cindex nopolar
The `set polar` command changes the meaning of the plot from rectangular
coordinates to polar coordinates.
Syntax:
@example
set polar
unset polar
show polar
@end example
In polar coordinates, the dummy variable (t) is an angle. The default range
of t is [0:2*pi], or, if degree units have been selected, to [0:360] (see
@ref{angles}).
The command `unset polar` changes the meaning of the plot back to the default
rectangular coordinate system.
The `set polar` command is not supported for `splot`s. See the @ref{mapping}
command for similar functionality for `splot`s.
While in polar coordinates the meaning of an expression in t is really
r = f(t), where t is an angle of rotation. The trange controls the domain
(the angle) of the function, and the x and y ranges control the range of the
graph in the x and y directions. Each of these ranges, as well as the
rrange, may be autoscaled or set explicitly. Ffor details of all the @ref{ranges}
commands, see @ref{xrange}.
Example:
@example
set polar
plot t*sin(t)
plot [-2*pi:2*pi] [-3:3] [-3:3] t*sin(t)
@end example
The first `plot` uses the default polar angular domain of 0 to 2*pi. The
radius and the size of the graph are scaled automatically. The second `plot`
expands the domain, and restricts the size of the graph to [-3:3] in both
directions.
You may want to `set size square` to have `gnuplot` try to make the aspect
ratio equal to unity, so that circles look circular.
See also
@uref{http://www.gnuplot.info/demo/polar.html,polar demos (polar.dem)
}
and
@uref{http://www.gnuplot.info/demo/poldat.html,polar data plot (poldat.dem).
}
@node print_, rmargin, polar, set-show
@subsection print
@c ?commands set print
@c ?commands show print
@c ?set print
@c ?show print
The @ref{print} command redirects the output of the @ref{print} command to a file.
Syntax:
@example
set print
set print "-"
set print ""
set print "" append
set print "|"
@end example
Without "", the output file is restored to . The
"-" means . The `append` flag causes the file to be opened in append
mode. A starting with "|" is opened as a pipe to the
on platforms that support piping.
@node rmargin, rrange, print_, set-show
@subsection rmargin
@c ?commands set rmargin
@c ?set rmargin
@cindex rmargin
@opindex rmargin
The command @ref{rmargin} sets the size of the right margin.
Please see @ref{margin} for details.
@node rrange, samples, rmargin, set-show
@subsection rrange
@c ?commands set rrange
@c ?commands show rrange
@c ?set rrange
@c ?show rrange
@cindex rrange
@opindex rrange
The @ref{rrange} command sets the range of the radial coordinate for a
graph in polar mode. Please see @ref{xrange} for details.
@node samples, size, rrange, set-show
@subsection samples
@c ?commands set samples
@c ?commands show samples
@c ?set samples
@c ?show samples
@cindex samples
@opindex samples
The sampling rate of functions, or for interpolating data, may be changed
by the @ref{samples} command.
Syntax:
@example
set samples @{,@}
show samples
@end example
By default, sampling is set to 100 points. A higher sampling rate will
produce more accurate plots, but will take longer. This parameter has no
effect on data file plotting unless one of the interpolation/approximation
options is used. See @ref{smooth} re 2D data and @ref{cntrparam} and
@ref{dgrid3d} re 3D data.
When a 2D graph is being done, only the value of is relevant.
When a surface plot is being done without the removal of hidden lines, the
value of samples specifies the number of samples that are to be evaluated for
the isolines. Each iso-v line will have samples and each iso-u
line will have samples. If you only specify ,
will be set to the same value as . See also
@ref{isosamples}.
@node size, style, samples, set-show
@subsection size
@c ?commands set size
@c ?commands show size
@c ?set size
@c ?show size
@cindex size
@opindex size
@c ?aspect ratio
Syntax:
@example
set size @{@{no@}square | ratio | noratio@} @{,@}
show size
@end example
The and values are scale factors for the size of the plot,
which includes the graph, labels, and margins.
Important note:
@example
In earlier versions of gnuplot, some terminal types used the values from
@ref{size} to control also the size of the output canvas; others did not.
In version 4.2 almost all terminals now follow the following convention:
@end example
`set term size , ` controls the size of the output
file, or `canvas`. Please see individual terminal documentation for allowed
values of the size parameters. By default, the plot will fill this canvas.
`set size , ` 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 on some terminal types.
`ratio` causes `gnuplot` to try to create a graph with an aspect ratio of
(the ratio of the y-axis length to the x-axis length) within the portion of
the plot specified by and .
The meaning of a negative value for is different. If =-1, gnuplot
tries to set the scales so that the unit has the same length on both the x
and y axes (suitable for geographical data, for instance). If =-2, the
unit on y has twice the length of the unit on x, and so on.
The success of `gnuplot` in producing the requested aspect ratio depends on
the terminal selected. The graph area will be the largest rectangle of
aspect ratio that will fit into the specified portion of the output
(leaving adequate margins, of course).
`square` is a synonym for `ratio 1`.
Both `noratio` and `nosquare` return the graph to the default aspect ratio
of the terminal, but do not return or to their default
values (1.0).
`ratio` and `square` have no effect on 3D plots, but do affect 3D projections
created using `set view map`. See also `set view equal`, which forces
the x and y axes of a 3D onto the same scale.
Examples:
To set the size so that the plot fills the available canvas:
@example
set size 1,1
@end example
To make the graph half size and square use:
@example
set size square 0.5,0.5
@end example
To make the graph twice as high as wide use:
@example
set size ratio 2
@end example
See also
@uref{http://www.gnuplot.info/demo/airfoil.html,airfoil demo.
}
@node style, surface, size, set-show
@subsection style
@c ?set style
@c ?show style
@c ?unset style
@c ^ ">
Default plotting styles are chosen with the `set style data` and
`set style function` commands. See @ref{with} for information about how to
override the default plotting style for individual functions and data sets.
See `plotting styles` for a complete list of styles.
Syntax:
@example
set style function
set style data
show style function
show style data
@end example
Default styles for specific plotting elements may also be set.
Syntax:
@example
set style arrow
set style fill
set style histogram
set style line
@end example
@menu
* set_style_arrow::
* set_style_data::
* set_style_fill::
* set_style_function::
* set_style_increment::
* set_style_line::
* set_style_rectangle::
@end menu
@node set_style_arrow, set_style_data, style, style
@subsubsection set style arrow
@c ?commands set style arrow
@c ?commands unset style arrow
@c ?commands show style arrow
@c ?set style arrow
@c ?unset style arrow
@c ?show style arrow
@cindex arrowstyle
@c ^
@c ^
Each terminal has a default set of arrow and point types, which can be seen
by using the command @ref{test}. @ref{arrow} defines a set of arrow types
and widths and point types and sizes so that you can refer to them later by
an index instead of repeating all the information at each invocation.
Syntax:
@example
set style arrow default
set style arrow @{nohead | head | heads@}
@{size ,@{,@}@}
@{filled | empty | nofilled@}
@{front | back@}
@{ @{linestyle | ls @}
| @{linetype | lt @}
@{linewidth | lw = 0 in colour (MIF sep. 2--7) and
`monochrome` plots all line types in black (MIF sep. 0).
`polyline` plots curves as continuous curves and @ref{vectors} plots curves as
collections of vectors.
@ref{help} and `?` print online help on standard error output---both print a
short description of the usage; @ref{help} also lists the options.
Examples:
@example
set term mif colour polylines # defaults
set term mif # defaults
set term mif vectors
set term mif help"
@end example
@node next, Openstep_(next), mif, terminal_
@subsubsection next
@c ?commands set terminal next
@c ?set terminal next
@c ?set term next
@c ?terminal next
@c ?term next
@cindex next
@cindex NeXT
Several options may be set in the next driver.
Syntax:
@example
set terminal next @{@} @{ @} @{@} @{@}
@{""@} @{@} title @{""@}
@end example
where is `default`, which sets all options to their defaults;
is either `new` or `old`, where `old` invokes the old single window;
is either `color` or `monochrome`;
is either `solid` or `dashed`;
"" is the name of a valid PostScript font;
is the size of the font in PostScript points; and
is the title for the GnuTerm window.
Defaults are `new`, `monochrome`, `dashed`, "Helvetica", 14pt.
Examples:
@example
set term next default
set term next 22
set term next color "Times-Roman" 14
set term next color "Helvetica" 12 title "MyPlot"
set term next old
@end example
Pointsizes may be changed with `set linestyle`."
@node Openstep_(next), pbm, next, terminal_
@subsubsection Openstep (next)
@c ?commands set terminal openstep
@c ?set terminal openstep
@c ?set term openstep
@c ?terminal openstep
@c ?term openstep
@cindex openstep
@cindex OpenStep
@cindex Openstep
/*
@cindex next
@cindex NeXT
*/
Several options may be set in the openstep (next) driver.
Syntax:
@example
set terminal openstep @{@} @{ @} @{@} @{@}
@{""@} @{@} title @{""@}
@end example
where is `default`, which sets all options to their defaults;
is either `new` or `old`, where `old` invokes the old single window;
is either `color` or `monochrome`;
is either `solid` or `dashed`;
"" is the name of a valid PostScript font;
is the size of the font in PostScript points; and
is the title for the GnuTerm window.
Defaults are `new`, `monochrome`, `dashed`, "Helvetica", 14pt.
Examples:
@example
set term openstep default
set term openstep 22
set term openstep color "Times-Roman" 14
set term openstep color "Helvetica" 12 title "MyPlot"
set term openstep old
@end example
Pointsizes may be changed with `set linestyle`."
@node pbm, dospc, Openstep_(next), terminal_
@subsubsection pbm
@c ?commands set terminal pbm
@c ?set terminal pbm
@c ?set term pbm
@c ?terminal pbm
@c ?term pbm
@cindex pbm
@tmindex pbm
Syntax:
@example
set terminal pbm @{@} @{@} @{size ,@}
@end example
where is `small`, `medium`, or `large` and is `monochrome`,
`gray` or `color`. The default plot size is 640 pixels wide and 480 pixels
high. The output size is white-space padded to the nearest multiple of
8 pixels on both x and y. This empty space may be cropped later if needed.
The output of the `pbm` driver depends upon : `monochrome` produces a
portable bitmap (one bit per pixel), `gray` a portable graymap (three bits
per pixel) and `color` a portable pixmap (color, four bits per pixel).
The output of this driver can be used with various image conversion and
manipulation utilities provided by NETPBM. Based on Jef Poskanzer's
PBMPLUS package, NETPBM provides programs to convert the above PBM formats
to GIF, TIFF, MacPaint, Macintosh PICT, PCX, X11 bitmap and many others.
Complete information is available at http://netpbm.sourceforge.net/.
Examples:
@example
set terminal pbm small monochrome # defaults
set terminal pbm color medium size 800,600
set output '| pnmrotate 45 | pnmtopng > tilted.png' # uses NETPBM"
@end example
@node dospc, pdf, pbm, terminal_
@subsubsection dospc
@c ?commands set terminal dospc
@c ?set terminal dospc
@c ?set term dospc
@c ?terminal dospc
@c ?term dospc
@cindex dospc
@tmindex dospc
The `dospc` terminal driver supports PCs with arbitrary graphics boards,
which will be automatically detected. It should be used only if you are
not using the gcc or Zortec C/C++ compilers."
@node pdf, pstricks, dospc, terminal_
@subsubsection pdf
@c ?commands set terminal pdf
@c ?set terminal pdf
@c ?set term pdf
@c ?terminal pdf
@c ?term pdf
@cindex pdf
@tmindex pdf
This terminal produces files in the Adobe Portable Document Format
(PDF), useable for printing or display with tools like Acrobat Reader
Syntax:
@example
set terminal pdf @{monochrome|color|colour@}
@{@{no@}enhanced@}
@{fname ""@} @{fsize @}
@{font "@{,@}"@}
@{linewidth @} @{rounded|butt@}
@{solid|dashed@} @{dl @}@}
@{size @{unit@},@{unit@}@}
@end example
The default is to use a different color for each line type. Selecting
`monochome` will use black for all linetypes, in which case you probably
want to select `dashed` to distinguish line types. Even in in mono mode
you can still use explicit colors for filled areas or linestyles.
where is the name of the default font to use (default Helvetica)
and is the font size (in points, default 12).
For help on which fonts are available or how to install new ones, please
see the documentation for your local installation of pdflib.
The `enhanced` option enables enhanced text processing features
(subscripts, superscripts and mixed fonts). See `enhanced`.
The width of all lines in the plot can be increased by the factor
specified in `linewidth`. Similarly `dashlength` is a multiplier for the
default dash spacing.
`rounded` sets line caps and line joins to be rounded; `butt` is the
default, butt caps and mitered joins.
The default size for PDF output is 5 inches by 3 inches. The @ref{size} option
changes this to whatever the user requests. By default the X and Y sizes
are taken to be in inches, but other units are possible (currently only cm).
* does not work.
@node pstricks, qms, pdf, terminal_
@subsubsection pstricks
@c ?commands set terminal pstricks
@c ?set terminal pstricks
@c ?set term pstricks
@c ?terminal pstricks
@c ?term pstricks
@cindex pstricks
@tmindex pstricks
The `pstricks` driver is intended for use with the "pstricks.sty" macro
package for LaTeX. It is an alternative to the `eepic` and `latex` drivers.
You need "pstricks.sty", and, of course, a printer that understands
PostScript, or a converter such as Ghostscript.
PSTricks is available via anonymous ftp from the /pub directory at
Princeton.edu. This driver definitely does not come close to using the full
capability of the PSTricks package.
Syntax:
@example
set terminal pstricks @{hacktext | nohacktext@} @{unit | nounit@}
@end example
The first option invokes an ugly hack that gives nicer numbers; the second
has to do with plot scaling. The defaults are `hacktext` and `nounit`."
@node qms, regis, pstricks, terminal_
@subsubsection qms
@c ?commands set terminal qms
@c ?set terminal qms
@c ?set term qms
@c ?terminal qms
@c ?term qms
@cindex qms
@tmindex qms
The `qms` terminal driver supports the QMS/QUIC Laser printer, the Talaris
1200 and others. It has no options."
@node regis, regis_, qms, terminal_
@subsubsection regis
@c ?commands set terminal regis
@c ?set terminal regis
@c ?set term regis
@c ?terminal regis
@c ?term regis
@cindex regis
@tmindex regis
The `regis` terminal device generates output in the REGIS graphics language.
It has the option of using 4 (the default) or 16 colors.
Syntax:
@example
set terminal regis @{4 | 16@}"
@end example
@node regis_, rgip, regis, terminal_
@subsubsection regis
@c ?commands set terminal regis
@c ?set terminal regis
@c ?set term regis
@c ?terminal regis
@c ?term regis
@cindex regis
@tmindex regis
The `regis` terminal device generates output in the REGIS graphics language.
It has the option of using 4 (the default) or 16 colors.
Syntax:
@example
set terminal regis @{4 | 16@}"
@end example
@node rgip, sun, regis_, terminal_
@subsubsection rgip
@c ?commands set terminal rgip
@c ?set terminal rgip
@c ?set term rgip
@c ?terminal rgip
@c ?term rgip
@cindex rgip
@tmindex rgip
@c ?commands set terminal uniplex
@c ?set terminal uniplex
@c ?set term uniplex
@c ?terminal uniplex
@c ?term uniplex
@cindex uniplex
@tmindex uniplex
The `rgip` and `uniplex` terminal drivers support RGIP metafiles. They can
combine several graphs on a single page, but only one page is allowed in a
given output file.
Syntax:
@example
set terminal rgip | uniplex @{portrait | landscape@}
@{[,]@} @{@}
@end example
permissible values for the font size are in the range 1--8, with the default
being 1. The default layout is landscape. Graphs are placed on the page in
a `horiz`x`vert` grid, which defaults to [1,1].
Example:
@example
set terminal uniplex portrait [2,3]
@end example
puts six graphs on a page in three rows of two in portrait orientation."
@node sun, svg, rgip, terminal_
@subsubsection sun
@c ?commands set terminal sun
@c ?set terminal sun
@c ?set term sun
@c ?terminal sun
@c ?term sun
@cindex sun
@tmindex sun
The `sun` terminal driver supports the SunView window system. It has no
options."
@node svg, tek410x, sun, terminal_
@subsubsection svg
@c ?commands set terminal svg
@c ?set terminal svg
@c ?set term svg
@c ?terminal svg
@c ?term svg
@cindex svg
@tmindex svg
This terminal produces files in the W3C Scalable Vector Graphics format.
Syntax:
@example
set terminal svg @{size , @{|fixed|dynamic@}@}
@{@{no@}enhanced@}
@{fname ""@} @{fsize @}
@{font "@{,@}"@}
@{fontfile @}
@{rounded|butt@} @{solid|dashed@} @{linewidth @}
@end example
where and are the size of the SVG plot to generate,
`dynamic` allows a svg-viewer to resize plot, whereas the default
setting, `fixed`, will request an absolute size.
`linewidth ` increases the width of all lines used in the figure
by a factor of .
is the name of the default font to use (default Arial) and
is the font size (in points, default 12). SVG viewing
programs may substitute other fonts when the file is displayed.
The svg terminal supports an enhanced text mode, which allows font
and other formatting commands to be embedded in labels and other text
strings. The enhanced text mode syntax is shared with other gnuplot
terminal types. See `enhanced` for more details.
SVG allows you to embed fonts directly into an SVG document, or to
provide a hypertext link to the desired font. The `fontfile` option
specifies a local file which is copied into the section of the
resulting SVG output file. This file may either itself contain a font,
or may contain the records necessary to create a hypertext reference to
the desired font. Gnuplot will look for the requested file using the
directory list in the GNUPLOT_FONTPATH environmental variable.
NB: You must embed an svg font, not a TrueType or PostScript font."
@node tek410x, tek410x_, svg, terminal_
@subsubsection tek410x
@c ?commands set terminal tek410x
@c ?set terminal tek410x
@c ?set term tek410x
@c ?terminal tek410x
@c ?term tek410x
@cindex tek410x
@tmindex tek410x
The `tek410x` terminal driver supports the 410x and 420x family of Tektronix
terminals. It has no options."
@node tek410x_, tek40, tek410x, terminal_
@subsubsection tek410x
@c ?commands set terminal tek410x
@c ?set terminal tek410x
@c ?set term tek410x
@c ?terminal tek410x
@c ?term tek410x
@cindex tek410x
@tmindex tek410x
The `tek410x` terminal driver supports the 410x and 420x family of Tektronix
terminals. It has no options."
@node tek40, texdraw, tek410x_, terminal_
@subsubsection tek40
@c ?commands set terminal tek40xx
@c ?set terminal tek40xx
@c ?set term tek40xx
@c ?terminal tek40xx
@c ?term tek40xx
@cindex tek40
@tmindex tek40
@c ?commands set terminal vttek
@c ?set terminal vttek
@c ?set term vttek
@c ?terminal vttek
@c ?term vttek
@cindex vttek
@tmindex vttek
@c ?commands set terminal kc-tek40xx
@c ?set terminal kc-tek40xx
@c ?set term kc-tek40xx
@c ?terminal kc-tek40xx
@c ?term kc-tek40xx
@cindex kc-tek40xx
@tmindex kc-tek40xx
@c ?commands set terminal km-tek40xx
@c ?set terminal km-tek40xx
@c ?set term km-tek40xx
@c ?terminal km-tek40xx
@c ?term km-tek40xx
@cindex km-tek40xx
@c ?commands set terminal selanar
@c ?set terminal selanar
@c ?set term selanar
@c ?terminal selanar
@c ?term selanar
@cindex selanar
@c ?commands set terminal bitgraph
@c ?set terminal bitgraph
@c ?set term bitgraph
@c ?terminal bitgraph
@c ?term bitgraph
@cindex bitgraph
This family of terminal drivers supports a variety of VT-like terminals.
`tek40xx` supports Tektronix 4010 and others as well as most TEK emulators.
`vttek` supports VT-like tek40xx terminal emulators.
The following are present only if selected when gnuplot is built:
`kc-tek40xx` supports MS-DOS Kermit Tek4010 terminal emulators in color;
`km-tek40xx` supports them in monochrome. `selanar` supports Selanar graphics.
`bitgraph` supports BBN Bitgraph terminals.
None have any options."
@node texdraw, tgif, tek40, terminal_
@subsubsection texdraw
@c ?commands set terminal texdraw
@c ?set terminal texdraw
@c ?set term texdraw
@c ?terminal texdraw
@c ?term texdraw
@cindex texdraw
@tmindex texdraw
The `texdraw` terminal driver supports the LaTeX texdraw environment. It is
intended for use with "texdraw.sty" and "texdraw.tex" in the texdraw package.
Points, among other things, are drawn using the LaTeX commands "\\Diamond" and
"\\Box". These commands no longer belong to the LaTeX2e core; they are included
in the latexsym package, which is part of the base distribution and thus part
of any LaTeX implementation. Please do not forget to use this package.
It has no options."
@node tgif, tgif_, texdraw, terminal_
@subsubsection tgif
@c ?commands set terminal tgif
@c ?set terminal tgif
@c ?set term tgif
@c ?terminal tgif
@c ?term tgif
@cindex tgif
@tmindex tgif
Tgif is an X11-based drawing tool---it has nothing to do with GIF.
The `tgif` driver supports different pointsizes (with @ref{pointsize}),
different label fonts and font sizes (e.g. `set label "Hallo" at x,y font
"Helvetica,34"`) and multiple graphs on the page. The proportions of the
axes are not changed.
Syntax:
@example
set terminal tgif @{portrait | landscape | default@} @{@}
@{monochrome | color@}
@{@{linewidth | lw@} @}
@{solid | dashed@}
@{font ""@} @{@}
@end example
where specifies the number of graphs in the x and y directions on the
page, `color` enables color, `linewidth` scales all linewidths by ,
"" is the name of a valid PostScript font, and
specifies the size of the PostScript font.
`defaults` sets all options to their defaults: `portrait`, `[1,1]`, `color`,
`linwidth 1.0`, `dashed`, `"Helvetica"`, and `18`.
The `solid` option is usually prefered if lines are colored, as they often
are in the editor. Hardcopy will be black-and-white, so `dashed` should be
chosen for that.
Multiplot is implemented in two different ways.
The first multiplot implementation is the standard gnuplot multiplot feature:
@example
set terminal tgif
set output "file.obj"
set multiplot
set origin x01,y01
set size xs,ys
plot ...
...
set origin x02,y02
plot ...
unset multiplot
@end example
See @ref{multiplot} for further information.
The second version is the [x,y] option for the driver itself. The advantage
of this implementation is that everything is scaled and placed automatically
without the need for setting origins and sizes; the graphs keep their natural
x/y proportions of 3/2 (or whatever is fixed by @ref{size}).
If both multiplot methods are selected, the standard method is chosen and a
warning message is given.
Examples of single plots (or standard multiplot):
@example
set terminal tgif # defaults
set terminal tgif "Times-Roman" 24
set terminal tgif landscape
set terminal tgif landscape solid
@end example
Examples using the built-in multiplot mechanism:
@example
set terminal tgif portrait [2,4] # portrait; 2 plots in the x-
# and 4 in the y-direction
set terminal tgif [1,2] # portrait; 1 plot in the x-
# and 2 in the y-direction
set terminal tgif landscape [3,3] # landscape; 3 plots in both
# directions"
@end example
@node tgif_, tkcanvas, tgif, terminal_
@subsubsection tgif
@c ?commands set terminal tgif
@c ?set terminal tgif
@c ?set term tgif
@c ?terminal tgif
@c ?term tgif
@cindex tgif
@tmindex tgif
Tgif is an X11-based drawing tool---it has nothing to do with GIF.
The `tgif` driver supports different pointsizes (with @ref{pointsize}),
different label fonts and font sizes (e.g. `set label "Hallo" at x,y font
"Helvetica,34"`) and multiple graphs on the page. The proportions of the
axes are not changed.
Syntax:
@example
set terminal tgif @{portrait | landscape | default@} @{@}
@{monochrome | color@}
@{@{linewidth | lw@} @}
@{solid | dashed@}
@{font ""@} @{@}
@end example
where specifies the number of graphs in the x and y directions on the
page, `color` enables color, `linewidth` scales all linewidths by ,
"" is the name of a valid PostScript font, and
specifies the size of the PostScript font.
`defaults` sets all options to their defaults: `portrait`, `[1,1]`, `color`,
`linwidth 1.0`, `dashed`, `"Helvetica"`, and `18`.
The `solid` option is usually prefered if lines are colored, as they often
are in the editor. Hardcopy will be black-and-white, so `dashed` should be
chosen for that.
Multiplot is implemented in two different ways.
The first multiplot implementation is the standard gnuplot multiplot feature:
@example
set terminal tgif
set output "file.obj"
set multiplot
set origin x01,y01
set size xs,ys
plot ...
...
set origin x02,y02
plot ...
unset multiplot
@end example
See @ref{multiplot} for further information.
The second version is the [x,y] option for the driver itself. The advantage
of this implementation is that everything is scaled and placed automatically
without the need for setting origins and sizes; the graphs keep their natural
x/y proportions of 3/2 (or whatever is fixed by @ref{size}).
If both multiplot methods are selected, the standard method is chosen and a
warning message is given.
Examples of single plots (or standard multiplot):
@example
set terminal tgif # defaults
set terminal tgif "Times-Roman" 24
set terminal tgif landscape
set terminal tgif landscape solid
@end example
Examples using the built-in multiplot mechanism:
@example
set terminal tgif portrait [2,4] # portrait; 2 plots in the x-
# and 4 in the y-direction
set terminal tgif [1,2] # portrait; 1 plot in the x-
# and 2 in the y-direction
set terminal tgif landscape [3,3] # landscape; 3 plots in both
# directions"
@end example
@node tkcanvas, tpic, tgif_, terminal_
@subsubsection tkcanvas
@c ?commands set terminal tkcanvas
@c ?set terminal tkcanvas
@c ?set term tkcanvas
@c ?terminal tkcanvas
@c ?term tkcanvas
@cindex tkcanvas
@tmindex tkcanvas
This terminal driver generates Tk canvas widget commands based on Tcl/Tk
(default) or Perl. To use it, rebuild `gnuplot` (after uncommenting or
inserting the appropriate line in "term.h"), then
@example
gnuplot> set term tkcanvas @{perltk@} @{interactive@}
gnuplot> set output 'plot.file'
@end example
After invoking "wish", execute the following sequence of Tcl/Tk commands:
@example
% source plot.file
% canvas .c
% pack .c
% gnuplot .c
@end example
Or, for Perl/Tk use a program like this:
@example
use Tk;
my $top = MainWindow->new;
my $c = $top->Canvas->pack;
my $gnuplot = do "plot.pl";
$gnuplot->($c);
MainLoop;
@end example
The code generated by `gnuplot` creates a procedure called "gnuplot"
that takes the name of a canvas as its argument. When the procedure is
called, it clears the canvas, finds the size of the canvas and draws the plot
in it, scaled to fit.
For 2-dimensional plotting (`plot`) two additional procedures are defined:
"gnuplot_plotarea" will return a list containing the borders of the plotting
area "xleft, xright, ytop, ybot" in canvas screen coordinates, while the ranges
of the two axes "x1min, x1max, y1min, y1max, x2min, x2max, y2min, y2max" in plot
coordinates can be obtained calling "gnuplot_axisranges".
If the "interactive" option is specified, mouse clicking on a line segment
will print the coordinates of its midpoint to stdout. Advanced actions
can happen instead if the user supplies a procedure named
"user_gnuplot_coordinates", which takes the following arguments:
"win id x1s y1s x2s y2s x1e y1e x2e y2e x1m y1m x2m y2m",
the name of the canvas and the id of the line segment followed by the
coordinates of its start and end point in the two possible axis ranges; the
coordinates of the midpoint are only filled for logarithmic axes.
The current version of `tkcanvas` supports neither @ref{multiplot} nor @ref{replot}."
@node tpic, unixpc, tkcanvas, terminal_
@subsubsection tpic
@c ?commands set terminal tpic
@c ?set terminal tpic
@c ?set term tpic
@c ?terminal tpic
@c ?term tpic
@cindex tpic
@tmindex tpic
The `tpic` terminal driver supports the LaTeX picture environment with tpic
\\specials. It is an alternative to the `latex` and `eepic` terminal drivers.
Options are the point size, line width, and dot-dash interval.
Syntax:
@example
set terminal tpic
@end example
where @ref{pointsize} and `linewidth` are integers in milli-inches and `interval`
is a float in inches. If a non-positive value is specified, the default is
chosen: pointsize = 40, linewidth = 6, interval = 0.1.
All drivers for LaTeX offer a special way of controlling text positioning:
If any text string begins with '@{', you also need to include a '@}' at the
end of the text, and the whole text will be centered both horizontally
and vertically by LaTeX. --- If the text string begins with '[', you need
to continue it with: a position specification (up to two out of t,b,l,r),
']@{', the text itself, and finally, '@}'. The text itself may be anything
LaTeX can typeset as an LR-box. \\rule@{@}@{@}'s may help for best positioning.
Examples:
About label positioning:
Use gnuplot defaults (mostly sensible, but sometimes not really best):
@example
set title '\\LaTeX\\ -- $ \\gamma $'
@end example
Force centering both horizontally and vertically:
@example
set label '@{\\LaTeX\\ -- $ \\gamma $@}' at 0,0
@end example
Specify own positioning (top here):
@example
set xlabel '[t]@{\\LaTeX\\ -- $ \\gamma $@}'
@end example
The other label -- account for long ticlabels:
@example
set ylabel '[r]@{\\LaTeX\\ -- $ \\gamma $\\rule@{7mm@}@{0pt@}@}'"
@end example
@node unixpc, unixplot, tpic, terminal_
@subsubsection unixpc
@c ?commands set terminal unixpc
@c ?set terminal unixpc
@c ?set term unixpc
@c ?terminal unixpc
@c ?term unixpc
@cindex unixpc
@tmindex unixpc
The `unixpc` terminal driver supports AT&T 3b1 and AT&T 7300 Unix PC. It has
no options."
@node unixplot, vx384, unixpc, terminal_
@subsubsection unixplot
@c ?commands set terminal unixplot
@c ?set terminal unixplot
@c ?set term unixplot
@c ?terminal unixplot
@c ?term unixplot
@cindex unixplot
@tmindex unixplot
The `unixplot` terminal driver generates output in the Unix "plot" graphics
language. It has no options.
This terminal cannot be compiled if the GNU version of plot is to be used;
in that case, use the `gnugraph` terminal instead."
@node vx384, vgagl, unixplot, terminal_
@subsubsection vx384
@c ?commands set terminal vx384
@c ?set terminal vx384
@c ?set term vx384
@c ?terminal vx384
@c ?term vx384
@cindex vx384
@tmindex vx384
The `vx384` terminal driver supports the Vectrix 384 and Tandy color
printers. It has no options."
@node vgagl, VWS, vx384, terminal_
@subsubsection vgagl
@c ?commands set terminal vgagl
@c ?set terminal vgagl
@c ?set term vgagl
@c ?terminal vgagl
@c ?term vgagl
@cindex vgagl
@tmindex vgagl
The `vgagl` driver is a fast linux console driver with full mouse and pm3d
support. It looks at the environment variable SVGALIB_DEFAULT_MODE for the
default mode; if not set, it uses a 256 color mode with the highest
available resolution.
Syntax:
@example
set terminal vgagl \\
background [red] [[green] [blue]] \\
[uniform | interpolate] \\
[dump "file"] \\
[mode]
@end example
The color mode can also be given with the mode option. Both Symbolic
names as G1024x768x256 and integers are allowed. The `background` option
takes either one or three integers in the range [0, 255]. If only one
integers is supplied, it is taken as gray value for the background.
If three integers are present, the background gets the corresponding
color.
The (mutually exclusive) options `interpolate` and `uniform` control
if color interpolation is done while drawing triangles (on by default).
A @ref{file} can be specified with the `dump "file"` option.
If this option is present, (i.e the dump file name is not empty) pressing
the key KP_Delete will write the file. This action cannot and cannot be
rebound. The file is written in raw ppm (P6) format. Note that this option
is reset each time the `set term` command is issued.
To get high resolution modes, you will probably have to modify the
configuration file of libvga, usually /etc/vga/libvga.conf. Using
the VESA fb is a good choice, but this needs to be compiled in the
kernel.
The vgagl driver uses the first *available* vga mode from the following list:
@example
- the driver which was supplied when setting vgagl, e.g. `set term vgagl
G1024x768x256` would first check, if the G1024x768x256 mode is available.
- the environment variable SVGALIB_DEFAULT_MODE
- G1024x768x256
- G800x600x256
- G640x480x256
- G320x200x256
- G1280x1024x256
- G1152x864x256
- G1360x768x256
- G1600x1200x256
@end example
@node VWS, windows, vgagl, terminal_
@subsubsection VWS
@c ?commands set terminal VWS
@c ?set terminal VWS
@c ?set term VWS
@c ?terminal VWS
@c ?term VWS
@cindex VWS
@tmindex VWS
The `VWS` terminal driver supports the VAX Windowing System. It has
no options. It will sense the display type (monochrome, gray scale,
or color.) All line styles are plotted as solid lines."
@node windows, wxt, VWS, terminal_
@subsubsection windows
@c ?commands set terminal windows
@c ?set terminal windows
@c ?set term windows
@c ?terminal windows
@c ?term windows
@cindex windows
@tmindex windows
Three options may be set in the `windows` terminal driver.
Syntax:
@example
set terminal windows @{color | monochrome@}
@{enhanced | noenhanced@}
@{@{font@} "fontname@{,fontsize@}" @{@}@}
@{title "Plot Window Title"@}
@end example
where `color` and `monochrome` select colored or mono output,
`enhanced` enables enhanced text mode features (subscripts,
superscripts and mixed fonts). See `enhanced` for more information.
`""` is the name of a valid Windows font, and ``
is the size of the font in points.
Other options may be set with the graph-menu or the initialization file.
The Windows version normally terminates immediately as soon as the end of
any files given as command line arguments is reached (i.e. in non-interactive
mode), unless you specify `-` as the last command line option.
It will also not show the text-window at all, in this mode, only the plot.
By giving the optional argument `-persist` (same as for gnuplot under x11;
former Windows-only options `/noend` or `-noend` are still accepted as well),
will not close gnuplot. Contrary to gnuplot on other operating systems,
gnuplot's interactive command line is accessible after the -persist option.
@noindent --- GRAPH-MENU ---
@c ?commands set terminal windows graph-menu
@c ?set terminal windows graph-menu
@c ?set term windows graph-menu
@c ?windows graph-menu
@cindex graph-menu
@tmindex graph-menu
The `gnuplot graph` window has the following options on a pop-up menu
accessed by pressing the right mouse button or selecting `Options` from the
system menu:
`Bring to Top` when checked brings the graph window to the top after every
plot.
`Color` when checked enables color linestyles. When unchecked it forces
monochrome linestyles.
`Copy to Clipboard` copies a bitmap and a Metafile picture.
`Background...` sets the window background color.
`Choose Font...` selects the font used in the graphics window.
`Line Styles...` allows customization of the line colors and styles.
`Print...` prints the graphics windows using a Windows printer driver and
allows selection of the printer and scaling of the output. The output
produced by `Print` is not as good as that from `gnuplot`'s own printer
drivers.
`Update wgnuplot.ini` saves the current window locations, window sizes, text
window font, text window font size, graph window font, graph window font
size, background color and linestyles to the initialization file
`WGNUPLOT.INI`.
@noindent --- PRINTING ---
@c ?commands set terminal windows printing
@c ?set terminal windows printing
@c ?set term windows printing
@c ?windows printing
@cindex printing
@tmindex printing
In order of preference, graphs may be be printed in the following ways.
`1.` Use the `gnuplot` command @ref{terminal} to select a printer and @ref{output} to redirect output to a file.
`2.` Select the `Print...` command from the `gnuplot graph` window. An extra
command `screendump` does this from the text window.
`3.` If `set output "PRN"` is used, output will go to a temporary file. When
you exit from `gnuplot` or when you change the output with another @ref{output} command, a dialog box will appear for you to select a printer port.
If you choose OK, the output will be printed on the selected port, passing
unmodified through the print manager. It is possible to accidentally (or
deliberately) send printer output meant for one printer to an incompatible
printer.
@noindent --- TEXT-MENU ---
@c ?commands set terminal windows text-menu
@c ?set terminal windows text-menu
@c ?set term windows text-menu
@c ?windows text-menu
@cindex text-menu
@tmindex text-menu
The `gnuplot text` window has the following options on a pop-up menu accessed
by pressing the right mouse button or selecting `Options` from the system
menu:
`Copy to Clipboard` copies marked text to the clipboard.
`Paste` copies text from the clipboard as if typed by the user.
`Choose Font...` selects the font used in the text window.
`System Colors` when selected makes the text window honor the System Colors
set using the Control Panel. When unselected, text is black or blue on a
white background.
`Update wgnuplot.ini` saves the current text window location, text window
size, text window font and text window font size to the initialisation file
`WGNUPLOT.INI`.
`MENU BAR`
If the menu file `WGNUPLOT.MNU` is found in the same directory as
WGNUPLOT.EXE, then the menu specified in `WGNUPLOT.MNU` will be loaded.
Menu commands:
[Menu] starts a new menu with the name on the following line.
[EndMenu] ends the current menu.
[--] inserts a horizontal menu separator.
[|] inserts a vertical menu separator.
[Button] puts the next macro on a push button instead of a menu.
Macros take two lines with the macro name (menu entry) on the first line and
the macro on the second line. Leading spaces are ignored. Macro commands:
[INPUT] --- Input string with prompt terminated by [EOS] or @{ENTER@}
[EOS] --- End Of String terminator. Generates no output.
[OPEN] --- Get name of file to open from list box, with title of list box
terminated by [EOS], followed by default filename terminated by [EOS] or
@{ENTER@}.
[SAVE] --- Get name of file to save. Similar to [OPEN]
Macro character substitutions:
@{ENTER@} --- Carriage Return '\\r'
@{TAB@} --- Tab '\\011'
@{ESC@} --- Escape '\\033'
@{^A@} --- '\\001'
...
@{^_@} --- '\\031'
Macros are limited to 256 characters after expansion.
@noindent --- WGNUPLOT.INI ---
@c ?commands set terminal windows wgnuplot.ini
@c ?set terminal windows wgnuplot.ini
@c ?set term windows wgnuplot.ini
@c ?windows wgnuplot.ini
@cindex wgnuplot.ini
@tmindex wgnuplot.ini
Windows `gnuplot` will read some of its options from the `[WGNUPLOT]` section
of `WGNUPLOT.INI` in user's %APPDATA% directory. A sample `WGNUPLOT.INI` file:
@example
[WGNUPLOT]
TextOrigin=0 0
TextSize=640 150
TextFont=Terminal,9
GraphOrigin=0 150
GraphSize=640 330
GraphFont=Arial,10
GraphColor=1
GraphToTop=1
GraphBackground=255 255 255
Border=0 0 0 0 0
Axis=192 192 192 2 2
Line1=0 0 255 0 0
Line2=0 255 0 0 1
Line3=255 0 0 0 2
Line4=255 0 255 0 3
Line5=0 0 128 0 4
@end example
The `GraphFont` entry specifies the font name and size in points. The five
numbers given in the `Border`, `Axis` and `Line` entries are the `Red`
intensity (0--255), `Green` intensity, `Blue` intensity, `Color Linestyle`
and `Mono Linestyle`. `Linestyles` are 0=SOLID, 1=DASH, 2=DOT, 3=DASHDOT,
4=DASHDOTDOT. In the sample `WGNUPLOT.INI` file above, Line 2 is a green
solid line in color mode, or a dashed line in monochrome mode. The default
line width is 1 pixel. If `Linestyle` is negative, it specifies the width of
a SOLID line in pixels. Line1 and any linestyle used with the `points` style
must be SOLID with unit width."
@node wxt, x11, windows, terminal_
@subsubsection wxt
@c ?set terminal wxt
@c ?terminal wxt
@c ?set term wxt
@c ?term wxt
@cindex wxt
@tmindex wxt
The `wxt` terminal device generates output in a separate window. The window
is created by the wxWidgets library, where the 'wxt' comes from. The actual
drawing is done via cairo, a 2D graphics library, and pango, a library for
laying out and rendering text.
Syntax:
@example
set term wxt @{@}
@{size ,@}
@{@{no@}enhanced@}
@{font @}
@{title "title"@}
@{@{no@}persist@}
@{@{no@}raise@}
@{@{no@}ctrl@}
@{close@}
@end example
Multiple plot windows are supported: `set terminal wxt ` directs the
output to plot window number n.
The default window title is based on the window number. This title can also
be specified with the keyword "title".
Plot windows remain open even when the `gnuplot` driver is changed to a
different device. A plot window can be closed by pressing the letter 'q'
while that window has input focus, by choosing `close` from a window
manager menu, or with `set term wxt close`.
The size of the plot area is given in pixels, it defaults to 640x384.
In addition to that, the actual size of the window also includes the space
reserved for the toolbar and the status bar.
When you resize a window, the plot is immediately scaled to fit in the
new size of the window. Unlike other interactive terminals, the `wxt`
terminal scales the whole plot, including fonts and linewidths, and keeps
its global aspect ratio constant, leaving an empty space painted in gray.
If you type @ref{replot}, click the @ref{replot} icon in the terminal toolbar or
type a new `plot` command, the new plot will completely fit in the window
and the font size and the linewidths will be reset to their defaults.
The active plot window (the one selected by `set term wxt `) is
interactive. Its behaviour is shared with other terminal types. See `mouse`
for details. It also has some extra icons, which are supposed to be
self-explanatory.
This terminal supports an enhanced text mode, which allows font and other
formatting commands (subscripts, superscripts, etc.) to be embedded in labels
and other text strings. The enhanced text mode syntax is shared with other
gnuplot terminal types. See `enhanced` for more details.
is in the format "FontFace,FontSize", i.e. the face and the size
comma-separated in a single string. FontFace is a usual font face name, such
as \'Arial\'. If you do not provide FontFace, the wxt terminal will use
\'Sans\'. FontSize is the font size, in points. If you do not provide it,
the wxt terminal will use a size of 10 points.
@example
For example :
set term wxt font "Arial,12"
set term wxt font "Arial" # to change the font face only
set term wxt font ",12" # to change the font size only
set term wxt font "" # to reset the font name and size
@end example
The fonts are retrieved from the usual fonts subsystems. Under Windows,
those fonts are to be found and configured in the entry "Fonts" of the
control panel. Under UNIX, they are handled by "fontconfig".
Pango, the library used to layout the text, is based on utf-8. Thus, the wxt
terminal has to convert from your encoding to utf-8. The default input
encoding is based on your \'locale\'. If you want to use another encoding,
make sure gnuplot knows which one you are using. See @ref{encoding} for more
details.
Pango may give unexpected results with fonts that do not respect the unicode
mapping. With the Symbol font, for example, the wxt terminal will use the map
provided by http://www.unicode.org/ to translate character codes to unicode.
Pango will do its best to find a font containing this character, looking for
your Symbol font, or other fonts with a broad unicode coverage, like the
DejaVu fonts. Note that "the Symbol font" is to be understood as the Adobe
Symbol font, distributed with Acrobat Reader as "SY______.PFB".
Alternatively, the OpenSymbol font, distributed with OpenOffice.org as
"opens___.ttf", offers the same characters. Microsoft has distributed a
Symbol font ("symbol.ttf"), but it has a different character set with
several missing or moved mathematic characters. If you experience problems
with your default setup (if the demo enhancedtext.dem is not displayed
properly for example), you probably have to install one of the Adobe or
OpenOffice Symbol fonts, and remove the Microsoft one.
Other non-conform fonts, such as "wingdings" have been observed working.
The rendering of the plot can be altered with a dialog available from the
toolbar. To obtain the best output possible, the rendering involves three
mechanisms : antialiasing, oversampling and hinting.
Antialiasing allows to display non-horizontal and non-vertical lines
smoother.
Oversampling combined with antialiasing provides subpixel accuracy,
so that gnuplot can draw a line from non-integer coordinates. This avoids
wobbling effects on diagonal lines ('plot x' for example).
Hinting avoids the blur on horizontal and vertical lines caused by
oversampling. The terminal will snap these lines to integer coordinates so
that a one-pixel-wide line will actually be drawn on one and only one pixel.
By default, the window is raised to the top of your desktop when a plot is
drawn. This can be controlled with the keyword "raise".
The keyword "persist" will prevent gnuplot from exiting before you
explicitely close all the plot windows.
Finally, by default the key raises the gnuplot console window, and
'q' closes the plot window. The keyword "ctrl" allows you to replace those
bindings by + and +'q', respectively.
These three keywords (raise, persist and ctrl) can also be set and remembered
between sessions through the configuration dialog."
@node x11, x11_, wxt, terminal_
@subsubsection x11
@c ?commands set terminal x11
@c ?set terminal x11
@c ?set term x11
@c ?terminal x11
@c ?term x11
@cindex x11
@cindex X11
`gnuplot` provides the `x11` terminal type for use with X servers. This
terminal type is set automatically at startup if the `DISPLAY` environment
variable is set, if the `TERM` environment variable is set to `xterm`, or
if the `-display` command line option is used.
Syntax:
@example
set terminal x11 @{ | window ""@}
@{title ""@}
@{@{no@}enhanced@} @{font @}
@{linewidth LW@} @{solid|dashed@}
@{@{no@}persist@} @{@{no@}raise@} @{@{no@}ctrlq@}
@{close@}
@{size XX,YY@} @{position XX,YY@}
set terminal x11 @{reset@}
@end example
Multiple plot windows are supported: `set terminal x11 ` directs the
output to plot window number n. If n is not 0, the terminal number will be
appended to the window title (unless a title has been supplied manually)
and the icon will be labeled `Gnuplot `. The active window may be
distinguished by a change in cursor (from default to crosshair).
The `x11` terminal can connect to X windows previously created by an outside
application via the option `window` followed by a string containing the
X ID for the window in hexadecimal format. Gnuplot uses that external X
window as a container since X does not allow for multiple clients selecting
the ButtonPress event. In this way, gnuplot's mouse features work within
the contained plot window.
@example
set term x11 window "220001e"
@end example
The x11 terminal supports enhanced text mode (see `enhanced`), subject
to the available fonts. In order for font size commands embedded in text
to have any effect, the default x11 font must be scalable. Thus the first
example below will work as expected, but the second will not.
@example
set term x11 enhanced font "arial,15"
set title '@{/=20 Big@} Medium @{/=5 Small@}'
@end example
@example
set term x11 enhanced font "terminal-14"
set title '@{/=20 Big@} Medium @{/=5 Small@}'
@end example
Plot windows remain open even when the `gnuplot` driver is changed to a
different device. A plot window can be closed by pressing the letter q
while that window has input focus, or by choosing `close` from a window
manager menu. All plot windows can be closed by specifying @ref{reset}, which
actually terminates the subprocess which maintains the windows (unless
`-persist` was specified). The `close` command can be used to close
individual plot windows by number. However, after a @ref{reset}, those plot
windows left due to persist cannot be closed with the command `close`.
A `close` without a number closes the current active plot window.
The gnuplot outboard driver, gnuplot_x11, is searched in a default place
chosen when the program is compiled. You can override that by defining
the environment variable GNUPLOT_DRIVER_DIR to point to a different
location.
Plot windows will automatically be closed at the end of the session
unless the `-persist` option was given.
The options `persist` and @ref{raise} are unset by default, which means that
the defaults (persist == no and raise == yes) or the command line options
-persist / -raise or the Xresources are taken. If [no]persist or
[no]raise are specified, they will override command line options and
Xresources. Setting one of these options takes place immediately, so
the behaviour of an already running driver can be modified. If the window
does not get raised, see discussion in @ref{raise}.
The option `title ""` will supply the title name of the window
for the current plot window or plot window if a number is given.
Where (or if) this title is shown depends on your X window manager.
The size option can be used to set the size of the plot window. The
size option will only apply to newly created windows.
The position option can be used to set the position of the plot window. The
position option will only apply to newly created windows.
The size or aspect ratio of a plot may be changed by resizing the `gnuplot`
window.
Linewidths and pointsizes may be changed from within `gnuplot` with
`set linestyle`.
For terminal type `x11`, `gnuplot` accepts (when initialized) the standard
X Toolkit options and resources such as geometry, font, and name from the
command line arguments or a configuration file. See the X(1) man page
(or its equivalent) for a description of such options.
@cindex X resources
A number of other `gnuplot` options are available for the `x11` terminal.
These may be specified either as command-line options when `gnuplot` is
invoked or as resources in the configuration file ".Xdefaults". They are
set upon initialization and cannot be altered during a `gnuplot` session.
(except `persist` and @ref{raise})
@noindent --- X11_FONTS ---
@c ?commands set terminal x11 x11_fonts
@c ?set terminal x11 x11_fonts
@c ?set term x11 x11_fonts
@c ?x11 x11_fonts
@cindex x11_fonts
@cindex fonts
Upon initial startup, the default font is taken from the X11 resources
as set in the system or user .Xdefaults file or on the command line.
Example:
@example
gnuplot*font: lucidasans-bold-12
@end example
A new default font may be specified to the x11 driver from inside
gnuplot using
@example
`set term x11 font ""`
@end example
The driver first queries the X-server for a font of the exact name given.
If this query fails, then it tries to interpret as
",,," and to construct a full X11 font name
of the form
@example
-*----*-*--*-*-*-*-*-
@end example
@example
is the base name of the font (e.g. Times or Symbol)
is the point size (defaults to 12 if not specified)
is `i` if =="italic" `o` if =="oblique" `r` otherwise
is `medium` or `bold` if explicitly requested, otherwise `*`
is set based on the current character set (see @ref{encoding}).
@end example
So `set term x11 font "arial,15,italic"` will be translated to
-*-arial-*-i-*-*-15-*-*-*-*-*-iso8859-1 (assuming default encoding).
The , , and specifications are all optional.
If you do not specify or then you will get whatever font
variant the font server offers first.
You may set a default enconding via the corresponding X11 resource. E.g.
@example
gnuplot*encoding: iso8859-15
@end example
The driver also recognizes some common PostScript font names and
replaces them with possible X11 or TrueType equivalents.
This same sequence is used to process font requests from `set label`.
If your gnuplot was built with configuration option --enable-x11-mbfonts,
you can specify multi-byte fonts by using the prefix "mbfont:" on the font
name. An additional font may be given, separated by a semicolon.
Since multi-byte font encodings are interpreted according to the locale
setting, you must make sure that the environmental variable LC_CTYPE is set
to some appropriate locale value such as ja_JP.eucJP, ko_KR.EUC, or zh_CN.EUC.
Example:
@example
set term x11 font 'mbfont:kana14;k14'
# 'kana14' and 'k14' are Japanese X11 font aliases, and ';'
# is the separator of font names.
set term x11 font 'mbfont:fixed,16,r,medium'
# ,,, form is also usable.
set title '(mb strings)' font 'mbfont:*-fixed-medium-r-normal--14-*'
@end example
The same syntax applies to the default font in Xresources settings,
for example,
@example
gnuplot*font: \\
mbfont:-misc-fixed-medium-r-normal--14-*-*-*-c-*-jisx0208.1983-0
@end example
If gnuplot is built with --enable-x11-mbfonts, you can use two special
PostScript font names 'Ryumin-Light-*' and 'GothicBBB-Medium-*' (standard
Japanese PS fonts) without the prefix "mbfont:".
@noindent --- COMMAND-LINE_OPTIONS ---
@c ?commands set terminal x11 command-line-options
@c ?set terminal x11 command-line-options
@c ?set term x11 command-line-options
@c ?x11 command-line-options
@cindex command-line-options
In addition to the X Toolkit options, the following options may be specified
on the command line when starting `gnuplot` or as resources in your
".Xdefaults" file (note that @ref{raise} and `persist` can be overridden
later by `set term x11 [no]raise [no]persist)`:
@example
`-mono` forces monochrome rendering on color displays.
`-gray` requests grayscale rendering on grayscale or color displays.
(Grayscale displays receive monochrome rendering by default.)
`-clear` requests that the window be cleared momentarily before a
new plot is displayed.
`-tvtwm` requests that geometry specifications for position of the
window be made relative to the currently displayed portion
of the virtual root.
`-raise` raises plot window after each plot
`-noraise` does not raise plot window after each plot
`-noevents` does not process mouse and key events
`-ctrlq ` closes window on ctrl-q rather than q
`-persist` plot windows survive after main gnuplot program exits
@end example
@cindex X resources
The options are shown above in their command-line syntax. When entered as
resources in ".Xdefaults", they require a different syntax.
Example:
@example
gnuplot*gray: on
gnuplot*ctrlq: on
@end example
`gnuplot` also provides a command line option (`-pointsize `) and a
resource, `gnuplot*pointsize: `, to control the size of points plotted
with the `points` plotting style. The value `v` is a real number (greater
than 0 and less than or equal to ten) used as a scaling factor for point
sizes. For example, `-pointsize 2` uses points twice the default size, and
`-pointsize 0.5` uses points half the normal size.
The `-noevents` switch disables all mouse and key event processing (except
for `q` and `` for closing the window). This is useful for programs
which use the x11 driver independent of the gnuplot main program.
The `-ctrlq` switch changes the hot-key that closes a plot window from `q`
to `q`. This is useful is you are using the keystroke-capture feature
`pause mouse keystroke`, since it allows the character `q` to be captured
just as all other alphanumeric characters. The `-ctrlq` switch similarly
replaces the hot-key with for the same reason.
@noindent --- MONOCHROME_OPTIONS ---
@c ?commands set terminal x11 monochrome_options
@c ?set terminal x11 monochrome_options
@c ?set term x11 monochrome_options
@c ?x11 monochrome_options
@cindex monochrome_options
@cindex X resources
For monochrome displays, `gnuplot` does not honor foreground or background
colors. The default is black-on-white. `-rv` or `gnuplot*reverseVideo: on`
requests white-on-black.
@noindent --- COLOR_RESOURCES ---
@c ?commands set terminal x11 color_resources
@c ?set terminal x11 color_resources
@c ?set term x11 color_resources
@c ?x11 color_resources
@cindex color_resources
@cindex X resources
The X11 terminal honors the following resources (shown here with their
default values) or the greyscale resources. The values may be color names
as listed in the X11 rgb.txt file on your system, hexadecimal RGB color
specifications (see X11 documentation), or a color name followed by a comma
and an `intensity` value from 0 to 1. For example, `blue, 0.5` means a half
intensity blue.
@example
gnuplot*background: white
gnuplot*textColor: black
gnuplot*borderColor: black
gnuplot*axisColor: black
gnuplot*line1Color: red
gnuplot*line2Color: green
gnuplot*line3Color: blue
gnuplot*line4Color: magenta
gnuplot*line5Color: cyan
gnuplot*line6Color: sienna
gnuplot*line7Color: orange
gnuplot*line8Color: coral
@end example
The command-line syntax for these is simple only for background,
which maps directly to the usual X11 toolkit option "-bg". All
others can only be set on the command line by use of the generic
"-xrm" resource override option
Examples:
@example
gnuplot -background coral
@end example
to change the background color.
@example
gnuplot -xrm 'gnuplot*line1Color:blue'
@end example
to override the first linetype color.
@noindent --- GRAYSCALE_RESOURCES ---
@c ?commands set terminal x11 grayscale_resources
@c ?set terminal x11 grayscale_resources
@c ?set term x11 grayscale_resources
@c ?x11 grayscale_resources
@cindex grayscale_resources
@cindex X resources
When `-gray` is selected, `gnuplot` honors the following resources for
grayscale or color displays (shown here with their default values). Note
that the default background is black.
@example
gnuplot*background: black
gnuplot*textGray: white
gnuplot*borderGray: gray50
gnuplot*axisGray: gray50
gnuplot*line1Gray: gray100
gnuplot*line2Gray: gray60
gnuplot*line3Gray: gray80
gnuplot*line4Gray: gray40
gnuplot*line5Gray: gray90
gnuplot*line6Gray: gray50
gnuplot*line7Gray: gray70
gnuplot*line8Gray: gray30
@end example
@noindent --- LINE_RESOURCES ---
@c ?commands set terminal x11 line_resources
@c ?set terminal x11 line_resources
@c ?set term x11 line_resources
@c ?x11 line_resources
@cindex line_resources
@cindex X resources
`gnuplot` honors the following resources for setting the width (in pixels) of
plot lines (shown here with their default values.) 0 or 1 means a minimal
width line of 1 pixel width. A value of 2 or 3 may improve the appearance of
some plots.
@example
gnuplot*borderWidth: 2
gnuplot*axisWidth: 0
gnuplot*line1Width: 0
gnuplot*line2Width: 0
gnuplot*line3Width: 0
gnuplot*line4Width: 0
gnuplot*line5Width: 0
gnuplot*line6Width: 0
gnuplot*line7Width: 0
gnuplot*line8Width: 0
@end example
`gnuplot` honors the following resources for setting the dash style used for
plotting lines. 0 means a solid line. A two-digit number `jk` (`j` and `k`
are >= 1 and 1 ? 2 : 8),
where num_colormaps is the number of colormaps which are currently used
by gnuplot (usually 1, if only one x11 window is open).
Some systems support multiple (different) visual classes together on one
screen. On these systems it might be necessary to force gnuplot to use a
specific visual class, e.g. the default visual might be 8bit PseudoColor
but the screen would also support 24bit TrueColor which would be the
preferred choice.
The information about an Xserver's capabilities can be obtained with the
program `xdpyinfo`. For the visual names below you can choose one of
StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, DirectColor.
If an Xserver supports a requested visual type at different depths,
`gnuplot` chooses the visual class with the highest depth (deepest).
If the requested visual class matches the default visual and multiple
classes of this type are supported, the default visual is preferred.
Example: on an 8bit PseudoColor visual you can force a private color map
by specifying `gnuplot*maxcolors: 240` and `gnuplot*mincolors: 240`.
@example
gnuplot*maxcolors:
gnuplot*mincolors:
gnuplot*visual:
@end example
, "
@noindent --- X11 OTHER_RESOURCES ---
@c ?commands set terminal x11 other_resources
@c ?set terminal x11 other_resources
@c ?set term x11 other_resources
@c ?x11 other_resources
@cindex X resources
By default the contents of the current plot window are exported to the X11
clipboard in response to X events in the window. Setting the resource
'gnuplot*exportselection' to 'off' or 'false' will disable this.
By default text rotation is done using a method that is fast, but can
corrupt nearby colors depending on the background. If this is a problem,
you can set the resource 'gnuplot.fastrotate' to 'off'
@example
gnuplot*exportselection: off
gnuplot*fastrotate: on
gnuplot*ctrlq: off
@end example
@node xlib, xlib_, x11_, terminal_
@subsubsection xlib
@c ?commands set terminal xlib
@c ?set terminal xlib
@c ?set term xlib
@c ?terminal xlib
@c ?term xlib
@cindex xlib
@tmindex xlib
The `xlib` terminal driver supports the X11 Windows System. It generates
gnuplot_x11 commands, but sends them to the output file specified by
`set output ''`. `set term x11` is equivalent to
`set terminal xlib; set output "|gnuplot_x11 -noevents"`.
`xlib` takes the same set of options as `x11`."
@node xlib_, , xlib, terminal_
@subsubsection xlib
@c ?commands set terminal xlib
@c ?set terminal xlib
@c ?set term xlib
@c ?terminal xlib
@c ?term xlib
@cindex xlib
@tmindex xlib
The `xlib` terminal driver supports the X11 Windows System. It generates
gnuplot_x11 commands, but sends them to the output file specified by
`set output ''`. `set term x11` is equivalent to
`set terminal xlib; set output "|gnuplot_x11 -noevents"`.
`xlib` takes the same set of options as `x11`."
@node Graphical_User_Interfaces, Bugs, Terminal_types, Top
@chapter Graphical User Interfaces
@c ?graphical user interfaces
@cindex gui's
Several graphical user interfaces have been written for `gnuplot` and one for
win32 is included in this distribution.
Bruce Ravel (ravel@@phys.washington.edu) has written a gnuplot-mode for
GNU emacs and XEmacs based on the earlier gnuplot.el file by Gershon Elber.
While the gnuplot CVS repository has its own copy the most recent
version of this package is available from
@uref{http://feff.phys.washington.edu/~ravel/software/gnuplot-mode/,http://feff.phys.washington.edu/~ravel/software/gnuplot-mode/
}
For Python, Tk/Tcl, and other front-ends, check the links on
@uref{http://gnuplot.sourceforge.net/links.html,http://gnuplot.sourceforge.net/links.html
}
@menu
* Bugs::
@end menu
@node Bugs, Concept_Index, Graphical_User_Interfaces, Top
@chapter Bugs
@cindex bugs
Bugs reported since the current release as well as older ones
may be located via the official distribution site on SourceForge.
Please e-mail bug reports to the gnuplot-bugs mailing list.
Or upload the report to the gnuplot web site on SourceForge.
Please give complete information on the version of gnuplot you are using
and, if possible, a test script that demonstrates the bug.
See @ref{Seeking-assistance}.
The sections below list problems known to be present in gnuplot version 4.2 at
the time of release. Some of these are actually bugs in external support
libraries and may have been fixed independent of any changes in gnuplot.
@menu
* Gnuplot_limitations::
* External_libraries::
@end menu
@node Gnuplot_limitations, External_libraries, Bugs, Bugs
@section Gnuplot limitations
@c ?bugs gnuplot
@cindex gamma
@findex gamma
@cindex bessel
@cindex timefmt
@opindex timefmt
@cindex nohidden3d
@cindex floating point exceptions
Floating point exceptions (floating point number too large/small, divide by
zero, etc.) may occasionally be generated by user defined functions. Some of
the demos in particular may cause numbers to exceed the floating point range.
Whether the system ignores such exceptions (in which case `gnuplot` labels
the corresponding point as undefined) or aborts `gnuplot` depends on the
compiler/runtime environment.
The gamma and bessel functions do not work for complex arguments.
Only one color palette at a time is active for any given x11 plot window.
This means that multiplots whose constituent plots use different palettes
will not display correctly in x11.
Coordinates specified as "time" wrap at 24 hours, and have a precision limited
to 1 second. This is in particular a limitation in using time format to
handle geographic coordinates.
Error bars are not handled properly in polar/spherical coordinate plot modes.
The 'nohidden3d' option that is supposed to exempt individual plots from the
global property 'set hidden3d' does not work for parametric curves.
@node External_libraries, , Gnuplot_limitations, Bugs
@section External libraries
@c ?bugs external_libraries
@cindex libgd
@cindex svgalib
@tmindex svgalib
@cindex locale
@opindex locale
@cindex internationalization
@cindex pdf
@tmindex pdf
External library GD (used by PNG/JPEG/GIF drivers):
Versions of libgd through 2.0.33 contain various bugs in mapping the characters
of Adobe's Symbol font. Also it is possible to trigger a library segfault if
an anti-aliased line crosses an upper corner of the canvas.
External library PDFlib (used by PDF driver):
Gnuplot can be linked against libpdf versions 4, 5, or 6. However, these
versions differ in their handling of piped I/O. Therefore gnuplot scripts
using piped output to PDF may work only for some versions of PDFlib.
External library svgalib (used by linux and vgagl driver):
Requires gnuplot to be suid root (bad!) and has many bugs that are specific
to the video card or graphics driver used in X11.
Internationalization (locale settings):
Gnuplot uses the C runtime library routine setlocale() to control
locale-specific formatting of input and output number, times, and date strings.
The locales available, and the level of support for locale features such as
"thousands' grouping separator", depend on the internationalization support
provided by your individual machine.
@node Concept_Index, Command_Index, Bugs, Top
@unnumbered Concept Index
@printindex cp
@node Command_Index, Options_Index, Concept_Index, Top
@unnumbered Command Index
@printindex cm
@node Options_Index, Function_Index, Command_Index, Top
@unnumbered Options Index
@printindex op
@node Function_Index, Terminal_Index, Options_Index, Top
@unnumbered Function Index
@printindex fn
@node Terminal_Index, , Function_Index, Top
@unnumbered Terminal Index
@printindex tm
@c @shortcontents
@contents
@bye