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