Annotation of OpenXM_contrib/gnuplot/docs/gnuplot.doc, Revision 1.1.1.3
1.1.1.3 ! ohara 1: C RCS $Id: gnuplot.doc,v 1.20.2.10 2002/12/04 19:31:06 lhecking Exp $
1.1 maekawa 2: C 3 December 1998
3: C Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley
4: C
5: ^ <h2> An Interactive Plotting Program </h2><p>
6: ^ <h2> Thomas Williams & Colin Kelley</h2><p>
7: ^ <h2> Version 3.7 organized by: David Denholm </h2><p>
8: ^ <h2>Major contributors (alphabetic order):</h2>
9: ^<ul><h3>
10: ^<li> Hans-Bernhard Broeker
11: ^<li> John Campbell
12: ^<li> Robert Cunningham
13: ^<li> David Denholm
14: ^<li> Gershon Elber
15: ^<li> Roger Fearick
16: ^<li> Carsten Grammes
17: ^<li> Lucas Hart
18: ^<li> Lars Hecking
19: ^<li> Thomas Koenig
20: ^<li> David Kotz
21: ^<li> Ed Kubaitis
22: ^<li> Russell Lang
23: ^<li> Alexander Lehmann
24: ^<li> Alexander Mai
25: ^<li> Carsten Steger
26: ^<li> Tom Tkacik
27: ^<li> Jos Van der Woude
28: ^<li> James R. Van Zandt
29: ^<li> Alex Woo
30: ^</h3></ul> <p>
31: ^<h2> Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley<p>
32: ^ Mailing list for comments: info-gnuplot@dartmouth.edu <p>
33: ^ Mailing list for bug reports: bug-gnuplot@dartmouth.edu<p>
34: ^</h2><p>
35: ^<h3> This manual was prepared by Dick Crawford</h3><p>
36: ^<h3> 3 December 1998</h3><p>
37: ^<hr>
38: 1 gnuplot
39: 2 Copyright
40: ?copyright
41: ?license
42: Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley
43:
44: Permission to use, copy, and distribute this software and its
45: documentation for any purpose with or without fee is hereby granted,
46: provided that the above copyright notice appear in all copies and
47: that both that copyright notice and this permission notice appear
48: in supporting documentation.
49:
50: Permission to modify the software is granted, but not the right to
51: distribute the complete modified source code. Modifications are to
52: be distributed as patches to the released version. Permission to
53: distribute binaries produced by compiling modified sources is granted,
54: provided you
55: 1. distribute the corresponding source modifications from the
56: released version in the form of a patch file along with the binaries,
57: 2. add special version identification to distinguish your version
58: in addition to the base release version number,
59: 3. provide your name and address as the primary contact for the
60: support of your modified version, and
61: 4. retain our contact information in regard to use of the base
62: software.
63: Permission to distribute the released version of the source code along
64: with corresponding source modifications in the form of a patch file is
65: granted with same provisions 2 through 4 for binary distributions.
66:
67: This software is provided "as is" without express or implied warranty
68: to the extent permitted by applicable law.
69:
70:
71: AUTHORS
72:
73: Original Software:
74: Thomas Williams, Colin Kelley.
75:
76: Gnuplot 2.0 additions:
77: Russell Lang, Dave Kotz, John Campbell.
78:
79: Gnuplot 3.0 additions:
80: Gershon Elber and many others.
81: 2 Introduction
82: ?introduction
83: ?
84: `gnuplot` is a command-driven interactive function and data plotting program.
85: It is case sensitive (commands and function names written in lowercase are
86: not the same as those written in CAPS). All command names may be abbreviated
87: as long as the abbreviation is not ambiguous. Any number of commands may
88: appear on a line (with the exception that `load` or `call` must be the final
89: command), separated by semicolons (;). Strings are indicated with quotes.
90: They may be either single or double quotation marks, e.g.,
91:
92: load "filename"
93: cd 'dir'
94:
95: although there are some subtle differences (see `syntax` for more details).
96:
97: Any command-line arguments are assumed to be names of files containing
98: `gnuplot` commands, with the exception of standard X11 arguments, which are
99: processed first. Each file is loaded with the `load` command, in the order
100: specified. `gnuplot` exits after the last file is processed. When no load
101: files are named, `gnuplot` enters into an interactive mode. The special
102: filename "-" is used to denote standard input. See "help batch/interactive"
103: for more details.
104:
105: Many `gnuplot` commands have multiple options. These options must appear in
106: the proper order, although unwanted ones may be omitted in most cases. Thus
107: if the entire command is "command a b c", then "command a c" will probably
108: work, but "command c a" will fail.
109:
110: Commands may extend over several input lines by ending each line but the last
111: with a backslash (\). The backslash must be the _last_ character on each
112: line. The effect is as if the backslash and newline were not there. That
113: is, no white space is implied, nor is a comment terminated. Therefore,
114: commenting out a continued line comments out the entire command (see
115: `comment`). But note that if an error occurs somewhere on a multi-line
116: command, the parser may not be able to locate precisely where the error is
117: and in that case will not necessarily point to the correct line.
118:
119: In this document, curly braces ({}) denote optional arguments and a vertical
120: bar (|) separates mutually exclusive choices. `gnuplot` keywords or `help`
121: topics are indicated by backquotes or `boldface` (where available). Angle
122: brackets (<>) are used to mark replaceable tokens. In many cases, a default
123: value of the token will be taken for optional arguments if the token is
124: omitted, but these cases are not always denoted with braces around the angle
125: brackets.
126:
127: For on-line help on any topic, type `help` followed by the name of the topic
128: or just `help` or `?` to get a menu of available topics.
129:
130: The new `gnuplot` user should begin by reading about `plotting` (if on-line,
131: type `help plotting`).
1.1.1.2 maekawa 132: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/simple.html"> Simple Plots Demo </a>
1.1 maekawa 133: 2 Seeking-assistance
134: ?seeking-assistance
135: There is a mailing list for `gnuplot` users. Note, however, that the
136: newsgroup
137: comp.graphics.apps.gnuplot
138: is identical to the mailing list (they both carry the same set of messages).
139: We prefer that you read the messages through the newsgroup rather than
140: subscribing to the mailing list. Administrative requests should be sent to
141: majordomo@dartmouth.edu
142: Send a message with the body (not the subject) consisting of the single word
143: "help" (without the quotes) for more details.
144:
145: The address for mailing to list members is:
146: info-gnuplot@dartmouth.edu
147:
148: Bug reports and code contributions should be mailed to:
149: bug-gnuplot@dartmouth.edu
150:
151: The list of those interested in beta-test versions is:
152: info-gnuplot-beta@dartmouth.edu
153:
154: There is also a World Wide Web page with up-to-date information, including
155: known bugs:
156: ^ <a href="http://www.cs.dartmouth.edu/gnuplot_info.html">
157: http://www.cs.dartmouth.edu/gnuplot_info.html
158: ^ </a>
159:
160: Before seeking help, please check the
1.1.1.2 maekawa 161: ^ <a href="http://www.ucc.ie/gnuplot/gnuplot-faq.html">
1.1 maekawa 162: FAQ (Frequently Asked Questions) list.
163: ^ </a>
164: If you do not have a copy of the FAQ, you may request a copy by email from
165: the Majordomo address above, ftp a copy from
1.1.1.2 maekawa 166: ftp://ftp.ucc.ie/pub/gnuplot/faq,
167: ftp://ftp.gnuplot.vt.edu/pub/gnuplot/faq,
1.1 maekawa 168: or see the WWW `gnuplot` page.
169:
170: When posting a question, please include full details of the version of
171: `gnuplot`, the machine, and operating system you are using. A _small_ script
172: demonstrating the problem may be useful. Function plots are preferable to
173: datafile plots. If email-ing to info-gnuplot, please state whether or not
174: you are subscribed to the list, so that users who use news will know to email
175: a reply to you. There is a form for such postings on the WWW site.
176: 2 What's New in version 3.7
177: ?new-features
178: Gnuplot version 3.7 contains many new features. This section gives a partial
179: list and links to the new items in no particular order.
180:
181: 1. `fit f(x) 'file' via` uses the Marquardt-Levenberg method to fit data.
182: (This is only slightly different from the `gnufit` patch available for 3.5.)
183:
184: 2. Greatly expanded `using` command. See `plot using`.
185:
186: 3. `set timefmt` allows for the use of dates as input and output for time
187: series plots. See `Time/Date data` and
1.1.1.2 maekawa 188: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/timedat.html">
1.1 maekawa 189: timedat.dem.
190: ^ </a>
191:
192: 4. Multiline labels and font selection in some drivers.
193:
194: 5. Minor (unlabeled) tics. See `set mxtics`.
195:
196: 6. `key` options for moving the key box in the page (and even outside of the
197: plot), putting a title on it and a box around it, and more. See `set key`.
198:
199: 7. Multiplots on a single logical page with `set multiplot`.
200:
201: 8. Enhanced `postscript` driver with super/subscripts and font changes.
202: (This was a separate driver (`enhpost`) that was available as a patch for
203: 3.5.)
204:
205: 9. Second axes: use the top and right axes independently of the bottom and
206: left, both for plotting and labels. See `plot`.
207:
208: 10. Special datafile names `'-'` and `""`. See `plot special-filenames`.
209:
210: 11. Additional coordinate systems for labels and arrows. See `coordinates`.
211:
212: 12. `set size` can try to plot with a specified aspect ratio.
213:
214: 13. `set missing` now treats missing data correctly.
215:
216: 14. The `call` command: `load` with arguments.
217:
1.1.1.3 ! ohara 218: 15. More flexible `range` commands with `reverse`, `writeback` and 'restore'
! 219: keywords.
1.1 maekawa 220:
221: 16. `set encoding` for multi-lingual encoding.
222:
223: 17. New `x11` driver with persistent and multiple windows.
224:
225: 18. New plotting styles: `xerrorbars`, `histeps`, `financebars` and more.
226: See `set style`.
227:
228: 19. New tic label formats, including `"%l %L"` which uses the mantissa and
229: exponents to a given base for labels. See `set format`.
230:
231: 20. New drivers, including `cgm` for inclusion into MS-Office applications
232: and `gif` for serving plots to the WEB.
233:
234: 21. Smoothing and spline-fitting options for `plot`. See `plot smooth`.
235:
236: 22. `set margin` and `set origin` give much better control over where a
237: graph appears on the page.
238:
239: 23. `set border` now controls each border individually.
240:
241: 24. The new commands `if` and `reread` allow command loops.
242:
243: 25. Point styles and sizes, line types and widths can be specified on the
244: `plot` command. Line types and widths can also be specified for grids,
245: borders, tics and arrows. See `plot with`. Furthermore these types may be
246: combined and stored for further use. See `set linestyle`.
247:
248: 26. Text (labels, tic labels, and the time stamp) can be written vertically
249: by those terminals capable of doing so.
250: 2 Batch/Interactive Operation
251: ?batch/interactive
252: `gnuplot` may be executed in either batch or interactive modes, and the two
253: may even be mixed together on many systems.
254:
255: Any command-line arguments are assumed to be names of files containing
256: `gnuplot` commands (with the exception of standard X11 arguments, which are
257: processed first). Each file is loaded with the `load` command, in the order
258: specified. `gnuplot` exits after the last file is processed. When no load
259: files are named, `gnuplot` enters into an interactive mode. The special
260: filename "-" is used to denote standard input.
261:
262: Both the `exit` and `quit` commands terminate the current command file and
263: `load` the next one, until all have been processed.
264:
265: Examples:
266:
267: To launch an interactive session:
268: gnuplot
269:
270: To launch a batch session using two command files "input1" and "input2":
271: gnuplot input1 input2
272:
273: To launch an interactive session after an initialization file "header" and
274: followed by another command file "trailer":
275: gnuplot header - trailer
276: 2 Command-line-editing
277: ?line-editing
278: ?editing
279: ?history
280: ?command-line-editing
281: Command-line editing is supported by the Unix, Atari, VMS, MS-DOS and OS/2
282: versions of `gnuplot`. Also, a history mechanism allows previous commands to
283: be edited and re-executed. After the command line has been edited, a newline
284: or carriage return will enter the entire line without regard to where the
285: cursor is positioned.
286:
287: (The readline function in `gnuplot` is not the same as the readline used in
288: GNU Bash and GNU Emacs. If the GNU version is desired, it may be selected
289: instead of the `gnuplot` version at compile time.)
290:
291:
292: The editing commands are as follows:
293:
294: @start table - first is interactive cleartext form
295: `Line-editing`:
296:
297: ^B moves back a single character.
298: ^F moves forward a single character.
299: ^A moves to the beginning of the line.
300: ^E moves to the end of the line.
301: ^H and DEL delete the previous character.
302: ^D deletes the current character.
303: ^K deletes from current position to the end of line.
304: ^L,^R redraws line in case it gets trashed.
305: ^U deletes the entire line.
1.1.1.3 ! ohara 306: ^W deletes from the current word to the end of line.
1.1 maekawa 307:
308: `History`:
309:
310: ^P moves back through history.
311: ^N moves forward through history.
312: #\begin{tabular}{|cl|} \hline
313: #\multicolumn{2}{|c|}{Command-line Editing Commands} \\ \hline \hline
314: #Character & Function \\ \hline
315: # & \multicolumn{1}{|c|}{Line Editing}\\ \cline{2-2}
316: #\verb~^B~ & move back a single character.\\
317: #\verb~^F~ & move forward a single character.\\
318: #\verb~^A~ & move to the beginning of the line.\\
319: #\verb~^E~ & move to the end of the line.\\
320: #\verb~^H, DEL~ & delete the previous character.\\
321: #\verb~^D~ & delete the current character.\\
322: #\verb~^K~ & delete from current position to the end of line.\\
323: #\verb~^L, ^R~ & redraw line in case it gets trashed.\\
324: #\verb~^U~ & delete the entire line. \\
325: #\verb~^W~ & delete from the current word to the end of line. \\ \hline
326: # & \multicolumn{1}{|c|}{History} \\ \cline{2-2}
327: #\verb~^P~ & move back through history.\\
328: #\verb~^N~ & move forward through history.\\
329: %c l .
330: %Character@Function
331: %_
332: %@Line Editing
333: %^B@move back a single character.
334: %^F@move forward a single character.
335: %^A@move to the beginning of the line.
336: %^E@move to the end of the line.
337: %^H, DEL@delete the previous character.
338: %^D@delete the current character.
339: %^K@delete from current position to the end of line.
340: %^L, ^R@redraw line in case it gets trashed.
341: %^U@delete the entire line.
342: %^W@delete from the current word to the end of line.
343: %_
344: %@History
345: %^P@move back through history.
346: %^N@move forward through history.
347: @end table
348:
349: On the IBM PC, the use of a TSR program such as DOSEDIT or CED may be desired
350: for line editing. The default makefile assumes that this is the case; by
351: default `gnuplot` will be compiled with no line-editing capability. If you
352: want to use `gnuplot`'s line editing, set READLINE in the makefile and add
353: readline.obj to the link file. The following arrow keys may be used on the
354: IBM PC and Atari versions if readline is used:
355:
356: @start table - first is interactive cleartext form
357: Left Arrow - same as ^B.
358: Right Arrow - same as ^F.
359: Ctrl Left Arrow - same as ^A.
360: Ctrl Right Arrow - same as ^E.
361: Up Arrow - same as ^P.
362: Down Arrow - same as ^N.
363: #\begin{tabular}{|cl|} \hline
364: #Arrow key & Function \\ \hline
365: #Left & same as \verb~^B~. \\
366: #Right & same as \verb~^F~. \\
367: #Ctrl Left & same as \verb~^A~. \\
368: #Ctrl Right & same as \verb~^E~. \\
369: #Up & same as \verb~^P~. \\
370: #Down & same as \verb~^N~. \\
371: %c l .
372: %Arrow key@Function
373: %_
374: %Left Arrow@same as ^B.
375: %Right Arrow@same as ^F.
376: %Ctrl Left Arrow@same as ^A.
377: %Ctrl Right Arrow@same as ^E.
378: %Up Arrow@same as ^P.
379: %Down Arrow@same as ^N.
380: %_
381: @end table
382:
383: The Atari version of readline defines some additional key aliases:
384:
385: @start table - first is interactive cleartext form
386: Undo - same as ^L.
387: Home - same as ^A.
388: Ctrl Home - same as ^E.
389: Esc - same as ^U.
390: Help - `help` plus return.
391: Ctrl Help - `help `.
392: #\begin{tabular}{|cl|} \hline
1.1.1.3 ! ohara 393: #Key & Function \\ \hline
1.1 maekawa 394: #Undo & same as \verb~^L~. \\
395: #Home & same as \verb~^A~. \\
396: #Ctrl Home & same as \verb~^E~. \\
397: #Esc & same as \verb~^U~. \\
398: #Help & `{\bf help}' plus return. \\
399: #Ctrl Help & `{\bf help }'. \\
400: %c l .
1.1.1.3 ! ohara 401: %Key@Function
1.1 maekawa 402: %_
403: %Undo@same as ^L.
404: %Home@same as ^A.
405: %Ctrl Home@same as ^E.
406: %Esc@same as ^U.
407: %Help@help plus return.
408: %Ctrl Help@help .
409: %_
410: @end table
411: 2 Comments
412: ?comments
413: Comments are supported as follows: a `#` may appear in most places in a line
414: and `gnuplot` will ignore the rest of the line. It will not have this effect
415: inside quotes, inside numbers (including complex numbers), inside command
416: substitutions, etc. In short, it works anywhere it makes sense to work.
417: 2 Coordinates
418: ?coordinates
419: The commands `set arrow`, `set key`, and `set label` allow you to draw
420: something at an arbitrary position on the graph. This position is specified
421: by the syntax:
422:
423: {<system>} <x>, {<system>} <y> {,{<system>} <z>}
424:
425: Each <system> can either be `first`, `second`, `graph` or `screen`.
426:
427: `first` places the x, y, or z coordinate in the system defined by the left
428: and bottom axes; `second` places it in the system defined by the second axes
429: (top and right); `graph` specifies the area within the axes---0,0 is bottom
430: left and 1,1 is top right (for splot, 0,0,0 is bottom left of plotting area;
431: use negative z to get to the base---see `set ticslevel`); and `screen`
432: specifies the screen area (the entire area---not just the portion selected by
433: `set size`), with 0,0 at bottom left and 1,1 at top right.
434:
435: If the coordinate system for x is not specified, `first` is used. If the
436: system for y is not specified, the one used for x is adopted.
437:
438: If one (or more) axis is timeseries, the appropriate coordinate should
439: be given as a quoted time string according to the `timefmt` format string.
440: See `set xdata` and `set timefmt`. `gnuplot` will also accept an integer
441: expression, which will be interpreted as seconds from 1 January 2000.
442: 2 Environment
443: ?environment
444: A number of shell environment variables are understood by `gnuplot`. None of
445: these are required, but may be useful.
446:
447: If GNUTERM is defined, it is used as the name of the terminal type to be
448: used. This overrides any terminal type sensed by `gnuplot` on start-up, but
449: is itself overridden by the .gnuplot (or equivalent) start-up file (see
450: `start-up`) and, of course, by later explicit changes.
451:
452: On Unix, AmigaOS, AtariTOS, MS-DOS and OS/2, GNUHELP may be defined to be the
453: pathname of the HELP file (gnuplot.gih).
454:
455: On VMS, the logical name GNUPLOT$HELP should be defined as the name of the
456: help library for `gnuplot`. The `gnuplot` help can be put inside any system
457: help library, allowing access to help from both within and outside `gnuplot`
458: if desired.
459:
460: On Unix, HOME is used as the name of a directory to search for a .gnuplot
461: file if none is found in the current directory. On AmigaOS, AtariTOS,
462: MS-DOS and OS/2, gnuplot is used. On VMS, SYS$LOGIN: is used. See `help
463: start-up`.
464:
465: On Unix, PAGER is used as an output filter for help messages.
466:
467: On Unix, AtariTOS and AmigaOS, SHELL is used for the `shell` command. On
468: MS-DOS and OS/2, COMSPEC is used for the `shell` command.
469:
470: On MS-DOS, if the BGI or Watcom interface is used, PCTRM is used to tell
471: the maximum resolution supported by your monitor by setting it to
472: S<max. horizontal resolution>. E.g. if your monitor's maximum resolution is
473: 800x600, then use:
474: set PCTRM=S800
475: If PCTRM is not set, standard VGA is used.
476:
477: FIT_SCRIPT may be used to specify a `gnuplot` command to be executed when a
478: fit is interrupted---see `fit`. FIT_LOG specifies the filename of the
479: logfile maintained by fit.
480: 2 Expressions
481: ?expressions
482: In general, any mathematical expression accepted by C, FORTRAN, Pascal, or
483: BASIC is valid. The precedence of these operators is determined by the
484: specifications of the C programming language. White space (spaces and tabs)
485: is ignored inside expressions.
486:
487: Complex constants are expressed as {<real>,<imag>}, where <real> and <imag>
488: must be numerical constants. For example, {3,2} represents 3 + 2i; {0,1}
489: represents 'i' itself. The curly braces are explicitly required here.
490:
491: Note that gnuplot uses both "real" and "integer" arithmetic, like FORTRAN and
492: C. Integers are entered as "1", "-10", etc; reals as "1.0", "-10.0", "1e1",
493: 3.5e-1, etc. The most important difference between the two forms is in
494: division: division of integers truncates: 5/2 = 2; division of reals does
495: not: 5.0/2.0 = 2.5. In mixed expressions, integers are "promoted" to reals
496: before evaluation: 5/2e0 = 2.5. The result of division of a negative integer
497: by a positive one may vary among compilers. Try a test like "print -5/2" to
498: determine if your system chooses -2 or -3 as the answer.
499:
500: The integer expression "1/0" may be used to generate an "undefined" flag,
501: which causes a point to ignored; the `ternary` operator gives an example.
502:
503: The real and imaginary parts of complex expressions are always real, whatever
504: the form in which they are entered: in {3,2} the "3" and "2" are reals, not
505: integers.
506: 3 Functions
507: ?expressions functions
508: ?functions
509: The functions in `gnuplot` are the same as the corresponding functions in
510: the Unix math library, except that all functions accept integer, real, and
511: complex arguments, unless otherwise noted.
512:
513: For those functions that accept or return angles that may be given in either
514: degrees or radians (sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
515: atan2(x) and arg(z)), the unit may be selected by `set angles`, which
516: defaults to radians.
517:
518: @start table
519: #\begin{tabular}{|ccl|} \hline
520: #\multicolumn{3}{|c|}{Math library functions} \\ \hline \hline
521: #Function & Arguments & Returns \\ \hline
522: %c c l .
523: %Function@Arguments@Returns
524: %_
525: 4 abs
526: ?expressions functions abs
527: ?functions abs
528: ?abs
529: #abs(x) & any & absolute value of $x$, $|x|$; same type \\
530: #abs(x) & complex & length of $x$, $\sqrt{{\mbox{real}(x)^{2} +
531: #\mbox{imag}(x)^{2}}}$ \\
532: %abs(x)@any@absolute value of $x$, $|x|$; same type
533: %abs(x)@complex@length of $x$, $sqrt{roman real (x) sup 2 + roman imag (x) sup 2}$
1.1.1.2 maekawa 534: The `abs(x)` function returns the absolute value of its argument. The
535: returned value is of the same type as the argument.
1.1 maekawa 536:
537: For complex arguments, abs(x) is defined as the length of x in the complex
538: plane [i.e., sqrt(real(x)**2 + imag(x)**2) ].
539: 4 acos
540: ?expressions functions acos
541: ?functions acos
542: ?acos
543: #acos(x) & any & $\cos^{-1} x$ (inverse cosine) \\
544: %acos(x)@any@$cos sup -1 x$ (inverse cosine)
1.1.1.2 maekawa 545: The `acos(x)` function returns the arc cosine (inverse cosine) of its
546: argument. `acos` returns its argument in radians or degrees, as selected by
547: `set angles`.
1.1 maekawa 548: 4 acosh
549: ?expressions functions acosh
550: ?functions acosh
551: ?acosh
552: #acosh(x) & any & $\cosh^{-1} x$ (inverse hyperbolic cosine) in radians \\
553: %acosh(x)@any@$cosh sup -1 x$ (inverse hyperbolic cosine) in radians
1.1.1.2 maekawa 554: The `acosh(x)` function returns the inverse hyperbolic cosine of its argument
555: in radians.
1.1 maekawa 556: 4 arg
557: ?expressions functions arg
558: ?functions arg
559: ?arg
560: #arg(x) & complex & the phase of $x$ \\
561: %arg(x)@complex@the phase of $x$
1.1.1.2 maekawa 562: The `arg(x)` function returns the phase of a complex number in radians or
1.1 maekawa 563: degrees, as selected by `set angles`.
564: 4 asin
565: ?expressions functions asin
566: ?functions asin
567: ?asin
568: #asin(x) & any & $\sin^{-1} x$ (inverse sin) \\
569: %asin(x)@any@$sin sup -1 x$ (inverse sin)
1.1.1.2 maekawa 570: The `asin(x)` function returns the arc sin (inverse sin) of its argument.
1.1 maekawa 571: `asin` returns its argument in radians or degrees, as selected by `set
572: angles`.
573: 4 asinh
574: ?expressions functions asinh
575: ?functions asinh
576: ?asinh
577: #asinh(x) & any & $\sinh^{-1} x$ (inverse hyperbolic sin) in radians \\
578: %asinh(x)@any@$sinh sup -1 x$ (inverse hyperbolic sin) in radians
1.1.1.2 maekawa 579: The `asinh(x)` function returns the inverse hyperbolic sin of its argument in
1.1 maekawa 580: radians.
581: 4 atan
582: ?expressions functions atan
583: ?functions atan
584: ?atan
585: #atan(x) & any & $\tan^{-1} x$ (inverse tangent) \\
586: %atan(x)@any@$tan sup -1 x$ (inverse tangent)
1.1.1.2 maekawa 587: The `atan(x)` function returns the arc tangent (inverse tangent) of its
1.1 maekawa 588: argument. `atan` returns its argument in radians or degrees, as selected by
589: `set angles`.
590: 4 atan2
591: ?expressions functions atan2
592: ?functions atan2
593: ?atan2
594: #atan2(y,x) & int or real & $\tan^{-1} (y/x)$ (inverse tangent) \\
595: %atan2(y,x)@int or real@$tan sup -1 (y/x)$ (inverse tangent)
1.1.1.2 maekawa 596: The `atan2(y,x)` function returns the arc tangent (inverse tangent) of the
597: ratio of the real parts of its arguments. `atan2` returns its argument in
598: radians or degrees, as selected by `set angles`, in the correct quadrant.
1.1 maekawa 599: 4 atanh
600: ?expressions functions atanh
601: ?functions atanh
1.1.1.2 maekawa 602: ?atanh
1.1 maekawa 603: #atanh(x) & any & $\tanh^{-1} x$ (inverse hyperbolic tangent) in radians \\
604: %atanh(x)@any@$tanh sup -1 x$ (inverse hyperbolic tangent) in radians
1.1.1.2 maekawa 605: The `atanh(x)` function returns the inverse hyperbolic tangent of its
606: argument in radians.
1.1 maekawa 607: 4 besj0
608: ?expressions functions besj0
609: ?functions besj0
610: ?besj0
611: #besj0(x) & int or real & $j_{0}$ Bessel function of $x$, in radians \\
612: %besj0(x)@int or real@$j sub 0$ Bessel function of $x$, in radians
1.1.1.2 maekawa 613: The `besj0(x)` function returns the j0th Bessel function of its argument.
1.1 maekawa 614: `besj0` expects its argument to be in radians.
615: 4 besj1
616: ?expressions functions besj1
617: ?functions besj1
618: ?besj1
619: #besj1(x) & int or real & $j_{1}$ Bessel function of $x$, in radians \\
620: %besj1(x)@int or real@$j sub 1$ Bessel function of $x$, in radians
1.1.1.2 maekawa 621: The `besj1(x)` function returns the j1st Bessel function of its argument.
1.1 maekawa 622: `besj1` expects its argument to be in radians.
623: 4 besy0
624: ?expressions functions besy0
625: ?functions besy0
626: ?besy0
627: #besy0(x) & int or real & $y_{0}$ Bessel function of $x$, in radians \\
628: %besy0(x)@int or real@$y sub 0$ Bessel function of $x$, in radians
1.1.1.3 ! ohara 629: The `besy0(x)` function returns the y0th Bessel function of its argument.
1.1 maekawa 630: `besy0` expects its argument to be in radians.
631: 4 besy1
632: ?expressions functions besy1
633: ?functions besy1
634: ?besy1
635: #besy1(x) & int or real & $y_{1}$ Bessel function of $x$, in radians \\
636: %besy1(x)@int or real@$y sub 1$ Bessel function of $x$, in radians
1.1.1.2 maekawa 637: The `besy1(x)` function returns the y1st Bessel function of its argument.
1.1 maekawa 638: `besy1` expects its argument to be in radians.
639: 4 ceil
640: ?expressions functions ceil
641: ?functions ceil
642: ?ceil
643: #ceil(x) & any & $\lceil x \rceil$, smallest integer not less than $x$
644: #(real part) \\
645: %ceil(x)@any@$left ceiling x right ceiling$, smallest integer not less than $x$ (real part)
1.1.1.2 maekawa 646: The `ceil(x)` function returns the smallest integer that is not less than its
1.1 maekawa 647: argument. For complex numbers, `ceil` returns the smallest integer not less
648: than the real part of its argument.
649: 4 cos
650: ?expressions functions cos
651: ?functions cos
652: ?cos
653: #cos(x) & any & $\cos x$, cosine of $x$ \\
654: %cos(x)@radians@$cos~x$, cosine of $x$
1.1.1.2 maekawa 655: The `cos(x)` function returns the cosine of its argument. `cos` accepts its
1.1 maekawa 656: argument in radians or degrees, as selected by `set angles`.
657: 4 cosh
658: ?expressions functions cosh
659: ?functions cosh
660: ?cosh
661: #cosh(x) & any & $\cosh x$, hyperbolic cosine of $x$ in radians \\
662: %cosh(x)@any@$cosh~x$, hyperbolic cosine of $x$ in radians
1.1.1.2 maekawa 663: The `cosh(x)` function returns the hyperbolic cosine of its argument. `cosh`
1.1 maekawa 664: expects its argument to be in radians.
665: 4 erf
666: ?expressions functions erf
667: ?functions erf
668: ?erf
669: #erf(x) & any & $\mbox{erf}(\mbox{real}(x))$, error function of real($x$) \\
670: %erf(x)@any@$erf ( roman real (x))$, error function of real ($x$)
1.1.1.2 maekawa 671: The `erf(x)` function returns the error function of the real part of its
1.1 maekawa 672: argument. If the argument is a complex value, the imaginary component is
673: ignored.
674: 4 erfc
675: ?expressions functions erfc
676: ?functions erfc
677: ?erfc
678: #erfc(x) & any & $\mbox{erfc}(\mbox{real}(x))$, 1.0 - error function of real($x$) \\
679: %erfc(x)@any@$erfc ( roman real (x))$, 1.0 - error function of real ($x$)
1.1.1.2 maekawa 680: The `erfc(x)` function returns 1.0 - the error function of the real part of
681: its argument. If the argument is a complex value, the imaginary component is
1.1 maekawa 682: ignored.
683: 4 exp
684: ?expressions functions exp
685: ?functions exp
686: ?exp
687: #exp(x) & any & $e^{x}$, exponential function of $x$ \\
688: %exp(x)@any@$e sup x$, exponential function of $x$
1.1.1.2 maekawa 689: The `exp(x)` function returns the exponential function of its argument (`e`
1.1 maekawa 690: raised to the power of its argument). On some implementations (notably
691: suns), exp(-x) returns undefined for very large x. A user-defined function
692: like safe(x) = x<-100 ? 0 : exp(x) might prove useful in these cases.
693: 4 floor
694: ?expressions functions floor
695: ?functions floor
696: ?floor
697: #floor(x) & any & $\lfloor x \rfloor$, largest integer not greater
698: #than $x$ (real part) \\
699: %floor(x)@any@$left floor x right floor$, largest integer not greater than $x$ (real part)
1.1.1.2 maekawa 700: The `floor(x)` function returns the largest integer not greater than its
1.1 maekawa 701: argument. For complex numbers, `floor` returns the largest integer not
702: greater than the real part of its argument.
703: 4 gamma
704: ?expressions functions gamma
705: ?functions gamma
706: ?gamma
707: #gamma(x) & any & $\mbox{gamma}(\mbox{real}(x))$, gamma function of real($x$) \\
708: %gamma(x)@any@$GAMMA ( roman real (x))$, gamma function of real ($x$)
1.1.1.2 maekawa 709: The `gamma(x)` function returns the gamma function of the real part of its
1.1 maekawa 710: argument. For integer n, gamma(n+1) = n!. If the argument is a complex
711: value, the imaginary component is ignored.
712: 4 ibeta
713: ?expressions functions ibeta
714: ?functions ibeta
715: ?ibeta
716: #ibeta(p,q,x) & any & $\mbox{ibeta}(\mbox{real}(p,q,x))$, ibeta function of real($p$,$q$,$x$) \\
717: %ibeta(p,q,x)@any@$ibeta ( roman real (p,q,x))$, ibeta function of real ($p$,$q$,$x$)
1.1.1.2 maekawa 718: The `ibeta(p,q,x)` function returns the incomplete beta function of the real
719: parts of its arguments. p, q > 0 and x in [0:1]. If the arguments are
720: complex, the imaginary components are ignored.
1.1 maekawa 721: 4 inverf
722: ?expressions functions inverf
723: ?functions inverf
724: ?inverf
725: #inverf(x) & any & inverse error function of real($x$) \\
726: %inverf(x)@any@inverse error function real($x$)
1.1.1.2 maekawa 727: The `inverf(x)` function returns the inverse error function of the real part
1.1 maekawa 728: of its argument.
729: 4 igamma
730: ?expressions functions igamma
731: ?functions igamma
732: ?igamma
733: #igamma(a,x) & any & $\mbox{igamma}(\mbox{real}(a,x))$, igamma function of real($a$,$x$) \\
734: %igamma(a,x)@any@$igamma ( roman real (a,x))$, igamma function of real ($a$,$x$)
1.1.1.2 maekawa 735: The `igamma(a,x)` function returns the incomplete gamma function of the real
1.1 maekawa 736: parts of its arguments. a > 0 and x >= 0. If the arguments are complex,
737: the imaginary components are ignored.
738: 4 imag
739: ?expressions functions imag
740: ?functions imag
741: ?imag
742: #imag(x) & complex & imaginary part of $x$ as a real number \\
743: %imag(x)@complex@imaginary part of $x$ as a real number
1.1.1.2 maekawa 744: The `imag(x)` function returns the imaginary part of its argument as a real
1.1 maekawa 745: number.
746: 4 invnorm
747: ?expressions functions invnorm
748: ?functions invnorm
749: ?invnorm
750: #invnorm(x) & any & inverse normal distribution function of real($x$) \\
751: %invnorm(x)@any@inverse normal distribution function real($x$)
1.1.1.2 maekawa 752: The `invnorm(x)` function returns the inverse normal distribution function of
1.1 maekawa 753: the real part of its argument.
754: 4 int
755: ?expressions functions int
756: ?functions int
757: ?int
758: #int(x) & real & integer part of $x$, truncated toward zero \\
759: %int(x)@real@integer part of $x$, truncated toward zero
1.1.1.2 maekawa 760: The `int(x)` function returns the integer part of its argument, truncated
1.1 maekawa 761: toward zero.
762: 4 lgamma
763: ?expressions functions lgamma
764: ?functions lgamma
765: ?lgamma
766: #lgamma(x) & any & $\mbox{lgamma}(\mbox{real}(x))$, lgamma function of real($x$) \\
767: %lgamma(x)@any@$lgamma ( roman real (x))$, lgamma function of real ($x$)
1.1.1.2 maekawa 768: The `lgamma(x)` function returns the natural logarithm of the gamma function
1.1 maekawa 769: of the real part of its argument. If the argument is a complex value, the
770: imaginary component is ignored.
771: 4 log
772: ?expressions functions log
773: ?functions log
774: ?log
775: #log(x) & any & $\log_{e} x$, natural logarithm (base $e$) of $x$ \\
776: %log(x)@any@$ln~x$, natural logarithm (base $e$) of $x$
1.1.1.2 maekawa 777: The `log(x)` function returns the natural logarithm (base `e`) of its
778: argument.
1.1 maekawa 779: 4 log10
780: ?expressions functions log10
781: ?functions log10
782: ?log10
783: #log10(x) & any & $\log_{10} x$, logarithm (base $10$) of $x$ \\
784: %log10(x)@any@${log sub 10}~x$, logarithm (base $10$) of $x$
1.1.1.2 maekawa 785: The `log10(x)` function returns the logarithm (base 10) of its argument.
1.1 maekawa 786: 4 norm
787: ?expressions functions norm
788: ?functions norm
789: ?norm
790: #norm(x) & any & normal distribution (Gaussian) function of real($x$) \\
791: %norm(x)@any@$norm(x)$, normal distribution function of real($x$)
1.1.1.2 maekawa 792: The `norm(x)` function returns the normal distribution function (or Gaussian)
1.1 maekawa 793: of the real part of its argument.
794: 4 rand
795: ?expressions functions rand
796: ?functions rand
797: ?rand
798: #rand(x) & any & $\mbox{rand}(\mbox{real}(x))$, pseudo random number generator \\
799: %rand(x)@any@$rand ( roman real (x))$, pseudo random number generator
1.1.1.2 maekawa 800: The `rand(x)` function returns a pseudo random number in the interval [0:1]
1.1 maekawa 801: using the real part of its argument as a seed. If seed < 0, the sequence
802: is (re)initialized. If the argument is a complex value, the imaginary
803: component is ignored.
804: 4 real
805: ?expressions functions real
806: ?functions real
807: ?real
808: #real(x) & any & real part of $x$ \\
809: %real(x)@any@real part of $x$
1.1.1.2 maekawa 810: The `real(x)` function returns the real part of its argument.
1.1 maekawa 811: 4 sgn
812: ?expressions functions sgn
813: ?functions sgn
814: ?sgn
815: #sgn(x) & any & 1 if $x>0$, -1 if $x<0$, 0 if $x=0$. imag($x$) ignored \\
816: %sgn(x)@any@1 if $x > 0$, -1 if $x < 0$, 0 if $x = 0$. $roman imag (x)$ ignored
1.1.1.2 maekawa 817: The `sgn(x)` function returns 1 if its argument is positive, -1 if its
818: argument is negative, and 0 if its argument is 0. If the argument is a
819: complex value, the imaginary component is ignored.
1.1 maekawa 820: 4 sin
821: ?expressions functions sin
822: ?functions sin
823: ?sin
824: #sin(x) & any & $\sin x$, sine of $x$ \\
825: %sin(x)@any@$sin~x$, sine of $x$
1.1.1.2 maekawa 826: The `sin(x)` function returns the sine of its argument. `sin` expects its
1.1 maekawa 827: argument to be in radians or degrees, as selected by `set angles`.
828: 4 sinh
829: ?expressions functions sinh
830: ?functions sinh
831: ?sinh
1.1.1.3 ! ohara 832: #sinh(x) & any & $\sinh x$, hyperbolic sine of $x$ in radians \\
! 833: %sinh(x)@any@$sinh~x$, hyperbolic sine of $x$ in radians
1.1.1.2 maekawa 834: The `sinh(x)` function returns the hyperbolic sine of its argument. `sinh`
1.1 maekawa 835: expects its argument to be in radians.
836: 4 sqrt
837: ?expressions functions sqrt
838: ?functions sqrt
839: ?sqrt
840: #sqrt(x) & any & $\sqrt{x}$, square root of $x$ \\
841: %sqrt(x)@any@$sqrt x $, square root of $x$
1.1.1.2 maekawa 842: The `sqrt(x)` function returns the square root of its argument.
1.1 maekawa 843: 4 tan
844: ?expressions functions tan
845: ?functions tan
846: ?tan
847: #tan(x) & any & $\tan x$, tangent of $x$ \\
848: %tan(x)@any@$tan~x$, tangent of $x$
1.1.1.2 maekawa 849: The `tan(x)` function returns the tangent of its argument. `tan` expects
1.1 maekawa 850: its argument to be in radians or degrees, as selected by `set angles`.
851: 4 tanh
852: ?expressions functions tanh
853: ?functions tanh
854: ?tanh
855: #tanh(x) & any & $\tanh x$, hyperbolic tangent of $x$ in radians\\
856: %tanh(x)@any@$tanh~x$, hyperbolic tangent of $x$ in radians
1.1.1.2 maekawa 857: The `tanh(x)` function returns the hyperbolic tangent of its argument. `tanh`
1.1 maekawa 858: expects its argument to be in radians.
859: @end table
860:
861: A few additional functions are also available.
862:
863: @start table
864: #\begin{tabular}{|ccl|} \hline
865: #\multicolumn{3}{|c|}{other {\bf gnuplot} functions} \\ \hline \hline
866: #Function & Arguments & Returns \\ \hline
867: %c c l .
868: %Function@Arguments@Returns
869: %_
870: 4 column
871: ?expressions functions column
872: ?functions column
873: ?column
874: #column(x) & int & column $x$ during datafile manipulation. \\
875: %column(x)@int@ column $x$ during datafile manipulation.
876: `column(x)` may be used only in expressions as part of `using` manipulations
877: to fits or datafile plots. See `plot datafile using`.
878: 4 tm_hour
879: ?expressions tm_hour
880: ?functions tm_hour
881: #tm\_hour(x) & int & the hour \\
882: %tm_hour(x)@int@the hour
883: The `tm_hour` function interprets its argument as a time, in seconds from
884: 1 Jan 2000. It returns the hour (an integer in the range 0--23) as a real.
885: 4 tm_mday
886: ?expressions tm_mday
887: ?functions tm_mday
888: #tm\_mday(x) & int & the day of the month \\
889: %tm_mday(x)@int@the day of the month
890: The `tm_mday` function interprets its argument as a time, in seconds from
891: 1 Jan 2000. It returns the day of the month (an integer in the range 1--31)
892: as a real.
893: 4 tm_min
894: ?expressions tm_min
895: ?functions tm_min
896: #tm\_min(x) & int & the minute \\
897: %tm_min(x)@int@the minute
898: The `tm_min` function interprets its argument as a time, in seconds from
899: 1 Jan 2000. It returns the minute (an integer in the range 0--59) as a real.
900: 4 tm_mon
901: ?expressions tm_mon
902: ?functions tm_mon
903: #tm\_mon(x) & int & the month \\
904: %tm_mon(x)@int@the month
905: The `tm_mon` function interprets its argument as a time, in seconds from
906: 1 Jan 2000. It returns the month (an integer in the range 1--12) as a real.
907: 4 tm_sec
908: ?expressions tm_sec
909: ?functions tm_sec
910: #tm\_sec(x) & int & the second \\
911: %tm_sec(x)@int@the second
912: The `tm_sec` function interprets its argument as a time, in seconds from
913: 1 Jan 2000. It returns the second (an integer in the range 0--59) as a real.
914: 4 tm_wday
915: ?expressions tm_wday
916: ?functions tm_wday
917: #tm\_wday(x) & int & the day of the week \\
918: %tm_wday(x)@int@the day of the week
919: The `tm_wday` function interprets its argument as a time, in seconds from
920: 1 Jan 2000. It returns the day of the week (an integer in the range 1--7) as
921: a real.
922: 4 tm_yday
923: ?expressions tm_yday
924: ?functions tm_yday
925: #tm\_yday(x) & int & the day of the year \\
926: %tm_yday(x)@int@the day of the year
927: The `tm_yday` function interprets its argument as a time, in seconds from
928: 1 Jan 2000. It returns the day of the year (an integer in the range 1--366)
929: as a real.
930: 4 tm_year
931: ?expressions tm_year
932: ?functions tm_year
933: #tm\_year(x) & int & the year \\
934: %tm_year(x)@int@the year
935: The `tm_year` function interprets its argument as a time, in seconds from
936: 1 Jan 2000. It returns the year (an integer) as a real.
937: 4 valid
938: ?expressions functions valid
939: ?functions valid
940: ?valid
941: #valid(x) & int & test validity of $\mbox{column}(x)$ during datafile manip.\\
942: %valid(x)@int@ test validity of column($x$) during datafile manip.
943: `valid(x)` may be used only in expressions as part of `using` manipulations
944: to fits or datafile plots. See `plot datafile using`.
945: @end table
1.1.1.2 maekawa 946: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html">Use of functions and complex variables for airfoils </a>
1.1 maekawa 947: 3 Operators
948: ?expressions operators
949: ?operators
950: The operators in `gnuplot` are the same as the corresponding operators in the
951: C programming language, except that all operators accept integer, real, and
952: complex arguments, unless otherwise noted. The ** operator (exponentiation)
953: is supported, as in FORTRAN.
954:
955: Parentheses may be used to change order of evaluation.
956: 4 Unary
957: ?expressions operators unary
958: ?operators unary
959: ?unary
960: The following is a list of all the unary operators and their usages:
961:
962: @start table - first is interactive cleartext form
963: Symbol Example Explanation
964: - -a unary minus
965: + +a unary plus (no-operation)
966: ~ ~a * one's complement
967: ! !a * logical negation
968: ! a! * factorial
969: $ $3 * call arg/column during `using` manipulation
970: #\begin{tabular}{|ccl|} \hline
971: #\multicolumn{3}{|c|}{Unary Operators}\\ \hline \hline
972: #Symbol & Example & Explanation \\ \hline
973: #\verb@-@ & \verb@-a@ & unary minus \\
974: #\verb@+@ & \verb@+a@ & unary plus (no-operation) \\
975: #\verb@~@ & \verb@~a@ & * one's complement \\
976: #\verb@!@ & \verb@!a@ & * logical negation \\
977: #\verb@!@ & \verb@a!@ & * factorial \\
978: #\verb@$@ & \verb@$3@ & * call arg/column during `using` manipulation \\
979: C ugly hack: doc2ms uses $ as delimiter for eqn's so it doesn't seem to
980: C be able to print them. So we have to typeset this table without using
981: C eqn (at least that's the only solution I found, without any real docs
982: C on *roff and eqn
983: C First, terminate the table doc2ms.c already started:
984: %.TE
985: C ... then turn off eqn delimiters:
986: %.EQ
987: %delim off
988: %.EN
989: C ... and restart the table:
990: %.TS
991: %center box tab (@) ;
992: %c c l .
993: %Symbol@Example@Explanation
994: %_
995: %-@-a@unary minus
996: %+@+a@unary plus (no-operation)
997: %~@~a@* one's complement
998: %!@!a@* logical negation
999: %!@a!@* factorial
1000: %$@$3@* call arg/column during `using` manipulation
1001: %_
1002: @end table
1003: (*) Starred explanations indicate that the operator requires an integer
1004: argument.
1005:
1006: Operator precedence is the same as in Fortran and C. As in those languages,
1007: parentheses may be used to change the order of operation. Thus -2**2 = -4,
1008: but (-2)**2 = 4.
1009:
1010: The factorial operator returns a real number to allow a greater range.
1011: 4 Binary
1012: ?expressions operators binary
1013: ?operators binary
1014: ?binary
1015: The following is a list of all the binary operators and their usages:
1016:
1017: @start table - first is interactive cleartext form
1018: Symbol Example Explanation
1019: ** a**b exponentiation
1020: * a*b multiplication
1021: / a/b division
1022: % a%b * modulo
1023: + a+b addition
1024: - a-b subtraction
1025: == a==b equality
1026: != a!=b inequality
1027: < a<b less than
1028: <= a<=b less than or equal to
1029: > a>b greater than
1030: >= a>=b greater than or equal to
1031: & a&b * bitwise AND
1032: ^ a^b * bitwise exclusive OR
1033: | a|b * bitwise inclusive OR
1034: && a&&b * logical AND
1035: || a||b * logical OR
1036: #\begin{tabular}{|ccl|} \hline
1037: #\multicolumn{3}{|c|}{Binary Operators} \\ \hline \hline
1038: #Symbol & Example & Explanation \\ \hline
1039: #\verb~**~ & \verb~a**b~ & exponentiation\\
1040: #\verb~*~ & \verb~a*b~ & multiplication\\
1041: #\verb~/~ & \verb~a/b~ & division\\
1042: #\verb~%~ & \verb~a%b~ & * modulo\\
1043: #\verb~+~ & \verb~a+b~ & addition\\
1044: #\verb~-~ & \verb~a-b~ & subtraction\\
1045: #\verb~==~ & \verb~a==b~ & equality\\
1046: #\verb~!=~ & \verb~a!=b~ & inequality\\
1047: #\verb~<~ & \verb~a<b~ & less than\\
1048: #\verb~<=~ & \verb~a<=b~ & less than or equal to\\
1049: #\verb~>~ & \verb~a>b~ & greater than\\
1050: #\verb~>=~ & \verb~a>=b~ & greater than or equal to\\
1051: #\verb~&~ & \verb~a&b~ & * bitwise AND\\
1052: #\verb~^~ & \verb~a^b~ & * bitwise exclusive OR\\
1053: #\verb~|~ & \verb~a|b~ & * bitwise inclusive OR\\
1054: #\verb~&&~ & \verb~a&&b~ & * logical AND\\
1055: #\verb~||~ & \verb~a||b~ & * logical OR\\
1056: %c c l .
1057: %Symbol@Example@Explanation
1058: %_
1059: %**@a**b@exponentiation
1060: %*@a*b@multiplication
1061: %/@a/b@division
1062: %%@a%b@* modulo
1063: %+@a+b@addition
1064: %-@a-b@subtraction
1065: %==@a==b@equality
1066: %!=@a!=b@inequality
1067: %<@a<b@less than
1068: %<=@a<=b@less than or equal to
1069: %>@a>b@greater than
1070: %>=@a>=b@greater than or equal to
1071: %&@a&b@* bitwise AND
1072: %^@a^b@* bitwise exclusive OR
1073: %|@a|b@* bitwise inclusive OR
1074: %&&@a&&b@* logical AND
1075: %||@a||b@* logical OR
1076:
1077: @end table
1078: (*) Starred explanations indicate that the operator requires integer
1079: arguments.
1080:
1081: Logical AND (&&) and OR (||) short-circuit the way they do in C. That is,
1082: the second `&&` operand is not evaluated if the first is false; the second
1083: `||` operand is not evaluated if the first is true.
1084: 4 Ternary
1085: ?expressions operators ternary
1086: ?operators ternary
1087: ?ternary
1088: There is a single ternary operator:
1089:
1090: @start table - first is interactive cleartext form
1091: Symbol Example Explanation
1092: ?: a?b:c ternary operation
1093: #\begin{tabular}{|ccl|} \hline
1094: #\multicolumn{3}{|c|}{Ternary Operator} \\ \hline \hline
1095: #Symbol & Example & Explanation \\ \hline
1096: #\verb~?:~ & \verb~a?b:c~ & ternary operation\\
1097: %c c l .
1098: %Symbol@Example@Explanation
1099: %_
1100: %?:@a?b:c@* ternary operation
1101:
1102: @end table
1103: The ternary operator behaves as it does in C. The first argument (a), which
1104: must be an integer, is evaluated. If it is true (non-zero), the second
1105: argument (b) is evaluated and returned; otherwise the third argument (c) is
1106: evaluated and returned.
1107:
1108: The ternary operator is very useful both in constructing piecewise functions
1109: and in plotting points only when certain conditions are met.
1110:
1111: Examples:
1112:
1113: Plot a function that is to equal sin(x) for 0 <= x < 1, 1/x for 1 <= x < 2,
1114: and undefined elsewhere:
1115: f(x) = 0<=x && x<1 ? sin(x) : 1<=x && x<2 ? 1/x : 1/0
1116: plot f(x)
1117: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/ternary.gif" alt="[ternary.gif]" width=640 height=480>
1118: Note that `gnuplot` quietly ignores undefined values, so the final branch of
1119: the function (1/0) will produce no plottable points. Note also that f(x)
1120: will be plotted as a continuous function across the discontinuity if a line
1121: style is used. To plot it discontinuously, create separate functions for the
1122: two pieces. (Parametric functions are also useful for this purpose.)
1123:
1124: For data in a file, plot the average of the data in columns 2 and 3 against
1125: the datum in column 1, but only if the datum in column 4 is non-negative:
1126:
1127: plot 'file' using 1:( $4<0 ? 1/0 : ($2+$3)/2 )
1128:
1129: Please see `plot data-file using` for an explanation of the `using` syntax.
1130: 3 User-defined
1131: ?expressions user-defined
1132: ?user-defined
1133: ?variables
1134: New user-defined variables and functions of one through five variables may
1135: be declared and used anywhere, including on the `plot` command itself.
1136:
1137: User-defined function syntax:
1138: <func-name>( <dummy1> {,<dummy2>} ... {,<dummy5>} ) = <expression>
1139:
1140: where <expression> is defined in terms of <dummy1> through <dummy5>.
1141:
1142: User-defined variable syntax:
1143: <variable-name> = <constant-expression>
1144:
1145: Examples:
1146: w = 2
1147: q = floor(tan(pi/2 - 0.1))
1148: f(x) = sin(w*x)
1149: sinc(x) = sin(pi*x)/(pi*x)
1150: delta(t) = (t == 0)
1151: ramp(t) = (t > 0) ? t : 0
1152: min(a,b) = (a < b) ? a : b
1153: comb(n,k) = n!/(k!*(n-k)!)
1154: len3d(x,y,z) = sqrt(x*x+y*y+z*z)
1155: plot f(x) = sin(x*a), a = 0.2, f(x), a = 0.4, f(x)
1156:
1157: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/userdefined.gif" alt="[userdefined.gif]" width=640 height=480>
1158: Note that the variable `pi` is already defined. But it is in no way magic;
1159: you may redefine it to be whatever you like.
1160:
1161: Valid names are the same as in most programming languages: they must begin
1162: with a letter, but subsequent characters may be letters, digits, "$", or "_".
1163: Note, however, that the `fit` mechanism uses several variables with names
1164: that begin "FIT_". It is safest to avoid using such names. "FIT_LIMIT",
1165: however, is one that you may wish to redefine. See the documentation
1166: on `fit` for details.
1167:
1168:
1169: See `show functions`, `show variables`, and `fit`.
1170: 2 Glossary
1171: ?glossary
1172: Throughout this document an attempt has been made to maintain consistency of
1173: nomenclature. This cannot be wholly successful because as `gnuplot` has
1174: evolved over time, certain command and keyword names have been adopted that
1175: preclude such perfection. This section contains explanations of the way
1176: some of these terms are used.
1177:
1178: A "page" or "screen" is the entire area addressable by `gnuplot`. On a
1179: monitor, it is the full screen; on a plotter, it is a single sheet of paper.
1180:
1181: A screen may contain one or more "plots". A plot is defined by an abscissa
1182: and an ordinate, although these need not actually appear on it, as well as
1183: the margins and any text written therein.
1184:
1185: A plot contains one "graph". A graph is defined by an abscissa and an
1186: ordinate, although these need not actually appear on it.
1187:
1188: A graph may contain one or more "lines". A line is a single function or
1189: data set. "Line" is also a plotting style. The word will also be used in
1190: sense "a line of text". Presumably the context will remove any ambiguity.
1191:
1192: The lines on a graph may have individual names. These may be listed
1193: together with a sample of the plotting style used to represent them in
1194: the "key", sometimes also called the "legend".
1195:
1196: The word "title" occurs with multiple meanings in `gnuplot`. In this
1197: document, it will always be preceded by the adjective "plot", "line", or
1198: "key" to differentiate among them.
1199:
1200: A graph may have up to four labelled axes. Various commands have the name of
1201: an axis built into their names, such as `set xlabel`. Other commands have
1202: one or more axis names as options, such as `set logscale xy`. The names of
1203: the four axes for these usages are "x" for the axis along the bottom border
1204: of the plot, "y" for the left border, "x2" for the top border, and "y2" for
1205: the right border. "z" also occurs in commands used with 3-d plotting.
1206:
1207: When discussing data files, the term "record" will be resurrected and used
1208: to denote a single line of text in the file, that is, the characters between
1209: newline or end-of-record characters. A "point" is the datum extracted from
1210: a single record. A "datablock" is a set of points from consecutive records,
1211: delimited by blank records. A line, when referred to in the context of a
1212: data file, is a subset of a datablock.
1213: 2 Plotting
1214: ?plotting
1215: There are three `gnuplot` commands which actually create a plot: `plot`,
1216: `splot` and `replot`. `plot` generates 2-d plots, `splot` generates 3-d
1217: plots (actually 2-d projections, of course), and `replot` appends its
1218: arguments to the previous `plot` or `splot` and executes the modified
1219: command.
1220:
1221: Much of the general information about plotting can be found in the discussion
1222: of `plot`; information specific to 3-d can be found in the `splot` section.
1223:
1224: `plot` operates in either rectangular or polar coordinates -- see `set polar`
1225: for details of the latter. `splot` operates only in rectangular coordinates,
1226: but the `set mapping` command allows for a few other coordinate systems to be
1227: treated. In addition, the `using` option allows both `plot` and `splot` to
1228: treat almost any coordinate system you'd care to define.
1229:
1230: `splot` can plot surfaces and contours in addition to points and/or lines.
1231: In addition to `splot`, see `set isosamples` for information about defining
1232: the grid for a 3-d function; `splot datafile` for information about the
1233: requisite file structure for 3-d data values; and `set contour` and `set
1234: cntrparam` for information about contours.
1235: 2 Start-up
1236: ?startup
1237: ?start
1238: ?.gnuplot
1239: When `gnuplot` is run, it looks for an initialization file to load. This
1240: file is called `.gnuplot` on Unix and AmigaOS systems, and `GNUPLOT.INI` on
1241: other systems. If this file is not found in the current directory, the
1242: program will look for it in the home directory (under AmigaOS,
1243: Atari(single)TOS, MS-DOS and OS/2, the environment variable `gnuplot` should
1244: contain the name of this directory). Note: if NOCWDRC is defined during the
1245: installation, `gnuplot` will not read from the current directory.
1246:
1247: If the initialization file is found, `gnuplot` executes the commands in it.
1248: These may be any legal `gnuplot` commands, but typically they are limited to
1249: setting the terminal and defining frequently-used functions or variables.
1250: 2 Substitution
1251: ?substitution
1252: Command-line substitution is specified by a system command enclosed in
1253: backquotes. This command is spawned and the output it produces replaces
1254: the name of the command (and backquotes) on the command line. Some
1255: implementations also support pipes; see `plot data-file special-filenames`.
1256:
1257: Newlines in the output produced by the spawned command are replaced with
1258: blanks.
1259:
1260: Command-line substitution can be used anywhere on the `gnuplot` command
1.1.1.3 ! ohara 1261: line, except inside strings delimited by single quotes.
1.1 maekawa 1262:
1263: Example:
1264:
1265: This will run the program `leastsq` and replace `leastsq` (including
1266: backquotes) on the command line with its output:
1267: f(x) = `leastsq`
1268:
1269: or, in VMS
1270: f(x) = `run leastsq`
1.1.1.3 ! ohara 1271:
! 1272: These will generate labels with the current time and userid:
! 1273: set label "generated on `date +%Y-%m-%d`by `whoami`" at 1,1
! 1274: set timestamp "generated on %Y-%m-%d by `whoami`"
! 1275:
1.1 maekawa 1276: 2 Syntax
1277: ?syntax
1278: ?specify
1279: ?punctuation
1280: The general rules of syntax and punctuation in `gnuplot` are that keywords
1281: and options are order-dependent. Options and any accompanying parameters are
1282: separated by spaces whereas lists and coordinates are separated by commas.
1283: Ranges are separated by colons and enclosed in brackets [], text and file
1284: names are enclosed in quotes, and a few miscellaneous things are enclosed
1285: in parentheses. Braces {} are used for a few special purposes.
1286:
1287: Commas are used to separate coordinates on the `set` commands `arrow`,
1288: `key`, and `label`; the list of variables being fitted (the list after the
1289: `via` keyword on the `fit` command); lists of discrete contours or the loop
1290: parameters which specify them on the `set cntrparam` command; the arguments
1291: of the `set` commands `dgrid3d`, `dummy`, `isosamples`, `offsets`, `origin`,
1292: `samples`, `size`, `time`, and `view`; lists of tics or the loop parameters
1293: which specify them; the offsets for titles and axis labels; parametric
1294: functions to be used to calculate the x, y, and z coordinates on the `plot`,
1295: `replot` and `splot` commands; and the complete sets of keywords specifying
1296: individual plots (data sets or functions) on the `plot`, `replot` and `splot`
1297: commands.
1298:
1299: Parentheses are used to delimit sets of explicit tics (as opposed to loop
1300: parameters) and to indicate computations in the `using` filter of the `fit`,
1301: `plot`, `replot` and `splot` commands.
1302:
1303: (Parentheses and commas are also used as usual in function notation.)
1304:
1305: Brackets are used to delimit ranges, whether they are given on `set`, `plot`
1306: or `splot` commands.
1307:
1308: Colons are used to separate extrema in `range` specifications (whether they
1309: are given on `set`, `plot` or `splot` commands) and to separate entries in
1310: the `using` filter of the `plot`, `replot`, `splot` and `fit` commands.
1311:
1312: Semicolons are used to separate commands given on a single command line.
1313:
1314: Braces are used in text to be specially processed by some terminals, like
1315: `postscript`. They are also used to denote complex numbers: {3,2} = 3 + 2i.
1316:
1317: Text may be enclosed in single- or double-quotes. Backslash processing of
1318: sequences like \n (newline) and \345 (octal character code) is performed for
1319: double-quoted strings, but not for single-quoted strings.
1320:
1321: The justification is the same for each line of a multi-line string. Thus the
1322: center-justified string
1323: "This is the first line of text.\nThis is the second line."
1324: will produce
1325: This is the first line of text.
1326: This is the second line.
1327: but
1328: 'This is the first line of text.\nThis is the second line.'
1329: will produce
1330: This is the first line of text.\nThis is the second line.
1331:
1332: Filenames may be entered with either single- or double-quotes. In this
1333: manual the command examples generally single-quote filenames and double-quote
1334: other string tokens for clarity.
1335:
1336: At present you should not embed \n inside {} when using the enhanced option
1337: of the postscript terminal.
1338:
1339: The EEPIC, Imagen, Uniplex, LaTeX, and TPIC drivers allow a newline to be
1340: specified by \\ in a single-quoted string or \\\\ in a double-quoted string.
1341:
1342: Back-quotes are used to enclose system commands for substitution.
1343: 2 Time/Date data
1344: ?time/date
1345: `gnuplot` supports the use of time and/or date information as input data.
1346: This feature is activated by the commands `set xdata time`, `set ydata time`,
1347: etc.
1348:
1349: Internally all times and dates are converted to the number of seconds from
1350: the year 2000. The command `set timefmt` defines the format for all inputs:
1351: data files, ranges, tics, label positions---in short, anything that accepts a
1352: data value must receive it in this format. Since only one input format can
1353: be in force at a given time, all time/date quantities being input at the same
1354: time must be presented in the same format. Thus if both x and y data in a
1355: file are time/date, they must be in the same format.
1356:
1357: The conversion to and from seconds assumes Universal Time (which is the same
1358: as Greenwich Standard Time). There is no provision for changing the time
1359: zone or for daylight savings. If all your data refer to the same time zone
1360: (and are all either daylight or standard) you don't need to worry about these
1361: things. But if the absolute time is crucial for your application, you'll
1362: need to convert to UT yourself.
1363:
1364: Commands like `show xrange` will re-interpret the integer according to
1365: `timefmt`. If you change `timefmt`, and then `show` the quantity again, it
1366: will be displayed in the new `timefmt`. For that matter, if you give the
1367: deactivation command (like `set xdata`), the quantity will be shown in its
1368: numerical form.
1369:
1370: The command `set format` defines the format that will be used for tic labels,
1371: whether or not the specified axis is time/date.
1372:
1373: If time/date information is to be plotted from a file, the `using` option
1374: _must_ be used on the `plot` or `splot` command. These commands simply use
1375: white space to separate columns, but white space may be embedded within the
1376: time/date string. If you use tabs as a separator, some trial-and-error may
1377: be necessary to discover how your system treats them.
1378:
1379: The following example demonstrates time/date plotting.
1380:
1381: Suppose the file "data" contains records like
1382:
1383: 03/21/95 10:00 6.02e23
1384:
1385: This file can be plotted by
1386:
1387: set xdata time
1388: set timefmt "%m/%d/%y"
1389: set xrange ["03/21/95":"03/22/95"]
1390: set format x "%m/%d"
1391: set timefmt "%m/%d/%y %H:%M"
1392: plot "data" using 1:3
1393:
1394: which will produce xtic labels that look like "03/21".
1395:
1396: See the descriptions of each command for more details.
1397: 1 Commands
1398: ?commands
1399: This section lists the commands acceptable to `gnuplot` in alphabetical
1400: order. Printed versions of this document contain all commands; on-line
1401: versions may not be complete. Indeed, on some systems there may be no
1402: commands at all listed under this heading.
1403:
1404: Note that in most cases unambiguous abbreviations for command names and their
1405: options are permissible, i.e., "`p f(x) w l`" instead of "`plot f(x) with
1406: lines`".
1407:
1408: In the syntax descriptions, braces ({}) denote optional arguments and a
1409: vertical bar (|) separates mutually exclusive choices.
1410: 2 cd
1411: ?commands cd
1412: ?cd
1413: The `cd` command changes the working directory.
1414:
1415: Syntax:
1416: cd '<directory-name>'
1417:
1418: The directory name must be enclosed in quotes.
1419:
1420: Examples:
1421: cd 'subdir'
1422: cd ".."
1423:
1424: DOS users _must_ use single-quotes---backslash [\] has special significance
1425: inside double-quotes. For example,
1426: cd "c:\newdata"
1427: fails, but
1428: cd 'c:\newdata'
1429: works as expected.
1430: 2 call
1431: ?commands call
1432: ?call
1433: The `call` command is identical to the load command with one exception: you
1434: can have up to ten additional parameters to the command (delimited according
1435: to the standard parser rules) which can be substituted into the lines read
1436: from the file. As each line is read from the `call`ed input file, it is
1437: scanned for the sequence `$` (dollar-sign) followed by a digit (0--9). If
1438: found, the sequence is replaced by the corresponding parameter from the
1439: `call` command line. If the parameter was specified as a string in the
1440: `call` line, it is substituted without its enclosing quotes. `$` followed by
1441: any character other than a digit will be that character. E.g. use `$$` to
1442: get a single `$`. Providing more than ten parameters on the `call` command
1443: line will cause an error. A parameter that was not provided substitutes as
1444: nothing. Files being `call`ed may themselves contain `call` or `load`
1445: commands.
1446:
1447: The `call` command _must_ be the last command on a multi-command line.
1448:
1449: Syntax:
1450: call "<input-file>" <parameter-0> <parm-1> ... <parm-9>
1451:
1452: The name of the input file must be enclosed in quotes, and it is recommended
1453: that parameters are similarly enclosed in quotes (future versions of gnuplot
1454: may treat quoted and unquoted arguments differently).
1455:
1456: Example:
1457:
1458: If the file 'calltest.gp' contains the line:
1459: print "p0=$0 p1=$1 p2=$2 p3=$3 p4=$4 p5=$5 p6=$6 p7=x$7x"
1460:
1461: entering the command:
1462: call 'calltest.gp' "abcd" 1.2 + "'quoted'" -- "$2"
1463:
1464: will display:
1465: p0=abcd p1=1.2 p2=+ p3='quoted' p4=- p5=- p6=$2 p7=xx
1466:
1467: NOTE: there is a clash in syntax with the datafile `using` callback
1468: operator. Use `$$n` or `column(n)` to access column n from a datafile inside
1469: a `call`ed datafile plot.
1470: 2 clear
1471: ?commands clear
1472: ?clear
1473: The `clear` command erases the current screen or output device as specified
1474: by `set output`. This usually generates a formfeed on hardcopy devices. Use
1475: `set terminal` to set the device type.
1476:
1477: For some terminals `clear` erases only the portion of the plotting surface
1478: defined by `set size`, so for these it can be used in conjunction with `set
1479: multiplot` to create an inset.
1480:
1481: Example:
1482: set multiplot
1483: plot sin(x)
1484: set origin 0.5,0.5
1485: set size 0.4,0.4
1486: clear
1487: plot cos(x)
1488: set nomultiplot
1489:
1490: Please see `set multiplot`, `set size`, and `set origin` for details of these
1491: commands.
1492: 2 exit
1493: ?commands exit
1494: ?exit
1495: The commands `exit` and `quit` and the END-OF-FILE character will exit the
1496: current `gnuplot` command file and `load` the next one. See "help
1497: batch/interactive" for more details.
1498:
1499: Each of these commands will clear the output device (as does the `clear`
1500: command) before exiting.
1501: 2 fit
1502: ?commands fit
1503: ?fit
1504: ?least-squares
1505: ?Marquardt
1506: The `fit` command can fit a user-defined function to a set of data points
1507: (x,y) or (x,y,z), using an implementation of the nonlinear least-squares
1508: (NLLS) Marquardt-Levenberg algorithm. Any user-defined variable occurring in
1509: the function body may serve as a fit parameter, but the return type of the
1510: function must be real.
1511:
1512: Syntax:
1513: fit {[xrange] {[yrange]}} <function> '<datafile>'
1514: {datafile-modifiers}
1515: via '<parameter file>' | <var1>{,<var2>,...}
1516:
1517: Ranges may be specified to temporarily limit the data which is to be fitted;
1518: any out-of-range data points are ignored. The syntax is
1519: [{dummy_variable=}{<min>}{:<max>}],
1520: analogous to `plot`; see `plot ranges`.
1521:
1522: <function> is any valid `gnuplot` expression, although it is usual to use a
1523: previously user-defined function of the form f(x) or f(x,y).
1524:
1525: <datafile> is treated as in the `plot` command. All the `plot datafile`
1526: modifiers (`using`, `every`,...) except `smooth` are applicable to `fit`.
1527: See `plot datafile`.
1528:
1529: The default data formats for fitting functions with a single independent
1530: variable, y=f(x), are {x:}y or x:y:s; those formats can be changed with
1531: the datafile `using` qualifier. The third item, (a column number or an
1532: expression), if present, is interpreted as the standard deviation of the
1533: corresponding y value and is used to compute a weight for the datum, 1/s**2.
1534: Otherwise, all data points are weighted equally, with a weight of one.
1535:
1536: To fit a function with two independent variables, z=f(x,y), the required
1537: format is `using` with four items, x:y:z:s. The complete format must be
1538: given---no default columns are assumed for a missing token. Weights for
1539: each data point are evaluated from 's' as above. If error estimates are
1540: not available, a constant value can be specified as a constant expression
1541: (see `plot datafile using`), e.g., `using 1:2:3:(1)`.
1542:
1543: Multiple datasets may be simultaneously fit with functions of one
1544: independent variable by making y a 'pseudo-variable', e.g., the dataline
1545: number, and fitting as two independent variables. See `fit multibranch`.
1546:
1547: The `via` qualifier specifies which parameters are to be adjusted, either
1548: directly, or by referencing a parameter file.
1549:
1550: Examples:
1551: f(x) = a*x**2 + b*x + c
1552: g(x,y) = a*x**2 + b*y**2 + c*x*y
1553: FIT_LIMIT = 1e-6
1554: fit f(x) 'measured.dat' via 'start.par'
1555: fit f(x) 'measured.dat' using 3:($7-5) via 'start.par'
1556: fit f(x) './data/trash.dat' using 1:2:3 via a, b, c
1557: fit g(x,y) 'surface.dat' using 1:2:3:(1) via a, b, c
1558:
1559: After each iteration step, detailed information about the current state
1560: of the fit is written to the display. The same information about the
1561: initial and final states is written to a log file, "fit.log". This file
1562: is always appended to, so as to not lose any previous fit history; it
1563: should be deleted or renamed as desired.
1564:
1565: The fit may be interrupted by pressing Ctrl-C (any key but Ctrl-C under
1566: MSDOS and Atari Multitasking Systems). After the current iteration
1567: completes, you have the option to (1) stop the fit and accept the current
1568: parameter values, (2) continue the fit, (3) execute a `gnuplot` command
1569: as specified by the environment variable FIT_SCRIPT. The default for
1570: FIT_SCRIPT is `replot`, so if you had previously plotted both the data
1571: and the fitting function in one graph, you can display the current state
1572: of the fit.
1573:
1574: Once `fit` has finished, the `update` command may be used to store final
1575: values in a file for subsequent use as a parameter file. See `update`
1576: for details.
1577: 3 adjustable parameters
1578: ?commands fit parameters
1579: ?fit parameters
1580: ?commands fit adjustable_parameters
1581: ?fit adjustable_parameters
1582: ?fit_parameters
1583: There are two ways that `via` can specify the parameters to be adjusted,
1584: either directly on the command line or indirectly, by referencing a
1585: parameter file. The two use different means to set initial values.
1586:
1587: Adjustable parameters can be specified by a comma-separated list of variable
1.1.1.3 ! ohara 1588: names after the `via` keyword. Any variable that is not already defined
1.1 maekawa 1589: is created with an initial value of 1.0. However, the fit is more likely
1590: to converge rapidly if the variables have been previously declared with more
1591: appropriate starting values.
1592:
1593: In a parameter file, each parameter to be varied and a corresponding initial
1594: value are specified, one per line, in the form
1595: varname = value
1596:
1597: Comments, marked by '#', and blank lines are permissible. The
1598: special form
1599: varname = value # FIXED
1600:
1601: means that the variable is treated as a 'fixed parameter', initialized by the
1602: parameter file, but not adjusted by `fit`. For clarity, it may be useful to
1603: designate variables as fixed parameters so that their values are reported by
1604: `fit`. The keyword `# FIXED` has to appear in exactly this form.
1605:
1606: 3 beginner's guide
1607: ?commands fit beginners_guide
1608: ?fit beginners_guide
1609: ?fit guide
1610: ?fitting
1611: `fit` is used to find a set of parameters that 'best' fits your data to your
1612: user-defined function. The fit is judged on the basis of the the sum of the
1613: squared differences or 'residuals' (SSR) between the input data points and
1614: the function values, evaluated at the same places. This quantity is often
1615: called 'chisquare' (i.e., the Greek letter chi, to the power of 2). The
1616: algorithm attempts to minimize SSR, or more precisely, WSSR, as the residuals
1617: are 'weighted' by the input data errors (or 1.0) before being squared; see
1618: `fit error_estimates` for details.
1619:
1620: That's why it is called 'least-squares fitting'. Let's look at an example
1621: to see what is meant by 'non-linear', but first we had better go over some
1622: terms. Here it is convenient to use z as the dependent variable for
1623: user-defined functions of either one independent variable, z=f(x), or two
1624: independent variables, z=f(x,y). A parameter is a user-defined variable
1625: that `fit` will adjust, i.e., an unknown quantity in the function
1626: declaration. Linearity/non-linearity refers to the relationship of the
1627: dependent variable, z, to the parameters which `fit` is adjusting, not of
1628: z to the independent variables, x and/or y. (To be technical, the
1629: second {and higher} derivatives of the fitting function with respect to
1630: the parameters are zero for a linear least-squares problem).
1631:
1632: For linear least-squares (LLS), the user-defined function will be a sum of
1633: simple functions, not involving any parameters, each multiplied by one
1634: parameter. NLLS handles more complicated functions in which parameters can
1635: be used in a large number of ways. An example that illustrates the
1636: difference between linear and nonlinear least-squares is the Fourier series.
1637: One member may be written as
1638: z=a*sin(c*x) + b*cos(c*x).
1639: If a and b are the unknown parameters and c is constant, then estimating
1640: values of the parameters is a linear least-squares problem. However, if
1641: c is an unknown parameter, the problem is nonlinear.
1642:
1643: In the linear case, parameter values can be determined by comparatively
1644: simple linear algebra, in one direct step. However LLS is a special case
1645: which is also solved along with more general NLLS problems by the iterative
1646: procedure that `gnuplot` uses. `fit` attempts to find the minimum by doing
1647: a search. Each step (iteration) calculates WSSR with a new set of parameter
1648: values. The Marquardt-Levenberg algorithm selects the parameter values for
1649: the next iteration. The process continues until a preset criterium is met,
1650: either (1) the fit has "converged" (the relative change in WSSR is less than
1651: FIT_LIMIT), or (2) it reaches a preset iteration count limit, FIT_MAXITER
1652: (see `fit control variables`). The fit may also be interrupted
1653: and subsequently halted from the keyboard (see `fit`).
1654:
1655: Often the function to be fitted will be based on a model (or theory) that
1656: attempts to describe or predict the behaviour of the data. Then `fit` can
1657: be used to find values for the free parameters of the model, to determine
1658: how well the data fits the model, and to estimate an error range for each
1659: parameter. See `fit error_estimates`.
1660:
1661: Alternatively, in curve-fitting, functions are selected independent of
1662: a model (on the basis of experience as to which are likely to describe
1663: the trend of the data with the desired resolution and a minimum number
1664: of parameters*functions.) The `fit` solution then provides an analytic
1665: representation of the curve.
1666:
1667: However, if all you really want is a smooth curve through your data points,
1668: the `smooth` option to `plot` may be what you've been looking for rather
1669: than `fit`.
1670: 3 error estimates
1671: ?commands fit error_estimate
1672: ?fit error_estimate
1673: ?fit errors
1674: In `fit`, the term "error" is used in two different contexts, data error
1675: estimates and parameter error estimates.
1676:
1677: Data error estimates are used to calculate the relative weight of each data
1678: point when determining the weighted sum of squared residuals, WSSR or
1679: chisquare. They can affect the parameter estimates, since they determine
1680: how much influence the deviation of each data point from the fitted function
1681: has on the final values. Some of the `fit` output information, including
1682: the parameter error estimates, is more meaningful if accurate data error
1683: estimates have been provided.
1684:
1685: The 'statistical overview' describes some of the `fit` output and gives some
1686: background for the 'practical guidelines'.
1687: 4 statistical overview
1688: ?commands fit error statistical_overview
1689: ?fit error statistical_overview
1690: ?statistical_overview
1691: The theory of non-linear least-squares (NLLS) is generally described in terms
1692: of a normal distribution of errors, that is, the input data is assumed to be
1693: a sample from a population having a given mean and a Gaussian (normal)
1694: distribution about the mean with a given standard deviation. For a sample of
1695: sufficiently large size, and knowing the population standard deviation, one
1696: can use the statistics of the chisquare distribution to describe a "goodness
1697: of fit" by looking at the variable often called "chisquare". Here, it is
1698: sufficient to say that a reduced chisquare (chisquare/degrees of freedom,
1699: where degrees of freedom is the number of datapoints less the number of
1700: parameters being fitted) of 1.0 is an indication that the weighted sum of
1701: squared deviations between the fitted function and the data points is the
1702: same as that expected for a random sample from a population characterized by
1703: the function with the current value of the parameters and the given standard
1704: deviations.
1705:
1706: If the standard deviation for the population is not constant, as in counting
1707: statistics where variance = counts, then each point should be individually
1708: weighted when comparing the observed sum of deviations and the expected sum
1709: of deviations.
1710:
1711: At the conclusion `fit` reports 'stdfit', the standard deviation of the fit,
1712: which is the rms of the residuals, and the variance of the residuals, also
1713: called 'reduced chisquare' when the data points are weighted. The number of
1714: degrees of freedom (the number of data points minus the number of fitted
1715: parameters) is used in these estimates because the parameters used in
1716: calculating the residuals of the datapoints were obtained from the same data.
1717:
1718: To estimate confidence levels for the parameters, one can use the minimum
1719: chisquare obtained from the fit and chisquare statistics to determine the
1720: value of chisquare corresponding to the desired confidence level, but
1721: considerably more calculation is required to determine the combinations of
1722: parameters which produce such values.
1723:
1724: Rather than determine confidence intervals, `fit` reports parameter error
1725: estimates which are readily obtained from the variance-covariance matrix
1726: after the final iteration. By convention, these estimates are called
1727: "standard errors" or "asymptotic standard errors", since they are calculated
1728: in the same way as the standard errors (standard deviation of each parameter)
1729: of a linear least-squares problem, even though the statistical conditions for
1730: designating the quantity calculated to be a standard deviation are not
1731: generally valid for the NLLS problem. The asymptotic standard errors are
1732: generally over-optimistic and should not be used for determining confidence
1733: levels, but are useful for qualitative purposes.
1734:
1735: The final solution also produces a correlation matrix, which gives an
1736: indication of the correlation of parameters in the region of the solution;
1737: if one parameter is changed, increasing chisquare, does changing another
1738: compensate? The main diagonal elements, autocorrelation, are all 1; if
1739: all parameters were independent, all other elements would be nearly 0. Two
1740: variables which completely compensate each other would have an off-diagonal
1741: element of unit magnitude, with a sign depending on whether the relation is
1742: proportional or inversely proportional. The smaller the magnitudes of the
1743: off-diagonal elements, the closer the estimates of the standard deviation
1744: of each parameter would be to the asymptotic standard error.
1745: 4 practical guidelines
1746: ?commands fit error practical_guidelines
1747: ?fit error practical_guidelines
1748: ?practical_guidelines
1749: ?guidelines
1750: If you have a basis for assigning weights to each data point, doing so lets
1751: you make use of additional knowledge about your measurements, e.g., take into
1752: account that some points may be more reliable than others. That may affect
1753: the final values of the parameters.
1754:
1755: Weighting the data provides a basis for interpreting the additional `fit`
1756: output after the last iteration. Even if you weight each point equally,
1757: estimating an average standard deviation rather than using a weight of 1
1758: makes WSSR a dimensionless variable, as chisquare is by definition.
1759:
1760: Each fit iteration will display information which can be used to evaluate
1761: the progress of the fit. (An '*' indicates that it did not find a smaller
1762: WSSR and is trying again.) The 'sum of squares of residuals', also called
1763: 'chisquare', is the WSSR between the data and your fitted function; `fit`
1764: has minimized that. At this stage, with weighted data, chisquare is expected
1765: to approach the number of degrees of freedom (data points minus parameters).
1766: The WSSR can be used to calculate the reduced chisquare (WSSR/ndf) or stdfit,
1767: the standard deviation of the fit, sqrt(WSSR/ndf). Both of these are
1768: reported for the final WSSR.
1769:
1770: If the data are unweighted, stdfit is the rms value of the deviation of the
1771: data from the fitted function, in user units.
1772:
1773: If you supplied valid data errors, the number of data points is large enough,
1774: and the model is correct, the reduced chisquare should be about unity. (For
1775: details, look up the 'chi-squared distribution' in your favourite statistics
1776: reference.) If so, there are additional tests, beyond the scope of this
1777: overview, for determining how well the model fits the data.
1778:
1779: A reduced chisquare much larger than 1.0 may be due to incorrect data error
1780: estimates, data errors not normally distributed, systematic measurement
1781: errors, 'outliers', or an incorrect model function. A plot of the residuals,
1782: e.g., `plot 'datafile' using 1:($2-f($1))`, may help to show any systematic
1783: trends. Plotting both the data points and the function may help to suggest
1784: another model.
1785:
1786: Similarly, a reduced chisquare less than 1.0 indicates WSSR is less than that
1787: expected for a random sample from the function with normally distributed
1788: errors. The data error estimates may be too large, the statistical
1789: assumptions may not be justified, or the model function may be too general,
1790: fitting fluctuations in a particular sample in addition to the underlying
1791: trends. In the latter case, a simpler function may be more appropriate.
1792:
1793: You'll have to get used to both `fit` and the kind of problems you apply it
1794: to before you can relate the standard errors to some more practical estimates
1795: of parameter uncertainties or evaluate the significance of the correlation
1796: matrix.
1797:
1798: Note that `fit`, in common with most NLLS implementations, minimizes the
1799: weighted sum of squared distances (y-f(x))**2. It does not provide any means
1800: to account for "errors" in the values of x, only in y. Also, any "outliers"
1801: (data points outside the normal distribution of the model) will have an
1802: exaggerated effect on the solution.
1803: 3 fit controlling
1804: ?commands fit_control
1805: ?fit_control
1806: ?fit control
1807: There are a number of `gnuplot` variables that can be defined to affect
1808: `fit`. Those which can be defined once `gnuplot` is running are listed
1809: under 'control_variables' while those defined before starting `gnuplot`
1810: are listed under 'environment_variables'.
1811: 4 control variables
1812: ?commands fit_control variables
1813: ?fit_control variables
1814: ?fit control variables
1815: The default epsilon limit (1e-5) may be changed by declaring a value for
1816: FIT_LIMIT
1817: When the sum of squared residuals changes between two iteration steps by
1818: a factor less than this number (epsilon), the fit is considered to have
1819: 'converged'.
1820:
1821: The maximum number of iterations may be limited by declaring a value for
1822: FIT_MAXITER
1823: A value of 0 (or not defining it at all) means that there is no limit.
1824:
1825: If you need even more control about the algorithm, and know the
1826: Marquardt-Levenberg algorithm well, there are some more variables to
1827: influence it. The startup value of `lambda` is normally calculated
1828: automatically from the ML-matrix, but if you want to, you may provide
1829: your own one with
1830: FIT_START_LAMBDA
1831: Specifying FIT_START_LAMBDA as zero or less will re-enable the automatic
1832: selection. The variable
1833: FIT_LAMBDA_FACTOR
1834: gives the factor by which `lambda` is increased or decreased whenever
1835: the chi-squared target function increased or decreased significantly.
1836: Setting FIT_LAMBDA_FACTOR to zero re-enables the default factor of
1837: 10.0.
1838:
1.1.1.3 ! ohara 1839: Other variables with the FIT_ prefix may be added to `fit`, so it is safer
1.1 maekawa 1840: not to use that prefix for user-defined variables.
1841:
1842: The variables FIT_SKIP and FIT_INDEX were used by earlier releases of
1843: `gnuplot` with a 'fit' patch called `gnufit` and are no longer available.
1844: The datafile `every` modifier provides the functionality of FIT_SKIP.
1845: FIT_INDEX was used for multi-branch fitting, but multi-branch fitting of
1846: one independent variable is now done as a pseudo-3D fit in which the
1847: second independent variable and `using` are used to specify the branch.
1848: See `fit multi-branch`.
1849: 4 environment variables
1850: ?commands fit_control environment
1851: ?fit_control environment
1852: ?fit control environment
1853: The environment variables must be defined before `gnuplot` is executed; how
1854: to do so depends on your operating system.
1855:
1856: FIT_LOG
1857: changes the name (and/or path) of the file to which the fit log will be
1858: written from the default of "fit.log" in the working directory.
1859:
1860: FIT_SCRIPT
1861: specifies a command that may be executed after an user interrupt. The default
1862: is `replot`, but a `plot` or `load` command may be useful to display a plot
1863: customized to highlight the progress of the fit.
1864: 3 multi-branch
1865: ?commands fit multi-branch
1866: ?fit multi-branch
1867: ?multi-branch
1868: ?branch
1869: In multi-branch fitting, multiple data sets can be simultaneously fit with
1870: functions of one independent variable having common parameters by minimizing
1871: the total WSSR. The function and parameters (branch) for each data set are
1872: selected by using a 'pseudo-variable', e.g., either the dataline number (a
1873: 'column' index of -1) or the datafile index (-2), as the second independent
1874: variable.
1875:
1876: Example: Given two exponential decays of the form, z=f(x), each describing
1877: a different data set but having a common decay time, estimate the values of
1878: the parameters. If the datafile has the format x:z:s, then
1879: f(x,y) = (y==0) ? a*exp(-x/tau) : b*exp(-x/tau)
1880: fit f(x,y) 'datafile' using 1:-1:2:3 via a, b, tau
1881:
1882: For a more complicated example, see the file "hexa.fnc" used by the
1883: "fit.dem" demo.
1884:
1885: Appropriate weighting may be required since unit weights may cause one
1886: branch to predominate if there is a difference in the scale of the dependent
1887: variable. Fitting each branch separately, using the multi-branch solution
1888: as initial values, may give an indication as to the relative effect of each
1889: branch on the joint solution.
1890: 3 starting values
1891: ?commands fit starting_values
1892: ?fit starting_values
1893: ?starting_values
1894: Nonlinear fitting is not guaranteed to converge to the global optimum (the
1895: solution with the smallest sum of squared residuals, SSR), and can get stuck
1896: at a local minimum. The routine has no way to determine that; it is up to
1897: you to judge whether this has happened.
1898:
1899: `fit` may, and often will get "lost" if started far from a solution, where
1900: SSR is large and changing slowly as the parameters are varied, or it may
1901: reach a numerically unstable region (e.g., too large a number causing a
1902: floating point overflow) which results in an "undefined value" message
1903: or `gnuplot` halting.
1904:
1905: To improve the chances of finding the global optimum, you should set the
1906: starting values at least roughly in the vicinity of the solution, e.g.,
1907: within an order of magnitude, if possible. The closer your starting values
1908: are to the solution, the less chance of stopping at another minimum. One way
1909: to find starting values is to plot data and the fitting function on the same
1910: graph and change parameter values and `replot` until reasonable similarity
1911: is reached. The same plot is also useful to check whether the fit stopped at
1912: a minimum with a poor fit.
1913:
1914: Of course, a reasonably good fit is not proof there is not a "better" fit (in
1915: either a statistical sense, characterized by an improved goodness-of-fit
1916: criterion, or a physical sense, with a solution more consistent with the
1917: model.) Depending on the problem, it may be desirable to `fit` with various
1918: sets of starting values, covering a reasonable range for each parameter.
1919: 3 tips
1920: ?commands fit tips
1921: ?fit tips
1922: ?tips
1923: Here are some tips to keep in mind to get the most out of `fit`. They're not
1924: very organized, so you'll have to read them several times until their essence
1925: has sunk in.
1926:
1927: The two forms of the `via` argument to `fit` serve two largely distinct
1928: purposes. The `via "file"` form is best used for (possibly unattended) batch
1929: operation, where you just supply the startup values in a file and can later
1930: use `update` to copy the results back into another (or the same) parameter
1931: file.
1932:
1933: The `via var1, var2, ...` form is best used interactively, where the command
1934: history mechanism may be used to edit the list of parameters to be fitted or
1935: to supply new startup values for the next try. This is particularly useful
1936: for hard problems, where a direct fit to all parameters at once won't work
1937: without good starting values. To find such, you can iterate several times,
1938: fitting only some of the parameters, until the values are close enough to the
1939: goal that the final fit to all parameters at once will work.
1940:
1941: Make sure that there is no mutual dependency among parameters of the function
1942: you are fitting. For example, don't try to fit a*exp(x+b), because
1943: a*exp(x+b)=a*exp(b)*exp(x). Instead, fit either a*exp(x) or exp(x+b).
1944:
1945: A technical issue: the parameters must not be too different in magnitude.
1946: The larger the ratio of the largest and the smallest absolute parameter
1947: values, the slower the fit will converge. If the ratio is close to or above
1948: the inverse of the machine floating point precision, it may take next to
1949: forever to converge, or refuse to converge at all. You will have to adapt
1950: your function to avoid this, e.g., replace 'parameter' by '1e9*parameter' in
1951: the function definition, and divide the starting value by 1e9.
1952:
1953: If you can write your function as a linear combination of simple functions
1954: weighted by the parameters to be fitted, by all means do so. That helps a
1955: lot, because the problem is no longer nonlinear and should converge with only
1956: a small number of iterations, perhaps just one.
1957:
1958: Some prescriptions for analysing data, given in practical experimentation
1959: courses, may have you first fit some functions to your data, perhaps in a
1960: multi-step process of accounting for several aspects of the underlying
1961: theory one by one, and then extract the information you really wanted from
1962: the fitting parameters of those functions. With `fit`, this may often be
1963: done in one step by writing the model function directly in terms of the
1964: desired parameters. Transforming data can also quite often be avoided,
1965: though sometimes at the cost of a more difficult fit problem. If you think
1966: this contradicts the previous paragraph about simplifying the fit function,
1967: you are correct.
1968:
1969: A "singular matrix" message indicates that this implementation of the
1970: Marquardt-Levenberg algorithm can't calculate parameter values for the next
1971: iteration. Try different starting values, writing the function in another
1972: form, or a simpler function.
1973:
1974: Finally, a nice quote from the manual of another fitting package (fudgit),
1975: that kind of summarizes all these issues: "Nonlinear fitting is an art!"
1976: 2 help
1977: ?commands help
1978: ?help
1979: The `help` command displays on-line help. To specify information on a
1980: particular topic use the syntax:
1981:
1982: help {<topic>}
1983:
1984: If <topic> is not specified, a short message is printed about `gnuplot`.
1985: After help for the requested topic is given, a menu of subtopics is given;
1986: help for a subtopic may be requested by typing its name, extending the help
1987: request. After that subtopic has been printed, the request may be extended
1988: again or you may go back one level to the previous topic. Eventually, the
1989: `gnuplot` command line will return.
1990:
1991: If a question mark (?) is given as the topic, the list of topics currently
1992: available is printed on the screen.
1993: 2 if
1994: ?commands if
1995: ?if
1996: The `if` command allows commands to be executed conditionally.
1997:
1998: Syntax:
1999: if (<condition>) <command-line>
2000:
2001: <condition> will be evaluated. If it is true (non-zero), then the command(s)
2002: of the <command-line> will be executed. If <condition> is false (zero), then
2003: the entire <command-line> is ignored. Note that use of `;` to allow multiple
2004: commands on the same line will _not_ end the conditionalized commands.
2005:
2006: Examples:
2007: pi=3
2008: if (pi!=acos(-1)) print "?Fixing pi!"; pi=acos(-1); print pi
2009: will display:
2010: ?Fixing pi!
2011: 3.14159265358979
2012: but
2013: if (1==2) print "Never see this"; print "Or this either"
2014: will not display anything.
2015:
2016: See `reread` for an example of how `if` and `reread` can be used together to
2017: perform a loop.
2018: 2 load
2019: ?commands load
2020: ?load
2021: The `load` command executes each line of the specified input file as if it
2022: had been typed in interactively. Files created by the `save` command can
2023: later be `load`ed. Any text file containing valid commands can be created
2024: and then executed by the `load` command. Files being `load`ed may themselves
2025: contain `load` or `call` commands. See `comment` for information about
2026: comments in commands. To `load` with arguments, see `call`.
2027:
2028: The `load` command _must_ be the last command on a multi-command line.
2029:
2030: Syntax:
2031: load "<input-file>"
2032:
2033: The name of the input file must be enclosed in quotes.
2034:
2035: The special filename "-" may be used to `load` commands from standard input.
2036: This allows a `gnuplot` command file to accept some commands from standard
2037: input. Please see "help batch/interactive" for more details.
2038:
2039: Examples:
2040: load 'work.gnu'
2041: load "func.dat"
2042:
2043: The `load` command is performed implicitly on any file names given as
2044: arguments to `gnuplot`. These are loaded in the order specified, and
2045: then `gnuplot` exits.
2046: 2 pause
2047: ?commands pause
2048: ?pause
2049: The `pause` command displays any text associated with the command and then
2050: waits a specified amount of time or until the carriage return is pressed.
2051: `pause` is especially useful in conjunction with `load` files.
2052:
2053: Syntax:
2054: pause <time> {"<string>"}
2055:
2056: <time> may be any integer constant or expression. Choosing -1 will wait
2057: until a carriage return is hit, zero (0) won't pause at all, and a positive
2058: integer will wait the specified number of seconds. `pause 0` is synonymous
2059: with `print`.
2060:
2061: Note: Since `pause` communicates with the operating system rather than the
2062: graphics, it may behave differently with different device drivers (depending
2063: upon how text and graphics are mixed).
2064:
2065: Examples:
2066: pause -1 # Wait until a carriage return is hit
2067: pause 3 # Wait three seconds
2068: pause -1 "Hit return to continue"
2069: pause 10 "Isn't this pretty? It's a cubic spline."
2070:
2071: 2 plot
2072: ?commands plot
2073: ?plot
2074: `plot` is the primary command for drawing plots with `gnuplot`. It creates
2075: plots of functions and data in many, many ways. `plot` is used to draw 2-d
2076: functions and data; `splot` draws 2-d projections of 3-d surfaces and data.
2077: `plot` and `splot` contain many common features; see `splot` for differences.
2078: Note specifically that `splot`'s `binary` and `matrix` options do not exist
2079: for `plot`.
2080:
2081: Syntax:
2082: plot {<ranges>}
2083: {<function> | {"<datafile>" {datafile-modifiers}}}
2084: {axes <axes>} {<title-spec>} {with <style>}
2085: {, {definitions,} <function> ...}
2086:
2087: where either a <function> or the name of a data file enclosed in quotes is
2088: supplied. A function is a mathematical expression or a pair of mathematical
2089: expressions in parametric mode. The expressions may be defined completely or
2090: in part earlier in the stream of `gnuplot` commands (see `user-defined`).
2091:
2092: It is also possible to define functions and parameters on the `plot` command
2093: itself. This is done merely by isolating them from other items with commas.
2094:
2095: There are four possible sets of axes available; the keyword <axes> is used to
2096: select the axes for which a particular line should be scaled. `x1y1` refers
2097: to the axes on the bottom and left; `x2y2` to those on the top and right;
2098: `x1y2` to those on the bottom and right; and `x2y1` to those on the top and
2099: left. Ranges specified on the `plot` command apply only to the first set of
2100: axes (bottom left).
2101:
2102: Examples:
2103: plot sin(x)
2104: plot f(x) = sin(x*a), a = .2, f(x), a = .4, f(x)
2105: plot [t=1:10] [-pi:pi*2] tan(t), \
2106: "data.1" using (tan($2)):($3/$4) smooth csplines \
2107: axes x1y2 notitle with lines 5
2108:
2109: 3 data-file
2110: ?commands plot datafile
2111: ?plot datafile
2112: ?data-file
2113: ?datafile
2114: ?data
2115: Discrete data contained in a file can be displayed by specifying the name of
2116: the data file (enclosed in single or double quotes) on the `plot` command line.
2117:
2118: Syntax:
2119: plot '<file_name>' {index <index list>}
2120: {every <every list>}
2121: {thru <thru expression>}
2122: {using <using list>}
2123: {smooth <option>}
2124:
2125: The modifiers `index`, `every`, `thru`, `using`, and `smooth` are discussed
2126: separately. In brief, `index` selects which data sets in a multi-data-set
2127: file are to be plotted, `every` specifies which points within a single data
2128: set are to be plotted, `using` determines how the columns within a single
2129: record are to be interpreted (`thru` is a special case of `using`), and
2130: `smooth` allows for simple interpolation and approximation. ('splot' has a
2131: similar syntax, but does not support the `smooth` and `thru` options.)
2132:
2133: Data files should contain at least one data point per record (`using` can
2134: select one data point from the record). Records beginning with `#` (and
2135: also with `!` on VMS) will be treated as comments and ignored. Each data
2136: point represents an (x,y) pair. For `plot`s with error bars (see `set style
2137: errorbars`), each data point is (x,y,ydelta), (x,y,ylow,yhigh), (x,y,xdelta),
2138: (x,y,xlow,xhigh), or (x,y,xlow,xhigh,ylow,yhigh). In all cases, the numbers
2139: on each record of a data file must be separated by white space (one or more
2140: blanks or tabs), unless a format specifier is provided by the `using` option.
2141: This white space divides each record into columns.
2142:
2143: Data may be written in exponential format with the exponent preceded by the
2144: letter e, E, d, D, q, or Q.
2145:
2146: Only one column (the y value) need be provided. If x is omitted, `gnuplot`
2147: provides integer values starting at 0.
2148:
2149: In datafiles, blank records (records with no characters other than blanks and
2150: a newline and/or carriage return) are significant---pairs of blank records
2151: separate `index`es (see `plot datafile index`). Data separated by double
2152: blank records are treated as if they were in separate data files.
2153:
2154: Single blank records designate discontinuities in a `plot`; no line will join
2155: points separated by a blank records (if they are plotted with a line style).
2156:
2157: If autoscaling has been enabled (`set autoscale`), the axes are automatically
2158: extended to include all datapoints, with a whole number of tic marks if tics
2159: are being drawn. This has two consequences: i) For `splot`, the corner of
2160: the surface may not coincide with the corner of the base. In this case, no
2161: vertical line is drawn. ii) When plotting data with the same x range on a
2162: dual-axis graph, the x coordinates may not coincide if the x2tics are not
2163: being drawn. This is because the x axis has been autoextended to a whole
2164: number of tics, but the x2 axis has not. The following example illustrates
2165: the problem:
2166:
2167: reset; plot '-', '-'
2168: 1 1
2169: 19 19
2170: e
2171: 1 1
2172: 19 19
2173: e
2174: 4 every
2175: ?commands plot datafile every
2176: ?plot datafile every
2177: ?plot every
2178: ?data-file every
2179: ?datafile every
2180: ?every
2181: The `every` keyword allows a periodic sampling of a data set to be plotted.
2182:
2183: In the discussion a "point" is a datum defined by a single record in the
2184: file; "block" here will mean the same thing as "datablock" (see `glossary`).
2185:
2186: Syntax:
2187: plot 'file' every {<point_incr>}
2188: {:{<block_incr>}
2189: {:{<start_point>}
2190: {:{<start_block>}
2191: {:{<end_point>}
2192: {:<end_block>}}}}}
2193:
2194: The data points to be plotted are selected according to a loop from
2195: <`start_point`> to <`end_point`> with increment <`point_incr`> and the
2196: blocks according to a loop from <`start_block`> to <`end_block`> with
2197: increment <`block_incr`>.
2198:
2199: The first datum in each block is numbered '0', as is the first block in the
2200: file.
2201:
2202: Note that records containing unplottable information are counted.
2203:
2204: Any of the numbers can be omitted; the increments default to unity, the start
2205: values to the first point or block, and the end values to the last point or
2206: block. If `every` is not specified, all points in all lines are plotted.
2207:
2208: Examples:
2209: every :::3::3 # selects just the fourth block ('0' is first)
2210: every :::::9 # selects the first 10 blocks
2211: every 2:2 # selects every other point in every other block
2212: every ::5::15 # selects points 5 through 15 in each block
1.1.1.2 maekawa 2213: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/simple.html">Simple Plot Demos </a>,
1.1 maekawa 2214: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/surfacea/surfacea.html">Non-parametric splot demos </a>, and
2215: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/surfaceb/surfaceb.html">Parametric splot demos.</a>
2216: 4 example datafile
2217: ?commands plot datafile example
2218: ?plot datafile example
2219: ?plot example
2220: ?datafile example
2221: ?data-file example
2222: ?example
2223: This example plots the data in the file "population.dat" and a theoretical
2224: curve:
2225:
2226: pop(x) = 103*exp((1965-x)/10)
2227: plot [1960:1990] 'population.dat', pop(x)
2228:
2229: The file "population.dat" might contain:
2230:
2231: # Gnu population in Antarctica since 1965
2232: 1965 103
2233: 1970 55
2234: 1975 34
2235: 1980 24
2236: 1985 10
2237:
2238: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/population.gif" alt="[population.gif]" width=640 height=480>
2239: 4 index
2240: ?commands plot datafile index
2241: ?plot datafile index
2242: ?plot index
2243: ?data-file index
2244: ?datafile index
2245: ?index
2246: The `index` keyword allows only some of the data sets in a multi-data-set
2247: file to be plotted.
2248:
2249: Syntax:
2250: plot 'file' index <m>{{:<n>}:<p>}
2251:
2252: Data sets are separated by pairs of blank records. `index <m>` selects only
2253: set <m>; `index <m>:<n>` selects sets in the range <m> to <n>; and `index
2254: <m>:<n>:<p>` selects indices <m>, <m>+<p>, <m>+2<p>, etc., but stopping at
2255: <n>. Following C indexing, the index 0 is assigned to the first data set in
2256: the file. Specifying too large an index results in an error message. If
2257: `index` is not specified, all sets are plotted as a single data set.
2258:
2259: Example:
2260: plot 'file' index 4:5
1.1.1.2 maekawa 2261: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/multimsh.html"> splot with indices demo. </a>
1.1 maekawa 2262: 4 smooth
2263: ?commands plot datafile smooth
2264: ?plot datafile smooth
2265: ?plot smooth
2266: ?data-file smooth
2267: ?datafile smooth
2268: ?smooth
2269: `gnuplot` includes a few general-purpose routines for interpolation and
2270: approximation of data; these are grouped under the `smooth` option. More
2271: sophisticated data processing may be performed by preprocessing the data
2272: externally or by using `fit` with an appropriate model.
2273:
2274: Syntax:
2275: smooth {unique | csplines | acsplines | bezier | sbezier}
2276:
2277: `unique` plots the data after making them monotonic. Each of the other
2278: routines uses the data to determine the coefficients of a continuous curve
2279: between the endpoints of the data. This curve is then plotted in the same
2280: manner as a function, that is, by finding its value at uniform intervals
2281: along the abscissa (see `set samples`) and connecting these points with
2282: straight line segments (if a line style is chosen).
2283:
2284: If `autoscale` is in effect, the ranges will be computed such that the
2285: plotted curve lies within the borders of the graph.
2286:
2287: If too few points are available to allow the selected option to be applied,
2288: an error message is produced. The minimum number is one for `unique`, four
2289: for `acsplines`, and three for the others.
2290:
2291: The `smooth` options have no effect on function plots.
2292: 5 acsplines
2293: ?commands plot datafile smooth acsplines
2294: ?plot datafile smooth acsplines
2295: ?data-file smooth acsplines
2296: ?datafile smooth acsplines
2297: ?plot smooth acsplines
2298: ?plot acsplines
2299: ?smooth acsplines
2300: ?acsplines
2301: The `acsplines` option approximates the data with a "natural smoothing spline".
2302: After the data are made monotonic in x (see `smooth unique`), a curve is
2303: piecewise constructed from segments of cubic polynomials whose coefficients
2304: are found by the weighting the data points; the weights are taken from the
2305: third column in the data file. That default can be modified by the third
2306: entry in the `using` list, e.g.,
2307: plot 'data-file' using 1:2:(1.0) smooth acsplines
2308:
2309: Qualitatively, the absolute magnitude of the weights determines the number
2310: of segments used to construct the curve. If the weights are large, the
2311: effect of each datum is large and the curve approaches that produced by
2312: connecting consecutive points with natural cubic splines. If the weights are
2313: small, the curve is composed of fewer segments and thus is smoother; the
2314: limiting case is the single segment produced by a weighted linear least
2315: squares fit to all the data. The smoothing weight can be expressed in terms
2316: of errors as a statistical weight for a point divided by a "smoothing factor"
2317: for the curve so that (standard) errors in the file can be used as smoothing
2318: weights.
2319:
2320: Example:
2321: sw(x,S)=1/(x*x*S)
2322: plot 'data_file' using 1:2:(sw($3,100)) smooth acsplines
2323: 5 bezier
2324: ?commands plot datafile smooth bezier
2325: ?plot datafile smooth bezier
2326: ?plot smooth bezier
2327: ?data-file smooth bezier
2328: ?datafile smooth bezier
2329: ?plot bezier
2330: ?smooth bezier
2331: ?bezier
2332: The `bezier` option approximates the data with a Bezier curve of degree n
2333: (the number of data points) that connects the endpoints.
2334: 5 csplines
2335: ?commands plot datafile smooth csplines
2336: ?plot datafile smooth csplines
2337: ?plot smooth csplines
2338: ?data-file smooth csplines
2339: ?datafile smooth csplines
2340: ?plot csplines
2341: ?smooth csplines
2342: ?csplines
2343: The `csplines` option connects consecutive points by natural cubic splines
2344: after rendering the data monotonic (see `smooth unique`).
2345: 5 sbezier
2346: ?commands plot datafile smooth sbezier
2347: ?plot datafile smooth sbezier
2348: ?plot smooth sbezier
2349: ?data-file smooth sbezier
2350: ?datafile smooth sbezier
2351: ?plot sbezier
2352: ?smooth sbezier
2353: ?sbezier
2354: The `sbezier` option first renders the data monotonic (`unique`) and then
2355: applies the `bezier` algorithm.
2356: 5 unique
2357: ?commands plot datafile smooth unique
2358: ?plot datafile smooth unique
2359: ?plot smooth unique
2360: ?data-file smooth unique
2361: ?datafile smooth unique
2362: ?plot unique
2363: ?smooth unique
2364: ?unique
2365: The `unique` option makes the data monotonic in x; points with the same
2366: x-value are replaced by a single point having the average y-value. The
2367: resulting points are then connected by straight line segments.
1.1.1.2 maekawa 2368: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/mgr.html"> See demos. </a>
1.1 maekawa 2369: 4 special-filenames
2370: ?commands plot datafile special-filenames
2371: ?plot datafile special-filenames
2372: ?plot special-filenames
2373: ?datafile special-filenames
2374: ?special-filenames
2375: A special filename of `'-'` specifies that the data are inline; i.e., they
2376: follow the command. Only the data follow the command; `plot` options like
2377: filters, titles, and line styles remain on the 'plot' command line. This is
2378: similar to << in unix shell script, and $DECK in VMS DCL. The data are
2379: entered as though they are being read from a file, one data point per record.
2380: The letter "e" at the start of the first column terminates data entry. The
2381: `using` option can be applied to these data---using it to filter them through
2382: a function might make sense, but selecting columns probably doesn't!
2383:
2384: `'-'` is intended for situations where it is useful to have data and commands
2385: together, e.g., when `gnuplot` is run as a sub-process of some front-end
2386: application. Some of the demos, for example, might use this feature. While
2387: `plot` options such as `index` and `every` are recognized, their use forces
2388: you to enter data that won't be used. For example, while
2389:
2390: plot '-' index 0, '-' index 1
2391: 2
2392: 4
2393: 6
2394:
2395:
2396: 10
2397: 12
2398: 14
2399: e
2400: 2
2401: 4
2402: 6
2403:
2404:
2405: 10
2406: 12
2407: 14
2408: e
2409:
2410: does indeed work,
2411:
2412: plot '-', '-'
2413: 2
2414: 4
2415: 6
2416: e
2417: 10
2418: 12
2419: 14
2420: e
2421:
2422: is a lot easier to type.
2423:
2424: If you use `'-'` with `replot`, you may need to enter the data more than once
2425: (see `replot`).
2426:
2427: A blank filename ('') specifies that the previous filename should be reused.
2428: This can be useful with things like
2429:
2430: plot 'a/very/long/filename' using 1:2, '' using 1:3, '' using 1:4
2431:
2432: (If you use both `'-'` and `''` on the same `plot` command, you'll need to
2433: have two sets of inline data, as in the example above.)
2434:
2435: On some computer systems with a popen function (Unix), the datafile can be
2436: piped through a shell command by starting the file name with a '<'. For
2437: example,
2438:
2439: pop(x) = 103*exp(-x/10)
2440: plot "< awk '{print $1-1965, $2}' population.dat", pop(x)
2441:
2442: would plot the same information as the first population example but with
2443: years since 1965 as the x axis. If you want to execute this example, you
2444: have to delete all comments from the data file above or substitute the
2445: following command for the first part of the command above (the part up to
2446: the comma):
2447:
2448: plot "< awk '$0 !~ /^#/ {print $1-1965, $2}' population.dat"
2449:
2450: While this approach is most flexible, it is possible to achieve simple
2451: filtering with the `using` or `thru` keywords.
2452: 4 thru
2453: ?commands plot datafile thru
2454: ?plot datafile thru
2455: ?plot thru
2456: ?data-file thru
2457: ?datafile thru
2458: ?thru
2459: The `thru` function is provided for backward compatibility.
2460:
2461: Syntax:
2462: plot 'file' thru f(x)
2463:
2464: It is equivalent to:
2465:
2466: plot 'file' using 1:(f($2))
2467:
2468: While the latter appears more complex, it is much more flexible. The more
2469: natural
2470:
2471: plot 'file' thru f(y)
2472:
2473: also works (i.e. you can use y as the dummy variable).
2474:
2475: `thru` is parsed for `splot` and `fit` but has no effect.
2476: 4 using
2477: ?commands plot datafile using
2478: ?plot datafile using
2479: ?plot using
2480: ?data-file using
2481: ?datafile using
2482: ?using
2483: The most common datafile modifier is `using`.
2484:
2485: Syntax:
2486: plot 'file' using {<entry> {:<entry> {:<entry> ...}}} {'format'}
2487:
2488: If a format is specified, each datafile record is read using the C library's
2489: 'scanf' function, with the specified format string. Otherwise the record is
2490: read and broken into columns at spaces or tabs. A format cannot be specified
2491: if time-format data is being used (this must be done by `set data time`).
2492:
2493: The resulting array of data is then sorted into columns according to the
2494: entries. Each <entry> may be a simple column number, which selects the
2495: datum, an expression enclosed in parentheses, or empty. The expression can
2496: use $1 to access the first item read, $2 for the second item, and so on. It
2497: can also use `column(x)` and `valid(x)` where x is an arbitrary expression
2498: resulting in an integer. `column(x)` returns the x'th datum; `valid(x)`
2499: tests that the datum in the x'th column is a valid number. A column number
2500: of 0 generates a number increasing (from zero) with each point, and is reset
2501: upon encountering two blank records. A column number of -1 gives the
2502: dataline number, which starts at 0, increments at single blank records, and
2503: is reset at double blank records. A column number of -2 gives the index
2504: number, which is incremented only when two blank records are found. An empty
2505: <entry> will default to its order in the list of entries. For example,
2506: `using ::4` is interpreted as `using 1:2:4`.
2507:
2508: N.B.---the `call` command also uses $'s as a special character. See `call`
2509: for details about how to include a column number in a `call` argument list.
2510:
2511: If the `using` list has but a single entry, that <entry> will be used for y
2512: and the data point number is used for x; for example, "`plot 'file' using 1`"
2513: is identical to "`plot 'file' using 0:1`". If the `using` list has two
2514: entries, these will be used for x and y. Additional entries are usually
2515: errors in x and/or y. See `set style` for details about plotting styles that
2516: make use of error information, and `fit` for use of error information in
2517: curve fitting.
2518:
2519: 'scanf' accepts several numerical specifications but `gnuplot` requires all
2520: inputs to be double-precision floating-point variables, so `lf` is the only
2521: permissible specifier. 'scanf' expects to see white space---a blank, tab
2522: ("\t"), newline ("\n"), or formfeed ("\f")---between numbers; anything else
2523: in the input stream must be explicitly skipped.
2524:
2525: Note that the use of "\t", "\n", or "\f" or requires use of double-quotes
2526: rather than single-quotes.
2527:
2528: Examples:
2529:
2530: This creates a plot of the sum of the 2nd and 3rd data against the first:
2531: (The format string specifies comma- rather than space-separated columns.)
2532: plot 'file' using 1:($2+$3) '%lf,%lf,%lf'
2533:
2534: In this example the data are read from the file "MyData" using a more
2535: complicated format:
2536: plot 'MyData' using "%*lf%lf%*20[^\n]%lf"
2537:
2538: The meaning of this format is:
2539:
2540: %*lf ignore a number
2541: %lf read a double-precision number (x by default)
2542: %*20[^\n] ignore 20 non-newline characters
2543: %lf read a double-precision number (y by default)
2544:
2545: One trick is to use the ternary `?:` operator to filter data:
2546:
2547: plot 'file' using 1:($3>10 ? $2 : 1/0)
2548:
2549: which plots the datum in column two against that in column one provided
2550: the datum in column three exceeds ten. `1/0` is undefined; `gnuplot`
2551: quietly ignores undefined points, so unsuitable points are suppressed.
2552:
2553: In fact, you can use a constant expression for the column number, provided it
2554: doesn't start with an opening parenthesis; constructs like `using
2555: 0+(complicated expression)` can be used. The crucial point is that the
2556: expression is evaluated once if it doesn't start with a left parenthesis, or
2557: once for each data point read if it does.
2558:
2559: If timeseries data are being used, the time can span multiple columns. The
2560: starting column should be specified. Note that the spaces within the time
2561: must be included when calculating starting columns for other data. E.g., if
2562: the first element on a line is a time with an embedded space, the y value
2563: should be specified as column three.
2564:
2565: It should be noted that `plot 'file'`, `plot 'file' using 1:2`, and `plot
2566: 'file' using ($1):($2)` can be subtly different: 1) if `file` has some lines
2567: with one column and some with two, the first will invent x values when they
2568: are missing, the second will quietly ignore the lines with one column, and
2569: the third will store an undefined value for lines with one point (so that in
2570: a plot with lines, no line joins points across the bad point); 2) if a line
2571: contains text at the first column, the first will abort the plot on an error,
2572: but the second and third should quietly skip the garbage.
2573:
2574: In fact, it is often possible to plot a file with lots of lines of garbage at
2575: the top simply by specifying
2576:
2577: plot 'file' using 1:2
2578:
2579: However, if you want to leave text in your data files, it is safer to put the
2580: comment character (#) in the first column of the text lines.
1.1.1.2 maekawa 2581: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/using.html"> Feeble using demos. </a>
1.1 maekawa 2582: 3 errorbars
2583: ?commands plot errorbars
2584: ?commands splot errorbars
2585: ?plot errorbars
2586: ?splot errorbars
2587: ?errorbars
2588: Error bars are supported for 2-d data file plots by reading one to four
2589: additional columns (or `using` entries); these additional values are used in
2590: different ways by the various errorbar styles.
2591:
2592: In the default situation, `gnuplot` expects to see three, four, or six
2593: numbers on each line of the data file---either
2594:
2595: (x, y, ydelta),
2596: (x, y, ylow, yhigh),
2597: (x, y, xdelta),
2598: (x, y, xlow, xhigh),
2599: (x, y, xdelta, ydelta), or
2600: (x, y, xlow, xhigh, ylow, yhigh).
2601:
2602: The x coordinate must be specified. The order of the numbers must be
2603: exactly as given above, though the `using` qualifier can manipulate the order
2604: and provide values for missing columns. For example,
2605:
2606: plot 'file' with errorbars
2607: plot 'file' using 1:2:(sqrt($1)) with xerrorbars
2608: plot 'file' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars
2609:
2610: The last example is for a file containing an unsupported combination of
2611: relative x and absolute y errors. The `using` entry generates absolute x min
2612: and max from the relative error.
2613:
2614: The y error bar is a vertical line plotted from (x, ylow) to (x, yhigh).
2615: If ydelta is specified instead of ylow and yhigh, ylow = y - ydelta and
2616: yhigh = y + ydelta are derived. If there are only two numbers on the record,
2617: yhigh and ylow are both set to y. The x error bar is a horizontal line
2618: computed in the same fashion. To get lines plotted between the data points,
2619: `plot` the data file twice, once with errorbars and once with lines (but
2620: remember to use the `notitle` option on one to avoid two entries in the key).
2621:
2622: The error bars have crossbars at each end unless `set bar` is used (see `set
2623: bar` for details).
2624:
2625: If autoscaling is on, the ranges will be adjusted to include the error bars.
2626: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html"> Errorbar demos. </a>
2627:
2628: See `plot using`, `plot with`, and `set style` for more information.
2629: 3 parametric
2630: ?commands plot parametric
2631: ?commands splot parametric
2632: ?plot parametric
2633: ?splot parametric
2634: ?parametric
2635: When in parametric mode (`set parametric`) mathematical expressions must be
2636: given in pairs for `plot` and in triplets for `splot`.
2637:
2638: Examples:
2639: plot sin(t),t**2
2640: splot cos(u)*cos(v),cos(u)*sin(v),sin(u)
2641:
2642: Data files are plotted as before, except any preceding parametric function
2643: must be fully specified before a data file is given as a plot. In other
2644: words, the x parametric function (`sin(t)` above) and the y parametric
2645: function (`t**2` above) must not be interrupted with any modifiers or data
2646: functions; doing so will generate a syntax error stating that the parametric
2647: function is not fully specified.
2648:
2649: Other modifiers, such as `with` and `title`, may be specified only after the
2650: parametric function has been completed:
2651:
2652: plot sin(t),t**2 title 'Parametric example' with linespoints
1.1.1.2 maekawa 2653: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/param.html"> Parametric Mode Demos. </a>
1.1 maekawa 2654: 3 ranges
2655: ?commands plot ranges
2656: ?commands splot ranges
2657: ?plot ranges
2658: ?splot ranges
2659: ?ranges
2660: The optional ranges specify the region of the graph that will be displayed.
2661:
2662: Syntax:
2663: [{<dummy-var>=}{{<min>}:{<max>}}]
2664: [{{<min>}:{<max>}}]
2665:
2666: The first form applies to the independent variable (`xrange` or `trange`, if
2667: in parametric mode). The second form applies to the dependent variable
2668: `yrange` (and `xrange`, too, if in parametric mode). <dummy-var> is a new
2669: name for the independent variable. (The defaults may be changed with `set
2670: dummy`.) The optional <min> and <max> terms can be constant expressions or *.
2671:
2672: In non-parametric mode, the order in which ranges must be given is `xrange`
2673: and `yrange`.
2674:
2675: In parametric mode, the order for the `plot` command is `trange`, `xrange`,
2676: and `yrange`. The following `plot` command shows setting the `trange` to
2677: [-pi:pi], the `xrange` to [-1.3:1.3] and the `yrange` to [-1:1] for the
2678: duration of the graph:
2679:
2680: plot [-pi:pi] [-1.3:1.3] [-1:1] sin(t),t**2
2681:
2682: Note that the x2range and y2range cannot be specified here---`set x2range`
2683: and `set y2range` must be used.
2684:
2685: Ranges are interpreted in the order listed above for the appropriate mode.
2686: Once all those needed are specified, no further ones must be listed, but
2687: unneeded ones cannot be skipped---use an empty range `[]` as a placeholder.
2688:
2689: `*` can be used to allow autoscaling of either of min and max. See also
2690: `set autoscale`.
2691:
2692: Ranges specified on the `plot` or `splot` command line affect only that
2693: graph; use the `set xrange`, `set yrange`, etc., commands to change the
2694: default ranges for future graphs.
2695:
2696: With time data, you must provide the range (in the same manner as the time
2697: appears in the datafile) within quotes. `gnuplot` uses the `timefmt` string
2698: to read the value---see `set timefmt`.
2699:
2700: Examples:
2701:
2702: This uses the current ranges:
2703: plot cos(x)
2704:
2705: This sets the x range only:
2706: plot [-10:30] sin(pi*x)/(pi*x)
2707:
2708: This is the same, but uses t as the dummy-variable:
2709: plot [t = -10 :30] sin(pi*t)/(pi*t)
2710:
2711: This sets both the x and y ranges:
2712: plot [-pi:pi] [-3:3] tan(x), 1/x
2713:
2714: This sets only the y range, and turns off autoscaling on both axes:
2715: plot [ ] [-2:sin(5)*-8] sin(x)**besj0(x)
2716:
2717: This sets xmax and ymin only:
2718: plot [:200] [-pi:] exp(sin(x))
2719:
2720: This sets the x range for a timeseries:
2721: set timefmt "%d/%m/%y %H:%M"
2722: plot ["1/6/93 12:00":"5/6/93 12:00"] 'timedata.dat'
2723:
2724: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/ranges/ranges.html"> See Demo. </a>
2725: 3 title
2726: ?commands plot title
2727: ?commands splot title
2728: ?plot title
2729: ?splot title
2730: A line title for each function and data set appears in the key, accompanied
2731: by a sample of the line and/or symbol used to represent it. It can be
2732: changed by using the `title` option.
2733:
2734: Syntax:
2735: title "<title>" | notitle
2736:
2737: where <title> is the new title of the line and must be enclosed in quotes.
2738: The quotes will not be shown in the key. A special character may be given as
2739: a backslash followed by its octal value ("\345"). The tab character "\t" is
2740: understood. Note that backslash processing occurs only for strings enclosed
2741: in double quotes---use single quotes to prevent such processing. The newline
2742: character "\n" is not processed in key entries in either type of string.
2743:
2744: The line title and sample can be omitted from the key by using the keyword
2745: `notitle`. A null title (`title ''`) is equivalent to `notitle`. If only
2746: the sample is wanted, use one or more blanks (`title ' '`).
2747:
2748: By default the line title is the function or file name as it appears on the
2749: `plot` command. If it is a file name, any datafile modifiers specified will
2750: be included in the default title.
2751:
2752: The layout of the key itself (position, title justification, etc.) can be
2753: controlled by `set key`. Please see `set key` for details.
2754:
2755: Examples:
2756:
2757: This plots y=x with the title 'x':
2758: plot x
2759:
2760: This plots x squared with title "x^2" and file "data.1" with title
2761: "measured data":
2762: plot x**2 title "x^2", 'data.1' t "measured data"
2763:
2764: This puts an untitled circular border around a polar graph:
2765: set polar; plot my_function(t), 1 notitle
2766: 3 with
2767: ?commands plot with
2768: ?commands splot with
2769: ?commands plot style
2770: ?commands splot style
2771: ?plot with
2772: ?plot style
2773: ?splot with
2774: ?splot style
2775: ?style
2776: ?with
2777: Functions and data may be displayed in one of a large number of styles.
2778: The `with` keyword provides the means of selection.
2779:
2780: Syntax:
2781: with <style> { {linestyle | ls <line_style>}
2782: | {{linetype | lt <line_type>}
2783: {linewidth | lw <line_width>}
2784: {pointtype | pt <point_type>}
2785: {pointsize | ps <point_size>}} }
2786:
2787: where <style> is either `lines`, `points`, `linespoints`, `impulses`, `dots`,
2788: `steps`, `fsteps`, `histeps`, `errorbars`, `xerrorbars`, `yerrorbars`,
2789: `xyerrorbars`, `boxes`, `boxerrorbars`, `boxxyerrorbars`, `financebars`,
2790: `candlesticks` or `vector`. Some of these styles require additional
2791: information. See `set style <style>` for details of each style.
2792:
2793: Default styles are chosen with the `set function style` and `set data style`
2794: commands.
2795:
2796: By default, each function and data file will use a different line type and
2797: point type, up to the maximum number of available types. All terminal
2798: drivers support at least six different point types, and re-use them, in
2799: order, if more are required. The LaTeX driver supplies an additional six
2800: point types (all variants of a circle), and thus will only repeat after 12
2801: curves are plotted with points. The PostScript drivers (`postscript`)
2802: supplies a total of 64.
2803:
2804: If you wish to choose the line or point type for a single plot, <line_type>
2805: and <point_type> may be specified. These are positive integer constants (or
2806: expressions) that specify the line type and point type to be used for the
2807: plot. Use `test` to display the types available for your terminal.
2808:
2809: You may also scale the line width and point size for a plot by using
2810: <line_width> and <point_size>, which are specified relative to the default
2811: values for each terminal. The pointsize may also be altered globally---see
2812: `set pointsize` for details. But note that both <point_size> as set here and
2813: as set by `set pointsize` multiply the default point size---their effects are
2814: not cumulative. That is, `set pointsize 2; plot x w p ps 3` will use points
2815: three times default size, not six.
2816:
2817: If you have defined specific line type/width and point type/size combinations
2818: with `set linestyle`, one of these may be selected by setting <line_style> to
2819: the index of the desired style.
2820:
2821: The keywords may be abbreviated as indicated.
2822:
2823: Note that the `linewidth` and `pointsize` options are not supported by all
2824: terminals.
2825:
2826: Examples:
2827:
2828: This plots sin(x) with impulses:
2829: plot sin(x) with impulses
2830:
2831: This plots x with points, x**2 with the default:
1.1.1.3 ! ohara 2832: plot x w points, x**2
1.1 maekawa 2833:
2834: This plots tan(x) with the default function style, file "data.1" with lines:
2835: plot [ ] [-2:5] tan(x), 'data.1' with l
2836:
2837: This plots "leastsq.dat" with impulses:
2838: plot 'leastsq.dat' w i
2839:
2840: This plots the data file "population" with boxes:
2841: plot 'population' with boxes
2842:
2843: This plots "exper.dat" with errorbars and lines connecting the points
2844: (errorbars require three or four columns):
2845: plot 'exper.dat' w lines, 'exper.dat' notitle w errorbars
2846:
2847: This plots sin(x) and cos(x) with linespoints, using the same line type but
2848: different point types:
2849: plot sin(x) with linesp lt 1 pt 3, cos(x) with linesp lt 1 pt 4
2850:
2851: This plots file "data" with points of type 3 and twice usual size:
2852: plot 'data' with points pointtype 3 pointsize 2
2853:
2854: This plots two data sets with lines differing only by weight:
2855: plot 'd1' t "good" w l lt 2 lw 3, 'd2' t "bad" w l lt 2 lw 1
2856:
2857: See `set style` to change the default styles.
2858: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/styles/styles.html"> Styles demos. </a>
2859: 2 print
2860: ?commands print
2861: ?print
2862: The `print` command prints the value of <expression> to the screen. It is
2863: synonymous with `pause 0`. <expression> may be anything that `gnuplot` can
2864: evaluate that produces a number, or it can be a string.
2865:
2866: Syntax:
2867: print <expression> {, <expression>, ...}
2868:
2869: See `expressions`.
2870: 2 pwd
2871: ?commands pwd
2872: ?pwd
2873: The `pwd` command prints the name of the working directory to the screen.
2874: 2 quit
2875: ?commands quit
2876: ?quit
2877: The `exit` and `quit` commands and END-OF-FILE character will exit `gnuplot`.
2878: Each of these commands will clear the output device (as does the `clear`
2879: command) before exiting.
2880: 2 replot
2881: ?commands replot
2882: ?replot
2883: The `replot` command without arguments repeats the last `plot` or `splot`
2884: command. This can be useful for viewing a plot with different `set` options,
2885: or when generating the same plot for several devices.
2886:
2887: Arguments specified after a `replot` command will be added onto the last
2888: `plot` or `splot` command (with an implied ',' separator) before it is
2889: repeated. `replot` accepts the same arguments as the `plot` and `splot`
2890: commands except that ranges cannot be specified. Thus you can use `replot`
2891: to plot a function against the second axes if the previous command was `plot`
2892: but not if it was `splot`, and similarly you can use `replot` to add a plot
2893: from a binary file only if the previous command was `splot`.
2894:
2895: N.B.---use of
2896:
2897: plot '-' ; ... ; replot
2898:
2899: is not recommended. `gnuplot` does not store the inline data internally, so
2900: since `replot` appends new information to the previous `plot` and then
2901: executes the modified command, the `'-'` from the initial `plot` will expect
2902: to read inline data again.
2903:
2904: Note that `replot` does not work in `multiplot` mode, since it reproduces
2905: only the last plot rather than the entire screen.
2906:
2907: See also `command-line-editing` for ways to edit the last `plot` (`splot`)
2908: command.
2909: 2 reread
2910: ?commands reread
2911: ?reread
2912: The `reread` command causes the current `gnuplot` command file, as specified
2913: by a `load` command or on the command line, to be reset to its starting
2914: point before further commands are read from it. This essentially implements
2915: an endless loop of the commands from the beginning of the command file to
2916: the `reread` command. (But this is not necessarily a disaster---`reread` can
2917: be very useful when used in conjunction with `if`. See `if` for details.)
2918: The `reread` command has no effect if input from standard input.
2919:
2920: Examples:
2921:
2922: Suppose the file "looper" contains the commands
2923: a=a+1
2924: plot sin(x*a)
2925: pause -1
2926: if(a<5) reread
2927: and from within `gnuplot` you submit the commands
2928: a=0
2929: load 'looper'
2930: The result will be four plots (separated by the `pause` message).
2931:
2932: Suppose the file "data" contains six columns of numbers with a total yrange
2933: from 0 to 10; the first is x and the next are five different functions of x.
2934: Suppose also that the file "plotter" contains the commands
2935: c_p = c_p+1
2936: plot "$0" using 1:c_p with lines linetype c_p
2937: if(c_p < n_p) reread
2938: and from within `gnuplot` you submit the commands
2939: n_p=6
2940: c_p=1
2941: set nokey
2942: set yrange [0:10]
2943: set multiplot
2944: call 'plotter' 'data'
2945: set nomultiplot
2946: The result is a single graph consisting of five plots. The yrange must be
2947: set explicitly to guarantee that the five separate graphs (drawn on top of
2948: each other in multiplot mode) will have exactly the same axes. The linetype
2949: must be specified; otherwise all the plots would be drawn with the same type.
1.1.1.2 maekawa 2950: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/animate.html"> Reread Animation Demo</a>
1.1 maekawa 2951: 2 reset
2952: ?commands reset
2953: ?reset
2954: The `reset` command causes all options that can be set with the `set`
2955: command to take on their default values. The only exceptions are that the
2956: terminal set with `set term` and the output file set with `set output` are
2957: left unchanged. This command is useful, e.g., to restore the default
2958: settings at the end of a command file, or to return to a defined state after
2959: lots of settings have been changed within a command file. Please refer to
2960: the `set` command to see the default values that the various options take.
2961: 2 save
2962: ?commands save
2963: ?save
2964: The `save` command saves user-defined functions, variables, `set` options,
2965: or all three, plus the last `plot` (`splot`) command to the specified file.
2966:
2967: Syntax:
2968: save {<option>} '<filename>'
2969:
2970: where <option> is `functions`, `variables` or `set`. If no option is used,
2971: `gnuplot` saves functions, variables, `set` options and the last `plot`
2972: (`splot`) command.
2973:
2974: `save`d files are written in text format and may be read by the `load`
2975: command.
2976:
2977: The filename must be enclosed in quotes.
2978:
2979: Examples:
2980: save 'work.gnu'
2981: save functions 'func.dat'
2982: save var 'var.dat'
2983: save set 'options.dat'
2984: 2 set-show
2985: ?commands set
2986: ?commands show
2987: ?set
2988: ?show
2989: ?show all
2990: The `set` command can be used to sets _lots_ of options. No screen is
2991: drawn, however, until a `plot`, `splot`, or `replot` command is given.
2992:
2993: The `show` command shows their settings; `show all` shows all the
2994: settings.
2995:
2996: If a variable contains time/date data, `show` will display it according to
2997: the format currently defined by `set timefmt`, even if that was not in effect
2998: when the variable was initially defined.
2999: 3 angles
3000: ?commands set angles
3001: ?commands show angles
3002: ?set angles
3003: ?show angles
3004: ?angles
3005: ?commands set angles degrees
3006: ?set angles degrees
3007: ?angles degrees
3008: ?degrees
3009: By default, `gnuplot` assumes the independent variable in polar graphs is in
3010: units of radians. If `set angles degrees` is specified before `set polar`,
3011: then the default range is [0:360] and the independent variable has units of
3012: degrees. This is particularly useful for plots of data files. The angle
3013: setting also applies to 3-d mapping as set via the `set mapping` command.
3014:
3015: Syntax:
3016: set angles {degrees | radians}
3017: show angles
3018:
3019: The angle specified in `set grid polar` is also read and displayed in the
3020: units specified by `set angles`.
3021:
3022: `set angles` also affects the arguments of the machine-defined functions
3023: sin(x), cos(x) and tan(x), and the outputs of asin(x), acos(x), atan(x),
3024: atan2(x), and arg(x). It has no effect on the arguments of hyperbolic
3025: functions or Bessel functions. However, the output arguments of inverse
3026: hyperbolic functions of complex arguments are affected; if these functions
3027: are used, `set angles radians` must be in effect to maintain consistency
3028: between input and output arguments.
3029:
3030: x={1.0,0.1}
3031: set angles radians
3032: y=sinh(x)
3033: print y #prints {1.16933, 0.154051}
3034: print asinh(y) #prints {1.0, 0.1}
3035: but
3036: set angles degrees
3037: y=sinh(x)
3038: print y #prints {1.16933, 0.154051}
3039: print asinh(y) #prints {57.29578, 5.729578}
1.1.1.2 maekawa 3040: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html"> Polar plot using `set angles`. </a>
1.1 maekawa 3041: 3 arrow
3042: ?commands set arrow
3043: ?commands set noarrow
3044: ?commands show arrow
3045: ?set arrow
3046: ?set noarrow
3047: ?show arrow
3048: ?arrow
3049: ?noarrow
3050: Arbitrary arrows can be placed on a plot using the `set arrow` command.
3051:
3052: Syntax:
3053: set arrow {<tag>} {from <position>} {to <position>} {{no}head}
3054: { {linestyle | ls <line_style>}
3055: | {linetype | lt <line_type>}
3056: {linewidth | lw <line_width} }
3057: set noarrow {<tag>}
3058: show arrow
3059:
3060: <tag> is an integer that identifies the arrow. If no tag is given, the
3061: lowest unused tag value is assigned automatically. The tag can be used to
3062: delete or change a specific arrow. To change any attribute of an existing
3063: arrow, use the `set arrow` command with the appropriate tag and specify the
3064: parts of the arrow to be changed.
3065:
3066: The <position>s are specified by either x,y or x,y,z, and may be preceded by
3067: `first`, `second`, `graph`, or `screen` to select the coordinate system.
3068: Unspecified coordinates default to 0. The endpoints can be specified in
3069: one of four coordinate systems---`first` or `second` axes, `graph` or
3070: `screen`. See `coordinates` for details. A coordinate system specifier
3071: does not carry over from the "from" position to the "to" position. Arrows
3072: outside the screen boundaries are permitted but may cause device errors.
3073:
3074: Specifying `nohead` produces an arrow drawn without a head---a line segment.
3075: This gives you yet another way to draw a line segment on the plot. By
3076: default, arrows have heads.
3077:
3078: The line style may be selected from a user-defined list of line styles (see
3079: `set linestyle`) or may be defined here by providing values for <line_type>
3080: (an index from the default list of styles) and/or <line_width> (which is a
3081: multiplier for the default width).
3082:
3083: Note, however, that if a user-defined line style has been selected, its
3084: properties (type and width) cannot be altered merely by issuing another
3085: `set arrow` command with the appropriate index and `lt` or `lw`.
3086:
3087: Examples:
3088:
3089: To set an arrow pointing from the origin to (1,2) with user-defined style 5,
3090: use:
3091: set arrow to 1,2 ls 5
3092:
3093: To set an arrow from bottom left of plotting area to (-5,5,3), and tag the
3094: arrow number 3, use:
3095: set arrow 3 from graph 0,0 to -5,5,3
3096:
3097: To change the preceding arrow to end at 1,1,1, without an arrow head and
3098: double its width, use:
3099: set arrow 3 to 1,1,1 nohead lw 2
3100:
3101: To draw a vertical line from the bottom to the top of the graph at x=3, use:
3102: set arrow from 3, graph 0 to 3, graph 1 nohead
3103:
3104: To delete arrow number 2, use:
3105: set noarrow 2
3106:
3107: To delete all arrows, use:
3108: set noarrow
3109:
3110: To show all arrows (in tag order), use:
3111: show arrow
3112: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/arrows/arrows.html"> Arrows Demos. </a>
3113: 3 autoscale
3114: ?commands set autoscale
3115: ?commands set noautoscale
3116: ?commands show autoscale
3117: ?set autoscale
3118: ?set noautoscale
3119: ?show autoscale
3120: ?autoscale
3121: ?noautoscale
3122: Autoscaling may be set individually on the x, y or z axis or globally on all
3123: axes. The default is to autoscale all axes.
3124:
3125: Syntax:
3126: set autoscale {<axes>{min|max}}
3127: set noautoscale {<axes>{min|max}}
3128: show autoscale
3129:
3130: where <axes> is either `x`, `y`, `z`, `x2`, `y2` or `xy`. A keyword with
3131: `min` or `max` appended (this cannot be done with `xy`) tells `gnuplot` to
3132: autoscale just the minimum or maximum of that axis. If no keyword is given,
3133: all axes are autoscaled.
3134:
3135: When autoscaling, the axis range is automatically computed and the dependent
3136: axis (y for a `plot` and z for `splot`) is scaled to include the range of the
3137: function or data being plotted.
3138:
3139: If autoscaling of the dependent axis (y or z) is not set, the current y or z
3140: range is used.
3141:
3142: Autoscaling the independent variables (x for `plot` and x,y for `splot`) is a
3143: request to set the domain to match any data file being plotted. If there are
3144: no data files, autoscaling an independent variable has no effect. In other
3145: words, in the absence of a data file, functions alone do not affect the x
3146: range (or the y range if plotting z = f(x,y)).
3147:
3148: Please see `set xrange` for additional information about ranges.
3149:
3150: The behavior of autoscaling remains consistent in parametric mode, (see `set
3151: parametric`). However, there are more dependent variables and hence more
3152: control over x, y, and z axis scales. In parametric mode, the independent or
3153: dummy variable is t for `plot`s and u,v for `splot`s. `autoscale` in
3154: parametric mode, then, controls all ranges (t, u, v, x, y, and z) and allows
3155: x, y, and z to be fully autoscaled.
3156:
3157: Autoscaling works the same way for polar mode as it does for parametric mode
3158: for `plot`, with the extension that in polar mode `set dummy` can be used to
3159: change the independent variable from t (see `set dummy`).
3160:
3161: When tics are displayed on second axes but no plot has been specified for
3162: those axes, x2range and y2range are inherited from xrange and yrange. This
3163: is done _before_ xrange and yrange are autoextended to a whole number of
3164: tics, which can cause unexpected results.
3165:
3166: Examples:
3167:
3168: This sets autoscaling of the y axis (other axes are not affected):
3169: set autoscale y
3170:
3171: This sets autoscaling only for the minimum of the y axis (the maximum of the
3172: y axis and the other axes are not affected):
3173: set autoscale ymin
3174:
3175: This sets autoscaling of the x and y axes:
3176: set autoscale xy
3177:
3178: This sets autoscaling of the x, y, z, x2 and y2 axes:
3179: set autoscale
3180:
3181: This disables autoscaling of the x, y, z, x2 and y2 axes:
3182: set noautoscale
3183:
3184: This disables autoscaling of the z axis only:
3185: set noautoscale z
3186: 4 parametric mode
3187: ?commands set autoscale parametric
3188: ?set autoscale parametric
3189: ?set autoscale t
3190: When in parametric mode (`set parametric`), the xrange is as fully scalable
3191: as the y range. In other words, in parametric mode the x axis can be
3192: automatically scaled to fit the range of the parametric function that is
3193: being plotted. Of course, the y axis can also be automatically scaled just
3194: as in the non-parametric case. If autoscaling on the x axis is not set, the
3195: current x range is used.
3196:
3197: Data files are plotted the same in parametric and non-parametric mode.
3198: However, there is a difference in mixed function and data plots: in
3199: non-parametric mode with autoscaled x, the x range of the datafile controls
3200: the x range of the functions; in parametric mode it has no influence.
3201:
3202: For completeness a last command `set autoscale t` is accepted. However, the
3203: effect of this "scaling" is very minor. When `gnuplot` determines that the
3204: t range would be empty, it makes a small adjustment if autoscaling is true.
3205: Otherwise, `gnuplot` gives an error. Such behavior may, in fact, not be very
3206: useful and the command `set autoscale t` is certainly questionable.
3207:
3208: `splot` extends the above ideas as you would expect. If autoscaling is set,
3209: then x, y, and z ranges are computed and each axis scaled to fit the
3210: resulting data.
3211: 4 polar mode
3212: ?commands set autoscale polar
3213: ?set autoscale polar
3214: ?set autoscale t
3215: When in polar mode (`set polar`), the xrange and the yrange are both found
3216: from the polar coordinates, and thus they can both be automatically scaled.
3217: In other words, in polar mode both the x and y axes can be automatically
3218: scaled to fit the ranges of the polar function that is being plotted.
3219:
3220: When plotting functions in polar mode, the rrange may be autoscaled. When
3221: plotting data files in polar mode, the trange may also be autoscaled. Note
3222: that if the trange is contained within one quadrant, autoscaling will produce
3223: a polar plot of only that single quadrant.
3224:
3225: Explicitly setting one or two ranges but not others may lead to unexpected
3226: results.
1.1.1.2 maekawa 3227: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html"> See polar demos </a>
1.1 maekawa 3228: 3 bar
3229: ?commands set bar
3230: ?commands show bar
3231: ?set bar
3232: ?show bar
3233: The `set bar` command controls the tics at the ends of errorbars.
3234:
3235: Syntax:
3236: set bar {small | large | <size>}
3237: show bar
3238:
3239: `small` is a synonym for 0.0, and `large` for 1.0.
3240: The default is 1.0 if no size is given.
3241: 3 bmargin
3242: ?commands set bmargin
3243: ?set bmargin
3244: ?bmargin
3245: The command `set bmargin` sets the size of the bottom margin. Please see
3246: `set margin` for details.
3247: 3 border
3248: ?commands set border
3249: ?commands set noborder
3250: ?commands show border
3251: ?set border
3252: ?set noborder
3253: ?show border
3254: ?border
3255: ?noborder
3256: The `set border` and `set noborder` commands control the display of the graph
3257: borders for the `plot` and `splot` commands.
3258:
3259: Syntax:
3260: set border {<integer> { {linestyle | ls <line_style>}
3261: | {linetype | lt <line_type> }
3262: {linewidth | lw <line_width>} } }
3263: set noborder
3264: show border
3265:
3266: The borders are encoded in a 12-bit integer: the bottom four bits control the
3267: border for `plot` and the sides of the base for `splot`; The next four bits
3268: control the verticals in `splot`; the top four bits control the edges on top
3269: of the `splot`. In detail, the `<integer>` should be the sum of the
3270: appropriate entries from the following table:
3271:
3272: @start table - first is interactive cleartext form
3273: plot border splot splot
3274: Side splot base verticals top
3275: bottom (south) 1 16 256
3276: left (west) 2 32 512
3277: top (north) 4 64 1024
3278: right (east) 8 128 2048
3279: #\begin{tabular}{|cc|ccc|} \hline
3280: #\multicolumn{5}{|c|}{Graph Border Encoding} \\ \hline \hline
3281: # & & \multicolumn{3}{|c|}{Integer value of selection bit} \\ \cline{3-5}
3282: # & & plot border & splot & splot \\
3283: #\multicolumn{2}{|c|}{Side}& splot base & verticals & top \\ \hline
3284: #bottom & (south) & 1 & 16 & 256 \\
3285: #left & (west) & 2 & 32 & 512 \\
3286: #top & (north) & 4 & 64 & 1024 \\
3287: #right & (east) & 8 & 128 & 2048 \\
3288: %c c c c c .
3289: %@plot border@splot@splot
3290: %@splot base@verticals@top
3291: %_
3292: %bottom (south)@1@16@256
3293: %left (west)@2@32@512
3294: %top (north)@4@64@1024
3295: %right (east)@8@128@2048
3296: @end table
3297:
3298: The default is 31, which is all four sides for `plot`, and base and z axis
3299: for `splot`.
3300:
3301: Using the optional <line_style>, <line_type> and <line_width>
3302: specifiers, the way the border lines are drawn can be influenced
1.1.1.2 maekawa 3303: (limited by what the current terminal driver supports). By default,
3304: the border is drawn with twice the usual linewidth. The <line_width>
3305: specifier scales this default value; for example, `set border 15 lw 2`
3306: will produce a border with four times the usual linewidth.
1.1 maekawa 3307:
3308: Various axes or combinations of axes may be added together in the command.
3309:
3310: To have tics on edges other than bottom and left, disable the usual tics and
3311: enable the second axes.
3312:
3313: Examples:
3314:
3315: Draw all borders:
3316: set border
3317:
3318: Draw only the SOUTHWEST borders:
3319: set border 3
3320:
3321: Draw a complete box around a `splot`:
3322: set border 4095
3323:
3324: Draw a partial box, omitting the front vertical:
3325: set border 127+256+512
3326:
3327: Draw only the NORTHEAST borders:
3328: set noxtics; set noytics; set x2tics; set y2tics; set border 12
3329:
3330: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/borders/borders.html"> Borders Demo. </a>
3331: 3 boxwidth
3332: ?commands set boxwidth
3333: ?commands show boxwidth
3334: ?set boxwidth
3335: ?show boxwidth
3336: ?boxwidth
3337: The `set boxwidth` command is used to set the default width of boxes in the
3338: `boxes` and `boxerrorbars` styles.
3339:
3340: Syntax:
3341: set boxwidth {<width>}
3342: show boxwidth
3343:
3344: If a data file is plotted without the width being specified in the third,
3345: fourth, or fifth column (or `using` entry), or if a function is plotted, the
3346: width of each box is set by the `set boxwidth` command. (If a width is given
3347: both in the file and by the `set boxwidth` command, the one in the file is
3348: used.) If the width is not specified in one of these ways, the width of each
3349: box will be calculated automatically so that it touches the adjacent boxes.
3350: In a four-column data set, the fourth column will be interpreted as the box
3351: width unless the width is set to -2.0, in which case the width will be
3352: calculated automatically. See `set style boxerrorbars` for more details.
3353:
3354: To set the box width to automatic use the command
3355: set boxwidth
3356: or, for four-column data,
3357: set boxwidth -2
3358:
3359: The same effect can be achieved with the `using` keyword in `plot`:
3360: plot 'file' using 1:2:3:4:(-2)
3361: 3 clabel
3362: ?commands set clabel
3363: ?commands set noclabel
3364: ?commands show clabel
3365: ?set clabel
3366: ?set noclabel
3367: ?show clabel
3368: ?clabel
3369: ?noclabel
3370: `gnuplot` will vary the linetype used for each contour level when clabel is
3371: set. When this option on (the default), a legend labels each linestyle with
3372: the z level it represents. It is not possible at present to separate the
3373: contour labels from the surface key.
3374:
3375: Syntax:
3376: set clabel {'<format>'}
3377: set noclabel
3378: show clabel
3379:
3380: The default for the format string is %8.3g, which gives three decimal places.
3381: This may produce poor label alignment if the key is altered from its default
3382: configuration.
3383:
3384: The first contour linetype, or only contour linetype when clabel is off, is
3385: the surface linetype +1; contour points are the same style as surface points.
3386:
3387: See also `set contour`.
3388: 3 clip
3389: ?commands set clip
3390: ?commands set noclip
3391: ?commands show clip
3392: ?set clip
3393: ?set noclip
3394: ?show clip
3395: ?clip
3396: ?noclip
3397: `gnuplot` can clip data points and lines that are near the boundaries of a
3398: graph.
3399:
3400: Syntax:
3401: set clip <clip-type>
3402: set noclip <clip-type>
3403: show clip
3404:
3405: Three clip types are supported by `gnuplot`: `points`, `one`, and `two`.
3406: One, two, or all three clip types may be active for a single graph.
3407:
3408: The `points` clip type forces `gnuplot` to clip (actually, not plot at all)
3409: data points that fall within but too close to the boundaries. This is done
3410: so that large symbols used for points will not extend outside the boundary
3411: lines. Without clipping points near the boundaries, the plot may look bad.
3412: Adjusting the x and y ranges may give similar results.
3413:
3414: Setting the `one` clip type causes `gnuplot` to draw a line segment which has
3415: only one of its two endpoints within the graph. Only the in-range portion of
3416: the line is drawn. The alternative is to not draw any portion of the line
3417: segment.
3418:
3419: Some lines may have both endpoints out of range, but pass through the graph.
3420: Setting the `two` clip-type allows the visible portion of these lines to be
3421: drawn.
3422:
3423: In no case is a line drawn outside the graph.
3424:
3425: The defaults are `noclip points`, `clip one`, and `noclip two`.
3426:
3427: To check the state of all forms of clipping, use
3428: show clip
3429:
3430: For backward compatibility with older versions, the following forms are also
3431: permitted:
3432: set clip
3433: set noclip
3434:
3435: `set clip` is synonymous with `set clip points`; `set noclip` turns off all
3436: three types of clipping.
3437: 3 cntrparam
3438: ?commands set cntrparam
3439: ?commands show cntrparam
3440: ?set cntrparam
3441: ?show cntrparam
3442: ?cntrparam
3443: `set cntrparam` controls the generation of contours and their smoothness for
3444: a contour plot. `show contour` displays current settings of `cntrparam` as
3445: well as `contour`.
3446:
3447: Syntax:
3448: set cntrparam { {linear | cubicspline | bspline}
3449: { points <n>} { order <n> }
3450: { levels auto {<n>} | <n>
3451: | discrete <z1> {,<z2>{,<z3>...}}
3452: | incremental <start>, <incr> {,<end>}
3453: }
3454: }
3455: show contour
3456:
3457: This command has two functions. First, it sets the values of z for which
3458: contour points are to be determined (by linear interpolation between data
3459: points or function isosamples.) Second, it controls the way contours are
3460: drawn between the points determined to be of equal z. <n> should be an
3461: integral constant expression and <z1>, <z2> ... any constant expressions.
3462: The parameters are:
3463:
3464: `linear`, `cubicspline`, `bspline`---Controls type of approximation or
3465: interpolation. If `linear`, then straight line segments connect points of
3466: equal z magnitude. If `cubicspline`, then piecewise-linear contours are
3467: interpolated between the same equal z points to form somewhat smoother
3468: contours, but which may undulate. If `bspline`, a guaranteed-smoother curve
3469: is drawn, which only approximates the position of the points of equal-z.
3470:
3471: `points`---Eventually all drawings are done with piecewise-linear strokes.
3472: This number controls the number of line segments used to approximate the
3473: `bspline` or `cubicspline` curve. Number of cubicspline or bspline
3474: segments (strokes) = `points` * number of linear segments.
3475:
3476: `order`---Order of the bspline approximation to be used. The bigger this
3477: order is, the smoother the resulting contour. (Of course, higher order
3478: bspline curves will move further away from the original piecewise linear
3479: data.) This option is relevant for `bspline` mode only. Allowed values are
3480: integers in the range from 2 (linear) to 10.
3481:
3482: `levels`--- Selection of contour levels, controlled by `auto` (default),
3483: `discrete`, `incremental`, and <n>, number of contour levels, limited to
3484: MAX_DISCRETE_LEVELS as defined in plot.h (30 is standard.)
3485:
3486: For `auto`, <n> specifies a nominal number of levels; the actual number will
3487: be adjusted to give simple labels. If the surface is bounded by zmin and zmax,
3488: contours will be generated at integer multiples of dz between zmin and zmax,
3489: where dz is 1, 2, or 5 times some power of ten (like the step between two
3490: tic marks).
3491:
3492: For `levels discrete`, contours will be generated at z = <z1>, <z2> ... as
3493: specified; the number of discrete levels sets the number of contour levels.
3494: In `discrete` mode, any `set cntrparms levels <n>` are ignored.
3495:
3496: For `incremental`, contours are generated at values of z beginning at <start>
3497: and increasing by <increment>, until the number of contours is reached. <end>
3498: is used to determine the number of contour levels, which will be changed by
3499: any subsequent `set cntrparam levels <n>`.
3500:
3501: If the command `set cntrparam` is given without any arguments specified, the
3502: defaults are used: linear, 5 points, order 4, 5 auto levels.
3503:
3504: Examples:
3505: set cntrparam bspline
3506: set cntrparam points 7
3507: set cntrparam order 10
3508:
3509: To select levels automatically, 5 if the level increment criteria are met:
3510: set cntrparam levels auto 5
3511:
3512: To specify discrete levels at .1, .37, and .9:
3513: set cntrparam levels discrete .1,1/exp(1),.9
3514:
3515: To specify levels from 0 to 4 with increment 1:
3516: set cntrparam levels incremental 0,1,4
3517:
3518: To set the number of levels to 10 (changing an incremental end or possibly
3519: the number of auto levels):
3520: set cntrparam levels 10
3521:
3522: To set the start and increment while retaining the number of levels:
3523: set cntrparam levels incremental 100,50
3524:
3525: See also `set contour` for control of where the contours are drawn, and `set
3526: clabel` for control of the format of the contour labels and linetypes.
1.1.1.2 maekawa 3527: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/contours.html">Contours Demo</a> and
3528: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/discrete.html">contours with User Defined Levels.</a>
1.1 maekawa 3529: 3 contour
3530: ?commands set contour
3531: ?commands set nocontour
3532: ?commands show contour
3533: ?set contour
3534: ?set nocontour
3535: ?show contour
3536: ?contour
3537: ?nocontour
3538: `set contour` enables contour drawing for surfaces. This option is available
3539: for `splot` only.
3540:
3541: Syntax:
3542: set contour {base | surface | both}
3543: set nocontour
3544: show contour
3545:
3546: The three options specify where to draw the contours: `base` draws the
3547: contours on the grid base where the x/ytics are placed, `surface` draws the
3548: contours on the surfaces themselves, and `both` draws the contours on both
3549: the base and the surface. If no option is provided, the default is `base`.
3550:
3551: See also `set cntrparam` for the parameters that affect the drawing of
3552: contours, and `set clabel` for control of labelling of the contours.
3553:
3554: The surface can be switched off (see `set surface`), giving a contour-only
3555: graph. Though it is possible to use `set size` to enlarge the plot to fill
3556: the screen, more control over the output format can be obtained by writing
3557: the contour information to a file, and rereading it as a 2-d datafile plot:
3558:
3559: set nosurface
3560: set contour
3561: set cntrparam ...
3562: set term table
3563: set out 'filename'
3564: splot ...
3565: set out
3566: # contour info now in filename
3567: set term <whatever>
3568: plot 'filename'
3569:
3570: In order to draw contours, the data should be organized as "grid data". In
3571: such a file all the points for a single y-isoline are listed, then all the
3572: points for the next y-isoline, and so on. A single blank line (a line
3573: containing no characters other than blank spaces and a carriage return and/or
3574: a line feed) separates one y-isoline from the next. See also `splot datafile`.
3575:
3576: If contours are desired from non-grid data, `set dgrid3d` can be used to
3577: create an appropriate grid. See `set dgrid3d` for more information.
1.1.1.2 maekawa 3578: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/contours.html">Contours Demo</a> and
3579: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/discrete.html">contours with User Defined Levels.</a>
1.1 maekawa 3580: 3 data style
3581: ?commands set data style
3582: ?commands show data style
3583: ?set data style
3584: ?show data style
3585: ?data style
3586: The `set data style` command changes the default plotting style for data
3587: plots.
3588:
3589: Syntax:
3590: set data style <style-choice>
3591: show data style
3592:
3593: See `set style` for the choices. If no choice is given, the choices are
3594: listed. `show data style` shows the current default data plotting style.
3595: 3 dgrid3d
3596: ?commands set dgrid3d
3597: ?commands set nodgrid3d
3598: ?commands show dgrid3d
3599: ?set dgrid3d
3600: ?set nodgrid3d
3601: ?show dgrid3d
3602: ?dgrid3d
3603: ?nodgrid3d
3604: The `set dgrid3d` command enables, and can set parameters for, non-grid
3605: to grid data mapping.
3606:
3607: Syntax:
3608: set dgrid3d {<row_size>} {,{<col_size>} {,<norm>}}
3609: set nodgrid3d
3610: show dgrid3d
3611:
3612: By default `dgrid3d` is disabled. When enabled, 3-d data read from a file
3613: are always treated as a scattered data set. A grid with dimensions derived
3614: from a bounding box of the scattered data and size as specified by the
3615: row/col_size parameters is created for plotting and contouring. The grid
3616: is equally spaced in x (rows) and in y (columns); the z values are computed
3617: as weighted averages of the scattered points' z values.
3618:
3619: The third parameter, norm, controls the weighting: Each data point is
3620: weighted inversely by its distance from the grid point raised to the norm
3621: power. (Actually, the weights are given by the inverse of dx^norm + dy^norm,
3622: where dx and dy are the components of the separation of the grid point from
3623: each data point. For some norms that are powers of two, specifically 4, 8,
3624: and 16, the computation is optimized by using the Euclidean distance in the
3625: weight calculation, (dx^2+dx^2)^norm/2. However, any non-negative integer
3626: can be used.)
3627:
3628: The closer the data point is to a grid point, the more effect it has on
3629: that grid point and the larger the value of norm the less effect more
3630: distant data points have on that grid point.
3631:
3632: The `dgrid3d` option is a simple low pass filter that converts scattered
3633: data to a grid data set. More sophisticated approaches to this problem
3634: exist and should be used to preprocess the data outside `gnuplot` if this
3635: simple solution is found inadequate.
3636:
3637: (The z values are found by weighting all data points, not by interpolating
3638: between nearby data points; also edge effects may produce unexpected and/or
3639: undesired results. In some cases, small norm values produce a grid point
3640: reflecting the average of distant data points rather than a local average,
3641: while large values of norm may produce "steps" with several grid points
3642: having the same value as the closest data point, rather than making a smooth
3643: transition between adjacent data points. Some areas of a grid may be filled
3644: by extrapolation, to an arbitrary boundary condition. The variables are
3645: not normalized; consequently the units used for x and y will affect the
3646: relative weights of points in the x and y directions.)
3647:
3648: Examples:
3649: set dgrid3d 10,10,1 # defaults
3650: set dgrid3d ,,4
3651:
3652: The first specifies that a grid of size 10 by 10 is to be constructed using
3653: a norm value of 1 in the weight computation. The second only modifies the
3654: norm, changing it to 4.
1.1.1.2 maekawa 3655: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/scatter.html"> Dgrid3d Demo.</a>
1.1 maekawa 3656:
3657: 3 dummy
3658: ?commands set dummy
3659: ?commands show dummy
3660: ?set dummy
3661: ?show dummy
3662: ?dummy
3663: The `set dummy` command changes the default dummy variable names.
3664:
3665: Syntax:
3666: set dummy {<dummy-var>} {,<dummy-var>}
3667: show dummy
3668:
3669: By default, `gnuplot` assumes that the independent, or "dummy", variable for
3670: the `plot` command is "t" if in parametric or polar mode, or "x" otherwise.
3671: Similarly the independent variables for the `splot` command are "u" and "v"
3672: in parametric mode (`splot` cannot be used in polar mode), or "x" and "y"
3673: otherwise.
3674:
3675: It may be more convenient to call a dummy variable by a more physically
3676: meaningful or conventional name. For example, when plotting time functions:
3677:
3678: set dummy t
3679: plot sin(t), cos(t)
3680:
3681: At least one dummy variable must be set on the command; `set dummy` by itself
3682: will generate an error message.
3683:
3684: Examples:
3685: set dummy u,v
3686: set dummy ,s
3687:
3688: The second example sets the second variable to s.
3689: 3 encoding
3690: ?commands set encoding
3691: ?commands show encoding
3692: ?set encoding
3693: ?show encoding
3694: ?encoding
3695: The `set encoding` command selects a character encoding. Valid values are
3696: `default`, which tells a terminal to use its default; `iso_8859_1` (known in
3697: the PostScript world as `ISO-Latin1`), which is used on many Unix workstations
3698: and with MS-Windows; `cp850`, for OS/2; and `cp437`, for MS-DOS.
3699:
3700: Syntax:
3701: set encoding {<value>}
3702: show encoding
3703:
3704: Note that encoding is not supported by all terminal drivers and that
3705: the device must be able to produce the desired non-standard characters.
3706: 3 format
3707: ?commands set format
3708: ?commands show format
3709: ?set format
3710: ?show format
3711: ?format
3712: The format of the tic-mark labels can be set with the `set format` command.
3713:
3714: Syntax:
3715: set format {<axes>} {"<format-string>"}
3716: set format {<axes>} {'<format-string>'}
3717: show format
3718:
3719: where <axes> is either `x`, `y`, `z`, `xy`, `x2`, `y2` or nothing (which is
3720: the same as `xy`). The length of the string representing a tic mark (after
3721: formatting with 'printf') is restricted to 100 characters. If the format
3722: string is omitted, the format will be returned to the default "%g". For
3723: LaTeX users, the format "$%g$" is often desirable. If the empty string "" is
3724: used, no label will be plotted with each tic, though the tic mark will still
3725: be plotted. To eliminate all tic marks, use `set noxtics` or `set noytics`.
3726:
3727: Newline (\n) is accepted in the format string. Use double-quotes rather than
3728: single-quotes to enable such interpretation. See also `syntax`.
3729:
3730: The default format for both axes is "%g", but other formats such as "%.2f" or
3731: "%3.0em" are often desirable. Anything accepted by 'printf' when given a
3732: double precision number, and accepted by the terminal, will work. Some other
3733: options have been added. If the format string looks like a floating point
3734: format, then `gnuplot` tries to construct a reasonable format.
3735:
3736: Characters not preceded by "%" are printed verbatim. Thus you can include
3737: spaces and labels in your format string, such as "%g m", which will put " m"
3738: after each number. If you want "%" itself, double it: "%g %%".
3739:
3740: See also `set xtics` for more information about tic labels.
1.1.1.2 maekawa 3741: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/electron.html"> See demo. </a>
1.1 maekawa 3742: 4 format specifiers
3743: ?commands set format specifiers
3744: ?set format specifiers
3745: ?format specifiers
3746: ?format_specifiers
3747: The acceptable formats (if not in time/date mode) are:
3748:
3749: @start table - first is interactive cleartext form
3750: Format Explanation
3751: %f floating point notation
3752: %e or %E exponential notation; an "e" or "E" before the power
3753: %g or %G the shorter of %e (or %E) and %f
3754: %x or %X hex
3755: %o or %O octal
3756: %t mantissa to base 10
3757: %l mantissa to base of current logscale
3758: %s mantissa to base of current logscale; scientific power
3759: %T power to base 10
3760: %L power to base of current logscale
3761: %S scientific power
3762: %c character replacement for scientific power
3763: %P multiple of pi
3764: #\begin{tabular}{|cl|} \hline
3765: #\multicolumn{2}{|c|}{Tic-mark label numerical format specifiers}\\
3766: #\hline \hline
3767: #Format & Explanation \\ \hline
3768: #\verb@%f@ & floating point notation \\
3769: #\verb@%e@ or \verb@%E@ & exponential notation; an "e" or "E" before the power \\
3770: #\verb@%g@ or \verb@%G@ & the shorter of \verb@%e@ (or \verb@%E@) and \verb@%f@ \\
3771: #\verb@%x@ or \verb@%X@ & hex \\
3772: #\verb@%o@ or \verb@%O@ & octal \\
3773: #\verb@%t@ & mantissa to base 10 \\
3774: #\verb@%l@ & mantissa to base of current logscale \\
3775: #\verb@%s@ & mantissa to base of current logscale; scientific power \\
3776: #\verb@%T@ & power to base 10 \\
3777: #\verb@%L@ & power to base of current logscale \\
3778: #\verb@%S@ & scientific power \\
3779: #\verb@%c@ & character replacement for scientific power \\
3780: #\verb@%P@ & multiple of pi \\
3781: %c l .
3782: %Format@Explanation
3783: %_
3784: %%f@floating point notation
3785: %%e or %E@exponential notation; an "e" or "E" before the power
3786: %%g or %G@the shorter of %e (or %E) and %f
3787: %%x or %X@hex
3788: %%o or %O@octal
3789: %%t@mantissa to base 10
3790: %%l@mantissa to base of current logscale
3791: %%s@mantissa to base of current logscale; scientific power
3792: %%T@power to base 10
3793: %%L@power to base of current logscale
3794: %%S@scientific power
3795: %%c@character replacement for scientific power
3796: %%P@multiple of pi
3797: %_
3798: @end table
3799:
3800: A 'scientific' power is one such that the exponent is a multiple of three.
3801: Character replacement of scientific powers (`"%c"`) has been implemented
3802: for powers in the range -18 to +18. For numbers outside of this range the
3803: format reverts to exponential.
3804:
3805: Other acceptable modifiers (which come after the "%" but before the format
3806: specifier) are "-", which left-justifies the number; "+", which forces all
3807: numbers to be explicitly signed; "#", which places a decimal point after
3808: floats that have only zeroes following the decimal point; a positive integer,
3809: which defines the field width; "0" (the digit, not the letter) immediately
3810: preceding the field width, which indicates that leading zeroes are to be used
3811: instead of leading blanks; and a decimal point followed by a non-negative
3812: integer, which defines the precision (the minimum number of digits of an
3813: integer, or the number of digits following the decimal point of a float).
3814:
3815: Some releases of 'printf' may not support all of these modifiers but may also
3816: support others; in case of doubt, check the appropriate documentation and
3817: then experiment.
3818:
3819: Examples:
3820: set format y "%t"; set ytics (5,10) # "5.0" and "1.0"
3821: set format y "%s"; set ytics (500,1000) # "500" and "1.0"
3822: set format y "+-12.3f"; set ytics(12345) # "+12345.000 "
3823: set format y "%.2t*10^%+03T"; set ytic(12345)# "1.23*10^+04"
3824: set format y "%s*10^{%S}"; set ytic(12345) # "12.345*10^{3}"
3825: set format y "%s %cg"; set ytic(12345) # "12.345 kg"
3826: set format y "%.0P pi"; set ytic(6.283185) # "2 pi"
3827: set format y "%.0P%%"; set ytic(50) # "50%"
3828:
3829: set log y 2; set format y '%l'; set ytics (1,2,3)
3830: #displays "1.0", "1.0" and "1.5" (since 3 is 1.5 * 2^1)
3831:
3832: There are some problem cases that arise when numbers like 9.999 are printed
3833: with a format that requires both rounding and a power.
3834:
3835: If the data type for the axis is time/date, the format string must contain
3836: valid codes for the 'strftime' function (outside of `gnuplot`, type "man
3837: strftime"). See `set timefmt` for a list of the allowed input format codes.
3838: 4 time/date specifiers
3839: ?commands set format time/date_specifiers
3840: ?set format time/date_specifiers
3841: ?set time/date_specifiers
3842: ?time/date_specifiers
3843: In time/date mode, the acceptable formats are:
3844:
3845: @start table - first is interactive cleartext form
3846: Format Explanation
3847: %a abbreviated name of day of the week
3848: %A full name of day of the week
3849: %b or %h abbreviated name of the month
3850: %B full name of the month
3851: %d day of the month, 1--31
3852: %D shorthand for "%m/%d/%y"
3853: %H or %k hour, 0--24
3854: %I or %l hour, 0--12
3855: %j day of the year, 1--366
3856: %m month, 1--12
3857: %M minute, 0--60
3858: %p "am" or "pm"
3859: %r shorthand for "%I:%M:%S %p"
1.1.1.3 ! ohara 3860: %R shorthand for "%H:%M"
1.1 maekawa 3861: %S second, 0--60
3862: %T shorthand for "%H:%M:%S"
3863: %U week of the year (week starts on Sunday)
3864: %w day of the week, 0--6 (Sunday = 0)
3865: %W week of the year (week starts on Monday)
3866: %y year, 0-99
3867: %Y year, 4-digit
3868: #\begin{tabular}{|cl|} \hline
3869: #\multicolumn{2}{|c|}{Tic-mark label Date/Time Format Specifiers}\\
3870: #\hline \hline
3871: #Format & Explanation \\ \hline
3872: #\verb@%a@ & abbreviated name of day of the week \\
3873: #\verb@%A@ & full name of day of the week \\
3874: #\verb@%b@ or \verb@%h@ & abbreviated name of the month \\
3875: #\verb@%B@ & full name of the month \\
3876: #\verb@%d@ & day of the month, 1--31 \\
3877: #\verb@%D@ & shorthand for \verb@"%m/%d/%y"@ \\
3878: #\verb@%H@ or \verb@%k@ & hour, 0--24 \\
3879: #\verb@%I@ or \verb@%l@ & hour, 0--12 \\
3880: #\verb@%j@ & day of the year, 1--366 \\
3881: #\verb@%m@ & month, 1--12 \\
3882: #\verb@%M@ & minute, 0--60 \\
3883: #\verb@%p@ & "am" or "pm" \\
3884: #\verb@%r@ & shorthand for \verb@"%I:%M:%S %p"@ \\
3885: #\verb@%R@ & shorthand for \verb@%H:%M"@ \\
3886: #\verb@%S@ & second, 0--60 \\
3887: #\verb@%T@ & shorthand for \verb@"%H:%M:%S"@ \\
3888: #\verb@%U@ & week of the year (week starts on Sunday) \\
3889: #\verb@%w@ & day of the week, 0--6 (Sunday = 0) \\
3890: #\verb@%W@ & week of the year (week starts on Monday) \\
3891: #\verb@%y@ & year, 0-99 \\
3892: #\verb@%Y@ & year, 4-digit \\
3893: %c l .
3894: %Format@Explanation
3895: %_
3896: %%a@abbreviated name of day of the week
3897: %%A@full name of day of the week
3898: %%b or %h@abbreviated name of the month
3899: %%B@full name of the month
3900: %%d@day of the month, 1--31
3901: %%D@shorthand for "%m/%d/%y"
3902: %%H or %k@hour, 0--24
3903: %%I or %l@hour, 0--12
3904: %%j@day of the year, 1--366
3905: %%m@month, 1--12
3906: %%M@minute, 0--60
3907: %%p@"am" or "pm"
3908: %%r@shorthand for "%I:%M:%S %p"
3909: %%R@shorthand for %H:%M"
3910: %%S@second, 0--60
3911: %%T@shorthand for "%H:%M:%S"
3912: %%U@week of the year (week starts on Sunday)
3913: %%w@day of the week, 0--6 (Sunday = 0)
3914: %%W@week of the year (week starts on Monday)
3915: %%y@year, 0-99
3916: %%Y@year, 4-digit
3917: %_
3918: @end table
3919:
3920: Except for the non-numerical formats, these may be preceded by a "0" ("zero",
3921: not "oh") to pad the field length with leading zeroes, and a positive digit,
3922: to define the minimum field width (which will be overridden if the specified
3923: width is not large enough to contain the number). There is a 24-character
3924: limit to the length of the printed text; longer strings will be truncated.
3925:
3926: Examples:
3927:
3928: Suppose the text is "76/12/25 23:11:11". Then
3929: set format x # defaults to "12/25/76" \n "23:11"
3930: set format x "%A, %d %b %Y" # "Saturday, 25 Dec 1976"
3931: set format x "%r %d" # "11:11:11 pm 12/25/76"
3932:
3933: Suppose the text is "98/07/06 05:04:03". Then
3934: set format x "%1y/%2m/%3d %01H:%02M:%03S" # "98/ 7/ 6 5:04:003"
3935: 3 function style
3936: ?commands set function style
3937: ?commands show function style
3938: ?set function style
3939: ?show function style
3940: ?function style
3941: The `set function style` command changes the default plotting style for
3942: function plots.
3943:
3944: Syntax:
3945: set function style <style-choice>
3946: show function style
3947:
3948: See `set style` for the choices. If no choice is given, the choices are
3949: listed. `show function style` shows the current default function plotting
3950: style.
3951: 3 functions
3952: ?commands show functions
3953: ?show functions
3954: The `show functions` command lists all user-defined functions and their
3955: definitions.
3956:
3957: Syntax:
3958: show functions
3959:
3960: For information about the definition and usage of functions in `gnuplot`,
3961: please see `expressions`.
1.1.1.2 maekawa 3962: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/spline.html"> Splines as User Defined Functions.</a>
3963: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html">Use of functions and complex variables for airfoils </a>
1.1 maekawa 3964: 3 grid
3965: ?commands set grid
3966: ?commands set nogrid
3967: ?commands show grid
3968: ?set grid
3969: ?set nogrid
3970: ?show grid
3971: ?grid
3972: ?nogrid
3973: The `set grid` command allows grid lines to be drawn on the plot.
3974:
3975: Syntax:
3976: set grid {{no}{m}xtics} {{no}{m}ytics} {{no}{m}ztics}
3977: {{no}{m}x2tics} {{no}{m}y2tics}
3978: {polar {<angle>}}
3979: { {linestyle <major_linestyle>}
3980: | {linetype | lt <major_linetype>}
3981: {linewidth | lw <major_linewidth>}
3982: { , {linestyle | ls <minor_linestyle>}
3983: | {linetype | lt <minor_linetype>}
3984: {linewidth | lw <minor_linewidth>} } }
3985: set nogrid
3986: show grid
3987:
3988: The grid can be enabled and disabled for the major and/or minor tic
3989: marks on any axis, and the linetype and linewidth can be specified
3990: for major and minor grid lines, also via a predefined linestyle, as
3991: far as the active terminal driver supports this.
3992:
3993: Additionally, a polar grid can be selected for 2-d plots---circles are drawn
3994: to intersect the selected tics, and radial lines are drawn at definable
3995: intervals. (The interval is given in degrees or radians ,depending on the
3996: `set angles` setting.) Note that a polar grid is no longer automatically
3997: generated in polar mode.
3998:
3999: The pertinent tics must be enabled before `set grid` can draw them; `gnuplot`
4000: will quietly ignore instructions to draw grid lines at non-existent tics, but
4001: they will appear if the tics are subsequently enabled.
4002:
4003: If no linetype is specified for the minor gridlines, the same linetype as the
4004: major gridlines is used. The default polar angle is 30 degrees.
4005:
1.1.1.2 maekawa 4006: By default, grid lines are drawn with half the usual linewidth. The major and
4007: minor linewidth specifiers scale this default value; for example, `set grid
4008: lw .5` will draw grid lines with one quarter the usual linewidth.
4009:
1.1 maekawa 4010: Z grid lines are drawn on the back of the plot. This looks better if a
4011: partial box is drawn around the plot---see `set border`.
4012: 3 hidden3d
4013: ?commands set hidden3d
4014: ?commands set nohidden3d
4015: ?commands show hidden3d
4016: ?set hidden3d
4017: ?set nohidden3d
4018: ?show hidden3d
4019: ?hidden3d
4020: ?nohidden3d
4021: The `set hidden3d` command enables hidden line removal for surface plotting
4022: (see `splot`). Some optional features of the underlying algorithm can also
4023: be controlled using this command.
4024:
4025: Syntax:
4026: set hidden3d {defaults} |
4027: { {{offset <offset>} | {nooffset}}
4028: {trianglepattern <bitpattern>}
4029: {{undefined <level>} | {noundefined}}
4030: {{no}altdiagonal}
4031: {{no}bentover} }
4032: set nohidden3d
4033: show hidden3d
4034:
4035: In contrast to the usual display in gnuplot, hidden line removal actually
4036: treats the given function or data grids as real surfaces that can't be seen
4037: through, so parts behind the surface will be hidden by it. For this to be
4038: possible, the surface needs to have 'grid structure' (see `splot datafile`
4039: about this), and it has to be drawn `with lines` or `with linespoints`.
4040:
4041: When `hidden3d` is set, both the hidden portion of the surface and possibly
4042: its contours drawn on the base (see `set contour`) as well as the grid will
4043: be hidden. Each surface has its hidden parts removed with respect to itself
4044: and to other surfaces, if more than one surface is plotted. Contours drawn
4045: on the surface (`set contour surface`) don't work. Labels and arrows are
4046: always visible and are unaffected. The key is also never hidden by the
4047: surface.
4048:
4049: Functions are evaluated at isoline intersections. The algorithm interpolates
4050: linearly between function points or data points when determining the visible
4051: line segments. This means that the appearance of a function may be different
4052: when plotted with `hidden3d` than when plotted with `nohidden3d` because in
4053: the latter case functions are evaluated at each sample. Please see `set
4054: samples` and `set isosamples` for discussion of the difference.
4055:
4056: The algorithm used to remove the hidden parts of the surfaces has some
4057: additional features controllable by this command. Specifying `defaults` will
4058: set them all to their default settings, as detailed below. If `defaults` is
4059: not given, only explicitly specified options will be influenced: all others
4060: will keep their previous values, so you can turn on/off hidden line removal
4061: via `set {no}hidden3d`, without modifying the set of options you chose.
4062:
4063: The first option, `offset`, influences the linestyle used for lines on the
4064: 'back' side. Normally, they are drawn in a linestyle one index number higher
4065: than the one used for the front, to make the two sides of the surface
4066: distinguishable. You can specify a different line style offset to add
4067: instead of the default 1, by `offset <offset>`. Option `nooffset` stands for
4068: `offset 0`, making the two sides of the surface use the same linestyle.
4069:
4070: Next comes the option `trianglepattern <bitpattern>`. <bitpattern> must be
4071: a number between 0 and 7, interpreted as a bit pattern. Each bit determines
4072: the visibility of one edge of the triangles each surface is split up into.
4073: Bit 0 is for the 'horizontal' edges of the grid, Bit 1 for the 'vertical'
4074: ones, and Bit 2 for the diagonals that split each cell of the original grid
4075: into two triangles. The default pattern is 3, making all horizontal and
4076: vertical lines visible, but not the diagonals. You may want to choose 7 to
4077: see those diagonals as well.
4078:
4079: The `undefined <level>` option lets you decide what the algorithm is to do
4080: with data points that are undefined (missing data, or undefined function
4081: values), or exceed the given x-, y- or z-ranges. Such points can either be
4082: plotted nevertheless, or taken out of the input data set. All surface
4083: elements touching a point that is taken out will be taken out as well, thus
4084: creating a hole in the surface. If <level> = 3, equivalent to option
4085: `noundefined`, no points will be thrown away at all. This may produce all
4086: kinds of problems elsewhere, so you should avoid this. <level> = 2 will
4087: throw away undefined points, but keep the out-of-range ones. <level> = 1,
4088: the default, will get rid of out-of-range points as well.
4089:
4090: By specifying `noaltdiagonal`, you can override the default handling of a
4091: special case can occur if `undefined` is active (i.e. <level> is not 3).
4092: Each cell of the grid-structured input surface will be divided in two
4093: triangles along one of its diagonals. Normally, all these diagonals have
4094: the same orientation relative to the grid. If exactly one of the four cell
4095: corners is excluded by the `undefined` handler, and this is on the usual
4096: diagonal, both triangles will be excluded. However if the default setting
4097: of `altdiagonal` is active, the other diagonal will be chosen for this cell
4098: instead, minimizing the size of the hole in the surface.
4099:
4100: The `bentover` option controls what happens to another special case, this
4101: time in conjunction with the `trianglepattern`. For rather crumply surfaces,
4102: it can happen that the two triangles a surface cell is divided into are seen
4103: from opposite sides (i.e. the original quadrangle is 'bent over'), as
4104: illustrated in the following ASCII art:
4105:
4106: C----B
4107: original quadrangle: A--B displayed quadrangle: |\ |
4108: ("set view 0,0") | /| ("set view 75,75" perhaps) | \ |
4109: |/ | | \ |
4110: C--D | \|
4111: A D
4112:
4113: If the diagonal edges of the surface cells aren't generally made visible by
4114: bit 2 of the <bitpattern> there, the edge CB above wouldn't be drawn at all,
4115: normally, making the resulting display hard to understand. Therefore, the
4116: default option of `bentover` will turn it visible in this case. If you don't
4117: want that, you may choose `nobentover` instead.
1.1.1.2 maekawa 4118: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/hidden.html"> Hidden Line Removal Demo</a> and
4119: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/singulr.html"> Complex Hidden Line Demo. </a>
1.1 maekawa 4120: 3 isosamples
4121: ?commands set isosamples
4122: ?commands show isosamples
4123: ?set isosamples
4124: ?show isosamples
4125: ?isosamples
4126: The isoline density (grid) for plotting functions as surfaces may be changed
4127: by the `set isosamples` command.
4128:
4129: Syntax:
4130: set isosamples <iso_1> {,<iso_2>}
4131: show isosamples
4132:
4133: Each function surface plot will have <iso_1> iso-u lines and <iso_2> iso-v
4134: lines. If you only specify <iso_1>, <iso_2> will be set to the same value
4135: as <iso_1>. By default, sampling is set to 10 isolines per u or v axis.
4136: A higher sampling rate will produce more accurate plots, but will take longer.
4137: These parameters have no effect on data file plotting.
4138:
4139: An isoline is a curve parameterized by one of the surface parameters while
4140: the other surface parameter is fixed. Isolines provide a simple means to
4141: display a surface. By fixing the u parameter of surface s(u,v), the iso-u
4142: lines of the form c(v) = s(u0,v) are produced, and by fixing the v parameter,
4143: the iso-v lines of the form c(u) = s(u,v0) are produced.
4144:
4145: When a function surface plot is being done without the removal of hidden
4146: lines, `set samples` controls the number of points sampled along each
4147: isoline; see `set samples` and `set hidden3d`. The contour algorithm
4148: assumes that a function sample occurs at each isoline intersection, so
4149: change in `samples` as well as `isosamples` may be desired when changing
4150: the resolution of a function surface/contour.
4151: 3 key
4152: ?commands set key
4153: ?commands set nokey
4154: ?commands show key
4155: ?set key
4156: ?set nokey
4157: ?show key
4158: ?key
4159: ?nokey
4160: ?legend
4161: The `set key` enables a key (or legend) describing plots on a plot.
4162:
4163: The contents of the key, i.e., the names given to each plotted data set and
4164: function and samples of the lines and/or symbols used to represent them, are
4165: determined by the `title` and `with` options of the {`s`}`plot` command.
4166: Please see `plot title` and `plot with` for more information.
4167:
4168: Syntax:
4169: set key { left | right | top | bottom | outside | below
4170: | <position>}
4171: {Left | Right} {{no}reverse}
4172: {samplen <sample_length>} {spacing <vertical_spacing>}
4173: {width <width_increment>}
4174: {title "<text>"}
4175: {{no}box { {linestyle | ls <line_style>}
4176: | {linetype | lt <line_type>}
4177: {linewidth | lw <line_width>}}}
4178: set nokey
4179: show key
4180:
4181: By default the key is placed in the upper right corner of the graph. The
4182: keywords `left`, `right`, `top`, `bottom`, `outside` and `below` may be used
4183: to place the key in the other corners inside the graph or to the right
4184: (outside) or below the graph. They may be given alone or combined.
4185:
4186: Justification of the labels within the key is controlled by `Left` or `Right`
4187: (default is `Right`). The text and sample can be reversed (`reverse`) and a
4188: box can be drawn around the key (`box {...}`) in a specified `linetype`
4189: and `linewidth`, or a user-defined `linestyle`. Note that not all
4190: terminal drivers support linewidth selection, though.
4191:
4192: The length of the sample line can be controlled by `samplen`. The sample
4193: length is computed as the sum of the tic length and <sample_length> times the
4194: character width. `samplen` also affects the positions of point samples in
4195: the key since these are drawn at the midpoint of the sample line, even if it
4196: is not drawn. <sample_length> must be an integer.
4197:
4198: The vertical spacing between lines is controlled by `spacing`. The spacing
4199: is set equal to the product of the pointsize, the vertical tic size, and
4200: <vertical_spacing>. The program will guarantee that the vertical spacing is
4201: no smaller than the character height.
4202:
4203: The <width_increment> is a number of character widths to be added to or
4204: subtracted from the length of the string. This is useful only when you are
4205: putting a box around the key and you are using control characters in the text.
4206: `gnuplot` simply counts the number of characters in the string when computing
4207: the box width; this allows you to correct it.
4208:
4209: A title can be put on the key (`title "<text>"`)---see also `syntax` for the
4210: distinction between text in single- or double-quotes. The key title uses the
4211: same justification as do the plot titles.
4212:
4213: The defaults for `set key` are `right`, `top`, `Right`, `noreverse`, `samplen
4214: 4`, `spacing 1.25`, `title ""`, and `nobox`. The default <linetype> is the
4215: same as that used for the plot borders. Entering `set key` with no options
4216: returns the key to its default configuration.
4217:
4218: The <position> can be a simple x,y,z as in previous versions, but these can
4219: be preceded by one of four keywords (`first`, `second`, `graph`, `screen`)
4220: which selects the coordinate system in which the position is specified. See
4221: `coordinates` for more details.
4222:
4223: The key is drawn as a sequence of lines, with one plot described on each
4224: line. On the right-hand side (or the left-hand side, if `reverse` is
4225: selected) of each line is a representation that attempts to mimic the way the
4226: curve is plotted. On the other side of each line is the text description
4227: (the line title), obtained from the `plot` command. The lines are vertically
4228: arranged so that an imaginary straight line divides the left- and right-hand
4229: sides of the key. It is the coordinates of the top of this line that are
4230: specified with the `set key` command. In a `plot`, only the x and y
4231: coordinates are used to specify the line position. For a `splot`, x, y and
4232: z are all used as a 3-d location mapped using the same mapping as the graph
4233: itself to form the required 2-d screen position of the imaginary line.
4234:
4235: Some or all of the key may be outside of the graph boundary, although this
4236: may interfere with other labels and may cause an error on some devices. If
4237: you use the keywords `outside` or `below`, `gnuplot` makes space for the keys
4238: and the graph becomes smaller. Putting keys outside to the right, they
4239: occupy as few columns as possible, and putting them below, as many columns as
4240: possible (depending of the length of the labels), thus stealing as little
4241: space from the graph as possible.
4242:
4243: When using the TeX or PostScript drivers, or similar drivers where formatting
4244: information is embedded in the string, `gnuplot` is unable to calculate
4245: correctly the width of the string for key positioning. If the key is to be
4246: positioned at the left, it may be convenient to use the combination `set key
4247: left Left reverse`. The box and gap in the grid will be the width of the
4248: literal string.
4249:
4250: If `splot` is being used to draw contours, the contour labels will be listed
4251: in the key. If the alignment of these labels is poor or a different number
4252: of decimal places is desired, the label format can be specified. See `set
4253: clabel` for details.
4254:
4255: Examples:
4256:
4257: This places the key at the default location:
4258: set key
4259:
4260: This disables the key:
4261: set nokey
4262:
4263: This places a key at coordinates 2,3.5,2 in the default (first) coordinate
4264: system:
4265: set key 2,3.5,2
4266:
4267: This places the key below the graph:
4268: set key below
4269:
4270: This places the key in the bottom left corner, left-justifies the text,
4271: gives it a title, and draws a box around it in linetype 3:
4272: set key left bottom Left title 'Legend' box 3
4273: 3 label
4274: ?commands set label
4275: ?commands set nolabel
4276: ?commands show label
4277: ?set label
4278: ?set nolabel
4279: ?show label
4280: ?label
4281: ?nolabel
4282: Arbitrary labels can be placed on the plot using the `set label` command.
4283:
4284: Syntax:
4285: set label {<tag>} {"<label_text>"} {at <position>}
4286: {<justification>} {{no}rotate} {font "<name><,size>"}
4287: set nolabel {<tag>}
4288: show label
4289:
4290: The <position> is specified by either x,y or x,y,z, and may be preceded by
4291: `first`, `second`, `graph`, or `screen` to select the coordinate system.
4292: See `coordinates` for details.
4293:
4294: The tag is an integer that is used to identify the label. If no <tag> is
4295: given, the lowest unused tag value is assigned automatically. The tag can be
4296: used to delete or modify a specific label. To change any attribute of an
4297: existing label, use the `set label` command with the appropriate tag, and
4298: specify the parts of the label to be changed.
4299:
4300: By default, the text is placed flush left against the point x,y,z. To adjust
4301: the way the label is positioned with respect to the point x,y,z, add the
4302: parameter <justification>, which may be `left`, `right` or `center`,
4303: indicating that the point is to be at the left, right or center of the text.
4304: Labels outside the plotted boundaries are permitted but may interfere with
4305: axis labels or other text.
4306:
4307: If `rotate` is given, the label is written vertically (if the terminal can do
4308: so, of course).
4309:
4310: If one (or more) axis is timeseries, the appropriate coordinate should be
4311: given as a quoted time string according to the `timefmt` format string. See
4312: `set xdata` and `set timefmt`.
4313:
4314: The EEPIC, Imagen, LaTeX, and TPIC drivers allow \\ in a string to specify
4315: a newline.
4316:
4317: Examples:
4318:
4319: To set a label at (1,2) to "y=x", use:
4320: set label "y=x" at 1,2
4321:
4322: To set a Sigma of size 24, from the Symbol font set, at the center of
4323: the graph, use:
4324: set label "S" at graph 0.5,0.5 center font "Symbol,24"
4325:
4326: To set a label "y=x^2" with the right of the text at (2,3,4), and tag the
4327: label as number 3, use:
4328: set label 3 "y=x^2" at 2,3,4 right
4329:
4330: To change the preceding label to center justification, use:
4331: set label 3 center
4332:
4333: To delete label number 2, use:
4334: set nolabel 2
4335:
4336: To delete all labels, use:
4337: set nolabel
4338:
4339: To show all labels (in tag order), use:
4340: show label
4341:
4342: To set a label on a graph with a timeseries on the x axis, use, for example:
4343: set timefmt "%d/%m/%y,%H:%M"
4344: set label "Harvest" at "25/8/93",1
4345: 3 linestyle
4346: ?commands set linestyle
4347: ?commands set nolinestyle
4348: ?commands show linestyle
4349: ?set linestyle
4350: ?set nolinestyle
4351: ?show linestyle
4352: ?linestyle
4353: Each terminal has a default set of line and point types, which can be seen
4354: by using the command `test`. `set linestyle` defines a set of line types
4355: and widths and point types and sizes so that you can refer to them later by
4356: an index instead of repeating all the information at each invocation.
4357:
4358: Syntax:
4359: set linestyle <index> {linetype | lt <line_type>}
4360: {linewidth | lw <line_width>}
4361: {pointtype | pt <point_type>}
4362: {pointsize | ps <point_size>}
4363: set nolinestyle
4364: show linestyle
4365:
4366: The line and point types are taken from the default types for the terminal
4367: currently in use. The line width and point size are multipliers for the
4368: default width and size (but note that <point_size> here is unaffected by
4369: the multiplier given on 'set pointsize').
4370:
4371: The defaults for the line and point types is the index. The defaults for
4372: the width and size are both unity.
4373:
4374: Linestyles created by this mechanism do not replace the default styles;
4375: both may be used.
4376:
4377: Not all terminals support the `linewidth` and `pointsize` features; if
4378: not supported, the option will be ignored.
4379:
4380: Note that this feature is not completely implemented; linestyles defined by
4381: this mechanism may be used with 'plot', 'splot', 'replot', and 'set arrow',
4382: but not by other commands that allow the default index to be used, such as
4383: 'set grid'.
4384:
4385: Example:
4386: Suppose that the default lines for indices 1, 2, and 3 are red, green, and
4387: blue, respectively, and the default point shapes for the same indices are a
4388: square, a cross, and a triangle, respectively. Then
4389:
4390: set linestyle 1 lt 2 lw 2 pt 3 ps 0.5
4391:
4392: defines a new linestyle that is green and twice the default width and a new
4393: pointstyle that is a half-sized triangle. The commands
4394:
4395: set function style lines
4396: plot f(x) lt 3, g(x) ls 1
4397:
4398: will create a plot of f(x) using the default blue line and a plot of g(x)
4399: using the user-defined wide green line. Similarly the commands
4400:
4401: set function style linespoints
4402: plot p(x) lt 1 pt 3, q(x) ls 1
4403:
4404: will create a plot of f(x) using the default triangles connected by a red
4405: line and q(x) using small triangles connected by a green line.
4406: 3 lmargin
4407: ?commands set lmargin
4408: ?set lmargin
4409: ?lmargin
4410: The command `set lmargin` sets the size of the left margin. Please see
4411: `set margin` for details.
4412: 3 locale
4413: ?commands set locale
4414: ?commands show logscale
4415: ?set locale
4416: ?show logscale
4417: ?locale
4418: The `locale` setting determines the language with which `{x,y,z}{d,m}tics`
4419: will write the days and months.
4420:
4421: Syntax:
4422: set locale {"<locale>"}
4423:
4424: <locale> may be any language designation acceptable to your installation.
4425: See your system documentation for the available options. The default value
4426: is determined from the LANG environment variable.
4427: 3 logscale
4428: ?commands set logscale
4429: ?commands set nologscale
4430: ?commands show logscale
4431: ?set logscale
4432: ?set nologscale
4433: ?show logscale
4434: ?logscale
4435: ?nologscale
4436: Log scaling may be set on the x, y, z, x2 and/or y2 axes.
4437:
4438: Syntax:
4439: set logscale <axes> <base>
4440: set nologscale <axes>
4441: show logscale
4442:
4443: where <axes> may be any combinations of `x`, `y`, and `z`, in any order, or
4444: `x2` or `y2` and where <base> is the base of the log scaling. If <base> is
4445: not given, then 10 is assumed. If <axes> is not given, then all axes are
4446: assumed. `set nologscale` turns off log scaling for the specified axes.
4447:
4448: Examples:
4449:
4450: To enable log scaling in both x and z axes:
4451: set logscale xz
4452:
4453: To enable scaling log base 2 of the y axis:
4454: set logscale y 2
4455:
4456: To disable z axis log scaling:
4457: set nologscale z
4458: 3 mapping
4459: ?commands set mapping
4460: ?commands show mapping
4461: ?set mapping
4462: ?show mapping
4463: ?mapping
4464: If data are provided to `splot` in spherical or cylindrical coordinates,
4465: the `set mapping` command should be used to instruct `gnuplot` how to
4466: interpret them.
4467:
4468: Syntax:
4469: set mapping {cartesian | spherical | cylindrical}
4470:
4471: A cartesian coordinate system is used by default.
4472:
4473: For a spherical coordinate system, the data occupy two or three columns (or
1.1.1.3 ! ohara 4474: `using` entries). The first two are interpreted as the azimuthal and polar
1.1 maekawa 4475: angles theta and phi (in the units specified by `set angles`). The radius r
4476: is taken from the third column if there is one, or is set to unity if there
4477: is no third column. The mapping is:
4478:
4479: x = r * cos(theta) * cos(phi)
4480: y = r * sin(theta) * cos(phi)
4481: z = r * sin(phi)
4482:
4483: Note that this is a "geographic" spherical system, rather than a "polar" one.
4484:
4485: For a cylindrical coordinate system, the data again occupy two or three
4486: columns. The first two are interpreted as theta (in the units specified by
4487: `set angles`) and z. The radius is either taken from the third column or set
4488: to unity, as in the spherical case. The mapping is:
4489:
4490: x = r * cos(theta)
4491: y = r * sin(theta)
4492: z = z
4493:
4494: The effects of `mapping` can be duplicated with the `using` filter on the
4495: `splot` command, but `mapping` may be more convenient if many data files are
4496: to be processed. However even if `mapping` is used, `using` may still be
4497: necessary if the data in the file are not in the required order.
4498:
4499: `mapping` has no effect on `plot`.
1.1.1.2 maekawa 4500: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/world.html">Mapping Demos.</a>
1.1 maekawa 4501: 3 margin
4502: ?commands set margin
4503: ?commands show margin
4504: ?set margin
4505: ?show margin
4506: ?margin
1.1.1.2 maekawa 4507: The computed margins can be overridden by the `set margin` commands. `show
4508: margin` shows the current settings.
1.1 maekawa 4509:
4510: Syntax:
4511: set bmargin {<margin>}
4512: set lmargin {<margin>}
4513: set rmargin {<margin>}
4514: set tmargin {<margin>}
4515: show margin
4516:
4517: The units of <margin> are character heights or widths, as appropriate. A
4518: positive value defines the absolute size of the margin. A negative value
4519: (or none) causes `gnuplot` to revert to the computed value.
1.1.1.2 maekawa 4520:
4521: Normally the margins of a plot are automatically calculated based on tics,
4522: tic labels, axis labels, the plot title, the timestamp and the size of the
4523: key if it is outside the borders. If, however, tics are attached to the
4524: axes (`set xtics axis`, for example), neither the tics themselves nor their
4525: labels will be included in either the margin calculation or the calculation
4526: of the positions of other text to be written in the margin. This can lead
4527: to tic labels overwriting other text if the axis is very close to the border.
1.1 maekawa 4528: 3 missing
4529: ?commands set missing
4530: ?set missing
4531: ?missing
4532: The `set missing` command allows you to tell `gnuplot` what character is
4533: used in a data file to denote missing data.
4534:
4535: Syntax:
4536: set missing {"<character>"}
4537: show missing
4538:
4539: Example:
4540: set missing "?"
4541:
4542: would mean that, when plotting a file containing
4543:
4544: 1 1
4545: 2 ?
4546: 3 2
4547:
4548: the middle line would be ignored.
4549:
4550: There is no default character for `missing`.
4551: 3 multiplot
4552: ?commands set multiplot
4553: ?commands set nomultiplot
4554: ?set multiplot
4555: ?set nomultiplot
4556: ?multiplot
4557: ?nomultiplot
4558: The command `set multiplot` places `gnuplot` in the multiplot mode, in which
4559: several plots are placed on the same page, window, or screen.
4560:
4561: Syntax:
4562: set multiplot
4563: set nomultiplot
4564:
4565: For some terminals, no plot is displayed until the command `set nomultiplot`
4566: is given, which causes the entire page to be drawn and then returns `gnuplot`
4567: to its normal single-plot mode. For other terminals, each separate `plot`
4568: command produces a plot, but the screen may not be cleared between plots.
4569:
4570: Any labels or arrows that have been defined will be drawn for each plot
4571: according to the current size and origin (unless their coordinates are
4572: defined in the `screen` system). Just about everything else that can be
4573: `set` is applied to each plot, too. If you want something to appear only
4574: once on the page, for instance a single time stamp, you'll need to put a `set
4575: time`/`set notime` pair around one of the `plot`, `splot` or `replot`
4576: commands within the `set multiplot`/`set nomultiplot` block.
4577:
4578: The commands `set origin` and `set size` must be used to correctly position
4579: each plot; see `set origin` and `set size` for details of their usage.
4580:
4581: Example:
4582: set size 0.7,0.7
4583: set origin 0.1,0.1
4584: set multiplot
4585: set size 0.4,0.4
4586: set origin 0.1,0.1
4587: plot sin(x)
4588: set size 0.2,0.2
4589: set origin 0.5,0.5
4590: plot cos(x)
4591: set nomultiplot
4592:
4593: displays a plot of cos(x) stacked above a plot of sin(x). Note the initial
4594: `set size` and `set origin`. While these are not always required, their
4595: inclusion is recommended. Some terminal drivers require that bounding box
4596: information be available before any plots can be made, and the form given
4597: above guarantees that the bounding box will include the entire plot array
4598: rather than just the bounding box of the first plot.
4599:
4600: `set size` and `set origin` refer to the entire plotting area used for each
4601: plot. If you want to have the axes themselves line up, you can guarantee
4602: that the margins are the same size with the `set margin` commands. See
4603: `set margin` for their use. Note that the margin settings are absolute,
4604: in character units, so the appearance of the graph in the remaining space
4605: will depend on the screen size of the display device, e.g., perhaps quite
4606: different on a video display and a printer.
1.1.1.2 maekawa 4607: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/multiplt.html"> See demo. </a>
1.1 maekawa 4608: 3 mx2tics
4609: ?commands set mx2tics
4610: ?commands set nomx2tics
4611: ?commands show mx2tics
4612: ?set mx2tics
4613: ?set nomx2tics
4614: ?show mx2tics
4615: ?mx2tics
4616: ?nomx2tics
4617: Minor tic marks along the x2 (top) axis are controlled by `set mx2tics`.
4618: Please see `set mxtics`.
4619: 3 mxtics
4620: ?commands set mxtics
4621: ?commands set nomxtics
4622: ?commands show mxtics
4623: ?set mxtics
4624: ?set nomxtics
4625: ?show mxtics
4626: ?mxtics
4627: ?nomxtics
4628: Minor tic marks along the x axis are controlled by `set mxtics`. They can be
4629: turned off with `set nomxtics`. Similar commands control minor tics along
4630: the other axes.
4631:
4632: Syntax:
4633: set mxtics {<freq> | default}
4634: set nomxtics
4635: show mxtics
4636:
4637: The same syntax applies to `mytics`, `mztics`, `mx2tics` and `my2tics`.
4638:
4639: <freq> is the number of sub-intervals (NOT the number of minor tics) between
4640: major tics (ten is the default for a linear axis, so there are nine minor
4641: tics between major tics). Selecting `default` will return the number of minor
4642: ticks to its default value.
4643:
4644: If the axis is logarithmic, the number of sub-intervals will be set to a
4645: reasonable number by default (based upon the length of a decade). This will
4646: be overridden if <freq> is given. However the usual minor tics (2, 3, ...,
4647: 8, 9 between 1 and 10, for example) are obtained by setting <freq> to 10,
4648: even though there are but nine sub-intervals.
4649:
4650: Minor tics can be used only with uniformly spaced major tics. Since major
4651: tics can be placed arbitrarily by `set {x|x2|y|y2|z}tics`, minor tics cannot
4652: be used if major tics are explicitly `set`.
4653:
4654: By default, minor tics are off for linear axes and on for logarithmic axes.
4655: They inherit the settings for `axis|border` and `{no}mirror` specified for
4656: the major tics. Please see `set xtics` for information about these.
4657: 3 my2tics
4658: ?commands set my2tics
4659: ?commands set nomy2tics
4660: ?commands show my2tics
4661: ?set my2tics
4662: ?set nomy2tics
4663: ?show my2tics
4664: ?my2tics
4665: ?nomy2tics
4666: Minor tic marks along the y2 (right-hand) axis are controlled by `set
4667: my2tics`. Please see `set mxtics`.
4668: 3 mytics
4669: ?commands set mytics
4670: ?commands set nomytics
4671: ?commands show mytics
4672: ?set mytics
4673: ?set nomytics
4674: ?show mytics
4675: ?mytics
4676: ?nomytics
4677: Minor tic marks along the y axis are controlled by `set mytics`. Please
4678: see `set mxtics`.
4679: 3 mztics
4680: ?commands set mztics
4681: ?commands set nomztics
4682: ?commands show mztics
4683: ?set mztics
4684: ?set nomztics
4685: ?show mztics
4686: ?mztics
4687: ?nomztics
4688: Minor tic marks along the z axis are controlled by `set mztics`. Please
4689: see `set mxtics`.
4690: 3 offsets
4691: ?commands set offsets
4692: ?commands set nooffsets
4693: ?commands show offsets
4694: ?set offsets
4695: ?set nooffsets
4696: ?show offsets
4697: ?offsets
4698: ?nooffsets
4699: Offsets provide a mechanism to put a boundary around the data inside of an
4700: autoscaled graph.
4701:
4702: Syntax:
4703: set offsets <left>, <right>, <top>, <bottom>
4704: set nooffsets
4705: show offsets
4706:
4707: Each offset may be a constant or an expression. Each defaults to 0. Left
4708: and right offsets are given in units of the x axis, top and bottom offsets in
4709: units of the y axis. A positive offset expands the graph in the specified
4710: direction, e.g., a positive bottom offset makes ymin more negative. Negative
4711: offsets, while permitted, can have unexpected interactions with autoscaling
4712: and clipping.
4713:
4714: Offsets are ignored in `splot`s.
4715:
4716: Example:
4717: set offsets 0, 0, 2, 2
4718: plot sin(x)
4719:
4720: This graph of sin(x) will have a y range [-3:3] because the function
4721: will be autoscaled to [-1:1] and the vertical offsets are each two.
4722: 3 origin
4723: ?commands set origin
4724: ?commands show origin
4725: ?set origin
4726: ?show origin
4727: ?origin
4728: The `set origin` command is used to specify the origin of a plotting surface
4729: (i.e., the graph and its margins) on the screen. The coordinates are given
4730: in the `screen` coordinate system (see `coordinates` for information about
4731: this system).
4732:
4733: Syntax:
4734: set origin <x-origin>,<y-origin>
4735: 3 output
4736: ?commands set output
4737: ?commands show output
4738: ?set output
4739: ?show output
4740: ?output
4741: By default, screens are displayed to the standard output. The `set output`
4742: command redirects the display to the specified file or device.
4743:
4744: Syntax:
4745: set output {"<filename>"}
4746: show output
4747:
4748: The filename must be enclosed in quotes. If the filename is omitted, any
4749: output file opened by a previous invocation of `set output` will be closed
4750: and new output will be sent to STDOUT. (If you give the command `set output
4751: "STDOUT"`, your output may be sent to a file named "STDOUT"! ["May be", not
4752: "will be", because some terminals, like `x11`, ignore `set output`.])
4753:
4754: MSDOS users should note that the \ character has special significance in
4755: double-quoted strings, so single-quotes should be used for filenames in
4756: different directories.
4757:
4758: When both `set terminal` and `set output` are used together, it is safest to
4759: give `set terminal` first, because some terminals set a flag which is needed
4760: in some operating systems. This would be the case, for example, if the
4761: operating system needs to know whether or not a file is to be formatted in
4762: order to open it properly.
4763:
4764: On machines with popen functions (Unix), output can be piped through a shell
4765: command if the first non-whitespace character of the filename is '|'.
4766: For instance,
4767:
4768: set output "|lpr -Plaser filename"
4769: set output "|lp -dlaser filename"
4770:
4771: On MSDOS machines, `set output "PRN"` will direct the output to the default
4772: printer. On VMS, output can be sent directly to any spooled device. It is
4773: also possible to send the output to DECnet transparent tasks, which allows
4774: some flexibility.
4775: 3 parametric
4776: ?commands set parametric
4777: ?commands set noparametric
4778: ?commands show parametric
4779: ?set parametric
4780: ?set noparametric
4781: ?show parametric
4782: ?parametric
4783: ?noparametric
4784: The `set parametric` command changes the meaning of `plot` (`splot`) from
4785: normal functions to parametric functions. The command `set noparametric`
4786: restores the plotting style to normal, single-valued expression plotting.
4787:
4788: Syntax:
4789: set parametric
4790: set noparametric
4791: show parametric
4792:
4793: For 2-d plotting, a parametric function is determined by a pair of parametric
4794: functions operating on a parameter. An example of a 2-d parametric function
4795: would be `plot sin(t),cos(t)`, which draws a circle (if the aspect ratio is
4796: set correctly---see `set size`). `gnuplot` will display an error message if
4797: both functions are not provided for a parametric `plot`.
4798:
4799: For 3-d plotting, the surface is described as x=f(u,v), y=g(u,v), z=h(u,v).
4800: Therefore a triplet of functions is required. An example of a 3-d parametric
4801: function would be `cos(u)*cos(v),cos(u)*sin(v),sin(u)`, which draws a sphere.
4802: `gnuplot` will display an error message if all three functions are not
4803: provided for a parametric `splot`.
4804:
4805: The total set of possible plots is a superset of the simple f(x) style plots,
4806: since the two functions can describe the x and y values to be computed
4807: separately. In fact, plots of the type t,f(t) are equivalent to those
4808: produced with f(x) because the x values are computed using the identity
4809: function. Similarly, 3-d plots of the type u,v,f(u,v) are equivalent to
4810: f(x,y).
4811:
4812: Note that the order the parametric functions are specified is xfunction,
4813: yfunction (and zfunction) and that each operates over the common parametric
4814: domain.
4815:
4816: Also, the `set parametric` function implies a new range of values. Whereas
4817: the normal f(x) and f(x,y) style plotting assume an xrange and yrange (and
4818: zrange), the parametric mode additionally specifies a trange, urange, and
4819: vrange. These ranges may be set directly with `set trange`, `set urange`,
4820: and `set vrange`, or by specifying the range on the `plot` or `splot`
4821: commands. Currently the default range for these parametric variables is
4822: [-5:5]. Setting the ranges to something more meaningful is expected.
4823: 3 pointsize
4824: ?commands set pointsize
4825: ?commands show pointsize
4826: ?set pointsize
4827: ?show pointsize
4828: ?pointsize
4829: The `set pointsize` command scales the size of the points used in plots.
4830:
4831: Syntax:
4832: set pointsize <multiplier>
4833: show pointsize
4834:
4835: The default is a multiplier of 1.0. Larger pointsizes may be useful to
4836: make points more visible in bitmapped graphics.
4837:
4838: The pointsize of a single plot may be changed on the `plot` command. See
4839: `plot with` for details.
4840:
4841: Please note that the pointsize setting is not supported by all terminal
4842: types.
4843: 3 polar
4844: ?commands set polar
4845: ?commands set nopolar
4846: ?commands show polar
4847: ?set polar
4848: ?set nopolar
4849: ?show polar
4850: ?polar
4851: ?nopolar
4852: The `set polar` command changes the meaning of the plot from rectangular
4853: coordinates to polar coordinates.
4854:
4855: Syntax:
4856: set polar
4857: set nopolar
4858: show polar
4859:
4860: There have been changes made to polar mode in version 3.7, so that scripts
4861: for `gnuplot` versions 3.5 and earlier will require modification. The main
4862: change is that the dummy variable t is used for the angle so that the x and
4863: y ranges can be controlled independently. Other changes are:
4864: 1) tics are no longer put along the zero axes automatically
4865: ---use `set xtics axis nomirror`; `set ytics axis nomirror`;
4866: 2) the grid, if selected, is not automatically polar
4867: ---use `set grid polar`;
4868: 3) the grid is not labelled with angles
4869: ---use `set label` as necessary.
4870:
4871: In polar coordinates, the dummy variable (t) is an angle. The default range
4872: of t is [0:2*pi], or, if degree units have been selected, to [0:360] (see
4873: `set angles`).
4874:
4875: The command `set nopolar` changes the meaning of the plot back to the default
4876: rectangular coordinate system.
4877:
4878: The `set polar` command is not supported for `splot`s. See the `set mapping`
4879: command for similar functionality for `splot`s.
4880:
4881: While in polar coordinates the meaning of an expression in t is really
4882: r = f(t), where t is an angle of rotation. The trange controls the domain
4883: (the angle) of the function, and the x and y ranges control the range of the
4884: graph in the x and y directions. Each of these ranges, as well as the
4885: rrange, may be autoscaled or set explicitly. See `set xrange` for details
4886: of all the `set range` commands.
4887:
4888: Example:
4889: set polar
4890: plot t*sin(t)
4891: plot [-2*pi:2*pi] [-3:3] [-3:3] t*sin(t)
4892:
4893: The first `plot` uses the default polar angular domain of 0 to 2*pi. The
4894: radius and the size of the graph are scaled automatically. The second `plot`
4895: expands the domain, and restricts the size of the graph to [-3:3] in both
4896: directions.
4897:
4898: You may want to `set size square` to have `gnuplot` try to make the aspect
4899: ratio equal to unity, so that circles look circular.
1.1.1.2 maekawa 4900: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/polar.html">Polar demos </a>
4901: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html">Polar Data Plot. </a>
1.1 maekawa 4902: 3 rmargin
4903: ?commands set rmargin
4904: ?set rmargin
4905: ?rmargin
4906: The command `set rmargin` sets the size of the right margin. Please see
4907: `set margin` for details.
4908: 3 rrange
4909: ?commands set rrange
4910: ?commands show rrange
4911: ?set rrange
4912: ?show rrange
4913: ?rrange
4914: The `set rrange` command sets the range of the radial coordinate for a
4915: graph in polar mode. Please see `set xrange` for details.
4916: 3 samples
4917: ?commands set samples
4918: ?commands show samples
4919: ?set samples
4920: ?show samples
4921: ?samples
4922: The sampling rate of functions, or for interpolating data, may be changed
4923: by the `set samples` command.
4924:
4925: Syntax:
4926: set samples <samples_1> {,<samples_2>}
4927: show samples
4928:
4929: By default, sampling is set to 100 points. A higher sampling rate will
4930: produce more accurate plots, but will take longer. This parameter has no
4931: effect on data file plotting unless one of the interpolation/approximation
4932: options is used. See `plot smooth` re 2-d data and `set cntrparam` and
4933: `set dgrid3d` re 3-d data.
4934:
4935: When a 2-d graph is being done, only the value of <samples_1> is relevant.
4936:
4937: When a surface plot is being done without the removal of hidden lines, the
4938: value of samples specifies the number of samples that are to be evaluated for
4939: the isolines. Each iso-v line will have <sample_1> samples and each iso-u
4940: line will have <sample_2> samples. If you only specify <samples_1>,
4941: <samples_2> will be set to the same value as <samples_1>. See also `set
4942: isosamples`.
4943: 3 size
4944: ?commands set size
4945: ?commands show size
4946: ?set size
4947: ?show size
4948: ?size
4949: The `set size` command scales the displayed size of the plot.
4950:
4951: Syntax:
4952: set size {{no}square | ratio <r> | noratio} {<xscale>,<yscale>}
4953: show size
4954:
4955: The <xscale> and <yscale> values are the scaling factors for the size of the
4956: plot, which includes the graph and the margins.
4957:
4958: `ratio` causes `gnuplot` to try to create a graph with an aspect ratio of <r>
4959: (the ratio of the y-axis length to the x-axis length) within the portion of
4960: the plot specified by <xscale> and <yscale>.
4961:
4962: The meaning of a negative value for <r> is different. If <r>=-1, gnuplot
4963: tries to set the scales so that the unit has the same length on both the x
4964: and y axes (suitable for geographical data, for instance). If <r>=-2, the
4965: unit on y has twice the length of the unit on x, and so on.
4966:
4967: The success of `gnuplot` in producing the requested aspect ratio depends on
4968: the terminal selected. The graph area will be the largest rectangle of
4969: aspect ratio <r> that will fit into the specified portion of the output
4970: (leaving adequate margins, of course).
4971:
4972: `square` is a synonym for `ratio 1`.
4973:
4974: Both `noratio` and `nosquare` return the graph to the default aspect ratio
4975: of the terminal, but do not return <xscale> or <yscale> to their default
4976: values (1.0).
4977:
4978: `ratio` and `square` have no effect on 3-d plots.
4979:
4980: `set size` is relative to the default size, which differs from terminal to
4981: terminal. Since `gnuplot` fills as much of the available plotting area as
4982: possible by default, it is safer to use `set size` to decrease the size of
4983: a plot than to increase it. See `set terminal` for the default sizes.
4984:
4985: On some terminals, changing the size of the plot will result in text being
4986: misplaced.
4987:
4988: Examples:
4989:
4990: To set the size to normal size use:
4991: set size 1,1
4992:
4993: To make the graph half size and square use:
4994: set size square 0.5,0.5
4995:
4996: To make the graph twice as high as wide use:
4997: set size ratio 2
4998:
1.1.1.2 maekawa 4999: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html"> See demo. </a>
1.1 maekawa 5000: 3 style
5001: ?commands set function style
5002: ?commands show function style
5003: ?commands set data style
5004: ?commands show data style
5005: ?set function style
5006: ?show function style
5007: ?set data style
5008: ?show data style
5009: ?set style
5010: ?show style
5011: Default styles are chosen with the `set function style` and `set data style`
5012: commands. See `plot with` for information about how to override the default
5013: plotting style for individual functions and data sets.
5014:
5015: Syntax:
5016: set function style <style>
5017: set data style <style>
5018: show function style
5019: show data style
5020:
5021: The types used for all line and point styles (i.e., solid, dash-dot, color,
5022: etc. for lines; circles, squares, crosses, etc. for points) will be either
5023: those specified on the `plot` or `splot` command or will be chosen
5024: sequentially from the types available to the terminal in use. Use the
5025: command `test` to see what is available.
5026:
5027: None of the styles requiring more than two columns of information (e.g.,
5028: `errorbars`) can be used with `splot`s or function `plot`s. Neither `boxes`
5029: nor any of the `steps` styles can be used with `splot`s. If an inappropriate
5030: style is specified, it will be changed to `points`.
5031:
5032: For 2-d data with more than two columns, `gnuplot` is picky about the allowed
5033: `errorbar` styles. The `using` option on the `plot` command can be used to
5034: set up the correct columns for the style you want. (In this discussion,
5035: "column" will be used to refer both to a column in the data file and an entry
5036: in the `using` list.)
5037:
5038: For three columns, only `xerrorbars`, `yerrorbars` (or `errorbars`), `boxes`,
5039: and `boxerrorbars` are allowed. If another plot style is used, the style
5040: will be changed to `yerrorbars`. The `boxerrorbars` style will calculate the
5041: boxwidth automatically.
5042:
5043: For four columns, only `xerrorbars`, `yerrorbars` (or `errorbars`),
5044: `xyerrorbars`, `boxxyerrorbars`, and `boxerrorbars` are allowed. An illegal
5045: style will be changed to `yerrorbars`.
5046:
5047: Five-column data allow only the `boxerrorbars`, `financebars`, and
5048: `candlesticks` styles. (The last two of these are primarily used for plots
5049: of financial prices.) An illegal style will be changed to `boxerrorbars`
5050: before plotting.
5051:
5052: Six- and seven-column data only allow the `xyerrorbars` and `boxxyerrorbars`
5053: styles. Illegal styles will be changed to `xyerrorbars` before plotting.
5054:
5055: For more information about error bars, please see `plot errorbars`.
5056: 4 boxerrorbars
5057: ?commands set style boxerrorbars
5058: ?set style boxerrorbars
5059: ?style boxerrorbars
5060: ?boxerrorbars
5061: The `boxerrorbars` style is only relevant to 2-d data plotting. It is a
5062: combination of the `boxes` and `yerrorbars` styles. The boxwidth will come
5063: from the fourth column if the y errors are in the form of "ydelta" and the
5064: boxwidth was not previously set equal to -2.0 (`set boxwidth -2.0`) or from
5065: the fifth column if the y errors are in the form of "ylow yhigh". The
5066: special case `boxwidth = -2.0` is for four-column data with y errors in the
5067: form "ylow yhigh". In this case the boxwidth will be calculated so that each
5068: box touches the adjacent boxes. The width will also be calculated in cases
5069: where three-column data are used.
5070:
5071: The box height is determined from the y error in the same way as it is for
5072: the `yerrorbars` style---either from y-ydelta to y+ydelta or from ylow to
5073: yhigh, depending on how many data columns are provided.
5074: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html"> See Demo. </a>
5075: 4 boxes
5076: ?commands set style boxes
5077: ?commands set style bargraph
5078: ?set style boxes
5079: ?set style bargraph
5080: ?style boxes
5081: ?style bargraph
5082: ?boxes
5083: ?bargraph
5084: The `boxes` style is only relevant to 2-d plotting. It draws a box centered
5085: about the given x coordinate from the x axis (not the graph border) to the
5086: given y coordinate. The width of the box is obtained in one of three ways.
5087: If it is a data plot and the data file has a third column, this will be used
5088: to set the width of the box. If not, if a width has been set using the `set
5089: boxwidth` command, this will be used. If neither of these is available, the
5090: width of each box will be calculated automatically so that it touches the
5091: adjacent boxes.
5092: 4 boxxyerrorbars
5093: ?commands set style boxxyerrorbars
5094: ?set style boxxyerrorbars
5095: ?style boxxyerrorbars
5096: ?boxxyerrorbars
5097: The `boxxyerrorbars` style is only relevant to 2-d data plotting. It is a
5098: combination of the `boxes` and `xyerrorbars` styles.
5099:
5100: The box width and height are determined from the x and y errors in the same
5101: way as they are for the `xyerrorbars` style---either from xlow to xhigh and
5102: from ylow to yhigh, or from x-xdelta to x+xdelta and from y-ydelta to
5103: y+ydelta , depending on how many data columns are provided.
5104: 4 candlesticks
5105: ?commands set style candlesticks
5106: ?set style candlesticks
5107: ?style candlesticks
5108: ?candlesticks
5109: The `candlesticks` style is only relevant for 2-d data plotting of financial
5110: data. Five columns of data are required; in order, these should be the x
5111: coordinate (most likely a date) and the opening, low, high, and closing
5112: prices. The symbol is an open rectangle, centered horizontally at the x
5113: coordinate and limited vertically by the opening and closing prices. A
5114: vertical line segment at the x coordinate extends up from the top of the
5115: rectangle to the high price and another down to the low. The width of the
5116: rectangle may be changed by `set bar`. The symbol will be unchanged if the
5117: low and high prices are interchanged or if the opening and closing prices
5118: are interchanged. See `set bar` and `financebars`.
5119: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/finance/finance.html"> See demos.</a>
5120: 4 dots
5121: ?commands set style dots
5122: ?set style dots
5123: ?style dots
5124: ?dots
5125: The `dots` style plots a tiny dot at each point; this is useful for scatter
5126: plots with many points.
5127: 4 financebars
5128: ?commands set style financebars
5129: ?set style financebars
5130: ?style financebars
5131: ?financebars
5132: The `financebars` style is only relevant for 2-d data plotting of financial
5133: data. Five columns of data are required; in order, these should be the x
5134: coordinate (most likely a date) and the opening, low, high, and closing
5135: prices. The symbol is a vertical line segment, located horizontally at the x
5136: coordinate and limited vertically by the high and low prices. A horizontal
5137: tic on the left marks the opening price and one on the right marks the
5138: closing price. The length of these tics may be changed by `set bar`. The
5139: symbol will be unchanged if the high and low prices are interchanged. See
5140: `set bar` and `candlesticks`.
5141: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/finance/finance.html"> See demos.</a>
5142: 4 fsteps
5143: ?commands set style fsteps
5144: ?set style fsteps
5145: ?style fsteps
5146: ?fsteps
5147: The `fsteps` style is only relevant to 2-d plotting. It connects consecutive
5148: points with two line segments: the first from (x1,y1) to (x1,y2) and the
5149: second from (x1,y2) to (x2,y2).
1.1.1.2 maekawa 5150: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html"> See demo. </a>
1.1 maekawa 5151: 4 histeps
5152: ?commands set style histeps
5153: ?set style histeps
5154: ?style histeps
5155: ?histeps
5156: The `histeps` style is only relevant to 2-d plotting. It is intended for
5157: plotting histograms. Y-values are assumed to be centered at the x-values;
5158: the point at x1 is represented as a horizontal line from ((x0+x1)/2,y1) to
5159: ((x1+x2)/2,y1). The lines representing the end points are extended so that
5160: the step is centered on at x. Adjacent points are connected by a vertical
5161: line at their average x, that is, from ((x1+x2)/2,y1) to ((x1+x2)/2,y2).
5162:
5163: If `autoscale` is in effect, it selects the xrange from the data rather than
5164: the steps, so the end points will appear only half as wide as the others.
1.1.1.2 maekawa 5165: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html"> See demo. </a>
1.1 maekawa 5166:
5167: `histeps` is only a plotting style; `gnuplot` does not have the ability to
5168: create bins and determine their population from some data set.
5169: 4 impulses
5170: ?commands set style impulses
5171: ?set style impulses
5172: ?style impulses
5173: ?impulses
5174: The `impulses` style displays a vertical line from the x axis (not the graph
5175: border), or from the grid base for `splot`, to each point.
5176: 4 lines
5177: ?commands set style lines
5178: ?set style lines
5179: ?style lines
5180: ?lines
5181: The `lines` style connects adjacent points with straight line segments.
5182: 4 linespoints
5183: ?commands set style linespoints
5184: ?commands set style lp
5185: ?set style linespoints
5186: ?set style lp
5187: ?style linespoints
5188: ?style lp
5189: ?linespoints
5190: ?lp
5191: The `linespoints` style does both `lines` and `points`, that is, it draws a
5192: small symbol at each point and then connects adjacent points with straight
5193: line segments. The command `set pointsize` may be used to change the size of
5194: the points. See `set pointsize` for its usage.
5195:
5196: `linespoints` may be abbreviated `lp`.
5197: 4 points
5198: ?commands set style points
5199: ?set style points
5200: ?style points
5201: ?points
5202: The `points` style displays a small symbol at each point. The command `set
5203: pointsize` may be used to change the size of the points. See `set pointsize`
5204: for its usage.
5205: 4 steps
5206: ?commands set style steps
5207: ?set style steps
5208: ?style steps
5209: ?steps
5210: The `steps` style is only relevant to 2-d plotting. It connects consecutive
5211: points with two line segments: the first from (x1,y1) to (x2,y1) and the
5212: second from (x2,y1) to (x2,y2).
1.1.1.2 maekawa 5213: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html"> See demo. </a>
1.1 maekawa 5214: 4 vector
5215: ?commands set style vector
5216: ?set style vector
5217: ?style vector
5218: ?vector
5219: The `vector` style draws a vector from (x,y) to (x+xdelta,y+ydelta). Thus
5220: it requires four columns of data. It also draws a small arrowhead at the
5221: end of the vector.
5222:
1.1.1.3 ! ohara 5223: `set clip one` and `set clip two` affect drawing vectors.
! 5224: Please see `set clip`.
1.1 maekawa 5225: 4 xerrorbars
5226: ?commands set style xerrorbars
5227: ?set style xerrorbars
5228: ?style xerrorbars
5229: ?xerrorbars
5230: The `xerrorbars` style is only relevant to 2-d data plots. `xerrorbars` is
5231: like `dots`, except that a horizontal error bar is also drawn. At each point
5232: (x,y), a line is drawn from (xlow,y) to (xhigh,y) or from (x-xdelta,y) to
5233: (x+xdelta,y), depending on how many data columns are provided. A tic mark
5234: is placed at the ends of the error bar (unless `set bar` is used---see `set
5235: bar` for details).
5236: 4 xyerrorbars
5237: ?commands set style xyerrorbars
5238: ?set style xyerrorbars
5239: ?style xyerrorbars
5240: ?xyerrorbars
5241: The `xyerrorbars` style is only relevant to 2-d data plots. `xyerrorbars` is
5242: like `dots`, except that horizontal and vertical error bars are also drawn.
5243: At each point (x,y), lines are drawn from (x,y-ydelta) to (x,y+ydelta) and
5244: from (x-xdelta,y) to (x+xdelta,y) or from (x,ylow) to (x,yhigh) and from
5245: (xlow,y) to (xhigh,y), depending upon the number of data columns provided. A
5246: tic mark is placed at the ends of the error bar (unless `set bar` is
5247: used---see `set bar` for details).
5248:
5249: If data are provided in an unsupported mixed form, the `using` filter on the
5250: `plot` command should be used to set up the appropriate form. For example,
5251: if the data are of the form (x,y,xdelta,ylow,yhigh), then you can use
5252:
1.1.1.3 ! ohara 5253: plot 'data' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars
1.1 maekawa 5254: 4 yerrorbars
5255: ?commands set style yerrorbars
5256: ?commands set style errorbars
5257: ?set style yerrorbars
5258: ?set style errorbars
5259: ?style yerrorbars
5260: ?style errorbars
5261: ?yerrorbars
5262: ?errorbars
5263: The `yerrorbars` (or `errorbars`) style is only relevant to 2-d data plots.
5264: `yerrorbars` is like `dots`, except that a vertical error bar is also drawn.
5265: At each point (x,y), a line is drawn from (x,y-ydelta) to (x,y+ydelta) or
5266: from (x,ylow) to (x,yhigh), depending on how many data columns are provided.
5267: A tic mark is placed at the ends of the error bar (unless `set bar` is
5268: used---see `set bar` for details).
5269: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html"> See demo. </a>
5270: 3 surface
5271: ?commands set surface
5272: ?commands set nosurface
5273: ?commands show surface
5274: ?set surface
5275: ?set nosurface
5276: ?show surface
5277: ?surface
5278: ?nosurface
5279: The command `set surface` controls the display of surfaces by `splot`.
5280:
5281: Syntax:
5282: set surface
5283: set nosurface
5284: show surface
5285:
5286: The surface is drawn with the style specifed by `with`, or else the
5287: appropriate style, data or function.
5288:
5289: Whenever `set nosurface` is issued, `splot` will not draw points or lines
1.1.1.3 ! ohara 5290: corresponding to the function or data file points. Contours may still be
1.1 maekawa 5291: drawn on the surface, depending on the `set contour` option. `set nosurface;
5292: set contour base` is useful for displaying contours on the grid base. See
5293: also `set contour`.
5294: ^ <h2> Terminal Types </h2>
5295: 3 terminal
5296: ?commands set terminal
5297: ?commands show terminal
5298: ?set terminal
5299: ?set term
5300: ?show terminal
5301: ?terminal
5302: ?term
5303: `gnuplot` supports many different graphics devices. Use `set terminal` to
5304: tell `gnuplot` what kind of output to generate. Use `set output` to redirect
5305: that output to a file or device.
5306:
5307: Syntax:
5308: set terminal {<terminal-type>}
5309: show terminal
5310:
5311: If <terminal-type> is omitted, `gnuplot` will list the available terminal
5312: types. <terminal-type> may be abbreviated.
5313:
5314: If both `set terminal` and `set output` are used together, it is safest to
5315: give `set terminal` first, because some terminals set a flag which is needed
5316: in some operating systems.
5317:
5318: Several terminals have additional options. For example, see `dumb`,
5319: `iris4d`, `hpljii` or `postscript`.
5320:
5321: This document may describe drivers that are not available to you because they
5322: were not installed, or it may not describe all the drivers that are available
5323: to you, depending on its output format.
5324: <4 -- all terminal stuff is pulled from the .trm files
5325: 3 tics
5326: ?commands set tics
5327: ?commands show tics
5328: ?set tics
5329: ?show tics
5330: ?tics
5331: The `set tics` command can be used to change the tics to be drawn outwards.
5332:
5333: Syntax:
5334: set tics {<direction>}
5335: show tics
5336:
5337: where <direction> may be `in` (the default) or `out`.
5338:
5339: See also `set xtics` for more control of major (labelled) tic marks and `set
5340: mxtics` for control of minor tic marks.
5341: 3 ticslevel
5342: ?commands set ticslevel
5343: ?commands show ticslevel
5344: ?set ticslevel
5345: ?show ticslevel
5346: ?ticslevel
5347: Using `splot`, one can adjust the relative height of the vertical (Z) axis
5348: using `set ticslevel`. The numeric argument provided specifies the location
5349: of the bottom of the scale (as a fraction of the z-range) above the xy-plane.
5350: The default value is 0.5. Negative values are permitted, but tic labels on
5351: the three axes may overlap.
5352:
5353: To place the xy-plane at a position 'pos' on the z-axis, `ticslevel` should
5354: be set equal to (pos - zmin) / (zmin - zmax).
5355:
5356: Syntax:
5357: set ticslevel {<level>}
5358: show tics
5359:
5360: See also `set view`.
5361: 3 ticscale
5362: ?commands set ticscale
5363: ?commands show ticscale
5364: ?set ticscale
5365: ?show ticscale
5366: ?ticscale
5367: The size of the tic marks can be adjusted with `set ticscale`.
5368:
5369: Syntax:
5370: set ticscale {<major> {<minor>}}
5371: show tics
5372:
5373: If <minor> is not specified, it is 0.5*<major>. The default size is 1.0 for
5374: major tics and 0.5 for minor tics. Note that it is possible to have the tic
5375: marks pointing outward by specifying a negative size.
5376: 3 timestamp
5377: ?commands set timestamp
5378: ?commands set time
5379: ?commands set notimestamp
5380: ?commands show timestamp
5381: ?set timestamp
5382: ?set time
5383: ?set notimestamp
5384: ?show timestamp
5385: ?timestamp
5386: ?notimestamp
5387: The command `set timestamp` places the time and date of the plot in the left
5388: margin.
5389:
5390: Syntax:
5391: set timestamp {"<format>"} {top|bottom} {{no}rotate}
5392: {<xoff>}{,<yoff>} {"<font>"}
5393: set notimestamp
5394: show timestamp
5395:
5396: The format string allows you to choose the format used to write the date and
5397: time. Its default value is what asctime() uses: "%a %b %d %H:%M:%S %Y"
5398: (weekday, month name, day of the month, hours, minutes, seconds, four-digit
5399: year). With `top` or `bottom` you can place the timestamp at the top or
5400: bottom of the left margin (default: bottom). `rotate` lets you write the
5401: timestamp vertically, if your terminal supports vertical text. The constants
1.1.1.3 ! ohara 5402: <xoff> and <yoff> are offsets from the default position given in character
1.1 maekawa 5403: screen coordinates. <font> is used to specify the font with which the time
5404: is to be written.
5405:
5406: The abbreviation `time` may be used in place of `timestamp`.
5407:
5408: Example:
5409: set timestamp "%d/%m/%y %H:%M" 80,-2 "Helvetica"
5410:
5411: See `set timefmt` for more information about time format strings.
5412: 3 timefmt
5413: ?commands set timefmt
5414: ?commands show timefmt
5415: ?set timefmt
5416: ?show timefmt
5417: ?timefmt
5418: This command applies to timeseries where data are composed of dates/times.
5419: It has no meaning unless the command `set xdata time` is given also.
5420:
5421: Syntax:
5422: set timefmt "<format string>"
5423: show timefmt
5424:
5425: The string argument tells `gnuplot` how to read timedata from the datafile.
5426: The valid formats are:
5427:
5428: @start table - first is interactive cleartext form
5429: Format Explanation
5430: %d day of the month, 1--31
5431: %m month of the year, 1--12
5432: %y year, 0--99
5433: %Y year, 4-digit
5434: %j day of the year, 1--365
5435: %H hour, 0--24
5436: %M minute, 0--60
1.1.1.3 ! ohara 5437: %s seconds since the Unix epoch (1970-01-01, 00:00 UTC)
1.1 maekawa 5438: %S second, 0--60
5439: %b three-character abbreviation of the name of the month
5440: %B name of the month
5441: #\begin{tabular}{|cl|} \hline
5442: #\multicolumn{2}{|c|}{Time Series timedata Format Specifiers}\\
5443: #\hline \hline
5444: #Format & Explanation \\ \hline
5445: #\verb@%d@ & day of the month, 1--31 \\
5446: #\verb@%m@ & month of the year, 1--12 \\
5447: #\verb@%y@ & year, 0--99 \\
5448: #\verb@%Y@ & year, 4-digit \\
5449: #\verb@%j@ & day of the year, 1--365 \\
5450: #\verb@%H@ & hour, 0--24 \\
5451: #\verb@%M@ & minute, 0--60 \\
1.1.1.3 ! ohara 5452: #\verb@%s@ & seconds since the Unix epoch (1970-01-01 00:00 UTC) \\
1.1 maekawa 5453: #\verb@%S@ & second, 0--60 \\
5454: #\verb@%b@ & three-character abbreviation of the name of the month \\
5455: #\verb@%B@ & name of the month \\
5456: %c l .
5457: %Format@Explanation
5458: %_
5459: %%d@day of the month, 1--31
5460: %%m@month of the year, 1--12
5461: %%y@year, 0--99
5462: %%Y@year, 4-digit
5463: %%j@day of the year, 1--365
5464: %%H@hour, 0--24
5465: %%M@minute, 0--60
1.1.1.3 ! ohara 5466: %%s@seconds since the Unix epoch (1970-01-01 00:00 UTC)
1.1 maekawa 5467: %%S@second, 0--60
5468: %%b@three-character abbreviation of the name of the month
5469: %%B@name of the month
5470: %_
5471: @end table
5472: Any character is allowed in the string, but must match exactly. \t (tab) is
5473: recognized. Backslash-octals (\nnn) are converted to char. If there is no
5474: separating character between the time/date elements, then %d, %m, %y, %H, %M
5475: and %S read two digits each, %Y reads four digits and %j reads three digits.
5476: %b requires three characters, and %B requires as many as it needs.
5477:
5478: Spaces are treated slightly differently. A space in the string stands for
5479: zero or more whitespace characters in the file. That is, "%H %M" can be used
5480: to read "1220" and "12 20" as well as "12 20".
5481:
5482: Each set of non-blank characters in the timedata counts as one column in the
5483: `using n:n` specification. Thus `11:11 25/12/76 21.0` consists of three
5484: columns. To avoid confusion, `gnuplot` requires that you provide a complete
5485: `using` specification if your file contains timedata.
5486:
5487: Since `gnuplot` cannot read non-numerical text, if the date format includes
5488: the day or month in words, the format string must exclude this text. But
5489: it can still be printed with the "%a", "%A", "%b", or "%B" specifier: see
5490: `set format` for more details about these and other options for printing
5491: timedata. (`gnuplot` will determine the proper month and weekday from the
5492: numerical values.)
5493:
5494: See also `set xdata` and `Time/date` for more information.
5495:
5496: Example:
5497: set timefmt "%d/%m/%Y\t%H:%M"
5498: tells `gnuplot` to read date and time separated by tab. (But look closely at
5499: your data---what began as a tab may have been converted to spaces somewhere
5500: along the line; the format string must match what is actually in the file.)
1.1.1.2 maekawa 5501: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/timedat.html"> Time Data Demo </a>
1.1 maekawa 5502: 3 title
5503: ?commands set title
5504: ?commands show title
5505: ?set title
5506: ?show title
5507: ?title
5508: The `set title` command produces a plot title that is centered at the top of
5509: the plot. `set title` is a special case of `set label`.
5510:
5511: Syntax:
5512: set title {"<title-text>"} {<xoff>}{,<yoff>} {"<font>,{<size>}"}
5513: show title
5514:
5515: Specifying constants <xoff> or <yoff> as optional offsets for the title will
5516: move the title <xoff> or <yoff> character screen coordinates (not graph
5517: coordinates). For example, "`set title ,-1`" will change only the y offset
5518: of the title, moving the title down by roughly the height of one character.
5519:
5520: <font> is used to specify the font with which the title is to be written;
5521: the units of the font <size> depend upon which terminal is used.
5522:
5523: `set title` with no parameters clears the title.
5524:
5525: See `syntax` for details about the processing of backslash sequences and
5526: the distinction between single- and double-quotes.
5527: 3 tmargin
5528: ?commands set tmargin
5529: ?set tmargin
5530: ?tmargin
5531: The command `set tmargin` sets the size of the top margin. Please see
5532: `set margin` for details.
5533: 3 trange
5534: ?commands set trange
5535: ?commands show trange
5536: ?set trange
5537: ?show trange
5538: ?trange
5539: The `set trange` command sets the parametric range used to compute x and y
5540: values when in parametric or polar modes. Please see `set xrange` for
5541: details.
5542: 3 urange
5543: ?commands set urange
5544: ?commands show urange
5545: ?set urange
5546: ?show urange
5547: ?urange
5548: The `set urange` and `set vrange` commands set the parametric ranges used
5549: to compute x, y, and z values when in `splot` parametric mode. Please see
5550: `set xrange` for details.
5551: 3 variables
5552: ?commands show variables
5553: ?show variables
5554: The `show variables` command lists all user-defined variables and their
5555: values.
5556:
5557: Syntax:
5558: show variables
5559: 3 version
5560: ?show version
5561: The `show version` command lists the version of gnuplot being run, its last
5562: modification date, the copyright holders, and email addresses for the FAQ,
5563: the info-gnuplot mailing list, and reporting bugs--in short, the information
5564: listed on the screen when the program is invoked interactively.
5565:
5566: Syntax:
5567: show version {long}
5568:
5569: When the `long` option is given, it also lists the operating system, the
5570: compilation options used when `gnuplot` was installed, the location of the
5571: help file, and (again) the useful email addresses.
5572: 3 view
5573: ?commands set view
5574: ?commands show view
5575: ?set view
5576: ?show view
5577: ?view
5578: The `set view` command sets the viewing angle for `splot`s. It controls how
5579: the 3-d coordinates of the plot are mapped into the 2-d screen space. It
5580: provides controls for both rotation and scaling of the plotted data, but
5581: supports orthographic projections only.
5582:
5583: Syntax:
5584: set view <rot_x> {,{<rot_z>}{,{<scale>}{,<scale_z>}}}
5585: show view
5586:
5587: where <rot_x> and <rot_z> control the rotation angles (in degrees) in a
5588: virtual 3-d coordinate system aligned with the screen such that initially
5589: (that is, before the rotations are performed) the screen horizontal axis is
5590: x, screen vertical axis is y, and the axis perpendicular to the screen is z.
5591: The first rotation applied is <rot_x> around the x axis. The second rotation
5592: applied is <rot_z> around the new z axis.
5593:
5594: <rot_x> is bounded to the [0:180] range with a default of 60 degrees, while
5595: <rot_z> is bounded to the [0:360] range with a default of 30 degrees.
5596: <scale> controls the scaling of the entire `splot`, while <scale_z> scales
5597: the z axis only. Both scales default to 1.0.
5598:
5599: Examples:
5600: set view 60, 30, 1, 1
5601: set view ,,0.5
5602:
5603: The first sets all the four default values. The second changes only scale,
5604: to 0.5.
5605:
5606: See also `set ticslevel`.
5607: 3 vrange
5608: ?commands set vrange
5609: ?commands show vrange
5610: ?set vrange
5611: ?show vrange
5612: ?vrange
5613: The `set urange` and `set vrange` commands set the parametric ranges used
5614: to compute x, y, and z values when in `splot` parametric mode. Please see
5615: `set xrange` for details.
5616: 3 x2data
5617: ?commands set x2data
5618: ?commands show x2data
5619: ?set x2data
5620: ?show x2data
5621: ?x2data
5622: The `set x2data` command sets data on the x2 (top) axis to timeseries
5623: (dates/times). Please see `set xdata`.
5624: 3 x2dtics
5625: ?commands set x2dtics
5626: ?commands set nox2dtics
5627: ?commands show x2dtics
5628: ?set x2dtics
5629: ?set nox2dtics
5630: ?show x2dtics
5631: ?x2dtics
5632: ?nox2dtics
5633: The `set x2dtics` command changes tics on the x2 (top) axis to days of the
5634: week. Please see `set xdtics` for details.
5635: 3 x2label
5636: ?commands set x2label
5637: ?commands show x2label
5638: ?set x2label
5639: ?show x2label
5640: ?x2label
5641: The `set x2label` command sets the label for the x2 (top) axis. Please see
5642: `set xlabel`.
5643: 3 x2mtics
5644: ?commands set x2mtics
5645: ?commands set nox2mtics
5646: ?commands show x2mtics
5647: ?set x2mtics
5648: ?set nox2mtics
5649: ?show x2mtics
5650: ?x2mtics
5651: ?nox2mtics
5652: The `set x2mtics` command changes tics on the x2 (top) axis to months of the
5653: year. Please see `set xmtics` for details.
5654: 3 x2range
5655: ?commands set x2range
5656: ?commands show x2range
5657: ?set x2range
5658: ?show x2range
5659: ?x2range
5660: The `set x2range` command sets the horizontal range that will be displayed on
5661: the x2 (top) axis. Please see `set xrange` for details.
5662: 3 x2tics
5663: ?commands set x2tics
5664: ?commands set nox2tics
5665: ?commands show x2tics
5666: ?set x2tics
5667: ?set nox2tics
5668: ?show x2tics
5669: ?x2tics
5670: ?nox2tics
5671: The `set x2tics` command controls major (labelled) tics on the x2 (top) axis.
5672: Please see `set xtics` for details.
5673: 3 x2zeroaxis
5674: ?commands set x2zeroaxis
5675: ?commands set nox2zeroaxis
5676: ?commands show x2zeroaxis
5677: ?set x2zeroaxis
5678: ?set nox2zeroaxis
5679: ?show x2zeroaxis
5680: ?x2zeroaxis
5681: ?nox2zeroaxis
5682: The `set x2zeroaxis` command draws a line at the origin of the x2 (top) axis
5683: (y2 = 0). For details, please see
5684: `set zeroaxis`.
5685: 3 xdata
5686: ?commands set xdata
5687: ?commands show xdata
5688: ?set xdata
5689: ?show xdata
5690: ?xdata
5691: This command sets the datatype on the x axis to time/date. A similar command
5692: does the same thing for each of the other axes.
5693:
5694: Syntax:
5695: set xdata {time}
5696: show xdata
5697:
5698: The same syntax applies to `ydata`, `zdata`, `x2data` and `y2data`.
5699:
5700: The `time` option signals that the datatype is indeed time/date. If the
5701: option is not specified, the datatype reverts to normal.
5702:
5703: See `set timefmt` to tell `gnuplot` how to read date or time data. The
5704: time/date is converted to seconds from start of the century. There is
5705: currently only one timefmt, which implies that all the time/date columns must
1.1.1.3 ! ohara 5706: conform to this format. Specification of ranges should be supplied as quoted
1.1 maekawa 5707: strings according to this format to avoid interpretation of the time/date as
5708: an expression.
5709:
5710: The function 'strftime' (type "man strftime" on unix to look it up) is used
5711: to print tic-mark labels. `gnuplot` tries to figure out a reasonable format
5712: for this unless the `set format x "string"` has supplied something that does
5713: not look like a decimal format (more than one '%' or neither %f nor %g).
5714:
5715: See also `Time/date` for more information.
5716: 3 xdtics
5717: ?commands set xdtics
5718: ?commands set noxdtics
5719: ?commands show xdtics
5720: ?set xdtics
5721: ?set noxdtics
5722: ?show xdtics
5723: ?xdtics
5724: ?noxdtics
5725: The `set xdtics` commands converts the x-axis tic marks to days of the week
5726: where 0=Sun and 6=Sat. Overflows are converted modulo 7 to dates. `set
5727: noxdtics` returns the labels to their default values. Similar commands do
5728: the same things for the other axes.
5729:
5730: Syntax:
5731: set xdtics
5732: set noxdtics
5733: show xdtics
5734:
5735: The same syntax applies to `ydtics`, `zdtics`, `x2dtics` and `y2dtics`.
5736:
5737: See also the `set format` command.
5738: 3 xlabel
5739: ?commands set xlabel
5740: ?commands show xlabel
5741: ?set xlabel
5742: ?show xlabel
5743: ?xlabel
5744: The `set xlabel` command sets the x axis label. Similar commands set labels
5745: on the other axes.
5746:
5747: Syntax:
5748: set xlabel {"<label>"} {<xoff>}{,<yoff>} {"<font>{,<size>}"}
5749: show xlabel
5750:
5751: The same syntax applies to `x2label`, `ylabel`, `y2label` and `zlabel`.
5752:
5753: Specifying the constants <xoff> or <yoff> as optional offsets for a label
5754: will move it <xoff> or <yoff> character widths or heights. For example,
5755: "` set xlabel -1`" will change only the x offset of the xlabel, moving the
5756: label roughly one character width to the left. The size of a character
5757: depends on both the font and the terminal.
5758:
5759: <font> is used to specify the font in which the label is written; the units
5760: of the font <size> depend upon which terminal is used.
5761:
5762: To clear a label, put no options on the command line, e.g., "`set y2label`".
5763:
5764: The default positions of the axis labels are as follows:
5765:
5766: xlabel: The x-axis label is centered below the bottom axis.
5767:
5768: ylabel: The position of the y-axis label depends on the terminal, and can be
5769: one of the following three positions:
5770:
5771: 1. Horizontal text flushed left at the top left of the plot. Terminals that
5772: cannot rotate text will probably use this method. If `set x2tics` is also
5773: in use, the ylabel may overwrite the left-most x2tic label. This may be
5774: remedied by adjusting the ylabel position or the left margin.
5775:
5776: 2. Vertical text centered vertically at the left of the plot. Terminals
5777: that can rotate text will probably use this method.
5778:
5779: 3. Horizontal text centered vertically at the left of the plot. The EEPIC,
5780: LaTeX and TPIC drivers use this method. The user must insert line breaks
5781: using \\ to prevent the ylabel from overwriting the plot. To produce a
5782: vertical row of characters, add \\ between every printing character (but this
5783: is ugly).
5784:
5785: zlabel: The z-axis label is centered along the z axis and placed in the space
5786: above the grid level.
5787:
5788: y2label: The y2-axis label is placed to the right of the y2 axis. The
5789: position is terminal-dependent in the same manner as is the y-axis label.
5790:
5791: x2label: The x2-axis label is placed above the top axis but below the plot
5792: title. It is also possible to create an x2-axis label by using new-line
5793: characters to make a multi-line plot title, e.g.,
5794:
5795: set title "This is the title\n\nThis is the x2label"
5796:
5797: Note that double quotes must be used. The same font will be used for both
5798: lines, of course.
5799:
5800: If you are not satisfied with the default position of an axis label, use `set
5801: label` instead--that command gives you much more control over where text is
5802: placed.
5803:
1.1.1.3 ! ohara 5804: Please see `syntax` for further information about backslash processing
1.1 maekawa 5805: and the difference between single- and double-quoted strings.
5806: 3 xmtics
5807: ?commands set xmtics
5808: ?commands set noxmtics
5809: ?commands show xmtics
5810: ?set xmtics
5811: ?set noxmtics
5812: ?show xmtics
5813: ?xmtics
5814: ?noxmtics
1.1.1.3 ! ohara 5815: The `set xmtics` command converts the x-axis tic marks to months of the
1.1 maekawa 5816: year where 1=Jan and 12=Dec. Overflows are converted modulo 12 to months.
5817: The tics are returned to their default labels by `set noxmtics`. Similar
5818: commands perform the same duties for the other axes.
5819:
5820: Syntax:
5821: set xmtics
5822: set noxmtics
5823: show xmtics
5824:
5825: The same syntax applies to `x2mtics`, `ymtics`, `y2mtics`, and `zmtics`.
5826:
5827: See also the `set format` command.
5828: 3 xrange
5829: ?commands set xrange
5830: ?commands show xrange
5831: ?set xrange
5832: ?show xrange
1.1.1.3 ! ohara 5833: ?writeback
! 5834: ?restore
1.1 maekawa 5835: ?xrange
5836: The `set xrange` command sets the horizontal range that will be displayed.
5837: A similar command exists for each of the other axes, as well as for the
5838: polar radius r and the parametric variables t, u, and v.
5839:
5840: Syntax:
1.1.1.3 ! ohara 5841: set xrange { [{{<min>}:{<max>}}] {{no}reverse} {{no}writeback} }
! 5842: | restore
1.1 maekawa 5843: show xrange
5844:
5845: where <min> and <max> terms are constants, expressions or an asterisk to set
5846: autoscaling. If the data are time/date, you must give the range as a quoted
5847: string according to the `set timefmt` format. Any value omitted will not be
5848: changed.
5849:
5850: The same syntax applies to `yrange`, `zrange`, `x2range`, `y2range`,
5851: `rrange`, `trange`, `urange` and `vrange`.
5852:
5853: The `reverse` option reverses the direction of the axis, e.g., `set xrange
5854: [0:1] reverse` will produce an axis with 1 on the left and 0 on the right.
5855: This is identical to the axis produced by `set xrange [1:0]`, of course.
5856: `reverse` is intended primarily for use with `autoscale`.
5857:
5858: The `writeback` option essentially saves the range found by `autoscale` in
5859: the buffers that would be filled by `set xrange`. This is useful if you wish
5860: to plot several functions together but have the range determined by only
5861: some of them. The `writeback` operation is performed during the `plot`
1.1.1.3 ! ohara 5862: execution, so it must be specified before that command. To restore
! 5863: the last saved horizontal range use `set xrange restore`. For example,
1.1 maekawa 5864:
5865: set xrange [-10:10]
5866: set yrange [] writeback
5867: plot sin(x)
1.1.1.3 ! ohara 5868: set yrange restore
1.1 maekawa 5869: replot x/2
5870:
5871: results in a yrange of [-1:1] as found only from the range of sin(x); the
5872: [-5:5] range of x/2 is ignored. Executing `show yrange` after each command
5873: in the above example should help you understand what is going on.
5874:
5875: In 2-d, `xrange` and `yrange` determine the extent of the axes, `trange`
5876: determines the range of the parametric variable in parametric mode or the
5877: range of the angle in polar mode. Similarly in parametric 3-d, `xrange`,
5878: `yrange`, and `zrange` govern the axes and `urange` and `vrange` govern the
5879: parametric variables.
5880:
5881: In polar mode, `rrange` determines the radial range plotted. <rmin> acts as
5882: an additive constant to the radius, whereas <rmax> acts as a clip to the
5883: radius---no point with radius greater than <rmax> will be plotted. `xrange`
5884: and `yrange` are affected---the ranges can be set as if the graph was of
5885: r(t)-rmin, with rmin added to all the labels.
5886:
5887: Any range may be partially or totally autoscaled, although it may not make
5888: sense to autoscale a parametric variable unless it is plotted with data.
5889:
5890: Ranges may also be specified on the `plot` command line. A range given on
5891: the plot line will be used for that single `plot` command; a range given by
5892: a `set` command will be used for all subsequent plots that do not specify
5893: their own ranges. The same holds true for `splot`.
5894:
5895: Examples:
5896:
5897: To set the xrange to the default:
5898: set xrange [-10:10]
5899:
5900: To set the yrange to increase downwards:
5901: set yrange [10:-10]
5902:
5903: To change zmax to 10 without affecting zmin (which may still be autoscaled):
5904: set zrange [:10]
5905:
5906: To autoscale xmin while leaving xmax unchanged:
5907: set xrange [*:]
5908: 3 xtics
5909: ?commands set xtics
5910: ?commands set noxtics
5911: ?commands show xtics
5912: ?set xtics
5913: ?set noxtics
5914: ?show xtics
5915: ?xtics
5916: ?noxtics
5917: Fine control of the major (labelled) tics on the x axis is possible with the
5918: `set xtics` command. The tics may be turned off with the `set noxtics`
5919: command, and may be turned on (the default state) with `set xtics`. Similar
5920: commands control the major tics on the y, z, x2 and y2 axes.
5921:
5922: Syntax:
5923: set xtics {axis | border} {{no}mirror} {{no}rotate}
5924: { autofreq
5925: | <incr>
5926: | <start>, <incr> {,<end>}
5927: | ({"<label>"} <pos> {,{"<label>"} <pos>}...) }
5928: set noxtics
5929: show xtics
5930:
5931: The same syntax applies to `ytics`, `ztics`, `x2tics` and `y2tics`.
5932:
5933: `axis` or `border` tells `gnuplot` to put the tics (both the tics themselves
1.1.1.2 maekawa 5934: and the accompanying labels) along the axis or the border, respectively. If
5935: the axis is very close to the border, the `axis` option can result in tic
5936: labels overwriting other text written in the margin.
5937:
5938: `mirror` tells `gnuplot` to put unlabelled tics at the same positions on the
5939: opposite border. `nomirror` does what you think it does.
5940:
5941: `rotate` asks `gnuplot` to rotate the text through 90 degrees, which will be
5942: done if the terminal driver in use supports text rotation. `norotate`
5943: cancels this.
5944:
5945: The defaults are `border mirror norotate` for tics on the x and y axes, and
5946: `border nomirror norotate` for tics on the x2 and y2 axes. For the z axis,
1.1.1.3 ! ohara 5947: the `{axis | border}` option is not available and the default is
1.1.1.2 maekawa 5948: `nomirror`. If you do want to mirror the z-axis tics, you might want to
5949: create a bit more room for them with `set border`.
5950:
5951: `set xtics` with no options restores the default border or axis if xtics are
5952: being displayed; otherwise it has no effect. Any previously specified tic
5953: frequency or position {and labels} are retained.
1.1 maekawa 5954:
5955: Positions of the tics are calculated automatically by default or if the
5956: `autofreq` option is given; otherwise they may be specified in either of
5957: two forms:
5958:
5959: The implicit <start>, <incr>, <end> form specifies that a series of tics will
5960: be plotted on the axis between the values <start> and <end> with an increment
5961: of <incr>. If <end> is not given, it is assumed to be infinity. The
5962: increment may be negative. If neither <start> nor <end> is given, <start> is
5963: assumed to be negative infinity, <end> is assumed to be positive infinity,
1.1.1.3 ! ohara 5964: and the tics will be drawn at integral multiples of <incr>. If the axis is
1.1 maekawa 5965: logarithmic, the increment will be used as a multiplicative factor.
5966:
5967: Examples:
5968:
5969: Make tics at 0, 0.5, 1, 1.5, ..., 9.5, 10.
5970: set xtics 0,.5,10
5971:
5972: Make tics at ..., -10, -5, 0, 5, 10, ...
5973: set xtics 5
5974:
5975: Make tics at 1, 100, 1e4, 1e6, 1e8.
1.1.1.3 ! ohara 5976: set logscale x; set xtics 1,100,1e8
1.1 maekawa 5977:
5978: The explicit ("<label>" <pos>, ...) form allows arbitrary tic positions or
5979: non-numeric tic labels. A set of tics is a set of positions, each with its
5980: own optional label. Note that the label is a string enclosed by quotes. It
5981: may be a constant string, such as "hello", may contain formatting information
5982: for converting the position into its label, such as "%3f clients", or may be
5983: empty, "". See `set format` for more information. If no string is given,
5984: the default label (numerical) is used. In this form, the tics do not need to
5985: be listed in numerical order.
5986:
5987: Examples:
5988: set xtics ("low" 0, "medium" 50, "high" 100)
5989: set xtics (1,2,4,8,16,32,64,128,256,512,1024)
5990: set ytics ("bottom" 0, "" 10, "top" 20)
5991:
5992: In the second example, all tics are labelled. In the third, only the end
5993: tics are labelled.
5994:
5995: However they are specified, tics will only be plotted when in range.
5996:
5997: Format (or omission) of the tic labels is controlled by `set format`, unless
1.1.1.3 ! ohara 5998: the explicit text of a labels is included in the `set xtics (`<label>`)` form.
1.1 maekawa 5999:
6000: Minor (unlabelled) tics can be added by the `set mxtics` command.
6001:
6002: In case of timeseries data, position values must be given as quoted dates
6003: or times according to the format `timefmt`. If the <start>, <incr>, <end>
6004: form is used, <start> and <end> must be given according to `timefmt`, but
6005: <incr> must be in seconds. Times will be written out according to the format
6006: given on `set format`, however.
6007:
6008: Examples:
6009: set xdata time
6010: set timefmt "%d/%m"
6011: set format x "%b %d"
6012: set xrange ["01/12":"06/12"]
6013: set xtics "01/12", 172800, "05/12"
6014:
6015: set xdata time
6016: set timefmt "%d/%m"
6017: set format x "%b %d"
6018: set xrange ["01/12":"06/12"]
6019: set xtics ("01/12", "" "03/12", "05/12")
6020: Both of these will produce tics "Dec 1", "Dec 3", and "Dec 5", but in the
6021: second example the tic at "Dec 3" will be unlabelled.
6022:
6023: 3 xzeroaxis
6024: ?commands set xzeroaxis
6025: ?commands set noxzeroaxis
6026: ?commands show xzeroaxis
6027: ?set xzeroaxis
6028: ?set noxzeroaxis
6029: ?show xzeroaxis
6030: ?xzeroaxis
6031: ?noxzeroaxis
6032: The `set xzeroaxis` command draws a line at y = 0. For details, please see
6033: `set zeroaxis`.
6034: 3 y2data
6035: ?commands set y2data
6036: ?commands show y2data
6037: ?set y2data
6038: ?show y2data
6039: ?y2data
6040: The `set y2data` command sets y2 (right-hand) axis data to timeseries
6041: (dates/times). Please see `set xdata`.
6042: 3 y2dtics
6043: ?commands set y2dtics
6044: ?commands set noy2dtics
6045: ?set y2dtics
6046: ?set noy2dtics
6047: ?show y2dtics
6048: ?y2dtics
6049: ?noy2dtics
6050: The `set y2dtics` command changes tics on the y2 (right-hand) axis to days of
6051: the week. Please see `set xdtics` for details.
6052: 3 y2label
6053: ?commands set y2label
6054: ?commands show y2label
6055: ?set y2label
6056: ?show y2label
6057: ?y2label
1.1.1.3 ! ohara 6058: The `set y2label` command sets the label for the y2 (right-hand) axis.
1.1 maekawa 6059: Please see `set xlabel`.
6060: 3 y2mtics
6061: ?commands set y2mtics
6062: ?commands set noy2mtics
6063: ?commands show y2mtics
6064: ?set y2mtics
6065: ?set noy2mtics
6066: ?show y2mtics
6067: ?y2mtics
6068: ?noy2mtics
6069: The `set y2mtics` command changes tics on the y2 (right-hand) axis to months
6070: of the year. Please see `set xmtics` for details.
6071: 3 y2range
6072: ?commands set y2range
6073: ?commands show y2range
6074: ?set y2range
6075: ?show y2range
6076: ?y2range
6077: The `set y2range` command sets the vertical range that will be displayed on
6078: the y2 (right-hand) axis. Please see `set xrange` for details.
6079: 3 y2tics
6080: ?commands set y2tics
6081: ?commands set noy2tics
6082: ?commands show y2tics
6083: ?set y2tics
6084: ?set noy2tics
6085: ?show y2tics
6086: ?y2tics
6087: ?noy2tics
6088: The `set y2tics` command controls major (labelled) tics on the y2 (right-hand)
6089: axis. Please see `set xtics` for details.
6090: 3 y2zeroaxis
6091: ?commands set y2zeroaxis
6092: ?commands set noy2zeroaxis
6093: ?commands show y2zeroaxis
6094: ?set y2zeroaxis
6095: ?set noy2zeroaxis
6096: ?show y2zeroaxis
6097: ?y2zeroaxis
6098: ?noy2zeroaxis
6099: The `set y2zeroaxis` command draws a line at the origin of the y2 (right-hand)
6100: axis (x2 = 0). For details, please see `set zeroaxis`.
6101: 3 ydata
6102: ?commands set ydata
6103: ?commands show ydata
6104: ?set ydata
6105: ?show ydata
6106: ?ydata
1.1.1.3 ! ohara 6107: The `set ydata` command sets y-axis data to timeseries (dates/times).
! 6108: Please see `set xdata`.
1.1 maekawa 6109: 3 ydtics
6110: ?commands set ydtics
6111: ?commands set noydtics
6112: ?commands show ydtics
6113: ?set ydtics
6114: ?set noydtics
6115: ?show ydtics
6116: ?ydtics
6117: ?noydtics
6118: The `set ydtics` command changes tics on the y axis to days of the week.
6119: Please see `set xdtics` for details.
6120: 3 ylabel
6121: ?commands set ylabel
6122: ?commands show ylabel
6123: ?set ylabel
6124: ?show ylabel
6125: ?ylabel
6126: This command sets the label for the y axis. Please see `set xlabel`.
6127: 3 ymtics
6128: ?commands set ymtics
6129: ?commands set noymtics
6130: ?commands show ymtics
6131: ?set ymtics
6132: ?set noymtics
6133: ?show ymtics
6134: ?ymtics
6135: ?noymtics
6136: The `set ymtics` command changes tics on the y axis to months of the year.
6137: Please see `set xmtics` for details.
6138: 3 yrange
6139: ?commands set yrange
6140: ?commands show yrange
6141: ?set yrange
6142: ?show yrange
6143: ?yrange
6144: The `set yrange` command sets the vertical range that will be displayed on
6145: the y axis. Please see `set xrange` for details.
6146: 3 ytics
6147: ?commands set ytics
6148: ?commands set noytics
6149: ?commands show ytics
6150: ?set ytics
6151: ?set noytics
6152: ?show ytics
6153: ?ytics
6154: ?noytics
6155: The `set ytics` command controls major (labelled) tics on the y axis.
6156: Please see `set xtics` for details.
6157: 3 yzeroaxis
6158: ?commands set yzeroaxis
6159: ?commands set noyzeroaxis
6160: ?commands show yzeroaxis
6161: ?set yzeroaxis
6162: ?set noyzeroaxis
6163: ?show yzeroaxis
6164: ?yzeroaxis
6165: ?noyzeroaxis
6166: The `set yzeroaxis` command draws a line at x = 0. For details, please see
6167: `set zeroaxis`.
6168: 3 zdata
6169: ?commands set zdata
6170: ?commands show zdata
6171: ?set zdata
6172: ?show zdata
6173: ?zdata
1.1.1.3 ! ohara 6174: The `set zdata` command sets z-axis data to timeseries (dates/times).
! 6175: Please see `set xdata`.
1.1 maekawa 6176: 3 zdtics
6177: ?commands set zdtics
6178: ?commands set nozdtics
6179: ?commands show zdtics
6180: ?set zdtics
6181: ?set nozdtics
6182: ?show zdtics
6183: ?zdtics
6184: ?nozdtics
6185: The `set zdtics` command changes tics on the z axis to days of the week.
6186: Please see `set xdtics` for details.
6187: 3 zero
6188: ?commands set zero
6189: ?commands show zero
6190: ?set zero
6191: ?show zero
6192: ?zero
6193: The `zero` value is the default threshold for values approaching 0.0.
6194:
6195: Syntax:
6196: set zero <expression>
6197: show zero
6198:
6199: `gnuplot` will not plot a point if its imaginary part is greater in magnitude
6200: than the `zero` threshold. This threshold is also used in various other
6201: parts of `gnuplot` as a (crude) numerical-error threshold. The default
6202: `zero` value is 1e-8. `zero` values larger than 1e-3 (the reciprocal of the
6203: number of pixels in a typical bitmap display) should probably be avoided, but
6204: it is not unreasonable to set `zero` to 0.0.
6205: 3 zeroaxis
6206: ?commands set zeroaxis
6207: ?commands set nozeroaxis
6208: ?commands show zeroaxis
6209: ?set zeroaxis
6210: ?set nozeroaxis
6211: ?show zeroaxis
6212: ?zeroaxis
6213: ?nozeroaxis
6214: The x axis may be drawn by `set xzeroaxis` and removed by `set noxzeroaxis`.
6215: Similar commands behave similarly for the y, x2, and y2 axes.
6216:
6217: Syntax:
6218: set {x|x2|y|y2|}zeroaxis { {linestyle | ls <line_style>}
6219: | { linetype | lt <line_type>}
6220: { linewidth | lw <line_width>}}
6221: set no{x|x2|y|y2|}zeroaxis
6222: show {x|y|}zeroaxis
6223:
6224:
6225: By default, these options are off. The selected zero axis is drawn
6226: with a line of type <line_type> and width <line_width> (if supported
6227: by the terminal driver currently in use), or a user-defined style
6228: <line_style>.
6229:
6230: If no linetype is specified, any zero axes selected will be drawn
6231: using the axis linetype (linetype 0).
6232:
6233: `set zeroaxis l` is equivalent to `set xzeroaxis l; set yzeroaxis l`. `set
6234: nozeroaxis` is equivalent to `set noxzeroaxis; set noyzeroaxis`.
6235: 3 zlabel
6236: ?commands set zlabel
6237: ?commands show zlabel
6238: ?set zlabel
6239: ?show zlabel
6240: ?zlabel
6241: This command sets the label for the z axis. Please see `set xlabel`.
6242: 3 zmtics
6243: ?commands set zmtics
6244: ?commands set nozmtics
6245: ?commands show zmtics
6246: ?set zmtics
6247: ?set nozmtics
6248: ?show zmtics
6249: ?zmtics
6250: ?nozmtics
6251: The `set zmtics` command changes tics on the z axis to months of the year.
6252: Please see `set xmtics` for details.
6253: 3 zrange
6254: ?commands set zrange
6255: ?commands show zrange
6256: ?set zrange
6257: ?show zrange
6258: ?zrange
6259: The `set zrange` command sets the range that will be displayed on the z axis.
6260: The zrange is used only by `splot` and is ignored by `plot`. Please see `set
6261: xrange` for details.
6262: 3 ztics
6263: ?commands set ztics
6264: ?commands set noztics
6265: ?commands show ztics
6266: ?set ztics
6267: ?set noztics
6268: ?show ztics
6269: ?ztics
6270: ?noztics
6271: The `set ztics` command controls major (labelled) tics on the z axis.
6272: Please see `set xtics` for details.
6273: 2 shell
6274: ?commands shell
6275: ?shell
6276: The `shell` command spawns an interactive shell. To return to `gnuplot`,
6277: type `logout` if using VMS, `exit` or the END-OF-FILE character if using
6278: Unix, `endcli` if using AmigaOS, or `exit` if using MS-DOS or OS/2.
6279:
6280: A single shell command may be spawned by preceding it with the ! character
6281: ($ if using VMS) at the beginning of a command line. Control will return
6282: immediately to `gnuplot` after this command is executed. For example, in
6283: Unix, AmigaOS, MS-DOS or OS/2,
6284:
6285: ! dir
6286:
6287: prints a directory listing and then returns to `gnuplot`.
6288:
6289: On an Atari, the `!` command first checks whether a shell is already loaded
6290: and uses it, if available. This is practical if `gnuplot` is run from
6291: `gulam`, for example.
6292: 2 splot
6293: ?commands splot
6294: ?splot
6295: `splot` is the command for drawing 3-d plots (well, actually projections on
6296: a 2-d surface, but you knew that). It can create a plot from functions or
6297: a data file in a manner very similar to the `plot` command.
6298:
6299: See `plot` for features common to the `plot` command; only differences are
6300: discussed in detail here. Note specifically that the `binary` and `matrix`
6301: options (discussed under "datafile-modifiers") are not available for `plot`.
6302:
6303: Syntax:
6304: splot {<ranges>}
6305: <function> | "<datafile>" {datafile-modifiers}}
6306: {<title-spec>} {with <style>}
6307: {, {definitions,} <function> ...}
6308:
6309: where either a <function> or the name of a data file enclosed in quotes is
6310: supplied. The function can be a mathematical expression, or a triple of
6311: mathematical expressions in parametric mode.
6312:
6313: By default `splot` draws the xy plane completely below the plotted data.
6314: The offset between the lowest ztic and the xy plane can be changed by `set
6315: ticslevel`. The orientation of a `splot` projection is controlled by
6316: `set view`. See `set view` and `set ticslevel` for more information.
6317:
6318: The syntax for setting ranges on the `splot` command is the same as for
6319: `plot`. In non-parametric mode, the order in which ranges must be given is
6320: `xrange`, `yrange`, and `zrange`. In parametric mode, the order is `urange`,
6321: `vrange`, `xrange`, `yrange`, and `zrange`.
6322:
6323: The `title` option is the same as in `plot`. The operation of `with` is also
6324: the same as in `plot`, except that the plotting styles available to `splot`
6325: are limited to `lines`, `points`, `linespoints`, `dots`, and `impulses`; the
6326: error-bar capabilities of `plot` are not available for `splot`.
6327:
6328: The datafile options have more differences.
6329: 3 data-file
6330: ?commands splot datafile
6331: ?splot datafile
6332: ?splot data-file
6333: As for `plot`, discrete data contained in a file can be displayed by
6334: specifying the name of the data file, enclosed in quotes, on the `splot`
6335: command line.
6336:
6337: Syntax:
6338: splot '<file_name>' {binary | matrix}
6339: {index <index list>}
6340: {every <every list>}
6341: {using <using list>}
6342:
6343: The special filenames `""` and `"-"` are permitted, as in `plot`.
6344:
6345: In brief, `binary` and `matrix` indicate that the the data are in a special
6346: form, `index` selects which data sets in a multi-data-set file are to be
6347: plotted, `every` specifies which datalines (subsets) within a single data
6348: set are to be plotted, and `using` determines how the columns within a single
6349: record are to be interpreted.
6350:
6351: The options `index` and `every` behave the same way as with `plot`; `using`
6352: does so also, except that the `using` list must provide three entries
6353: instead of two.
6354:
6355: The `plot` options `thru` and `smooth` are not available for `splot`, but
6356: `cntrparams` and `dgrid3d` provide limited smoothing cabilities.
6357:
6358: Data file organization is essentially the same as for `plot`, except that
6359: each point is an (x,y,z) triple. If only a single value is provided, it
6360: will be used for z, the datablock number will be used for y, and the index
6361: of the data point in the datablock will be used for x. If two values are
6362: provided, `gnuplot` gives you an error message. Three values are interpreted
6363: as an (x,y,z) triple. Additional values are generally used as errors, which
6364: can be used by `fit`.
6365:
6366: Single blank records separate datablocks in a `splot` datafile; `splot`
6367: treats datablocks as the equivalent of function y-isolines. No line will
6368: join points separated by a blank record. If all datablocks contain the same
6369: number of points, `gnuplot` will draw cross-isolines between datablocks,
6370: connecting corresponding points. This is termed "grid data", and is required
6371: for drawing a surface, for contouring (`set contour`) and hidden-line removal
6372: (`set hidden3d`). See also `splot grid data`
6373:
6374: It is no longer necessary to specify `parametric` mode for three-column
6375: `splot`s.
6376: 4 binary
6377: ?commands splot datafile binary
6378: ?splot datafile binary
6379: ?splot binary
6380: ?data-file binary
6381: ?datafile binary
6382: ?binary
6383: ?binary data
6384: ?binary files
6385: `splot` can read binary files written with a specific format (and on a
6386: system with a compatible binary file representation.)
6387:
6388: In previous versions, `gnuplot` dynamically detected binary data files. It
6389: is now necessary to specify the keyword `binary` directly after the filename.
6390:
6391: Single precision floats are stored in a binary file as follows:
6392:
6393: <N+1> <y0> <y1> <y2> ... <yN>
6394: <x0> <z0,0> <z0,1> <z0,2> ... <z0,N>
6395: <x1> <z1,0> <z1,1> <z1,2> ... <z1,N>
6396: : : : : ... :
6397:
6398: which are converted into triplets:
6399: <x0> <y0> <z0,0>
6400: <x0> <y1> <z0,1>
6401: <x0> <y2> <z0,2>
6402: : : :
6403: <x0> <yN> <z0,N>
6404:
6405: <x1> <y0> <z1,0>
6406: <x1> <y1> <z1,1>
6407: : : :
6408:
6409: These triplets are then converted into `gnuplot` iso-curves and then
6410: `gnuplot` proceeds in the usual manner to do the rest of the plotting.
6411:
6412: A collection of matrix and vector manipulation routines (in C) is provided
6413: in `binary.c`. The routine to write binary data is
6414:
6415: int fwrite_matrix(file,m,nrl,nrl,ncl,nch,row_title,column_title)
6416:
6417: An example of using these routines is provided in the file `bf_test.c`, which
6418: generates binary files for the demo file `demo/binary.dem`.
6419:
6420: The `index` keyword is not supported, since the file format allows only one
6421: surface per file. The `every` and `using` filters are supported. `using`
6422: operates as if the data were read in the above triplet form.
1.1.1.2 maekawa 6423: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/binary.html">Binary File Splot Demo.</a>
1.1 maekawa 6424: 4 example datafile
6425: ?commands splot datafile example
6426: ?splot datafile example
6427: ?splot example
6428: A simple example of plotting a 3-d data file is
6429:
6430: splot 'datafile.dat'
6431:
6432: where the file "datafile.dat" might contain:
6433:
6434: # The valley of the Gnu.
6435: 0 0 10
6436: 0 1 10
6437: 0 2 10
6438:
6439: 1 0 10
6440: 1 1 5
6441: 1 2 10
6442:
6443: 2 0 10
6444: 2 1 1
6445: 2 2 10
6446:
6447: 3 0 10
6448: 3 1 0
6449: 3 2 10
6450:
6451: Note that "datafile.dat" defines a 4 by 3 grid ( 4 rows of 3 points each ).
6452: Rows (datablocks) are separated by blank records.
6453:
6454: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/splot.gif" alt="[splot.gif]" width=640 height=480>
6455: Note also that the x value is held constant within each dataline. If you
6456: instead keep y constant, and plot with hidden-line removal enabled, you will
6457: find that the surface is drawn 'inside-out'.
6458:
6459: Actually for grid data it is not necessary to keep the x values constant
6460: within a datablock, nor is it necessary to keep the same sequence of y
6461: values. `gnuplot` requires only that the number of points be the same for
6462: each datablock. However since the surface mesh, from which contours are
6463: derived, connects sequentially corresponding points, the effect of an
6464: irregular grid on a surface plot is unpredictable and should be examined
6465: on a case-by-case basis.
6466: 4 matrix
6467: ?commands splot datafile matrix
6468: ?splot datafile matrix
6469: ?splot matrix
6470: ?data-file matrix
6471: ?datafile matrix
6472: ?matrix
6473: The `matrix` flag indicates that the ASCII data are stored in matrix format.
6474: The z-values are read in a row at a time, i. e.,
6475: z11 z12 z13 z14 ...
6476: z21 z22 z23 z24 ...
6477: z31 z32 z33 z34 ...
6478: and so forth. The row and column indices are used for the x- and y-values.
6479: 3 grid_data
6480: ?commands splot grid_data
6481: ?splot grid_data
6482: ?grid_data
6483: The 3D routines are designed for points in a grid format, with one sample,
6484: datapoint, at each mesh intersection; the datapoints may originate from
6485: either evaluating a function, see `set isosamples`, or reading a datafile,
6486: see `splot datafile`. The term "isoline" is applied to the mesh lines for
6487: both functions and data. Note that the mesh need not be rectangular in x
6488: and y, as it may be parameterized in u and v, see `set isosamples`.
6489:
6490: However, `gnuplot` does not require that format. In the case of functions,
6491: 'samples' need not be equal to 'isosamples', i.e., not every x-isoline
6492: sample need intersect a y-isoline. In the case of data files, if there
6493: are an equal number of scattered data points in each datablock, then
6494: "isolines" will connect the points in a datablock, and "cross-isolines"
6495: will connect the corresponding points in each datablock to generate a
6496: "surface". In either case, contour and hidden3d modes may give different
6497: plots than if the points were in the intended format. Scattered data can be
6498: converted to a {different} grid format with `set dgrid3d`.
6499:
6500: The contour code tests for z intensity along a line between a point on a
6501: y-isoline and the corresponding point in the next y-isoline. Thus a `splot`
6502: contour of a surface with samples on the x-isolines that do not coincide with
6503: a y-isoline intersection will ignore such samples. Try:
6504: set xrange [-pi/2:pi/2]; set yrange [-pi/2:pi/2]
6505: set function style lp
6506: set contour
6507: set isosamples 10,10; set samples 10,10;
6508: splot cos(x)*cos(y)
6509: set samples 4,10; replot
6510: set samples 10,4; replot
6511:
6512: 3 splot_overview
6513: ?commands splot_overview
6514: ? splot_overview
6515: `splot` can display a surface as a collection of points, or by connecting
6516: those points. As with `plot`, the points may be read from a data file or
6517: result from evaluation of a function at specified intervals, see `set
6518: isosamples`. The surface may be approximated by connecting the points
6519: with straight line segments, see `set surface`, in which case the surface
6520: can be made opaque with `set hidden3d.` The orientation from which the 3d
6521: surface is viewed can be changed with `set view`.
6522:
6523: Additionally, for points in a grid format, `splot` can interpolate points
6524: having a common amplitude (see `set contour`) and can then connect those
6525: new points to display contour lines, either directly with straight-line
6526: segments or smoothed lines (see `set cntrparams`). Functions are already
6527: evaluated in a grid format, determined by `set isosamples` and `set samples`,
6528: while file data must either be in a grid format, as described in `data-file`,
6529: or be used to generate a grid (see `set dgrid3d`).
6530:
6531: Contour lines may be displayed either on the surface or projected onto the
6532: base. The base projections of the contour lines may be written to a
6533: file, and then read with `plot`, to take advantage of `plot`'s additional
6534: formatting capabilities.
6535: 2 test
6536: ?commands test
6537: ?test
6538: `test` creates a display of line and point styles and other useful things
6539: appropriate for the terminal you are using.
6540:
6541: Syntax:
6542: test
6543: 2 update
6544: ?commands update
6545: ?update
6546: This command writes the current values of the fit parameters into the given
6547: file, formatted as an initial-value file (as described in the `fit`section).
6548: This is useful for saving the current values for later use or for restarting
6549: a converged or stopped fit.
6550:
6551: Syntax:
6552: update <filename> {<filename>}
6553:
6554: If a second filename is supplied, the updated values are written to this
6555: file, and the original parameter file is left unmodified.
6556:
6557: Otherwise, if the file already exists, `gnuplot` first renames it by
6558: appending `.old` and then opens a new file. That is, "`update 'fred'`"
6559: behaves the same as "`!rename fred fred.old; update 'fred.old' 'fred'`".
6560: [On DOS and other systems that use the twelve-character "filename.ext"
6561: naming convention, "ext" will be "`old`" and "filename" will be related
6562: (hopefully recognizably) to the initial name. Renaming is not done at all
6563: on VMS systems, since they use file-versioning.]
6564:
6565: Please see `fit` for more information.
6566: 1 Graphical User Interfaces
6567: ?graphical user interfaces
6568: ?gui's
6569: Several graphical user interfaces have been written for `gnuplot` and one for
6570: win32 is included in this distribution. In addition, there is a Macintosh
6571: interface at
6572: ^<a href="ftp://ftp.ee.gatech.edu/pub/mac/gnuplot">
6573: ftp://ftp.ee.gatech.edu/pub/mac/gnuplot
6574: ^</a>
6575: and several X11 interfaces include three Tcl/Tk located at the usual Tcl/Tk
6576: repositories.
6577: 1 Bugs
6578: ?bugs
6579: Floating point exceptions (floating point number too large/small, divide by
6580: zero, etc.) may occasionally be generated by user defined functions. Some of
6581: the demos in particular may cause numbers to exceed the floating point range.
6582: Whether the system ignores such exceptions (in which case `gnuplot` labels
6583: the corresponding point as undefined) or aborts `gnuplot` depends on the
6584: compiler/runtime environment.
6585:
6586: The bessel functions do not work for complex arguments.
6587:
6588: The gamma function does not work for complex arguments.
6589:
6590: As of `gnuplot` version 3.7, all development has been done using ANSI C.
6591: With current operating system, compiler, and library releases, the OS
6592: specific bugs documented in release 3.5, now relegated to `old_bugs`, may
6593: no longer be relevant.
6594:
6595: Bugs reported since the current release may be located via the official
6596: distribution site:
6597: ftp://ftp.dartmouth.edu/pub/gnuplot
6598: http://www.cs.dartmouth.edu/gnuplot_info.html
6599:
6600: Please e-mail any bugs to bug-gnuplot@dartmouth.edu.
6601: 2 Old_bugs
6602: ?old_bugs
6603: ?os_bugs
6604: There is a bug in the stdio library for old Sun operating systems (SunOS
6605: Sys4-3.2). The "%g" format for 'printf' sometimes incorrectly prints numbers
6606: (e.g., 200000.0 as "2"). Thus, tic mark labels may be incorrect on a Sun4
6607: version of `gnuplot`. A work-around is to rescale the data or use the `set
6608: format` command to change the tic mark format to "%7.0f" or some other
6609: appropriate format. This appears to have been fixed in SunOS 4.0.
6610:
6611: Another bug: On a Sun3 under SunOS 4.0, and on Sun4's under Sys4-3.2 and
6612: SunOS 4.0, the 'sscanf' routine incorrectly parses "00 12" with the format
6613: "%f %f" and reads 0 and 0 instead of 0 and 12. This affects data input. If
6614: the data file contains x coordinates that are zero but are specified like
6615: '00', '000', etc, then you will read the wrong y values. Check any data
6616: files or upgrade the SunOS. It appears to have been fixed in SunOS 4.1.1.
6617:
6618: Suns appear to overflow when calculating exp(-x) for large x, so `gnuplot`
6619: gets an undefined result. One work-around is to make a user-defined function
6620: like e(x) = x<-500 ? 0 : exp(x). This affects plots of Gaussians (exp(-x*x))
6621: in particular, since x*x grows quite rapidly.
6622:
6623: Microsoft C 5.1 has a nasty bug associated with the %g format for 'printf'.
6624: When any of the formats "%.2g", "%.1g", "%.0g", "%.g" are used, 'printf' will
6625: incorrectly print numbers in the range 1e-4 to 1e-1. Numbers that should be
6626: printed in the %e format are incorrectly printed in the %f format, with the
6627: wrong number of zeros after the decimal point. To work around this problem,
6628: use the %e or %f formats explicitly.
6629:
6630: `gnuplot`, when compiled with Microsoft C, did not work correctly on two VGA
6631: displays that were tested. The CGA, EGA and VGA drivers should probably be
6632: rewritten to use the Microsoft C graphics library. `gnuplot` compiled with
6633: Borland C++ uses the Turbo C graphics drivers and does work correctly with
6634: VGA displays.
6635:
6636: VAX/VMS 4.7 C compiler release 2.4 also has a poorly implemented %g format
6637: for 'printf'. The numbers are printed numerically correct, but may not be in
6638: the requested format. The K&R second edition says that for the %g format, %e
6639: is used if the exponent is less than -4 or greater than or equal to the
6640: precision. The VAX uses %e format if the exponent is less than -1. The VAX
6641: appears to take no notice of the precision when deciding whether to use %e or
6642: %f for numbers less than 1. To work around this problem, use the %e or %f
6643: formats explicitly. From the VAX C 2.4 release notes: e,E,f,F,g,G Result
6644: will always contain a decimal point. For g and G, trailing zeros will not
6645: be removed from the result.
6646:
6647: VAX/VMS 5.2 C compiler release 3.0 has a slightly better implemented %g
6648: format than release 2.4, but not much. Trailing decimal points are now
6649: removed, but trailing zeros are still not removed from %g numbers in
6650: exponential format.
6651:
6652: The two preceding problems are actually in the libraries rather than in the
6653: compilers. Thus the problems will occur whether `gnuplot` is built using
6654: either the DEC compiler or some other one (e.g. the latest gcc).
6655:
6656: ULTRIX X11R3 has a bug that causes the X11 driver to display "every other"
6657: graph. The bug seems to be fixed in DEC's release of X11R4 so newer releases
6658: of ULTRIX don't seem to have the problem. Solutions for older sites include
6659: upgrading the X11 libraries (from DEC or direct from MIT) or defining
6660: ULTRIX_KLUDGE when compiling the x11.trm file. Note that the kludge is not
6661: an ideal fix, however.
6662:
6663: The constant HUGE was incorrectly defined in the NeXT OS 2.0 operating
6664: system. HUGE should be set to 1e38 in plot.h. This error has been corrected
6665: in the 2.1 version of NeXT OS.
6666:
6667: Some older models of HP plotters do not have a page eject command 'PG'. The
6668: current HPGL driver uses this command in HPGL_reset. This may need to be
6669: removed for these plotters. The current PCL5 driver uses HPGL/2 for text as
6670: well as graphics. This should be modified to use scalable PCL fonts.
6671:
6672: On the Atari version, it is not possible to send output directly to the
6673: printer (using `/dev/lp` as output file), since CRs are added to LFs in
6674: binary output. As a work-around, write the output to a file and copy it to
6675: the printer afterwards using a shell command.
6676:
6677: On AIX 4, the literal 'NaNq' in a datafile causes the special internal value
6678: 'not-a-number' to be stored, rather than setting an internal 'undefined'
6679: flag. A workaround is to use `set missing 'NaNq'`.
6680:
6681: There may be an up-to-date list of bugs since the release on the WWW page:
6682: http://www.cs.dartmouth.edu/gnuplot_info.html
6683:
6684: Please report any bugs to bug-gnuplot@dartmouth.edu.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gnuplot.doc CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gnuplot / docs