1 C RCS $Id: gnuplot.doc,v 1.387.2.51 2009/05/18 02:47:35 sfeam Exp $
3 C Copyright (C) 1986 - 1993, 1998, 1999, 2000, 2001, 2004 Thomas Williams, Colin Kelley et al.
5 ^ <h2> An Interactive Plotting Program </h2><p>
6 ^ <h2> Thomas Williams & Colin Kelley</h2><p>
7 ^ <h2> Version 4.2 organized by Hans-Bernhard Broeker and others</h2><p>
8 ^ <h2>Major contributors (alphabetic order):</h2>
10 ^<li> Hans-Bernhard Broeker
12 ^<li> Robert Cunningham
23 ^<li> Alexander Lehmann
29 ^<li> Jos Van der Woude
31 ^<li> James R. Van Zandt
32 ^<li> Johannes Zellner
34 ^<h2> Copyright (C) 1986 - 1993, 1998 - 2004 Thomas Williams, Colin Kelley<p>
35 ^ Mailing list for comments: gnuplot-info@lists.sourceforge.net <p>
36 ^ Mailing list for bug reports: gnuplot-bugs@lists.sourceforge.net <p>
38 ^<h3> This manual was prepared by Dick Crawford</h3><p>
39 ^<h3> Last revised: February 2007</h3><p>
45 Copyright (C) 1986 - 1993, 1998, 2004, 2007 Thomas Williams, Colin Kelley
47 Permission to use, copy, and distribute this software and its
48 documentation for any purpose with or without fee is hereby granted,
49 provided that the above copyright notice appear in all copies and
50 that both that copyright notice and this permission notice appear
51 in supporting documentation.
53 Permission to modify the software is granted, but not the right to
54 distribute the complete modified source code. Modifications are to
55 be distributed as patches to the released version. Permission to
56 distribute binaries produced by compiling modified sources is granted,
58 1. distribute the corresponding source modifications from the
59 released version in the form of a patch file along with the binaries,
60 2. add special version identification to distinguish your version
61 in addition to the base release version number,
62 3. provide your name and address as the primary contact for the
63 support of your modified version, and
64 4. retain our contact information in regard to use of the base
66 Permission to distribute the released version of the source code along
67 with corresponding source modifications in the form of a patch file is
68 granted with same provisions 2 through 4 for binary distributions.
70 This software is provided "as is" without express or implied warranty
71 to the extent permitted by applicable law.
77 Thomas Williams, Colin Kelley.
79 Gnuplot 2.0 additions:
80 Russell Lang, Dave Kotz, John Campbell.
82 Gnuplot 3.0 additions:
83 Gershon Elber and many others.
85 Gnuplot 4.0 additions:
86 See list of contributors at head of this document.
90 `gnuplot` is a command-driven interactive function and data plotting program.
92 Any command-line arguments are assumed to be names of files containing
93 `gnuplot` commands, with the exception of standard X11 arguments, which are
94 processed first. Each file is loaded with the `load` command, in the order
95 specified. `gnuplot` exits after the last file is processed. The special
96 filename "-" is used to denote standard input. When no load files are named,
97 `gnuplot` enters into an interactive mode. See help for `batch/interactive`
100 `gnuplot` is case sensitive (commands and function names written in lowercase
101 are not the same as those written in CAPS). All command names may be
102 abbreviated as long as the abbreviation is not ambiguous. Any number of
103 commands may appear on a line (with the exception that `load` or `call` must
104 be the final command), separated by semicolons (;). Strings are indicated
105 with quotes. They may be either single or double quotation marks, e.g.,
110 although there are some subtle differences (see `syntax` for more details).
112 Many `gnuplot` commands have multiple options. Version 4 is less sensitive
113 to the order of these options than earlier versions, but some order-dependence
114 remains. If you see error messages about unrecognized options, please try
115 again using the exact order listed in the documentation.
117 Commands may extend over several input lines by ending each line but the last
118 with a backslash (\). The backslash must be the _last_ character on each
119 line. The effect is as if the backslash and newline were not there. That
120 is, no white space is implied, nor is a comment terminated. Therefore,
121 commenting out a continued line comments out the entire command
122 (see `comments`). But note that if an error occurs somewhere on a multi-line
123 command, the parser may not be able to locate precisely where the error is
124 and in that case will not necessarily point to the correct line.
126 In this document, curly braces ({}) denote optional arguments and a vertical
127 bar (|) separates mutually exclusive choices. `gnuplot` keywords or `help`
128 topics are indicated by backquotes or `boldface` (where available). Angle
129 brackets (<>) are used to mark replaceable tokens. In many cases, a default
130 value of the token will be taken for optional arguments if the token is
131 omitted, but these cases are not always denoted with braces around the angle
134 For on-line help on any topic, type `help` followed by the name of the topic
135 or just `help` or `?` to get a menu of available topics.
137 The new `gnuplot` user should begin by reading about `plotting` (if on-line,
138 type `help plotting`).
140 See the simple.dem demo, also available together with other demos on the web page
141 ^ <a href="http://www.gnuplot.info/demo/simple.html">
142 http://www.gnuplot.info/demo/simple.html
145 ^ <a name="Seeking-assistance"></a>
148 There is a mailing list for `gnuplot` users. Note, however, that the
150 comp.graphics.apps.gnuplot
151 is identical to the mailing list (they both carry the same set of messages).
152 We prefer that you read the messages through the newsgroup rather than
153 subscribing to the mailing list. Instructions for subscribing to gnuplot
154 mailing lists may be found via the gnuplot development website on SourceForge
155 ^ <a href="http://sourceforge.net/projects/gnuplot">
156 http://sourceforge.net/projects/gnuplot
159 The address for mailing to list members is:
160 gnuplot-info@lists.sourceforge.net
162 Bug reports and code contributions should be mailed to:
163 gnuplot-bugs@lists.sourceforge.net
165 The list of those interested in beta-test versions is:
166 gnuplot-beta@lists.sourceforge.net
168 There is also the canonical (if occasionally out-of-date) gnuplot web page at
170 ^ <a href="http://www.gnuplot.info">
171 http://www.gnuplot.info
174 Before seeking help, please check the
176 ^ <a href="http://www.gnuplot.info/faq/">
177 FAQ (Frequently Asked Questions) list.
180 When posting a question, please include full details of the version of
181 `gnuplot`, the machine, and operating system you are using. A _small_ script
182 demonstrating the problem may be useful. Function plots are preferable to
183 datafile plots. If email-ing to gnuplot-info, please state whether or not
184 you are subscribed to the list, so that users who use news will know to email
185 a reply to you. There is a form for such postings on the WWW site.
187 2 New features introduced in version 4.2
189 ?version 4.2 features
190 Gnuplot version 4.2 offers many new features introduced since the preceding
191 official version 4.0. This section lists major additions and gives a partial
192 list of changes and minor new features. For a more exhaustive list, see the
198 Histograms, or bar charts, can be produced.
202 In coordination with the new `datastrings` feature described below, gnuplot
203 can draw a label at each vertex of a curve.
207 The `image` and `rgbimage` styles allow to plot 2D images (from ascii or
208 `binary` files) and map them in a 2D or 3D plot.
209 See `image` and `rgbimage`.
212 The plot style `fillstyle` has been augmented to allow to fill the area
213 between two input curves with a color or a pattern.
217 Gnuplot can draw plots with vectors with a small arrowhead, requiring four or
218 six columns of data for 2D or 3D, respectively.
221 3 Input from binary data files
222 Gnuplot can now read a generic `binary` input, including matrix binary and
223 `general binary` (until now gnuplot supported only its own `binary matrix`
224 format). Several matrix file formats are autodetected (`gpbin`, `edf`, `avs`).
225 Binary data files are mainly useful for `image` and `rgbimage` drawings.
226 See `binary` and `binary general filetype`.
231 Explicit RGB colors can be specified for all plot elements instead of
232 specifying a predefined linetype.
235 4 Arbitrary rectangles
236 You can place rectangles with desired fill style and border anywhere in a 2D
238 See `set object rectangle`.
241 4 String and text data read from datafiles
242 Gnuplot can now read and process text fields in datafiles.
244 4 User-defined string variables, operators, and functions
245 String variables and string functions are introduced. Most gnuplot commands
246 that previously required a string constant will now also accept a string
247 variable, a string expression, or a function that returns a string.
248 See `string variables`.
251 Gnuplot supports command line macro expansion by '@stringvariablename'.
254 3 Auto-layout of multiple plots on a page
255 The `multiplot` mode is now able to layout automatically simple
256 multiplots without having to set the size or the position for each plot.
260 Gnuplot now exports several "read-only" variables such as GPVAL_TERM,
262 See `gnuplot-defined variables`.
264 3 New or revised terminal drivers
266 The `wxt` terminal is an interactive and cross-platform terminal for on-screen
267 rendering. It uses the wxWidgets library for its user interface, and Cairo
268 associated with Pango for the actual rendering, providing nice plots with
269 antialiasing on lines and text. The terminal supports the full range of
270 gnuplot capabilities, including mousing, pm3d plots, image plots and
273 The `emf` terminal generates an Enhanced Metafile Format file. This file
274 format is the metafile standard on MS Win32 Systems. The emf terminal
275 supports pm3d, rgb color, and image plot modes.
276 4 `gif`, `jpeg`, `png`
277 The code for the terminals using the `gd` library has been consolidated.
278 The `gif` terminal also knows how to produce an animated gif from a sequence
281 The `postscript` terminal can load prologue files, which can contain
282 additional user-defined sections with, for example, character encodings.
283 See `postscript prologue`.
285 The Adobe Illustrator `ai` driver is outdated. Since Adobe Illustrator
286 understands PostScript files, `set terminal post level1 ...` should be used
288 4 `epslatex`, `pslatex`, `pstex`
289 The terminals supporting an output to latex augmented by PostScript commands
290 have been consolidated. Many options are the same as in the `postscript`
293 The `windows` terminal now supports the `enhanced text` mode.
300 In earlier versions of gnuplot, some terminal types used the values from
301 `set size` to control also the size of the output canvas; others did not.
302 The use of 'set size' for this purpose was deprecated in version 4.2.
303 In version 4.3 almost all terminals now behave as follows:
305 `set term <terminal_type> size <XX>, <YY>` controls the size of the output
306 file, or "canvas". Please see individual terminal documentation for allowed
307 values of the size parameters. By default, the plot will fill this canvas.
309 `set size <XX>, <YY>` scales the plot itself relative to the size of the
310 canvas. Scale values less than 1 will cause the plot to not fill the entire
311 canvas. Scale values larger than 1 will cause only a portion of the plot to
312 fit on the canvas. Please be aware that setting scale values larger than 1
313 may cause problems on some terminal types.
315 The major exception to this convention is the PostScript driver, which
316 by default continues to act as it has in earlier versions. Be warned that
317 the next version of gnuplot may change the default behaviour of the
318 PostScript driver as well.
323 set term png size 600, 400
324 set output "figure.png"
325 plot "data" with lines
327 These commands will produce an output file "figure.png" that is 600 pixels
328 wide and 400 pixels tall. The plot will fill the lower left quarter of this
329 canvas. This is consistent with the way multiplot mode has always worked,
330 however it is a change in the way the png driver worked for single plots in
333 2 Backwards compatibility
334 ?backwards compatibility
336 Gnuplot version 4.0 deprecated certain syntax used in earlier versions, but
337 continued to recognize it. This is now under the control of a configuration
338 option, and can be disabled as follows:
340 ./configure --disable-backwards-compatibility
342 Notice: Deprecated syntax items may be disabled permanently in some future
345 One major difference is the introduction of keywords to disambiguate complex
346 commands, particularly commands containing string variables. A notable issue
347 was the use of bare numbers to specify offsets, line and point types.
348 Illustrative examples:
353 plot 1 2 4 # horizontal line at y=1
356 set title TITLE offset char 0, char -1
357 set style data linespoints
358 plot 1 linetype 2 pointtype 4
360 Another compatibility issue is the effect of the command `set size` outside
361 when not in multiplot mode. In earlier versions, the command
362 `set size <xx>, <yy>` caused some terminals to change both the size of the plot
363 and the size of the canvas is was drawn on; other terminatls changed only the
364 plot size. The use of `set size` to change the canvas size is now deprecated.
366 Please see `set size`, `set term size` and also the documentation for
367 individual terminals.
369 2 Features introduced in version 4.0
371 Gnuplot version 4.0 contained many features introduced since the preceding
372 official version 3.7. These are summarized here.
374 3 Mouse and hotkey support in interactive terminals
376 Interaction with the current plot via mouse and hotkeys is supported for the
377 X11, OS/2 Presentation Manager, ggi, Windows, and wxWidgets terminals. See
378 `mouse input` for more information on mousing. See help for `bind` for
379 information on hotkeys. Also see the documentation for individual mousing
380 terminals `ggi`, `pm`, `windows`, `wxt` and `x11`.
382 Sample script: mousevariables.dem
386 `aqua`: New terminal for Mac OS X. Requires AquaTerm 1.0 or later.
388 `epslatex`: New terminal. Prepares eps figures for inclusion in LaTeX
391 `gif`: Consolidated with png/jpeg terminals. Requires libgd.
393 `ggi`: New full-screen interactive terminal for Linux. Interface to the
394 General Graphics Interface Library.
396 `pdf`: New terminal exporting Adobe Portable Document Format. Requires libpdf.
398 `png` and `jpeg`: Support for GIF, PNG and JPEG image output is provided by a
399 new driver via libgd. The new driver supports many more features than the
400 old png driver, including TrueType fonts. Requires libgd.
402 `svg`: New terminal exporting Scalable Vector Graphics.
404 3 New plot style `pm3d`
406 The `splot` command is now capable of plotting 2D maps and 3D surfaces
407 colored by greyscale or color palettes. See help for `set pm3d`, `set palette`,
408 `set cbrange`, `set view map`, `set colorbox` and `test palette`.
410 Sample scripts: pm3d.dem pm3dcolors.dem pm3dgamma.dem
414 A solid color or patterned fill style can be set for any plot style that
415 contains boxes. See `boxes`, `boxerrorbars`, `boxxyerrorbars`,
416 `candlesticks`, `set style fill`.
418 Sample scripts: fillstyle.dem candlesticks.dem
420 3 New plot option smooth frequency
422 Input data can be filtered through several built-in routines for interpolation
423 or approximation of data. See `smooth`, `frequency`, `unique`.
425 Sample scripts: steps.dem mgr.dem
427 3 Improved text options
429 Most gnuplot plot commands that produce text labels now accept modifiers to
430 specify text color, font, size, and rotation angle. See `set label`.
431 Not all terminal types support these options, however. The enhanced text
432 mode previously available for the postscript and pm terminals has been
433 extended to other terminal types as well. Terminal types currently supported
434 include aqua, dumb, jpeg, pdf, pm, png, postscript, x11, windows, and wxt.
437 Sample scripts: textcolor.dem textrotate.dem
439 3 More text encodings
441 Several terminals, including `postscript`, `x11` and `pm`, support additional
442 text `encodings`: ISO 8859-1 (Latin 1), ISO 8859-2 (Latin 2), ISO 8859-15
443 (variant of 8859-1 with Euro sign), KOI8-R and KOI8-U (cyrillic), and
444 miscellaneous codepages. See `encoding` for more details.
448 Single- or double-ended arrows can be placed on a plot individually from the
449 command line or from a data file via the `plot with vectors` style.
450 See `set style arrow`, `plotting styles vectors`.
452 Sample scripts: arrowstyle.dem vector.dem
456 The new `set datafile` command can be used to specify information about the
457 format of input data files, including the characters used to separate fields,
458 to indicate comment lines, and to specify missing data. Gnuplot now attempts
459 to recognize text fields with embedded blanks as single entities based on the
460 datafile format settings. This allows input from csv (comma-separated value)
461 files such as those exported by spreadsheet programs. See `set datafile`.
462 See also the `binary` option (introduced in 4.2).
466 `set view map` selects a top-view 2D projection of 3D surface plot.
468 `set term push` and `set term pop` save and restore the current terminal type.
470 `load` and `save` commands accept piped input and output, respectively.
472 3 Other changes and additions
474 Since gnuplot 4.0, `unset <something>` is preferred to `set no<something>`.
475 The older form has been deprecated.
476 Version 4.2 continues to allow the older syntax, but such backwards
477 compatibility may be lost in future versions.
479 Commands of the form `set <something> <style>` also are deprecated in favor
480 of the more general form `set style <something> <options>`. Many more plot
481 elements now have style options of their own, including arrows, filled
482 areas, lines, and points. There are also style settings for input data and
483 formatting. Please see `set style`, `set decimalsign`, and `set datafile`.
485 The MS Windows package includes an additional executable `pgnuplot.exe` to
486 support piping command through standard input, which is otherwise not
487 available for graphical applications on this system.
489 3 Accompanying documentation
491 In directory docs/psdocs/ you may find new information in the gnuplot output
492 postscript file guide, list of postscript symbols in different encodings.
494 Improved FAQ. Please read it before asking your question in a public forum.
496 There are plenty of new demos *.dem in the demo/ directory. Please run them,
499 before asking for help. Plots produced by the demo scripts can also be viewed
501 ^ <a href="http://www.gnuplot.info/demo/">
502 http://www.gnuplot.info/demo/
505 2 Batch/Interactive Operation
507 `gnuplot` may be executed in either batch or interactive modes, and the two
508 may even be mixed together on many systems.
510 Any command-line arguments are assumed to be names of files containing
511 `gnuplot` commands (with the exception of standard X11 arguments, which are
512 processed first). Each file is loaded with the `load` command, in the order
513 specified. `gnuplot` exits after the last file is processed. When no load
514 files are named, `gnuplot` enters into an interactive mode. The special
515 filename "-" is used to denote standard input.
517 Both the `exit` and `quit` commands terminate the current command file and
518 `load` the next one, until all have been processed.
522 To launch an interactive session:
525 To launch a batch session using two command files "input1" and "input2":
526 gnuplot input1 input2
528 To launch an interactive session after an initialization file "header" and
529 followed by another command file "trailer":
530 gnuplot header - trailer
531 2 Command-line-editing
534 ?command-line-editing
535 Command-line editing is supported by the Unix, Atari, VMS, MS-DOS and OS/2
536 versions of `gnuplot`. Also, a history mechanism allows previous commands to
537 be edited and re-executed. After the command line has been edited, a newline
538 or carriage return will enter the entire line without regard to where the
539 cursor is positioned.
541 (The readline function in `gnuplot` is not the same as the readline used in
542 GNU Bash and GNU Emacs. If the GNU version is desired, it may be selected
543 instead of the `gnuplot` version at compile time.)
546 The editing commands are as follows:
548 @start table - first is interactive cleartext form
551 ^B moves back a single character.
552 ^F moves forward a single character.
553 ^A moves to the beginning of the line.
554 ^E moves to the end of the line.
555 ^H and DEL delete the previous character.
556 ^D deletes the current character.
557 ^K deletes from current position to the end of line.
558 ^L,^R redraws line in case it gets trashed.
559 ^U deletes the entire line.
560 ^W deletes from the current word to the end of line.
564 ^P moves back through history.
565 ^N moves forward through history.
566 #\begin{tabular}{|cl|} \hline
567 #\multicolumn{2}{|c|}{Command-line Editing Commands} \\ \hline \hline
568 #Character & Function \\ \hline
569 # & \multicolumn{1}{|c|}{Line Editing}\\ \cline{2-2}
570 #\verb~^B~ & move back a single character.\\
571 #\verb~^F~ & move forward a single character.\\
572 #\verb~^A~ & move to the beginning of the line.\\
573 #\verb~^E~ & move to the end of the line.\\
574 #\verb~^H, DEL~ & delete the previous character.\\
575 #\verb~^D~ & delete the current character.\\
576 #\verb~^K~ & delete from current position to the end of line.\\
577 #\verb~^L, ^R~ & redraw line in case it gets trashed.\\
578 #\verb~^U~ & delete the entire line. \\
579 #\verb~^W~ & delete from the current word to the end of line. \\ \hline
580 # & \multicolumn{1}{|c|}{History} \\ \cline{2-2}
581 #\verb~^P~ & move back through history.\\
582 #\verb~^N~ & move forward through history.\\
587 %^B@move back a single character.
588 %^F@move forward a single character.
589 %^A@move to the beginning of the line.
590 %^E@move to the end of the line.
591 %^H, DEL@delete the previous character.
592 %^D@delete the current character.
593 %^K@delete from current position to the end of line.
594 %^L, ^R@redraw line in case it gets trashed.
595 %^U@delete the entire line.
596 %^W@delete from the current word to the end of line.
599 %^P@move back through history.
600 %^N@move forward through history.
603 On the IBM PC, the use of a TSR program such as DOSEDIT or CED may be desired
604 for line editing. The default makefile assumes that this is the case; by
605 default `gnuplot` will be compiled with no line-editing capability. If you
606 want to use `gnuplot`'s line editing, set READLINE in the makefile and add
607 readline.obj to the link file. The following arrow keys may be used on the
608 IBM PC and Atari versions if readline is used:
610 @start table - first is interactive cleartext form
611 Left Arrow - same as ^B.
612 Right Arrow - same as ^F.
613 Ctrl Left Arrow - same as ^A.
614 Ctrl Right Arrow - same as ^E.
615 Up Arrow - same as ^P.
616 Down Arrow - same as ^N.
617 #\begin{tabular}{|cl|} \hline
618 #Arrow key & Function \\ \hline
619 #Left & same as \verb~^B~. \\
620 #Right & same as \verb~^F~. \\
621 #Ctrl Left & same as \verb~^A~. \\
622 #Ctrl Right & same as \verb~^E~. \\
623 #Up & same as \verb~^P~. \\
624 #Down & same as \verb~^N~. \\
628 %Left Arrow@same as ^B.
629 %Right Arrow@same as ^F.
630 %Ctrl Left Arrow@same as ^A.
631 %Ctrl Right Arrow@same as ^E.
632 %Up Arrow@same as ^P.
633 %Down Arrow@same as ^N.
637 The Atari version of readline defines some additional key aliases:
639 @start table - first is interactive cleartext form
642 Ctrl Home - same as ^E.
644 Help - `help` plus return.
646 #\begin{tabular}{|cl|} \hline
647 #Key & Function \\ \hline
648 #Undo & same as \verb~^L~. \\
649 #Home & same as \verb~^A~. \\
650 #Ctrl Home & same as \verb~^E~. \\
651 #Esc & same as \verb~^U~. \\
652 #Help & `{\bf help}` plus return. \\
653 #Ctrl Help & `{\bf help}`. \\
659 %Ctrl Home@same as ^E.
661 %Help@help plus return.
667 Comments are supported as follows: a `#` may appear in most places in a line
668 and `gnuplot` will ignore the rest of the line. It will not have this effect
669 inside quotes, inside numbers (including complex numbers), inside command
670 substitutions, etc. In short, it works anywhere it makes sense to work.
672 See also `set datafile commentschars` for specifying comment characters in
676 The commands `set arrow`, `set key`, `set label` and `set object` allow you
677 to draw something at an arbitrary position on the graph. This position is
678 specified by the syntax:
680 {<system>} <x>, {<system>} <y> {,{<system>} <z>}
682 Each <system> can either be `first`, `second`, `graph`, `screen`, or
685 `first` places the x, y, or z coordinate in the system defined by the left
686 and bottom axes; `second` places it in the system defined by the second axes
687 (top and right); `graph` specifies the area within the axes---0,0 is bottom
688 left and 1,1 is top right (for splot, 0,0,0 is bottom left of plotting area;
689 use negative z to get to the base---see `set ticslevel`); `screen`
690 specifies the screen area (the entire area---not just the portion selected by
691 `set size`), with 0,0 at bottom left and 1,1 at top right; and `character`
692 gives the position in character widths and heights from the bottom left of
693 the screen area (screen 0,0), `character` coordinates depend on the chosen
696 If the coordinate system for x is not specified, `first` is used. If the
697 system for y is not specified, the one used for x is adopted.
699 In some cases, the given coordinate is not an absolute position but a
700 relative value (e.g., the second position in `set arrow` ... `rto`). In
701 most cases, the given value serves as difference to the first position.
702 If the given coordinate resides in a logarithmic axis the value is
703 interpreted as factor. For example,
706 set arrow 100,5 rto 10,2
708 plots an arrow from position 100,5 to position 1000,7 since the x axis is
709 logarithmic while the y axis is linear.
711 If one (or more) axis is timeseries, the appropriate coordinate should
712 be given as a quoted time string according to the `timefmt` format string.
713 See `set xdata` and `set timefmt`. `gnuplot` will also accept an integer
714 expression, which will be interpreted as seconds from 1 January 2000.
717 The configuration option --enable-datastrings allows gnuplot to read and
718 process text fields in datafiles. A text field consists of either an arbitrary
719 string of printable characters containing no whitespace or an arbitrary string
720 of characters, possibly including whitespace, delimited by double quotes.
721 The following sample line from a datafile is interpreted to contain four
722 columns, with a text field in column 3:
724 1.000 2.000 "Third column is all of this text" 4.00
726 Text fields can be positioned within a 2-D or 3-D plot using the commands:
728 plot 'datafile' using 1:2:4 with labels
729 splot 'datafile using 1:2:3:4 with labels
731 A column of text data can also be used to label the ticmarks along one or more
732 of the plot axes. The example below plots a line through a series of points
733 with (X,Y) coordinates taken from columns 3 and 4 of the input datafile.
734 However, rather than generating regularly spaced tics along the x axis
735 labeled numerically, gnuplot will position a tic mark along the x axis at the
736 X coordinate of each point and label the tic mark with text taken from column
737 1 of the input datafile.
740 plot 'datafile' using 3:4:xticlabels(1) with linespoints
742 There is also an option that will interpret the first entry in a column of
743 input data as a text field, and use it as the key title for data plotted from
744 that column. The example given below will use the first entry in column 2 to
745 generate a title in the key box, while processing the remainder of columns
746 2 and 4 to draw the required line:
748 plot 'datafile' using 1:(f($2)/$4) title 2 with lines
750 See `set style labels`, `using xticlabels`, `plot title`, `using`.
753 A number of shell environment variables are understood by `gnuplot`. None of
754 these are required, but may be useful.
756 If GNUTERM is defined, it is used as the name of the terminal type to be
757 used. This overrides any terminal type sensed by `gnuplot` on start-up, but
758 is itself overridden by the .gnuplot (or equivalent) start-up file
759 (see `start-up`) and, of course, by later explicit changes.
761 On Unix, AmigaOS, AtariTOS, MS-DOS and OS/2, GNUHELP may be defined to be the
762 pathname of the HELP file (gnuplot.gih).
764 On VMS, the logical name GNUPLOT$HELP should be defined as the name of the
765 help library for `gnuplot`. The `gnuplot` help can be put inside any system
766 help library, allowing access to help from both within and outside `gnuplot`
769 On Unix, HOME is used as the name of a directory to search for a .gnuplot
770 file if none is found in the current directory. On AmigaOS, AtariTOS,
771 MS-DOS, Windows and OS/2, GNUPLOT is used. On Windows, the NT-specific
772 variable USERPROFILE is tried, too. VMS, SYS$LOGIN: is used. Type `help
775 On Unix, PAGER is used as an output filter for help messages.
777 On Unix, AtariTOS and AmigaOS, SHELL is used for the `shell` command. On
778 MS-DOS and OS/2, COMSPEC is used for the `shell` command.
780 On MS-DOS, if the BGI or Watcom interface is used, PCTRM is used to tell
781 the maximum resolution supported by your monitor by setting it to
782 S<max. horizontal resolution>. E.g. if your monitor's maximum resolution is
785 If PCTRM is not set, standard VGA is used.
787 FIT_SCRIPT may be used to specify a `gnuplot` command to be executed when a
788 fit is interrupted---see `fit`. FIT_LOG specifies the default filename of the
789 logfile maintained by fit.
791 GNUPLOT_LIB may be used to define additional search directories for data
792 and command files. The variable may contain a single directory name, or
793 a list of directories separated by a platform-specific path separator,
794 eg. ':' on Unix, or ';' on DOS/Windows/OS/2/Amiga platforms. The contents
795 of GNUPLOT_LIB are appended to the `loadpath` variable, but not saved
796 with the `save` and `save set` commands.
798 Several gnuplot terminal drivers access TrueType fonts via the gd library.
799 For these drivers the font search path is controlled by the environmental
800 variable GDFONTPATH. Furthermore, a default font for these drivers may be
801 set via the environmental variable GNUPLOT_DEFAULT_GDFONT.
803 The postscript terminal uses its own font search path. It is controlled by
804 the environmental variable GNUPLOT_FONTPATH. The format is the same as for
805 GNUPLOT_LIB. The contents of GNUPLOT_FONTPATH are appended to the `fontpath`
806 variable, but not saved with the `save` and `save set` commands.
808 GNUPLOT_PS_DIR is used by the postscript driver to use external prologue
809 files. Depending on the build process, gnuplot contains either a builtin
810 copy of those files or simply a default hardcoded path. Use this variable
811 to test the postscript terminal with custom prologue files. See
812 `postscript prologue`.
815 In general, any mathematical expression accepted by C, FORTRAN, Pascal, or
816 BASIC is valid. The precedence of these operators is determined by the
817 specifications of the C programming language. White space (spaces and tabs)
818 is ignored inside expressions.
820 Complex constants are expressed as {<real>,<imag>}, where <real> and <imag>
821 must be numerical constants. For example, {3,2} represents 3 + 2i; {0,1}
822 represents 'i' itself. The curly braces are explicitly required here.
824 Note that gnuplot uses both "real" and "integer" arithmetic, like FORTRAN and
825 C. Integers are entered as "1", "-10", etc; reals as "1.0", "-10.0", "1e1",
826 3.5e-1, etc. The most important difference between the two forms is in
827 division: division of integers truncates: 5/2 = 2; division of reals does
828 not: 5.0/2.0 = 2.5. In mixed expressions, integers are "promoted" to reals
829 before evaluation: 5/2e0 = 2.5. The result of division of a negative integer
830 by a positive one may vary among compilers. Try a test like "print -5/2" to
831 determine if your system chooses -2 or -3 as the answer.
833 The integer expression "1/0" may be used to generate an "undefined" flag,
834 which causes a point to ignored; the `ternary` operator gives an example.
835 Or you can use the pre-defined variable NaN to achieve the same result.
838 The real and imaginary parts of complex expressions are always real, whatever
839 the form in which they are entered: in {3,2} the "3" and "2" are reals, not
842 Gnuplot can also perform simple operations on strings and string variables.
843 For example, the expression ("A" . "B" eq "AB") evaluates as true, illustrating
844 the string concatenation operator and the string equality operator.
846 A string which contains a numerical value is promoted to the corresponding
847 integer or real value if used in a numerical expression. Thus ("3" + "4" == 7)
848 and (6.78 == "6.78") both evaluate to true. An integer, but not a real or
849 complex value, is promoted to a string if used in string concatenation.
850 A typical case is the use of integers to construct file names or other strings;
851 e.g. ("file" . 4 eq "file4") is true.
853 Substrings can be specified using a postfixed range descriptor [beg:end].
854 For example, "ABCDEF"[3:4] == "CD" and "ABCDEF"[4:*] == "DEF"
855 The syntax "string"[beg:end] is exactly equivalent to calling the built-in
856 string-valued function substr("string",beg,end), except that you cannot
857 omit either beg or end from the function call.
859 ?expressions functions
861 The functions in `gnuplot` are the same as the corresponding functions in
862 the Unix math library, except that all functions accept integer, real, and
863 complex arguments, unless otherwise noted.
865 For those functions that accept or return angles that may be given in either
866 degrees or radians (sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
867 atan2(x) and arg(z)), the unit may be selected by `set angles`, which
871 #\begin{tabular}{|ccl|} \hline
872 #\multicolumn{3}{|c|}{Math library functions} \\ \hline \hline
873 #Function & Arguments & Returns \\ \hline
875 %Function@Arguments@Returns
878 ?expressions functions abs
881 #abs(x) & any & absolute value of $x$, $|x|$; same type \\
882 #abs(x) & complex & length of $x$, $\sqrt{{\mbox{real}(x)^{2} +
883 #\mbox{imag}(x)^{2}}}$ \\
884 %abs(x)@any@absolute value of $x$, $|x|$; same type
885 %abs(x)@complex@length of $x$, $sqrt{roman real (x) sup 2 + roman imag (x) sup 2}$
886 The `abs(x)` function returns the absolute value of its argument. The
887 returned value is of the same type as the argument.
889 For complex arguments, abs(x) is defined as the length of x in the complex
890 plane [i.e., sqrt(real(x)**2 + imag(x)**2) ].
892 ?expressions functions acos
895 #acos(x) & any & $\cos^{-1} x$ (inverse cosine) \\
896 %acos(x)@any@$cos sup -1 x$ (inverse cosine)
897 The `acos(x)` function returns the arc cosine (inverse cosine) of its
898 argument. `acos` returns its argument in radians or degrees, as selected by
901 ?expressions functions acosh
904 #acosh(x) & any & $\cosh^{-1} x$ (inverse hyperbolic cosine) in radians \\
905 %acosh(x)@any@$cosh sup -1 x$ (inverse hyperbolic cosine) in radians
906 The `acosh(x)` function returns the inverse hyperbolic cosine of its argument
909 ?expressions functions arg
912 #arg(x) & complex & the phase of $x$ \\
913 %arg(x)@complex@the phase of $x$
914 The `arg(x)` function returns the phase of a complex number in radians or
915 degrees, as selected by `set angles`.
917 ?expressions functions asin
920 #asin(x) & any & $\sin^{-1} x$ (inverse sin) \\
921 %asin(x)@any@$sin sup -1 x$ (inverse sin)
922 The `asin(x)` function returns the arc sin (inverse sin) of its argument.
923 `asin` returns its argument in radians or degrees, as selected by `set
926 ?expressions functions asinh
929 #asinh(x) & any & $\sinh^{-1} x$ (inverse hyperbolic sin) in radians \\
930 %asinh(x)@any@$sinh sup -1 x$ (inverse hyperbolic sin) in radians
931 The `asinh(x)` function returns the inverse hyperbolic sin of its argument in
934 ?expressions functions atan
937 #atan(x) & any & $\tan^{-1} x$ (inverse tangent) \\
938 %atan(x)@any@$tan sup -1 x$ (inverse tangent)
939 The `atan(x)` function returns the arc tangent (inverse tangent) of its
940 argument. `atan` returns its argument in radians or degrees, as selected by
943 ?expressions functions atan2
946 #atan2(y,x) & int or real & $\tan^{-1} (y/x)$ (inverse tangent) \\
947 %atan2(y,x)@int or real@$tan sup -1 (y/x)$ (inverse tangent)
948 The `atan2(y,x)` function returns the arc tangent (inverse tangent) of the
949 ratio of the real parts of its arguments. `atan2` returns its argument in
950 radians or degrees, as selected by `set angles`, in the correct quadrant.
952 ?expressions functions atanh
955 #atanh(x) & any & $\tanh^{-1} x$ (inverse hyperbolic tangent) in radians \\
956 %atanh(x)@any@$tanh sup -1 x$ (inverse hyperbolic tangent) in radians
957 The `atanh(x)` function returns the inverse hyperbolic tangent of its
960 ?expressions functions besj0
963 #besj0(x) & int or real & $j_{0}$ Bessel function of $x$, in radians \\
964 %besj0(x)@int or real@$j sub 0$ Bessel function of $x$, in radians
965 The `besj0(x)` function returns the j0th Bessel function of its argument.
966 `besj0` expects its argument to be in radians.
968 ?expressions functions besj1
971 #besj1(x) & int or real & $j_{1}$ Bessel function of $x$, in radians \\
972 %besj1(x)@int or real@$j sub 1$ Bessel function of $x$, in radians
973 The `besj1(x)` function returns the j1st Bessel function of its argument.
974 `besj1` expects its argument to be in radians.
976 ?expressions functions besy0
979 #besy0(x) & int or real & $y_{0}$ Bessel function of $x$, in radians \\
980 %besy0(x)@int or real@$y sub 0$ Bessel function of $x$, in radians
981 The `besy0(x)` function returns the y0th Bessel function of its argument.
982 `besy0` expects its argument to be in radians.
984 ?expressions functions besy1
987 #besy1(x) & int or real & $y_{1}$ Bessel function of $x$, in radians \\
988 %besy1(x)@int or real@$y sub 1$ Bessel function of $x$, in radians
989 The `besy1(x)` function returns the y1st Bessel function of its argument.
990 `besy1` expects its argument to be in radians.
992 ?expressions functions ceil
995 #ceil(x) & any & $\lceil x \rceil$, smallest integer not less than $x$
997 %ceil(x)@any@$left ceiling x right ceiling$, smallest integer not less than $x$ (real part)
998 The `ceil(x)` function returns the smallest integer that is not less than its
999 argument. For complex numbers, `ceil` returns the smallest integer not less
1000 than the real part of its argument.
1002 ?expressions functions cos
1005 #cos(x) & any & $\cos x$, cosine of $x$ \\
1006 %cos(x)@radians@$cos~x$, cosine of $x$
1007 The `cos(x)` function returns the cosine of its argument. `cos` accepts its
1008 argument in radians or degrees, as selected by `set angles`.
1010 ?expressions functions cosh
1013 #cosh(x) & any & $\cosh x$, hyperbolic cosine of $x$ in radians \\
1014 %cosh(x)@any@$cosh~x$, hyperbolic cosine of $x$ in radians
1015 The `cosh(x)` function returns the hyperbolic cosine of its argument. `cosh`
1016 expects its argument to be in radians.
1018 ?expressions functions erf
1021 #erf(x) & any & $\mbox{erf}(\mbox{real}(x))$, error function of real($x$) \\
1022 %erf(x)@any@$erf ( roman real (x))$, error function of real ($x$)
1023 The `erf(x)` function returns the error function of the real part of its
1024 argument. If the argument is a complex value, the imaginary component is
1025 ignored. See `erfc`, `inverf`, and `norm`.
1027 ?expressions functions erfc
1030 #erfc(x) & any & $\mbox{erfc}(\mbox{real}(x))$, 1.0 - error function of real($x$) \\
1031 %erfc(x)@any@$erfc ( roman real (x))$, 1.0 - error function of real ($x$)
1032 The `erfc(x)` function returns 1.0 - the error function of the real part of
1033 its argument. If the argument is a complex value, the imaginary component is
1034 ignored. See `erf`, `inverf`, and `norm`.
1036 ?expressions functions exp
1039 #exp(x) & any & $e^{x}$, exponential function of $x$ \\
1040 %exp(x)@any@$e sup x$, exponential function of $x$
1041 The `exp(x)` function returns the exponential function of its argument (`e`
1042 raised to the power of its argument). On some implementations (notably
1043 suns), exp(-x) returns undefined for very large x. A user-defined function
1044 like safe(x) = x<-100 ? 0 : exp(x) might prove useful in these cases.
1046 ?expressions functions floor
1049 #floor(x) & any & $\lfloor x \rfloor$, largest integer not greater
1050 #than $x$ (real part) \\
1051 %floor(x)@any@$left floor x right floor$, largest integer not greater than $x$ (real part)
1052 The `floor(x)` function returns the largest integer not greater than its
1053 argument. For complex numbers, `floor` returns the largest integer not
1054 greater than the real part of its argument.
1056 ?expressions functions gamma
1059 #gamma(x) & any & $\mbox{gamma}(\mbox{real}(x))$, gamma function of real($x$) \\
1060 %gamma(x)@any@$GAMMA ( roman real (x))$, gamma function of real ($x$)
1061 The `gamma(x)` function returns the gamma function of the real part of its
1062 argument. For integer n, gamma(n+1) = n!. If the argument is a complex
1063 value, the imaginary component is ignored.
1065 ?expressions functions ibeta
1068 #ibeta(p,q,x) & any & $\mbox{ibeta}(\mbox{real}(p,q,x))$, ibeta function of real($p$,$q$,$x$) \\
1069 %ibeta(p,q,x)@any@$ibeta ( roman real (p,q,x))$, ibeta function of real ($p$,$q$,$x$)
1070 The `ibeta(p,q,x)` function returns the incomplete beta function of the real
1071 parts of its arguments. p, q > 0 and x in [0:1]. If the arguments are
1072 complex, the imaginary components are ignored.
1074 ?expressions functions inverf
1077 #inverf(x) & any & inverse error function of real($x$) \\
1078 %inverf(x)@any@inverse error function real($x$)
1079 The `inverf(x)` function returns the inverse error function of the real part
1080 of its argument. See `erf` and `invnorm`.
1082 ?expressions functions igamma
1085 #igamma(a,x) & any & $\mbox{igamma}(\mbox{real}(a,x))$, igamma function of real($a$,$x$) \\
1086 %igamma(a,x)@any@$igamma ( roman real (a,x))$, igamma function of real ($a$,$x$)
1087 The `igamma(a,x)` function returns the normalized incomplete gamma
1088 function of the real parts of its arguments, where a > 0 and x >= 0.
1089 The standard notation is P(a,x), e.g. Abramowitz and Stegun (6.5.1),
1090 with limiting value of 1 as x approaches infinity. If the arguments
1091 are complex, the imaginary components are ignored.
1093 ?expressions functions imag
1096 #imag(x) & complex & imaginary part of $x$ as a real number \\
1097 %imag(x)@complex@imaginary part of $x$ as a real number
1098 The `imag(x)` function returns the imaginary part of its argument as a real
1101 ?expressions functions invnorm
1104 #invnorm(x) & any & inverse normal distribution function of real($x$) \\
1105 %invnorm(x)@any@inverse normal distribution function real($x$)
1106 The `invnorm(x)` function returns the inverse cumulative normal (Gaussian)
1107 distribution function of the real part of its argument. See `norm`.
1109 ?expressions functions int
1112 #int(x) & real & integer part of $x$, truncated toward zero \\
1113 %int(x)@real@integer part of $x$, truncated toward zero
1114 The `int(x)` function returns the integer part of its argument, truncated
1117 ?expressions functions lambertw
1120 #lambertw(x) & real & Lambert W function \\
1121 %lambertw(x)@real@Lambert W function
1122 The lambertw function returns the value of the principal branch of
1123 Lambert's W function, which is defined by the equation (W(z)*exp(W(z))=z.
1124 z must be a real number with z >= -exp(-1).
1126 ?expressions functions lgamma
1129 #lgamma(x) & any & $\mbox{lgamma}(\mbox{real}(x))$, lgamma function of real($x$) \\
1130 %lgamma(x)@any@$lgamma ( roman real (x))$, lgamma function of real ($x$)
1131 The `lgamma(x)` function returns the natural logarithm of the gamma function
1132 of the real part of its argument. If the argument is a complex value, the
1133 imaginary component is ignored.
1135 ?expressions functions log
1138 #log(x) & any & $\log_{e} x$, natural logarithm (base $e$) of $x$ \\
1139 %log(x)@any@$ln~x$, natural logarithm (base $e$) of $x$
1140 The `log(x)` function returns the natural logarithm (base `e`) of its
1141 argument. See `log10`.
1143 ?expressions functions log10
1146 #log10(x) & any & $\log_{10} x$, logarithm (base $10$) of $x$ \\
1147 %log10(x)@any@${log sub 10}~x$, logarithm (base $10$) of $x$
1148 The `log10(x)` function returns the logarithm (base 10) of its argument.
1150 ?expressions functions norm
1153 #norm(x) & any & normal distribution (Gaussian) function of real($x$) \\
1154 %norm(x)@any@$norm(x)$, normal distribution function of real($x$)
1155 The `norm(x)` function returns the cumulative normal (Gaussian) distribution
1156 function of the real part of its argument. See `invnorm`, `erf` and `erfc`.
1158 ?expressions functions rand
1161 #rand(x) & any & $\mbox{rand}(x)$, pseudo random number generator \\
1162 %rand(x)@any@$rand (x)$, pseudo random number generator
1163 `rand(0)` returns a pseudo random number in the interval [0:1] generated
1164 from the current value of two internal 32-bit seeds.
1165 `rand(-1)` resets both seeds to a standard value.
1166 `rand(x)` for x>0 sets both seeds to a value based on the value of x.
1167 `rand({x,y})` for x>0 sets seed1 to x and seed2 to y.
1168 Note: This behavior has changed starting with gnuplot version 3.8l. Older
1169 scripts that expected rand(x>0) to produce sequential pseudo-random numbers
1170 from the same seeded sequence must be changed to call rand(0) instead.
1172 ?expressions functions real
1175 #real(x) & any & real part of $x$ \\
1176 %real(x)@any@real part of $x$
1177 The `real(x)` function returns the real part of its argument.
1179 ?expressions functions sgn
1182 #sgn(x) & any & 1 if $x>0$, -1 if $x<0$, 0 if $x=0$. imag($x$) ignored \\
1183 %sgn(x)@any@1 if $x > 0$, -1 if $x < 0$, 0 if $x = 0$. $roman imag (x)$ ignored
1184 The `sgn(x)` function returns 1 if its argument is positive, -1 if its
1185 argument is negative, and 0 if its argument is 0. If the argument is a
1186 complex value, the imaginary component is ignored.
1188 ?expressions functions sin
1191 #sin(x) & any & $\sin x$, sine of $x$ \\
1192 %sin(x)@any@$sin~x$, sine of $x$
1193 The `sin(x)` function returns the sine of its argument. `sin` expects its
1194 argument to be in radians or degrees, as selected by `set angles`.
1196 ?expressions functions sinh
1199 #sinh(x) & any & $\sinh x$, hyperbolic sine of $x$ in radians \\
1200 %sinh(x)@any@$sinh~x$, hyperbolic sine of $x$ in radians
1201 The `sinh(x)` function returns the hyperbolic sine of its argument. `sinh`
1202 expects its argument to be in radians.
1204 ?expressions functions sqrt
1207 #sqrt(x) & any & $\sqrt{x}$, square root of $x$ \\
1208 %sqrt(x)@any@$sqrt x $, square root of $x$
1209 The `sqrt(x)` function returns the square root of its argument.
1211 ?expressions functions tan
1214 #tan(x) & any & $\tan x$, tangent of $x$ \\
1215 %tan(x)@any@$tan~x$, tangent of $x$
1216 The `tan(x)` function returns the tangent of its argument. `tan` expects
1217 its argument to be in radians or degrees, as selected by `set angles`.
1219 ?expressions functions tanh
1222 #tanh(x) & any & $\tanh x$, hyperbolic tangent of $x$ in radians\\
1223 %tanh(x)@any@$tanh~x$, hyperbolic tangent of $x$ in radians
1224 The `tanh(x)` function returns the hyperbolic tangent of its argument. `tanh`
1225 expects its argument to be in radians.
1229 #\begin{tabular}{|ccl|} \hline
1230 #\multicolumn{3}{|c|}{String functions} \\ \hline \hline
1231 #Function & Arguments & Returns \\ \hline
1233 %Function@Arguments@Returns
1236 ?expressions functions gprintf
1238 #gprintf("format",x) & any & string result from applying gnuplot's format parser \\
1239 %gprintf("format",x)@any@string result from applysing gnuplot's format parser
1240 `gprintf("format",x)` applies gnuplot's own format specifiers to the single
1241 variable x and returns the resulting string. If you want standard C-language
1242 format specifiers, you must instead use `sprintf("format",x)`.
1243 See `format specifiers`.
1245 ?expressions functions sprintf
1248 #sprintf("format",x,...) & multiple & string result from C-language sprintf \\
1249 %sprintf("format",x,...)@multiple@string result from C-language sprintf
1250 `sprintf("format",var1,var2,...)` applies standard C-language format specifiers
1251 to multiple arguments (10 max) and returns the resulting string. If you want to
1252 use gnuplot's own format specifiers, you must instead call `gprintf()`.
1253 For information on sprintf format specifiers, please see standard C-language
1254 documentation or the unix sprintf man page.
1256 ?expressions functions strlen
1259 #strlen("string") & string & int length of string \\
1260 %strlen("string")@string@int length of string
1261 `strlen("string")` returns the number of characters in the string.
1263 ?expressions functions strstrt
1266 #strstrt("string","key") & strings & int index of first character of substring "key" \\
1267 %strstrt("string","key")@strings@int index of first character of substring "key"
1268 `strstrt("string","key")` searches for the character string "key" in "string"
1269 and returns the index to the first character of "key". If "key" is not found,
1270 returns 0. Similar to C library function strstr except that it returns an
1271 index rather than a string pointer. strstrt("hayneedlestack","needle") = 4.
1273 ?expressions functions substr
1277 #substr("string",beg,end) & multiple & string "string"[beg:end] \\
1278 %substr("string",beg,end)@multiple@string "string"[beg:end]
1279 `substr("string",beg,end)` returns the substring consisting of characters
1280 beg through end of the original string. This is exactly equivalent to the
1281 expression "string"[beg:end] except that you do not have the option of
1282 ommitting beg or end.
1284 ?expressions functions strftime
1287 #strftime("timeformat",t) & any & string result from applying gnuplot's time parser \\
1288 %strftime("timeformat",t)@any@string result from applying gnuplot's time parser
1289 `strftime("timeformat",t)` applies the timeformat specifiers to the time t
1290 given in seconds since the year 2000.
1291 See `time_specifiers` and `strptime`.
1293 ? expressions functions strptime
1296 #strptime("timeformat",s) & string & seconds since year 2000 as given in string s \\
1297 %strptime("timeformat",s)@string@seconds since year 2000 as given in string s
1298 `strptime("timeformat",s)` reads the time from the string s using the
1299 timeformat specifiers and converts it into seconds since the year 2000.
1300 See `time_specifiers` and `strftime`.
1302 ?expressions functions system
1306 #system("command") & string & string containing output stream of shell command \\
1307 %system("command")@string@stdout containing output stream of shell command
1308 `system("command")` executes "command" using the standard shell and returns
1309 the resulting character stream from stdout as string variable.
1310 One optional trailing newline is ignored.
1312 This can be used to import external functions into gnuplot scripts using
1313 'f(x) = real(system(sprintf("somecommand %f", x)))'.
1315 ?expressions functions word
1319 #word("string",n) & string, int & returns the nth word in "string" \\
1320 %word("string",n)@string, int@returns the nth word in "string"
1321 `word("string",n)` returns the nth word in string. For example,
1322 `word("one two three",2)` returns the string "two".
1324 ?expressions functions words
1328 #words("string") & string & returns the number of words in "string" \\
1329 %words("string")@string@returns the number of words in "string"
1330 `words("string")` returns the number of words in string. For example,
1331 `words(" a b c d")` returns the 4.
1335 #\begin{tabular}{|ccl|} \hline
1336 #\multicolumn{3}{|c|}{other {\bf gnuplot} functions} \\ \hline \hline
1337 #Function & Arguments & Returns \\ \hline
1339 %Function@Arguments@Returns
1342 ?expressions functions column
1345 #column(x) & int & column $x$ during datafile manipulation. \\
1346 %column(x)@int@ column $x$ during datafile manipulation.
1347 `column(x)` may be used only in expressions as part of `using` manipulations
1348 to fits or datafile plots. It evaluates to the numerical value of the contents
1349 of column x. See `plot datafile using`.
1351 ?expressions functions defined
1354 #defined(X) & variable name & [DEPRECATED] returns 1 if X is defined, 0 otherwise. \\
1355 %defined(X)@variable name@ [DEPRECATED] returns 1 if X is defined, 0 otherwise.
1356 `defined(X)` [DEPRECATED] returns 1 if a variable named X has been defined, otherwise
1359 ?expressions functions exists
1362 #exists("X") & "variable name" & returns 1 if a variable named X is defined, 0 otherwise. \\
1363 %exists("X")@"variable name"@ returns 1 if a variable named X is defined, 0 otherwise.
1364 The argument to exists() is a string constant or a string variable;
1365 if the string contains the name of a defined variable, the function returns 1.
1366 Otherwise the function returns 0.
1368 ?expressions functions stringcolumn
1369 ?functions stringcolumn
1371 ?expressions functions strcol
1374 #stringcolumn(x) & int & content of column $x$ as a string. \\
1375 %stringcolumn(x)@int@ content column $x$ as a string.
1376 `stringcolumn(x)` may be used only in expressions as part of `using` manipulations
1377 to fits or datafile plots. It returns the content of column x as a string variable.
1378 See `plot datafile using`.
1380 ?expressions functions timecolumn
1381 ?functions timecolumn
1383 #timecolumn(x) & int & timecolumn $x$ during datafile manipulation. \\
1384 %timecolumn(x)@int@ timecolumn $x$ during datafile manipulation.
1385 `timecolumn(x)` may be used only in expressions as part of `using`
1386 manipulations to fits or datafile plots. See `plot datafile using`.
1388 It reads the data starting at that column as a time/date value and
1389 returns its value in gnuplot's internal time representation of
1390 "seconds since the millennium".
1392 To find the right `timefmt` string to use, `timecolumn` searches for a
1393 `using` specification with the same column number as its argument.
1394 If one is found, `timefmt` pattern of the target axis for this specifier
1395 is used. Otherwise, `timecolumn` chooses the x axis `timefmt` per default.
1397 ?expressions tm_hour
1400 #tm\_hour(x) & int & the hour \\
1401 %tm_hour(x)@int@the hour
1402 The `tm_hour` function interprets its argument as a time, in seconds from
1403 1 Jan 2000. It returns the hour (an integer in the range 0--23) as a real.
1405 ?expressions tm_mday
1408 #tm\_mday(x) & int & the day of the month \\
1409 %tm_mday(x)@int@the day of the month
1410 The `tm_mday` function interprets its argument as a time, in seconds from
1411 1 Jan 2000. It returns the day of the month (an integer in the range 1--31)
1417 #tm\_min(x) & int & the minute \\
1418 %tm_min(x)@int@the minute
1419 The `tm_min` function interprets its argument as a time, in seconds from
1420 1 Jan 2000. It returns the minute (an integer in the range 0--59) as a real.
1425 #tm\_mon(x) & int & the month \\
1426 %tm_mon(x)@int@the month
1427 The `tm_mon` function interprets its argument as a time, in seconds from
1428 1 Jan 2000. It returns the month (an integer in the range 0--11) as a real.
1433 #tm\_sec(x) & int & the second \\
1434 %tm_sec(x)@int@the second
1435 The `tm_sec` function interprets its argument as a time, in seconds from
1436 1 Jan 2000. It returns the second (an integer in the range 0--59) as a real.
1438 ?expressions tm_wday
1441 #tm\_wday(x) & int & the day of the week \\
1442 %tm_wday(x)@int@the day of the week
1443 The `tm_wday` function interprets its argument as a time, in seconds from
1444 1 Jan 2000. It returns the day of the week (an integer in the range 0--6) as
1447 ?expressions tm_yday
1450 #tm\_yday(x) & int & the day of the year \\
1451 %tm_yday(x)@int@the day of the year
1452 The `tm_yday` function interprets its argument as a time, in seconds from
1453 1 Jan 2000. It returns the day of the year (an integer in the range 1--366)
1456 ?expressions tm_year
1459 #tm\_year(x) & int & the year \\
1460 %tm_year(x)@int@the year
1461 The `tm_year` function interprets its argument as a time, in seconds from
1462 1 Jan 2000. It returns the year (an integer) as a real.
1464 ?expressions functions valid
1467 #valid(x) & int & test validity of $\mbox{column}(x)$ during datafile manip.\\
1468 %valid(x)@int@ test validity of column($x$) during datafile manip.
1469 `valid(x)` may be used only in expressions as part of `using` manipulations
1470 to fits or datafile plots. See `plot datafile using`.
1473 ^ <a href="http://www.gnuplot.info/demo/airfoil.html">
1474 airfoil.dem: use of functions and complex variables for airfoils demo.
1477 4 Random number generator
1481 The behavior of the built-in function `rand(x)` has changed as of version 3.8l.
1482 Older scripts that expected rand(x>0) to produce sequential pseudo-random
1483 numbers from the same seeded sequence must be changed to call rand(0) instead.
1484 The current behavior is as follows:
1485 `rand(0)` returns a pseudo random number in the interval [0:1] generated
1486 from the current value of two internal 32-bit seeds.
1487 `rand(-1)` resets both seeds to a standard value.
1488 `rand(x)` for x>0 sets both seeds to a value based on the value of x.
1489 `rand({x,y})` for x>0 sets seed1 to x and seed2 to y.
1492 ?expressions operators
1494 The operators in `gnuplot` are the same as the corresponding operators in the
1495 C programming language, except that all operators accept integer, real, and
1496 complex arguments, unless otherwise noted. The ** operator (exponentiation)
1497 is supported, as in FORTRAN.
1499 Parentheses may be used to change order of evaluation.
1501 ?expressions operators unary
1504 The following is a list of all the unary operators and their usages:
1506 @start table - first is interactive cleartext form
1507 Symbol Example Explanation
1509 + +a unary plus (no-operation)
1510 ~ ~a * one's complement
1511 ! !a * logical negation
1513 $ $3 * call arg/column during `using` manipulation
1517 =operator precedence
1518 #\begin{tabular}{|ccl|} \hline
1519 #\multicolumn{3}{|c|}{Unary Operators}\\ \hline \hline
1520 #Symbol & Example & Explanation \\ \hline
1521 #\verb@-@ & \verb@-a@ & unary minus \\
1522 #\verb@+@ & \verb@+a@ & unary plus (no-operation) \\
1523 #\verb@~@ & \verb@~a@ & * one's complement \\
1524 #\verb@!@ & \verb@!a@ & * logical negation \\
1525 #\verb@!@ & \verb@a!@ & * factorial \\
1526 #\verb@$@ & \verb@$3@ & * call arg/column during `using` manipulation \\
1527 C ugly hack: doc2ms uses $ as delimiter for eqn's so it doesn't seem to
1528 C be able to print them. So we have to typeset this table without using
1529 C eqn (at least that's the only solution I found, without any real docs
1531 C First, terminate the table doc2ms.c already started:
1533 C ... then turn off eqn delimiters:
1537 C ... and restart the table:
1539 %center box tab (@) ;
1541 %Symbol@Example@Explanation
1544 %+@+a@unary plus (no-operation)
1545 %~@~a@* one's complement
1546 %!@!a@* logical negation
1548 %$@$3@* call arg/column during `using` manipulation
1551 (*) Starred explanations indicate that the operator requires an integer
1554 Operator precedence is the same as in Fortran and C. As in those languages,
1555 parentheses may be used to change the order of operation. Thus -2**2 = -4,
1558 The factorial operator returns a real number to allow a greater range.
1560 ?expressions operators binary
1562 The following is a list of all the binary operators and their usages:
1564 @start table - first is interactive cleartext form
1565 Symbol Example Explanation
1566 ** a**b exponentiation
1567 * a*b multiplication
1575 <= a<=b less than or equal to
1577 >= a>=b greater than or equal to
1579 ^ a^b * bitwise exclusive OR
1580 | a|b * bitwise inclusive OR
1581 && a&&b * logical AND
1582 || a||b * logical OR
1583 . A.B string concatenation
1584 eq A eq B string equality
1585 ne A ne B string inequality
1590 #\begin{tabular}{|ccl|} \hline
1591 #\multicolumn{3}{|c|}{Binary Operators} \\ \hline \hline
1592 #Symbol & Example & Explanation \\ \hline
1593 #\verb~**~ & \verb~a**b~ & exponentiation\\
1594 #\verb~*~ & \verb~a*b~ & multiplication\\
1595 #\verb~/~ & \verb~a/b~ & division\\
1596 #\verb~%~ & \verb~a%b~ & * modulo\\
1597 #\verb~+~ & \verb~a+b~ & addition\\
1598 #\verb~-~ & \verb~a-b~ & subtraction\\
1599 #\verb~==~ & \verb~a==b~ & equality\\
1600 #\verb~!=~ & \verb~a!=b~ & inequality\\
1601 #\verb~<~ & \verb~a<b~ & less than\\
1602 #\verb~<=~ & \verb~a<=b~ & less than or equal to\\
1603 #\verb~>~ & \verb~a>b~ & greater than\\
1604 #\verb~>=~ & \verb~a>=b~ & greater than or equal to\\
1605 #\verb~&~ & \verb~a&b~ & * bitwise AND\\
1606 #\verb~^~ & \verb~a^b~ & * bitwise exclusive OR\\
1607 #\verb~|~ & \verb~a|b~ & * bitwise inclusive OR\\
1608 #\verb~&&~ & \verb~a&&b~ & * logical AND\\
1609 #\verb~||~ & \verb~a||b~ & * logical OR\\
1610 #\verb~.~ & \verb~A.B~ & string concatenation\\
1611 #\verb~eq~ & \verb~A eq B~ & string equality\\
1612 #\verb~ne~ & \verb~A ne B~ & string inequality\\
1614 %Symbol@Example@Explanation
1616 %**@a**b@exponentiation
1617 %*@a*b@multiplication
1625 %<=@a<=b@less than or equal to
1627 %>=@a>=b@greater than or equal to
1628 %&@a&b@* bitwise AND
1629 %^@a^b@* bitwise exclusive OR
1630 %|@a|b@* bitwise inclusive OR
1631 %&&@a&&b@* logical AND
1632 %||@a||b@* logical OR
1633 %.@a.b@string concatenation
1634 %eq@A eq B@string equality
1635 %ne@A ne B@string inequality
1638 (*) Starred explanations indicate that the operator requires integer
1640 Capital letters A and B indicate that the operator requires string arguments.
1642 Logical AND (&&) and OR (||) short-circuit the way they do in C. That is,
1643 the second `&&` operand is not evaluated if the first is false; the second
1644 `||` operand is not evaluated if the first is true.
1646 ?expressions operators ternary
1649 There is a single ternary operator:
1651 @start table - first is interactive cleartext form
1652 Symbol Example Explanation
1653 ?: a?b:c ternary operation
1654 #\begin{tabular}{|ccl|} \hline
1655 #\multicolumn{3}{|c|}{Ternary Operator} \\ \hline \hline
1656 #Symbol & Example & Explanation \\ \hline
1657 #\verb~?:~ & \verb~a?b:c~ & ternary operation\\
1659 %Symbol@Example@Explanation
1661 %?:@a?b:c@* ternary operation
1664 The ternary operator behaves as it does in C. The first argument (a), which
1665 must be an integer, is evaluated. If it is true (non-zero), the second
1666 argument (b) is evaluated and returned; otherwise the third argument (c) is
1667 evaluated and returned.
1669 The ternary operator is very useful both in constructing piecewise functions
1670 and in plotting points only when certain conditions are met.
1674 Plot a function that is to equal sin(x) for 0 <= x < 1, 1/x for 1 <= x < 2,
1675 and undefined elsewhere:
1676 f(x) = 0<=x && x<1 ? sin(x) : 1<=x && x<2 ? 1/x : 1/0
1678 ^ <img align=bottom src="http://www.gnuplot.info/doc/ternary.gif" alt="[ternary.gif]" width=640 height=480>
1679 Note that `gnuplot` quietly ignores undefined values, so the final branch of
1680 the function (1/0) will produce no plottable points. Note also that f(x)
1681 will be plotted as a continuous function across the discontinuity if a line
1682 style is used. To plot it discontinuously, create separate functions for the
1683 two pieces. (Parametric functions are also useful for this purpose.)
1685 For data in a file, plot the average of the data in columns 2 and 3 against
1686 the datum in column 1, but only if the datum in column 4 is non-negative:
1688 plot 'file' using 1:( $4<0 ? 1/0 : ($2+$3)/2 )
1690 Please see `plot datafile using` for an explanation of the `using` syntax.
1692 3 Gnuplot-defined variables
1693 ?gnuplot-defined variables
1694 The variable `pi` is defined to be pi, see
1697 Additionally, gnuplot may define some variables under various operations.
1699 Working with interactive terminals with `mouse` functionality defines
1700 variables with names that begin "MOUSE_", see `mouse variables` for details.
1702 Further, there are several "read-only" variables that begin "GPVAL_", like
1703 GPVAL_TERM, GPVAL_X_MIN, GPVAL_X_MAX, GPVAL_Y_MIN,... Type `show variables all`
1704 to display their list and values. Values related to axes parameters (ranges, log
1705 base) are values used during the last plot, not those currently `set`.
1707 The `fit` mechanism uses several variables with names that begin "FIT_". It
1708 is safest to avoid using such names. "FIT_LIMIT", however, is one that you
1709 may wish to redefine. Under `set fit errorvariables`, the error for each
1710 fitted parameter will be stored in a variable named like the parameter, but
1711 with "_err" appended. See the documentation on `fit` for details.
1713 See `user-defined variables`, `mouse variables`, and `fit`.
1715 3 User-defined variables and functions
1716 ?expressions user-defined
1717 ?user-defined variables
1720 New user-defined variables and functions of one through five variables may
1721 be declared and used anywhere, including on the `plot` command itself.
1723 User-defined function syntax:
1724 <func-name>( <dummy1> {,<dummy2>} ... {,<dummy5>} ) = <expression>
1726 where <expression> is defined in terms of <dummy1> through <dummy5>.
1728 User-defined variable syntax:
1729 <variable-name> = <constant-expression>
1733 q = floor(tan(pi/2 - 0.1))
1735 sinc(x) = sin(pi*x)/(pi*x)
1737 ramp(t) = (t > 0) ? t : 0
1738 min(a,b) = (a < b) ? a : b
1739 comb(n,k) = n!/(k!*(n-k)!)
1740 len3d(x,y,z) = sqrt(x*x+y*y+z*z)
1741 plot f(x) = sin(x*a), a = 0.2, f(x), a = 0.4, f(x)
1744 file(n) = sprintf("run_%d.dat",n)
1746 ^ <img align=bottom src="http://www.gnuplot.info/doc/userdefined.gif" alt="[userdefined.gif]" width=640 height=480>
1747 The final two examples illustrate a user-defined string variable and a
1748 user-defined string function.
1752 Note that the variables `pi` (3.14159...) and `NaN` (IEEE "Not a Number") are
1753 already defined. You can redefine these to something else if you really need
1754 to. The original values can be recovered by setting:
1759 Other variables may be defined under various gnuplot operations like mousing in
1760 interactive terminals or fitting; see `gnuplot-defined variables` for details.
1762 You can check for existence of a given variable V by the exists("V")
1763 expression. For example
1765 if (exists("a")) print "a is defined"
1766 if (!exists("b")) print "b is not defined"
1768 Valid names are the same as in most programming languages: they must begin
1769 with a letter, but subsequent characters may be letters, digits, "$", or "_".
1771 See `show functions`, `functions`, `gnuplot-defined variables`, `macros`.
1774 Throughout this document an attempt has been made to maintain consistency of
1775 nomenclature. This cannot be wholly successful because as `gnuplot` has
1776 evolved over time, certain command and keyword names have been adopted that
1777 preclude such perfection. This section contains explanations of the way
1778 some of these terms are used.
1780 A "page" or "screen" is the entire area addressable by `gnuplot`. On a
1781 monitor, it is the full screen; on a plotter, it is a single sheet of paper.
1783 A screen may contain one or more "plots". A plot is defined by an abscissa
1784 and an ordinate, although these need not actually appear on it, as well as
1785 the margins and any text written therein.
1787 A plot contains one "graph". A graph is defined by an abscissa and an
1788 ordinate, although these need not actually appear on it.
1790 A graph may contain one or more "lines". A line is a single function or
1791 data set. "Line" is also a plotting style. The word will also be used in
1792 sense "a line of text". Presumably the context will remove any ambiguity.
1794 The lines on a graph may have individual names. These may be listed
1795 together with a sample of the plotting style used to represent them in
1796 the "key", sometimes also called the "legend".
1798 The word "title" occurs with multiple meanings in `gnuplot`. In this
1799 document, it will always be preceded by the adjective "plot", "line", or
1800 "key" to differentiate among them.
1802 A 2-d graph may have up to four labelled axes. The names of the four axes
1803 for these usages are "x" for the axis along the bottom border of the plot,
1804 "y" for the left border, "x2" for the top border, and "y2" for the right
1807 A 3-d graph may have up to three labelled axes -- "x", "y" and "z". It is
1808 not possible to say where on the graph any particular axis will fall because
1809 you can change the direction from which the graph is seen with `set view`.
1811 When discussing data files, the term "record" will be resurrected and used
1812 to denote a single line of text in the file, that is, the characters between
1813 newline or end-of-record characters. A "point" is the datum extracted from
1814 a single record. A "datablock" is a set of points from consecutive records,
1815 delimited by blank records. A line, when referred to in the context of a
1816 data file, is a subset of a datablock.
1817 2 linetype, colors, and styles
1820 Each gnuplot terminal type provides a set of distinct "linetypes". These may
1821 differ in color, in thickness, in dot/dash pattern, or in some combination of
1822 color and dot/dash. The default linetypes for a particular terminal can be
1823 previewed by issuing the `test` command after setting the terminal type.
1824 The pre-defined colors and dot/dash patterns are not guaranteed to be
1825 consistent for all terminal types, but all terminals use the special linetype
1826 -1 to mean a solid line in the primary foreground color (normally black).
1827 By default, successive functions or datafiles plotted by a single command will
1828 be assigned successive linetypes. You can override this default by specifying
1829 a particular linetype for any function, datafile, or plot element.
1833 plot "foo", "bar" # plot two files using linetypes 1, 2
1834 plot sin(x) linetype 4 # terminal-specific linetype color 4
1835 plot sin(x) lt -1 # black
1838 For many terminal types it is also possible to assign user-defined colors
1839 using explicit rgb (red, green, blue) values, named colors, or color values
1840 that refer to the current PM3D palette.
1844 plot sin(x) lt rgb "violet" # one of gnuplot's named colors
1845 plot sin(x) lt rgb "#FF00FF" # explicit RGB triple in hexadecimal
1846 plot sin(x) lt palette cb -45 # whatever color corresponds to -45
1847 # in the current cbrange of the palette
1848 plot sin(x) lt palette frac 0.3 # fractional value along the palette
1850 See `show palette colornames`, `set palette`, `cbrange`.
1852 For terminals that support dot/dash patterns, each default linetype has both
1853 a dot-dash pattern and a default color. However, you can override the default
1854 color by using the keyword `linecolor`, abbreviated `lc`. For example, the
1855 postscript terminal provides a dashed blue line as linetype 3. The plot
1856 commands below use this same dash pattern for three plots, one in blue (the
1857 default), another in red (the default for linetype 1), and a third in gold.
1861 set term postscript dashed color
1862 plot 'foo' lt 3, 'baz' lt 3 linecolor 1, 'bar' lt 3 lc rgb 'gold'
1864 Lines can have additional properties such as linewidth. You can associate
1865 these various properties, as well as equivalent properties for point symbols,
1866 into user-defined "line styles" using the command `set style line`. Once
1867 you have defined a linestyle, you can use it in a plot command to control
1868 the appearance of one or more plot elements.
1872 # define a new line style with terminal-independent color cyan,
1873 # linewidth 3, and associated point type 6 (a circle with a dot in it).
1874 set style line 5 lt rgb "cyan" lw 3 pt 6
1875 plot sin(x) with linespoints ls 5 # user-defined line style 5
1877 See `linestyle`, `set style line`.
1886 Many commands allow you to specify a linetype with an explicit color.
1887 Note that not all terminals support RGB colors or pm3d palette colors.
1891 ... {linetype | lt} <colorspec>
1892 ... {linecolor | lc} <colorspec>
1893 ... {textcolor | tc} <colorspec>
1895 where <colorspec> has one of the following forms:
1897 rgbcolor "colorname"
1900 palette frac <val> # <val> runs from 0 to 1
1901 palette cb <value> # <val> lies within cbrange
1903 variable # color index is read from input file
1905 "colorname" refers to one of the color names built in to gnuplot. For a list
1906 of the available names, see `show palette colornames`.
1908 "#RRGGBB" is a hexadecimal constant preceded by the "#" symbol. The RRGGBB
1909 represents the red, green, and blue components of the color, each on a scale
1910 from 0 - 255. For example, magenta = full-scale red + full-scale blue would
1911 be represented by #FF00FF, which is the hexadecimal representation of
1912 (255 << 16) + (0 << 8) + (255).
1914 "rgb variable" requires an additional column in the `using` specifier, and
1915 is only available in 3D plotting mode (splot). The extra column is interpreted
1916 as a 24-bit packed RGB triple. These are most easily specified in a data file
1917 as hexadecimal values (see above).
1921 rgb(r,g,b) = 65536 * int(r) + 256 * int(g) + int(b)
1922 splot "data" using 1:2:3:(rgb($1,$2,$3)) with points lc rgb variable
1924 The color palette is a linear gradient of colors that smoothly maps a
1925 single numerical value onto a particular color. Two such mappings are always
1926 in effect. `palette frac` maps a fractional value between 0 and 1 onto the
1927 full range of the color palette. `palette cb` maps the range of the color
1928 axis onto the same palette. See `set cbrange`. See also `set colorbox`.
1929 You can use either of these to select a constant color from the current
1932 "palette z" maps the z value of each plot segment or plot element into the
1933 cbrange mapping of the palette. This allows smoothly-varying color along a
1934 3D line or surface. It also allows coloring 2D plots by palette values read
1935 from an extra column of data.
1936 4 linecolor variable
1941 Most plot commands assign a single color (linetype) to each element of the
1942 plot. If there are multiple plots on a single graph, the default color
1943 (linetype) is incremented sequentially. You can instead assign a separate
1944 color for each data point, line segment, or label based on additional
1945 information in the input data file. This is indicated by the colorspec
1948 `lc variable` tells the program to use the value read from one column of the
1949 input data as a linestyle index, and use the color belonging to that linestyle.
1950 This requires a corresponding additional column in the `using` specifier.
1951 Text colors can be set similarly using `tc variable`.
1953 A single data file may contain multiple sets of data, separated by two blank
1954 lines. Each of these separate sets is assigned an index value (see `index`)
1955 that can be retrieved via the using specifier column(-2).
1956 All data in the file is drawn with the same color/linestyle/pointtype
1957 properties by default. The command `lc variable` can be used to assign
1958 different colors to each data set in the file by using the index value from
1962 # Use the third column of data to assign colors to individual points
1963 plot 'data' using 1:2:3 with points lc variable
1965 # Use the data set index to choose a linestyle color
1966 plot 'data' using 1:2:(column(-2)) with lines lc variable
1970 The `x11`, `pm`, `windows`, `ggi`, and `wxt` terminals allow interaction with
1971 the current plot using the mouse. They also support the definition of hotkeys
1972 to activate pre-defined functions by hitting a single key while the mouse
1973 focus is in the active plot window. It is even possible to combine mouse
1974 input with `batch` command scripts, by invoking the command `pause mouse`
1975 and then using the mouse variables returned by mouse clicking as parameters
1976 for subsequent scripted actions. See `bind` and `mouse variables`.
1977 See also the command `set mouse`.
1981 The `bind` allows defining or redefining a hotkey, i.e. a sequence of gnuplot
1982 commands which will be executed when a certain key or key sequence is pressed
1983 while the driver's window has the input focus. Note that `bind` is only
1984 available if gnuplot was compiled with `mouse` support and it is used by all
1985 mouse-capable terminals. Bindings overwrite the builtin bindings (like in
1986 every real editor), except <space> and 'q' which cannot be rebound (unless
1987 one exception, see below). Mouse buttons cannot be rebound.
1989 You get the list of all hotkeys by typing `bind` or by hitting 'h' in the
1992 Note that multikey-bindings with modifiers have to be quoted.
1994 Normally hotkeys are only recognized when the currently active plot window
1995 has focus. `bind allwindows <key> ...` (short form: `bind all <key> ...`)
1996 causes the binding for <key> to apply to all gnuplot plot windows, active
1997 or not. In this case gnuplot variable MOUSE_KEY_WINDOW is set to the ID
1998 of the originating window, and may be used by the bound command.
2000 By default, the <space> hotkey raises gnuplot's command window. On some
2001 terminals (e.g. x11, wx), 'q' closes the graph window. These defaults can
2002 be changed to ctrl-space and ctrl-q by starting gnuplot as 'gnuplot -ctrlq',
2003 see `x11 command-line-options`, or by the X Resource 'gnuplot*ctrlq'.
2004 Note: if <space> (or ctrl-space) does not raise the gnuplot window under X11,
2005 see discussion in `raise`.
2008 bind {allwindows} [<key-sequence>] ["<gnuplot commands>"]
2016 bind "ctrl-a" "plot x*x"
2017 bind "ctrl-alt-a" 'print "great"'
2018 bind Home "set view 60,30; replot"
2019 bind all Home 'print "This is window ",MOUSE_KEY_WINDOW'
2022 bind "ctrl-a" # shows the binding for ctrl-a
2023 bind # shows all bindings
2026 bind "ctrl-alt-a" "" # removes binding for ctrl-alt-a
2027 (note that builtins cannot be removed)
2028 bind! # installs default (builtin) bindings
2030 - bind a key to toggle something:
2032 bind "ctrl-r" "v=v+1;if(v%2)set term x11 noraise; else set term x11 raise"
2034 Modifiers (ctrl / alt) are case insensitive, keys not:
2035 ctrl-alt-a == CtRl-alT-a
2036 ctrl-alt-a != ctrl-alt-A
2038 List of modifiers (alt == meta):
2041 List of supported special keys:
2043 "BackSpace", "Tab", "Linefeed", "Clear", "Return", "Pause", "Scroll_Lock",
2044 "Sys_Req", "Escape", "Delete", "Home", "Left", "Up", "Right", "Down",
2045 "PageUp", "PageDown", "End", "Begin",
2047 "KP_Space", "KP_Tab", "KP_Enter", "KP_F1", "KP_F2", "KP_F3", "KP_F4",
2048 "KP_Home", "KP_Left", "KP_Up", "KP_Right", "KP_Down", "KP_PageUp",
2049 "KP_PageDown", "KP_End", "KP_Begin", "KP_Insert", "KP_Delete", "KP_Equal",
2050 "KP_Multiply", "KP_Add", "KP_Separator", "KP_Subtract", "KP_Decimal",
2053 "KP_1" - "KP_9", "F1" - "F12"
2055 See also help for `mouse` and `if`.
2059 When mousing is active, clicking in the active window will set several user
2060 variables that can be accessed from the gnuplot command line. The coordinates
2061 of the mouse at the time of the click are stored in MOUSE_X MOUSE_Y MOUSE_X2
2062 and MOUSE_Y2. The mouse button clicked, and any meta-keys active at that time,
2063 are stored in MOUSE_BUTTON MOUSE_SHIFT MOUSE_ALT and MOUSE_CTRL. These
2064 variables are set to undefined at the start of every plot, and only become
2065 defined in the event of a mouse click in the active plot window. To determine
2066 from a script if the mouse has been clicked in the active plot window, it is
2067 sufficient to test for any one of these variables being defined.
2071 if (defined(MOUSE_BUTTON)) call 'something_else'; \
2072 else print "No mouse click."
2074 It is also possible to track keystrokes in the plot window using the mousing
2078 pause mouse keypress
2079 print "Keystroke ", MOUSE_KEY, " at ", MOUSE_X, " ", MOUSE_Y
2081 When `pause mouse keypress` is terminated by a keypress, then MOUSE_KEY will
2082 contain the ascii character value of the key that was pressed. MOUSE_CHAR will
2083 contain the character itself as a string variable. If the pause command is
2084 terminated abnormally (e.g. by ctrl-C or by externally closing the plot window)
2085 then MOUSE_KEY will equal -1.
2087 Note that after a zoom by mouse, you can read the new ranges as GPVAL_X_MIN,
2088 GPVAL_X_MAX, GPVAL_Y_MIN, and GPVAL_Y_MAX, see `gnuplot-defined variables`.
2093 There are three `gnuplot` commands which actually create a plot: `plot`,
2094 `splot` and `replot`. `plot` generates 2-d plots, `splot` generates 3-d
2095 plots (actually 2-d projections, of course), and `replot` appends its
2096 arguments to the previous `plot` or `splot` and executes the modified
2099 Much of the general information about plotting can be found in the discussion
2100 of `plot`; information specific to 3-d can be found in the `splot` section.
2102 `plot` operates in either rectangular or polar coordinates -- see `set polar`
2103 for details of the latter. `splot` operates only in rectangular coordinates,
2104 but the `set mapping` command allows for a few other coordinate systems to be
2105 treated. In addition, the `using` option allows both `plot` and `splot` to
2106 treat almost any coordinate system you'd care to define.
2108 `plot` also lets you use each of the four borders -- x (bottom), x2 (top), y
2109 (left) and y2 (right) -- as an independent axis. The `axes` option lets you
2110 choose which pair of axes a given function or data set is plotted against. A
2111 full complement of `set` commands exists to give you complete control over
2112 the scales and labelling of each axis. Some commands have the name of an
2113 axis built into their names, such as `set xlabel`. Other commands have one
2114 or more axis names as options, such as `set logscale xy`. Commands and
2115 options controlling the z axis have no effect on 2-d graphs.
2117 `splot` can plot surfaces and contours in addition to points and/or lines.
2118 In addition to `splot`, see `set isosamples` for information about defining
2119 the grid for a 3-d function; `splot datafile` for information about the
2120 requisite file structure for 3-d data values; and `set contour` and
2121 `set cntrparam` for information about contours.
2123 In `splot`, control over the scales and labels of the axes are the same as
2124 with `plot`, except that commands and options controlling the x2 and y2 axes
2125 have no effect whereas of course those controlling the z axis do take effect.
2127 ^ <a name="start-up"></a>
2131 When `gnuplot` is run, it looks for an initialization file to load.
2132 This file is called `.gnuplot` on Unix and AmigaOS systems, and
2133 `GNUPLOT.INI` on other systems. If this file is not found in the
2134 current directory, the program will look for it in the HOME directory
2135 (under AmigaOS, Atari(single)TOS, MS-DOS, Windows and OS/2, the
2136 environment variable `GNUPLOT` should contain the name of this
2137 directory; on Windows NT, it will use `USERPROFILE` if GNUPLOT isn't
2138 defined). Note: if NOCWDRC is defined during the installation,
2139 `gnuplot` will not read from the current directory.
2141 If the initialization file is found, `gnuplot` executes the commands in it.
2142 These may be any legal `gnuplot` commands, but typically they are limited to
2143 setting the terminal and defining frequently-used functions or variables.
2144 2 String constants and string variables
2147 In addition to string constants, most gnuplot commands also accept a string
2148 variable, a string expression, or a function that returns a string.
2149 For example, the following four methods of creating a plot all result in the
2153 graph4 = "Title for plot #4"
2154 graph(n) = sprintf("Title for plot #%d",n)
2156 plot 'data.4' title "Title for plot #4"
2157 plot 'data.4' title graph4
2158 plot 'data.4' title "Title for plot #".four
2159 plot 'data.4' title graph(4)
2161 Since integers are promoted to strings when operated on by the string
2162 concatenation operator, the following method also works:
2165 plot 'data.'.N title "Title for plot #".N
2167 In general, elements on the command line will only be evaluated as possible
2168 string variables if they are not otherwise recognizable as part of the normal
2169 gnuplot syntax. So the following sequence of commands is legal, although
2170 probably should be avoided so as not to cause confusion:
2172 plot = "my_datafile.dat"
2174 plot plot title title
2176 There are three binary operators that require string operands: the string
2177 concatenation operator ".", the string equality operator "eq" and the string
2178 inequality operator "ne". The following example will print TRUE.
2180 if ("A"."B" eq "AB") print "TRUE"
2182 See also the two string formatting functions `gprintf` and `sprintf`.
2185 Substrings can be specified by appending a range specifier to any string,
2186 string variable, or string-valued function. The range specifier has the
2187 form [begin:end], where begin is the index of the first character of the
2188 substring and end is the index of the last character of the substring.
2189 The first character has index 1. The begin or end fields may be empty, or
2190 contain '*', to indicate the true start or end of the original string.
2191 E.g. str[:] and str[*:*] both describe the full string str.
2192 2 Substitution and Command line macros
2194 When a command line to gnuplot is first read, i.e. before it is interpreted
2195 or executed, two forms of lexical substitution are performed. These are
2196 triggered by the presence of text in backquotes (ascii character 96) or
2197 preceded by @ (ascii character 64).
2198 3 Substitution of system commands in backquotes
2199 ?substitution backquotes
2202 Command-line substitution is specified by a system command enclosed in
2203 backquotes. This command is spawned and the output it produces replaces
2204 the backquoted text on the command line. Some implementations also support
2205 pipes; see `plot datafile special-filenames`.
2207 Command-line substitution can be used anywhere on the `gnuplot` command
2208 line, except inside strings delimited by single quotes.
2212 This will run the program `leastsq` and replace `leastsq` (including
2213 backquotes) on the command line with its output:
2217 f(x) = `run leastsq`
2219 These will generate labels with the current time and userid:
2220 set label "generated on `date +%Y-%m-%d` by `whoami`" at 1,1
2221 set timestamp "generated on %Y-%m-%d by `whoami`"
2222 3 Substitution of string variables as macros
2223 ?substitution macros
2226 Substitution of command line macros is disabled by default, but may be
2227 enabled using the `set macros` command. If macro substitution is enabled,
2228 the character @ is used to trigger substitution of the current value of a
2229 string variable into the command line. The text in the string variable may
2230 contain any number of lexical elements. This allows string variables to be
2231 used as command line macros. Only string constants may be expanded using this
2232 mechanism, not string-valued expressions.
2236 style1 = "lines lt 4 lw 2"
2237 style2 = "points lt 3 pt 5 ps 2"
2238 range1 = "using 1:3"
2239 range2 = "using 1:5"
2240 plot "foo" @range1 with @style1, "bar" @range2 with @style2
2242 The line containing @ symbols is expanded on input, so that by the time it is
2243 executed the effect is identical to having typed in full
2245 plot "foo" using 1:3 with lines lt 4 lw 2, \
2246 "bar" using 1:5 with points lt 3 pt 5 ps 2
2248 The function exists() may be useful in connection with macro evaluation.
2249 The following example checks that C can safely be expanded as the name of
2250 a user-defined variable:
2253 if (exists(C)) print C," = ", @C
2255 Macro expansion does not occur inside either single or double quotes.
2256 However macro expansion does occur inside backquotes.
2257 3 String variables, macros, and command line substitution
2258 ?mixing_macros_backquotes
2259 ?substitution mixing_macros_backquotes
2260 The interaction of string variables, backquotes and macro substitution is
2261 somewhat complicated. Backquotes do not block macro substitution, so
2263 filename = "mydata.inp"
2264 lines = ` wc --lines @filename | sed "s/ .*//" `
2266 results in the number of lines in mydata.inp being stored in the integer
2267 variable lines. And double quotes do not block backquote substitution, so
2269 mycomputer = "`uname -n`"
2271 results in the string returned by the system command `uname -n` being stored
2272 in the string variable mycomputer.
2274 However, macro substitution is not performed inside double quotes, so you
2275 cannot define a system command as a macro and then use both macro and backquote
2276 substitution at the same time.
2278 machine_id = "uname -n"
2279 mycomputer = "`@machine_id`" # doesn't work!!
2281 This fails because the double quotes prevent @machine_id from being interpreted
2282 as a macro. To store a system command as a macro and execute it later you must
2283 instead include the backquotes as part of the macro itself. This is
2284 accomplished by defining the macro as shown below. Notice that the sprintf
2285 format nests all three types of quotes.
2287 machine_id = sprintf('"`uname -n`"')
2288 mycomputer = @machine_id
2293 Version 4 of gnuplot is much less sensitive than earlier versions to the
2294 order of keywords and suboptions. However, if you get error messages from
2295 specifying options that you think should work, please try rearranging them
2296 into the exact order listed by the documentation.
2298 Options and any accompanying parameters are separated by spaces whereas lists
2299 and coordinates are separated by commas. Ranges are separated by colons and
2300 enclosed in brackets [], text and file names are enclosed in quotes, and a
2301 few miscellaneous things are enclosed in parentheses. Braces {} are used for
2302 a few special purposes.
2304 Commas are used to separate coordinates on the `set` commands `arrow`,
2305 `key`, and `label`; the list of variables being fitted (the list after the
2306 `via` keyword on the `fit` command); lists of discrete contours or the loop
2307 parameters which specify them on the `set cntrparam` command; the arguments
2308 of the `set` commands `dgrid3d`, `dummy`, `isosamples`, `offsets`, `origin`,
2309 `samples`, `size`, `time`, and `view`; lists of tics or the loop parameters
2310 which specify them; the offsets for titles and axis labels; parametric
2311 functions to be used to calculate the x, y, and z coordinates on the `plot`,
2312 `replot` and `splot` commands; and the complete sets of keywords specifying
2313 individual plots (data sets or functions) on the `plot`, `replot` and `splot`
2316 Parentheses are used to delimit sets of explicit tics (as opposed to loop
2317 parameters) and to indicate computations in the `using` filter of the `fit`,
2318 `plot`, `replot` and `splot` commands.
2320 (Parentheses and commas are also used as usual in function notation.)
2322 Square brackets are used to delimit ranges given in `set`, `plot`
2323 or `splot` commands.
2325 Colons are used to separate extrema in `range` specifications (whether they
2326 are given on `set`, `plot` or `splot` commands) and to separate entries in
2327 the `using` filter of the `plot`, `replot`, `splot` and `fit` commands.
2329 Semicolons are used to separate commands given on a single command line.
2331 Braces are used in text to be specially processed by some terminals, like
2332 `postscript`. They are also used to denote complex numbers: {3,2} = 3 + 2i.
2334 At present you should not embed \n inside {} when using the PostScript
2335 terminal in `enhanced text` mode.
2337 The EEPIC, Imagen, Uniplex, LaTeX, and TPIC drivers allow a newline to be
2338 specified by \\ in a single-quoted string or \\\\ in a double-quoted string.
2342 Gnuplot uses three forms of quote marks for delimiting text strings,
2343 double-quote (ascii 34), single-quote (ascii 39), and backquote (ascii 96).
2345 Filenames may be entered with either single- or double-quotes. In this
2346 manual the command examples generally single-quote filenames and double-quote
2347 other string tokens for clarity.
2349 String constants and text strings used for labels, titles, or other plot
2350 elements may be enclosed in either single quotes or double quotes. Further
2351 processing of the quoted text depends on the choice of quote marks.
2353 Backslash processing of special characters like \n (newline) and
2354 \345 (octal character code) is performed for double-quoted strings. In
2355 single-quoted strings, backslashes are just ordinary characters. To get
2356 a single-quote (ascii 39) in a single-quoted string, it has to be doubled.
2357 Thus the strings "d\" s' b\\" and 'd" s'' b\' are completely equivalent.
2359 Text justification is the same for each line of a multi-line string.
2360 Thus the center-justified string
2361 "This is the first line of text.\nThis is the second line."
2363 This is the first line of text.
2364 This is the second line.
2366 'This is the first line of text.\nThis is the second line.'
2368 This is the first line of text.\nThis is the second line.
2370 Enhanced text processing is performed for both double-quoted text and
2371 single-quoted text, but only by terminals supporting this mode.
2372 See `enhanced text`.
2374 Back-quotes are used to enclose system commands for substitution into the
2375 command line. See `substitution`.
2377 ^ <a name="Time/Date data"></a>
2378 ^ <a name="Time/date"></a>
2380 `gnuplot` supports the use of time and/or date information as input data.
2381 This feature is activated by the commands `set xdata time`, `set ydata time`,
2384 Internally all times and dates are converted to the number of seconds from
2385 the year 2000. The command `set timefmt` defines the format for all inputs:
2386 data files, ranges, tics, label positions---in short, anything that accepts a
2387 data value must receive it in this format. Since only one input format can
2388 be in force at a given time, all time/date quantities being input at the same
2389 time must be presented in the same format. Thus if both x and y data in a
2390 file are time/date, they must be in the same format.
2392 The conversion to and from seconds assumes Universal Time (which is the same
2393 as Greenwich Standard Time). There is no provision for changing the time
2394 zone or for daylight savings. If all your data refer to the same time zone
2395 (and are all either daylight or standard) you don't need to worry about these
2396 things. But if the absolute time is crucial for your application, you'll
2397 need to convert to UT yourself.
2399 Commands like `show xrange` will re-interpret the integer according to
2400 `timefmt`. If you change `timefmt`, and then `show` the quantity again, it
2401 will be displayed in the new `timefmt`. For that matter, if you give the
2402 deactivation command (like `set xdata`), the quantity will be shown in its
2405 The commands `set format` or `set tics format` define the format that will be
2406 used for tic labels, whether or not the specified axis is time/date.
2408 If time/date information is to be plotted from a file, the `using` option
2409 _must_ be used on the `plot` or `splot` command. These commands simply use
2410 white space to separate columns, but white space may be embedded within the
2411 time/date string. If you use tabs as a separator, some trial-and-error may
2412 be necessary to discover how your system treats them.
2414 The following example demonstrates time/date plotting.
2416 Suppose the file "data" contains records like
2418 03/21/95 10:00 6.02e23
2420 This file can be plotted by
2423 set timefmt "%m/%d/%y"
2424 set xrange ["03/21/95":"03/22/95"]
2425 set format x "%m/%d"
2426 set timefmt "%m/%d/%y %H:%M"
2427 plot "data" using 1:3
2429 which will produce xtic labels that look like "03/21".
2431 See the descriptions of each command for more details.
2434 This section lists the commands acceptable to `gnuplot` in alphabetical
2435 order. Printed versions of this document contain all commands; on-line
2436 versions may not be complete. Indeed, on some systems there may be no
2437 commands at all listed under this heading.
2439 Note that in most cases unambiguous abbreviations for command names and their
2440 options are permissible, i.e., "`p f(x) w li`" instead of "`plot f(x) with
2443 In the syntax descriptions, braces ({}) denote optional arguments and a
2444 vertical bar (|) separates mutually exclusive choices.
2448 The `cd` command changes the working directory.
2451 cd '<directory-name>'
2453 The directory name must be enclosed in quotes.
2459 It is recommended for DOS and Windows users to use
2460 single-quotes---backslash [\] has special significance inside
2461 double-quotes and has to be escaped. For example,
2470 The `call` command is identical to the load command with one exception: you
2471 can have up to ten additional parameters to the command (delimited according
2472 to the standard parser rules) which can be substituted into the lines read
2473 from the file. As each line is read from the `call`ed input file, it is
2474 scanned for the sequence `$` (dollar-sign) followed by a digit (0--9). If
2475 found, the sequence is replaced by the corresponding parameter from the
2476 `call` command line. If the parameter was specified as a string in the
2477 `call` line, it is substituted without its enclosing quotes. Sequence `$#`
2478 is replaced by the number of passed parameters. `$` followed by any character
2479 will be that character; e.g. use `$$` to get a single `$`. Providing more
2480 than ten parameters on the `call` command line will cause an error. A
2481 parameter that was not provided substitutes as nothing. Files being `call`ed
2482 may themselves contain `call` or `load` commands.
2484 The `call` command _must_ be the last command on a multi-command line.
2487 call "<input-file>" <parameter-0> <parm-1> ... <parm-9>
2489 The name of the input file must be enclosed in quotes, and it is recommended
2490 that parameters are similarly enclosed in quotes (future versions of gnuplot
2491 may treat quoted and unquoted arguments differently).
2495 If the file 'calltest.gp' contains the line:
2496 print "argc=$# p0=$0 p1=$1 p2=$2 p3=$3 p4=$4 p5=$5 p6=$6 p7=x$7x"
2498 entering the command:
2499 call 'calltest.gp' "abcd" 1.2 + "'quoted'" -- "$2"
2502 argc=7 p0=abcd p1=1.2 p2=+ p3='quoted' p4=- p5=- p6=$2 p7=xx
2504 NOTE: there is a clash in syntax with the datafile `using` callback
2505 operator. Use `$$n` or `column(n)` to access column n from a datafile inside
2506 a `call`ed datafile plot.
2510 The `clear` command erases the current screen or output device as specified
2511 by `set output`. This usually generates a formfeed on hardcopy devices. Use
2512 `set terminal` to set the device type.
2514 For some terminals `clear` erases only the portion of the plotting surface
2515 defined by `set size`, so for these it can be used in conjunction with `set
2516 multiplot` to create an inset.
2527 Please see `set multiplot`, `set size`, and `set origin` for details of these
2532 The commands `exit` and `quit`, as well as the END-OF-FILE character (usually
2533 Ctrl-D) terminate input from the current input stream: terminal session, pipe,
2534 and file input (pipe).
2536 If input streams are nested (inherited `load` scripts), then reading will
2537 continue in the parent stream. When the top level stream is closed, the
2538 program itself will exit.
2540 The command `exit gnuplot` will immediately and unconditionally cause gnuplot
2541 to exit even if the input stream is multiply nested. In this case any open
2542 output files may not be completed cleanly. Example of use:
2544 bind "ctrl-x" "unset output; exit gnuplot"
2546 See help for `batch/interactive` for more details.
2552 The `fit` command can fit a user-defined function to a set of data points
2553 (x,y) or (x,y,z), using an implementation of the nonlinear least-squares
2554 (NLLS) Marquardt-Levenberg algorithm. Any user-defined variable occurring in
2555 the function body may serve as a fit parameter, but the return type of the
2556 function must be real.
2559 fit {[xrange] {[yrange]}} <function> '<datafile>'
2560 {datafile-modifiers}
2561 via '<parameter file>' | <var1>{,<var2>,...}
2563 Ranges may be specified to temporarily limit the data which is to be fitted;
2564 any out-of-range data points are ignored. The syntax is
2565 [{dummy_variable=}{<min>}{:<max>}],
2566 analogous to `plot`; see `plot ranges`.
2568 <function> is any valid `gnuplot` expression, although it is usual to use a
2569 previously user-defined function of the form f(x) or f(x,y).
2571 <datafile> is treated as in the `plot` command. All the `plot datafile`
2572 modifiers (`using`, `every`,...) except `smooth` and the deprecated `thru`
2573 are applicable to `fit`. See `plot datafile`.
2575 The default data formats for fitting functions with a single independent
2576 variable, y=f(x), are {x:}y or x:y:s; those formats can be changed with
2577 the datafile `using` qualifier. The third item (a column number or an
2578 expression), if present, is interpreted as the standard deviation of the
2579 corresponding y value and is used to compute a weight for the datum, 1/s**2.
2580 Otherwise, all data points are weighted equally, with a weight of one.
2581 Note that if you don't specify a `using` option at all, no y deviations are
2582 read from the datafile even if it does have a third column, so you'll
2583 always get unit weights.
2585 To fit a function with two independent variables, z=f(x,y), the required
2586 format is `using` with four items, x:y:z:s. The complete format must be
2587 given---no default columns are assumed for a missing token. Weights for
2588 each data point are evaluated from 's' as above. If error estimates are
2589 not available, a constant value can be specified as a constant expression
2590 (see `plot datafile using`), e.g., `using 1:2:3:(1)`.
2592 Multiple datasets may be simultaneously fit with functions of one
2593 independent variable by making y a 'pseudo-variable', e.g., the dataline
2594 number, and fitting as two independent variables. See `fit multi-branch`.
2596 The `via` qualifier specifies which parameters are to be adjusted, either
2597 directly, or by referencing a parameter file.
2600 f(x) = a*x**2 + b*x + c
2601 g(x,y) = a*x**2 + b*y**2 + c*x*y
2603 fit f(x) 'measured.dat' via 'start.par'
2604 fit f(x) 'measured.dat' using 3:($7-5) via 'start.par'
2605 fit f(x) './data/trash.dat' using 1:2:3 via a, b, c
2606 fit g(x,y) 'surface.dat' using 1:2:3:(1) via a, b, c
2608 After each iteration step, detailed information about the current state
2609 of the fit is written to the display. The same information about the
2610 initial and final states is written to a log file, "fit.log". This file
2611 is always appended to, so as to not lose any previous fit history; it
2612 should be deleted or renamed as desired. By using the command
2613 `set fit logfile`, the name of the log file can be changed.
2615 If gnuplot was built with this option, and you activated it using `set fit
2616 errorvariables`, the error for each fitted parameter will be stored in
2617 a variable named like the parameter, but with "_err" appended. Thus the
2618 errors can be used as input for further computations.
2620 The fit may be interrupted by pressing Ctrl-C (any key but Ctrl-C under
2621 MSDOS and Atari Multitasking Systems). After the current iteration
2622 completes, you have the option to (1) stop the fit and accept the current
2623 parameter values, (2) continue the fit, (3) execute a `gnuplot` command
2624 as specified by the environment variable FIT_SCRIPT. The default for
2625 FIT_SCRIPT is `replot`, so if you had previously plotted both the data
2626 and the fitting function in one graph, you can display the current state
2629 Once `fit` has finished, the `update` command may be used to store final
2630 values in a file for subsequent use as a parameter file. See `update`
2632 3 adjustable parameters
2633 ?commands fit parameters
2635 ?commands fit adjustable_parameters
2636 ?fit adjustable_parameters
2638 There are two ways that `via` can specify the parameters to be adjusted,
2639 either directly on the command line or indirectly, by referencing a
2640 parameter file. The two use different means to set initial values.
2642 Adjustable parameters can be specified by a comma-separated list of variable
2643 names after the `via` keyword. Any variable that is not already defined
2644 is created with an initial value of 1.0. However, the fit is more likely
2645 to converge rapidly if the variables have been previously declared with more
2646 appropriate starting values.
2648 In a parameter file, each parameter to be varied and a corresponding initial
2649 value are specified, one per line, in the form
2652 Comments, marked by '#', and blank lines are permissible. The
2654 varname = value # FIXED
2656 means that the variable is treated as a 'fixed parameter', initialized by the
2657 parameter file, but not adjusted by `fit`. For clarity, it may be useful to
2658 designate variables as fixed parameters so that their values are reported by
2659 `fit`. The keyword `# FIXED` has to appear in exactly this form.
2661 3 short introduction
2662 ?commands fit beginners_guide
2663 ?fit beginners_guide
2666 `fit` is used to find a set of parameters that 'best' fits your data to your
2667 user-defined function. The fit is judged on the basis of the sum of the
2668 squared differences or 'residuals' (SSR) between the input data points and
2669 the function values, evaluated at the same places. This quantity is often
2670 called 'chisquare' (i.e., the Greek letter chi, to the power of 2). The
2671 algorithm attempts to minimize SSR, or more precisely, WSSR, as the residuals
2672 are 'weighted' by the input data errors (or 1.0) before being squared;
2673 see `fit error_estimates` for details.
2675 That's why it is called 'least-squares fitting'. Let's look at an example
2676 to see what is meant by 'non-linear', but first we had better go over some
2677 terms. Here it is convenient to use z as the dependent variable for
2678 user-defined functions of either one independent variable, z=f(x), or two
2679 independent variables, z=f(x,y). A parameter is a user-defined variable
2680 that `fit` will adjust, i.e., an unknown quantity in the function
2681 declaration. Linearity/non-linearity refers to the relationship of the
2682 dependent variable, z, to the parameters which `fit` is adjusting, not of
2683 z to the independent variables, x and/or y. (To be technical, the
2684 second {and higher} derivatives of the fitting function with respect to
2685 the parameters are zero for a linear least-squares problem).
2687 For linear least-squares (LLS), the user-defined function will be a sum of
2688 simple functions, not involving any parameters, each multiplied by one
2689 parameter. NLLS handles more complicated functions in which parameters can
2690 be used in a large number of ways. An example that illustrates the
2691 difference between linear and nonlinear least-squares is the Fourier series.
2692 One member may be written as
2693 z=a*sin(c*x) + b*cos(c*x).
2694 If a and b are the unknown parameters and c is constant, then estimating
2695 values of the parameters is a linear least-squares problem. However, if
2696 c is an unknown parameter, the problem is nonlinear.
2698 In the linear case, parameter values can be determined by comparatively
2699 simple linear algebra, in one direct step. However LLS is a special case
2700 which is also solved along with more general NLLS problems by the iterative
2701 procedure that `gnuplot` uses. `fit` attempts to find the minimum by doing
2702 a search. Each step (iteration) calculates WSSR with a new set of parameter
2703 values. The Marquardt-Levenberg algorithm selects the parameter values for
2704 the next iteration. The process continues until a preset criterion is met,
2705 either (1) the fit has "converged" (the relative change in WSSR is less than
2706 FIT_LIMIT), or (2) it reaches a preset iteration count limit, FIT_MAXITER
2707 (see `fit control variables`). The fit may also be interrupted
2708 and subsequently halted from the keyboard (see `fit`). The user variable
2709 FIT_CONVERGED contains 1 if the previous fit command terminated due to
2710 convergence; it contains 0 if the previous fit terminated for any other
2713 Often the function to be fitted will be based on a model (or theory) that
2714 attempts to describe or predict the behaviour of the data. Then `fit` can
2715 be used to find values for the free parameters of the model, to determine
2716 how well the data fits the model, and to estimate an error range for each
2717 parameter. See `fit error_estimates`.
2719 Alternatively, in curve-fitting, functions are selected independent of
2720 a model (on the basis of experience as to which are likely to describe
2721 the trend of the data with the desired resolution and a minimum number
2722 of parameters*functions.) The `fit` solution then provides an analytic
2723 representation of the curve.
2725 However, if all you really want is a smooth curve through your data points,
2726 the `smooth` option to `plot` may be what you've been looking for rather
2729 ?commands fit error_estimates
2730 ?fit error_estimates
2732 In `fit`, the term "error" is used in two different contexts, data error
2733 estimates and parameter error estimates.
2735 Data error estimates are used to calculate the relative weight of each data
2736 point when determining the weighted sum of squared residuals, WSSR or
2737 chisquare. They can affect the parameter estimates, since they determine
2738 how much influence the deviation of each data point from the fitted function
2739 has on the final values. Some of the `fit` output information, including
2740 the parameter error estimates, is more meaningful if accurate data error
2741 estimates have been provided.
2743 The 'statistical overview' describes some of the `fit` output and gives some
2744 background for the 'practical guidelines'.
2745 4 statistical overview
2746 ?commands fit error statistical_overview
2747 ?fit error statistical_overview
2748 ?statistical_overview
2749 The theory of non-linear least-squares (NLLS) is generally described in terms
2750 of a normal distribution of errors, that is, the input data is assumed to be
2751 a sample from a population having a given mean and a Gaussian (normal)
2752 distribution about the mean with a given standard deviation. For a sample of
2753 sufficiently large size, and knowing the population standard deviation, one
2754 can use the statistics of the chisquare distribution to describe a "goodness
2755 of fit" by looking at the variable often called "chisquare". Here, it is
2756 sufficient to say that a reduced chisquare (chisquare/degrees of freedom,
2757 where degrees of freedom is the number of datapoints less the number of
2758 parameters being fitted) of 1.0 is an indication that the weighted sum of
2759 squared deviations between the fitted function and the data points is the
2760 same as that expected for a random sample from a population characterized by
2761 the function with the current value of the parameters and the given standard
2764 If the standard deviation for the population is not constant, as in counting
2765 statistics where variance = counts, then each point should be individually
2766 weighted when comparing the observed sum of deviations and the expected sum
2769 At the conclusion `fit` reports 'stdfit', the standard deviation of the fit,
2770 which is the rms of the residuals, and the variance of the residuals, also
2771 called 'reduced chisquare' when the data points are weighted. The number of
2772 degrees of freedom (the number of data points minus the number of fitted
2773 parameters) is used in these estimates because the parameters used in
2774 calculating the residuals of the datapoints were obtained from the same data.
2775 These values are exported to the variables
2776 FIT_NDF = Number of degrees of freedom
2777 FIT_WSSR = Weighted sum-of-squares residual
2778 FIT_STDFIT = sqrt(WSSR/NDF)
2780 To estimate confidence levels for the parameters, one can use the minimum
2781 chisquare obtained from the fit and chisquare statistics to determine the
2782 value of chisquare corresponding to the desired confidence level, but
2783 considerably more calculation is required to determine the combinations of
2784 parameters which produce such values.
2786 Rather than determine confidence intervals, `fit` reports parameter error
2787 estimates which are readily obtained from the variance-covariance matrix
2788 after the final iteration. By convention, these estimates are called
2789 "standard errors" or "asymptotic standard errors", since they are calculated
2790 in the same way as the standard errors (standard deviation of each parameter)
2791 of a linear least-squares problem, even though the statistical conditions for
2792 designating the quantity calculated to be a standard deviation are not
2793 generally valid for the NLLS problem. The asymptotic standard errors are
2794 generally over-optimistic and should not be used for determining confidence
2795 levels, but are useful for qualitative purposes.
2797 The final solution also produces a correlation matrix, which gives an
2798 indication of the correlation of parameters in the region of the solution;
2799 if one parameter is changed, increasing chisquare, does changing another
2800 compensate? The main diagonal elements, autocorrelation, are all 1; if
2801 all parameters were independent, all other elements would be nearly 0. Two
2802 variables which completely compensate each other would have an off-diagonal
2803 element of unit magnitude, with a sign depending on whether the relation is
2804 proportional or inversely proportional. The smaller the magnitudes of the
2805 off-diagonal elements, the closer the estimates of the standard deviation
2806 of each parameter would be to the asymptotic standard error.
2807 4 practical guidelines
2808 ?commands fit error practical_guidelines
2809 ?fit error practical_guidelines
2810 ?practical_guidelines
2812 If you have a basis for assigning weights to each data point, doing so lets
2813 you make use of additional knowledge about your measurements, e.g., take into
2814 account that some points may be more reliable than others. That may affect
2815 the final values of the parameters.
2817 Weighting the data provides a basis for interpreting the additional `fit`
2818 output after the last iteration. Even if you weight each point equally,
2819 estimating an average standard deviation rather than using a weight of 1
2820 makes WSSR a dimensionless variable, as chisquare is by definition.
2822 Each fit iteration will display information which can be used to evaluate
2823 the progress of the fit. (An '*' indicates that it did not find a smaller
2824 WSSR and is trying again.) The 'sum of squares of residuals', also called
2825 'chisquare', is the WSSR between the data and your fitted function; `fit`
2826 has minimized that. At this stage, with weighted data, chisquare is expected
2827 to approach the number of degrees of freedom (data points minus parameters).
2828 The WSSR can be used to calculate the reduced chisquare (WSSR/ndf) or stdfit,
2829 the standard deviation of the fit, sqrt(WSSR/ndf). Both of these are
2830 reported for the final WSSR.
2832 If the data are unweighted, stdfit is the rms value of the deviation of the
2833 data from the fitted function, in user units.
2835 If you supplied valid data errors, the number of data points is large enough,
2836 and the model is correct, the reduced chisquare should be about unity. (For
2837 details, look up the 'chi-squared distribution' in your favourite statistics
2838 reference.) If so, there are additional tests, beyond the scope of this
2839 overview, for determining how well the model fits the data.
2841 A reduced chisquare much larger than 1.0 may be due to incorrect data error
2842 estimates, data errors not normally distributed, systematic measurement
2843 errors, 'outliers', or an incorrect model function. A plot of the residuals,
2844 e.g., `plot 'datafile' using 1:($2-f($1))`, may help to show any systematic
2845 trends. Plotting both the data points and the function may help to suggest
2848 Similarly, a reduced chisquare less than 1.0 indicates WSSR is less than that
2849 expected for a random sample from the function with normally distributed
2850 errors. The data error estimates may be too large, the statistical
2851 assumptions may not be justified, or the model function may be too general,
2852 fitting fluctuations in a particular sample in addition to the underlying
2853 trends. In the latter case, a simpler function may be more appropriate.
2855 You'll have to get used to both `fit` and the kind of problems you apply it
2856 to before you can relate the standard errors to some more practical estimates
2857 of parameter uncertainties or evaluate the significance of the correlation
2860 Note that `fit`, in common with most NLLS implementations, minimizes the
2861 weighted sum of squared distances (y-f(x))**2. It does not provide any means
2862 to account for "errors" in the values of x, only in y. Also, any "outliers"
2863 (data points outside the normal distribution of the model) will have an
2864 exaggerated effect on the solution.
2866 ?commands fit control
2868 There are a number of `gnuplot` variables that can be defined to affect
2869 `fit`. Those which can be defined once `gnuplot` is running are listed
2870 under 'control_variables' while those defined before starting `gnuplot`
2871 are listed under 'environment_variables'.
2873 ?commands fit control variables
2874 ?fit control variables
2875 The default epsilon limit (1e-5) may be changed by declaring a value for
2877 When the sum of squared residuals changes between two iteration steps by
2878 a factor less than this number (epsilon), the fit is considered to have
2881 The maximum number of iterations may be limited by declaring a value for
2883 A value of 0 (or not defining it at all) means that there is no limit.
2885 If you need even more control about the algorithm, and know the
2886 Marquardt-Levenberg algorithm well, there are some more variables to
2887 influence it. The startup value of `lambda` is normally calculated
2888 automatically from the ML-matrix, but if you want to, you may provide
2891 Specifying FIT_START_LAMBDA as zero or less will re-enable the automatic
2892 selection. The variable
2894 gives the factor by which `lambda` is increased or decreased whenever
2895 the chi-squared target function increased or decreased significantly.
2896 Setting FIT_LAMBDA_FACTOR to zero re-enables the default factor of
2899 Other variables with the FIT_ prefix may be added to `fit`, so it is safer
2900 not to use that prefix for user-defined variables.
2902 The variables FIT_SKIP and FIT_INDEX were used by earlier releases of
2903 `gnuplot` with a 'fit' patch called `gnufit` and are no longer available.
2904 The datafile `every` modifier provides the functionality of FIT_SKIP.
2905 FIT_INDEX was used for multi-branch fitting, but multi-branch fitting of
2906 one independent variable is now done as a pseudo-3D fit in which the
2907 second independent variable and `using` are used to specify the branch.
2908 See `fit multi-branch`.
2909 4 environment variables
2910 ?commands fit control environment
2911 ?fit control environment
2912 The environment variables must be defined before `gnuplot` is executed; how
2913 to do so depends on your operating system.
2916 changes the name (and/or path) of the file to which the fit log will be
2917 written from the default of "fit.log" in the working directory. The default
2918 value can be overwritten using the command `set fit logfile`.
2921 specifies a command that may be executed after an user interrupt. The default
2922 is `replot`, but a `plot` or `load` command may be useful to display a plot
2923 customized to highlight the progress of the fit.
2925 ?commands fit multi-branch
2929 In multi-branch fitting, multiple data sets can be simultaneously fit with
2930 functions of one independent variable having common parameters by minimizing
2931 the total WSSR. The function and parameters (branch) for each data set are
2932 selected by using a 'pseudo-variable', e.g., either the dataline number (a
2933 'column' index of -1) or the datafile index (-2), as the second independent
2936 Example: Given two exponential decays of the form, z=f(x), each describing
2937 a different data set but having a common decay time, estimate the values of
2938 the parameters. If the datafile has the format x:z:s, then
2939 f(x,y) = (y==0) ? a*exp(-x/tau) : b*exp(-x/tau)
2940 fit f(x,y) 'datafile' using 1:-2:2:3 via a, b, tau
2942 For a more complicated example, see the file "hexa.fnc" used by the
2945 Appropriate weighting may be required since unit weights may cause one
2946 branch to predominate if there is a difference in the scale of the dependent
2947 variable. Fitting each branch separately, using the multi-branch solution
2948 as initial values, may give an indication as to the relative effect of each
2949 branch on the joint solution.
2951 ?commands fit starting_values
2952 ?fit starting_values
2954 Nonlinear fitting is not guaranteed to converge to the global optimum (the
2955 solution with the smallest sum of squared residuals, SSR), and can get stuck
2956 at a local minimum. The routine has no way to determine that; it is up to
2957 you to judge whether this has happened.
2959 `fit` may, and often will get "lost" if started far from a solution, where
2960 SSR is large and changing slowly as the parameters are varied, or it may
2961 reach a numerically unstable region (e.g., too large a number causing a
2962 floating point overflow) which results in an "undefined value" message
2963 or `gnuplot` halting.
2965 To improve the chances of finding the global optimum, you should set the
2966 starting values at least roughly in the vicinity of the solution, e.g.,
2967 within an order of magnitude, if possible. The closer your starting values
2968 are to the solution, the less chance of stopping at another minimum. One way
2969 to find starting values is to plot data and the fitting function on the same
2970 graph and change parameter values and `replot` until reasonable similarity
2971 is reached. The same plot is also useful to check whether the fit stopped at
2972 a minimum with a poor fit.
2974 Of course, a reasonably good fit is not proof there is not a "better" fit (in
2975 either a statistical sense, characterized by an improved goodness-of-fit
2976 criterion, or a physical sense, with a solution more consistent with the
2977 model.) Depending on the problem, it may be desirable to `fit` with various
2978 sets of starting values, covering a reasonable range for each parameter.
2983 Here are some tips to keep in mind to get the most out of `fit`. They're not
2984 very organized, so you'll have to read them several times until their essence
2987 The two forms of the `via` argument to `fit` serve two largely distinct
2988 purposes. The `via "file"` form is best used for (possibly unattended) batch
2989 operation, where you just supply the startup values in a file and can later
2990 use `update` to copy the results back into another (or the same) parameter
2993 The `via var1, var2, ...` form is best used interactively, where the command
2994 history mechanism may be used to edit the list of parameters to be fitted or
2995 to supply new startup values for the next try. This is particularly useful
2996 for hard problems, where a direct fit to all parameters at once won't work
2997 without good starting values. To find such, you can iterate several times,
2998 fitting only some of the parameters, until the values are close enough to the
2999 goal that the final fit to all parameters at once will work.
3001 Make sure that there is no mutual dependency among parameters of the function
3002 you are fitting. For example, don't try to fit a*exp(x+b), because
3003 a*exp(x+b)=a*exp(b)*exp(x). Instead, fit either a*exp(x) or exp(x+b).
3005 A technical issue: the parameters must not be too different in magnitude.
3006 The larger the ratio of the largest and the smallest absolute parameter
3007 values, the slower the fit will converge. If the ratio is close to or above
3008 the inverse of the machine floating point precision, it may take next to
3009 forever to converge, or refuse to converge at all. You will have to adapt
3010 your function to avoid this, e.g., replace 'parameter' by '1e9*parameter' in
3011 the function definition, and divide the starting value by 1e9.
3013 If you can write your function as a linear combination of simple functions
3014 weighted by the parameters to be fitted, by all means do so. That helps a
3015 lot, because the problem is no longer nonlinear and should converge with only
3016 a small number of iterations, perhaps just one.
3018 Some prescriptions for analysing data, given in practical experimentation
3019 courses, may have you first fit some functions to your data, perhaps in a
3020 multi-step process of accounting for several aspects of the underlying
3021 theory one by one, and then extract the information you really wanted from
3022 the fitting parameters of those functions. With `fit`, this may often be
3023 done in one step by writing the model function directly in terms of the
3024 desired parameters. Transforming data can also quite often be avoided,
3025 though sometimes at the cost of a more difficult fit problem. If you think
3026 this contradicts the previous paragraph about simplifying the fit function,
3029 A "singular matrix" message indicates that this implementation of the
3030 Marquardt-Levenberg algorithm can't calculate parameter values for the next
3031 iteration. Try different starting values, writing the function in another
3032 form, or a simpler function.
3034 Finally, a nice quote from the manual of another fitting package (fudgit),
3035 that kind of summarizes all these issues: "Nonlinear fitting is an art!"
3039 The `help` command displays on-line help. To specify information on a
3040 particular topic use the syntax:
3044 If <topic> is not specified, a short message is printed about `gnuplot`.
3045 After help for the requested topic is given, a menu of subtopics is given;
3046 help for a subtopic may be requested by typing its name, extending the help
3047 request. After that subtopic has been printed, the request may be extended
3048 again or you may go back one level to the previous topic. Eventually, the
3049 `gnuplot` command line will return.
3051 If a question mark (?) is given as the topic, the list of topics currently
3052 available is printed on the screen.
3056 `history` command lists or saves previous entries in the history of the
3057 command line editing, or executes an entry.
3059 Here you find 'usage by examples':
3061 history # show the complete history
3062 history 5 # show last 5 entries in the history
3063 history quiet 5 # show last 5 entries without entry numbers
3064 history "hist.gp" # write the complete history to file hist.gp
3065 history "hist.gp" append # append the complete history to file hist.gp
3066 history 10 "hist.gp" # write last 10 commands to file hist.gp
3067 history 10 "|head -5 >>diary.gp" # write 5 history commands using pipe
3068 history ?load # show all history entries starting with "load"
3069 history ?"set c" # like above, several words enclosed in quotes
3070 hi !reread # execute last entry starting with "reread"
3071 hist !"set xr" # like above, several words enclosed in quotes
3072 hi !hi # guess yourself :-))
3074 On systems which support a popen function (Unix), the output of history can be
3075 piped through an external program by starting the file name with a '|', as one
3076 of the above examples demonstrates.
3080 The `if` command allows commands to be executed conditionally.
3083 if (<condition>) <command-line> [; else if (<condition>) ...; else ...]
3085 <condition> will be evaluated. If it is true (non-zero), then the command(s)
3086 of the <command-line> will be executed. If <condition> is false (zero), then
3087 the entire <command-line> is ignored until the next occurrence of `else`.
3088 Note that use of `;` to allow multiple commands on the same line will
3089 _not_ end the conditionalized commands.
3093 if (pi!=acos(-1)) print "?Fixing pi!"; pi=acos(-1); print pi
3098 if (1==2) print "Never see this"; print "Or this either"
3099 will not display anything.
3103 v=v+1; if (v%2) print "2" ; else if (v%3) print "3"; else print "fred"
3104 (repeat the last line repeatedly!)
3106 See `reread` for an example of how `if` and `reread` can be used together to
3111 The `load` command executes each line of the specified input file as if it
3112 had been typed in interactively. Files created by the `save` command can
3113 later be `load`ed. Any text file containing valid commands can be created
3114 and then executed by the `load` command. Files being `load`ed may themselves
3115 contain `load` or `call` commands. See `comments` for information about
3116 comments in commands. To `load` with arguments, see `call`.
3118 The `load` command _must_ be the last command on a multi-command line.
3123 The name of the input file must be enclosed in quotes.
3125 The special filename "-" may be used to `load` commands from standard input.
3126 This allows a `gnuplot` command file to accept some commands from standard
3127 input. Please see help for `batch/interactive` for more details.
3129 On some systems which support a popen function (Unix), the load file can be
3130 read from a pipe by starting the file name with a '<'.
3135 load "< loadfile_generator.sh"
3137 The `load` command is performed implicitly on any file names given as
3138 arguments to `gnuplot`. These are loaded in the order specified, and
3139 then `gnuplot` exits.
3144 lower {plot_window_nb}
3146 The `lower` command lowers (opposite to `raise`) plot window(s) associated
3147 with the interactive terminal of your gnuplot session, i.e. `pm`, `win`, `wxt`
3148 or `x11`. It puts the plot window to bottom in the z-order windows stack of
3149 the window manager of your desktop.
3151 As `x11` and `wxt` support multiple plot windows, then by default they lower
3152 these windows in descending order of most recently created on top to the least
3153 recently created on bottom. If a plot number is supplied as an optional
3154 parameter, only the associated plot window will be lowered if it exists.
3156 The optional parameter is ignored for single plot-window terminals, i.e. `pm`
3162 The `pause` command displays any text associated with the command and then
3163 waits a specified amount of time or until the carriage return is pressed.
3164 `pause` is especially useful in conjunction with `load` files.
3167 pause <time> {"<string>"}
3168 pause mouse {<endcondition>}{, <endcondition>} {"<string>"}
3170 <time> may be any constant or expression. Choosing -1 will wait until a
3171 carriage return is hit, zero (0) won't pause at all, and a positive number
3172 will wait the specified number of seconds. The time is rounded to an integer
3173 number of seconds if subsecond time resolution is not supported by the given
3174 platform. `pause 0` is synonymous with `print`.
3176 If the current terminal supports mousing, then `pause mouse` will terminate
3177 on either a mouse click or on ctrl-C. For all other terminals, or if mousing
3178 is not active, `pause mouse` is equivalent to `pause -1`.
3180 If one or more end conditions are given after `pause mouse`, then any one of
3181 the conditions will terminate the pause. The possible end conditions are
3182 `keypress`, `button1`, `button2`, `button3`, `close`, and `any`.
3183 If the pause terminates on a keypress, then the ascii value of the key pressed
3184 is returned in MOUSE_KEY. The character itself is returned as a one character
3185 string in MOUSE_CHAR. Hotkeys (bind command) are disabled if keypress is one of
3186 the end conditions. Zooming is disabled if button3 is one of the end
3189 In all cases the coordinates of the mouse are returned in variables MOUSE_X,
3190 MOUSE_Y, MOUSE_X2, MOUSE_Y2. See `mouse variables`.
3192 Note: Since `pause` communicates with the operating system rather than the
3193 graphics, it may behave differently with different device drivers (depending
3194 upon how text and graphics are mixed).
3197 pause -1 # Wait until a carriage return is hit
3198 pause 3 # Wait three seconds
3199 pause -1 "Hit return to continue"
3200 pause 10 "Isn't this pretty? It's a cubic spline."
3201 pause mouse "Click any mouse button on selected data point"
3202 pause mouse keypress "Type a letter from A-F in the active window"
3203 pause mouse button1,keypress
3204 pause mouse any "Any key or button will terminate"
3206 The variant "pause mouse key" will resume after any keypress in the active
3207 plot window. If you want to wait for a particular key to be pressed, you can
3208 use a reread loop such as:
3210 printf "I will resume after you hit the Tab key in the plot window"
3213 File "wait_for_tab" contains the lines
3216 if (MOUSE_KEY != 9) reread
3221 `plot` is the primary command for drawing plots with `gnuplot`. It creates
3222 plots of functions and data in many, many ways. `plot` is used to draw 2-d
3223 functions and data; `splot` draws 2-d projections of 3-d surfaces and data.
3224 `plot` and `splot` contain many common features; see `splot` for differences.
3225 Note specifically that although the `binary <binary list>` variation does
3226 work for both `plot` and `splot`, there are small differences between these
3227 modes. Furthermore, `plot`'s `axes` option does not exist for `splot`.
3231 {<function> | {"<datafile>" {datafile-modifiers}}}
3232 {axes <axes>} {<title-spec>} {with <style>}
3233 {, {definitions,} <function> ...}
3235 where either a <function> or the name of a data file enclosed in quotes is
3236 supplied. A function is a mathematical expression or a pair of mathematical
3237 expressions in parametric mode. The expressions may be defined completely or
3238 in part earlier in the stream of `gnuplot` commands (see `user-defined`).
3240 It is also possible to define functions and parameters on the `plot` command
3241 itself. This is done merely by isolating them from other items with commas.
3243 There are four possible sets of axes available; the keyword <axes> is used to
3244 select the axes for which a particular line should be scaled. `x1y1` refers
3245 to the axes on the bottom and left; `x2y2` to those on the top and right;
3246 `x1y2` to those on the bottom and right; and `x2y1` to those on the top and
3247 left. Ranges specified on the `plot` command apply only to the first set of
3252 plot f(x) = sin(x*a), a = .2, f(x), a = .4, f(x)
3253 plot [t=1:10] [-pi:pi*2] tan(t), \
3254 "data.1" using (tan($2)):($3/$4) smooth csplines \
3255 axes x1y2 notitle with lines 5
3257 See also `show plot`.
3259 ?commands plot datafile
3265 Discrete data contained in a file can be displayed by specifying the name of
3266 the data file (enclosed in single or double quotes) on the `plot` command line.
3269 plot '<file_name>' {binary <binary list>}
3271 {index <index list>}
3272 {every <every list>}
3273 {thru <thru expression>}
3274 {using <using list>}
3277 The modifiers `binary`, `index`, `every`, `thru`, `using`, and `smooth` are
3278 discussed separately. In brief, `binary` allows data entry from a binary
3279 file (default is ASCII), `index` selects which data sets in a multi-data-set
3280 file are to be plotted, `every` specifies which points within a single data
3281 set are to be plotted, `using` determines how the columns within a single
3282 record are to be interpreted (`thru` is a special case of `using`), and
3283 `smooth` allows for simple interpolation and approximation. (`splot` has a
3284 similar syntax, but does not support the `smooth` and `thru` options.)
3289 Data files should contain at least one data point per record (`using`
3290 can select one data point from the record). Records beginning with `#`
3291 (and also with `!` on VMS) will be treated as comments and ignored.
3292 Each data point represents an (x,y) pair. For `plot`s with error bars or
3293 error bars with lines (see `set style errorbars` or `set style errorlines`),
3294 each data point is (x,y,ydelta), (x,y,ylow,yhigh),
3295 (x,y,xdelta), (x,y,xlow,xhigh), or (x,y,xlow,xhigh,ylow,yhigh).
3297 In all cases, the numbers of each record of a data file must be separated
3298 by white space (one or more blanks or tabs) unless a format specifier is
3299 provided by the `using` option. This white space divides each record into
3300 columns. However, whitespace inside a pair of double quotes is ignored when
3301 counting columns, so the following datafile line has three columns:
3302 1.0 "second column" 3.0
3304 Data may be written in exponential format with the exponent preceded by the
3305 letter e or E. The fortran exponential specificiers d, D, q, and Q may also
3306 be used if the command `set datafile fortran` is in effect.
3308 Only one column (the y value) need be provided. If x is omitted, `gnuplot`
3309 provides integer values starting at 0.
3311 In datafiles, blank records (records with no characters other than blanks and
3312 a newline and/or carriage return) are significant.
3314 Single blank records designate discontinuities in a `plot`; no line will join
3315 points separated by a blank records (if they are plotted with a line style).
3317 Two blank records in a row indicate a break between separate data sets.
3320 If autoscaling has been enabled (`set autoscale`), the axes are automatically
3321 extended to include all datapoints, with a whole number of tic marks if tics
3322 are being drawn. This has two consequences: i) For `splot`, the corner of
3323 the surface may not coincide with the corner of the base. In this case, no
3324 vertical line is drawn. ii) When plotting data with the same x range on a
3325 dual-axis graph, the x coordinates may not coincide if the x2tics are not
3326 being drawn. This is because the x axis has been autoextended to a whole
3327 number of tics, but the x2 axis has not. The following example illustrates
3330 reset; plot '-', '-' axes x2y1
3338 To avoid this, you can use the `fixmin`/`fixmax` feature of the
3339 `set autoscale` command, which turns off the automatic extension of the
3340 axis range upto the next tic mark.
3345 Gnuplot can read binary data files. However, adequate information about
3346 details of the file format must be given on the command line or extracted
3347 from the file itself for a supported binary `filetype`. In particular,
3348 there are two structures for binary files, a matrix binary format and a
3349 general binary format.
3351 The matrix binary format contains a two dimensional array of 32 bit IEEE
3352 float values with an additional column and row of coordinate values. As
3353 with ASCII matrix, in the `using` list, repetition of the coordinate row
3354 constitutes column 1, repetition of the coordinate column constitutes
3355 column 2, and the array of values constitutes column 3.
3357 The general binary format contains an arbitrary number of columns for which
3358 information must be specified at the command line. For example, `array`,
3359 `record`, `format` and `using` can indicate the size, format and dimension
3360 of data. There are a variety of useful commands for skipping file headers
3361 and changing endianess. There are a set of commands for positioning and
3362 translating data since often coordinates are not part of the file when
3363 uniform sampling is inherent in the data. Different from matrix binary or
3364 ASCII, general binary does not treat the generated columns as 1, 2 or 3 in
3365 the `using` list. Rather, column 1 begins with column 1 of the file, or as
3366 specified in the `format` list.
3368 There are global default settings for the various binary options which may
3369 be set using the same syntax as the options when used as part of the `(s)plot
3370 <filename> binary ...` command. This syntax is `set datafile binary ...`.
3371 The general rule is that common command-line specified parameters override
3372 file-extracted parameters which override default parameters.
3374 Matrix binary is the default binary format when no keywords specific to
3375 general binary are given, i.e., `array`, `record`, `format`, `filetype`.
3377 General binary data can be entered at the command line via the special file
3378 name '-'. However, this is intended for use through a pipe where programs
3379 can exchange binary data, not for keyboards. There is no "end of record"
3380 character for binary data. Gnuplot continues reading from a pipe until it
3381 has read the number of points declared in the `array` qualifier.
3383 See `datafile binary` for more details.
3385 ?commands plot datafile binary
3386 ?plot datafile binary
3387 ?splot datafile binary
3393 The `binary` keyword allows a data file to be binary as opposed to ASCII.
3394 There are two formats for binary--matrix binary and general binary. Matrix
3395 binary is a fixed format in which data appears in a 2D array with an extra
3396 row and column for coordinate values. General binary is a flexible format
3397 for which details about the file must be given at the command line.
3399 See `binary matrix` or `binary general` for more details.
3401 ?commands plot datafile binary general
3402 ?commands splot datafile binary general
3403 ?plot binary general
3404 ?splot binary general
3406 General binary data in which format information is not necessarily part of
3407 the file can be read by giving further details about the file format at the
3408 command line. Although the syntax is slightly arcane to the casual user,
3409 general binary is particularly useful for application programs using gnuplot
3410 and sending large amounts of data.
3413 plot '<file_name>' {binary <binary list>} ...
3414 splot '<file_name>' {binary <binary list>} ...
3416 General binary format is activated by keywords in <binary list> pertaining
3417 to information about file structure, i.e., `array`, `record`, `format` or
3418 `filetype`. Otherwise, matrix binary format is assumed. (See `binary matrix`
3421 There are some standard file types that may be read for which details about
3422 the binary format may be extracted automatically. (Type `show datafile
3423 binary` at the command line for a list.) Otherwise, details must be
3424 specified at the command line or set in the defaults. Keywords are described
3427 The keyword `filetype` in <binary list> controls the routine used to
3428 read the file, i.e., the format of the data. For a list of the supported
3429 file types, type `show datafile binary filetypes`. If no file type is
3430 given, the rule is that traditional gnuplot binary is assumed for `splot`
3431 if the `binary` keyword stands alone. In all other circumstances, for
3432 `plot` or when one of the <binary list> keywords appears, a raw binary
3433 file is assumed whereby the keywords specify the binary format.
3435 General binary data files fall into two basic classes, and some files may
3436 be of both classes depending upon how they are treated. There is that
3437 class for which uniform sampling is assumed and point coordinates must be
3438 generated. This is the class for which full control via the <binary
3439 list> keywords applies. For this class, the settings precedence is that
3440 command line parameters override in-file parameters, which override
3441 default settings. The other class is that set of files for which
3442 coordinate information is contained within the file or there is possibly
3443 a non-uniform sampling such as gnuplot binary.
3445 Other than for the unique data files such as gnuplot binary, one should
3446 think of binary data as conceptually the same as ASCII data. Each point
3447 has columns of information which are selected via the `<using list>`
3448 associated with `using`. When no `format` string is specified, gnuplot
3449 will retrieve a number of binary variables equal to the largest column
3450 given in the `<using list>`. For example, `using 1:3` will result in
3451 three columns being read, of which the second will be ignored. There are
3452 default using lists based upon the typical number of parameters associated
3453 with a certain plot type. For example, `with image` has a default of
3454 `using 1`, while `with rgbimage` has a default of `using 1:2:3`. Note
3455 that the special characters for `using` representing point/line/index
3456 generally should not be used for binary data. There are keywords in
3457 <binary list> that control this.
3459 ?binary general array
3460 Describes the sampling array dimensions associated with the binary file.
3461 The coordinates will be generated by gnuplot. A number must be specified
3462 for each dimension, thereby calling out the size of the array. For example,
3463 `array=10x20` means the underlying sampling structure is two-dimensional with
3464 10 points along the first (x) dimension and 20 points along the second (y)
3465 dimension. A special "number", `Inf`, can be used to indicate that data should
3466 be read until the end of file. A colon can be used to separate the dimensions
3467 for multiple records. For example, `array=25:35` indicates there are two
3468 one-dimensional records within the file. The colon behavior applies to the
3469 remaining keywords in this list for which it makes sense to be associated with
3472 Currently, syntax allows for up to three-dimensional arrays. However, no
3473 conventions have yet been made for handling three-dimensional coordinates.
3475 ?binary general record
3476 This keyword serves the same function as `array`, having the same syntax.
3477 However, `record` causes gnuplot to not generate coordinate information.
3478 This is for the case where such information may be included in one of the
3479 columns of the binary data file.
3481 ?binary general format
3482 The default binary format is a float. For more flexibility, the format can
3483 include details about variable sizes. For example, `format="%uchar%int%float"`
3484 associates an unsigned character with the first using column, an int with the
3485 second column and a float with the third column. If the number of size
3486 specifications is less than the greatest column number, the size is implicitly
3487 taken to be similar to the last given variable size.
3489 Furthermore, the format specification can include "discarded" terms via the `*`
3490 character. For example, to skip the middle column of the previous example, one
3491 could write `format="%uchar%*int%float"` and gnuplot will discard the middle
3492 integer. To list variable sizes, type `show datafile binary datasizes`. There
3493 are a group of names that are machine dependent along with their sizes in bytes
3494 for the particular compilation. There is also a group of names which attempt
3495 to be machine independent.
3497 ?binary general endian
3498 Often the endianess of binary data in the file does not agree with the
3499 endianess used by the platform on which gnuplot is running. Several words can
3500 direct gnuplot how to arrange bytes. For example `endian=little` means treat
3501 the binary file as having byte significance from least to greatest. The options
3504 little: least significant to greatest significance
3505 big: greatest significance to least significance
3506 default: assume file endianess is the same as compiler
3507 swap (swab): Interchange the significance. (If things
3508 don't look right, try this.)
3510 Gnuplot can support "middle" ("pdp") endian if it is compiled with that option.
3512 ?binary general filetype
3513 For some standard binary file formats gnuplot can extract all the necessary
3514 information from the file in question. As an example, "format=edf" will read
3515 ESRF Header File format files. For a list of the currently supported file
3516 formats, type `show datafile binary filetypes`.
3518 There is a special file type called `auto` for which gnuplot will check if the
3519 binary file's extension is a quasi-standard extension for a supported format.
3521 Command line keywords may be used to override settings extracted from the file.
3522 The settings from the file override any defaults. (See `set datafile binary`
3525 ?binary general filetype avs
3528 `avs` is one of the automatically recognized binary file types for images.
3529 AVS is an extremely simple format, suitable mostly for streaming between
3530 applications. It consists of 2 longs (xwidth, ywidth) followed by a stream
3531 of pixels, each with four bytes of information alpha/red/green/blue.
3533 ?binary general filetype edf
3538 `edf` is one of the automatically recognized binary file types for images.
3539 EDF stands for ESRF Data Format, and it supports both edf and ehf formats
3540 (the latter means ESRF Header Format). More information on specifications
3543 http://www.esrf.fr/computing/expg/subgroups/general/format/Format.html
3547 ?binary general keywords
3549 The following keywords apply only when generating coordinates. That is, when
3550 the keyword `array` is used.
3552 ?binary general keywords scan
3553 A great deal of confusion can arise concerning the relationship between how
3554 gnuplot scans a binary file and the dimensions seen on the plot. To lessen
3555 the confusion, conceptually think of gnuplot _always_ scanning the binary file
3556 point/line/plane or fast/medium/slow. Then this keyword is used to tell
3557 gnuplot how to map this scanning convention to the Cartesian convention shown
3558 in plots, i.e., x/y/z. The qualifier for scan is a two or three letter code
3559 representing where point is assigned (first letter), line is assigned (second
3560 letter), and plane is assigned (third letter). For example, `scan=yx` means
3561 the fastest, point-by-point, increment should be mapped along the Cartesian
3562 y dimension and the middle, line-by-line, increment should be mapped along the
3565 When the plotting mode is `plot`, the qualifier code can include the two
3566 letters x and y. For `splot`, it can include the three letters x, y and z.
3568 There is nothing restricting the inherent mapping from point/line/plane to
3569 apply only to Cartesian coordinates. For this reason there are cylindrical
3570 coordinate synonyms for the qualifier codes where t (theta), r and z are
3571 analogous to the x, y and z of Cartesian coordinates.
3573 ?binary general keywords transpose
3574 Shorthand notation for `scan=yx` or `scan=yxz`.
3576 ?binary general keywords dx
3577 When gnuplot generates coordinates, it uses the spacing described by these
3578 keywords. For example `dx=10 dy=20` would mean space samples along the
3579 x dimension by 10 and space samples along the y dimension by 20. `dy` cannot
3580 appear if `dx` does not appear. Similarly, `dz` cannot appear if `dy` does not
3581 appear. If the underlying dimensions are greater than the keywords specified,
3582 the spacing of the highest dimension given is extended to the other dimensions.
3583 For example, if an image is being read from a file and only `dx=3.5` is given
3584 gnuplot uses a delta x and delta y of 3.5.
3586 The following keywords also apply only when generating coordinates. However
3587 they may also be used with matrix binary files.
3588 6 flipx, flipy, flipz
3589 ?binary general keywords flipx
3590 Sometimes the scanning directions in a binary datafile are not consistent with
3591 that assumed by gnuplot. These keywords can flip the scanning direction along
3594 ?binary general keywords origin
3595 When gnuplot generates coordinates based upon transposition and flip, it
3596 attempts to always position the lower left point in the array at the origin,
3597 i.e., the data lies in the first quadrant of a Cartesian system after transpose
3600 To position the array somewhere else on the graph, the `origin` keyword directs
3601 gnuplot to position the lower left point of the array at a point specified by a
3602 tuple. The tuple should be a double for `plot` and a triple for `splot`.
3603 For example, `origin=(100,100):(100,200)` is for two records in the file and
3604 intended for plotting in two dimensions. A second example, `origin=(0,0,3.5)`,
3605 is for plotting in three dimensions.
3607 ?binary general keywords center
3608 Similar to `origin`, this keyword will position the array such that its center
3609 lies at the point given by the tuple. For example, `center=(0,0)`. Center
3610 does not apply when the size of the array is `Inf`.
3612 ?binary general keywords rotate
3613 The transpose and flip commands provide some flexibility in generating and
3614 orienting coordinates. However, for full degrees of freedom, it is possible to
3615 apply a rotational vector described by a rotational angle in two dimensions.
3617 The `rotate` keyword applies to the two-dimensional plane, whether it be `plot`
3618 or `splot`. The rotation is done with respect to the positive angle of the
3621 The angle can be expressed in radians, radians as a multiple of pi, or degrees.
3622 For example, `rotate=1.5708`, `rotate=0.5pi` and `rotate=90deg` are equivalent.
3624 If `origin` is specified, the rotation is done about the lower left sample
3625 point before translation. Otherwise, the rotation is done about the array
3628 ?binary general keywords perpendicular
3629 For `splot`, the concept of a rotational vector is implemented by a triple
3630 representing the vector to be oriented normal to the two-dimensional x-y plane.
3631 Naturally, the default is (0,0,1). Thus specifying both rotate and
3632 perpendicular together can orient data myriad ways in three-space.
3634 The two-dimensional rotation is done first, followed by the three-dimensional
3635 rotation. That is, if R' is the rotational 2 x 2 matrix described by an angle,
3636 and P is the 3 x 3 matrix projecting (0,0,1) to (xp,yp,zp), let R be
3637 constructed from R' at the upper left sub-matrix, 1 at element 3,3 and zeros
3638 elsewhere. Then the matrix formula for translating data is v' = P R v, where v
3639 is the 3 x 1 vector of data extracted from the data file. In cases where the
3640 data of the file is inherently not three-dimensional, logical rules are used to
3641 place the data in three-space. (E.g., usually setting the z-dimension value to
3642 zero and placing 2D data in the x-y plane.)
3646 ?binary general examples
3649 # Selects two float values (second one implicit) with a float value
3650 # discarded between them for an indefinite length of 1D data.
3651 plot '<file_name>' binary format="%float%*float" using 1:2 with lines
3653 # The data file header contains all details necessary for creating
3654 # coordinates from an EDF file.
3655 plot '<file_name>' binary filetype=edf with image
3656 plot '<file_name>.edf' binary filetype=auto with image
3658 # Selects three unsigned characters for components of a raw RGB image
3659 # and flips the y-dimension so that typical image orientation (start
3660 # at top left corner) translates to the Cartesian plane. Pixel
3661 # spacing is given and there are two images in the file. One of them
3662 # is translated via origin.
3663 plot '<file_name>' binary array=512x1024:1024x512 format='%uchar' \
3664 dx=2:1 dy=1:2 origin=(0,0):(1024,1024) flipy u 1:2:3 w rgbimage
3666 # Four separate records in which the coordinates are part of the
3667 # data file. The file was created with a endianess different from
3668 # the system on which gnuplot is running.
3669 splot '<file_name>' binary record=30:30:29:26 endian=swap u 1:2:3
3671 See also `binary matrix`.
3673 ?commands plot datafile every
3674 ?plot datafile every
3679 The `every` keyword allows a periodic sampling of a data set to be plotted.
3681 In the discussion a "point" is a datum defined by a single record in the
3682 file; "block" here will mean the same thing as "datablock" (see `glossary`).
3685 plot 'file' every {<point_incr>}
3692 The data points to be plotted are selected according to a loop from
3693 <`start_point`> to <`end_point`> with increment <`point_incr`> and the
3694 blocks according to a loop from <`start_block`> to <`end_block`> with
3695 increment <`block_incr`>.
3697 The first datum in each block is numbered '0', as is the first block in the
3700 Note that records containing unplottable information are counted.
3702 Any of the numbers can be omitted; the increments default to unity, the start
3703 values to the first point or block, and the end values to the last point or
3704 block. If `every` is not specified, all points in all lines are plotted.
3707 every :::3::3 # selects just the fourth block ('0' is first)
3708 every :::::9 # selects the first 10 blocks
3709 every 2:2 # selects every other point in every other block
3710 every ::5::15 # selects points 5 through 15 in each block
3713 ^ <a href="http://www.gnuplot.info/demo/simple.html">
3714 simple plot demos (simple.dem)
3717 ^ <a href="http://www.gnuplot.info/demo/surface1.html">
3718 Non-parametric splot demos
3721 ^ <a href="http://gnuplot.sourceforge.net/demo/surface2.html">
3722 Parametric splot demos
3726 ?commands plot datafile example
3727 ?plot datafile example
3732 This example plots the data in the file "population.dat" and a theoretical
3735 pop(x) = 103*exp((1965-x)/10)
3736 plot [1960:1990] 'population.dat', pop(x)
3738 The file "population.dat" might contain:
3740 # Gnu population in Antarctica since 1965
3747 ^ <img align=bottom src="http://www.gnuplot.info/doc/population.gif" alt="[population.gif]" width=640 height=480>
3749 ?commands plot datafile index
3750 ?plot datafile index
3755 The `index` keyword allows you to select specific data sets in a multi-data-set
3759 plot 'file' index <m>{{:<n>}:<p>}
3761 Data sets are separated by pairs of blank records. `index <m>` selects only
3762 set <m>; `index <m>:<n>` selects sets in the range <m> to <n>; and `index
3763 <m>:<n>:<p>` selects indices <m>, <m>+<p>, <m>+2<p>, etc., but stopping at
3764 <n>. Following C indexing, the index 0 is assigned to the first data set in
3765 the file. Specifying too large an index results in an error message. If
3766 `index` is not specified, all sets are plotted as a single data set.
3769 plot 'file' index 4:5
3771 For each point in the file, the index value of the data set it appears in is
3772 available via the pseudo-column `column(-2)`. This leads to an alternative way
3773 of distinguishing individual data sets within a file as shown below. This is
3774 more awkward that the `index` command if all you are doing is selecting one
3775 data set for plotting, but is very useful if you want to assign different
3776 properties to each data set. See `lc variable`.
3779 plot 'file' using 1:(column(-2)==4 ? $2 : NaN) # very awkward
3780 plot 'file' using 1:2:(column(-2)) linecolor variable # very useful!
3783 ^ <a href="http://www.gnuplot.info/demo/multimsh.html">
3784 ^ splot with indices demo.
3787 ?commands plot datafile smooth
3788 ?plot datafile smooth
3793 `gnuplot` includes a few general-purpose routines for interpolation and
3794 approximation of data; these are grouped under the `smooth` option. More
3795 sophisticated data processing may be performed by preprocessing the data
3796 externally or by using `fit` with an appropriate model.
3799 smooth {unique | frequency | csplines | acsplines | bezier | sbezier}
3801 `unique` and `frequency` plot the data after making them monotonic. Each of
3802 the other routines uses the data to determine the coefficients of a
3803 continuous curve between the endpoints of the data. This curve is then
3804 plotted in the same manner as a function, that is, by finding its value at
3805 uniform intervals along the abscissa (see `set samples`) and connecting these
3806 points with straight line segments (if a line style is chosen).
3808 If `autoscale` is in effect, the ranges will be computed such that the
3809 plotted curve lies within the borders of the graph.
3811 If `autoscale` is not in effect, and the smooth option is either `acspline`
3812 or `cspline`, the sampling of the generated curve is
3813 done across the intersection of the x range covered by the input data and
3814 the fixed abscissa range as defined by `set xrange`.
3816 If too few points are available to allow the selected option to be applied,
3817 an error message is produced. The minimum number is one for `unique` and
3818 `frequency`, four for `acsplines`, and three for the others.
3820 The `smooth` options have no effect on function plots.
3822 ?commands plot datafile smooth acsplines
3823 ?plot datafile smooth acsplines
3824 ?data-file smooth acsplines
3825 ?datafile smooth acsplines
3826 ?plot smooth acsplines
3830 The `acsplines` option approximates the data with a "natural smoothing spline".
3831 After the data are made monotonic in x (see `smooth unique`), a curve is
3832 piecewise constructed from segments of cubic polynomials whose coefficients
3833 are found by the weighting the data points; the weights are taken from the
3834 third column in the data file. That default can be modified by the third
3835 entry in the `using` list, e.g.,
3836 plot 'data-file' using 1:2:(1.0) smooth acsplines
3838 Qualitatively, the absolute magnitude of the weights determines the number
3839 of segments used to construct the curve. If the weights are large, the
3840 effect of each datum is large and the curve approaches that produced by
3841 connecting consecutive points with natural cubic splines. If the weights are
3842 small, the curve is composed of fewer segments and thus is smoother; the
3843 limiting case is the single segment produced by a weighted linear least
3844 squares fit to all the data. The smoothing weight can be expressed in terms
3845 of errors as a statistical weight for a point divided by a "smoothing factor"
3846 for the curve so that (standard) errors in the file can be used as smoothing
3851 plot 'data_file' using 1:2:(sw($3,100)) smooth acsplines
3853 ?commands plot datafile smooth bezier
3854 ?plot datafile smooth bezier
3856 ?data-file smooth bezier
3857 ?datafile smooth bezier
3861 The `bezier` option approximates the data with a Bezier curve of degree n
3862 (the number of data points) that connects the endpoints.
3864 ?commands plot datafile smooth csplines
3865 ?plot datafile smooth csplines
3866 ?plot smooth csplines
3867 ?data-file smooth csplines
3868 ?datafile smooth csplines
3872 The `csplines` option connects consecutive points by natural cubic splines
3873 after rendering the data monotonic (see `smooth unique`).
3875 ?commands plot datafile smooth sbezier
3876 ?plot datafile smooth sbezier
3877 ?plot smooth sbezier
3878 ?data-file smooth sbezier
3879 ?datafile smooth sbezier
3883 The `sbezier` option first renders the data monotonic (`unique`) and then
3884 applies the `bezier` algorithm.
3886 ?commands plot datafile smooth unique
3887 ?plot datafile smooth unique
3889 ?data-file smooth unique
3890 ?datafile smooth unique
3894 The `unique` option makes the data monotonic in x; points with the same
3895 x-value are replaced by a single point having the average y-value. The
3896 resulting points are then connected by straight line segments.
3898 ^ <a href="http://www.gnuplot.info/demo/mgr.html">
3903 ?commands plot datafile smooth frequency
3904 ?plot datafile smooth frequency
3905 ?plot smooth frequency
3906 ?data-file smooth frequency
3907 ?datafile smooth frequency
3911 The `frequency` option makes the data monotonic in x; points with the same
3912 x-value are replaced by a single point having the summed y-values. The
3913 resulting points are then connected by straight line segments.
3915 ?commands plot datafile special-filenames
3916 ?plot datafile special-filenames
3917 ?plot special-filenames
3918 ?datafile special-filenames
3920 A special filename of `'-'` specifies that the data are inline; i.e., they
3921 follow the command. Only the data follow the command; `plot` options like
3922 filters, titles, and line styles remain on the `plot` command line. This is
3923 similar to << in unix shell script, and $DECK in VMS DCL. The data are
3924 entered as though they are being read from a file, one data point per record.
3925 The letter "e" at the start of the first column terminates data entry. The
3926 `using` option can be applied to these data---using it to filter them through
3927 a function might make sense, but selecting columns probably doesn't!
3929 `'-'` is intended for situations where it is useful to have data and commands
3930 together, e.g., when `gnuplot` is run as a sub-process of some front-end
3931 application. Some of the demos, for example, might use this feature. While
3932 `plot` options such as `index` and `every` are recognized, their use forces
3933 you to enter data that won't be used. For example, while
3935 plot '-' index 0, '-' index 1
3967 is a lot easier to type.
3969 If you use `'-'` with `replot`, you may need to enter the data more than once
3972 A blank filename ('') specifies that the previous filename should be reused.
3973 This can be useful with things like
3975 plot 'a/very/long/filename' using 1:2, '' using 1:3, '' using 1:4
3977 (If you use both `'-'` and `''` on the same `plot` command, you'll need to
3978 have two sets of inline data, as in the example above.)
3980 On some computer systems with a popen function (Unix), the datafile can be
3981 piped through a shell command by starting the file name with a '<'. For
3984 pop(x) = 103*exp(-x/10)
3985 plot "< awk '{print $1-1965, $2}' population.dat", pop(x)
3987 would plot the same information as the first population example but with
3988 years since 1965 as the x axis. If you want to execute this example, you
3989 have to delete all comments from the data file above or substitute the
3990 following command for the first part of the command above (the part up to
3993 plot "< awk '$0 !~ /^#/ {print $1-1965, $2}' population.dat"
3995 While this approach is most flexible, it is possible to achieve simple
3996 filtering with the `using` or `thru` keywords.
3998 ?commands plot datafile thru
4004 The `thru` function is provided for backward compatibility.
4007 plot 'file' thru f(x)
4009 It is equivalent to:
4011 plot 'file' using 1:(f($2))
4013 While the latter appears more complex, it is much more flexible. The more
4016 plot 'file' thru f(y)
4018 also works (i.e. you can use y as the dummy variable).
4020 `thru` is parsed for `splot` and `fit` but has no effect.
4022 ?commands plot datafile using
4023 ?plot datafile using
4028 The most common datafile modifier is `using`.
4031 plot 'file' using {<entry> {:<entry> {:<entry> ...}}} {'format'}
4033 If a format is specified, each datafile record is read using the C library's
4034 'scanf' function, with the specified format string. Otherwise the record is
4035 read and broken into columns. By default the separation between columns is
4036 whitespace (spaces and/or tabs), but see `datafile separator`.
4038 Each <entry> may be a simple column number that selects the value from one
4039 field of the input fit, an expression enclosed in parentheses, or empty.
4041 If the entry is an expression in parentheses, then the function column(N) may
4042 be used to indicate the value in column N. That is, column(1) refers to the
4043 first item read, column(2) to the second, and so on. The special symbols
4044 $1, $2, ... are shorthand for column(1), column(2) ... The function `valid(N)`
4045 tests whether the value in the Nth column is a valid number.
4047 In addition to the actual columns 1...N in the input data file, gnuplot
4048 presents data from several "pseudo-columns" that hold bookkeeping information.
4049 E.g. $0 or column(0) returns the sequence number of this data record within a
4052 An empty <entry> will default to its order in the list of entries.
4053 For example, `using ::4` is interpreted as `using 1:2:4`.
4055 If the `using` list has but a single entry, that <entry> will be used for y
4056 and the data point number (pseudo-column $0) is used for x; for example,
4057 "`plot 'file' using 1`" is identical to "`plot 'file' using 0:1`".
4058 If the `using` list has two entries, these will be used for x and y.
4059 See `set style` and `fit` for details about plotting styles that make use of
4060 data from additional columns of input.
4062 'scanf' accepts several numerical specifications but `gnuplot`
4063 requires all inputs to be double-precision floating-point variables,
4064 so "%lf" is essentially the only permissible specifier.
4065 A format string given by the user must contain at least one such
4066 input specifier, and no more than seven of them.
4067 'scanf' expects to see white space---a blank, tab
4068 ("\t"), newline ("\n"), or formfeed ("\f")---between numbers; anything else
4069 in the input stream must be explicitly skipped.
4071 Note that the use of "\t", "\n", or "\f" requires use of double-quotes
4072 rather than single-quotes.
4075 ?commands plot datafile using examples
4076 ?plot datafile using examples
4077 ?datafile using examples
4079 This creates a plot of the sum of the 2nd and 3rd data against the first:
4080 The format string specifies comma- rather than space-separated columns.
4081 The same result could be achieved by specifying `set datafile separator ","`.
4082 plot 'file' using 1:($2+$3) '%lf,%lf,%lf'
4084 In this example the data are read from the file "MyData" using a more
4086 plot 'MyData' using "%*lf%lf%*20[^\n]%lf"
4088 The meaning of this format is:
4090 %*lf ignore a number
4091 %lf read a double-precision number (x by default)
4092 %*20[^\n] ignore 20 non-newline characters
4093 %lf read a double-precision number (y by default)
4095 One trick is to use the ternary `?:` operator to filter data:
4097 plot 'file' using 1:($3>10 ? $2 : 1/0)
4099 which plots the datum in column two against that in column one provided
4100 the datum in column three exceeds ten. `1/0` is undefined; `gnuplot`
4101 quietly ignores undefined points, so unsuitable points are suppressed.
4102 Or you can use the pre-defined variable NaN to achieve the same result.
4105 In fact, you can use a constant expression for the column number, provided it
4106 doesn't start with an opening parenthesis; constructs like `using
4107 0+(complicated expression)` can be used. The crucial point is that the
4108 expression is evaluated once if it doesn't start with a left parenthesis, or
4109 once for each data point read if it does.
4111 If timeseries data are being used, the time can span multiple columns. The
4112 starting column should be specified. Note that the spaces within the time
4113 must be included when calculating starting columns for other data. E.g., if
4114 the first element on a line is a time with an embedded space, the y value
4115 should be specified as column three.
4117 It should be noted that `plot 'file'`, `plot 'file' using 1:2`, and `plot
4118 'file' using ($1):($2)` can be subtly different: 1) if `file` has some lines
4119 with one column and some with two, the first will invent x values when they
4120 are missing, the second will quietly ignore the lines with one column, and
4121 the third will store an undefined value for lines with one point (so that in
4122 a plot with lines, no line joins points across the bad point); 2) if a line
4123 contains text at the first column, the first will abort the plot on an error,
4124 but the second and third should quietly skip the garbage.
4126 In fact, it is often possible to plot a file with lots of lines of garbage at
4127 the top simply by specifying
4129 plot 'file' using 1:2
4131 However, if you want to leave text in your data files, it is safer to put the
4132 comment character (#) in the first column of the text lines.
4133 ^ See also the web page
4134 ^ <a href="http://www.gnuplot.info/demo/using.html">
4138 If gnuplot is built with configuration option --enable-datastrings, then
4139 additional modifiers to `using` can specify handling of text fields in the
4140 datafile. See `datastrings`, `using xticlabels`, `using title`.
4144 If gnuplot is built with configuration option --enable-datastrings, then
4145 the first entry of a column of the input data file can be used as a string
4146 to provide the plot title in the key box. The column containing specified
4147 is independent of the column[s] used for the plot itself.
4149 plot 'data' using 1:($2/$3) title column(N)
4151 In this case the entry in the first row of column N will be used for the
4152 key entry of the plot constructed from dividing column 2 by column 3.
4153 The entry in the first row of columns 2 and 3 will be ignored.
4157 ?plot using xticlabels
4158 If gnuplot is built with configuration option --enable-datastrings, then
4159 a column of the input data file can be used to label axis tic marks.
4160 The format of such a plot command is
4162 plot 'datafile' using <xcol>:<ycol>:xticlabels(<labelcol>) with <plotstyle>
4164 Tic labels may be read for any of the plot axes: x x2 y y2 z.
4165 The `ticlabels(<labelcol>)` specifiers must come after all of the data
4166 coordinate specifiers in the `using` portion of the command.
4167 For each data point which has a valid set of X,Y[,Z] coordinates,
4168 the text field found in column <labelcol> is added to the list of xtic labels
4169 at the same X coordinate as the point it belongs to. `xticlabels(<labelcol>)`
4170 may be shortened to `xtic(<labelcol>)`.
4174 splot "data" using 2:4:6:xtic(1):ytic(3):ztic(6)
4176 In this example the x and y axis tic labels are taken from different columns
4177 than the x and y coordinate values. The z axis tics, however, are generated
4178 from the z coordinate of the corresponding point.
4181 ?plot using x2ticlabels
4182 See `plot using xticlabels`.
4185 ?plot using yticlabels
4186 See `plot using xticlabels`.
4189 ?plot using y2ticlabels
4190 See `plot using xticlabels`.
4193 ?plot using zticlabels
4194 See `plot using xticlabels`.
4196 ?commands plot errorbars
4197 ?commands splot errorbars
4201 Error bars are supported for 2-d data file plots by reading one to four
4202 additional columns (or `using` entries); these additional values are used in
4203 different ways by the various errorbar styles.
4205 In the default situation, `gnuplot` expects to see three, four, or six
4206 numbers on each line of the data file---either
4209 (x, y, ylow, yhigh),
4211 (x, y, xlow, xhigh),
4212 (x, y, xdelta, ydelta), or
4213 (x, y, xlow, xhigh, ylow, yhigh).
4215 The x coordinate must be specified. The order of the numbers must be
4216 exactly as given above, though the `using` qualifier can manipulate the order
4217 and provide values for missing columns. For example,
4219 plot 'file' with errorbars
4220 plot 'file' using 1:2:(sqrt($1)) with xerrorbars
4221 plot 'file' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars
4223 The last example is for a file containing an unsupported combination of
4224 relative x and absolute y errors. The `using` entry generates absolute x min
4225 and max from the relative error.
4227 The y error bar is a vertical line plotted from (x, ylow) to (x,
4228 yhigh). If ydelta is specified instead of ylow and yhigh, ylow = y -
4229 ydelta and yhigh = y + ydelta are derived. If there are only two
4230 numbers on the record, yhigh and ylow are both set to y. The x error
4231 bar is a horizontal line computed in the same fashion. To get lines
4232 plotted between the data points, `plot` the data file twice, once with
4233 errorbars and once with lines (but remember to use the `notitle`
4234 option on one to avoid two entries in the key). Alternately, use the
4235 errorlines command (see `errorlines`).
4237 The error bars have crossbars at each end unless `set bars` is used
4238 (see `set bars` for details).
4240 If autoscaling is on, the ranges will be adjusted to include the error bars.
4243 ^ <a href="http://gnuplot.sourceforge.net/demo/mgr.html">
4247 See `plot using`, `plot with`, and `set style` for more information.
4249 ?commands plot errorlines
4250 ?commands splot errorlines
4254 Lines with error bars are supported for 2-d data file plots by reading
4255 one to four additional columns (or `using` entries); these additional
4256 values are used in different ways by the various errorlines styles.
4258 In the default situation, `gnuplot` expects to see three, four, or six
4259 numbers on each line of the data file---either
4262 (x, y, ylow, yhigh),
4264 (x, y, xlow, xhigh),
4265 (x, y, xdelta, ydelta), or
4266 (x, y, xlow, xhigh, ylow, yhigh).
4268 The x coordinate must be specified. The order of the numbers must be
4269 exactly as given above, though the `using` qualifier can manipulate
4270 the order and provide values for missing columns. For example,
4272 plot 'file' with errorlines
4273 plot 'file' using 1:2:(sqrt($1)) with xerrorlines
4274 plot 'file' using 1:2:($1-$3):($1+$3):4:5 with xyerrorlines
4276 The last example is for a file containing an unsupported combination
4277 of relative x and absolute y errors. The `using` entry generates
4278 absolute x min and max from the relative error.
4280 The y error bar is a vertical line plotted from (x, ylow) to (x,
4281 yhigh). If ydelta is specified instead of ylow and yhigh, ylow = y -
4282 ydelta and yhigh = y + ydelta are derived. If there are only two
4283 numbers on the record, yhigh and ylow are both set to y. The x error
4284 bar is a horizontal line computed in the same fashion.
4286 The error bars have crossbars at each end unless `set bars` is used
4287 (see `set bars` for details).
4289 If autoscaling is on, the ranges will be adjusted to include the error bars.
4291 See `plot using`, `plot with`, and `set style` for more information.
4293 ?commands plot parametric
4294 ?commands splot parametric
4297 When in parametric mode (`set parametric`) mathematical expressions must be
4298 given in pairs for `plot` and in triplets for `splot`.
4302 splot cos(u)*cos(v),cos(u)*sin(v),sin(u)
4304 Data files are plotted as before, except any preceding parametric function
4305 must be fully specified before a data file is given as a plot. In other
4306 words, the x parametric function (`sin(t)` above) and the y parametric
4307 function (`t**2` above) must not be interrupted with any modifiers or data
4308 functions; doing so will generate a syntax error stating that the parametric
4309 function is not fully specified.
4311 Other modifiers, such as `with` and `title`, may be specified only after the
4312 parametric function has been completed:
4314 plot sin(t),t**2 title 'Parametric example' with linespoints
4317 ^ <a href="http://www.gnuplot.info/demo/param.html">
4318 Parametric Mode Demos.
4321 ?commands plot ranges
4322 ?commands splot ranges
4326 The optional ranges specify the region of the graph that will be displayed.
4329 [{<dummy-var>=}{{<min>}:{<max>}}]
4332 The first form applies to the independent variable (`xrange` or `trange`, if
4333 in parametric mode). The second form applies to the dependent variable
4334 `yrange` (and `xrange`, too, if in parametric mode). <dummy-var> is a new
4335 name for the independent variable. (The defaults may be changed with `set
4336 dummy`.) The optional <min> and <max> terms can be constant expressions or *.
4338 In non-parametric mode, the order in which ranges must be given is `xrange`
4341 In parametric mode, the order for the `plot` command is `trange`, `xrange`,
4342 and `yrange`. The following `plot` command shows setting the `trange` to
4343 [-pi:pi], the `xrange` to [-1.3:1.3] and the `yrange` to [-1:1] for the
4344 duration of the graph:
4346 plot [-pi:pi] [-1.3:1.3] [-1:1] sin(t),t**2
4348 Note that the x2range and y2range cannot be specified here---`set x2range`
4349 and `set y2range` must be used.
4351 Ranges are interpreted in the order listed above for the appropriate mode.
4352 Once all those needed are specified, no further ones must be listed, but
4353 unneeded ones cannot be skipped---use an empty range `[]` as a placeholder.
4355 `*` can be used to allow autoscaling of either of min and max. See also
4358 Ranges specified on the `plot` or `splot` command line affect only that
4359 graph; use the `set xrange`, `set yrange`, etc., commands to change the
4360 default ranges for future graphs.
4362 With time data, you must provide the range (in the same manner as the time
4363 appears in the datafile) within quotes. `gnuplot` uses the `timefmt` string
4364 to read the value---see `set timefmt`.
4368 This uses the current ranges:
4371 This sets the x range only:
4372 plot [-10:30] sin(pi*x)/(pi*x)
4374 This is the same, but uses t as the dummy-variable:
4375 plot [t = -10 :30] sin(pi*t)/(pi*t)
4377 This sets both the x and y ranges:
4378 plot [-pi:pi] [-3:3] tan(x), 1/x
4380 This sets only the y range, and turns off autoscaling on both axes:
4381 plot [ ] [-2:sin(5)*-8] sin(x)**besj0(x)
4383 This sets xmax and ymin only:
4384 plot [:200] [-pi:] exp(sin(x))
4386 This sets the x range for a timeseries:
4387 set timefmt "%d/%m/%y %H:%M"
4388 plot ["1/6/93 12:00":"5/6/93 12:00"] 'timedata.dat'
4391 ?commands plot title
4392 ?commands splot title
4395 A line title for each function and data set appears in the key, accompanied
4396 by a sample of the line and/or symbol used to represent it. It can be
4397 changed by using the `title` option.
4400 title "<title>" | notitle ["<ignored title>"]
4402 where <title> is the new title of the line and must be enclosed in quotes.
4403 The quotes will not be shown in the key. A special character may be given as
4404 a backslash followed by its octal value ("\345"). The tab character "\t" is
4405 understood. Note that backslash processing occurs only for strings enclosed
4406 in double quotes---use single quotes to prevent such processing. The newline
4407 character "\n" is not processed in key entries in either type of string.
4409 The line title and sample can be omitted from the key by using the keyword
4410 `notitle`. A null title (`title ''`) is equivalent to `notitle`. If only
4411 the sample is wanted, use one or more blanks (`title ' '`). If `notitle`
4412 is followed by a string this string is ignored.
4414 If `key autotitles` is set (which is the default) and neither `title` nor
4415 `notitle` are specified the line title is the function name or the file name as
4416 it appears on the `plot` command. If it is a file name, any datafile modifiers
4417 specified will be included in the default title.
4419 The layout of the key itself (position, title justification, etc.) can be
4420 controlled by `set key`. Please see `set key` for details.
4424 This plots y=x with the title 'x':
4427 This plots x squared with title "x^2" and file "data.1" with title
4429 plot x**2 title "x^2", 'data.1' t "measured data"
4431 This puts an untitled circular border around a polar graph:
4432 set polar; plot my_function(t), 1 notitle
4435 ?commands splot with
4436 ?commands plot style
4437 ?commands splot style
4444 Functions and data may be displayed in one of a large number of styles.
4445 The `with` keyword provides the means of selection.
4448 with <style> { {linestyle | ls <line_style>}
4449 | {{linetype | lt <line_type>}
4450 {linewidth | lw <line_width>}
4451 {linecolor | lc <colorspec>}
4452 {pointtype | pt <point_type>}
4453 {pointsize | ps <point_size>}
4454 {fill | fs <fillstyle>}
4455 {nohidden3d | nocontours}
4459 where <style> is either `lines`, `points`, `linespoints`, `impulses`,
4460 `dots`, `steps`, `fsteps`, `histeps`, `errorbars`, `labels`, `xerrorbars`,
4461 `yerrorbars`, `xyerrorbars`, `errorlines`, `xerrorlines`, `yerrorlines`,
4462 `xyerrorlines`, `boxes`, `histograms`, `filledcurves`, `boxerrorbars`,
4463 `boxxyerrorbars`, `financebars`, `candlesticks`, `vectors`, `image`,
4464 `rgbimage` or `pm3d`. Some of these styles require additional information.
4465 See `plotting styles` for details of each style. `fill` is relevant only
4466 to certain 2D plots (currently `boxes` `boxxyerrorbars` and `candlesticks`).
4467 Note that `filledcurves` and `pm3d` can take an additional option not
4468 listed above (the latter only when used in the `splot` command)---see
4469 their help or examples below for more details.
4471 Default styles are chosen with the `set style function` and `set style data`
4474 By default, each function and data file will use a different line type and
4475 point type, up to the maximum number of available types. All terminal
4476 drivers support at least six different point types, and re-use them, in
4477 order, if more are required. The LaTeX driver supplies an additional six
4478 point types (all variants of a circle), and thus will only repeat after 12
4479 curves are plotted with points. The PostScript drivers (`postscript`)
4480 supplies a total of 64.
4482 If you wish to choose the line or point type for a single plot, <line_type>
4483 and <point_type> may be specified. These are positive integer constants (or
4484 expressions) that specify the line type and point type to be used for the
4485 plot. Use `test` to display the types available for your terminal.
4487 You may also scale the line width and point size for a plot by using
4488 <line_width> and <point_size>, which are specified relative to the default
4489 values for each terminal. The pointsize may also be altered
4490 globally---see `set pointsize` for details. But note that both <point_size>
4491 as set here and as set by `set pointsize` multiply the default point
4492 size---their effects are not cumulative. That is,
4493 `set pointsize 2; plot x w p ps 3` will use points three times default size,
4496 It is also possible to specify `pointsize variable` either as part of a
4497 line style or for an individual plot. In this case one extra column of input
4498 is required, i.e. 3 columns for a 2D plot and 4 columns for a 3D splot. The
4499 size of each individual point is determined by multiplying the global
4500 pointsize by the value read from the data file.
4502 If you have defined specific line type/width and point type/size combinations
4503 with `set style line`, one of these may be selected by setting <line_style> to
4504 the index of the desired style.
4506 If gnuplot was built with `pm3d` support, the special keyword `palette` is
4507 allowed for smooth color change of lines, points and dots in `splots`. The
4508 color is chosen from a smooth palette which was set previously with the
4509 command `set palette`. The color value corresponds to the z-value of the
4510 point coordinates or to the color coordinate if specified by the 4th parameter
4511 in `using`. Both 2d and 3d plots (`plot` and `splot` commands) can use palette
4512 colors as specified by either their fractional value or the corresponding value
4513 mapped to the colorbox range. A palette color value can also be read from an
4514 explicitly specified column in the `using` specifier.
4515 Z value. See `colors`, `set palette`, `linetype`.
4517 The keyword `nohidden3d` applies only to plots made with the `splot` command.
4518 Normally the global option `set hidden3d` applies to all plots in the graph.
4519 You can attach the `nohidden3d` option to any individual plots that you want
4520 to exclude from the hidden3d processing. The individual elements other than
4521 surfaces (i.e. lines, dots, labels, ...) of a plot marked `nohidden3d` will all
4522 be drawn, even if they would normally be obscured by other plot elements.
4524 Similarly, the keyword `nocontours` will turn off contouring for an individual
4525 plot even if the global property "set contour" is active.
4527 The keywords may be abbreviated as indicated.
4529 Note that the `linewidth`, `pointsize` and `palette` options are not supported
4534 This plots sin(x) with impulses:
4535 plot sin(x) with impulses
4537 This plots x with points, x**2 with the default:
4538 plot x w points, x**2
4540 This plots tan(x) with the default function style, file "data.1" with lines:
4541 plot [ ] [-2:5] tan(x), 'data.1' with l
4543 This plots "leastsq.dat" with impulses:
4544 plot 'leastsq.dat' w i
4546 This plots the data file "population" with boxes:
4547 plot 'population' with boxes
4549 This plots "exper.dat" with errorbars and lines connecting the points
4550 (errorbars require three or four columns):
4551 plot 'exper.dat' w lines, 'exper.dat' notitle w errorbars
4553 Another way to plot "exper.dat" with errorlines (errorbars require three
4555 plot 'exper.dat' w errorlines
4557 This plots sin(x) and cos(x) with linespoints, using the same line type but
4558 different point types:
4559 plot sin(x) with linesp lt 1 pt 3, cos(x) with linesp lt 1 pt 4
4561 This plots file "data" with points of type 3 and twice usual size:
4562 plot 'data' with points pointtype 3 pointsize 2
4564 This plots file "data" with variable pointsize read from column 4
4565 plot 'data' using 1:2:4 with points pt 5 pointsize variable
4567 This plots two data sets with lines differing only by weight:
4568 plot 'd1' t "good" w l lt 2 lw 3, 'd2' t "bad" w l lt 2 lw 1
4570 This plots filled curve of x*x and a color stripe:
4571 plot x*x with filledcurve closed, 40 with filledcurve y1=10
4573 This plots x*x and a color box:
4574 plot x*x, (x>=-5 && x<=5 ? 40 : 1/0) with filledcurve y1=10 lt 8
4576 This plots a surface with color lines:
4577 splot x*x-y*y with line palette
4579 This plots two color surfaces at different altitudes:
4580 splot x*x-y*y with pm3d, x*x+y*y with pm3d at t
4585 The `print` command prints the value of <expression> to the screen. It is
4586 synonymous with `pause 0`. <expression> may be anything that `gnuplot` can
4587 evaluate that produces a number, or it can be a string.
4590 print <expression> {, <expression>, ...}
4592 See `expressions`. The output file can be set with `set print`.
4596 The `pwd` command prints the name of the working directory to the screen.
4600 The `exit` and `quit` commands and END-OF-FILE character will exit `gnuplot`.
4601 Each of these commands will clear the output device (as does the `clear`
4602 command) before exiting.
4607 raise {plot_window_nb}
4609 The `raise` command raises (opposite to `lower`) plot window(s) associated
4610 with the interactive terminal of your gnuplot session, i.e. `pm`, `win`, `wxt`
4611 or `x11`. It puts the plot window to front (top) in the z-order windows stack
4612 of the window manager of your desktop.
4614 As `x11` and `wxt` support multiple plot windows, then by default they raise
4615 these windows in descending order of most recently created on top to the least
4616 recently created on bottom. If a plot number is supplied as an optional
4617 parameter, only the associated plot window will be raised if it exists.
4619 The optional parameter is ignored for single plot-windows terminal, i.e. `pm`
4622 If the window is not raised under X11, then (1) they don't run in the same
4623 X11 session (telnet or ssh session, for example), or (2) raising is blocked
4624 by your window manager. On KDE, you may like to go to the KDE Control Center
4625 => Desktop => Window Behaviour => Advanced and set the "Focus stealing
4626 prevention level" to None (default is Low).
4630 The `replot` command without arguments repeats the last `plot` or `splot`
4631 command. This can be useful for viewing a plot with different `set` options,
4632 or when generating the same plot for several devices.
4634 Arguments specified after a `replot` command will be added onto the last
4635 `plot` or `splot` command (with an implied ',' separator) before it is
4636 repeated. `replot` accepts the same arguments as the `plot` and `splot`
4637 commands except that ranges cannot be specified. Thus you can use `replot`
4638 to plot a function against the second axes if the previous command was `plot`
4639 but not if it was `splot`.
4643 plot '-' ; ... ; replot
4645 is not recommended. `gnuplot` does not store the inline data internally, so
4646 since `replot` appends new information to the previous `plot` and then
4647 executes the modified command, the `'-'` from the initial `plot` will expect
4648 to read inline data again.
4650 Note that `replot` does not work in `multiplot` mode, since it reproduces
4651 only the last plot rather than the entire screen.
4653 See also `command-line-editing` for ways to edit the last `plot` (`splot`)
4656 See also `show plot` to show the whole current plotting command, and the
4657 possibility to copy it into the `history`.
4661 The `reread` command causes the current `gnuplot` command file, as specified
4662 by a `load` command or on the command line, to be reset to its starting
4663 point before further commands are read from it. This essentially implements
4664 an endless loop of the commands from the beginning of the command file to
4665 the `reread` command. (But this is not necessarily a disaster---`reread` can
4666 be very useful when used in conjunction with `if`. See `if` for details.)
4667 The `reread` command has no effect if input from standard input.
4671 Suppose the file "looper" contains the commands
4676 and from within `gnuplot` you submit the commands
4679 The result will be five plots (separated by the `pause` message).
4681 Suppose the file "data" contains six columns of numbers with a total yrange
4682 from 0 to 10; the first is x and the next are five different functions of x.
4683 Suppose also that the file "plotter" contains the commands
4685 plot "$0" using 1:c_p with lines linetype c_p
4686 if(c_p < n_p) reread
4687 and from within `gnuplot` you submit the commands
4693 call 'plotter' 'data'
4695 The result is a single graph consisting of five plots. The yrange must be
4696 set explicitly to guarantee that the five separate graphs (drawn on top of
4697 each other in multiplot mode) will have exactly the same axes. The linetype
4698 must be specified; otherwise all the plots would be drawn with the same type.
4699 See animate.dem in demo directory for an animated example.
4704 The `reset` command causes all graph-related options that can be set with the
4705 `set` command to take on their default values. This command is useful, e.g.,
4706 to restore the default graph settings at the end of a command file, or to
4707 return to a defined state after lots of settings have been changed within a
4708 command file. Please refer to the `set` command to see the default values
4709 that the various options take.
4711 The following `set` commands do not change the graph status and are thus left
4712 unchanged: the terminal set with `set term`, the output file set with `set
4713 output` and directory paths set with `set loadpath` and `set fontpath`.
4715 ^ <a name="save set"></a>
4718 The `save` command saves user-defined functions, variables, the `set
4719 term` status, all `set` options, or all of these, plus the last `plot`
4720 (`splot`) command to the specified file.
4723 save {<option>} '<filename>'
4725 where <option> is `functions`, `variables`, `terminal` or `set`. If
4726 no option is used, `gnuplot` saves functions, variables, `set`
4727 options and the last `plot` (`splot`) command.
4729 `save`d files are written in text format and may be read by the
4730 `load` command. For `save` with the `set` option or without any
4731 option, the `terminal` choice and the `output` filename are written
4732 out as a comment, to get an output file that works in other
4733 installations of gnuplot, without changes and without risk of
4734 unwillingly overwriting files.
4736 `save terminal` will write out just the `terminal` status, without
4737 the comment marker in front of it. This is mainly useful for
4738 switching the `terminal` setting for a short while, and getting back
4739 to the previously set terminal, afterwards, by loading the saved
4740 `terminal` status. Note that for a single gnuplot session you may
4741 rather use the other method of saving and restoring current terminal
4742 by the commands `set term push` and `set term pop`, see `set term`.
4744 The filename must be enclosed in quotes.
4746 The special filename "-" may be used to `save` commands to standard output.
4747 On systems which support a popen function (Unix), the output of save can be
4748 piped through an external program by starting the file name with a '|'.
4749 This provides a consistent interface to `gnuplot`'s internal settings to
4750 programs which communicate with `gnuplot` through a pipe. Please see
4751 help for `batch/interactive` for more details.
4755 save functions 'func.dat'
4757 save set 'options.dat'
4758 save term 'myterm.gnu'
4760 save '|grep title >t.gp'
4767 The `set` command can be used to set _lots_ of options. No screen is
4768 drawn, however, until a `plot`, `splot`, or `replot` command is given.
4770 The `show` command shows their settings; `show all` shows all the
4773 Options changed using `set` can be returned to the default state by giving the
4774 corresponding `unset` command. See also the `reset` command, which returns
4775 all settable parameters to default values.
4777 If a variable contains time/date data, `show` will display it according to
4778 the format currently defined by `set timefmt`, even if that was not in effect
4779 when the variable was initially defined.
4781 ?commands set angles
4782 ?commands show angles
4786 ?commands set angles degrees
4790 By default, `gnuplot` assumes the independent variable in polar graphs is in
4791 units of radians. If `set angles degrees` is specified before `set polar`,
4792 then the default range is [0:360] and the independent variable has units of
4793 degrees. This is particularly useful for plots of data files. The angle
4794 setting also applies to 3-d mapping as set via the `set mapping` command.
4797 set angles {degrees | radians}
4800 The angle specified in `set grid polar` is also read and displayed in the
4801 units specified by `set angles`.
4803 `set angles` also affects the arguments of the machine-defined functions
4804 sin(x), cos(x) and tan(x), and the outputs of asin(x), acos(x), atan(x),
4805 atan2(x), and arg(x). It has no effect on the arguments of hyperbolic
4806 functions or Bessel functions. However, the output arguments of inverse
4807 hyperbolic functions of complex arguments are affected; if these functions
4808 are used, `set angles radians` must be in effect to maintain consistency
4809 between input and output arguments.
4814 print y #prints {1.16933, 0.154051}
4815 print asinh(y) #prints {1.0, 0.1}
4819 print y #prints {1.16933, 0.154051}
4820 print asinh(y) #prints {57.29578, 5.729578}
4822 ^ <a href="http://www.gnuplot.info/demo/poldat.html">
4823 poldat.dem: polar plot using `set angles` demo.
4827 ?commands unset arrow
4828 ?commands show arrow
4834 Arbitrary arrows can be placed on a plot using the `set arrow` command.
4837 set arrow {<tag>} {from <position>} {to|rto <position>}
4838 { {arrowstyle | as <arrow_style>}
4839 | { {nohead | head | backhead | heads}
4840 {size <length>,<angle>{,<backangle>}}
4841 {filled | empty | nofilled}
4843 { {linestyle | ls <line_style>}
4844 | {linetype | lt <line_type>}
4845 {linewidth | lw <line_width} } } }
4850 <tag> is an integer that identifies the arrow. If no tag is given, the
4851 lowest unused tag value is assigned automatically. The tag can be used to
4852 delete or change a specific arrow. To change any attribute of an existing
4853 arrow, use the `set arrow` command with the appropriate tag and specify the
4854 parts of the arrow to be changed.
4856 The <position>s are specified by either x,y or x,y,z, and may be preceded by
4857 `first`, `second`, `graph`, `screen`, or `character` to select the coordinate
4858 system. Unspecified coordinates default to 0. The end points can be
4859 specified in one of five coordinate systems---`first` or `second` axes,
4860 `graph`, `screen`, or `character`. See `coordinates` for details. A
4861 coordinate system specifier does not carry over from the "from" position to
4862 the "to" position. Arrows outside the screen boundaries are permitted but
4863 may cause device errors. If the end point is specified by "rto" instead of
4864 "to" it is drawn relatively to the start point. For linear axes, `graph`
4865 and `screen` coordinates, the distance between the start and the end point
4866 corresponds to the given relative coordinate. For logarithmic axes, the
4867 relative given coordinate corresponds to the factor of the coordinate
4868 between start and end point. Thus, a negative relative value or zero are
4869 not allowed for logarithmic axes.
4871 Specifying `nohead` produces an arrow drawn without a head---a line segment.
4872 This gives you yet another way to draw a line segment on the plot. By
4873 default, an arrow has a head at its end. Specifying `backhead` draws an arrow
4874 head at the start point of the arrow while `heads` draws arrow heads on both
4875 ends of the line. Not all terminal types support double-ended arrows.
4877 Head size can be controlled by `size <length>,<angle>` or
4878 `size <length>,<angle>,<backangle>`, where `<length>` defines length of each
4879 branch of the arrow head and `<angle>` the angle (in degrees) they make with
4880 the arrow. `<Length>` is in x-axis units; this can be changed by `first`,
4881 `second`, `graph`, `screen`, or `character` before the <length>; see
4882 `coordinates` for details. `<Backangle>` only takes effect when `filled`
4883 or `empty` is also used. Then, `<backangle>` is the angle (in degrees) the
4884 back branches make with the arrow (in the same direction as `<angle>`).
4885 The `fig` terminal has a restricted backangle function. It supports three
4886 different angles. There are two thresholds: Below 70 degrees, the arrow head
4887 gets an indented back angle. Above 110 degrees, the arrow head has an acute
4888 back angle. Between these thresholds, the back line is straight.
4890 Specifying `filled` produces filled arrow heads (if heads are used).
4891 Filling is supported on filled-polygon capable terminals, see help of `pm3d`
4892 for their list, otherwise the arrow heads are closed but not filled.
4893 The same result (closed but not filled arrow head) is reached by specifying
4894 `empty`. Further, filling and outline is obviously not supported on
4895 terminals drawing arrows by their own specific routines, like `metafont`,
4896 `metapost`, `latex` or `tgif`.
4898 The line style may be selected from a user-defined list of line styles
4899 (see `set style line`) or may be defined here by providing values for
4900 <line_type> (an index from the default list of styles) and/or <line_width>
4901 (which is a multiplier for the default width).
4903 Note, however, that if a user-defined line style has been selected, its
4904 properties (type and width) cannot be altered merely by issuing another
4905 `set arrow` command with the appropriate index and `lt` or `lw`.
4907 If `front` is given, the arrow is written on top of the graphed data. If
4908 `back` is given (the default), the arrow is written underneath the graphed
4909 data. Using `front` will prevent an arrow from being obscured by dense data.
4913 To set an arrow pointing from the origin to (1,2) with user-defined style 5,
4915 set arrow to 1,2 ls 5
4917 To set an arrow from bottom left of plotting area to (-5,5,3), and tag the
4918 arrow number 3, use:
4919 set arrow 3 from graph 0,0 to -5,5,3
4921 To change the preceding arrow to end at 1,1,1, without an arrow head and
4922 double its width, use:
4923 set arrow 3 to 1,1,1 nohead lw 2
4925 To draw a vertical line from the bottom to the top of the graph at x=3, use:
4926 set arrow from 3, graph 0 to 3, graph 1 nohead
4928 To draw a vertical arrow with T-shape ends, use:
4929 set arrow 3 from 0,-5 to 0,5 heads size screen 0.1,90
4931 To draw an arrow relatively to the start point, where the relative distances
4932 are given in graph coordinates, use:
4933 set arrow from 0,-5 rto graph 0.1,0.1
4935 To draw an arrow with relative end point in logarithmic x axis, use:
4937 set arrow from 100,-5 rto 10,10
4938 This draws an arrow from 100,-5 to 1000,5. For the logarithmic x axis, the
4939 relative coordinate 10 means "factor 10" while for the linear y axis, the
4940 relative coordinate 10 means "difference 10".
4942 To delete arrow number 2, use:
4945 To delete all arrows, use:
4948 To show all arrows (in tag order), use:
4951 ^ <a href="http://gnuplot.sourceforge.net/demo/arrowstyle.html">
4956 ?commands set autoscale
4957 ?commands unset autoscale
4958 ?commands show autoscale
4964 Autoscaling may be set individually on the x, y or z axis or globally on all
4965 axes. The default is to autoscale all axes.
4968 set autoscale {<axes>{|min|max|fixmin|fixmax|fix} | fix | keepfix}
4969 unset autoscale {<axes>}
4972 where <axes> is either `x`, `y`, `z`, `cb`, `x2`, `y2` or `xy`. A keyword with
4973 `min` or `max` appended (this cannot be done with `xy`) tells `gnuplot` to
4974 autoscale just the minimum or maximum of that axis. If no keyword is given,
4975 all axes are autoscaled.
4977 A keyword with `fixmin`, `fixmax` or `fix` appended tells gnuplot to disable
4978 extension of the axis range to the next tic mark position, for autoscaled
4979 axes using equidistant tics; `set autoscale fix` sets this for all axes.
4980 Command `set autoscale keepfix` autoscales all axes while keeping the fix
4983 When autoscaling, the axis range is automatically computed and the dependent
4984 axis (y for a `plot` and z for `splot`) is scaled to include the range of the
4985 function or data being plotted.
4987 If autoscaling of the dependent axis (y or z) is not set, the current y or z
4990 Autoscaling the independent variables (x for `plot` and x,y for `splot`) is a
4991 request to set the domain to match any data file being plotted. If there are
4992 no data files, autoscaling an independent variable has no effect. In other
4993 words, in the absence of a data file, functions alone do not affect the x
4994 range (or the y range if plotting z = f(x,y)).
4996 Please see `set xrange` for additional information about ranges.
4998 The behavior of autoscaling remains consistent in parametric mode, (see
4999 `set parametric`). However, there are more dependent variables and hence more
5000 control over x, y, and z axis scales. In parametric mode, the independent or
5001 dummy variable is t for `plot`s and u,v for `splot`s. `autoscale` in
5002 parametric mode, then, controls all ranges (t, u, v, x, y, and z) and allows
5003 x, y, and z to be fully autoscaled.
5005 Autoscaling works the same way for polar mode as it does for parametric mode
5006 for `plot`, with the extension that in polar mode `set dummy` can be used to
5007 change the independent variable from t (see `set dummy`).
5009 When tics are displayed on second axes but no plot has been specified for
5010 those axes, x2range and y2range are inherited from xrange and yrange. This
5011 is done _before_ xrange and yrange are autoextended to a whole number of
5012 tics, which can cause unexpected results. You can use the `fixmin`
5013 or `fixmax` options to avoid this.
5017 This sets autoscaling of the y axis (other axes are not affected):
5020 This sets autoscaling only for the minimum of the y axis (the maximum of the
5021 y axis and the other axes are not affected):
5024 This disables extension of the x2 axis tics to the next tic mark,
5025 thus keeping the exact range as found in the plotted data and functions:
5026 set autoscale x2fixmin
5027 set autoscale x2fixmax
5029 This sets autoscaling of the x and y axes:
5032 This sets autoscaling of the x, y, z, x2 and y2 axes:
5035 This disables autoscaling of the x, y, z, x2 and y2 axes:
5038 This disables autoscaling of the z axis only:
5041 ?commands set autoscale parametric
5042 ?set autoscale parametric
5044 When in parametric mode (`set parametric`), the xrange is as fully scalable
5045 as the y range. In other words, in parametric mode the x axis can be
5046 automatically scaled to fit the range of the parametric function that is
5047 being plotted. Of course, the y axis can also be automatically scaled just
5048 as in the non-parametric case. If autoscaling on the x axis is not set, the
5049 current x range is used.
5051 Data files are plotted the same in parametric and non-parametric mode.
5052 However, there is a difference in mixed function and data plots: in
5053 non-parametric mode with autoscaled x, the x range of the datafile controls
5054 the x range of the functions; in parametric mode it has no influence.
5056 For completeness a last command `set autoscale t` is accepted. However, the
5057 effect of this "scaling" is very minor. When `gnuplot` determines that the
5058 t range would be empty, it makes a small adjustment if autoscaling is true.
5059 Otherwise, `gnuplot` gives an error. Such behavior may, in fact, not be very
5060 useful and the command `set autoscale t` is certainly questionable.
5062 `splot` extends the above ideas as you would expect. If autoscaling is set,
5063 then x, y, and z ranges are computed and each axis scaled to fit the
5066 ?commands set autoscale polar
5067 ?set autoscale polar
5068 When in polar mode (`set polar`), the xrange and the yrange are both found
5069 from the polar coordinates, and thus they can both be automatically scaled.
5070 In other words, in polar mode both the x and y axes can be automatically
5071 scaled to fit the ranges of the polar function that is being plotted.
5073 When plotting functions in polar mode, the rrange may be autoscaled. When
5074 plotting data files in polar mode, the trange may also be autoscaled. Note
5075 that if the trange is contained within one quadrant, autoscaling will produce
5076 a polar plot of only that single quadrant.
5078 Explicitly setting one or two ranges but not others may lead to unexpected
5081 ^ <a href="http://www.gnuplot.info/demo/poldat.html">
5090 The `set bars` command controls the tics at the ends of error bars,
5091 and also the width of the boxes in plot styles candlesticks and
5095 set bars {small | large | fullwidth | <size>}
5099 `small` is a synonym for 0.0, and `large` for 1.0.
5100 The default is 1.0 if no size is given.
5102 The keyword `fullwidth` is relevant only to histograms with errorbars.
5103 It sets the width of the errorbar ends to be the same as the width of the
5104 associated box in the histogram. It does not change the width of the box
5107 ?commands set bmargin
5110 The command `set bmargin` sets the size of the bottom margin.
5111 Please see `set margin` for details.
5113 ?commands set border
5114 ?commands unset border
5115 ?commands show border
5121 The `set border` and `unset border` commands control the display of the graph
5122 borders for the `plot` and `splot` commands. Note that the borders do not
5123 necessarily coincide with the axes; with `plot` they often do, but with
5124 `splot` they usually do not.
5127 set border {<integer>} {front | back} {linewidth | lw <line_width>}
5128 {{linestyle | ls <line_style>} | {linetype | lt <line_type>}}
5132 With a `splot` displayed in an arbitrary orientation, like `set view 56,103`,
5133 the four corners of the x-y plane can be referred to as "front", "back",
5134 "left" and "right". A similar set of four corners exist for the top surface,
5135 of course. Thus the border connecting, say, the back and right corners of the
5136 x-y plane is the "bottom right back" border, and the border connecting the top
5137 and bottom front corners is the "front vertical". (This nomenclature is
5138 defined solely to allow the reader to figure out the table that follows.)
5140 The borders are encoded in a 12-bit integer: the bottom four bits control the
5141 border for `plot` and the sides of the base for `splot`; the next four bits
5142 control the verticals in `splot`; the top four bits control the edges on top
5143 of the `splot`. In detail, `<integer>` should be the sum of the appropriate
5144 entries from the following table:
5146 @start table - first is interactive cleartext form
5148 1 bottom bottom left front
5149 2 left bottom left back
5150 4 top bottom right front
5151 8 right bottom right back
5152 16 no effect left vertical
5153 32 no effect back vertical
5154 64 no effect right vertical
5155 128 no effect front vertical
5156 256 no effect top left back
5157 512 no effect top right back
5158 1024 no effect top left front
5159 2048 no effect top right front
5160 #\begin{tabular}{|c|c|c|} \hline
5161 #\multicolumn{3}{|c|}{Graph Border Encoding} \\ \hline \hline
5162 #Bit & plot & splot \\ \hline
5163 #1 & bottom & bottom left front \\
5164 #2 & left & bottom left back \\
5165 #4 & top & bottom right front \\
5166 #8 & right & bottom right back \\
5167 #16 & no effect & left vertical \\
5168 #32 & no effect & back vertical \\
5169 #64 & no effect & right vertical \\
5170 #128 & no effect & front vertical \\
5171 #256 & no effect & top left back \\
5172 #512 & no effect & top right back \\
5173 #1024 & no effect & top left front \\
5174 #2048 & no effect & top right front \\
5178 %1@bottom@bottom left front
5179 %2@left@bottom left back
5180 %4@top@bottom right front
5181 %8@right@bottom right back
5182 %16@no effect@left vertical
5183 %32@no effect@back vertical
5184 %64@no effect@right vertical
5185 %128@no effect@front vertical
5186 %256@no effect@top left back
5187 %512@no effect@top right back
5188 %1024@no effect@top left front
5189 %2048@no effect@top right front
5192 Various bits or combinations of bits may be added together in the command.
5194 The default is 31, which is all four sides for `plot`, and base and z axis
5197 In 2D plots the border is normally drawn on top of all plots elements
5198 (`front`). If you want the border to be drawn behind the plot elements,
5199 use `set border back`.
5201 Using the optional <line_style>, <line_type> and <line_width> specifiers, the
5202 way the border lines are drawn can be influenced (limited by what the current
5203 terminal driver supports).
5205 For `plot`, tics may be drawn on edges other than bottom and left by enabling
5206 the second axes -- see `set xtics` for details.
5208 If a `splot` draws only on the base, as is the case with "`unset surface; set
5209 contour base`", then the verticals and the top are not drawn even if they are
5212 The `set grid` options 'back', 'front' and 'layerdefault' also
5213 control the order in which the border lines are drawn with respect to
5214 the output of the plotted data.
5218 Draw default borders:
5221 Draw only the left and bottom (`plot`) or both front and back bottom left
5225 Draw a complete box around a `splot`:
5228 Draw a topless box around a `splot`, omitting the front vertical:
5229 set border 127+256+512 # or set border 1023-128
5231 Draw only the top and right borders for a `plot` and label them as axes:
5232 unset xtics; unset ytics; set x2tics; set y2tics; set border 12
5235 ?commands set boxwidth
5236 ?commands show boxwidth
5240 The `set boxwidth` command is used to set the default width of boxes in the
5241 `boxes`, `boxerrorbars`, `candlesticks` and `histograms` styles.
5244 set boxwidth {<width>} {absolute|relative}
5247 By default, adjacent boxes are extended in width until they touch each other.
5248 A different default width may be specified using the `set boxwidth` command.
5249 `Relative` widths are interpreted as being a fraction of this default width.
5251 An explicit value for the boxwidth is interpreted as being a number of units
5252 along the current x axis (`absolute`) unless the modifier `relative` is given.
5253 If the x axis is a log-scale (see `set log`) then the value of boxwidth is
5254 truly "absolute" only at x=1; this physical width is maintained everywhere
5255 along the axis (i.e. the boxes do not become narrower the value of x
5256 increases). If the range spanned by a log scale x axis is far from x=1,
5257 some experimentation may be required to find a useful value of boxwidth.
5259 The default is superseded by explicit width information taken from an extra
5260 data column in styles `boxes` or `boxerrorbars`. In a four-column data set,
5261 the fourth column will be interpreted as the box width unless the width is set
5262 to -2.0, in which case the width will be calculated automatically.
5263 See `style boxes` and `style boxerrorbars` for more details.
5265 To set the box width to automatic use the command
5268 or, for four-column data,
5271 The same effect can be achieved with the `using` keyword in `plot`:
5272 plot 'file' using 1:2:3:4:(-2)
5274 To set the box width to half of the automatic size use
5275 set boxwidth 0.5 relative
5277 To set the box width to an absolute value of 2 use
5278 set boxwidth 2 absolute
5280 ?commands set clabel
5281 ?commands unset clabel
5282 ?commands show clabel
5287 `gnuplot` will vary the linetype used for each contour level when clabel is
5288 set. When this option on (the default), a legend labels each linestyle with
5289 the z level it represents. It is not possible at present to separate the
5290 contour labels from the surface key.
5293 set clabel {'<format>'}
5297 The default for the format string is %8.3g, which gives three decimal places.
5298 This may produce poor label alignment if the key is altered from its default
5301 The first contour linetype, or only contour linetype when clabel is off, is
5302 the surface linetype +1; contour points are the same style as surface points.
5304 See also `set contour`.
5307 ?commands unset clip
5314 `gnuplot` can clip data points and lines that are near the boundaries of a
5318 set clip <clip-type>
5319 unset clip <clip-type>
5322 Three clip types for points and lines are supported by `gnuplot`: `points`,
5323 `one`, and `two`. One, two, or all three clip types may be active for a
5325 Note that clipping of color filled quadrangles drawn by `pm3d` maps and
5326 surfaces is not controlled by this command, but by `set pm3d clip1in` and
5329 The `points` clip type forces `gnuplot` to clip (actually, not plot at all)
5330 data points that fall within but too close to the boundaries. This is done
5331 so that large symbols used for points will not extend outside the boundary
5332 lines. Without clipping points near the boundaries, the plot may look bad.
5333 Adjusting the x and y ranges may give similar results.
5335 Setting the `one` clip type causes `gnuplot` to draw a line segment which has
5336 only one of its two endpoints within the graph. Only the in-range portion of
5337 the line is drawn. The alternative is to not draw any portion of the line
5340 Some lines may have both endpoints out of range, but pass through the graph.
5341 Setting the `two` clip-type allows the visible portion of these lines to be
5344 In no case is a line drawn outside the graph.
5346 The defaults are `noclip points`, `clip one`, and `noclip two`.
5348 To check the state of all forms of clipping, use
5351 For backward compatibility with older versions, the following forms are also
5356 `set clip` is synonymous with `set clip points`; `unset clip` turns off all
5357 three types of clipping.
5359 ?commands set cntrparam
5360 ?commands show cntrparam
5364 `set cntrparam` controls the generation of contours and their smoothness for
5365 a contour plot. `show contour` displays current settings of `cntrparam` as
5369 set cntrparam { { linear
5374 | levels { auto {<n>} | <n>
5375 | discrete <z1> {,<z2>{,<z3>...}}
5376 | incremental <start>, <incr> {,<end>}
5382 This command has two functions. First, it sets the values of z for which
5383 contour points are to be determined (by linear interpolation between data
5384 points or function isosamples.) Second, it controls the way contours are
5385 drawn between the points determined to be of equal z. <n> should be an
5386 integral constant expression and <z1>, <z2> ... any constant expressions.
5389 `linear`, `cubicspline`, `bspline`---Controls type of approximation or
5390 interpolation. If `linear`, then straight line segments connect points of
5391 equal z magnitude. If `cubicspline`, then piecewise-linear contours are
5392 interpolated between the same equal z points to form somewhat smoother
5393 contours, but which may undulate. If `bspline`, a guaranteed-smoother curve
5394 is drawn, which only approximates the position of the points of equal-z.
5396 `points`---Eventually all drawings are done with piecewise-linear strokes.
5397 This number controls the number of line segments used to approximate the
5398 `bspline` or `cubicspline` curve. Number of cubicspline or bspline
5399 segments (strokes) = `points` * number of linear segments.
5401 `order`---Order of the bspline approximation to be used. The bigger this
5402 order is, the smoother the resulting contour. (Of course, higher order
5403 bspline curves will move further away from the original piecewise linear
5404 data.) This option is relevant for `bspline` mode only. Allowed values are
5405 integers in the range from 2 (linear) to 10.
5407 `levels`--- Selection of contour levels, controlled by `auto` (default),
5408 `discrete`, `incremental`, and <n>, number of contour levels.
5410 For `auto`, <n> specifies a nominal number of levels; the actual number will
5411 be adjusted to give simple labels. If the surface is bounded by zmin and zmax,
5412 contours will be generated at integer multiples of dz between zmin and zmax,
5413 where dz is 1, 2, or 5 times some power of ten (like the step between two
5416 For `levels discrete`, contours will be generated at z = <z1>, <z2> ... as
5417 specified; the number of discrete levels sets the number of contour levels.
5418 In `discrete` mode, any `set cntrparam levels <n>` are ignored.
5420 For `incremental`, contours are generated at values of z beginning at <start>
5421 and increasing by <increment>, until the number of contours is reached. <end>
5422 is used to determine the number of contour levels, which will be changed by
5423 any subsequent `set cntrparam levels <n>`. If the z axis is logarithmic,
5424 <increment> will be interpreted as a factor, just like in `set ztics`.
5426 If the command `set cntrparam` is given without any arguments specified, the
5427 defaults are used: linear, 5 points, order 4, 5 auto levels.
5430 set cntrparam bspline
5431 set cntrparam points 7
5432 set cntrparam order 10
5434 To select levels automatically, 5 if the level increment criteria are met:
5435 set cntrparam levels auto 5
5437 To specify discrete levels at .1, .37, and .9:
5438 set cntrparam levels discrete .1,1/exp(1),.9
5440 To specify levels from 0 to 4 with increment 1:
5441 set cntrparam levels incremental 0,1,4
5443 To set the number of levels to 10 (changing an incremental end or possibly
5444 the number of auto levels):
5445 set cntrparam levels 10
5447 To set the start and increment while retaining the number of levels:
5448 set cntrparam levels incremental 100,50
5450 See also `set contour` for control of where the contours are drawn, and
5451 `set clabel` for control of the format of the contour labels and linetypes.
5454 ^ <a href="http://www.gnuplot.info/demo/contours.html">
5455 contours demo (contours.dem)
5458 ^ <a href="http://www.gnuplot.info/demo/discrete.html">
5459 contours with user defined levels demo (discrete.dem).
5462 ?commands set colorbox
5463 ?commands show colorbox
5464 ?commands unset colorbox
5470 The color scheme, i.e. the gradient of the smooth color with min_z and
5471 max_z values of `pm3d`'s `palette`, is drawn in a color box unless `unset
5476 { vertical | horizontal }
5481 { noborder | bdefault | border [line style] }
5486 Color box position can be `default` or `user`. If the latter is specified the
5487 values as given with the `origin` and `size` subcommands are used. The box
5488 can be drawn after (`front`) or before (`back`) the graph or the surface.
5490 The orientation of the color gradient can be switched by options `vertical`
5493 `origin x, y` and `size x, y` are used only in combination with the `user`
5494 option. The x and y values are interpreted as screen coordinates by default,
5495 and this is the only legal option for 3D plots. 2D plots, including splot with
5496 `set view map`, allow any coordinate system to be specified. Try for example:
5497 set colorbox horiz user origin .1,.02 size .8,.04
5498 which will draw a horizontal gradient somewhere at the bottom of the graph.
5500 `border` turns the border on (this is the default). `noborder` turns the border
5501 off. If an positive integer argument is given after `border`, it is used as a
5502 line style tag which is used for drawing the border, e.g.:
5503 set style line 2604 linetype -1 linewidth .4
5504 set colorbox border 2604
5505 will use line style `2604`, a thin line with the default border color (-1)
5506 for drawing the border. `bdefault` (which is the default) will use the default
5507 border line style for drawing the border of the color box.
5509 The axis of the color box is called `cb` and it is controlled by means of the
5510 usual axes commands, i.e. `set/unset/show` with `cbrange`, `[m]cbtics`,
5511 `format cb`, `grid [m]cb`, `cblabel`, and perhaps even `cbdata`, `[no]cbdtics`,
5514 `set colorbox` without any parameter switches the position to default.
5515 `unset colorbox` resets the default parameters for the colorbox and switches
5518 See also help for `set pm3d`, `set palette`, `x11 pm3d`, and `set style line`.
5521 ?commands set contour
5522 ?commands unset contour
5523 ?commands show contour
5529 `set contour` enables contour drawing for surfaces. This option is available
5530 for `splot` only. It requires grid data, see `grid_data` for more details.
5531 If contours are desired from non-grid data, `set dgrid3d` can be used to
5532 create an appropriate grid.
5535 set contour {base | surface | both}
5539 The three options specify where to draw the contours: `base` draws the
5540 contours on the grid base where the x/ytics are placed, `surface` draws the
5541 contours on the surfaces themselves, and `both` draws the contours on both
5542 the base and the surface. If no option is provided, the default is `base`.
5544 See also `set cntrparam` for the parameters that affect the drawing of
5545 contours, and `set clabel` for control of labelling of the contours.
5547 The surface can be switched off (see `set surface`), giving a contour-only
5548 graph. Though it is possible to use `set size` to enlarge the plot to fill
5549 the screen, more control over the output format can be obtained by writing
5550 the contour information to a file, and rereading it as a 2-d datafile plot:
5555 set table 'filename'
5558 # contour info now in filename
5562 In order to draw contours, the data should be organized as "grid data". In
5563 such a file all the points for a single y-isoline are listed, then all the
5564 points for the next y-isoline, and so on. A single blank line (a line
5565 containing no characters other than blank spaces and a carriage return and/or
5566 a line feed) separates one y-isoline from the next.
5567 See also `splot datafile`.
5570 ^ <a href="http://www.gnuplot.info/demo/contours.html">
5571 contours demo (contours.dem)
5574 ^ <a href="http://www.gnuplot.info/demo/discrete.html">
5575 contours with user defined levels demo (discrete.dem).
5578 ?DUMMYLABEL set style data
5579 This form of the command is deprecated. Please see `set style data`.
5583 The `set datafile` command options control interpretation of fields read from
5584 input data files by the `plot`, `splot`, and `fit` commands. Four such
5585 options are currently implemented.
5586 4 set datafile fortran
5587 ?set datafile fortran
5589 The `set datafile fortran` command enables a special check for values in the
5590 input file expressed as Fortran D or Q constants. This extra check slows down
5591 the input process, and should only be selected if you do in fact have datafiles
5592 containing Fortran D or Q constants. The option can be disabled again using
5593 `unset datafile fortran`.
5594 4 set datafile missing
5595 ?set datafile missing
5598 The `set datafile missing` command allows you to tell `gnuplot` what character
5599 string is used in a data file to denote missing data. Exactly how this missing
5600 value will be treated depends on the `using` specifier of the `plot` or `splot`
5604 set datafile missing {"<string>"}
5605 show datafile missing
5609 # Ignore entries containing IEEE NaN ("Not a Number") code
5610 set datafile missing "NaN"
5613 set datafile missing "?"
5614 set style data lines
5629 plot '-' using 1:($2)
5637 The first `plot` will recognize only the first datum in the "3 ?" line. It
5638 will use the single-datum-on-a-line convention that the line number is "x"
5639 and the datum is "y", so the point will be plotted (in this case erroneously)
5642 The second `plot` will correctly ignore the middle line. The plotted line
5643 will connect the points at (2,20) and (4,40).
5645 The third `plot` will also correctly ignore the middle line, but the plotted
5646 line will not connect the points at (2,20) and (4,40).
5648 There is no default character for `missing`, but in many cases any
5649 non-parsible string of characters found where a numerical value is expected
5650 will be treated as missing data.
5652 4 set datafile separator
5653 ?set datafile separator
5654 ?show datafile separator
5657 The command `set datafile separator "<char>"` tells `gnuplot` that data fields
5658 in subsequent input files are separated by <char> rather than by whitespace.
5659 The most common use is to read in csv (comma-separated value) files written
5660 by spreadsheet or database programs. By default data fields are separated by
5664 set datafile separator {"<char>" | whitespace}
5667 # Input file contains tab-separated fields
5668 set datafile separator "\t"
5670 # Input file contains comma-separated values fields
5671 set datafile separator ","
5672 4 set datafile commentschars
5673 ?set datafile commentschars
5675 The `set datafile commentschars` command allows you to tell `gnuplot` what
5676 characters are used in a data file to denote comments. Gnuplot will ignore
5677 rest of the line behind the specified characters if either of them is the
5678 first non-blank character on the line.
5681 set datafile commentschars {"<string>"}
5682 show datafile commentschars
5685 Default value of the string is "#!" on VMS and "#" otherwise.
5687 Then, the following line in a data file is completely ignored
5691 produces rather unexpected plot unless
5692 set datafile missing '#'
5693 is specified as well.
5696 set datafile commentschars "#!%"
5697 4 set datafile binary
5698 ?set datafile binary
5699 The `set datafile binary` command is used to set the defaults when reading
5700 binary data files. The syntax matches precisely that used for commands
5701 `plot` and `splot`. See `binary` for details about <binary list>.
5704 set datafile binary <binary list>
5705 show datafile binary
5710 set datafile binary filetype=auto
5711 set datafile binary array=512x512 format="%uchar"
5713 ?commands set decimalsign
5714 ?commands show decimalsign
5715 ?commands unset decimalsign
5721 The `set decimalsign` command selects a decimal sign for numbers printed
5722 into tic labels or `set label` strings.
5725 set decimalsign {<value> | locale {"<locale>"}}
5729 The argument <value> is a string to be used in place of the usual
5730 decimal point. Typical choices include the period, '.', and the comma,
5731 ',', but others may be useful, too. If you omit the <value> argument,
5732 the decimal separator is not modified from the usual default, which is
5733 a period. Unsetting decimalsign has the same effect as omitting <value>.
5737 Correct typesetting in most European countries requires:
5740 Please note: If you set an explicit string, this affects only numbers that
5741 are printed using gnuplot's gprintf() formatting routine, include axis tics.
5742 It does not affect the format expected for input data, and it does not affect
5743 numbers printed with the sprintf() formatting routine. To change the behavior
5744 of both input and output formatting, instead use the form
5746 set decimalsign locale
5748 This instructs the program to use both input and output formats in accordance
5749 with the current setting of the LC_ALL, LC_NUMERIC, or LANG environmental
5752 set decimalsign locale "foo"
5754 This instructs the program to format all input and output in accordance with
5755 locale "foo", which must be installed. If locale "foo" is not found then an
5756 error message is printed and the decimal sign setting is unchanged.
5757 On linux systems you can get a list of the locales installed on your machine by
5758 typing "locale -a". A typical linux locale string is of the form "sl_SI.UTF-8".
5759 A typical Windows locale string is of the form "Slovenian_Slovenia.1250" or
5760 "slovenian". Please note that interpretation of the locale settings is done by
5761 the C library at runtime. Older C libraries may offer only partial support for
5762 locale settings such as the thousands grouping separator character.
5764 set decimalsign locale; set decimalsign "."
5766 This sets all input and output to use whatever decimal sign is correct for
5767 the current locale, but over-rides this with an explicit '.' in numbers
5768 formatted using gnuplot's internal gprintf() function.
5770 ?commands set dgrid3d
5771 ?commands unset dgrid3d
5772 ?commands show dgrid3d
5778 The `set dgrid3d` command enables, and can set parameters for, non-grid to
5779 grid data mapping. See `splot grid_data` for more details about the grid data
5783 set dgrid3d {<row_size>} {,{<col_size>} {,<norm>}}
5787 By default `dgrid3d` is disabled. When enabled, 3-d data read from a file
5788 are always treated as a scattered data set. A grid with dimensions derived
5789 from a bounding box of the scattered data and size as specified by the
5790 row/col_size parameters is created for plotting and contouring. The grid
5791 is equally spaced in x (rows) and in y (columns); the z values are computed
5792 as weighted averages of the scattered points' z values.
5794 The third parameter, norm, controls the weighting: Each data point is
5795 weighted inversely by its distance from the grid point raised to the norm
5796 power. (Actually, the weights are given by the inverse of dx^norm + dy^norm,
5797 where dx and dy are the components of the separation of the grid point from
5798 each data point. For some norms that are powers of two, specifically 4, 8,
5799 and 16, the computation is optimized by using the Euclidean distance in the
5800 weight calculation, (dx^2+dy^2)^norm/2. However, any non-negative integer
5803 The closer the data point is to a grid point, the more effect it has on
5804 that grid point and the larger the value of norm the less effect more
5805 distant data points have on that grid point.
5807 The `dgrid3d` option is a simple low pass filter that converts scattered
5808 data to a grid data set. More sophisticated approaches to this problem
5809 exist and should be used to preprocess the data outside `gnuplot` if this
5810 simple solution is found inadequate.
5812 (The z values are found by weighting all data points, not by interpolating
5813 between nearby data points; also edge effects may produce unexpected and/or
5814 undesired results. In some cases, small norm values produce a grid point
5815 reflecting the average of distant data points rather than a local average,
5816 while large values of norm may produce "steps" with several grid points
5817 having the same value as the closest data point, rather than making a smooth
5818 transition between adjacent data points. Some areas of a grid may be filled
5819 by extrapolation, to an arbitrary boundary condition. The variables are
5820 not normalized; consequently the units used for x and y will affect the
5821 relative weights of points in the x and y directions.)
5824 set dgrid3d 10,10,1 # defaults
5827 The first specifies that a grid of size 10 by 10 is to be constructed using
5828 a norm value of 1 in the weight computation. The second only modifies the
5829 norm, changing it to 4.
5831 ^ <a href="http://www.gnuplot.info/demo/scatter.html">
5832 scatter.dem: dgrid3d demo.
5837 ?commands show dummy
5841 The `set dummy` command changes the default dummy variable names.
5844 set dummy {<dummy-var>} {,<dummy-var>}
5847 By default, `gnuplot` assumes that the independent, or "dummy", variable for
5848 the `plot` command is "t" if in parametric or polar mode, or "x" otherwise.
5849 Similarly the independent variables for the `splot` command are "u" and "v"
5850 in parametric mode (`splot` cannot be used in polar mode), or "x" and "y"
5853 It may be more convenient to call a dummy variable by a more physically
5854 meaningful or conventional name. For example, when plotting time functions:
5859 At least one dummy variable must be set on the command; `set dummy` by itself
5860 will generate an error message.
5866 The second example sets the second variable to s.
5868 ?commands set encoding
5869 ?commands show encoding
5874 The `set encoding` command selects a character encoding.
5876 set encoding {<value>}
5880 default - tells a terminal to use its default encoding
5881 iso_8859_1 - the most common Western European font used by many
5882 Unix workstations and by MS-Windows. This encoding is
5883 known in the PostScript world as 'ISO-Latin1'.
5884 iso_8859_2 - used in Central and Eastern Europe
5885 iso_8859_15 - a variant of iso_8859_1 that includes the Euro symbol
5886 koi8r - popular Unix cyrillic encoding
5887 koi8u - ukrainian Unix cyrillic encoding
5888 cp437 - codepage for MS-DOS
5889 cp850 - codepage for OS/2, Western Europe
5890 cp852 - codepage for OS/2, Central and Eastern Europe
5891 cp1250 - codepage for MS Windows, Central and Eastern Europe
5893 Generally you must set the encoding before setting the terminal type.
5894 Note that encoding is not supported by all terminal drivers and that
5895 the device must be able to produce the desired non-standard characters.
5896 The PostScript, X11 and wxt terminals support all encodings. OS/2 Presentation
5897 Manager switches automatically to codepage 912 for `iso_8859_2`.
5903 The `fit` setting defines where the `fit` command writes its output.
5904 If this option was built into your version of gnuplot, it also controls
5905 whether parameter errors from the fit will be written into variables.
5908 set fit {logfile {"<filename>"}} {{no}errorvariables}
5912 The <filename> argument must be enclosed in single or double quotes.
5914 If no filename is given or `unset fit` is used the log file is
5915 reset to its default value "fit.log" or the value of the environmental
5918 Users of DOS-like platforms should note that the \ character has
5919 special significance in double-quoted strings, so single-quotes
5920 should be used for filenames in different directories, or you have
5921 to write \\ for each \. Or you can just use forward slashes,
5922 even though this is DOS.
5924 If the given logfile name ends with a / or \, it is interpreted to be
5925 a directory name, and the actual filename will be "fit.log" in that
5928 If the `errorvariables` option is turned on, the error of each fitted
5929 parameter computed by `fit` will be copied to a user-defined variable
5930 whose name is formed by appending "_err" to the name of the parameter
5931 itself. This is useful mainly to put the parameter and its error onto
5932 a plot of the data and the fitted function, for reference, as in:
5934 set fit errorvariables
5935 fit f(x) 'datafile' using 1:2 via a, b
5936 print "error of a is:", a_err
5937 set label 'a=%6.2f', a, '+/- %6.2f', a_err
5938 plot 'datafile' using 1:2, f(x)
5940 ?commands set fontpath
5941 ?commands show fontpath
5945 The `fontpath` setting defines additional locations for font files
5946 searched when including font files. Currently only the postscript terminal
5947 supports `fontpath`. If a file cannot be found in the current directory,
5948 the directories in `fontpath` are tried. Further documentation concerning
5949 the supported file formats is included in the `terminal postscript` section
5950 of the documentation.
5953 set fontpath {"pathlist1" {"pathlist2"...}}
5956 Path names may be entered as single directory names, or as a list of
5957 path names separated by a platform-specific path separator, eg. colon
5958 (':') on Unix, semicolon (';') on DOS/Windows/OS/2/Amiga platforms.
5959 The `show fontpath`, `save` and `save set` commands replace the
5960 platform-specific separator with a space character (' ') for maximum
5961 portability. If a directory name ends with an exclamation mark ('!') also
5962 the subdirectories of this directory are searched for font files.
5964 If the environmental variable GNUPLOT_FONTPATH is set, its contents are
5965 appended to `fontpath`. If it is not set, a system dependent default value
5966 is used. It is set by testing several directories for existence when using
5967 the fontpath the first time. Thus, the first call of `set fontpath`,
5968 `show fontpath`, `save fontpath`, `plot`, or `splot` with embedded font
5969 files takes a little more time. If you want to save this time you may
5970 set the environmental variable GNUPLOT_FONTPATH since probing is switched
5971 off, then. You can find out which is the default fontpath by using
5974 However, `show fontpath` prints the contents of user defined fontpath and
5975 system fontpath separately. Also, the `save` and `save set` commands save
5976 only the user specified parts of `fontpath`, for portability reasons.
5978 Many other terminal drivers access TrueType fonts via the gd library.
5979 For these drivers the font search path is controlled by the environmental
5980 variable GDFONTPATH.
5982 ?commands set format
5983 ?commands show format
5988 The format of the tic-mark labels can be set with the `set format` command
5989 or with the `set tics format` or individual `set {axis}tics format` commands.
5992 set format {<axes>} {"<format-string>"}
5993 set format {<axes>} {'<format-string>'}
5996 where <axes> is either `x`, `y`, `xy`, `x2`, `y2`, `z`, `cb` or
5997 nothing (which refers to all axes at once). The length of the string
5998 representing a tic mark (after formatting with 'printf') is restricted
5999 to 100 characters. If the format string is omitted, the format will
6000 be returned to the default "% g". For LaTeX users, the format "$%g$"
6001 is often desirable. If the empty string "" is used, no label will be
6002 plotted with each tic, though the tic mark will still be plotted. To
6003 eliminate all tic marks, use `unset xtics` or `unset ytics`.
6005 Newline (\n) is accepted in the format string. Use double-quotes rather than
6006 single-quotes to enable such interpretation. See also `syntax`.
6008 The default format for both axes is "% g", but other formats such as "%.2f" or
6009 "%3.0em" are often desirable. Anything accepted by 'printf' when given a
6010 double precision number, and accepted by the terminal, will work. Some other
6011 options have been added. If the format string looks like a floating point
6012 format, then `gnuplot` tries to construct a reasonable format.
6014 Characters not preceded by "%" are printed verbatim. Thus you can include
6015 spaces and labels in your format string, such as "%g m", which will put " m"
6016 after each number. If you want "%" itself, double it: "%g %%".
6018 See also `set xtics` for more information about tic labels, and
6019 `set decimalsign` for how to use non-default decimal separators in numbers
6022 ^ <a href="http://www.gnuplot.info/demo/electron.html">
6023 electron demo (electron.dem).
6027 The string function gprintf("format",x) uses gnuplot's own format specifiers,
6028 as do the gnuplot commands `set format`, `set timestamp`, and others. These
6029 format specifiers are not the same as those used by the standard C-language
6030 routine sprintf(). Gnuplot also provides an sprintf("format",x,...) routine
6031 if you prefer. For a list of gnuplot's format options, see `format specifiers`.
6033 ?commands set format specifiers
6034 ?set format specifiers
6037 The acceptable formats (if not in time/date mode) are:
6039 @start table - first is interactive cleartext form
6041 %f floating point notation
6042 %e or %E exponential notation; an "e" or "E" before the power
6043 %g or %G the shorter of %e (or %E) and %f
6046 %t mantissa to base 10
6047 %l mantissa to base of current logscale
6048 %s mantissa to base of current logscale; scientific power
6050 %L power to base of current logscale
6052 %c character replacement for scientific power
6054 #\begin{tabular}{|cl|} \hline
6055 #\multicolumn{2}{|c|}{Tic-mark label numerical format specifiers}\\
6057 #Format & Explanation \\ \hline
6058 #\verb@%f@ & floating point notation \\
6059 #\verb@%e@ or \verb@%E@ & exponential notation; an "e" or "E" before the power \\
6060 #\verb@%g@ or \verb@%G@ & the shorter of \verb@%e@ (or \verb@%E@) and \verb@%f@ \\
6061 #\verb@%x@ or \verb@%X@ & hex \\
6062 #\verb@%o@ or \verb@%O@ & octal \\
6063 #\verb@%t@ & mantissa to base 10 \\
6064 #\verb@%l@ & mantissa to base of current logscale \\
6065 #\verb@%s@ & mantissa to base of current logscale; scientific power \\
6066 #\verb@%T@ & power to base 10 \\
6067 #\verb@%L@ & power to base of current logscale \\
6068 #\verb@%S@ & scientific power \\
6069 #\verb@%c@ & character replacement for scientific power \\
6070 #\verb@%P@ & multiple of pi \\
6074 %%f@floating point notation
6075 %%e or %E@exponential notation; an "e" or "E" before the power
6076 %%g or %G@the shorter of %e (or %E) and %f
6079 %%t@mantissa to base 10
6080 %%l@mantissa to base of current logscale
6081 %%s@mantissa to base of current logscale; scientific power
6082 %%T@power to base 10
6083 %%L@power to base of current logscale
6084 %%S@scientific power
6085 %%c@character replacement for scientific power
6090 A 'scientific' power is one such that the exponent is a multiple of three.
6091 Character replacement of scientific powers (`"%c"`) has been implemented
6092 for powers in the range -18 to +18. For numbers outside of this range the
6093 format reverts to exponential.
6095 Other acceptable modifiers (which come after the "%" but before the format
6096 specifier) are "-", which left-justifies the number; "+", which forces all
6097 numbers to be explicitly signed; " " (a space), which makes positive numbers
6098 have a space in front of them where negative numbers have "-";
6099 "#", which places a decimal point after
6100 floats that have only zeroes following the decimal point; a positive integer,
6101 which defines the field width; "0" (the digit, not the letter) immediately
6102 preceding the field width, which indicates that leading zeroes are to be used
6103 instead of leading blanks; and a decimal point followed by a non-negative
6104 integer, which defines the precision (the minimum number of digits of an
6105 integer, or the number of digits following the decimal point of a float).
6107 Some systems may not support all of these modifiers but may also support
6108 others; in case of doubt, check the appropriate documentation and
6112 set format y "%t"; set ytics (5,10) # "5.0" and "1.0"
6113 set format y "%s"; set ytics (500,1000) # "500" and "1.0"
6114 set format y "%+-12.3f"; set ytics(12345) # "+12345.000 "
6115 set format y "%.2t*10^%+03T"; set ytic(12345)# "1.23*10^+04"
6116 set format y "%s*10^{%S}"; set ytic(12345) # "12.345*10^{3}"
6117 set format y "%s %cg"; set ytic(12345) # "12.345 kg"
6118 set format y "%.0P pi"; set ytic(6.283185) # "2 pi"
6119 set format y "%.0f%%"; set ytic(50) # "50%"
6121 set log y 2; set format y '%l'; set ytics (1,2,3)
6122 #displays "1.0", "1.0" and "1.5" (since 3 is 1.5 * 2^1)
6124 There are some problem cases that arise when numbers like 9.999 are printed
6125 with a format that requires both rounding and a power.
6127 If the data type for the axis is time/date, the format string must contain
6128 valid codes for the 'strftime' function (outside of `gnuplot`, type "man
6129 strftime"). See `set timefmt` for a list of the allowed input format codes.
6130 4 time/date specifiers
6131 ?commands set format date_specifiers
6132 ?commands set format time_specifiers
6133 ?set format date_specifiers
6134 ?set format time_specifiers
6135 ?set date_specifiers
6136 ?set time_specifiers
6139 In time/date mode, the acceptable formats are:
6141 @start table - first is interactive cleartext form
6143 %a abbreviated name of day of the week
6144 %A full name of day of the week
6145 %b or %h abbreviated name of the month
6146 %B full name of the month
6147 %d day of the month, 01--31
6148 %D shorthand for "%m/%d/%y" (only output)
6149 %F shorthand for "%Y-%m-%d" (only output)
6150 %k hour, 0--23 (one or two digits)
6151 %H hour, 00--23 (always two digits)
6152 %l hour, 1--12 (one or two digits)
6153 %I hour, 01--12 (always two digits)
6154 %j day of the year, 1--366
6158 %r shorthand for "%I:%M:%S %p" (only output)
6159 %R shorthand for "%H:%M" (only output)
6161 %T shorthand for "%H:%M:%S" (only output)
6162 %U week of the year (week starts on Sunday)
6163 %w day of the week, 0--6 (Sunday = 0)
6164 %W week of the year (week starts on Monday)
6167 #\begin{tabular}{|cl|} \hline
6168 #\multicolumn{2}{|c|}{Tic-mark label Date/Time Format Specifiers}\\
6170 #Format & Explanation \\ \hline
6171 #\verb@%a@ & abbreviated name of day of the week \\
6172 #\verb@%A@ & full name of day of the week \\
6173 #\verb@%b@ or \verb@%h@ & abbreviated name of the month \\
6174 #\verb@%B@ & full name of the month \\
6175 #\verb@%d@ & day of the month, 1--31 \\
6176 #\verb@%D@ & shorthand for \verb@"%m/%d/%y"@ (only output) \\
6177 #\verb@%F@ & shorthand for \verb@"%Y-%m-%d"@ (only output) \\
6178 #\verb@%k@ & hour, 0--23 (one or two digits)\\
6179 #\verb@%H@ & hour, 00--23 (always two digits)\\
6180 #\verb@%l@ & hour, 1--12 (one or two digits)\\
6181 #\verb@%I@ & hour, 01--12 (always two digits)\\
6182 #\verb@%j@ & day of the year, 1--366 \\
6183 #\verb@%m@ & month, 1--12 \\
6184 #\verb@%M@ & minute, 0--60 \\
6185 #\verb@%p@ & "am" or "pm" \\
6186 #\verb@%r@ & shorthand for \verb@"%I:%M:%S %p"@ (only output)\\
6187 #\verb@%R@ & shorthand for \verb@%H:%M"@ (only output)\\
6188 #\verb@%S@ & second, 0--60 \\
6189 #\verb@%T@ & shorthand for \verb@"%H:%M:%S"@ (only output)\\
6190 #\verb@%U@ & week of the year (week starts on Sunday) \\
6191 #\verb@%w@ & day of the week, 0--6 (Sunday = 0) \\
6192 #\verb@%W@ & week of the year (week starts on Monday) \\
6193 #\verb@%y@ & year, 0-99 \\
6194 #\verb@%Y@ & year, 4-digit \\
6198 %%a@abbreviated name of day of the week
6199 %%A@full name of day of the week
6200 %%b or %h@abbreviated name of the month
6201 %%B@full name of the month
6202 %%d@day of the month, 1--31
6203 %%D@shorthand for "%m/%d/%y" (only output)
6204 %%F@shorthand for "%Y-%m-%d" (only output)
6205 %%k@hour, 0--23 (one or two digits)
6206 %%H@hour, 00--23 (always two digits)
6207 %%l@hour, 1--12 (one or two digits)
6208 %%I@hour, 01--12 (always two digits)
6209 %%j@day of the year, 1--366
6213 %%r@shorthand for "%I:%M:%S %p" (only output)
6214 %%R@shorthand for %H:%M" (only output)
6216 %%T@shorthand for "%H:%M:%S" (only output)
6217 %%U@week of the year (week starts on Sunday)
6218 %%w@day of the week, 0--6 (Sunday = 0)
6219 %%W@week of the year (week starts on Monday)
6225 Except for the non-numerical formats, these may be preceded by a "0" ("zero",
6226 not "oh") to pad the field length with leading zeroes, and a positive digit,
6227 to define the minimum field width (which will be overridden if the specified
6228 width is not large enough to contain the number). There is a 24-character
6229 limit to the length of the printed text; longer strings will be truncated.
6233 Suppose the text is "76/12/25 23:11:11". Then
6234 set format x # defaults to "12/25/76" \n "23:11"
6235 set format x "%A, %d %b %Y" # "Saturday, 25 Dec 1976"
6236 set format x "%r %D" # "11:11:11 pm 12/25/76"
6238 Suppose the text is "98/07/06 05:04:03". Then
6239 set format x "%1y/%2m/%3d %01H:%02M:%03S" # "98/ 7/ 6 5:04:003"
6241 This form of the command is deprecated. Please see `set style function`.
6243 ?commands show functions
6245 The `show functions` command lists all user-defined functions and their
6251 For information about the definition and usage of functions in `gnuplot`,
6252 please see `expressions`.
6254 ^ <a href="http://www.gnuplot.info/demo/spline.html">
6255 splines as user defined functions (spline.dem)
6258 ^ <a href="http://www.gnuplot.info/demo/airfoil.html">
6259 use of functions and complex variables for airfoils (airfoil.dem).
6263 ?commands unset grid
6270 The `set grid` command allows grid lines to be drawn on the plot.
6273 set grid {{no}{m}xtics} {{no}{m}ytics} {{no}{m}ztics}
6274 {{no}{m}x2tics} {{no}{m}y2tics}
6277 {layerdefault | front | back}
6278 { {linestyle <major_linestyle>}
6279 | {linetype | lt <major_linetype>}
6280 {linewidth | lw <major_linewidth>}
6281 { , {linestyle | ls <minor_linestyle>}
6282 | {linetype | lt <minor_linetype>}
6283 {linewidth | lw <minor_linewidth>} } }
6287 The grid can be enabled and disabled for the major and/or minor tic
6288 marks on any axis, and the linetype and linewidth can be specified
6289 for major and minor grid lines, also via a predefined linestyle, as
6290 far as the active terminal driver supports this.
6292 Additionally, a polar grid can be selected for 2-d plots---circles are drawn
6293 to intersect the selected tics, and radial lines are drawn at definable
6294 intervals. (The interval is given in degrees or radians, depending on the
6295 `set angles` setting.) Note that a polar grid is no longer automatically
6296 generated in polar mode.
6298 The pertinent tics must be enabled before `set grid` can draw them; `gnuplot`
6299 will quietly ignore instructions to draw grid lines at non-existent tics, but
6300 they will appear if the tics are subsequently enabled.
6302 If no linetype is specified for the minor gridlines, the same linetype as the
6303 major gridlines is used. The default polar angle is 30 degrees.
6305 If `front` is given, the grid is drawn on top of the graphed data. If
6306 `back` is given, the grid is drawn underneath the graphed data. Using
6307 `front` will prevent the grid from being obscured by dense data. The
6308 default setup, `layerdefault`, is equivalent to `back` for 2d plots.
6309 In 3D plots the default is to split up the grid and the graph box into
6310 two layers: one behind, the other in front of the plotted data and
6311 functions. Since `hidden3d` mode does its own sorting, it ignores
6312 all grid drawing order options and passes the grid lines through the
6313 hidden line removal machinery instead. These options actually affect
6314 not only the grid, but also the lines output by `set border` and the
6315 various ticmarks (see `set xtics`).
6317 Z grid lines are drawn on the bottom of the plot. This looks better if a
6318 partial box is drawn around the plot---see `set border`.
6320 ?commands set hidden3d
6321 ?commands unset hidden3d
6322 ?commands show hidden3d
6328 The `set hidden3d` command enables hidden line removal for surface plotting
6329 (see `splot`). Some optional features of the underlying algorithm can also
6330 be controlled using this command.
6333 set hidden3d {defaults} |
6334 { {{offset <offset>} | {nooffset}}
6335 {trianglepattern <bitpattern>}
6336 {{undefined <level>} | {noundefined}}
6342 In contrast to the usual display in gnuplot, hidden line removal actually
6343 treats the given function or data grids as real surfaces that can't be seen
6344 through, so parts behind the surface will be hidden by it. For this to be
6345 possible, the surface needs to have 'grid structure' (see `splot datafile`
6346 about this), and it has to be drawn `with lines` or `with linespoints`.
6348 When `hidden3d` is set, both the hidden portion of the surface and possibly
6349 its contours drawn on the base (see `set contour`) as well as the grid will
6350 be hidden. Each surface has its hidden parts removed with respect to itself
6351 and to other surfaces, if more than one surface is plotted. Contours drawn
6352 on the surface (`set contour surface`) don't work.
6354 Labels and arrows are always visible and are unaffected. The key box is
6355 never hidden by the surface. As of gnuplot version 4.2, `set hidden3d` also
6356 affects 3D plotting styles `with points`, `with labels`, and `with vectors`,
6357 even if no surface is present in the graph. Individual plots within the
6358 graph may be explicitly excluded from this processing by appending the extra
6359 option `nohidden3d` to the `with` specifier.
6361 Hidden3d does not affect solid surfaces drawn using the pm3d mode. To
6362 achieve a similar effect for pm3d surfaces, use instead set `pm3d depthorder`.
6364 Functions are evaluated at isoline intersections. The algorithm interpolates
6365 linearly between function points or data points when determining the visible
6366 line segments. This means that the appearance of a function may be different
6367 when plotted with `hidden3d` than when plotted with `nohidden3d` because in
6368 the latter case functions are evaluated at each sample. Please see
6369 `set samples` and `set isosamples` for discussion of the difference.
6371 The algorithm used to remove the hidden parts of the surfaces has some
6372 additional features controllable by this command. Specifying `defaults` will
6373 set them all to their default settings, as detailed below. If `defaults` is
6374 not given, only explicitly specified options will be influenced: all others
6375 will keep their previous values, so you can turn on/off hidden line removal
6376 via `set {no}hidden3d`, without modifying the set of options you chose.
6378 The first option, `offset`, influences the linestyle used for lines on the
6379 'back' side. Normally, they are drawn in a linestyle one index number higher
6380 than the one used for the front, to make the two sides of the surface
6381 distinguishable. You can specify a different line style offset to add
6382 instead of the default 1, by `offset <offset>`. Option `nooffset` stands for
6383 `offset 0`, making the two sides of the surface use the same linestyle.
6385 Next comes the option `trianglepattern <bitpattern>`. <bitpattern> must be
6386 a number between 0 and 7, interpreted as a bit pattern. Each bit determines
6387 the visibility of one edge of the triangles each surface is split up into.
6388 Bit 0 is for the 'horizontal' edges of the grid, Bit 1 for the 'vertical'
6389 ones, and Bit 2 for the diagonals that split each cell of the original grid
6390 into two triangles. The default pattern is 3, making all horizontal and
6391 vertical lines visible, but not the diagonals. You may want to choose 7 to
6392 see those diagonals as well.
6394 The `undefined <level>` option lets you decide what the algorithm is to do
6395 with data points that are undefined (missing data, or undefined function
6396 values), or exceed the given x-, y- or z-ranges. Such points can either be
6397 plotted nevertheless, or taken out of the input data set. All surface
6398 elements touching a point that is taken out will be taken out as well, thus
6399 creating a hole in the surface. If <level> = 3, equivalent to option
6400 `noundefined`, no points will be thrown away at all. This may produce all
6401 kinds of problems elsewhere, so you should avoid this. <level> = 2 will
6402 throw away undefined points, but keep the out-of-range ones. <level> = 1,
6403 the default, will get rid of out-of-range points as well.
6405 By specifying `noaltdiagonal`, you can override the default handling of a
6406 special case can occur if `undefined` is active (i.e. <level> is not 3).
6407 Each cell of the grid-structured input surface will be divided in two
6408 triangles along one of its diagonals. Normally, all these diagonals have
6409 the same orientation relative to the grid. If exactly one of the four cell
6410 corners is excluded by the `undefined` handler, and this is on the usual
6411 diagonal, both triangles will be excluded. However if the default setting
6412 of `altdiagonal` is active, the other diagonal will be chosen for this cell
6413 instead, minimizing the size of the hole in the surface.
6415 The `bentover` option controls what happens to another special case, this
6416 time in conjunction with the `trianglepattern`. For rather crumply surfaces,
6417 it can happen that the two triangles a surface cell is divided into are seen
6418 from opposite sides (i.e. the original quadrangle is 'bent over'), as
6419 illustrated in the following ASCII art:
6422 original quadrangle: A--B displayed quadrangle: |\ |
6423 ("set view 0,0") | /| ("set view 75,75" perhaps) | \ |
6428 If the diagonal edges of the surface cells aren't generally made visible by
6429 bit 2 of the <bitpattern> there, the edge CB above wouldn't be drawn at all,
6430 normally, making the resulting display hard to understand. Therefore, the
6431 default option of `bentover` will turn it visible in this case. If you don't
6432 want that, you may choose `nobentover` instead.
6434 ^ <a href="http://www.gnuplot.info/demo/hidden.html">
6435 hidden line removal demo (hidden.dem)
6438 ^ <a href="http://www.gnuplot.info/demo/singulr.html">
6439 complex hidden line demo (singulr.dem).
6442 ?commands set historysize
6447 Note: the command `set historysize` is only available when
6448 gnuplot has been configured with the GNU readline.
6451 set historysize <int>
6454 When leaving gnuplot, the value of historysize is used for
6455 truncating the history to at most that much lines. The default
6457 `unset historysize` will disable history truncation and thus
6458 allow an infinite number of lines to be written to the history
6461 ?commands set isosamples
6462 ?commands show isosamples
6466 The isoline density (grid) for plotting functions as surfaces may be changed
6467 by the `set isosamples` command.
6470 set isosamples <iso_1> {,<iso_2>}
6473 Each function surface plot will have <iso_1> iso-u lines and <iso_2> iso-v
6474 lines. If you only specify <iso_1>, <iso_2> will be set to the same value
6475 as <iso_1>. By default, sampling is set to 10 isolines per u or v axis.
6476 A higher sampling rate will produce more accurate plots, but will take longer.
6477 These parameters have no effect on data file plotting.
6479 An isoline is a curve parameterized by one of the surface parameters while
6480 the other surface parameter is fixed. Isolines provide a simple means to
6481 display a surface. By fixing the u parameter of surface s(u,v), the iso-u
6482 lines of the form c(v) = s(u0,v) are produced, and by fixing the v parameter,
6483 the iso-v lines of the form c(u) = s(u,v0) are produced.
6485 When a function surface plot is being done without the removal of hidden
6486 lines, `set samples` controls the number of points sampled along each
6487 isoline; see `set samples` and `set hidden3d`. The contour algorithm
6488 assumes that a function sample occurs at each isoline intersection, so
6489 change in `samples` as well as `isosamples` may be desired when changing
6490 the resolution of a function surface/contour.
6501 The `set key` command enables a key (or legend) describing plots on a plot.
6503 The contents of the key, i.e., the names given to each plotted data set and
6504 function and samples of the lines and/or symbols used to represent them, are
6505 determined by the `title` and `with` options of the {`s`}`plot` command.
6506 Please see `plot title` and `plot with` for more information.
6509 set key {on|off} {default}
6510 {{inside | outside} | {lmargin | rmargin | tmargin | bmargin}
6512 {left | right | center} {top | bottom | center}
6513 {vertical | horizontal} {Left | Right}
6514 {{no}reverse} {{no}invert}
6515 {samplen <sample_length>} {spacing <vertical_spacing>}
6516 {width <width_increment>}
6517 {height <height_increment>}
6518 {{no}autotitle {columnheader}}
6519 {title "<text>"} {{no}enhanced}
6520 {{no}box { {linestyle | ls <line_style>}
6521 | {linetype | lt <line_type>}
6522 {linewidth | lw <line_width>}}}
6526 Plots may be drawn with no visible key by requesting `set key off` or
6529 Elements within the key are stacked according to `vertical` or `horizontal`.
6530 In the case of `vertical`, the key occupies as few columns as possible. That
6531 is, elements are aligned in a column until running out of vertical space at
6532 which point a new column is started. In the case of `horizontal`, the key
6533 occupies as few rows as possible.
6535 By default the key is placed in the upper right inside corner of the graph.
6536 The keywords `left`, `right`, `top`, `bottom`, `center`, `inside`, `outside`,
6537 `lmargin`, `rmargin`, `tmargin`, `bmargin` (, `above`, `over`, `below` and
6538 `under`) may be used to automatically place the key in other positions of the
6539 graph. Also an `at <position>` may be given to indicate precisely where the
6540 plot should be placed. In this case, the keywords `left`, `right`, `top`,
6541 `bottom` and `center` serve an analogous purpose for alignment.
6543 To understand positioning, the best concept is to think of a region, i.e.,
6544 inside/outside, or one of the margins. Along with the region, keywords
6545 `left/center/right` (l/c/r) and `top/center/bottom` (t/c/b) control where
6546 within the particular region the key should be placed.
6548 When in `inside` mode, the keywords `left` (l), `right` (r), `top` (t),
6549 `bottom` (b), and `center` (c) push the key out toward the plot boundary as
6559 When in `outside` mode, automatic placement is similar to the above
6560 illustration, but with respect to the view, rather than the graph boundary.
6561 That is, a border is moved inward to make room for the key outside of
6562 the plotting area, although this may interfere with other labels and may
6563 cause an error on some devices. The particular plot border that is moved
6564 depends upon the position described above and the stacking direction. For
6565 options centered in one of the dimensions, there is no ambiguity about which
6566 border to move. For the corners, when the stack direction is `vertical`, the
6567 left or right border is moved inward appropriately. When the stack direction
6568 is `horizontal`, the top or bottom border is moved inward appropriately.
6570 The margin syntax allows automatic placement of key regardless of stack
6571 direction. When one of the margins `lmargin` (lm), `rmargin` (rm),
6572 `tmargin` (tm), and `bmargin` (bm) is combined with a single, non-conflicting
6573 direction keyword, the following illustrated positions may contain the key:
6586 Keywords `above` and `over` are synonymous with `tmargin`. For version
6587 compatibility, `above` or `over` without an additional l/c/r or stack direction
6588 keyword uses `center` and `horizontal`. Keywords `below` and `under` are
6589 synonymous with `bmargin`. For compatibility, `below` or `under` without an
6590 additional l/c/r or stack direction keyword uses `center` and `horizontal`. A
6591 further compatibility issue is that `outside` appearing without an additional
6592 t/b/c or stack direction keyword uses `top`, `right` and `vertical` (i.e., the
6593 same as t/rm above).
6595 The <position> can be a simple x,y,z as in previous versions, but these can
6596 be preceded by one of five keywords (`first`, `second`, `graph`, `screen`,
6597 `character`) which selects the coordinate system in which the position of
6598 the first sample line is specified. See `coordinates` for more details.
6599 The effect of `left`, `right`, `top`, `bottom`, and `center` when <position>
6600 is given is to align the key as though it were text positioned using the
6601 label command, i.e., `left` means left align with key to the right of
6604 Justification of the labels within the key is controlled by `Left` or `Right`
6605 (default is `Right`). The text and sample can be reversed (`reverse`) and a
6606 box can be drawn around the key (`box {...}`) in a specified `linetype`
6607 and `linewidth`, or a user-defined `linestyle`. Note that not all
6608 terminal drivers support linewidth selection, though.
6610 By default the first plot label is at the top of the key and successive labels
6611 are entered below it. The `invert` option causes the first label to be placed
6612 at the bottom of the key, with successive labels entered above it. This option
6613 is useful to force the vertical ordering of labels in the key to match the
6614 order of box types in a stacked histogram.
6616 The length of the sample line can be controlled by `samplen`. The sample
6617 length is computed as the sum of the tic length and <sample_length> times the
6618 character width. `samplen` also affects the positions of point samples in
6619 the key since these are drawn at the midpoint of the sample line, even if
6620 the sample line itself is not drawn.
6622 The vertical spacing between lines is controlled by `spacing`. The spacing
6623 is set equal to the product of the pointsize, the vertical tic size, and
6624 <vertical_spacing>. The program will guarantee that the vertical spacing is
6625 no smaller than the character height.
6627 The <width_increment> is a number of character widths to be added to or
6628 subtracted from the length of the string. This is useful only when you are
6629 putting a box around the key and you are using control characters in the text.
6630 `gnuplot` simply counts the number of characters in the string when computing
6631 the box width; this allows you to correct it.
6633 The <height_increment> is a number of character heights to be added to or
6634 subtracted from the height of the key box. This is useful mainly when you are
6635 putting a box around the key, otherwise it can be used to adjust the vertical
6636 shift of automatically chosen key position by <height_increment>/2.
6638 All plotted curves of `plot`s and `splot`s are titled according to the
6639 default option `autotitles`. The automatic generation of titles can be
6640 suppressed by `noautotitles`; then only those titles explicitly defined
6641 by `(s)plot ... title ...` will be drawn.
6643 The `set key autotitle columnheader` option is available if gnuplot was built
6644 with --enable-datastrings. This command causes the first entry in each column
6645 of plotted data to be interpreted as a text string and used as a title for
6646 the corresponding plot. If the quantity being plotted is a function of data
6647 from several columns, gnuplot may be confused as to which column to draw the
6648 title from. In this case it is necessary to specify the column explicitly in
6649 the plot command, e.g. `plot "datafile" using (($2+$3)/$4) title 3 with lines`.
6651 A title can be put on the key (`title "<text>"`)---see also `syntax` for the
6652 distinction between text in single- or double-quotes. The key title uses the
6653 same justification as do the plot titles.
6655 An explicitly given title is typeset using enhanced text properties on
6656 terminals supporting this, see `enhanced text` for more details.
6657 This default behavior can be switched off by the `noenhanced` option.
6659 The defaults for `set key` are `on`, `right`, `top`, `vertical`, `Right`,
6660 `noreverse`, `noinvert`, `samplen 4`, `spacing 1.25`, `title ""`, and
6661 `nobox`. The default <linetype> is the same as that used for the plot
6662 borders. Entering `set key default` returns the key to its default
6665 The key is drawn as a sequence of lines, with one plot described on each
6666 line. On the right-hand side (or the left-hand side, if `reverse` is
6667 selected) of each line is a representation that attempts to mimic the way the
6668 curve is plotted. On the other side of each line is the text description
6669 (the line title), obtained from the `plot` command. The lines are vertically
6670 arranged so that an imaginary straight line divides the left- and right-hand
6671 sides of the key. It is the coordinates of the top of this line that are
6672 specified with the `set key` command. In a `plot`, only the x and y
6673 coordinates are used to specify the line position. For a `splot`, x, y and
6674 z are all used as a 3-d location mapped using the same mapping as the graph
6675 itself to form the required 2-d screen position of the imaginary line.
6677 When using the TeX or PostScript drivers, or similar drivers where formatting
6678 information is embedded in the string, `gnuplot` is unable to calculate
6679 correctly the width of the string for key positioning. If the key is to be
6680 positioned at the left, it may be convenient to use the combination `set key
6681 left Left reverse`. The box and gap in the grid will be the width of the
6684 If `splot` is being used to draw contours, the contour labels will be listed
6685 in the key. If the alignment of these labels is poor or a different number
6686 of decimal places is desired, the label format can be specified. See
6687 `set clabel` for details.
6691 This places the key at the default location:
6694 This disables the key:
6697 This places a key at coordinates 2,3.5,2 in the default (first) coordinate
6701 This places the key below the graph:
6704 This places the key in the bottom left corner, left-justifies the text,
6705 gives it a title, and draws a box around it in linetype 3:
6706 set key left bottom Left title 'Legend' box 3
6709 ?commands unset label
6710 ?commands show label
6716 Arbitrary labels can be placed on the plot using the `set label` command.
6719 set label {<tag>} {"<label text>"} {at <position>}
6720 {left | center | right}
6721 {norotate | rotate {by <degrees>}}
6722 {font "<name>{,<size>}"}
6725 {textcolor <colorspec>}
6726 {point <pointstyle> | nopoint}
6731 The <position> is specified by either x,y or x,y,z, and may be preceded by
6732 `first`, `second`, `graph`, `screen`, or `character` to select the coordinate
6733 system. See `coordinates` for details.
6735 The tag is an integer that is used to identify the label. If no <tag>
6736 is given, the lowest unused tag value is assigned automatically. The
6737 tag can be used to delete or modify a specific label. To change any
6738 attribute of an existing label, use the `set label` command with the
6739 appropriate tag, and specify the parts of the label to be changed.
6741 The <label text> can be a string constant, a string variable, or a string-
6742 valued expression. See `strings`, `sprintf`, and `gprintf`.
6744 By default, the text is placed flush left against the point x,y,z. To adjust
6745 the way the label is positioned with respect to the point x,y,z, add the
6746 justification parameter, which may be `left`, `right` or `center`,
6747 indicating that the point is to be at the left, right or center of the text.
6748 Labels outside the plotted boundaries are permitted but may interfere with
6749 axis labels or other text.
6751 If `rotate` is given, the label is written vertically (if the terminal can do
6752 so, of course). If `rotate by <degrees>` is given, conforming terminals will
6753 try to write the text at the specified angle; non-conforming terminals will
6754 treat this as vertical text.
6756 Font and its size can be chosen explicitly by `font "<name>{,<size>}"` if the
6757 terminal supports font settings. Otherwise the default font of the terminal
6760 Normally the enhanced text mode string interpretation, if enabled for the
6761 current terminal, is applied to all text strings including label text.
6762 The `noenhanced` property can be used to exempt a specific label from the
6763 enhanced text mode processing. The can be useful if the label contains
6764 underscores, for example. See `enhanced text`.
6766 If `front` is given, the label is written on top of the graphed data. If
6767 `back` is given (the default), the label is written underneath the graphed
6768 data. Using `front` will prevent a label from being obscured by dense data.
6770 `textcolor <colorspec>` changes the color of the label text. <colorspec> can be
6771 a linetype, an rgb color, or a palette mapping. See help for `colorspec` and
6772 `palette`. `textcolor` may be abbreviated `tc`.
6773 `tc default` resets the text color to its default state.
6774 `tc lt <n>` sets the text color to that of line type <n>.
6775 `tc ls <n>` sets the text color to that of line style <n>.
6776 `tc palette z` selects a palette color corresponding to the label z position.
6777 `tc palette cb <val>` selects a color corresponding to <val> on the colorbar.
6778 `tc palette fraction <val>`, with 0<=val<=1, selects a color corresponding to
6779 the mapping [0:1] to grays/colors of the `palette`.
6780 `tc rgb "#RRGGBB"` selects an arbitrary 24-bit RGB color.
6782 If a <pointstyle> is given, using keywords `lt`, `pt` and `ps`, see `style`,
6783 a point with the given style and color of the given line type is plotted at
6784 the label position and the text of the label is displaced slightly.
6785 This option is used by default for placing labels in `mouse` enhanced
6786 terminals. Use `nopoint` to turn off the drawing of a point near
6787 the label (this is the default).
6789 The displacement defaults to 1,1 in `pointsize` units if a <pointstyle> is
6790 given, 0,0 if no <pointstyle> is given. The displacement can be controlled
6791 by the optional `offset <offset>` where <offset> is specified by either x,y
6792 or x,y,z, and may be preceded by `first`, `second`, `graph`, `screen`, or
6793 `character` to select the coordinate system. See `coordinates` for details.
6795 If one (or more) axis is timeseries, the appropriate coordinate should be
6796 given as a quoted time string according to the `timefmt` format string.
6797 See `set xdata` and `set timefmt`.
6799 The EEPIC, Imagen, LaTeX, and TPIC drivers allow \\ in a string to specify
6804 To set a label at (1,2) to "y=x", use:
6805 set label "y=x" at 1,2
6807 To set a Sigma of size 24, from the Symbol font set, at the center of
6809 set label "S" at graph 0.5,0.5 center font "Symbol,24"
6811 To set a label "y=x^2" with the right of the text at (2,3,4), and tag the
6812 label as number 3, use:
6813 set label 3 "y=x^2" at 2,3,4 right
6815 To change the preceding label to center justification, use:
6818 To delete label number 2, use:
6821 To delete all labels, use:
6824 To show all labels (in tag order), use:
6827 To set a label on a graph with a timeseries on the x axis, use, for example:
6828 set timefmt "%d/%m/%y,%H:%M"
6829 set label "Harvest" at "25/8/93",1
6831 To display a freshly fitted parameter on the plot with the data and the
6832 fitted function, do this after the `fit`, but before the `plot`:
6833 set label sprintf("a = %3.5g",par_a) at 30,15
6834 bfit = gprintf("b = %s*10^%S",par_b)
6835 set label bfit at 30,20
6837 To set a label displaced a little bit from a small point:
6838 set label 'origin' at 0,0 point lt 1 pt 2 ps 3 offset 1,-1
6840 To set a label whose color matches the z value (in this case 5.5) of some
6841 point on a 3D splot colored using pm3d:
6842 set label 'text' at 0,0,5.5 tc palette z
6845 ?commands set lmargin
6848 The command `set lmargin` sets the size of the left margin.
6849 Please see `set margin` for details.
6851 ?commands set loadpath
6852 ?commands show loadpath
6856 The `loadpath` setting defines additional locations for data and command
6857 files searched by the `call`, `load`, `plot` and `splot` commands. If a
6858 file cannot be found in the current directory, the directories in
6859 `loadpath` are tried.
6862 set loadpath {"pathlist1" {"pathlist2"...}}
6865 Path names may be entered as single directory names, or as a list of
6866 path names separated by a platform-specific path separator, eg. colon
6867 (':') on Unix, semicolon (';') on DOS/Windows/OS/2/Amiga platforms.
6868 The `show loadpath`, `save` and `save set` commands replace the
6869 platform-specific separator with a space character (' ') for maximum
6872 If the environment variable GNUPLOT_LIB is set, its contents are
6873 appended to `loadpath`. However, `show loadpath` prints the contents
6874 of user defined loadpath and system loadpath separately. Also, the
6875 `save` and `save set` commands save only the user specified parts of
6876 `loadpath`, for portability reasons.
6878 ?commands set locale
6881 The `locale` setting determines the language with which `{x,y,z}{d,m}tics`
6882 will write the days and months.
6885 set locale {"<locale>"}
6887 <locale> may be any language designation acceptable to your installation.
6888 See your system documentation for the available options. The default value
6889 is determined from the LC_TIME, LC_ALL, or LANG environment variables.
6891 To change the decimal point locale, see `set decimalsign`.
6893 ?commands set logscale
6894 ?commands unset logscale
6895 ?commands show logscale
6903 set logscale <axes> <base>
6904 unset logscale <axes>
6907 where <axes> may be any combination of `x`, `x2`, `y`, `y2`, `z`, and `cb` in
6908 any order, and where <base> is the base of the log scaling. If <base> is not
6909 given, then 10 is assumed. If <axes> is not given, then all axes are assumed.
6910 `unset logscale` turns off log scaling for the specified axes.
6914 To enable log scaling in both x and z axes:
6917 To enable scaling log base 2 of the y axis:
6920 To enable z and color log axes for a pm3d plot:
6923 To disable z axis log scaling:
6926 ?commands set macros
6927 ?commands show macros
6930 If command line macro substitution is enabled, then tokens in the command line
6931 of the form @<stringvariablename> will be replaced by the text string contained
6932 in <stringvariablename>. See `substitution`.
6938 ?commands set mapping
6939 ?commands show mapping
6943 If data are provided to `splot` in spherical or cylindrical coordinates,
6944 the `set mapping` command should be used to instruct `gnuplot` how to
6948 set mapping {cartesian | spherical | cylindrical}
6950 A cartesian coordinate system is used by default.
6952 For a spherical coordinate system, the data occupy two or three columns
6953 (or `using` entries). The first two are interpreted as the azimuthal
6954 and polar angles theta and phi (or "longitude" and "latitude"), in the
6955 units specified by `set angles`. The radius r is taken from the third
6956 column if there is one, or is set to unity if there is no third column.
6959 x = r * cos(theta) * cos(phi)
6960 y = r * sin(theta) * cos(phi)
6963 Note that this is a "geographic" spherical system, rather than a "polar"
6964 one (that is, phi is measured from the equator, rather than the pole).
6966 For a cylindrical coordinate system, the data again occupy two or three
6967 columns. The first two are interpreted as theta (in the units specified by
6968 `set angles`) and z. The radius is either taken from the third column or set
6969 to unity, as in the spherical case. The mapping is:
6975 The effects of `mapping` can be duplicated with the `using` filter on the
6976 `splot` command, but `mapping` may be more convenient if many data files are
6977 to be processed. However even if `mapping` is used, `using` may still be
6978 necessary if the data in the file are not in the required order.
6980 `mapping` has no effect on `plot`.
6982 ^ <a href="http://www.gnuplot.info/demo/world.html">
6983 world.dem: mapping demos.
6986 ?commands set margin
6987 ?commands show margin
6991 The computed margins can be overridden by the `set margin` commands. `show
6992 margin` shows the current settings.
6995 set bmargin {{at screen} <margin>}
6996 set lmargin {{at screen} <margin>}
6997 set rmargin {{at screen} <margin>}
6998 set tmargin {{at screen} <margin>}
7001 The default units of <margin> are character heights or widths, as appropriate.
7002 A positive value defines the absolute size of the margin. A negative value
7003 (or none) causes `gnuplot` to revert to the computed value. For 3D plots,
7004 only the left margin can be set using character units.
7006 The keywords `at screen` indicates that the margin is specified as a fraction
7007 of the full drawing area. This can be used to precisely line up the corners of
7008 individual 2D and 3D graphs in a multiplot. This placement ignores the current
7009 values of `set origin` and `set size`, and is intended as an alternative
7010 method for positioning graphs within a multiplot.
7012 Normally the margins of a plot are automatically calculated based on tics,
7013 tic labels, axis labels, the plot title, the timestamp and the size of the
7014 key if it is outside the borders. If, however, tics are attached to the
7015 axes (`set xtics axis`, for example), neither the tics themselves nor their
7016 labels will be included in either the margin calculation or the calculation
7017 of the positions of other text to be written in the margin. This can lead
7018 to tic labels overwriting other text if the axis is very close to the border.
7021 ?commands unset mouse
7026 The command `set mouse` enables mouse actions. Currently the pm, x11, ggi,
7027 windows and wxt terminals are mouse enhanced. There are two mouse modes. The
7028 2d-graph mode works for 2d graphs and for maps (i.e. splots with `set view`
7029 having z-rotation 0, 90, 180, 270 or 360 degrees, including `set view map`)
7030 and it allows tracing the position over graph, zooming, annotating graph etc.
7031 For 3d graphs `splot`, the view and scaling of the graph can be changed with
7032 mouse buttons 1 and 2. If additionally to these buttons the modifier <ctrl> is
7033 hold down, the coordinate system only is rotated which is useful for large
7034 data sets. A vertical motion of Button 2 with the shift key hold down changes
7037 Mousing is not available in multiplot mode. When multiplot is finished using
7038 `unset multiplot`, then the mouse will be turned on again and acts on the
7039 last plot (like replot does).
7042 set mouse {doubleclick <ms>} {nodoubleclick} \
7043 {{no}zoomcoordinates} \
7044 {noruler | ruler {at x,y}} \
7045 {polardistance{deg|tan} | nopolardistance} \
7047 {clipboardformat <int>/<string>} \
7048 {mouseformat <int>/<string>} \
7049 {{no}labels} {labeloptions <string>} \
7050 {{no}zoomjump} {{no}verbose}
7053 The doubleclick resolution is given in milliseconds and used for Button 1
7054 which copies the current mouse position to the `clipboard`. If you want that
7055 to be done by single clicking a value of 0 ms can be used. The default value
7058 The option `zoomcoordinates` determines if the coordinates of the zoom box are
7059 drawn at the edges while zooming. This is on by default.
7061 The options `noruler` and `ruler` switch the ruler off and on, the latter
7062 optionally at given `coordinates`. This corresponds to the default key binding
7065 The option `polardistance` determines if the distance between the mouse cursor
7066 and the ruler is also shown in polar coordinates (distance and angle in
7067 degrees or tangent (slope)). This corresponds to the default key binding '5'.
7069 The `format` option takes a fprintf like format string which determines how
7070 floating point numbers are printed to the drivers window and the clipboard.
7071 The default is "% #g".
7073 `clipboardformat` and `mouseformat` are used for formatting the text on
7074 Button1 and Button2 actions -- copying the coordinates to the clipboard and
7075 temporarily annotating the mouse position. This corresponds to the key
7076 bindings '1', '2', '3', '4' (see the drivers's help window). If the argument
7077 is a string this string is used as c format specifier and should contain two
7078 float specifiers, e.g. `set mouse mouseformat "mouse = %5.2g, %10.2f"`. Use
7079 `set mouse mouseformat ""` to turn this string off again.
7081 The following formats are available (format 6 may only be selected if the
7082 format string was specified already):
7084 0 real coordinates in brackets e.g. [1.23, 2.45]
7085 1 real coordinates w/o brackets e.g. 1.23, 2.45
7086 2 x == timefmt [(as set by `set timefmt`), 2.45]
7087 3 x == date [31. 12. 1999, 2.45]
7088 4 x == time [23:59, 2.45]
7089 5 x == date / time [31. 12. 1999 23:59, 2.45]
7090 6 alt. format, specified as string ""
7092 Choose the option `labels` to get real gnuplot labels on Button 2. (The
7093 default is `nolabels` which makes Button 2 drawing only temporary annotations
7094 at the mouse positions). The labels are drawn with the current setting of
7095 `mouseformat`. `labeloptions` controls which options are passed to the
7096 `set label` command. The default is "pointstyle 1" which will plot a small
7097 plus at the label position. Note that the pointsize is taken from the
7098 `set pointsize` command.
7099 Labels can be removed by holding the Ctrl-Key down while clicking with
7100 Button 2 on the label's point. The threshold for how close you must be to the
7101 label is also determined by the `pointsize`.
7103 If the option `zoomjump` is on, the mouse pointer will be automatically
7104 offset a small distance after starting a zoom region with button 3. This can
7105 be useful to avoid a tiny (or even empty) zoom region. `zoomjump` is off by
7108 If the option `verbose` is turned on the communication commands are shown
7109 during execution. This option can also be toggled by hitting `6` in the
7110 driver's window. `verbose` is off by default.
7112 Press 'h' in the driver's window for a short summary of the mouse and key
7113 bindings. This will also display user defined bindings or `hotkeys` which
7114 can be defined using the `bind` command, see help for `bind`. Note, that user
7115 defined `hotkeys` may override the default bindings.
7117 Press 'q' in the driver's window to close the window. This key cannot be
7118 overridden with the `bind` command.
7120 See also help for `bind` and `label`.
7125 If multiple X11 plot windows have been opened using the `set term x11 <n>`
7126 terminal option, then only the current plot window supports the entire
7127 range of mouse commands and hotkeys. The other windows will, however,
7128 continue to display mouse coordinates at the lower left.
7130 For consistency with other screen terminals, X11 mouse support is turned on by
7131 default, wherever the standard input comes from. However, on some UNIX
7132 flavors, special input devices as /dev/null might not be `select-able`; using
7133 such devices with the mouse turned on will hang gnuplot. Please turn off
7134 mousing with `unset mouse` if you are in this situation.
7136 ?commands set multiplot
7137 ?commands unset multiplot
7142 The command `set multiplot` places `gnuplot` in the multiplot mode, in which
7143 several plots are placed on the same page, window, or screen.
7146 set multiplot { layout <rows>,<cols>
7147 {rowsfirst|columnsfirst} {downwards|upwards}
7148 {title <page title>}
7149 {scale <xscale>{,<yscale>}} {offset <xoff>{,<yoff>}}
7153 For some terminals, no plot is displayed until the command `unset multiplot`
7154 is given, which causes the entire page to be drawn and then returns gnuplot
7155 to its normal single-plot mode. For other terminals, each separate `plot`
7156 command produces an updated display, either by redrawing all previous ones
7157 and the newly added plot, or by just adding the new plot to the existing
7160 The area to be used by the next plot is not erased before doing the
7161 new plot. The `clear` command can be used to do this if wanted, as is
7162 typically the case for "inset" plots.
7164 Any labels or arrows that have been defined will be drawn for each plot
7165 according to the current size and origin (unless their coordinates are
7166 defined in the `screen` system). Just about everything else that can be
7167 `set` is applied to each plot, too. If you want something to appear only
7168 once on the page, for instance a single time stamp, you'll need to put a `set
7169 time`/`unset time` pair around one of the `plot`, `splot` or `replot`
7170 commands within the `set multiplot`/`unset multiplot` block.
7172 The multiplot title is separate from the individual plot titles, if any.
7173 Space is reserved for it at the top of the page, spanning the full width
7176 The commands `set origin` and `set size` must be used to correctly position
7177 each plot if no layout is specified or if fine tuning is desired. See
7178 `set origin` and `set size` for details of their usage.
7190 This displays a plot of cos(x) stacked above a plot of sin(x).
7192 `set size` and `set origin` refer to the entire plotting area used for each
7193 plot. Please also see `set term size`. If you want to have the axes
7194 themselves line up, you can guarantee that the margins are the same size with
7195 the `set margin` commands. See `set margin` for their use. Note that the
7196 margin settings are absolute, in character units, so the appearance of the
7197 graph in the remaining space will depend on the screen size of the display
7198 device, e.g., perhaps quite different on a video display and a printer.
7200 With the `layout` option you can generate simple multiplots without having
7201 to give the `set size` and `set origin` commands before each plot: Those
7202 are generated automatically, but can be overridden at any time. With
7203 `layout` the display will be divided by a grid with <rows> rows and
7204 <cols> columns. This grid is filled rows first or columns first depending on
7205 whether the corresponding option is given in the multiplot command. The stack
7206 of plots can grow `downwards` or `upwards`.
7207 Default is `rowsfirst` and `downwards`.
7209 Each plot can be scaled by `scale` and shifted with `offset`; if the y-values
7210 for scale or offset are omitted, the x-value will be used. `unset multiplot`
7211 will turn off the automatic layout and restore the values of `set size` and
7212 `set origin` as they were before `set multiplot layout`.
7217 set multiplot layout 3,2 columnsfirst scale 1.1,0.9
7218 [ up to 6 plot commands here ]
7221 The above example will produce 6 plots in 2 columns filled top to bottom,
7222 left to right. Each plot will have a horizontal size of 1.1/2 and a vertical
7226 ^ <a href="http://gnuplot.sourceforge.net/demo/multiplt.html">
7227 multiplot demo (multiplt.dem)
7230 ?commands set mx2tics
7231 ?commands unset mx2tics
7232 ?commands show mx2tics
7238 Minor tic marks along the x2 (top) axis are controlled by `set mx2tics`.
7239 Please see `set mxtics`.
7241 ?commands set mxtics
7242 ?commands unset mxtics
7243 ?commands show mxtics
7249 Minor tic marks along the x axis are controlled by `set mxtics`. They can be
7250 turned off with `unset mxtics`. Similar commands control minor tics along
7254 set mxtics {<freq> | default}
7258 The same syntax applies to `mytics`, `mztics`, `mx2tics`, `my2tics` and
7261 <freq> is the number of sub-intervals (NOT the number of minor tics) between
7262 major tics (the default for a linear axis is either two or five
7263 depending on the major tics, so there are one or four minor
7264 tics between major tics). Selecting `default` will return the number of minor
7265 ticks to its default value.
7267 If the axis is logarithmic, the number of sub-intervals will be set to a
7268 reasonable number by default (based upon the length of a decade). This will
7269 be overridden if <freq> is given. However the usual minor tics (2, 3, ...,
7270 8, 9 between 1 and 10, for example) are obtained by setting <freq> to 10,
7271 even though there are but nine sub-intervals.
7273 To set minor tics at arbitrary positions, use the ("<label>" <pos> <level>,
7274 ...) form of `set {x|x2|y|y2|z}tics` with <label> empty and <level> set to 1.
7276 The `set m{x|x2|y|y2|z}tics` commands work only when there are uniformly
7277 spaced major tics. If all major tics were placed explicitly by
7278 `set {x|x2|y|y2|z}tics`, then minor tic commands are ignored. Implicit
7279 major tics and explicit minor tics can be combined using
7280 `set {x|x2|y|y2|z}tics` and `set {x|x2|y|y2|z}tics add`.
7286 Major tics at 0,5,7.5,10, minor tics at 1,2,3,4,6,7,8,9
7289 set ytics 1e-6, 10, 1
7290 set ytics add ("1" 1, ".1" 0.1, ".01" 0.01, "10^-3" 0.001, \
7293 Major tics with special formatting, minor tics at log positions
7295 By default, minor tics are off for linear axes and on for logarithmic axes.
7296 They inherit the settings for `axis|border` and `{no}mirror` specified for
7297 the major tics. Please see `set xtics` for information about these.
7299 ?commands set my2tics
7300 ?commands unset my2tics
7301 ?commands show my2tics
7307 Minor tic marks along the y2 (right-hand) axis are controlled by `set
7308 my2tics`. Please see `set mxtics`.
7310 ?commands set mytics
7311 ?commands unset mytics
7312 ?commands show mytics
7318 Minor tic marks along the y axis are controlled by `set mytics`. Please
7321 ?commands set mztics
7322 ?commands unset mztics
7323 ?commands show mztics
7329 Minor tic marks along the z axis are controlled by `set mztics`. Please
7332 ?commands set offsets
7333 ?commands unset offsets
7334 ?commands show offsets
7340 Offsets provide a mechanism to put a boundary around the data inside of an
7344 set offsets <left>, <right>, <top>, <bottom>
7348 Each offset may be a constant or an expression. Each defaults to 0. Left
7349 and right offsets are given in units of the x axis, top and bottom offsets in
7350 units of the y axis. A positive offset expands the graph in the specified
7351 direction, e.g., a positive bottom offset makes ymin more negative. Negative
7352 offsets, while permitted, can have unexpected interactions with autoscaling
7355 Offsets are ignored in `splot`s.
7358 set offsets 0, 0, 2, 2
7361 This graph of sin(x) will have a y range [-3:3] because the function
7362 will be autoscaled to [-1:1] and the vertical offsets are each two.
7364 ?commands set origin
7365 ?commands show origin
7369 The `set origin` command is used to specify the origin of a plotting surface
7370 (i.e., the graph and its margins) on the screen. The coordinates are given
7371 in the `screen` coordinate system (see `coordinates` for information about
7375 set origin <x-origin>,<y-origin>
7377 ?commands set output
7378 ?commands show output
7383 By default, screens are displayed to the standard output. The `set output`
7384 command redirects the display to the specified file or device.
7387 set output {"<filename>"}
7390 The filename must be enclosed in quotes. If the filename is omitted, any
7391 output file opened by a previous invocation of `set output` will be closed
7392 and new output will be sent to STDOUT. (If you give the command `set output
7393 "STDOUT"`, your output may be sent to a file named "STDOUT"! ["May be", not
7394 "will be", because some terminals, like `x11` or `wxt`, ignore `set output`.])
7396 MSDOS users should note that the \ character has special significance in
7397 double-quoted strings, so single-quotes should be used for filenames in
7398 different directories.
7400 When both `set terminal` and `set output` are used together, it is safest to
7401 give `set terminal` first, because some terminals set a flag which is needed
7402 in some operating systems. This would be the case, for example, if the
7403 operating system needs to know whether or not a file is to be formatted in
7404 order to open it properly.
7406 On machines with popen functions (Unix), output can be piped through a shell
7407 command if the first non-whitespace character of the filename is '|'.
7410 set output "|lpr -Plaser filename"
7411 set output "|lp -dlaser filename"
7413 On MSDOS machines, `set output "PRN"` will direct the output to the default
7414 printer. On VMS, output can be sent directly to any spooled device. It is
7415 also possible to send the output to DECnet transparent tasks, which allows
7418 ?commands set parametric
7419 ?commands unset parametric
7420 ?commands show parametric
7426 The `set parametric` command changes the meaning of `plot` (`splot`) from
7427 normal functions to parametric functions. The command `unset parametric`
7428 restores the plotting style to normal, single-valued expression plotting.
7435 For 2-d plotting, a parametric function is determined by a pair of parametric
7436 functions operating on a parameter. An example of a 2-d parametric function
7437 would be `plot sin(t),cos(t)`, which draws a circle (if the aspect ratio is
7438 set correctly---see `set size`). `gnuplot` will display an error message if
7439 both functions are not provided for a parametric `plot`.
7441 For 3-d plotting, the surface is described as x=f(u,v), y=g(u,v), z=h(u,v).
7442 Therefore a triplet of functions is required. An example of a 3-d parametric
7443 function would be `cos(u)*cos(v),cos(u)*sin(v),sin(u)`, which draws a sphere.
7444 `gnuplot` will display an error message if all three functions are not
7445 provided for a parametric `splot`.
7447 The total set of possible plots is a superset of the simple f(x) style plots,
7448 since the two functions can describe the x and y values to be computed
7449 separately. In fact, plots of the type t,f(t) are equivalent to those
7450 produced with f(x) because the x values are computed using the identity
7451 function. Similarly, 3-d plots of the type u,v,f(u,v) are equivalent to
7454 Note that the order the parametric functions are specified is xfunction,
7455 yfunction (and zfunction) and that each operates over the common parametric
7458 Also, the `set parametric` function implies a new range of values. Whereas
7459 the normal f(x) and f(x,y) style plotting assume an xrange and yrange (and
7460 zrange), the parametric mode additionally specifies a trange, urange, and
7461 vrange. These ranges may be set directly with `set trange`, `set urange`,
7462 and `set vrange`, or by specifying the range on the `plot` or `splot`
7463 commands. Currently the default range for these parametric variables is
7464 [-5:5]. Setting the ranges to something more meaningful is expected.
7468 The `show plot` command shows the current plotting command as it results
7469 from the last `plot` and/or `splot` and possible subsequent `replot` commands.
7471 In addition, the `show plot add2history` command adds this current plot
7472 command into the `history`. It is useful if you have used `replot` to add
7473 more curves to the current plot and you want to edit the whole command now.
7480 pm3d is an `splot` style for drawing palette-mapped 3d and 4d data as
7481 color/gray maps and surfaces. It uses a pm3d algorithm which allows plotting
7482 gridded as well as non-gridded data without preprocessing, even when the data
7483 scans do not have the same number of points.
7485 Drawing of color surfaces is available on terminals supporting filled colored
7486 polygons with color mapping specified by `palette`. Currently supported
7490 OS/2 Presentation Manager
7499 pslatex, pstex, epslatex
7508 Let us first describe how a map/surface is drawn. The input data come from an
7509 evaluated function or from an `splot data file`. Each surface consists of a
7510 sequence of separate scans (isolines). The pm3d algorithm fills the region
7511 between two neighbouring points in one scan with another two points in the
7512 next scan by a gray (or color) according to z-values (or according to an
7513 additional 'color' column, see help for `using`) of these 4 corners; by default
7514 the 4 corner values are averaged, but this can be changed by the option
7515 `corners2color`. In order to get a reasonable surface, the neighbouring scans
7516 should not cross and the number of points in the neighbouring scans should not
7517 differ too much; of course, the best plot is with scans having same number of
7518 points. There are no other requirements (e.g. the data need not be gridded).
7519 Another advantage is that the pm3d algorithm does not draw anything outside of
7520 the input (measured or calculated) region.
7522 Surface coloring works with the following input data:
7524 1. splot of function or of data file with one or three data columns: The
7525 gray/color scale is obtained by mapping the averaged (or `corners2color`)
7526 z-coordinate of the four corners of the above-specified quadrangle into the
7527 range [min_color_z,max_color_z] of `zrange` or `cbrange` providing a gray value
7528 in the range [0:1]. This value can be used directly as the gray for gray maps.
7529 The normalized gray value can be further mapped into a color---see `set palette`
7530 for the complete description.
7532 2. splot of data file with two or four data columns: The gray/color value is
7533 obtained by using the last-column coordinate instead of the z-value, thus
7534 allowing the color and the z-coordinate be mutually independent. This can be
7535 used for 4d data drawing.
7539 1. The term 'scan' referenced above is used more among physicists than the
7540 term 'iso_curve' referenced in gnuplot documentation and sources. You measure
7541 maps recorded one scan after another scan, that's why.
7543 2. The 'gray' or 'color' scale is a linear mapping of a continuous variable
7544 onto a smoothly varying palette of colors. The mapping is shown in a
7545 rectangle next to the main plot. This documentation refers to this as a
7546 "colorbox", and refers to the indexing variable as lying on the colorbox axis.
7547 See `set colorbox`, `set cbrange`.
7549 3. To use pm3d coloring to generate a two-dimensional plot rather than a 3D
7550 surface, use `set view map` or `set pm3d map`.
7552 Syntax (the options can be given in any order):
7554 { at <bst combination> }
7555 { interpolate <steps in scan>,<steps between scans> }
7556 { scansautomatic | scansforward | scansbackward | depthorder }
7557 { flush { begin | center | end } }
7558 { ftriangles | noftriangles }
7559 { clip1in | clip4in }
7560 { corners2color { mean|geomean|median|min|max|c1|c2|c3|c4 } }
7561 { hidden3d <linestyle> | nohidden3d }
7562 { implicit | explicit }
7568 Color surface is drawn if data or function `style` is set to pm3d globally or
7569 via 'with' option, or if the option `implicit` is on---then the pm3d surface
7570 is combined with the line surface mesh. See bottom of this section for mode
7573 Color surface can be drawn at the base or top (then it is a gray/color planar
7574 map) or at z-coordinates of surface points (gray/color surface). This is
7575 defined by the `at` option with a string of up to 6 combinations of `b`, `t`
7576 and `s`. For instance, `at b` plots at bottom only, `at st` plots firstly
7577 surface and then top map, while `at bstbst` will never by seriously used.
7579 Colored quadrangles are plotted one after another. When plotting surfaces
7580 (`at s`), the later quadrangles overlap (overdraw) the previous ones.
7581 (Gnuplot is not virtual reality tool to calculate intersections of filled
7582 polygon meshes.) You may try to switch between `scansforward` and
7583 `scansbackward` to force the first scan of the data to be plotted first or
7584 last. The default is `scansautomatic` where gnuplot makes a guess about scans
7585 order. On the other hand, the `depthorder` option completely reorders the
7586 qudrangles. The rendering is performed after a depth sorting, which allows to
7587 visualize even complicated surfaces; see `pm3d depthorder` for more
7590 If two subsequent scans do not have same number of points, then it has to be
7591 decided whether to start taking points for quadrangles from the beginning of
7592 both scans (`flush begin`), from their ends (`flush end`) or to center them
7593 (`flush center`). Note, that `flush (center|end)` are incompatible with
7594 `scansautomatic`: if you specify `flush center` or `flush end` and
7595 `scansautomatic` is set, it is silently switched to `scansforward`.
7597 If two subsequent scans do not have the same number of points, the option
7598 `ftriangles` specifies whether color triangles are drawn at the scan tail(s)
7599 where there are not enough points in either of the scan. This can be used to
7600 draw a smooth map boundary.
7602 Clipping with respect to x, y coordinates of quadrangles can be done in two
7603 ways. `clip1in`: all 4 points of each quadrangle must be defined and at least
7604 1 point of the quadrangle must lie in the x and y ranges. `clip4in`: all 4
7605 points of each quadrangle must lie in the x and y ranges.
7607 There is a single gray/color value associated to each drawn pm3d quadrangle
7608 (no smooth color change among vertices). The value is calculated from
7609 z-coordinates from the surrounding corners according to `corners2color
7610 <option>`. The options 'mean' (default), 'geomean' and 'median' produce
7611 various kinds of surface color smoothing, while options 'min' and 'max' choose
7612 minimal or maximal value, respectively. This may not be desired for pixel
7613 images or for maps with sharp and intense peaks, in which case the options
7614 'c1', 'c2', 'c3' or 'c4' can be used instead to assign the quadrangle color
7615 based on the z-coordinate of only one corner. Some experimentation may be
7616 needed to determine which corner corresponds to 'c1', as the orientation
7617 depends on the drawing direction. Because the pm3d algorithm does not extend
7618 the colored surface outside the range of the input data points, the 'c<j>'
7619 coloring options will result in pixels along two edges of the grid not
7620 contributing to the color of any quadrangle. For example, applying the pm3d
7621 algorithm to the 4x4 grid of data points in script `demo/pm3d.dem` (please have
7622 a look) produces only (4-1)x(4-1)=9 colored rectangles.
7624 Another drawing algorithm, which would draw quadrangles around a given node
7625 by taking corners from averaged (x,y)-coordinates of its surrounding 4 nodes
7626 while using node's color, could be implemented in the future. This is already
7627 done for drawing images (2D grids) via `image` and `rgbimage` styles.
7629 Notice that ranges of z-values and color-values for surfaces are adjustable
7630 independently by `set zrange`, `set cbrange`, as well as `set log` for z or
7631 cb. Maps can be adjusted by the cb-axis only; see also `set view map` and
7634 The option `hidden3d` takes as the argument a linestyle which must be created
7635 by `set style line ...`. (The style need not to be present when setting pm3d,
7636 but it must be present when plotting). If set, lines are drawn using the
7637 specified line style, taking into account hidden line removal. This is by
7638 far more efficient than using the command `set hidden3d` as it doesn't really
7639 calculate hidden line removal, but just draws the filled polygons in the
7640 correct order. So the recommended choice when using pm3d is
7641 set pm3d at s hidden3d 100
7642 set style line 100 lt 5 lw 0.5
7647 There used to be an option {transparent|solid} to this command. Now
7648 you get the same effect from `set grid {front|layerdefault}`,
7651 The `set pm3d map` is an abbreviation for `set pm3d at b`; `set view map`;
7652 `set style data pm3d`; `set style func pm3d`;.
7653 It is used for backwards compatibility, when `set view map` was not available.
7654 Take care that you properly use `zrange` and `cbrange` for input data point
7655 filtering and color range scaling, respectively; and also `set (no)surface`
7656 seems to have a (side?) effect.
7658 The option `interpolate` will interpolate grid points into a finer mesh, and
7659 color each quadrangle appropriately. For data files, this will smoothen the
7660 color surface, and enhance spikes in a color surface. For functions,
7661 interpolation makes little sense, except to trade off precision for memory.
7662 It would usually make more sense to use `samples` and `isosamples` when working
7665 The coloring setup as well as the color box drawing are determined by
7666 `set palette`. There can be only one palette for the current plot. Drawing
7667 of several surfaces with different palettes can be achieved by `multiplot`
7668 with fixed `origin` and `size`; don't forget to use `set palette maxcolors`
7669 when your terminal is running out of available colors.
7671 On gnuplot start-up, mode is `explicit`. For historical and thus compatibility
7672 reasons, commands `set pm3d;` (i.e. no options) and `set pm3d at X ...` (i.e.
7673 `at` is the first option) sets mode `implicit`. Further, `set pm3d;` sets up
7674 the other options to their default.
7676 If the option `implicit` is on, all surface plots will be plotted additionally
7677 to the default type, e.g.
7678 splot 'fred.dat' with lines, 'lola.dat' with lines
7679 would give both plots (meshes) additionally to a pm3d surface. That's what you
7680 are used to after `set pm3d;`.
7682 If the option `explicit` is on (or `implicit` is off) only plots specified
7683 by the `with pm3d` attribute are plotted with a pm3d surface, e.g.:
7684 splot 'fred.dat' with lines, 'lola.dat' with pm3d
7685 would plot 'fred.dat' with lines (and only lines) and 'lola.dat' with
7688 If you set the default data or function style to `pm3d`, e.g.:
7690 then the options `implicit` and `explicit` have no effect.
7692 Note that when plotting several plots, they are plotted in the order given
7693 on the command line. This can be of interest especially for filled surfaces
7694 which can overwrite and therefore hide part of earlier plots.
7696 If `with pm3d` is specified in the `splot` command line, then it accepts the
7697 'at' option. The following plots draw three color surfaces at different
7701 splot 10*x with pm3d at b, x*x-y*y, x*x+y*y with pm3d at t
7703 See also help for `set palette`, `set cbrange`, `set colorbox`, `x11 pm3d`
7704 and definitely the demo file `demo/pm3d.dem`.
7706 ?commands set pm3d depthorder
7707 ?set pm3d depthorder
7710 By default the quadrangles making up a pm3d solid surface are rendered in the
7711 order they are encountered along the surface grid points. This order may be
7712 controlled by the options `scansautomatic`|`scansforward`|`scansbackward`.
7713 These scan options are not in general compatible with hidden-surface removal.
7715 Gnuplot does not do true hidden surface removal for solid surfaces, but often
7716 it is sufficient to render the component quadrangles in order from furthest
7717 to closest. This mode may be selected using the options
7718 set pm3d depthorder hidden3d
7719 The `depthorder` option orders the solid quadrangles; the `hidden3d` option
7720 similarly orders the bounding lines (if drawn). Note that the global option
7721 `set hidden3d` does not affect pm3d surfaces.
7723 ?commands set palette
7724 ?commands show palette
7728 Palette is a color storage for use by `pm3d`, filled color contours or
7729 polygons, color histograms, color gradient background, and whatever it is
7730 or it will be implemented... Here it stands for a palette of smooth
7731 "continuous" colors or grays, but let's call it just a palette.
7733 Color palettes require terminal entries for filled color polygons and
7734 palettes of smooth colors, are currently available for terminals listed in
7735 help for `set pm3d`. The range of color values are adjustable independently by
7736 `set cbrange` and `set log cb`. The whole color palette is
7737 visualized in the `colorbox`.
7744 { rgbformulae <r>,<g>,<b>
7745 | defined { ( <gray1> <color1> {, <grayN> <colorN>}... ) }
7746 | file '<filename>' {datafile-modifiers}
7747 | functions <R>,<G>,<B>
7749 { model { RGB | HSV | CMY | YIQ | XYZ } }
7750 { positive | negative }
7751 { nops_allcF | ps_allcF }
7752 { maxcolors <maxcolors> }
7755 show palette palette <n> {{float | int}}
7756 show palette gradient
7757 show palette fit2rgbformulae
7758 show palette rgbformulae
7759 show palette colornames
7761 `set palette` (i.e. without options) sets up the default values.
7762 Otherwise, the options can be given in any order.
7763 `show palette` shows the current palette properties.
7765 `show palette gradient` displays the gradient defining the palette (if
7766 appropriate). `show palette rgbformulae` prints the available fixed gray -->
7767 color transformation formulae. `show palette colornames` prints the
7768 implemented color names.
7770 `show palette palette <n>` prints to screen or to the file given by
7771 `set output` table of RGB triplets calculated for the current palette settings
7772 and a palette having <n> discrete colors. The default wide table can be
7773 limited to 3 columns of r,g,b float values [0..1] or integer values [0..255]
7774 by options float or int, respectively. This way, the current gnuplot color
7775 palette can be loaded into other imaging applications, for example Octave.
7776 Additionally to this textual list of RGB table, you can enjoy command `test
7777 palette` to draw graphically the R,G,B profiles for the current palette.
7779 The following options determine the coloring properties.
7781 Figure using this palette can be `gray` or `color`. For instance, in `pm3d`
7782 color surfaces the gray of each small spot is obtained by mapping the averaged
7783 z-coordinate of the 4 corners of surface quadrangles into the range
7784 [min_z,max_z] providing range of grays [0:1]. This value can be used directly
7785 as the gray for gray maps. The color map requires a transformation gray -->
7786 (R,G,B), i.e. a mapping [0:1] --> ([0:1],[0:1],[0:1]).
7788 Basically two different types of mappings can be used: Analytic formulae to
7789 convert gray to color, or discrete mapping tables which are interpolated.
7790 `palette rgbformulae` and `palette functions` use analytic formulae whereas
7791 `palette defined` and `palette file` use interpolated tables. `palette
7792 rgbformulae` reduces the size of postscript output to a minimum.
7794 The command `show palette fit2rgbformulae` finds the best matching `set
7795 palette rgbformulae` for the current `set palette`. Naturally, it makes sense
7796 to use it for non-rgbformulae palettes. This command can be found useful
7797 mainly for external programs using the same rgbformulae definition of palettes
7798 as gnuplot, like zimg (
7799 ^ <a href="http://zimg.sourceforge.net">
7800 http://zimg.sourceforge.net
7804 `set palette gray` switches to a gray only palette. `set palette rgbformulae`,
7805 `set palette defined`, `set palette file` and `set palette functions` switch
7806 to a color mapping. `set palette color` is an easy way to switch back from the
7807 gray palette to the last color mapping.
7809 Automatic gamma correction via `set palette gamma <gamma>` can be done for
7810 gray maps only (`set palette gray`). Linear mapping to gray is for gamma
7811 equals 1, see `test palette`. Gamma is ignored for color mappings.
7813 Most terminals support only discrete number of colors (e.g. 256 colors in
7814 gif). All entries of the palette remaining after the default gnuplot linetype
7815 colors declaration are allocated for pm3d by default. Then `multiplot` could
7816 fail if there are no more color positions in the terminal available. Then you
7817 should use `set palette maxcolors <maxcolors>` with a reasonably small value.
7818 This option can also be used to separate levels of z=constant in discrete
7819 steps, thus to emulate filled contours. Default value of 0 stays for
7820 allocating all remaining entries in the terminal palette or for to use exact
7823 RGB color space might not be the most useful color space to work in. For that
7824 reason you may change the color space with `model` to one of `RGB`, `HSV`,
7825 `CMY`, `YIQ` and `XYZ`. Using color names for `set palette defined` tables
7826 and a color space other than RGB will result in funny colors. All explanation
7827 have been written for RGB color space, so please note, that `R` can be `H`,
7828 `C`, `Y`, or `X`, depending on the actual color space (`G` and `B`
7831 All values for all color spaces are limited to [0,1].
7833 RGB stands for Red, Green and Blue; CMY stands for Cyan, Magenta and Yellow;
7834 HSV stands for Hue, Saturation, and Value; YIQ is the color model used by
7835 the U.S. Commercial Color Television Broadcasting, it is basically an RGB
7836 recoding with downward compatibility for black and white television;
7837 XYZ are the three primary colors of the color model defined by the 'Commission
7838 Internationale de l'Eclairage' (CIE).
7839 For more information on color models see:
7840 ^ <a href="http://www.cs.rit.edu/~ncs/color/glossary.htm">
7841 http://www.cs.rit.edu/~ncs/color/glossary.htm
7844 ^ <a href="http://cs.fit.edu/wds/classes/cse5255/cse5255/davis/index.html">
7845 http://cs.fit.edu/wds/classes/cse5255/cse5255/davis/index.html
7849 ?commands set palette rgbformulae
7850 ?set palette rgbformulae
7851 ?palette rgbformulae
7854 For `rgbformulae` three suitable mapping functions have
7855 to be chosen. This is done via `rgbformulae <r>,<g>,<b>`. The available
7856 mapping functions are listed by `show palette rgbformulae`. Default is
7857 `7,5,15`, some other examples are `3,11,6`, `21,23,3` or `3,23,21`. Negative
7858 numbers, like `3,-11,-6`, mean inverted color (i.e. 1-gray passed into the
7859 formula, see also `positive` and `negative` options below).
7861 Some nice schemes in RGB color space
7862 7,5,15 ... traditional pm3d (black-blue-red-yellow)
7863 3,11,6 ... green-red-violet
7864 23,28,3 ... ocean (green-blue-white); try also all other permutations
7865 21,22,23 ... hot (black-red-yellow-white)
7866 30,31,32 ... color printable on gray (black-blue-violet-yellow-white)
7867 33,13,10 ... rainbow (blue-green-yellow-red)
7868 34,35,36 ... AFM hot (black-red-yellow-white)
7870 A full color palette in HSV color space
7871 3,2,2 ... red-yellow-green-cyan-blue-magenta-red
7873 Please note that even if called `rgbformulae` the formulas might actually
7874 determine the <H>,<S>,<V> or <X>,<Y>,<Z> or ... color components as usual.
7876 Use `positive` and `negative` to invert the figure colors.
7877 ^ <a name="positive"></a>
7878 ^ <a name="negative"></a>
7880 Note that it is possible to find a set of the best matching rgbformulae for any
7881 other color scheme by the command
7882 show palette fit2rgbformulae
7884 ?commands set palette defined
7885 ?set palette defined
7888 Gray-to-rgb mapping can be manually set by use of `palette defined`: A color gradient
7889 is defined and used to give the rgb values. Such a gradient is a piecewise
7890 linear mapping from gray values in [0,1] to the RGB space [0,1]x[0,1]x[0,1].
7891 You have to specify the gray values and the corresponding RGB values in
7892 between a linear interpolation shall take place:
7895 set palette defined { ( <gray1> <color1> {, <grayN> <colorN>}... ) }
7897 <grayX> are gray values which are mapped to [0,1] and <colorX> are the
7898 corresponding rgb colors. The color can be specified in three different
7901 <color> := { <r> <g> <b> | '<color-name>' | '#rrggbb' }
7903 Either by three numbers (each in [0,1]) for red, green and blue, separated by
7904 whitespace, or the name of the color in quotes or X style color specifiers
7905 also in quotes. You may freely mix the three types in a gradient definition,
7906 but the named color "red" will be something strange if RGB is not selected
7907 as color space. Use `show palette colornames` for a list of known color
7910 Please note, that even if written as <r>, this might actually be the
7911 <H> component in HSV color space or <X> in CIE-XYZ space, or ...
7912 depending on the selected color model.
7914 The <gray> values have to form an ascending sequence of real numbers; the
7915 sequence will be automatically rescaled to [0,1].
7917 `set palette defined` (without a gradient definition in braces) switches to
7918 RGB color space and uses a preset full-spectrum color gradient.
7919 Use `show palette gradient` to display the gradient.
7923 To produce a gray palette (useless but instructive) use:
7924 set palette model RGB
7925 set palette defined ( 0 "black", 1 "white" )
7927 To produce a blue yellow red palette use (all equivalent):
7928 set palette defined ( 0 "blue", 1 "yellow", 2 "red" )
7929 set palette defined ( 0 0 0 1, 1 1 1 0, 2 1 0 0 )
7930 set palette defined ( 0 "#0000ff", 1 "#ffff00", 2 "#ff0000" )
7932 To produce some rainbow-like palette use:
7933 set palette defined ( 0 "blue", 3 "green", 6 "yellow", 10 "red" )
7935 Full color spectrum within HSV color space:
7936 set palette model HSV
7937 set palette defined ( 0 0 1 1, 1 1 1 1 )
7938 set palette defined ( 0 0 1 0, 1 0 1 1, 6 0.8333 1 1, 7 0.8333 0 1)
7940 To produce a palette with few colors only use:
7941 set palette model RGB maxcolors 4
7942 set palette defined ( 0 "blue", 1 "green", 2 "yellow", 3 "red" )
7944 'Traffic light' palette (non-smooth color jumps at gray = 1/3 and 2/3).
7945 set palette model RGB
7946 set palette defined (0 "dark-green", 1 "green", 1 "yellow", \
7947 2 "dark-yellow", 2 "red", 3 "dark-red" )
7950 ?commands set palette functions
7951 ?set palette functions
7953 Use `set palette functions <Rexpr>, <Gexpr>, <Bexpr>` to define three formulae
7954 for the R(gray), G(gray) and B(gray) mapping. The three formulae may depend
7955 on the variable `gray` which will take values in [0,1] and should also
7956 produce values in [0,1].
7957 Please note that <Rexpr> might be a formula for the H-value if HSV color
7958 space has been chosen (same for all other formulae and color spaces).
7962 To produce a full color palette use:
7963 set palette model HSV functions gray, 1, 1
7965 A nice black to gold palette:
7966 set palette model XYZ functions gray**0.35, gray**0.5, gray**0.8
7968 A gamma-corrected black and white palette
7970 color(gray) = gray**(1./gamma)
7971 set palette model RGB functions color(gray), color(gray), color(gray)
7974 ?commands set palette file
7977 `set palette file` is basically a `set palette defined (<gradient>)` where
7978 <gradient> is read from a datafile. Either 4 columns (gray,R,G,B) or
7979 just three columns (R,G,B) have to be selected via the `using` data file
7980 modifier. In the three column case, the line number will be used as gray.
7981 The gray range is automatically rescaled to [0,1]. The file is read as a
7982 normal data file, so all datafile modifiers can be used.
7983 Please note, that `R` might actually be e.g. `H` if HSV color space is
7986 As usual <filename> may be `'-'` which means that the data follow the command
7987 inline and are terminated by a single `e` on a line of its own.
7989 Use `show palette gradient` to display the gradient.
7993 Read in a palette of RGB triples each in range [0,255]:
7994 set palette file 'some-palette' using ($1/255):($2/255):($3/255)
7996 Equidistant rainbow (blue-green-yellow-red) palette:
7997 set palette model RGB file "-"
8004 Binary palette files are supported as well, see `binary general`. Example:
8005 put 64 triplets of R,G,B doubles into file palette.bin and load it by
8006 set palette file "palette.bin" binary record=64 using 1:2:3
8010 ?commands set palette gamma-correction
8011 ?set palette gamma-correction
8012 ?palette gamma-correction
8014 For gray mappings gamma correction can be turned on by `set palette gamma
8015 <gamma>`. <gamma> defaults to 1.5 which is quite suitable for most
8018 For color mappings no automatic gamma correction is done by gnuplot. However,
8019 you may easily implement gamma correction. Here is an example for a gray
8020 scale image by use of explicit functions for the red, green and blue component
8021 with slightly different values of gamma
8024 set palette model RGB
8025 set palette functions gray**0.64, gray**0.67, gray**0.70
8027 To use gamma correction with interpolated gradients specify intermediate
8028 gray values with appropriate colors. Instead of
8030 set palette defined ( 0 0 0 0, 1 1 1 1 )
8034 set palette defined ( 0 0 0 0, 0.5 .73 .73 .73, 1 1 1 1 )
8036 or even more intermediate points until the linear interpolation fits the
8037 "gamma corrected" interpolation well enough.
8040 ?commands set palette postscript
8041 ?set palette postscript
8042 In order to reduce the size of postscript files, the gray value and not all
8043 three calculated r,g,b values are written to the file. Therefore the
8044 analytical formulae are coded directly in the postscript language as a header
8045 just before the pm3d drawing, see /g and /cF definitions. Usually, it makes
8046 sense to write therein definitions of only the 3 formulae used. But for
8047 multiplot or any other reason you may want to manually edit the
8048 transformations directly in the postscript file. This is the default option
8049 `nops_allcF`. Using the option `ps_allcF` writes postscript definitions of
8050 all formulae. This you may find interesting if you want to edit the
8051 postscript file in order to have different palettes for different surfaces
8052 in one graph. Well, you can achieve this functionality by `multiplot` with
8053 fixed `origin` and `size`.
8055 If pm3d map has been plotted from gridded or almost regular data with an
8056 output to a postscript file, then it is possible to reduce the size of this
8057 postscript file up to at about 50% by the enclosed awk script
8058 `pm3dCompress.awk`. This you may find interesting if you intend to keep the
8059 file for including it into your publication or before downloading a very large
8060 file into a slow printer. Usage:
8061 awk -f pm3dCompress.awk thefile.ps >smallerfile.ps
8063 If pm3d map has been plotted from rectangular gridded data with an output
8064 to a postscript file, then it is possible to reduce the file size even more
8065 by the enclosed awk script `pm3dConvertToImage.awk`. Usage:
8066 awk -f pm3dConvertToImage.awk <thefile.ps >smallerfile.ps
8068 You may manually change the postscript output from gray to color and vice
8069 versa and change the definition of <maxcolors>.
8072 ?show palette colornames
8074 Gnuplot knows a limited number of color names. You can use these to define
8075 the color range spanned by a pm3d palette, or to assign a terminal-independent
8076 color to a particular linetype or linestyle. To see the list of known color
8077 names, use the command `show palette colornames`.
8078 See `set palette`, `linestyle`.
8080 ?commands set pointsize
8081 ?commands show pointsize
8085 The `set pointsize` command scales the size of the points used in plots.
8088 set pointsize <multiplier>
8091 The default is a multiplier of 1.0. Larger pointsizes may be useful to
8092 make points more visible in bitmapped graphics.
8094 The pointsize of a single plot may be changed on the `plot` command.
8095 See `plot with` for details.
8097 Please note that the pointsize setting is not supported by all terminal
8101 ?commands unset polar
8102 ?commands show polar
8108 The `set polar` command changes the meaning of the plot from rectangular
8109 coordinates to polar coordinates.
8116 There have been changes made to polar mode in version 3.7, so that scripts
8117 for `gnuplot` versions 3.5 and earlier will require modification. The main
8118 change is that the dummy variable t is used for the angle so that the x and
8119 y ranges can be controlled independently. Other changes are:
8120 1) tics are no longer put along the zero axes automatically
8121 ---use `set xtics axis nomirror`; `set ytics axis nomirror`;
8122 2) the grid, if selected, is not automatically polar
8123 ---use `set grid polar`;
8124 3) the grid is not labelled with angles
8125 ---use `set label` as necessary.
8127 In polar coordinates, the dummy variable (t) is an angle. The default range
8128 of t is [0:2*pi], or, if degree units have been selected, to [0:360] (see
8131 The command `unset polar` changes the meaning of the plot back to the default
8132 rectangular coordinate system.
8134 The `set polar` command is not supported for `splot`s. See the `set mapping`
8135 command for similar functionality for `splot`s.
8137 While in polar coordinates the meaning of an expression in t is really
8138 r = f(t), where t is an angle of rotation. The trange controls the domain
8139 (the angle) of the function, and the x and y ranges control the range of the
8140 graph in the x and y directions. Each of these ranges, as well as the
8141 rrange, may be autoscaled or set explicitly. See `set xrange` for details
8142 of all the `ranges` commands.
8147 plot [-2*pi:2*pi] [-3:3] [-3:3] t*sin(t)
8149 The first `plot` uses the default polar angular domain of 0 to 2*pi. The
8150 radius and the size of the graph are scaled automatically. The second `plot`
8151 expands the domain, and restricts the size of the graph to [-3:3] in both
8154 You may want to `set size square` to have `gnuplot` try to make the aspect
8155 ratio equal to unity, so that circles look circular.
8157 ^ <a href="http://www.gnuplot.info/demo/polar.html">
8158 polar demos (polar.dem)
8161 ^ <a href="http://www.gnuplot.info/demo/poldat.html">
8162 polar data plot (poldat.dem).
8166 ?commands show print
8169 The `set print` command redirects the output of the `print` command to a file.
8174 set print "<filename>"
8175 set print "<filename>" append
8176 set print "|<shell_command>"
8178 Without "<filename>", the output file is restored to <STDERR>. The <filename>
8179 "-" means <STDOUT>. The `append` flag causes the file to be opened in append
8180 mode. A <filename> starting with "|" is opened as a pipe to the
8181 <shell_command> on platforms that support piping.
8185 ?commands set object
8186 ?commands show object
8187 ?commands set object rectangle
8188 ?commands show object rectangle
8191 ?set object rectangle
8192 ?show object rectangle
8193 This command defines a single object, which will appear in all subsequent
8194 2D plots. You may define as many objects as you like. Currently the only
8195 object type supported is `rectangle`.
8196 Each rectangle is specified by a pair of points that define diagonal vertices.
8197 A default set of style properties (fill, color, border) are inherited from
8198 those set by the command `set style rectangle`, but each rectangle can also be
8199 given individual style properties.
8202 set object <index> rectangle
8203 {from <position> {to|rto} <position> |
8204 center <position> size <w>,<h> |
8205 at <position> size <w>,<h>}
8206 {front|back|behind} {fc|fillcolor <colorspec>} {fs <fillstyle>}
8207 {default} {lw|linewidth <width>}
8209 The position of the rectangle may be specified by giving the position of two
8210 diagonal corners (bottom left and top right) or by giving the position of the
8211 center followed by the width and the height. In either case the positions
8212 may be given in axis, graph, or screen coordinates. See `coordinates`.
8213 The options `at` and `center` are synonyms.
8215 Setting `front` will draw the rectangle in front of all plot elements, but
8216 behind any labels that are also marked `front`. Setting `back` will place the
8217 rectangle behind all plot curves and labels. Setting `behind` will place the
8218 rectangle behind everything including the axes and `back` rectangles, and can
8219 be used to provide a colored background for the entire graph or page.
8221 The fill color of the rectangle is taken from the <colorspec>. `fillcolor`
8222 may be abbreviated `fc`. The fill style is taken from <fillstyle>.
8223 See `colorspec` and `fillstyle`. If the keyword `default` is given,
8224 these properties are inherited from the default settings of at the time a plot
8225 is drawn. See `set style rectangle`.
8228 # Force the entire area enclosed by the axes to have background color cyan
8229 set object 1 rect from graph 0, graph 0 to graph 1, graph 1 back
8230 set object 1 rect fc rgb "cyan" fillstyle solid 1.0
8232 # Position a red square with lower left at 0,0 and upper right at 2,3
8233 set object 2 rect from 0,0 to 2,3 fc lt 1
8235 # Position an empty rectangle (no fill) with a blue border
8236 set object 3 rect from 0,0 to 2,3 fs empty border 3
8238 # Return fill and color to the default style but leave vertices unchanged
8239 set object 2 rect default
8242 ?commands set rmargin
8245 The command `set rmargin` sets the size of the right margin.
8246 Please see `set margin` for details.
8248 ?commands set rrange
8249 ?commands show rrange
8253 The `set rrange` command sets the range of the radial coordinate for a
8254 graph in polar mode. Please see `set xrange` for details.
8256 ?commands set samples
8257 ?commands show samples
8261 The sampling rate of functions, or for interpolating data, may be changed
8262 by the `set samples` command.
8265 set samples <samples_1> {,<samples_2>}
8268 By default, sampling is set to 100 points. A higher sampling rate will
8269 produce more accurate plots, but will take longer. This parameter has no
8270 effect on data file plotting unless one of the interpolation/approximation
8271 options is used. See `plot smooth` re 2-d data and `set cntrparam` and
8272 `set dgrid3d` re 3-d data.
8274 When a 2-d graph is being done, only the value of <samples_1> is relevant.
8276 When a surface plot is being done without the removal of hidden lines, the
8277 value of samples specifies the number of samples that are to be evaluated for
8278 the isolines. Each iso-v line will have <sample_1> samples and each iso-u
8279 line will have <sample_2> samples. If you only specify <samples_1>,
8280 <samples_2> will be set to the same value as <samples_1>. See also
8290 set size {{no}square | ratio <r> | noratio} {<xscale>,<yscale>}
8293 The <xscale> and <yscale> values are scale factors for the size of the plot,
8294 which includes the graph, labels, and margins.
8297 In earlier versions of gnuplot, some terminal types used the values from
8298 `set size` to control also the size of the output canvas; others did not.
8299 In version 4.2 almost all terminals now follow the following convention:
8301 `set term <terminal_type> size <XX>, <YY>` controls the size of the output
8302 file, or `canvas`. Please see individual terminal documentation for allowed
8303 values of the size parameters. By default, the plot will fill this canvas.
8305 `set size <XX>, <YY>` scales the plot itself relative to the size of the
8306 canvas. Scale values less than 1 will cause the plot to not fill the entire
8307 canvas. Scale values larger than 1 will cause only a portion of the plot to
8308 fit on the canvas. Please be aware that setting scale values larger than 1
8309 may cause problems on some terminal types.
8311 `ratio` causes `gnuplot` to try to create a graph with an aspect ratio of <r>
8312 (the ratio of the y-axis length to the x-axis length) within the portion of
8313 the plot specified by <xscale> and <yscale>.
8315 The meaning of a negative value for <r> is different. If <r>=-1, gnuplot
8316 tries to set the scales so that the unit has the same length on both the x
8317 and y axes (suitable for geographical data, for instance). If <r>=-2, the
8318 unit on y has twice the length of the unit on x, and so on.
8320 The success of `gnuplot` in producing the requested aspect ratio depends on
8321 the terminal selected. The graph area will be the largest rectangle of
8322 aspect ratio <r> that will fit into the specified portion of the output
8323 (leaving adequate margins, of course).
8325 `square` is a synonym for `ratio 1`.
8327 Both `noratio` and `nosquare` return the graph to the default aspect ratio
8328 of the terminal, but do not return <xscale> or <yscale> to their default
8331 `ratio` and `square` have no effect on 3-d plots, but do affect 3D projections
8332 created using `set view map`. Similarly `set view equal` forces the
8333 x and y axes of a 3D onto the same scale.
8337 To set the size so that the plot fills the available canvas:
8340 To make the graph half size and square use:
8341 set size square 0.5,0.5
8343 To make the graph twice as high as wide use:
8347 ^ <a href="http://www.gnuplot.info/demo/airfoil.html">
8354 ^ <a name="set style <style>"></a>
8355 Default plotting styles are chosen with the `set style data` and
8356 `set style function` commands. See `plot with` for information about how to
8357 override the default plotting style for individual functions and data sets.
8358 See `plotting styles` for a complete list of styles.
8361 set style function <style>
8362 set style data <style>
8366 Default styles for specific plotting elements may also be set.
8369 set style arrow <n> <arrowstyle>
8370 set style fill <fillstyle>
8371 set style histogram <histogram style options>
8372 set style line <n> <linestyle>
8375 ?commands set style arrow
8376 ?commands unset style arrow
8377 ?commands show style arrow
8382 ^ <a name="arrowtype"></a>
8383 ^ <a name="arrowwidth"></a>
8384 Each terminal has a default set of arrow and point types, which can be seen
8385 by using the command `test`. `set style arrow` defines a set of arrow types
8386 and widths and point types and sizes so that you can refer to them later by
8387 an index instead of repeating all the information at each invocation.
8390 set style arrow <index> default
8391 set style arrow <index> {nohead | head | heads}
8392 {size <length>,<angle>{,<backangle>}}
8393 {filled | empty | nofilled}
8395 { {linestyle | ls <line_style>}
8396 | {linetype | lt <line_type>}
8397 {linewidth | lw <line_width} }
8401 <index> is an integer that identifies the arrowstyle.
8403 If `default` is given all arrow style parameters are set to their default
8406 If the linestyle <index> already exists, only the given parameters are
8407 changed while all others are preserved. If not, all undefined values are
8408 set to the default values.
8410 Specifying `nohead` produces arrows drawn without a head---a line segment.
8411 This gives you yet another way to draw a line segment on the plot. By
8412 default, arrows have one head. Specifying `heads` draws arrow heads on both
8415 Head size can be controlled by `size <length>,<angle>` or
8416 `size <length>,<angle>,<backangle>`, where `<length>` defines length of each
8417 branch of the arrow head and `<angle>` the angle (in degrees) they make with
8418 the arrow. `<Length>` is in x-axis units; this can be changed by `first`,
8419 `second`, `graph`, `screen`, or `character` before the <length>; see
8420 `coordinates` for details. `<Backangle>` only takes effect when `filled`
8421 or `empty` is also used. Then, `<backangle>` is the angle (in degrees) the
8422 back branches make with the arrow (in the same direction as `<angle>`).
8423 The `fig` terminal has a restricted backangle function. It supports three
8424 different angles. There are two thresholds: Below 70 degrees, the arrow head
8425 gets an indented back angle. Above 110 degrees, the arrow head has an acute
8426 back angle. Between these thresholds, the back line is straight.
8428 Specifying `filled` produces filled arrow heads (if heads are used).
8429 Filling is supported on filled-polygon capable terminals, see help of `pm3d`
8430 for their list, otherwise the arrow heads are closed but not filled.
8431 The same result (closed but not filled arrow head) is reached by specifying
8432 `empty`. Further, filling and outline is obviously not supported on
8433 terminals drawing arrows by their own specific routines, like `metafont`,
8434 `metapost`, `latex` or `tgif`.
8436 The line style may be selected from a user-defined list of line styles
8437 (see `set style line`) or may be defined here by providing values for
8438 `<line_type>` (an index from the default list of styles) and/or
8439 `<line_width>` (which is a multiplier for the default width).
8441 Note, however, that if a user-defined line style has been selected, its
8442 properties (type and width) cannot be altered merely by issuing another
8443 `set style arrow` command with the appropriate index and `lt` or `lw`.
8445 If `front` is given, the arrows are written on top of the graphed data. If
8446 `back` is given (the default), the arrow is written underneath the graphed
8447 data. Using `front` will prevent a arrow from being obscured by dense data.
8451 To draw an arrow without an arrow head and double width, use:
8452 set style arrow 1 nohead lw 2
8453 set arrow arrowstyle 1
8455 See also `set arrow` for further examples.
8458 ?commands set style data
8459 ?commands show style data
8463 The `set style data` command changes the default plotting style for data
8467 set style data <plotting-style>
8470 See `plotting styles` for the choices. If no choice is given, the choices are
8471 listed. `show style data` shows the current default data plotting style.
8473 ?commands set style fill
8474 ?commands show style fill
8478 The `set style fill` command is used to set the style of boxes,
8479 histograms, candlesticks and filledcurves.
8482 set style fill {empty | solid {<density>} | pattern {<n>}}
8483 {border {<linetype>} | noborder}
8485 The default fillstyle is `empty`.
8487 The `solid` option causes filling with a solid color, if the terminal
8488 supports that. The <density> parameter specifies the intensity of the
8489 fill color. At a <density> of 0.0, the box is empty, at <density> of 1.0,
8490 the inner area is of the same color as the current linetype.
8491 Some terminal types can vary the density continuously; others implement
8492 only a few levels of partial fill. If no <density> parameter is given,
8495 The `pattern` option causes filling to be done with a fill pattern supplied
8496 by the terminal driver. The kind and number of available fill patterns
8497 depend on the terminal driver. If multiple datasets using filled boxes are
8498 plotted, the pattern cycles through all available pattern types, starting
8499 from pattern <n>, much as the line type cycles for multiple line plots.
8501 The `empty` option causes filled boxes not to be filled. This is the default.
8503 By default, `border`, the box is bounded by a solid line of the current
8504 linetype. `border <lt>` specifies that a border is to be drawn using
8505 linetype <lt>. `noborder` specifies that no bounding lines are drawn.
8506 4 set style function
8507 ?commands set style function
8508 ?commands show style function
8510 ?show style function
8512 The `set style function` command changes the default plotting style for
8516 set style function <plotting-style>
8519 See `plotting styles` for the choices. If no choice is given, the choices are
8520 listed. `show style function` shows the current default function plotting
8522 4 set style increment
8523 ?commands set style increment
8524 ?commands show style increment
8525 ?set style increment
8526 ?show style increment
8528 set style increment {default|userstyles}
8529 show style increment
8531 By default, successive plots within the same graph will use successive
8532 linetypes from the default set for the current terminal type.
8533 However, choosing `set style increment user` allows you to step through
8534 the user-defined line styles rather than through the default linetypes.
8538 set style line 1 lw 2 lc rgb "gold"
8539 set style line 2 lw 2 lc rgb "purple"
8540 set style line 4 lw 1 lc rgb "sea-green"
8541 set style increment user
8543 plot f1(x), f2(x), f3(x), f4(x)
8545 should plot functions f1, f2, f4 in your 3 newly defined line styles.
8546 If a user-defined line style is not found then the corresponding default
8547 linetype is used instead. E.g. in the example above, f3(x) will be plotted
8548 using the default linetype 3.
8551 ?commands set style line
8552 ?commands unset style line
8553 ?commands show style line
8559 Each terminal has a default set of line and point types, which can be seen
8560 by using the command `test`. `set style line` defines a set of line types
8561 and widths and point types and sizes so that you can refer to them later by
8562 an index instead of repeating all the information at each invocation.
8565 set style line <index> default
8566 set style line <index> {{linetype | lt} <line_type> | <colorspec>}
8567 {{linecolor | lc} <colorspec>}
8568 {{linewidth | lw} <line_width>}
8569 {{pointtype | pt} <point_type>}
8570 {{pointsize | ps} <point_size>}
8575 If `default` is given all line style parameters are set to their default
8578 If the linestyle <index> already exists, only the given parameters are
8579 changed while all others are preserved. If not, all undefined values are
8580 set to the default values.
8582 The line and point types are taken from the default types for the terminal
8583 currently in use. The line width and point size are multipliers for the
8584 default width and size (but note that <point_size> here is unaffected by
8585 the multiplier given on `set pointsize`).
8587 The defaults for the line and point types is the index. The defaults for
8588 the width and size are both unity.
8590 Linestyles created by this mechanism do not replace the default linetype
8591 styles; both may be used. If you want plots to use the defined styles in
8592 preference to the default linetypes, please see `set style increment`.
8594 Not all terminals support the `linewidth` and `pointsize` features; if
8595 not supported, the option will be ignored.
8597 Terminal-independent colors may be assigned using either
8598 `linecolor <colorspec>` or `linetype <colorspec>`, abbreviated `lc` or `lt`.
8599 This requires giving a RGB color triple, a known palette color name,
8600 a fractional index into the current palette, or a constant value from the
8601 current mapping of the palette onto cbrange.
8602 See `colors`, `colorspec`, `set palette`, `colornames`, `cbrange`.
8604 `set style line <n> linetype <lt>` will set both a terminal-dependent dot/dash
8605 pattern and color. The commands`set style line <n> linecolor <colorspec>` or
8606 `set style line <n> linetype <colorspec>` will set a new line color while
8607 leaving the existing dot-dash pattern unchanged.
8609 In 3d mode (`splot` command), the special keyword `palette` is allowed as a
8610 shorthand for "linetype palette z". The color value corresponds to the
8611 z-value (elevation) of the splot, and varies smoothly along a line or surface.
8614 Suppose that the default lines for indices 1, 2, and 3 are red, green, and
8615 blue, respectively, and the default point shapes for the same indices are a
8616 square, a cross, and a triangle, respectively. Then
8618 set style line 1 lt 2 lw 2 pt 3 ps 0.5
8620 defines a new linestyle that is green and twice the default width and a new
8621 pointstyle that is a half-sized triangle. The commands
8623 set style function lines
8624 plot f(x) lt 3, g(x) ls 1
8626 will create a plot of f(x) using the default blue line and a plot of g(x)
8627 using the user-defined wide green line. Similarly the commands
8629 set style function linespoints
8630 plot p(x) lt 1 pt 3, q(x) ls 1
8632 will create a plot of p(x) using the default triangles connected by a red
8633 line and q(x) using small triangles connected by a green line.
8635 splot sin(sqrt(x*x+y*y))/sqrt(x*x+y*y) w l pal
8637 creates a surface plot using smooth colors according to `palette`. Note,
8638 that this works only on some terminals. See also `set palette`, `set pm3d`.
8640 set style line 10 linetype 1 linecolor rgb "cyan"
8642 will assign linestyle 10 to be a solid cyan line on any terminal that
8643 supports rgb colors.
8648 The commands `set style data` and `set style function` change the
8649 default plotting style for subsequent `plot` and `splot` commands.
8651 The types used for all line and point styles (i.e., solid, dash-dot, color,
8652 etc. for lines; circles, squares, crosses, etc. for points) will be either
8653 those specified on the `plot` or `splot` command or will be chosen
8654 sequentially from the types available to the terminal in use. Use the
8655 command `test` to see what is available.
8657 None of the styles requiring more than two columns of information
8658 (e.g., `errorbars` or `errorlines`) can be used with `splot`s or
8659 function `plot`s. Neither `boxes`, `filledcurves` nor any
8660 of the `steps` styles can be used with `splot`s. If an inappropriate style
8661 is specified, it will be changed to `points`.
8663 The above caveat does not apply to `plot with labels`, for which the third
8664 column specifies a data source rather than coordinate information.
8665 See `set style labels`.
8667 For 2-d data with more than two columns, `gnuplot` is picky about the
8668 allowed `errorbars` and `errorlines` styles. The `using` option on the
8669 `plot` command can be used to set up the correct columns for the style
8670 you want. (In this discussion, "column" will be used to refer both to
8671 a column in the data file and an entry in the `using` list.)
8673 For three columns, only `xerrorbars`, `yerrorbars` (or `errorbars`),
8674 `xerrorlines`, `yerrorlines` (or `errorlines`), `boxes`,
8675 and `boxerrorbars` are allowed. If another plot style is used, the style
8676 will be changed to `yerrorbars`. The `boxerrorbars` style will
8677 calculate the boxwidth automatically.
8679 For four columns, only `xerrorbars`, `yerrorbars` (or `errorbars`),
8680 `xyerrorbars`, `xerrorlines`, `yerrorlines` (or `errorlines`), `xyerrorlines`,
8681 `boxxyerrorbars`, and `boxerrorbars` are allowed. An illegal
8682 style will be changed to `yerrorbars`.
8684 Five-column data allow only the `boxerrorbars`, `financebars`, and
8685 `candlesticks` styles. An illegal style will be changed to `boxerrorbars`
8688 Six- and seven-column data only allow the `xyerrorbars`,
8689 `xyerrorlines`, and `boxxyerrorbars` styles. Illegal styles will be
8690 changed to `xyerrorbars` before plotting.
8692 For more information about error bars with and without lines,
8693 please see `plot errorlines` and `plot errorbars`.
8695 4 set style rectangle
8696 ?commands set style rectangle
8697 ?commands unset style rectangle
8698 ?commands show style rectangle
8699 ?set style rectangle
8700 ?unset style rectangle
8701 ?show style rectangle
8703 Rectangles defined with the `set object rectangle` command can have individual
8704 styles. However, if a rectangle is not assigned a private style then it
8705 inherits a default that is taken from the `set style rectangle` command.
8708 set style rectangle {front|back} {fillcolor <colorspec>} {fs <fillstyle>}
8711 See `colorspec` and `fillstyle`. `fillcolor` may be abbreviated as `fc`.
8714 set style rectangle back fc rgb "white" fs solid 1.0 border -1
8715 set style rectangle fc linsestyle 3 fs pattern 2 noborder
8717 The default values correspond to solid fill with the background color and a
8721 ?commands set style boxerrorbars
8722 ?set style boxerrorbars
8723 ?plotting styles boxerrorbars
8726 The `boxerrorbars` style is only relevant to 2-d data plotting. It is a
8727 combination of the `boxes` and `yerrorbars` styles. The boxwidth will come
8728 from the fourth column if the y errors are in the form of "ydelta" and the
8729 boxwidth was not previously set equal to -2.0 (`set boxwidth -2.0`) or from
8730 the fifth column if the y errors are in the form of "ylow yhigh". The
8731 special case `boxwidth = -2.0` is for four-column data with y errors in the
8732 form "ylow yhigh". In this case the boxwidth will be calculated so that each
8733 box touches the adjacent boxes. The width will also be calculated in cases
8734 where three-column data are used.
8736 The box height is determined from the y error in the same way as it is for
8737 the `yerrorbars` style---either from y-ydelta to y+ydelta or from ylow to
8738 yhigh, depending on how many data columns are provided.
8740 ^ <a href="http://www.gnuplot.info/demo/mgr.html">
8744 ?commands set style boxes
8746 ?plotting styles boxes
8749 The `boxes` style is only relevant to 2-d plotting. It draws a box centered
8750 about the given x coordinate from the x axis (not the graph border) to the
8751 given y coordinate. The width of the box is obtained in one of three ways.
8752 If it is a data plot and the data file has a third column, this will be used
8753 to set the width of the box. If not, if a width has been set using the `set
8754 boxwidth` command, this will be used. If neither of these is available, the
8755 width of each box will be calculated automatically so that it touches the
8758 The interior of the boxes is drawn according to the current fillstyle.
8759 See `set style fill` for details. Alternatively a new fillstyle
8760 may be specified in the plot command.
8762 For fillstyle `empty` the box is filled with the background color.
8764 For fillstyle `solid` the box is filled with a solid rectangle of the
8765 current drawing color. There is an optional parameter <density> that
8766 controls the fill density; it runs from 0 (background color) to 1
8767 (current drawing color).
8769 For fillstyle `pattern` the box is filled in the current drawing color with
8770 a pattern, if supported by the terminal driver.
8774 To plot a data file with solid filled boxes with a small vertical space
8775 separating them (bargraph):
8777 set boxwidth 0.9 relative
8778 set style fill solid 1.0
8779 plot 'file.dat' with boxes
8781 To plot a sine and a cosine curve in pattern-filled boxes style:
8783 set style fill pattern
8784 plot sin(x) with boxes, cos(x) with boxes
8786 The sin plot will use pattern 0; the cos plot will use pattern 1.
8787 Any additional plots would cycle through the patterns supported by the
8790 To specify explicit fillstyles for each dataset:
8792 plot 'file1' with boxes fs solid 0.25, \
8793 'file2' with boxes fs solid 0.50, \
8794 'file3' with boxes fs solid 0.75, \
8795 'file4' with boxes fill pattern 1, \
8796 'file5' with boxes fill empty
8798 Currently only the following terminal drivers support fillstyles other
8800 x11, windows, pm, wxt, postscript, fig, pbm, png, gif, hpdj, hppj, hpljii,
8801 hp500c, jpeg, nec_cp6, epson_180dpi, epson_60dpi, epson_lx800, okidata, starc
8802 and tandy_60dpi. The BeOS driver (`be`) is untested.
8804 ?commands set style boxxyerrorbars
8805 ?set style boxxyerrorbars
8806 ?plotting styles boxxyerrorbars
8807 ?style boxxyerrorbars
8809 The `boxxyerrorbars` style is only relevant to 2-d data plotting. It is a
8810 combination of the `boxes` and `xyerrorbars` styles.
8812 The box width and height are determined from the x and y errors in the same
8813 way as they are for the `xyerrorbars` style---either from xlow to xhigh and
8814 from ylow to yhigh, or from x-xdelta to x+xdelta and from y-ydelta to
8815 y+ydelta , depending on how many data columns are provided.
8817 If filled-box support is present, then the interior of the boxes is drawn
8818 according to the current fillstyle. See `set style fill` and `boxes` for
8819 details. Alternatively a new fillstyle may be specified in the plot command.
8821 ?commands set style candlesticks
8822 ?set style candlesticks
8823 ?plotting styles candlesticks
8826 The `candlesticks` style can be used for 2-d data plotting of financial
8827 data or for generating box-and-whisker plots of statistical data.
8828 Five columns of data are required; in order, these should be the x
8829 coordinate (most likely a date) and the opening, low, high, and closing
8830 prices. The symbol is a rectangular box, centered horizontally at the x
8831 coordinate and limited vertically by the opening and closing prices. A
8832 vertical line segment at the x coordinate extends up from the top of the
8833 rectangle to the high price and another down to the low. The vertical line
8834 will be unchanged if the low and high prices are interchanged.
8836 The width of the rectangle can be controlled by the `set boxwidth` command.
8837 For backwards compatibility with earlier gnuplot versions, when the
8838 boxwidth parameter has not been set then the width of the candlestick
8839 rectangle is controlled by `set bars <width>`.
8841 By default the vertical line segments have no crossbars at the top and
8842 bottom. If you want crossbars, which are typically used for box-and-whisker
8843 plots, then add the keyword `whiskerbars` to the plot command. By default
8844 these whiskerbars extend the full horizontal width of the candlestick, but
8845 you can modify this by specifying a fraction of the full width.
8847 By default the rectangle is empty if (open < close), and filled with three
8848 vertical bars if (close < open). If filled-boxes support is present, then
8849 the rectangle is colored according to `set style fill <fillstyle>`.
8850 See `set bars` and `financebars`. See also
8851 ^ <a href="http://gnuplot.sourceforge.net/demo/candlesticks.html">
8856 Note: To place additional symbols, such as the median value, on a
8857 box-and-whisker plot requires additional plot commands as in this example:
8859 # Data columns: X Min 1stQuartile Median 3rdQuartile Max
8861 set style fill empty
8862 plot 'stat.dat' using 1:3:2:6:5 with candlesticks title 'Quartiles', \
8863 '' using 1:4:4:4:4 with candlesticks lt -1 notitle
8865 # Plot with crossbars on the whiskers, crossbars are 50% of full width
8866 plot 'stat.dat' using 1:3:2:6:5 with candlesticks whiskerbars 0.5
8868 See `set boxwidth`, `set bars` and `set style fill`.
8870 ?commands set style dots
8872 ?plotting styles dots
8875 The `dots` style plots a tiny dot at each point; this is useful for scatter
8876 plots with many points. For some terminals (post, pdf) the size of the dot can
8877 be controlled by changing the linewidth.
8879 ?commands set style filledcurves
8880 ?set style filledcurves
8881 ?plotting styles filledcurves
8884 The `filledcurves` style is only relevant to 2-d plotting. Three variants
8885 are possible. The first two variants require either a function or two columns
8886 of input data, and may be further modified by the options listed below.
8887 The first variant, `closed`, treats the curve itself as a closed polygon.
8888 This is the default if there are two columns of input data.
8890 The second variant is to fill the area between the curve and a given axis,
8891 a horizontal or vertical line, or a point.
8893 The third variant requires three columns of input data: the x coordinate and
8894 two y coordinates corresponding to two curves sampled at the same set of
8895 x coordinates; the area between the two curves is filled.
8896 This is the default if there are three or more columns of input data.
8900 set style [data | function] filledcurves [option]
8901 plot ... with filledcurves [option]
8903 where the option can be
8905 [closed | {above | below} {x1 | x2 | y1 | y2}[=<a>] | xy=<x>,<y>]
8907 The first two plot variants can be further modified by the options
8909 filledcurves closed ... just filled closed curve,
8910 filledcurves x1 ... x1 axis,
8911 filledcurves x2 ... x2 axis, etc for y1 and y2 axes,
8912 filledcurves y1=0 ... line y=0 (at y1 axis) ie parallel to x1 axis,
8913 filledcurves y2=42 ... line y=42 (at y2 axis) ie parallel to x2, etc,
8914 filledcurves xy=10,20 ... point 10,20 of x1,y1 axes (arc-like shape).
8916 Example of filling the area between two input curves.
8917 ^ <a href="http://www.gnuplot.info/demo/fillbetween.html">
8918 fill between curves demo.
8921 plot 'data' using 1:2:3 with filledcurves
8923 The `above` and `below` options apply both to commands of the form
8924 ... filledcurves above {x1|x2|y1|y2}=<val>
8925 and to commands of the form
8926 ... using 1:2:3 with filledcurves below
8927 In either case the option limits the filled area to one side of the bounding
8930 Note: Not all terminal types support this plotting mode.
8932 Zoom of a filled curve drawn from a datafile may produce empty or incorrect
8933 area because gnuplot is clipping points and lines, and not areas.
8935 If the values of <a>, <x>, <y> are out of the drawing boundary, then they
8936 are moved to the graph boundary. Then the actually filled area in the case
8937 of option xy=<x>,<y> will depend on xrange and yrange.
8939 ?commands set style financebars
8940 ?set style financebars
8941 ?plotting styles financebars
8944 The `financebars` style is only relevant for 2-d data plotting of financial
8945 data. Five columns of data are required; in order, these should be the x
8946 coordinate (most likely a date) and the opening, low, high, and closing
8947 prices. The symbol is a vertical line segment, located horizontally at the x
8948 coordinate and limited vertically by the high and low prices. A horizontal
8949 tic on the left marks the opening price and one on the right marks the
8950 closing price. The length of these tics may be changed by `set bars`. The
8951 symbol will be unchanged if the high and low prices are interchanged.
8952 See `set bars` and `candlesticks`, and also the
8953 ^ <a href="http://www.gnuplot.info/demo/finance.html">
8957 ?commands set style fsteps
8959 ?plotting styles fsteps
8962 The `fsteps` style is only relevant to 2-d plotting. It connects consecutive
8963 points with two line segments: the first from (x1,y1) to (x1,y2) and the
8964 second from (x1,y2) to (x2,y2).
8966 ^ <a href="http://www.gnuplot.info/demo/steps.html">
8970 ?commands set style histeps
8972 ?plotting styles histeps
8975 The `histeps` style is only relevant to 2-d plotting. It is intended for
8976 plotting histograms. Y-values are assumed to be centered at the x-values;
8977 the point at x1 is represented as a horizontal line from ((x0+x1)/2,y1) to
8978 ((x1+x2)/2,y1). The lines representing the end points are extended so that
8979 the step is centered on at x. Adjacent points are connected by a vertical
8980 line at their average x, that is, from ((x1+x2)/2,y1) to ((x1+x2)/2,y2).
8982 If `autoscale` is in effect, it selects the xrange from the data rather than
8983 the steps, so the end points will appear only half as wide as the others.
8985 ^ <a href="http://www.gnuplot.info/demo/steps.html">
8989 `histeps` is only a plotting style; `gnuplot` does not have the ability to
8990 create bins and determine their population from some data set.
8992 ?commands set style histogram
8993 ?set style histogram
8995 ?plotting styles histograms
8997 The `histograms` style is only relevant to 2-d plotting. It produces a bar
8998 chart from a sequence of data columns in parallel. Each element of the
8999 `plot` command must specify a single input data source (e.g. one column of
9000 the input file), possibly with associated tic values or key titles.
9001 Four styles of histogram layout are currently supported.
9003 set style histogram clustered {gap <gapsize>}
9004 set style histogram errorbars {gap <gapsize>} {<linewidth>}
9005 set style histogram rowstacked
9006 set style histogram columnstacked
9008 The default style corresponds to `set style histogram clustered gap 2`.
9009 In this style, each set of parallel data values is collected into a group of
9010 boxes clustered at the x-axis coordinate corresponding to their sequential
9011 position (row #) in the selected datafile columns. Thus if <n> datacolumns are
9012 selected, the first cluster is centered about x=1, and contains <n> boxes whose
9013 heights are taken from the first entry in the corresponding <n> data columns.
9014 This is followed by a gap and then a second cluster of boxes centered about x=2
9015 corresponding to the second entry in the respective data columns, and so on.
9016 The default gap width of 2 indicates that the empty space between clusters is
9017 equivalent to the width of 2 boxes. All boxes derived from any one column
9018 are given the same fill color and/or pattern (see `set style fill`).
9020 Each cluster of boxes is derived from a single row of the input data file.
9021 It is common in such input files that the first element of each row is a
9022 label. Labels from this column may be placed along the x-axis underneath
9023 the appropriate cluster of boxes with the `xticlabels` option to `using`.
9025 The `errorbars` style is very similar to the `clustered` style, except that
9026 it requires two columns of input for each entry. The first column is treated
9027 as the height (y-value) of that box, exactly as for the `clustered` style.
9028 The second column is treated as an error magnitude, and used to generate a
9029 vertical error bar at the top of the box. The appearance of the error bar is
9030 controlled by the current value of `set bars` and by the optional <linewidth>
9033 Two styles of stacked histogram are supported, chosen by the command
9034 `set style histogram {rowstacked|columnstacked}`. In these styles the data
9035 values from the selected columns are collected into stacks of boxes.
9036 Positive values stack upwards from y=0; negative values stack downwards.
9037 Mixed positive and negative values will produce both an upward stack and a
9038 downward stack. The default stacking mode is `rowstacked`.
9040 The `rowstacked` style places a box resting on the x-axis for each
9041 data value in the first selected column; the first data value results in
9042 a box a x=1, the second at x=2, and so on. Boxes corresponding to the
9043 second and subsequent data columns are layered on top of these, resulting
9044 in a stack of boxes at x=1 representing the first data value from each
9045 column, a stack of boxes at x=2 representing the second data value from
9046 each column, and so on. All boxes derived from any one column are given the
9047 same fill color and/or pattern (see `set style fill`).
9049 The `columnstacked` style is similar, except that each stack of boxes is
9050 built up from a single data column. Each data value from the first specified
9051 column yields a box in the stack at x=1, each data value from the second
9052 specified column yields a box in the stack at x=2, and so on. In this style
9053 the color of each box is taken from the row number, rather than the column
9054 number, of the corresponding data field.
9056 Box widths may be modified using the `set boxwidth` command.
9057 Box fill styles may be set using the `set style fill` command.
9059 Histograms always use the x1 axis, but may use either y1 or y2.
9060 If a plot contains both histograms and other plot styles, the non-histogram
9061 plot elements may use either the x1 or the x2 axis.
9065 To plot a data file containing multiple columns of data as a histogram
9066 of clustered boxes (the default style):
9068 set boxwidth 0.9 relative
9069 set style data histograms
9070 set style fill solid 1.0 border -1
9071 plot 'file.dat' using 2, '' using 4, '' using 6
9073 This will produce a plot with clusters of three boxes (vertical bars) centered
9074 at each integral value on the x axis. If the first column of the input file
9075 contains labels, they may be placed along the x-axis using the variant command
9077 plot 'file.dat' using 2, '' using 4, '' using 6:xticlabels(1)
9079 If the file contains both a magnitude and an error estimate for each value,
9080 then error bars can be added to the plot. The following commands will add
9081 error bars extending from (y-<error>) to (y+<error>), capped by horizontal bar
9082 ends drawn the same width as the box itself. The error bars and bar ends are
9083 drawn with linewidth 2 using the border linetype from the current fill style.
9086 set style fill solid border -1
9087 set style histogram errorbars gap 2 lw 2
9088 plot 'file.dat' using 2:3, '' using 4:5, '' using 6:7:xticlabels(1)
9090 To plot the same data as a rowstacked histogram:
9092 set style histogram rows
9093 plot 'file.dat' using 2, '' using 4, '' using 6:xtic(1)
9095 This will produce a plot in which each vertical bar contains a stack of three
9096 segments, corresponding in height to the values found in columns 2, 4 and 6
9099 Finally, the commands
9101 set style histogram columnstacked
9102 plot 'file.dat' using 2, '' using 4, '' using 6
9104 will produce three vertical stacks. The stack at x=1 will contain a box for
9105 each entry in column 2 of the datafile. The stack at x=2 will contain a box
9106 for each parallel entry in column 4 of the datafile, and the stack at x=3 a
9107 box for each entry of column 6. Because this interchanges gnuplot's usual
9108 interpretation of input rows and columns, the specification of key titles and
9109 x-axis tic labels must also be modified.
9111 set style histogram columnstacked
9112 plot '' u 5:key(1) # uses first column to generate key titles
9113 plot '' u 5 title columnhead # uses first row to generate xtic labels
9116 ?histograms newhistogram
9117 More than one set of histograms can appear in a single plot. In this case you
9118 can force a gap between them, and a separate label for each set, by using the
9119 plot command `newhistogram {"<title>"} {<linetype>} {at <x-coord>}`.
9122 set style histogram cluster
9123 plot newhistogram "Set A", 'a' using 1, '' using 2, '' using 3, \
9124 newhistogram "Set B", 'b' using 1, '' using 2, '' using 3
9126 The labels "Set A" and "Set B" will appear beneath the respective sets of
9127 histograms, under the overall x axis label.
9129 The newhistogram command can also be used to force histogram coloring to
9130 begin with a specific color (linetype). By default colors will continue to
9131 increment successively even across histogram boundaries. Here is an example
9132 using the same coloring for multiple histograms
9133 plot newhistogram "Set A" lt 4, 'a' using 1, '' using 2, '' using 3, \
9134 newhistogram "Set B" lt 4, 'b' using 1, '' using 2, '' using 3
9136 The `at <x-coord>` option only applies to column-stacked histograms.
9138 ?commands set style image
9140 ?plotting styles image
9143 The `image` style is intendend for plotting 2D images. It may be used for
9144 both `plot` and `splot` in the form of 3D data (x,y,value) or projected 4D
9145 data (x,y,z,value), respectively. It is assumed that in the viewing plane
9146 the image data forms an equidistant sampling grid in the viewing plane along
9147 two, not necessarily orthogonal, directions. In other words, groups of
9148 four adjacent points are assumed to form the same size parallelogram. The
9149 variable `value` in the tuples represent a palette color (gray value) for
9150 indexing in the current palette.
9152 The `image` style will attempt to create a properly positioned and scaled
9153 data matrix to match the plot borders for those terminals supporting palettes
9154 and images. Such output is efficient and draws quickly. However, when a
9155 terminal driver does not support palettes and images, or when image support
9156 is not implemented, the `image` style reverts to drawing filled rectangular
9157 boxes for pixels, which is not as efficient. General parallelogram-shaped
9158 images currently always have filled parallelograms for pixels.
9160 The coordinate of each data point of an image will lie at the center of a
9161 pixel. That is, an M x N set of data will form an image with M x N pixels.
9162 This is slightly different than pm3d elements where an M x N set of data
9163 will form a surface of (M-1) x (N-1) elements. The scan directions for the
9164 image data grid can be any of eight possible combinations.
9166 Here are some specific comments about particular terminal drivers:
9168 x11 and wxt - Pixels are either repeated or decimated to fit the display
9169 resolution; no other processing (filtering) is done. Thus, aliasing may
9170 occur when decimating images having high spatial frequency content.
9172 postscript (pslatex, epslatex, pstex) - Image is copied in its original
9173 resolution, and sample interpolation is turned off.
9175 See also `rgbimage`.
9177 ?commands set style impulses
9179 ?plotting styles impulses
9182 The `impulses` style displays a vertical line from the x axis (not the graph
9183 border), or from the grid base for `splot`, to each point.
9185 ?commands set style labels
9187 ?plotting styles labels
9190 The `labels` style is available only if gnuplot is built with configuration
9191 option --enable-datastrings. For a 2-D plot with labels you must specify
9192 3 input data columns; the text string found in the third column is printed at
9193 the X and Y coordinates generated by the first two column specifiers. The
9194 font, color, rotation angle and other properties of the printed text may be
9195 specified as additional command options (see `set label`). The example below
9196 will generate a 2-D plot with text labels taken from column 4 of the input
9197 file (`tc lt 2` is shorthand for `textcolor linetype 2`, which is green).
9199 plot 'datafile' using 1:(0.5 * $2):4 with labels font "arial,11" tc lt 2
9201 The `labels` style can also be used in 3-D plots. In this case four input
9202 column specifiers are required, corresponding to X Y Z and text.
9204 splot 'datafile' using 1:2:3:4 with labels
9206 See also `datastrings`, `set style data`.
9208 ?commands set style lines
9210 ?plotting styles lines
9213 The `lines` style connects adjacent points with straight line segments.
9214 See also `linetype`, `linewidth`, and `linestyle`.
9216 ?commands set style linespoints
9217 ?commands set style lp
9218 ?set style linespoints
9219 ?plotting styles linespoints
9225 The `linespoints` style does both `lines` and `points`, that is, it draws a
9226 small symbol at each point and then connects adjacent points with straight
9227 line segments. The command `set pointsize` may be used to change the size of
9228 the points. See `set pointsize` for its usage.
9230 `linespoints` may be abbreviated `lp`.
9232 ?commands set style points
9234 ?plotting styles points
9237 The `points` style displays a small symbol at each point. The command `set
9238 pointsize` may be used to change the size of the points. See `set pointsize`
9241 ?commands set style steps
9243 ?plotting styles steps
9246 The `steps` style is only relevant to 2-d plotting. It connects consecutive
9247 points with two line segments: the first from (x1,y1) to (x2,y1) and the
9248 second from (x2,y1) to (x2,y2).
9250 ^ <a href="http://www.gnuplot.info/demo/steps.html">
9254 ?commands set style rgbimage
9256 ?plotting styles rgbimage
9259 The `rgbimage` style is intended for plotting 2D images and is similar
9260 in concept to `image`. See `image` for details. The difference is
9261 that 5D data (x,y,r,g,b) for `plot` and 6D data (x,y,z,r,g,b) for `splot`
9262 describe the coordinates and color components of an image.
9266 ?commands set style vectors
9268 ?plotting styles vectors
9271 The 2D `vectors` style draws a vector from (x,y) to (x+xdelta,y+ydelta).
9272 Thus it requires four columns of data. It also draws a small arrowhead at the
9274 The 3D `vectors` style is similar, but requires six columns of data.
9275 splot with vectors is supported only for `set mapping cartesian`.
9276 The keywords "with vectors" may be followed by arrow style specifications.
9277 See `arrowstyle` for more details.
9280 plot 'file.dat' using 1:2:3:4 with vectors head filled lt 2
9281 splot 'file.dat' using 1:2:3:(1):(1):(1) with vectors filled head lw 2
9283 `set clip one` and `set clip two` affect vectors drawn in 2D.
9284 Please see `set clip` and `arrowstyle`.
9286 ?commands set style xerrorbars
9287 ?set style xerrorbars
9288 ?plotting styles xerrorbars
9291 The `xerrorbars` style is only relevant to 2-d data plots. `xerrorbars` is
9292 like `dots`, except that a horizontal error bar is also drawn. At each point
9293 (x,y), a line is drawn from (xlow,y) to (xhigh,y) or from (x-xdelta,y) to
9294 (x+xdelta,y), depending on how many data columns are provided. A tic mark
9295 is placed at the ends of the error bar (unless `set bars` is used---see
9296 `set bars` for details).
9298 ?commands set style xyerrorbars
9299 ?set style xyerrorbars
9300 ?plotting styles xyerrorbars
9303 The `xyerrorbars` style is only relevant to 2-d data plots. `xyerrorbars` is
9304 like `dots`, except that horizontal and vertical error bars are also drawn.
9305 At each point (x,y), lines are drawn from (x,y-ydelta) to (x,y+ydelta) and
9306 from (x-xdelta,y) to (x+xdelta,y) or from (x,ylow) to (x,yhigh) and from
9307 (xlow,y) to (xhigh,y), depending upon the number of data columns provided. A
9308 tic mark is placed at the ends of the error bar (unless `set bars` is
9309 used---see `set bars` for details).
9311 If data are provided in an unsupported mixed form, the `using` filter on the
9312 `plot` command should be used to set up the appropriate form. For example,
9313 if the data are of the form (x,y,xdelta,ylow,yhigh), then you can use
9315 plot 'data' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars
9317 ?commands set style yerrorbars
9318 ?commands set style errorbars
9319 ?plotting styles yerrorbars
9320 ?plotting styles errorbars
9321 ?set style yerrorbars
9322 ?set style errorbars
9326 The `yerrorbars` (or `errorbars`) style is only relevant to 2-d data plots.
9327 `yerrorbars` is like `points`, except that a vertical error bar is also drawn.
9328 At each point (x,y), a line is drawn from (x,y-ydelta) to (x,y+ydelta) or
9329 from (x,ylow) to (x,yhigh), depending on how many data columns are provided.
9330 A tic mark is placed at the ends of the error bar (unless `set bars` is
9331 used---see `set bars` for details).
9333 ^ <a href="http://www.gnuplot.info/demo/mgr.html">
9337 ?commands set style xerrorlines
9338 ?set style xerrorlines
9339 ?plotting styles xerrorlines
9342 The `xerrorlines` style is only relevant to 2-d data plots.
9343 `xerrorlines` is like `linespoints`, except that a horizontal error
9344 line is also drawn. At each point (x,y), a line is drawn from (xlow,y)
9345 to (xhigh,y) or from (x-xdelta,y) to (x+xdelta,y), depending on how
9346 many data columns are provided. A tic mark is placed at the ends of
9347 the error bar (unless `set bars` is used---see `set bars` for details).
9349 ?commands set style xyerrorlines
9350 ?set style xyerrorlines
9351 ?plotting styles xyerrorlines
9354 The `xyerrorlines` style is only relevant to 2-d data plots.
9355 `xyerrorlines` is like `linespoints`, except that horizontal and
9356 vertical error bars are also drawn. At each point (x,y), lines are
9357 drawn from (x,y-ydelta) to (x,y+ydelta) and from (x-xdelta,y) to
9358 (x+xdelta,y) or from (x,ylow) to (x,yhigh) and from (xlow,y) to
9359 (xhigh,y), depending upon the number of data columns provided. A tic
9360 mark is placed at the ends of the error bar (unless `set bars` is
9361 used---see `set bars` for details).
9363 If data are provided in an unsupported mixed form, the `using` filter on the
9364 `plot` command should be used to set up the appropriate form. For example,
9365 if the data are of the form (x,y,xdelta,ylow,yhigh), then you can use
9367 plot 'data' using 1:2:($1-$3):($1+$3):4:5 with xyerrorlines
9369 ?commands set style yerrorlines
9370 ?commands set style errorlines
9371 ?plotting styles yerrorlines
9372 ?plotting styles errorlines
9373 ?set style yerrorlines
9374 ?set style errorlines
9378 The `yerrorlines` (or `errorlines`) style is only relevant to 2-d data
9379 plots. `yerrorlines` is like `linespoints`, except that a vertical
9380 error line is also drawn. At each point (x,y), a line is drawn from
9381 (x,y-ydelta) to (x,y+ydelta) or from (x,ylow) to (x,yhigh), depending
9382 on how many data columns are provided. A tic mark is placed at the
9383 ends of the error bar (unless `set bars` is used---see `set bars` for
9386 ^ <a href="http://www.gnuplot.info/demo/mgr.html">
9390 ?commands set surface
9391 ?commands unset surface
9392 ?commands show surface
9398 The command `set surface` controls the display of surfaces by `splot`.
9405 The surface is drawn with the style specified by `with`, or else the
9406 appropriate style, data or function.
9408 Whenever `unset surface` is issued, `splot` will not draw points or lines
9409 corresponding to the function or data file points. Contours may still be
9410 drawn on the surface, depending on the `set contour` option. `unset surface;
9411 set contour base` is useful for displaying contours on the grid base. See
9417 When `table` mode is enabled, `plot` and `splot` commands print out a
9418 multicolumn ASCII table of X Y {Z} R values rather than creating an actual
9419 plot on the current terminal. The character R takes on one of three values:
9420 "i" if the point is in the active range, "o" if it is out-of-range, or "u"
9421 if it is undefined. The data format is determined by the format of the axis
9422 labels (see `set format`), and the columns are separated by single spaces.
9423 This can be useful if you want to generate contours and then save them for
9424 further use, perhaps for plotting with `plot`; see `set contour` for example.
9425 The same method can be used to save interpolated data
9426 (see `set samples` and `set dgrid3d`).
9429 set table {"outfile"}
9433 Tabular output is written to the named file, if any, otherwise it is written
9434 to the current value of `set output`. You must explicitly `unset table`
9435 in order to go back to normal plotting on the current terminal.
9437 ?commands set terminal
9438 ?commands show terminal
9453 `gnuplot` supports many different graphics devices. Use `set terminal` to
9454 tell `gnuplot` what kind of output to generate. Use `set output` to redirect
9455 that output to a file or device.
9458 set terminal {<terminal-type> | push | pop}
9461 If <terminal-type> is omitted, `gnuplot` will list the available terminal
9462 types. <terminal-type> may be abbreviated.
9464 If both `set terminal` and `set output` are used together, it is safest to
9465 give `set terminal` first, because some terminals set a flag which is needed
9466 in some operating systems.
9468 Several terminals have many additional options. For example, see `png`,
9470 The options used by a previous invocation `set term <term> <options>` of a
9471 given `<term>` are remembered, thus subsequent `set term <term>` does
9472 not reset them. This helps in printing, for instance, when switching
9473 among different terminals---previous options don't have to be repeated.
9475 The command `set term push` remembers the current terminal including its
9476 settings while `set term pop` restores it. This is equivalent to `save term`
9477 and `load term`, but without accessing the filesystem. Therefore they can be
9478 used to achieve platform independent restoring of the terminal after printing,
9479 for instance. After gnuplot's startup, the default terminal or that from
9480 `startup` file is pushed automatically. Therefore portable scripts can rely
9481 that `set term pop` restores the default terminal on a given platform unless
9482 another terminal has been pushed explicitly.
9484 For a complete list of available terminal types, see `terminal`.
9486 ?commands set termoption
9489 The `set termoption` command allows you to change the behaviour of the
9490 current terminal without requiring a new `set terminal` command. Only one
9491 option can be changed per command, and only a small number of options can
9492 be changed this way. Currently the only options accepted are
9494 set termoption {no}enhanced
9495 set termoption font "<fontname>{,<fontsize>}"
9499 ?commands unset tics
9505 Control of the major (labelled) tics on all axes at once is possible with the
9508 Fine control of the major (labelled) tics on all axes at once is possible
9509 with the `set tics` command. The tics may be turned off with the `unset tics`
9510 command, and may be turned on (the default state) with `set tics`. Similar
9511 commands (by preceding 'tics' by the axis name) control the major tics on a
9515 set tics {axis | border} {{no}mirror}
9516 {in | out} {scale {default | <major> {,<minor>}}}
9517 {{no}rotate {by <ang>}} {offset <offset> | nooffset}
9518 { format "formatstring" } { font "name{,<size>}" }
9519 { textcolor <colorspec> }
9520 set tics {front | back}
9524 The options in the first set above can be applied individually to
9525 any or all axes, i.e., x, y, z, x2, y2, and cb.
9527 Set tics `front` or `back` applies to all axes at once, but only for 2D plots
9528 (not splot). It controls whether the tics are placed behind or in front of
9529 the plot elements, in the case that there is overlap.
9531 `axis` or `border` tells `gnuplot` to put the tics (both the tics themselves
9532 and the accompanying labels) along the axis or the border, respectively. If
9533 the axis is very close to the border, the `axis` option will move the
9534 tic labels to outside the border in case the border is printed (see
9535 `set border`). The relevant margin settings will usually be sized badly by
9536 the automatic layout algorithm in this case.
9538 `mirror` tells `gnuplot` to put unlabelled tics at the same positions on the
9539 opposite border. `nomirror` does what you think it does.
9541 `in` and `out` change the tic marks to be drawn inwards or outwards.
9543 With `scale`, the size of the tic marks can be adjusted. If <minor> is not
9544 specified, it is 0.5*<major>. The default size 1.0 for major tics and 0.5
9545 for minor tics is requested by `scale default`.
9547 `rotate` asks `gnuplot` to rotate the text through 90 degrees, which will be
9548 done if the terminal driver in use supports text rotation. `norotate`
9549 cancels this. `rotate by <ang>` asks for rotation by <ang> degrees, supported
9550 by some terminal types.
9552 The defaults are `border mirror norotate` for tics on the x and y axes, and
9553 `border nomirror norotate` for tics on the x2 and y2 axes. For the z axis,
9554 the default is `nomirror`.
9556 The <offset> is specified by either x,y or x,y,z, and may be preceded by
9557 `first`, `second`, `graph`, `screen`, or `character` to select the
9558 coordinate system. <offset> is the offset of the tics texts from their
9559 default positions, while the default coordinate system is `character`.
9560 See `coordinates` for details. `nooffset` switches off the offset.
9562 `set tics` with no options restores to place tics inwards. Every other
9563 options are retained.
9565 See also `set xtics` for more control of major (labelled) tic marks and
9566 `set mxtics` for control of minor tic marks. These commands provide control
9567 at a axis by axis basis.
9571 ?commands set ticscale
9572 ?commands show ticscale
9576 The `set ticscale` command is deprecated, use `set tics scale` instead.
9578 ?commands set timestamp
9579 ?commands unset timestamp
9580 ?commands show timestamp
9586 The command `set timestamp` places the time and date of the plot in the left
9590 set timestamp {"<format>"} {top|bottom} {{no}rotate}
9591 {offset <xoff>{,<yoff>}} {font "<fontspec>"}
9595 The format string allows you to choose the format used to write the date and
9596 time. Its default value is what asctime() uses: "%a %b %d %H:%M:%S %Y"
9597 (weekday, month name, day of the month, hours, minutes, seconds, four-digit
9598 year). With `top` or `bottom` you can place the timestamp at the top or
9599 bottom of the left margin (default: bottom). `rotate` lets you write the
9600 timestamp vertically, if your terminal supports vertical text. The constants
9601 <xoff> and <yoff> are offsets that let you adjust the position more finely.
9602 <font> is used to specify the font with which the time is to be written.
9604 The abbreviation `time` may be used in place of `timestamp`.
9607 set timestamp "%d/%m/%y %H:%M" offset 80,-2 font "Helvetica"
9609 See `set timefmt` for more information about time format strings.
9611 ?commands set timefmt
9612 ?commands show timefmt
9616 This command applies to timeseries where data are composed of dates/times.
9617 It has no meaning unless the command `set xdata time` is given also.
9620 set timefmt "<format string>"
9623 The string argument tells `gnuplot` how to read timedata from the datafile.
9624 The valid formats are:
9626 @start table - first is interactive cleartext form
9628 %d day of the month, 1--31
9629 %m month of the year, 1--12
9632 %j day of the year, 1--365
9635 %s seconds since the Unix epoch (1970-01-01, 00:00 UTC)
9637 %b three-character abbreviation of the name of the month
9638 %B name of the month
9639 #\begin{tabular}{|cl|} \hline
9640 #\multicolumn{2}{|c|}{Time Series timedata Format Specifiers}\\
9642 #Format & Explanation \\ \hline
9643 #\verb@%d@ & day of the month, 1--31 \\
9644 #\verb@%m@ & month of the year, 1--12 \\
9645 #\verb@%y@ & year, 0--99 \\
9646 #\verb@%Y@ & year, 4-digit \\
9647 #\verb@%j@ & day of the year, 1--365 \\
9648 #\verb@%H@ & hour, 0--24 \\
9649 #\verb@%M@ & minute, 0--60 \\
9650 #\verb@%s@ & seconds since the Unix epoch (1970-01-01 00:00 UTC) \\
9651 #\verb@%S@ & second, 0--60 \\
9652 #\verb@%b@ & three-character abbreviation of the name of the month \\
9653 #\verb@%B@ & name of the month \\
9657 %%d@day of the month, 1--31
9658 %%m@month of the year, 1--12
9661 %%j@day of the year, 1--365
9664 %%s@seconds since the Unix epoch (1970-01-01 00:00 UTC)
9666 %%b@three-character abbreviation of the name of the month
9667 %%B@name of the month
9670 Any character is allowed in the string, but must match exactly. \t (tab) is
9671 recognized. Backslash-octals (\nnn) are converted to char. If there is no
9672 separating character between the time/date elements, then %d, %m, %y, %H, %M
9673 and %S read two digits each, %Y reads four digits and %j reads three digits.
9674 %b requires three characters, and %B requires as many as it needs.
9676 Spaces are treated slightly differently. A space in the string stands for
9677 zero or more whitespace characters in the file. That is, "%H %M" can be used
9678 to read "1220" and "12 20" as well as "12 20".
9680 Each set of non-blank characters in the timedata counts as one column in the
9681 `using n:n` specification. Thus `11:11 25/12/76 21.0` consists of three
9682 columns. To avoid confusion, `gnuplot` requires that you provide a complete
9683 `using` specification if your file contains timedata.
9685 Since `gnuplot` cannot read non-numerical text, if the date format includes
9686 the day or month in words, the format string must exclude this text. But
9687 it can still be printed with the "%a", "%A", "%b", or "%B" specifier:
9688 see `set format` for more details about these and other options for printing
9689 timedata. (`gnuplot` will determine the proper month and weekday from the
9692 See also `set xdata` and `Time/date` for more information.
9695 set timefmt "%d/%m/%Y\t%H:%M"
9696 tells `gnuplot` to read date and time separated by tab. (But look closely at
9697 your data---what began as a tab may have been converted to spaces somewhere
9698 along the line; the format string must match what is actually in the file.)
9700 ^ <a href="http://www.gnuplot.info/demo/timedat.html">
9705 ?commands show title
9709 The `set title` command produces a plot title that is centered at the top of
9710 the plot. `set title` is a special case of `set label`.
9713 set title {"<title-text>"} {offset <offset>} {font "<font>{,<size>}"}
9714 {{textcolor | tc} {<colorspec> | default}} {{no}enhanced}
9717 If <offset> is specified by either x,y or x,y,z the title is moved by the
9718 given offset. It may be preceded by `first`, `second`, `graph`, `screen`,
9719 or `character` to select the coordinate system. See `coordinates` for
9720 details. By default, the `character` coordinate system is used. For
9721 example, "`set title offset 0,-1`" will change only the y offset of the
9722 title, moving the title down by roughly the height of one character. The
9723 size of a character depends on both the font and the terminal.
9725 <font> is used to specify the font with which the title is to be written;
9726 the units of the font <size> depend upon which terminal is used.
9728 `textcolor <colorspec>` changes the color of the text. <colorspec> can be a
9729 linetype, an rgb color, or a palette mapping. See help for `colorspec` and
9732 `noenhanced` requests that the title not be processed by the enhanced text
9733 mode parser, even if enhanced text mode is currently active.
9735 `set title` with no parameters clears the title.
9737 See `syntax` for details about the processing of backslash sequences and
9738 the distinction between single- and double-quotes.
9740 ?commands set tmargin
9743 The command `set tmargin` sets the size of the top margin.
9744 Please see `set margin` for details.
9746 ?commands set trange
9747 ?commands show trange
9751 The `set trange` command sets the parametric range used to compute x and y
9752 values when in parametric or polar modes. Please see `set xrange` for
9755 ?commands set urange
9756 ?commands show urange
9760 The `set urange` and `set vrange` commands set the parametric ranges used
9761 to compute x, y, and z values when in `splot` parametric mode.
9762 Please see `set xrange` for details.
9764 ?commands show variables
9766 The `show variables` command lists all user-defined variables and their
9770 show variables {all}
9772 With the optional keyword "all", also the `gnuplot-defined variables` that
9773 begin with `GPVAL_` are listed.
9777 The `show version` command lists the version of gnuplot being run, its last
9778 modification date, the copyright holders, and email addresses for the FAQ,
9779 the gnuplot-info mailing list, and reporting bugs--in short, the information
9780 listed on the screen when the program is invoked interactively.
9785 When the `long` option is given, it also lists the operating system, the
9786 compilation options used when `gnuplot` was installed, the location of the
9787 help file, and (again) the useful email addresses.
9793 ?set view {no}equal {xy|xyz}
9796 The `set view` command sets the viewing angle for `splot`s. It controls how
9797 the 3-d coordinates of the plot are mapped into the 2-d screen space. It
9798 provides controls for both rotation and scaling of the plotted data, but
9799 supports orthographic projections only. It supports both 3D projection or
9800 orthogonal 2D projection into a 2D plot-like map.
9803 set view <rot_x>{,{<rot_z>}{,{<scale>}{,<scale_z>}}}
9805 set view {no}equal_axes
9808 where <rot_x> and <rot_z> control the rotation angles (in degrees) in a
9809 virtual 3-d coordinate system aligned with the screen such that initially
9810 (that is, before the rotations are performed) the screen horizontal axis is
9811 x, screen vertical axis is y, and the axis perpendicular to the screen is z.
9812 The first rotation applied is <rot_x> around the x axis. The second rotation
9813 applied is <rot_z> around the new z axis.
9815 Command `set view map` is used to represent the drawing as a map. It can be
9816 used for `contour` plots, or for color `pm3d` maps. In the latter, take care
9817 that you properly use `zrange` and `cbrange` for input data point filtering
9818 and color range scaling, respectively.
9820 <rot_x> is bounded to the [0:180] range with a default of 60 degrees, while
9821 <rot_z> is bounded to the [0:360] range with a default of 30 degrees.
9822 <scale> controls the scaling of the entire `splot`, while <scale_z> scales
9823 the z axis only. Both scales default to 1.0.
9826 set view 60, 30, 1, 1
9829 The first sets all the four default values. The second changes only scale,
9832 The command `set view equal xy` forces the unit length of the x and y axes
9833 to be on the same scale, and chooses that scale so that the plot will fit on
9834 the page. The command `set view equal xyz` additionally sets the z axis
9835 scale to match the x and y axes; however there is no guarantee that the
9836 current z axis range will fit within the plot boundary.
9837 By default all three axes are scaled independently to fill the available area.
9839 See also `set ticslevel`.
9841 ?commands set vrange
9842 ?commands show vrange
9846 The `set urange` and `set vrange` commands set the parametric ranges used
9847 to compute x, y, and z values when in `splot` parametric mode.
9848 Please see `set xrange` for details.
9850 ?commands set x2data
9851 ?commands show x2data
9855 The `set x2data` command sets data on the x2 (top) axis to timeseries
9856 (dates/times). Please see `set xdata`.
9858 ?commands set x2dtics
9859 ?commands unset x2dtics
9860 ?commands show x2dtics
9866 The `set x2dtics` command changes tics on the x2 (top) axis to days of the
9867 week. Please see `set xdtics` for details.
9869 ?commands set x2label
9870 ?commands show x2label
9874 The `set x2label` command sets the label for the x2 (top) axis.
9875 Please see `set xlabel`.
9877 ?commands set x2mtics
9878 ?commands unset x2mtics
9879 ?commands show x2mtics
9885 The `set x2mtics` command changes tics on the x2 (top) axis to months of the
9886 year. Please see `set xmtics` for details.
9888 ?commands set x2range
9889 ?commands show x2range
9893 The `set x2range` command sets the horizontal range that will be displayed on
9894 the x2 (top) axis. Please see `set xrange` for details.
9896 ?commands set x2tics
9897 ?commands unset x2tics
9898 ?commands show x2tics
9904 The `set x2tics` command controls major (labelled) tics on the x2 (top) axis.
9905 Please see `set xtics` for details.
9907 ?commands set x2zeroaxis
9908 ?commands unset x2zeroaxis
9909 ?commands show x2zeroaxis
9915 The `set x2zeroaxis` command draws a line at the origin of the x2 (top) axis
9916 (y2 = 0). For details, please see `set zeroaxis`.
9919 ?commands show xdata
9923 This command sets the datatype on the x axis to time/date. A similar command
9924 does the same thing for each of the other axes.
9930 The same syntax applies to `ydata`, `zdata`, `x2data`, `y2data` and `cbdata`.
9932 The `time` option signals that the datatype is indeed time/date. If the
9933 option is not specified, the datatype reverts to normal.
9935 See `set timefmt` to tell gnuplot how to read date or time data. The
9936 time/date is converted to seconds from start of the century. There is
9937 currently only one timefmt, which implies that all the time/date columns must
9938 conform to this format. Specification of ranges should be supplied as quoted
9939 strings according to this format to avoid interpretation of the time/date as
9942 The function 'strftime' (type "man strftime" on unix to look it up) is used
9943 to print tic-mark labels. `gnuplot` tries to figure out a reasonable format
9944 for this unless the `set format x "string"` has supplied something that does
9945 not look like a decimal format (more than one '%' or neither %f nor %g).
9947 See also `Time/date` for more information.
9949 ?commands set xdtics
9950 ?commands unset xdtics
9951 ?commands show xdtics
9957 The `set xdtics` commands converts the x-axis tic marks to days of the week
9958 where 0=Sun and 6=Sat. Overflows are converted modulo 7 to dates. `set
9959 noxdtics` returns the labels to their default values. Similar commands do
9960 the same things for the other axes.
9967 The same syntax applies to `ydtics`, `zdtics`, `x2dtics`, `y2dtics` and
9970 See also the `set format` command.
9972 ?commands set xlabel
9973 ?commands show xlabel
9977 The `set xlabel` command sets the x axis label. Similar commands set labels
9981 set xlabel {"<label>"} {offset <offset>} {font "<font>{,<size>}"}
9982 {{textcolor | tc} {lt <line_type> | default}} {{no}enhanced}
9983 {rotate by <degrees>}
9986 The same syntax applies to `x2label`, `ylabel`, `y2label`, `zlabel` and
9989 If <offset> is specified by either x,y or x,y,z the label is moved by the
9990 given offset. It may be preceded by `first`, `second`, `graph`, `screen`,
9991 or `character` to select the coordinate system. See `coordinates` for
9992 details. By default, the `character` coordinate system is used. For
9993 example, "`set xlabel offset -1,0`" will change only the x offset of the
9994 title, moving the label roughly one character width to the left. The size
9995 of a character depends on both the font and the terminal.
9997 <font> is used to specify the font in which the label is written; the units
9998 of the font <size> depend upon which terminal is used.
10000 `textcolor lt <n>` sets the text color to that of line type <n>.
10002 `noenhanced` requests that the label text not be processed by the enhanced text
10003 mode parser, even if enhanced text mode is currently active.
10005 To clear a label, put no options on the command line, e.g., "`set y2label`".
10007 The default positions of the axis labels are as follows:
10009 xlabel: The x-axis label is centered below the bottom axis.
10011 ylabel: The position of the y-axis label depends on the terminal, and can be
10012 one of the following three positions:
10014 1. Horizontal text flushed left at the top left of the plot. Terminals that
10015 cannot rotate text will probably use this method. If `set x2tics` is also
10016 in use, the ylabel may overwrite the left-most x2tic label. This may be
10017 remedied by adjusting the ylabel position or the left margin.
10019 2. Vertical text centered vertically at the left of the plot. Terminals
10020 that can rotate text will probably use this method.
10022 3. Horizontal text centered vertically at the left of the plot. The EEPIC,
10023 LaTeX and TPIC drivers use this method. The EEPIC driver will produce a
10024 stack of characters so as not to overwrite the plot. With other drivers
10025 (such as LaTeX and TPIC), the user probably has to insert line breaks
10026 using \\ to prevent the ylabel from overwriting the plot.
10028 zlabel: The z-axis label is centered along the z axis and placed in the space
10029 above the grid level.
10031 cblabel: The color box axis label is centered along the box and placed below
10032 or right according to horizontal or vertical color box gradient.
10034 y2label: The y2-axis label is placed to the right of the y2 axis. The
10035 position is terminal-dependent in the same manner as is the y-axis label.
10037 x2label: The x2-axis label is placed above the top axis but below the plot
10038 title. It is also possible to create an x2-axis label by using new-line
10039 characters to make a multi-line plot title, e.g.,
10041 set title "This is the title\n\nThis is the x2label"
10043 Note that double quotes must be used. The same font will be used for both
10046 The y and y2 axis labels can be explicitly rotated from their default
10047 orientation, but this applies only to 2D plots and only on terminals
10048 that support text rotation.
10050 If you are not satisfied with the default position of an axis label, use `set
10051 label` instead--that command gives you much more control over where text is
10054 Please see `syntax` for further information about backslash processing
10055 and the difference between single- and double-quoted strings.
10057 ?commands set xmtics
10058 ?commands unset xmtics
10059 ?commands show xmtics
10065 The `set xmtics` command converts the x-axis tic marks to months of the
10066 year where 1=Jan and 12=Dec. Overflows are converted modulo 12 to months.
10067 The tics are returned to their default labels by `unset xmtics`. Similar
10068 commands perform the same duties for the other axes.
10075 The same syntax applies to `x2mtics`, `ymtics`, `y2mtics`, `zmtics` and
10078 See also the `set format` command.
10080 ?commands set xrange
10081 ?commands show xrange
10087 The `set xrange` command sets the horizontal range that will be displayed.
10088 A similar command exists for each of the other axes, as well as for the
10089 polar radius r and the parametric variables t, u, and v.
10092 set xrange { [{{<min>}:{<max>}}] {{no}reverse} {{no}writeback} }
10096 where <min> and <max> terms are constants, expressions or an asterisk to set
10097 autoscaling. If the data are time/date, you must give the range as a quoted
10098 string according to the `set timefmt` format. Any value omitted will not be
10101 The same syntax applies to `yrange`, `zrange`, `x2range`, `y2range`, `cbrange`,
10102 `rrange`, `trange`, `urange` and `vrange`.
10104 The `reverse` option reverses the direction of the axis, e.g., `set xrange
10105 [0:1] reverse` will produce an axis with 1 on the left and 0 on the right.
10106 This is identical to the axis produced by `set xrange [1:0]`, of course.
10107 `reverse` is intended primarily for use with `autoscale`.
10109 The `writeback` option essentially saves the range found by `autoscale` in
10110 the buffers that would be filled by `set xrange`. This is useful if you wish
10111 to plot several functions together but have the range determined by only
10112 some of them. The `writeback` operation is performed during the `plot`
10113 execution, so it must be specified before that command. To restore,
10114 the last saved horizontal range use `set xrange restore`. For example,
10116 set xrange [-10:10]
10117 set yrange [] writeback
10122 results in a yrange of [-1:1] as found only from the range of sin(x); the
10123 [-5:5] range of x/2 is ignored. Executing `show yrange` after each command
10124 in the above example should help you understand what is going on.
10126 In 2-d, `xrange` and `yrange` determine the extent of the axes, `trange`
10127 determines the range of the parametric variable in parametric mode or the
10128 range of the angle in polar mode. Similarly in parametric 3-d, `xrange`,
10129 `yrange`, and `zrange` govern the axes and `urange` and `vrange` govern the
10130 parametric variables.
10132 In polar mode, `rrange` determines the radial range plotted. <rmin> acts as
10133 an additive constant to the radius, whereas <rmax> acts as a clip to the
10134 radius---no point with radius greater than <rmax> will be plotted. `xrange`
10135 and `yrange` are affected---the ranges can be set as if the graph was of
10136 r(t)-rmin, with rmin added to all the labels.
10138 Any range may be partially or totally autoscaled, although it may not make
10139 sense to autoscale a parametric variable unless it is plotted with data.
10141 Ranges may also be specified on the `plot` command line. A range given on
10142 the plot line will be used for that single `plot` command; a range given by
10143 a `set` command will be used for all subsequent plots that do not specify
10144 their own ranges. The same holds true for `splot`.
10148 To set the xrange to the default:
10149 set xrange [-10:10]
10151 To set the yrange to increase downwards:
10152 set yrange [10:-10]
10154 To change zmax to 10 without affecting zmin (which may still be autoscaled):
10157 To autoscale xmin while leaving xmax unchanged:
10160 ?commands set xtics
10161 ?commands unset xtics
10162 ?commands show xtics
10168 Fine control of the major (labelled) tics on the x axis is possible with the
10169 `set xtics` command. The tics may be turned off with the `unset xtics`
10170 command, and may be turned on (the default state) with `set xtics`. Similar
10171 commands control the major tics on the y, z, x2 and y2 axes.
10174 set xtics {axis | border} {{no}mirror}
10175 {in | out} {scale {default | <major> {,<minor>}}}
10176 {{no}rotate {by <ang>}} {offset <offset> | nooffset}
10180 | <start>, <incr> {,<end>}
10181 | ({"<label>"} <pos> {<level>} {,{"<label>"}...) }
10182 { format "formatstring" } { font "name{,<size>}" }
10184 { textcolor <colorspec> }
10188 The same syntax applies to `ytics`, `ztics`, `x2tics`, `y2tics` and `cbtics`.
10190 `axis` or `border` tells `gnuplot` to put the tics (both the tics themselves
10191 and the accompanying labels) along the axis or the border, respectively. If
10192 the axis is very close to the border, the `axis` option will move the
10193 tic labels to outside the border. The relevant margin settings will usually
10194 be sized badly by the automatic layout algorithm in this case.
10196 `mirror` tells `gnuplot` to put unlabelled tics at the same positions on the
10197 opposite border. `nomirror` does what you think it does.
10199 `in` and `out` change the tic marks to be drawn inwards or outwards.
10201 With `scale`, the size of the tic marks can be adjusted. If <minor> is not
10202 specified, it is 0.5*<major>. The default size 1.0 for major tics and 0.5
10203 for minor tics is requested by `scale default`.
10205 `rotate` asks `gnuplot` to rotate the text through 90 degrees, which will be
10206 done if the terminal driver in use supports text rotation. `norotate`
10207 cancels this. `rotate by <ang>` asks for rotation by <ang> degrees, supported
10208 by some terminal types.
10210 The defaults are `border mirror norotate` for tics on the x and y axes, and
10211 `border nomirror norotate` for tics on the x2 and y2 axes. For the z axis,
10212 the `{axis | border}` option is not available and the default is
10213 `nomirror`. If you do want to mirror the z-axis tics, you might want to
10214 create a bit more room for them with `set border`.
10216 The <offset> is specified by either x,y or x,y,z, and may be preceded by
10217 `first`, `second`, `graph`, `screen`, or `character` to select the
10218 coordinate system. <offset> is the offset of the tics texts from their
10219 default positions, while the default coordinate system is `character`.
10220 See `coordinates` for details. `nooffset` switches off the offset.
10224 Move xtics more closely to the plot.
10225 set xtics offset 0,graph 0.05
10227 `set xtics` with no options restores the default border or axis if xtics are
10228 being displayed; otherwise it has no effect. Any previously specified tic
10229 frequency or position {and labels} are retained.
10231 Positions of the tics are calculated automatically by default or if the
10232 `autofreq` option is given; otherwise they may be specified in either of
10235 The implicit <start>, <incr>, <end> form specifies that a series of tics will
10236 be plotted on the axis between the values <start> and <end> with an increment
10237 of <incr>. If <end> is not given, it is assumed to be infinity. The
10238 increment may be negative. If neither <start> nor <end> is given, <start> is
10239 assumed to be negative infinity, <end> is assumed to be positive infinity,
10240 and the tics will be drawn at integral multiples of <incr>. If the axis is
10241 logarithmic, the increment will be used as a multiplicative factor.
10243 If you specify to a negative <start> or <incr> after a numerical value
10244 (e.g., `rotate by <angle>` or `offset <offset>`), the parser fails because
10245 it subtracts <start> or <incr> from that value. As a workaround, specify
10246 `0-<start>` resp. `0-<incr>` in that case.
10249 set xtics border offset 0,0.5 -5,1,5
10250 Fails with 'invalid expression' at the last comma.
10251 set xtics border offset 0,0.5 0-5,1,5
10253 set xtics offset 0,0.5 border -5,1,5
10254 Sets tics at the border, tics text with an offset of 0,0.5 characters, and
10255 sets the start, increment, and end to -5, 1, and 5, as requested.
10257 The `set grid` options 'front', 'back' and 'layerdefault' affect the drawing
10258 order of the xtics, too.
10262 Make tics at 0, 0.5, 1, 1.5, ..., 9.5, 10.
10265 Make tics at ..., -10, -5, 0, 5, 10, ...
10268 Make tics at 1, 100, 1e4, 1e6, 1e8.
10269 set logscale x; set xtics 1,100,1e8
10271 The explicit ("<label>" <pos> <level>, ...) form allows arbitrary tic
10272 positions or non-numeric tic labels. In this form, the tics do not
10273 need to be listed in numerical order. Each tic has a
10274 position, optionally with a label. Note that the label is
10275 a string enclosed by quotes. It may be a constant string, such as
10276 "hello", may contain formatting information for converting the
10277 position into its label, such as "%3f clients", or may be empty, "".
10278 See `set format` for more information. If no string is given, the
10279 default label (numerical) is used.
10281 An explicit tic mark has a third parameter, the "level". The default
10282 is level 0, a major tic. A level of 1 generates a minor tic. If the
10283 level is specified, then the label must also be supplied.
10286 set xtics ("low" 0, "medium" 50, "high" 100)
10287 set xtics (1,2,4,8,16,32,64,128,256,512,1024)
10288 set ytics ("bottom" 0, "" 10, "top" 20)
10289 set ytics ("bottom" 0, "" 10 1, "top" 20)
10291 In the second example, all tics are labelled. In the third, only the end
10292 tics are labelled. In the fourth, the unlabeled tic is a minor tic.
10294 Normally if explicit tics are given, they are used instead of auto-generated
10295 tics. Conversely if you specify `set xtics auto` or the like it will erase
10296 any previously specified explicit tics. You can mix explicit and auto-
10297 generated tics by using the keyword `add`, which must appear before
10298 the tic style being added.
10302 set xtics add ("Pi" 3.14159)
10304 This will automatically generate tic marks every 0.5 along x, but will
10305 also add an explicit labeled tic mark at pi.
10307 However they are specified, tics will only be plotted when in range.
10309 Format (or omission) of the tic labels is controlled by `set format`, unless
10310 the explicit text of a label is included in the `set xtics ("<label>")` form.
10312 Minor (unlabelled) tics can be added automatically by the `set mxtics`
10313 command, or at explicit positions by the `set xtics ("" <pos> 1, ...)` form.
10315 ?set xtics time_axis tics
10316 ?xtics time_axis tics
10318 In case of timeseries data, axis tic position values must be given as quoted
10319 dates or times according to the format `timefmt`. If the <start>, <incr>, <end>
10320 form is used, <start> and <end> must be given according to `timefmt`, but
10321 <incr> must be in seconds. Times will be written out according to the format
10322 given on `set format`, however.
10326 set timefmt "%d/%m"
10327 set xtics format "%b %d"
10328 set xrange ["01/12":"06/12"]
10329 set xtics "01/12", 172800, "05/12"
10332 set timefmt "%d/%m"
10333 set xtics format "%b %d"
10334 set xrange ["01/12":"06/12"]
10335 set xtics ("01/12", "" "03/12", "05/12")
10336 Both of these will produce tics "Dec 1", "Dec 3", and "Dec 5", but in the
10337 second example the tic at "Dec 3" will be unlabelled.
10338 4 xtics rangelimited
10339 ?set xtics rangelimited
10340 ?xtics rangelimited
10343 This option limits both the auto-generated axis tic labels and the
10344 corresponding plot border to the range of values actually present in the data
10345 that has been plotted. Note that this is independent of the current range
10346 limits for the plot. For example, suppose that the data in "file.dat" all lies
10347 in the range 2 < y < 4. Then the following commands will create a plot for
10348 which the left-hand plot border (y axis) is drawn for only this portion of the
10349 total y range, and only the axis tics in this region are generated.
10350 I.e., the plot will be scaled to the full range on y, but there will be a gap
10351 between 0 and 2 on the left border and another gap between 4 and 10. This
10352 style is sometimes refered to as a `range-frame` graph.
10355 set ytics nomirror rangelimited
10358 ?commands set ticslevel
10359 ?commands show ticslevel
10363 ?commands set xyplane
10364 ?commands show xyplane
10368 The `set xyplane` command adjusts the position at which the xy plane is drawn
10369 in a 3D plot. The synonym "set ticslevel" is accepted for backwards
10373 set ticslevel <frac>
10375 set xyplane at <zvalue>
10378 The form `set ticslevel <frac>` places the xy plane below the range in Z, where
10379 the distance from the xy plane to Zmin is given as a fraction of the total
10380 range in z. The default value is 0.5. Negative values are permitted, but tic
10381 labels on the three axes may overlap.
10383 To place the xy-plane at a position 'pos' on the z-axis, `ticslevel` may
10384 be set equal to (pos - zmin) / (zmin - zmax). However, this position will
10385 change if the z range is changed.
10387 The alternative form `set xyplane at <zvalue>` fixes the placement of the
10388 xy plane at a specific Z value regardless of the current z range. Thus to
10389 force the x, y, and z axes to meet at a common origin one would specify
10390 `set xyplane at 0`.
10392 See also `set view`, and `set zeroaxis`.
10394 ?commands set xzeroaxis
10395 ?commands unset xzeroaxis
10396 ?commands show xzeroaxis
10402 The `set xzeroaxis` command draws a line at y = 0. For details,
10403 please see `set zeroaxis`.
10405 ?commands set y2data
10406 ?commands show y2data
10410 The `set y2data` command sets y2 (right-hand) axis data to timeseries
10411 (dates/times). Please see `set xdata`.
10413 ?commands set y2dtics
10414 ?commands unset y2dtics
10420 The `set y2dtics` command changes tics on the y2 (right-hand) axis to days of
10421 the week. Please see `set xdtics` for details.
10423 ?commands set y2label
10424 ?commands show y2label
10428 The `set y2label` command sets the label for the y2 (right-hand) axis.
10429 Please see `set xlabel`.
10431 ?commands set y2mtics
10432 ?commands unset y2mtics
10433 ?commands show y2mtics
10439 The `set y2mtics` command changes tics on the y2 (right-hand) axis to months
10440 of the year. Please see `set xmtics` for details.
10442 ?commands set y2range
10443 ?commands show y2range
10447 The `set y2range` command sets the vertical range that will be displayed on
10448 the y2 (right-hand) axis. Please see `set xrange` for details.
10450 ?commands set y2tics
10451 ?commands unset y2tics
10452 ?commands show y2tics
10458 The `set y2tics` command controls major (labelled) tics on the y2 (right-hand)
10459 axis. Please see `set xtics` for details.
10461 ?commands set y2zeroaxis
10462 ?commands unset y2zeroaxis
10463 ?commands show y2zeroaxis
10469 The `set y2zeroaxis` command draws a line at the origin of the y2 (right-hand)
10470 axis (x2 = 0). For details, please see `set zeroaxis`.
10472 ?commands set ydata
10473 ?commands show ydata
10477 The `set ydata` commands sets y-axis data to timeseries (dates/times).
10478 Please see `set xdata`.
10480 ?commands set ydtics
10481 ?commands unset ydtics
10482 ?commands show ydtics
10488 The `set ydtics` command changes tics on the y axis to days of the week.
10489 Please see `set xdtics` for details.
10491 ?commands set ylabel
10492 ?commands show ylabel
10496 This command sets the label for the y axis. Please see `set xlabel`.
10498 ?commands set ymtics
10499 ?commands unset ymtics
10500 ?commands show ymtics
10506 The `set ymtics` command changes tics on the y axis to months of the year.
10507 Please see `set xmtics` for details.
10509 ?commands set yrange
10510 ?commands show yrange
10514 The `set yrange` command sets the vertical range that will be displayed on
10515 the y axis. Please see `set xrange` for details.
10517 ?commands set ytics
10518 ?commands unset ytics
10519 ?commands show ytics
10525 The `set ytics` command controls major (labelled) tics on the y axis.
10526 Please see `set xtics` for details.
10528 ?commands set yzeroaxis
10529 ?commands unset yzeroaxis
10530 ?commands show yzeroaxis
10536 The `set yzeroaxis` command draws a line at x = 0. For details,
10537 please see `set zeroaxis`.
10539 ?commands set zdata
10540 ?commands show zdata
10544 The `set zdata` command sets zaxis data to timeseries (dates/times).
10545 Please see `set xdata`.
10547 ?commands set zdtics
10548 ?commands unset zdtics
10549 ?commands show zdtics
10555 The `set zdtics` command changes tics on the z axis to days of the week.
10556 Please see `set xdtics` for details.
10558 ?commands set zzeroaxis
10559 ?commands unset zzeroaxis
10560 ?commands show zzeroaxis
10566 The `set zzeroaxis` command draws a line through (x=0,y=0). This has no effect
10567 on 2D plots, including splot with `set view map`. For details, please
10568 see `set zeroaxis` and `set xyplane`.
10570 ?commands set cbdata
10571 ?commands show cbdata
10575 Set color box axis data to timeseries (dates/times). Please see `set xdata`.
10577 ?commands set cbdtics
10578 ?commands unset cbdtics
10579 ?commands show cbdtics
10585 The `set cbdtics` command changes tics on the color box axis to days of the
10586 week. Please see `set xdtics` for details.
10589 ?commands show zero
10593 The `zero` value is the default threshold for values approaching 0.0.
10596 set zero <expression>
10599 `gnuplot` will not plot a point if its imaginary part is greater in magnitude
10600 than the `zero` threshold. This threshold is also used in various other
10601 parts of `gnuplot` as a (crude) numerical-error threshold. The default
10602 `zero` value is 1e-8. `zero` values larger than 1e-3 (the reciprocal of the
10603 number of pixels in a typical bitmap display) should probably be avoided, but
10604 it is not unreasonable to set `zero` to 0.0.
10606 ?commands set zeroaxis
10607 ?commands unset zeroaxis
10608 ?commands show zeroaxis
10613 The x axis may be drawn by `set xzeroaxis` and removed by `unset xzeroaxis`.
10614 Similar commands behave similarly for the y, x2, y2, and z axes.
10617 set {x|x2|y|y2|z}zeroaxis { {linestyle | ls <line_style>}
10618 | { linetype | lt <line_type>}
10619 { linewidth | lw <line_width>}}
10620 unset {x|x2|y|y2|z}zeroaxis
10621 show {x|y|z}zeroaxis
10624 By default, these options are off. The selected zero axis is drawn
10625 with a line of type <line_type> and width <line_width> (if supported
10626 by the terminal driver currently in use), or a user-defined style
10629 If no linetype is specified, any zero axes selected will be drawn
10630 using the axis linetype (linetype 0).
10632 `set zeroaxis` is equivalent to `set xzeroaxis; set yzeroaxis`.
10633 Note that the z-axis must be set separately using `set zzeroaxis`.
10637 To simply have the y=0 axis drawn visibly:
10641 If you want a thick line in a different color or pattern, instead:
10643 set xzeroaxis linetype 3 linewidth 2.5
10645 ?commands set zlabel
10646 ?commands show zlabel
10650 This command sets the label for the z axis. Please see `set xlabel`.
10652 ?commands set zmtics
10653 ?commands unset zmtics
10654 ?commands show zmtics
10660 The `set zmtics` command changes tics on the z axis to months of the year.
10661 Please see `set xmtics` for details.
10663 ?commands set zrange
10664 ?commands show zrange
10668 The `set zrange` command sets the range that will be displayed on the z axis.
10669 The zrange is used only by `splot` and is ignored by `plot`. Please see
10670 `set xrange` for details.
10672 ?commands set ztics
10673 ?commands unset ztics
10674 ?commands show ztics
10680 The `set ztics` command controls major (labelled) tics on the z axis.
10681 Please see `set xtics` for details.
10683 ?commands set cblabel
10684 ?commands show cblabel
10688 This command sets the label for the color box axis. Please see `set xlabel`.
10690 ?commands set cbmtics
10691 ?commands unset cbmtics
10692 ?commands show cbmtics
10698 The `set cbmtics` command changes tics on the color box axis to months of the
10699 year. Please see `set xmtics` for details.
10701 ?commands set cbrange
10702 ?commands show cbrange
10706 The `set cbrange` command sets the range of values which are colored using
10707 the current `palette` by styles `with pm3d`, `with image` and `with palette`.
10708 Values outside of the color range use color of the nearest extreme.
10710 If the cb-axis is autoscaled in `splot`, then the colorbox range is taken from
10711 `zrange`. Points drawn in `splot ... pm3d|palette` can be filtered by using
10712 different `zrange` and `cbrange`.
10714 Please see `set xrange` for details on `set cbrange` syntax. See also
10715 `set palette` and `set colorbox`.
10717 ?commands set cbtics
10718 ?commands unset cbtics
10719 ?commands show cbtics
10725 The `set cbtics` command controls major (labelled) tics on the color box axis.
10726 Please see `set xtics` for details.
10730 The `shell` command spawns an interactive shell. To return to `gnuplot`,
10731 type `logout` if using VMS, `exit` or the END-OF-FILE character if using
10732 Unix, `endcli` if using AmigaOS, or `exit` if using MS-DOS or OS/2.
10734 There are two ways of spawning a shell command: using `system` command
10735 or via `!` ($ if using VMS). The former command takes a string as a
10736 parameter and thus it can be used anywhere among other gnuplot commands,
10737 while the latter syntax requires to be the only command on the line. Control
10738 will return immediately to `gnuplot` after this command is executed. For
10739 example, in AmigaOS, MS-DOS or OS/2,
10746 prints a directory listing and then returns to `gnuplot`.
10749 Other examples of the former syntax:
10750 system "date"; set time; plot "a.dat"
10751 print=1; if (print) replot; set out; system "lpr x.ps"
10753 On an Atari, the `!` command first checks whether a shell is already loaded
10754 and uses it, if available. This is practical if `gnuplot` is run from
10755 `gulam`, for example.
10759 `splot` is the command for drawing 3-d plots (well, actually projections on
10760 a 2-d surface, but you knew that). It can create a plot from functions or
10761 a data file in a manner very similar to the `plot` command.
10763 See `plot` for features common to the `plot` command; only differences are
10764 discussed in detail here. Note specifically `plot`'s `axes` option is not
10765 available for `splot`.
10769 <function> | "<datafile>" {datafile-modifiers}}
10770 {<title-spec>} {with <style>}
10771 {, {definitions,} <function> ...}
10773 where either a <function> or the name of a data file enclosed in quotes is
10774 supplied. The function can be a mathematical expression, or a triple of
10775 mathematical expressions in parametric mode.
10777 By default `splot` draws the xy plane completely below the plotted data.
10778 The offset between the lowest ztic and the xy plane can be changed by `set
10779 ticslevel`. The orientation of a `splot` projection is controlled by
10780 `set view`. See `set view` and `set ticslevel` for more information.
10782 The syntax for setting ranges on the `splot` command is the same as for
10783 `plot`. In non-parametric mode, the order in which ranges must be given is
10784 `xrange`, `yrange`, and `zrange`. In parametric mode, the order is `urange`,
10785 `vrange`, `xrange`, `yrange`, and `zrange`.
10787 The `title` option is the same as in `plot`. The operation of `with` is also
10788 the same as in `plot`, except that the plotting styles available to `splot`
10789 are limited to `lines`, `points`, `linespoints`, `dots`, and `impulses`; the
10790 error-bar capabilities of `plot` are not available for `splot`.
10792 The `datafile` options have more differences.
10794 See also `show plot`.
10796 ?commands splot datafile
10799 As for `plot`, discrete data contained in a file can be displayed by
10800 specifying the name of the data file, enclosed in quotes, on the `splot`
10804 splot '<file_name>' {binary <binary list>}
10806 {index <index list>}
10807 {every <every list>}
10808 {using <using list>}
10810 The special filenames `""` and `"-"` are permitted, as in `plot`.
10812 In brief, `binary` and `matrix` indicate that the data are in a special
10813 form, `index` selects which data sets in a multi-data-set file are to be
10814 plotted, `every` specifies which datalines (subsets) within a single data
10815 set are to be plotted, and `using` determines how the columns within a single
10816 record are to be interpreted.
10818 The options `index` and `every` behave the same way as with `plot`; `using`
10819 does so also, except that the `using` list must provide three entries
10822 The `plot` options `thru` and `smooth` are not available for `splot`, but
10823 `cntrparam` and `dgrid3d` provide limited smoothing capabilities.
10825 Data file organization is essentially the same as for `plot`, except that
10826 each point is an (x,y,z) triple. If only a single value is provided, it
10827 will be used for z, the datablock number will be used for y, and the index
10828 of the data point in the datablock will be used for x. If two or four values
10829 are provided, `gnuplot` uses the last value for calculating the color in
10830 pm3d plots. Three values are interpreted as an (x,y,z) triple. Additional
10831 values are generally used as errors, which can be used by `fit`.
10833 Single blank records separate datablocks in a `splot` datafile; `splot`
10834 treats datablocks as the equivalent of function y-isolines. No line will
10835 join points separated by a blank record. If all datablocks contain the same
10836 number of points, `gnuplot` will draw cross-isolines between datablocks,
10837 connecting corresponding points. This is termed "grid data", and is required
10838 for drawing a surface, for contouring (`set contour`) and hidden-line removal
10839 (`set hidden3d`). See also `splot grid_data`.
10841 It is no longer necessary to specify `parametric` mode for three-column
10844 ?commands plot datafile binary matrix
10845 ?commands splot datafile binary matrix
10846 ?plot datafile matrix binary
10847 ?splot datafile matrix binary
10848 ?plot binary matrix
10849 ?splot binary matrix
10850 ?plot matrix binary
10851 ?splot matrix binary
10855 Gnuplot can read matrix binary files by use of the option `binary` appearing
10856 without keyword qualifications unique to general binary, i.e., `array`,
10857 `record`, `format`, or `filetype`. Other general binary keywords for
10858 translation should also apply to matrix binary. (See `binary general` for
10861 In previous versions, `gnuplot` dynamically detected binary data files. It
10862 is now necessary to specify the keyword `binary` directly after the filename.
10864 Single precision floats are stored in a binary file as follows:
10866 <N+1> <y0> <y1> <y2> ... <yN>
10867 <x0> <z0,0> <z0,1> <z0,2> ... <z0,N>
10868 <x1> <z1,0> <z1,1> <z1,2> ... <z1,N>
10871 which are converted into triplets:
10882 These triplets are then converted into `gnuplot` iso-curves and then
10883 `gnuplot` proceeds in the usual manner to do the rest of the plotting.
10885 A collection of matrix and vector manipulation routines (in C) is provided
10886 in `binary.c`. The routine to write binary data is
10888 int fwrite_matrix(file,m,nrl,nrl,ncl,nch,row_title,column_title)
10890 An example of using these routines is provided in the file `bf_test.c`, which
10891 generates binary files for the demo file `demo/binary.dem`.
10893 The `index` keyword is not supported, since the file format allows only one
10894 surface per file. The `every` and `using` filters are supported. `using`
10895 operates as if the data were read in the above triplet form.
10897 See also `binary general` and
10899 ^ <a href="http://www.gnuplot.info/demo/binary.html">
10900 Binary File Splot Demo.
10903 ?commands splot datafile example
10904 ?splot datafile example
10906 A simple example of plotting a 3-d data file is
10908 splot 'datafile.dat'
10910 where the file "datafile.dat" might contain:
10912 # The valley of the Gnu.
10929 Note that "datafile.dat" defines a 4 by 3 grid ( 4 rows of 3 points each ).
10930 Rows (datablocks) are separated by blank records.
10932 ^ <img align=bottom src="http://www.gnuplot.info/doc/splot.gif" alt="[splot.gif]" width=640 height=480>
10933 Note also that the x value is held constant within each dataline. If you
10934 instead keep y constant, and plot with hidden-line removal enabled, you will
10935 find that the surface is drawn 'inside-out'.
10937 Actually for grid data it is not necessary to keep the x values constant
10938 within a datablock, nor is it necessary to keep the same sequence of y
10939 values. `gnuplot` requires only that the number of points be the same for
10940 each datablock. However since the surface mesh, from which contours are
10941 derived, connects sequentially corresponding points, the effect of an
10942 irregular grid on a surface plot is unpredictable and should be examined
10943 on a case-by-case basis.
10945 ?commands plot datafile matrix ascii
10946 ?commands splot datafile matrix ascii
10947 ?plot datafile matrix ascii
10948 ?splot datafile matrix ascii
10950 ?splot matrix ascii
10951 ?data-file matrix ascii
10952 ?datafile matrix ascii
10954 The `matrix` keyword (without a sequent `binary` keyword) in
10955 {s}plot 'a.dat' matrix
10956 indicates that data are stored in an ascii numbers matrix format.
10958 The z-values are read in a row at a time, i. e.,
10959 z11 z12 z13 z14 ...
10960 z21 z22 z23 z24 ...
10961 z31 z32 z33 z34 ...
10964 In 3D, the x- and y-indices of the matrix surface plot correspond to column
10965 and row indices of the matrix, respectively, being enumerated from 0. You can
10966 rescale or transform the axes as usual for a data file with three columns
10967 by means of x=$1, y=$2, z=$3. For example
10968 splot 'a.dat' matrix using (1+$1/100):(1+$2*10):3
10970 A blank line or comment line ends the matrix, and starts a new surface mesh.
10971 You can select among the meshes inside a file by the `index` option to the
10972 `splot` command, as usual.
10974 See `matrix` for examples of plotting rows and columns of the matrix in
10977 ?commands plot datafile matrix
10978 ?commands splot datafile matrix
10979 ?plot datafile matrix
10980 ?splot datafile matrix
10986 Datafile can be in an ascii or binary matrix format. The `matrix` flag
10987 indicates that the file is ascii, the `binary` or `matrix binary` stands for
10988 a binary format. For details, see `matrix ascii` and `matrix binary`.
10990 Basic usage in `splot`:
10991 splot 'a.dat' matrix
10992 splot 'a.gpbin' {matrix} binary
10993 Advanced usage in `splot`:
10994 splot 'a.dat' matrix using 1:2:3
10995 splot 'a.gpbin' {matrix} binary using 1:2:3
10996 allows to transform the axes coordinates and the z-data independently.
10999 plot `a.dat` matrix
11000 plot `a.dat` matrix using 1:3
11001 plot 'a.gpbin' {matrix} binary using 1:3
11002 will plot rows of the matrix, while using 2:3 will plot matrix columns, and
11003 using 1:2 the point coordinates (rather useless). Applying the `every` option
11004 you can specify explicit rows and columns.
11006 Example -- rescale axes of a matrix in an ascii file:
11007 splot `a.dat` matrix using (1+$1):(1+$2*10):3
11009 Example -- plot the 3rd row of a matrix in an ascii file:
11010 plot 'a.dat' matrix using 1:3 every 1:999:1:2
11011 (rows are enumerated from 0, thus 2 instead of 3).
11013 ?commands splot grid_data
11016 The 3D routines are designed for points in a grid format, with one sample,
11017 datapoint, at each mesh intersection; the datapoints may originate from
11018 either evaluating a function, see `set isosamples`, or reading a datafile,
11019 see `splot datafile`. The term "isoline" is applied to the mesh lines for
11020 both functions and data. Note that the mesh need not be rectangular in x
11021 and y, as it may be parameterized in u and v, see `set isosamples`.
11023 However, `gnuplot` does not require that format. In the case of functions,
11024 'samples' need not be equal to 'isosamples', i.e., not every x-isoline
11025 sample need intersect a y-isoline. In the case of data files, if there
11026 are an equal number of scattered data points in each datablock, then
11027 "isolines" will connect the points in a datablock, and "cross-isolines"
11028 will connect the corresponding points in each datablock to generate a
11029 "surface". In either case, contour and hidden3d modes may give different
11030 plots than if the points were in the intended format. Scattered data can be
11031 converted to a {different} grid format with `set dgrid3d`.
11033 The contour code tests for z intensity along a line between a point on a
11034 y-isoline and the corresponding point in the next y-isoline. Thus a `splot`
11035 contour of a surface with samples on the x-isolines that do not coincide with
11036 a y-isoline intersection will ignore such samples. Try:
11037 set xrange [-pi/2:pi/2]; set yrange [-pi/2:pi/2]
11038 set style function lp
11040 set isosamples 10,10; set samples 10,10;
11041 splot cos(x)*cos(y)
11042 set samples 4,10; replot
11043 set samples 10,4; replot
11046 ?commands splot overview
11048 `splot` can display a surface as a collection of points, or by connecting
11049 those points. As with `plot`, the points may be read from a data file or
11050 result from evaluation of a function at specified intervals, see
11051 `set isosamples`. The surface may be approximated by connecting the points
11052 with straight line segments, see `set surface`, in which case the surface
11053 can be made opaque with `set hidden3d.` The orientation from which the 3d
11054 surface is viewed can be changed with `set view`.
11056 Additionally, for points in a grid format, `splot` can interpolate points
11057 having a common amplitude (see `set contour`) and can then connect those
11058 new points to display contour lines, either directly with straight-line
11059 segments or smoothed lines (see `set cntrparam`). Functions are already
11060 evaluated in a grid format, determined by `set isosamples` and `set samples`,
11061 while file data must either be in a grid format, as described in `data-file`,
11062 or be used to generate a grid (see `set dgrid3d`).
11064 Contour lines may be displayed either on the surface or projected onto the
11065 base. The base projections of the contour lines may be written to a
11066 file, and then read with `plot`, to take advantage of `plot`'s additional
11067 formatting capabilities.
11071 `system "command"` executes "command" using the standard shell. See `shell`.
11072 If called as a function, `system("command")` returns the resulting character
11073 stream from stdout as a string. One optional trailing newline is ignored.
11075 This can be used to import external functions into gnuplot scripts:
11077 f(x) = real(system(sprintf("somecommand %f", x)))
11082 This command graphically tests or presents terminal and palette capabilities.
11085 test {terminal | palette [rgb|rbg|grb|gbr|brg|bgr]}
11087 `test` or `test terminal` creates a display of line and point styles and other
11088 useful things appropriate for and supported by the `terminal` you are just
11091 `test palette` draws graphically profiles R(z),G(z),B(z), where 0<=z<=1, as
11092 calculated by the current color `palette`. In other words, it is a beautiful
11093 plot you would have to do yourself with the result of `show palette palette 256 float`.
11094 The optional parameter, a permutation of letters rgb, determines the sequence of
11095 r,g,b profiles drawn one after the other --- try this yourself for `set palette
11096 gray`. The default sequence is rgb.
11100 Clear one or more previously defined user variables. This is useful in order
11101 to reset the state of a script containing an initialization test.
11105 undefine foo foo1 foo2
11106 if (!exists("foo")) load "initialize.gp"
11111 Options set using the `set` command may be returned to their default state by
11112 issuing the corresponding `unset` command.
11115 set xtics mirror rotate by -45 0,10,100
11122 This command writes the current values of the fit parameters into the given
11123 file, formatted as an initial-value file (as described in the `fit`section).
11124 This is useful for saving the current values for later use or for restarting
11125 a converged or stopped fit.
11128 update <filename> {<filename>}
11130 If a second filename is supplied, the updated values are written to this
11131 file, and the original parameter file is left unmodified.
11133 Otherwise, if the file already exists, `gnuplot` first renames it by
11134 appending `.old` and then opens a new file. That is, "`update 'fred'`"
11135 behaves the same as "`!rename fred fred.old; update 'fred.old' 'fred'`".
11136 [On DOS and other systems that use the twelve-character "filename.ext"
11137 naming convention, "ext" will be "`old`" and "filename" will be related
11138 (hopefully recognizably) to the initial name. Renaming is not done at all
11139 on VMS systems, since they use file-versioning.]
11141 Please see `fit` for more information.
11143 ^ <h2> Terminal Types </h2>
11147 Gnuplot supports a large number of output formats. These are selected by
11148 choosing an appropriate terminal type, possibly with additional modifying
11149 options. See `set terminal`.
11151 This document may describe terminal types that are not available to you
11152 because they were not configured or installed on your system. To see a list of
11153 terminals available on a particular gnuplot installation, type 'set terminal'
11155 <3 -- all terminal stuff is pulled from the .trm files
11156 1 Graphical User Interfaces
11157 ?graphical user interfaces
11159 Several graphical user interfaces have been written for `gnuplot` and one for
11160 win32 is included in this distribution. In addition, there is a Python
11162 ^ <a href="http://py-gnuplot.darwinports.com/">
11163 http://py-gnuplot.darwinports.com/
11166 Also several X11 interfaces exist.
11167 One of them is called xgfe. It uses the Qt library and can be found on
11168 ^ <a href="http://www.flash.net/~dmishee/xgfe/xgfe.html">
11169 http://www.flash.net/~dmishee/xgfe/xgfe.html
11172 In addition three Tcl/Tk located at the usual Tcl/Tk repositories exist.
11174 Bruce Ravel (ravel@phys.washington.edu) has written a new version of
11175 gnuplot-mode for GNU emacs and XEmacs. This version is based on
11176 the gnuplot.el file by Gershon Elber.
11177 While the gnuplot CVS repository has its own copy the most recent
11178 version of this package is available from
11179 ^ <a href="http://feff.phys.washington.edu/~ravel/software/gnuplot-mode/">
11180 http://feff.phys.washington.edu/~ravel/software/gnuplot-mode/
11185 Bugs reported since the current release as well as older ones
11186 may be located via the official distribution site on SourceForge.
11188 Please e-mail bug reports to the gnuplot-bugs mailing list.
11189 Or upload the report to the gnuplot web site on SourceForge.
11190 Please give complete information on the version of gnuplot you are using
11191 and, if possible, a test script that demonstrates the bug.
11192 See `Seeking-assistance`.
11194 The sections below list problems known to be present in gnuplot version 4.2 at
11195 the time of release. Some of these are actually bugs in external support
11196 libraries and may have been fixed indepently of any changes in gnuplot.
11198 2 Gnuplot limitations
11205 Floating point exceptions (floating point number too large/small, divide by
11206 zero, etc.) may occasionally be generated by user defined functions. Some of
11207 the demos in particular may cause numbers to exceed the floating point range.
11208 Whether the system ignores such exceptions (in which case `gnuplot` labels
11209 the corresponding point as undefined) or aborts `gnuplot` depends on the
11210 compiler/runtime environment.
11212 The gamma and bessel functions do not work for complex arguments.
11214 If a command line contains a "load" command, then anything on the line after
11215 the "load <filename>" is ignored.
11217 Only one color palette at a time is active for any given x11 plot window.
11218 This means that multiplots whose constituent plots use different palettes
11219 will not display correctly in x11.
11221 Coordinates specified as "time" wrap at 24 hours, and have a precision limited
11222 to 1 second. This is in particular a limitation in using time format to
11223 handle geographic coordinates.
11225 Error bars are not handled properly in polar/spherical coordinate plot modes.
11227 The 'nohidden3d' option that is supposed to exempt individual plots from the
11228 global property 'set hidden3d' does not work for parametric curves.
11230 2 External libraries
11231 ?bugs external_libraries
11235 =internationalization
11237 External library GD (used by PNG/JPEG/GIF drivers):
11238 Versions of libgd through 2.0.33 contain various bugs in mapping the characters
11239 of Adobe's Symbol font. Also it is possible to trigger a library segfault if
11240 an anti-aliased line crosses an upper corner of the canvas.
11242 External library PDFlib (used by PDF driver):
11243 Gnuplot can be linked against libpdf versions 4, 5, or 6. However, these
11244 versions differ in their handling of piped I/O. Therefore gnuplot scripts
11245 using piped output to PDF may work only for some versions of PDFlib.
11247 External library svgalib (used by linux and vgagl driver):
11248 Requires gnuplot to be suid root (bad!) and has many bugs that are specific
11249 to the video card or graphics driver used in X11.
11251 Internationalization (locale settings):
11252 Gnuplot uses the C runtime library routine setlocale() to control
11253 locale-specific formatting of input and output number, times, and date strings.
11254 The locales available, and the level of support for locale features such as
11255 "thousands' grouping separator", depend on the internationalization support
11256 provided by your individual machine.