Annotation of OpenXM_contrib/gnuplot/docs/gnuplot.texi, Revision 1.1
1.1 ! maekawa 1: \input texinfo @c -*-texinfo-*-
! 2:
! 3: @c %**start of header
! 4: @setfilename gnuplot.info
! 5: @settitle Gnuplot: An Interactive Plotting Program
! 6: @setchapternewpage odd
! 7: @c %**end of header
! 8:
! 9: @c define the command and options indeces
! 10: @defindex cm
! 11: @defindex op
! 12: @defindex tm
! 13:
! 14: @direntry
! 15: * GNUPLOT: (gnuplot). An Interactive Plotting Program
! 16: @end direntry
! 17:
! 18: @ifnottex
! 19: @node Top, gnuplot, (dir), (dir)
! 20: @top Master Menu
! 21: @end ifnottex
! 22:
! 23: @example
! 24: GNUPLOT
! 25:
! 26: An Interactive Plotting Program
! 27: Thomas Williams & Colin Kelley
! 28: Version 3.7 organized by: David Denholm
! 29:
! 30: Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley
! 31:
! 32: Mailing list for comments: info-gnuplot@@dartmouth.edu
! 33: Mailing list for bug reports: bug-gnuplot@@dartmouth.edu
! 34:
! 35: This manual was prepared by Dick Crawford
! 36: 3 December 1998
! 37:
! 38:
! 39: Major contributors (alphabetic order):
! 40: @end example
! 41:
! 42: @c ^ <h2> An Interactive Plotting Program </h2><p>
! 43: @c ^ <h2> Thomas Williams & Colin Kelley</h2><p>
! 44: @c ^ <h2> Version 3.7 organized by: David Denholm </h2><p>
! 45: @c ^ <h2>Major contributors (alphabetic order):</h2>
! 46:
! 47: @itemize @bullet
! 48: @item
! 49: Hans-Bernhard Broeker
! 50: @item
! 51: John Campbell
! 52: @item
! 53: Robert Cunningham
! 54: @item
! 55: David Denholm
! 56: @item
! 57: Gershon Elber
! 58: @item
! 59: Roger Fearick
! 60: @item
! 61: Carsten Grammes
! 62: @item
! 63: Lucas Hart
! 64: @item
! 65: Lars Hecking
! 66: @item
! 67: Thomas Koenig
! 68: @item
! 69: David Kotz
! 70: @item
! 71: Ed Kubaitis
! 72: @item
! 73: Russell Lang
! 74: @item
! 75: Alexander Lehmann
! 76: @item
! 77: Alexander Mai
! 78: @item
! 79: Carsten Steger
! 80: @item
! 81: Tom Tkacik
! 82: @item
! 83: Jos Van der Woude
! 84: @item
! 85: James R. Van Zandt
! 86: @item
! 87: Alex Woo
! 88: @end itemize
! 89:
! 90: @c ^<h2> Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley<p>
! 91: @c ^ Mailing list for comments: info-gnuplot@@dartmouth.edu <p>
! 92: @c ^ Mailing list for bug reports: bug-gnuplot@@dartmouth.edu<p>
! 93: @c ^</h2><p>
! 94: @c ^<h3> This manual was prepared by Dick Crawford</h3><p>
! 95: @c ^<h3> 3 December 1998</h3><p>
! 96: @c ^<hr>
! 97:
! 98: @menu
! 99: * gnuplot::
! 100: * Commands::
! 101: * Graphical_User_Interfaces::
! 102: * Bugs::
! 103: * Concept_Index::
! 104: * Command_Index::
! 105: * Options_Index::
! 106: * Function_Index::
! 107: * Terminal_Index::
! 108: @end menu
! 109:
! 110: @node gnuplot, Commands, Top, Top
! 111: @chapter gnuplot
! 112:
! 113:
! 114: @menu
! 115: * Copyright::
! 116: * Introduction::
! 117: * Seeking-assistance::
! 118: * What's_New_in_version_3.7::
! 119: * Batch/Interactive_Operation::
! 120: * Command-line-editing::
! 121: * Comments::
! 122: * Coordinates::
! 123: * Environment::
! 124: * Expressions::
! 125: * Glossary::
! 126: * Plotting::
! 127: * Start-up::
! 128: * Substitution::
! 129: * Syntax::
! 130: * Time/Date_data::
! 131: @end menu
! 132:
! 133: @node Copyright, Introduction, gnuplot, gnuplot
! 134: @section Copyright
! 135:
! 136: @cindex copyright
! 137:
! 138: @cindex license
! 139:
! 140: @example
! 141: Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley
! 142:
! 143: @end example
! 144:
! 145: Permission to use, copy, and distribute this software and its
! 146: documentation for any purpose with or without fee is hereby granted,
! 147: provided that the above copyright notice appear in all copies and
! 148: that both that copyright notice and this permission notice appear
! 149: in supporting documentation.
! 150:
! 151: Permission to modify the software is granted, but not the right to
! 152: distribute the complete modified source code. Modifications are to
! 153: be distributed as patches to the released version. Permission to
! 154: distribute binaries produced by compiling modified sources is granted,
! 155: provided you
! 156: @example
! 157: 1. distribute the corresponding source modifications from the
! 158: released version in the form of a patch file along with the binaries,
! 159: 2. add special version identification to distinguish your version
! 160: in addition to the base release version number,
! 161: 3. provide your name and address as the primary contact for the
! 162: support of your modified version, and
! 163: 4. retain our contact information in regard to use of the base
! 164: software.
! 165: @end example
! 166:
! 167: Permission to distribute the released version of the source code along
! 168: with corresponding source modifications in the form of a patch file is
! 169: granted with same provisions 2 through 4 for binary distributions.
! 170:
! 171: This software is provided "as is" without express or implied warranty
! 172: to the extent permitted by applicable law.
! 173:
! 174:
! 175: @example
! 176: AUTHORS
! 177:
! 178: @end example
! 179:
! 180: @example
! 181: Original Software:
! 182: Thomas Williams, Colin Kelley.
! 183:
! 184: @end example
! 185:
! 186: @example
! 187: Gnuplot 2.0 additions:
! 188: Russell Lang, Dave Kotz, John Campbell.
! 189:
! 190: @end example
! 191:
! 192: @example
! 193: Gnuplot 3.0 additions:
! 194: Gershon Elber and many others.
! 195:
! 196: @end example
! 197:
! 198: @node Introduction, Seeking-assistance, Copyright, gnuplot
! 199: @section Introduction
! 200:
! 201: @cindex introduction
! 202:
! 203: @c ?
! 204: `gnuplot` is a command-driven interactive function and data plotting program.
! 205: It is case sensitive (commands and function names written in lowercase are
! 206: not the same as those written in CAPS). All command names may be abbreviated
! 207: as long as the abbreviation is not ambiguous. Any number of commands may
! 208: appear on a line (with the exception that @ref{load} or @ref{call} must be the final
! 209: command), separated by semicolons (;). Strings are indicated with quotes.
! 210: They may be either single or double quotation marks, e.g.,
! 211:
! 212: @example
! 213: load "filename"
! 214: cd 'dir'
! 215:
! 216: @end example
! 217:
! 218: although there are some subtle differences (see `syntax` for more details).
! 219:
! 220: Any command-line arguments are assumed to be names of files containing
! 221: `gnuplot` commands, with the exception of standard X11 arguments, which are
! 222: processed first. Each file is loaded with the @ref{load} command, in the order
! 223: specified. `gnuplot` exits after the last file is processed. When no load
! 224: files are named, `gnuplot` enters into an interactive mode. The special
! 225: filename "-" is used to denote standard input. See "help batch/interactive"
! 226: for more details.
! 227:
! 228: Many `gnuplot` commands have multiple options. These options must appear in
! 229: the proper order, although unwanted ones may be omitted in most cases. Thus
! 230: if the entire command is "command a b c", then "command a c" will probably
! 231: work, but "command c a" will fail.
! 232:
! 233: Commands may extend over several input lines by ending each line but the last
! 234: with a backslash (\). The backslash must be the _last_ character on each
! 235: line. The effect is as if the backslash and newline were not there. That
! 236: is, no white space is implied, nor is a comment terminated. Therefore,
! 237: commenting out a continued line comments out the entire command (see
! 238: `comment`). But note that if an error occurs somewhere on a multi-line
! 239: command, the parser may not be able to locate precisely where the error is
! 240: and in that case will not necessarily point to the correct line.
! 241:
! 242: In this document, curly braces (@{@}) denote optional arguments and a vertical
! 243: bar (|) separates mutually exclusive choices. `gnuplot` keywords or @ref{help}
! 244: topics are indicated by backquotes or `boldface` (where available). Angle
! 245: brackets (<>) are used to mark replaceable tokens. In many cases, a default
! 246: value of the token will be taken for optional arguments if the token is
! 247: omitted, but these cases are not always denoted with braces around the angle
! 248: brackets.
! 249:
! 250: For on-line help on any topic, type @ref{help} followed by the name of the topic
! 251: or just @ref{help} or `?` to get a menu of available topics.
! 252:
! 253: The new `gnuplot` user should begin by reading about `plotting` (if on-line,
! 254: type `help plotting`).
! 255: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/simple.html,Simple Plots Demo }
! 256:
! 257: @node Seeking-assistance, What's_New_in_version_3.7, Introduction, gnuplot
! 258: @section Seeking-assistance
! 259:
! 260: @cindex seeking-assistance
! 261:
! 262: There is a mailing list for `gnuplot` users. Note, however, that the
! 263: newsgroup
! 264: @example
! 265: comp.graphics.apps.gnuplot
! 266: @end example
! 267:
! 268: is identical to the mailing list (they both carry the same set of messages).
! 269: We prefer that you read the messages through the newsgroup rather than
! 270: subscribing to the mailing list. Administrative requests should be sent to
! 271: @example
! 272: majordomo@@dartmouth.edu
! 273: @end example
! 274:
! 275: Send a message with the body (not the subject) consisting of the single word
! 276: "help" (without the quotes) for more details.
! 277:
! 278: The address for mailing to list members is:
! 279: @example
! 280: info-gnuplot@@dartmouth.edu
! 281:
! 282: @end example
! 283:
! 284: Bug reports and code contributions should be mailed to:
! 285: @example
! 286: bug-gnuplot@@dartmouth.edu
! 287:
! 288: @end example
! 289:
! 290: The list of those interested in beta-test versions is:
! 291: @example
! 292: info-gnuplot-beta@@dartmouth.edu
! 293:
! 294: @end example
! 295:
! 296: There is also a World Wide Web page with up-to-date information, including
! 297: known bugs:
! 298: @uref{http://www.cs.dartmouth.edu/gnuplot_info.html,http://www.cs.dartmouth.edu/gnuplot_info.html
! 299: }
! 300:
! 301: Before seeking help, please check the
! 302: @uref{http://www.ucc.ie/gnuplot/gnuplot-faq.html,FAQ (Frequently Asked Questions) list.
! 303: }
! 304: If you do not have a copy of the FAQ, you may request a copy by email from
! 305: the Majordomo address above, ftp a copy from
! 306: @example
! 307: ftp://ftp.ucc.ie/pub/gnuplot/faq,
! 308: ftp://ftp.gnuplot.vt.edu/pub/gnuplot/faq,
! 309: @end example
! 310:
! 311: or see the WWW `gnuplot` page.
! 312:
! 313: When posting a question, please include full details of the version of
! 314: `gnuplot`, the machine, and operating system you are using. A _small_ script
! 315: demonstrating the problem may be useful. Function plots are preferable to
! 316: datafile plots. If email-ing to info-gnuplot, please state whether or not
! 317: you are subscribed to the list, so that users who use news will know to email
! 318: a reply to you. There is a form for such postings on the WWW site.
! 319:
! 320: @node What's_New_in_version_3.7, Batch/Interactive_Operation, Seeking-assistance, gnuplot
! 321: @section What's New in version 3.7
! 322:
! 323: @cindex new-features
! 324:
! 325: Gnuplot version 3.7 contains many new features. This section gives a partial
! 326: list and links to the new items in no particular order.
! 327:
! 328: 1. `fit f(x) 'file' via` uses the Marquardt-Levenberg method to fit data.
! 329: (This is only slightly different from the `gnufit` patch available for 3.5.)
! 330:
! 331: 2. Greatly expanded @ref{using} command. See @ref{using}.
! 332:
! 333: 3. @ref{timefmt} allows for the use of dates as input and output for time
! 334: series plots. See `Time/Date data` and
! 335: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/timedat.html,timedat.dem.
! 336: }
! 337:
! 338: 4. Multiline labels and font selection in some drivers.
! 339:
! 340: 5. Minor (unlabeled) tics. See @ref{mxtics}.
! 341:
! 342: 6. @ref{key} options for moving the key box in the page (and even outside of the
! 343: plot), putting a title on it and a box around it, and more. See @ref{key}.
! 344:
! 345: 7. Multiplots on a single logical page with @ref{multiplot}.
! 346:
! 347: 8. Enhanced `postscript` driver with super/subscripts and font changes.
! 348: (This was a separate driver (`enhpost`) that was available as a patch for
! 349: 3.5.)
! 350:
! 351: 9. Second axes: use the top and right axes independently of the bottom and
! 352: left, both for plotting and labels. See @ref{plot}.
! 353:
! 354: 10. Special datafile names `'-'` and `""`. See @ref{special-filenames}.
! 355:
! 356: 11. Additional coordinate systems for labels and arrows. See `coordinates`.
! 357:
! 358: 12. @ref{size} can try to plot with a specified aspect ratio.
! 359:
! 360: 13. @ref{missing} now treats missing data correctly.
! 361:
! 362: 14. The @ref{call} command: @ref{load} with arguments.
! 363:
! 364: 15. More flexible `range` commands with `reverse` and `writeback` keywords.
! 365:
! 366: 16. @ref{encoding} for multi-lingual encoding.
! 367:
! 368: 17. New `x11` driver with persistent and multiple windows.
! 369:
! 370: 18. New plotting styles: @ref{xerrorbars}, @ref{histeps}, @ref{financebars} and more.
! 371: See @ref{style}.
! 372:
! 373: 19. New tic label formats, including `"%l %L"` which uses the mantissa and
! 374: exponents to a given base for labels. See `set format`.
! 375:
! 376: 20. New drivers, including `cgm` for inclusion into MS-Office applications
! 377: and `gif` for serving plots to the WEB.
! 378:
! 379: 21. Smoothing and spline-fitting options for @ref{plot}. See @ref{smooth}.
! 380:
! 381: 22. @ref{margin} and @ref{origin} give much better control over where a
! 382: graph appears on the page.
! 383:
! 384: 23. @ref{border} now controls each border individually.
! 385:
! 386: 24. The new commands @ref{if} and @ref{reread} allow command loops.
! 387:
! 388: 25. Point styles and sizes, line types and widths can be specified on the
! 389: @ref{plot} command. Line types and widths can also be specified for grids,
! 390: borders, tics and arrows. See @ref{with}. Furthermore these types may be
! 391: combined and stored for further use. See @ref{linestyle}.
! 392:
! 393: 26. Text (labels, tic labels, and the time stamp) can be written vertically
! 394: by those terminals capable of doing so.
! 395:
! 396: @node Batch/Interactive_Operation, Command-line-editing, What's_New_in_version_3.7, gnuplot
! 397: @section Batch/Interactive Operation
! 398:
! 399: @cindex batch/interactive
! 400:
! 401: `gnuplot` may be executed in either batch or interactive modes, and the two
! 402: may even be mixed together on many systems.
! 403:
! 404: Any command-line arguments are assumed to be names of files containing
! 405: `gnuplot` commands (with the exception of standard X11 arguments, which are
! 406: processed first). Each file is loaded with the @ref{load} command, in the order
! 407: specified. `gnuplot` exits after the last file is processed. When no load
! 408: files are named, `gnuplot` enters into an interactive mode. The special
! 409: filename "-" is used to denote standard input.
! 410:
! 411: Both the @ref{exit} and @ref{quit} commands terminate the current command file and
! 412: @ref{load} the next one, until all have been processed.
! 413:
! 414: Examples:
! 415:
! 416: To launch an interactive session:
! 417: @example
! 418: gnuplot
! 419:
! 420: @end example
! 421:
! 422: To launch a batch session using two command files "input1" and "input2":
! 423: @example
! 424: gnuplot input1 input2
! 425:
! 426: @end example
! 427:
! 428: To launch an interactive session after an initialization file "header" and
! 429: followed by another command file "trailer":
! 430: @example
! 431: gnuplot header - trailer
! 432:
! 433: @end example
! 434:
! 435: @node Command-line-editing, Comments, Batch/Interactive_Operation, gnuplot
! 436: @section Command-line-editing
! 437:
! 438: @cindex line-editing
! 439:
! 440: @cindex editing
! 441:
! 442: @cindex history
! 443:
! 444: @cindex command-line-editing
! 445:
! 446: Command-line editing is supported by the Unix, Atari, VMS, MS-DOS and OS/2
! 447: versions of `gnuplot`. Also, a history mechanism allows previous commands to
! 448: be edited and re-executed. After the command line has been edited, a newline
! 449: or carriage return will enter the entire line without regard to where the
! 450: cursor is positioned.
! 451:
! 452: (The readline function in `gnuplot` is not the same as the readline used in
! 453: GNU Bash and GNU Emacs. If the GNU version is desired, it may be selected
! 454: instead of the `gnuplot` version at compile time.)
! 455:
! 456:
! 457: The editing commands are as follows:
! 458:
! 459:
! 460: @example
! 461: `Line-editing`:
! 462:
! 463: @end example
! 464:
! 465: @example
! 466: ^B moves back a single character.
! 467: ^F moves forward a single character.
! 468: ^A moves to the beginning of the line.
! 469: ^E moves to the end of the line.
! 470: ^H and DEL delete the previous character.
! 471: ^D deletes the current character.
! 472: ^K deletes from current position to the end of line.
! 473: ^L,^R redraws line in case it gets trashed.
! 474: ^U deletes the entire line.
! 475: ^W deletes the last word.
! 476:
! 477: @end example
! 478:
! 479: @example
! 480: `History`:
! 481:
! 482: @end example
! 483:
! 484: @example
! 485: ^P moves back through history.
! 486: ^N moves forward through history.
! 487:
! 488: @end example
! 489:
! 490:
! 491: On the IBM PC, the use of a TSR program such as DOSEDIT or CED may be desired
! 492: for line editing. The default makefile assumes that this is the case; by
! 493: default `gnuplot` will be compiled with no line-editing capability. If you
! 494: want to use `gnuplot`'s line editing, set READLINE in the makefile and add
! 495: readline.obj to the link file. The following arrow keys may be used on the
! 496: IBM PC and Atari versions if readline is used:
! 497:
! 498:
! 499: @example
! 500: Left Arrow - same as ^B.
! 501: Right Arrow - same as ^F.
! 502: Ctrl Left Arrow - same as ^A.
! 503: Ctrl Right Arrow - same as ^E.
! 504: Up Arrow - same as ^P.
! 505: Down Arrow - same as ^N.
! 506:
! 507: @end example
! 508:
! 509:
! 510: The Atari version of readline defines some additional key aliases:
! 511:
! 512:
! 513: @example
! 514: Undo - same as ^L.
! 515: Home - same as ^A.
! 516: Ctrl Home - same as ^E.
! 517: Esc - same as ^U.
! 518: Help - @ref{help} plus return.
! 519: Ctrl Help - `help `.
! 520:
! 521: @end example
! 522:
! 523:
! 524: @node Comments, Coordinates, Command-line-editing, gnuplot
! 525: @section Comments
! 526:
! 527: @cindex comments
! 528:
! 529: Comments are supported as follows: a `#` may appear in most places in a line
! 530: and `gnuplot` will ignore the rest of the line. It will not have this effect
! 531: inside quotes, inside numbers (including complex numbers), inside command
! 532: substitutions, etc. In short, it works anywhere it makes sense to work.
! 533:
! 534: @node Coordinates, Environment, Comments, gnuplot
! 535: @section Coordinates
! 536:
! 537: @cindex coordinates
! 538:
! 539: The commands @ref{arrow}, @ref{key}, and @ref{label} allow you to draw
! 540: something at an arbitrary position on the graph. This position is specified
! 541: by the syntax:
! 542:
! 543: @example
! 544: @{<system>@} <x>, @{<system>@} <y> @{,@{<system>@} <z>@}
! 545:
! 546: @end example
! 547:
! 548: Each <system> can either be `first`, `second`, `graph` or `screen`.
! 549:
! 550: `first` places the x, y, or z coordinate in the system defined by the left
! 551: and bottom axes; `second` places it in the system defined by the second axes
! 552: (top and right); `graph` specifies the area within the axes---0,0 is bottom
! 553: left and 1,1 is top right (for splot, 0,0,0 is bottom left of plotting area;
! 554: use negative z to get to the base---see @ref{ticslevel}); and `screen`
! 555: specifies the screen area (the entire area---not just the portion selected by
! 556: @ref{size}), with 0,0 at bottom left and 1,1 at top right.
! 557:
! 558: If the coordinate system for x is not specified, `first` is used. If the
! 559: system for y is not specified, the one used for x is adopted.
! 560:
! 561: If one (or more) axis is timeseries, the appropriate coordinate should
! 562: be given as a quoted time string according to the @ref{timefmt} format string.
! 563: See @ref{xdata} and @ref{timefmt}. `gnuplot` will also accept an integer
! 564: expression, which will be interpreted as seconds from 1 January 2000.
! 565:
! 566: @node Environment, Expressions, Coordinates, gnuplot
! 567: @section Environment
! 568:
! 569: @cindex environment
! 570:
! 571: A number of shell environment variables are understood by `gnuplot`. None of
! 572: these are required, but may be useful.
! 573:
! 574: If GNUTERM is defined, it is used as the name of the terminal type to be
! 575: used. This overrides any terminal type sensed by `gnuplot` on start-up, but
! 576: is itself overridden by the .gnuplot (or equivalent) start-up file (see
! 577: `start-up`) and, of course, by later explicit changes.
! 578:
! 579: On Unix, AmigaOS, AtariTOS, MS-DOS and OS/2, GNUHELP may be defined to be the
! 580: pathname of the HELP file (gnuplot.gih).
! 581:
! 582: On VMS, the logical name GNUPLOT$HELP should be defined as the name of the
! 583: help library for `gnuplot`. The `gnuplot` help can be put inside any system
! 584: help library, allowing access to help from both within and outside `gnuplot`
! 585: if desired.
! 586:
! 587: On Unix, HOME is used as the name of a directory to search for a .gnuplot
! 588: file if none is found in the current directory. On AmigaOS, AtariTOS,
! 589: MS-DOS and OS/2, gnuplot is used. On VMS, SYS$LOGIN: is used. See `help
! 590: start-up`.
! 591:
! 592: On Unix, PAGER is used as an output filter for help messages.
! 593:
! 594: On Unix, AtariTOS and AmigaOS, SHELL is used for the @ref{shell} command. On
! 595: MS-DOS and OS/2, COMSPEC is used for the @ref{shell} command.
! 596:
! 597: On MS-DOS, if the BGI or Watcom interface is used, PCTRM is used to tell
! 598: the maximum resolution supported by your monitor by setting it to
! 599: S<max. horizontal resolution>. E.g. if your monitor's maximum resolution is
! 600: 800x600, then use:
! 601: @example
! 602: set PCTRM=S800
! 603: @end example
! 604:
! 605: If PCTRM is not set, standard VGA is used.
! 606:
! 607: FIT_SCRIPT may be used to specify a `gnuplot` command to be executed when a
! 608: fit is interrupted---see `fit`. FIT_LOG specifies the filename of the
! 609: logfile maintained by fit.
! 610:
! 611: @node Expressions, Glossary, Environment, gnuplot
! 612: @section Expressions
! 613:
! 614: @cindex expressions
! 615:
! 616: In general, any mathematical expression accepted by C, FORTRAN, Pascal, or
! 617: BASIC is valid. The precedence of these operators is determined by the
! 618: specifications of the C programming language. White space (spaces and tabs)
! 619: is ignored inside expressions.
! 620:
! 621: Complex constants are expressed as @{<real>,<imag>@}, where <real> and <imag>
! 622: must be numerical constants. For example, @{3,2@} represents 3 + 2i; @{0,1@}
! 623: represents 'i' itself. The curly braces are explicitly required here.
! 624:
! 625: Note that gnuplot uses both "real" and "integer" arithmetic, like FORTRAN and
! 626: C. Integers are entered as "1", "-10", etc; reals as "1.0", "-10.0", "1e1",
! 627: 3.5e-1, etc. The most important difference between the two forms is in
! 628: division: division of integers truncates: 5/2 = 2; division of reals does
! 629: not: 5.0/2.0 = 2.5. In mixed expressions, integers are "promoted" to reals
! 630: before evaluation: 5/2e0 = 2.5. The result of division of a negative integer
! 631: by a positive one may vary among compilers. Try a test like "print -5/2" to
! 632: determine if your system chooses -2 or -3 as the answer.
! 633:
! 634: The integer expression "1/0" may be used to generate an "undefined" flag,
! 635: which causes a point to ignored; the `ternary` operator gives an example.
! 636:
! 637: The real and imaginary parts of complex expressions are always real, whatever
! 638: the form in which they are entered: in @{3,2@} the "3" and "2" are reals, not
! 639: integers.
! 640:
! 641: @menu
! 642: * Functions::
! 643: * Operators::
! 644: * User-defined::
! 645: @end menu
! 646:
! 647: @node Functions, Operators, Expressions, Expressions
! 648: @subsection Functions
! 649:
! 650: @c ?expressions functions
! 651: @cindex functions
! 652: @opindex functions
! 653:
! 654:
! 655: The functions in `gnuplot` are the same as the corresponding functions in
! 656: the Unix math library, except that all functions accept integer, real, and
! 657: complex arguments, unless otherwise noted.
! 658:
! 659: For those functions that accept or return angles that may be given in either
! 660: degrees or radians (sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
! 661: atan2(x) and arg(z)), the unit may be selected by @ref{angles}, which
! 662: defaults to radians.
! 663:
! 664:
! 665:
! 666: @menu
! 667: * abs::
! 668: * acos::
! 669: * acosh::
! 670: * arg::
! 671: * asin::
! 672: * asinh::
! 673: * atan::
! 674: * atan2::
! 675: * atanh::
! 676: * besj0::
! 677: * besj1::
! 678: * besy0::
! 679: * besy1::
! 680: * ceil::
! 681: * cos::
! 682: * cosh::
! 683: * erf::
! 684: * erfc::
! 685: * exp::
! 686: * floor::
! 687: * gamma::
! 688: * ibeta::
! 689: * inverf::
! 690: * igamma::
! 691: * imag::
! 692: * invnorm::
! 693: * int::
! 694: * lgamma::
! 695: * log::
! 696: * log10::
! 697: * norm::
! 698: * rand::
! 699: * real::
! 700: * sgn::
! 701: * sin::
! 702: * sinh::
! 703: * sqrt::
! 704: * tan::
! 705: * tanh::
! 706: * column::
! 707: * tm_hour::
! 708: * tm_mday::
! 709: * tm_min::
! 710: * tm_mon::
! 711: * tm_sec::
! 712: * tm_wday::
! 713: * tm_yday::
! 714: * tm_year::
! 715: * valid::
! 716: @end menu
! 717:
! 718: @node abs, acos, Functions, Functions
! 719: @subsubsection abs
! 720:
! 721: @c ?expressions functions abs
! 722: @c ?functions abs
! 723: @cindex abs
! 724: @findex abs
! 725:
! 726:
! 727: The `abs(x)` function returns the absolute value of its argument. The
! 728: returned value is of the same type as the argument.
! 729:
! 730: For complex arguments, abs(x) is defined as the length of x in the complex
! 731: plane [i.e., sqrt(real(x)**2 + imag(x)**2) ].
! 732:
! 733: @node acos, acosh, abs, Functions
! 734: @subsubsection acos
! 735:
! 736: @c ?expressions functions acos
! 737: @c ?functions acos
! 738: @cindex acos
! 739: @findex acos
! 740:
! 741:
! 742: The `acos(x)` function returns the arc cosine (inverse cosine) of its
! 743: argument. `acos` returns its argument in radians or degrees, as selected by
! 744: @ref{angles}.
! 745:
! 746: @node acosh, arg, acos, Functions
! 747: @subsubsection acosh
! 748:
! 749: @c ?expressions functions acosh
! 750: @c ?functions acosh
! 751: @cindex acosh
! 752: @findex acosh
! 753:
! 754:
! 755: The `acosh(x)` function returns the inverse hyperbolic cosine of its argument
! 756: in radians.
! 757:
! 758: @node arg, asin, acosh, Functions
! 759: @subsubsection arg
! 760:
! 761: @c ?expressions functions arg
! 762: @c ?functions arg
! 763: @cindex arg
! 764: @findex arg
! 765:
! 766:
! 767: The `arg(x)` function returns the phase of a complex number in radians or
! 768: degrees, as selected by @ref{angles}.
! 769:
! 770: @node asin, asinh, arg, Functions
! 771: @subsubsection asin
! 772:
! 773: @c ?expressions functions asin
! 774: @c ?functions asin
! 775: @cindex asin
! 776: @findex asin
! 777:
! 778:
! 779: The `asin(x)` function returns the arc sin (inverse sin) of its argument.
! 780: `asin` returns its argument in radians or degrees, as selected by @ref{angles}.
! 781:
! 782: @node asinh, atan, asin, Functions
! 783: @subsubsection asinh
! 784:
! 785: @c ?expressions functions asinh
! 786: @c ?functions asinh
! 787: @cindex asinh
! 788: @findex asinh
! 789:
! 790:
! 791: The `asinh(x)` function returns the inverse hyperbolic sin of its argument in
! 792: radians.
! 793:
! 794: @node atan, atan2, asinh, Functions
! 795: @subsubsection atan
! 796:
! 797: @c ?expressions functions atan
! 798: @c ?functions atan
! 799: @cindex atan
! 800: @findex atan
! 801:
! 802:
! 803: The `atan(x)` function returns the arc tangent (inverse tangent) of its
! 804: argument. `atan` returns its argument in radians or degrees, as selected by
! 805: @ref{angles}.
! 806:
! 807: @node atan2, atanh, atan, Functions
! 808: @subsubsection atan2
! 809:
! 810: @c ?expressions functions atan2
! 811: @c ?functions atan2
! 812: @cindex atan2
! 813: @findex atan2
! 814:
! 815:
! 816: The `atan2(y,x)` function returns the arc tangent (inverse tangent) of the
! 817: ratio of the real parts of its arguments. @ref{atan2} returns its argument in
! 818: radians or degrees, as selected by @ref{angles}, in the correct quadrant.
! 819:
! 820: @node atanh, besj0, atan2, Functions
! 821: @subsubsection atanh
! 822:
! 823: @c ?expressions functions atanh
! 824: @c ?functions atanh
! 825: @cindex atanh
! 826: @findex atanh
! 827:
! 828:
! 829: The `atanh(x)` function returns the inverse hyperbolic tangent of its
! 830: argument in radians.
! 831:
! 832: @node besj0, besj1, atanh, Functions
! 833: @subsubsection besj0
! 834:
! 835: @c ?expressions functions besj0
! 836: @c ?functions besj0
! 837: @cindex besj0
! 838: @findex besj0
! 839:
! 840:
! 841: The `besj0(x)` function returns the j0th Bessel function of its argument.
! 842: @ref{besj0} expects its argument to be in radians.
! 843:
! 844: @node besj1, besy0, besj0, Functions
! 845: @subsubsection besj1
! 846:
! 847: @c ?expressions functions besj1
! 848: @c ?functions besj1
! 849: @cindex besj1
! 850: @findex besj1
! 851:
! 852:
! 853: The `besj1(x)` function returns the j1st Bessel function of its argument.
! 854: @ref{besj1} expects its argument to be in radians.
! 855:
! 856: @node besy0, besy1, besj1, Functions
! 857: @subsubsection besy0
! 858:
! 859: @c ?expressions functions besy0
! 860: @c ?functions besy0
! 861: @cindex besy0
! 862: @findex besy0
! 863:
! 864:
! 865: The @ref{besy0} function returns the y0th Bessel function of its argument.
! 866: @ref{besy0} expects its argument to be in radians.
! 867:
! 868: @node besy1, ceil, besy0, Functions
! 869: @subsubsection besy1
! 870:
! 871: @c ?expressions functions besy1
! 872: @c ?functions besy1
! 873: @cindex besy1
! 874: @findex besy1
! 875:
! 876:
! 877: The `besy1(x)` function returns the y1st Bessel function of its argument.
! 878: @ref{besy1} expects its argument to be in radians.
! 879:
! 880: @node ceil, cos, besy1, Functions
! 881: @subsubsection ceil
! 882:
! 883: @c ?expressions functions ceil
! 884: @c ?functions ceil
! 885: @cindex ceil
! 886: @findex ceil
! 887:
! 888:
! 889: The `ceil(x)` function returns the smallest integer that is not less than its
! 890: argument. For complex numbers, @ref{ceil} returns the smallest integer not less
! 891: than the real part of its argument.
! 892:
! 893: @node cos, cosh, ceil, Functions
! 894: @subsubsection cos
! 895:
! 896: @c ?expressions functions cos
! 897: @c ?functions cos
! 898: @cindex cos
! 899: @findex cos
! 900:
! 901:
! 902: The `cos(x)` function returns the cosine of its argument. `cos` accepts its
! 903: argument in radians or degrees, as selected by @ref{angles}.
! 904:
! 905: @node cosh, erf, cos, Functions
! 906: @subsubsection cosh
! 907:
! 908: @c ?expressions functions cosh
! 909: @c ?functions cosh
! 910: @cindex cosh
! 911: @findex cosh
! 912:
! 913:
! 914: The `cosh(x)` function returns the hyperbolic cosine of its argument. @ref{cosh}
! 915: expects its argument to be in radians.
! 916:
! 917: @node erf, erfc, cosh, Functions
! 918: @subsubsection erf
! 919:
! 920: @c ?expressions functions erf
! 921: @c ?functions erf
! 922: @cindex erf
! 923: @findex erf
! 924:
! 925:
! 926: The `erf(x)` function returns the error function of the real part of its
! 927: argument. If the argument is a complex value, the imaginary component is
! 928: ignored.
! 929:
! 930: @node erfc, exp, erf, Functions
! 931: @subsubsection erfc
! 932:
! 933: @c ?expressions functions erfc
! 934: @c ?functions erfc
! 935: @cindex erfc
! 936: @findex erfc
! 937:
! 938:
! 939: The `erfc(x)` function returns 1.0 - the error function of the real part of
! 940: its argument. If the argument is a complex value, the imaginary component is
! 941: ignored.
! 942:
! 943: @node exp, floor, erfc, Functions
! 944: @subsubsection exp
! 945:
! 946: @c ?expressions functions exp
! 947: @c ?functions exp
! 948: @cindex exp
! 949: @findex exp
! 950:
! 951:
! 952: The `exp(x)` function returns the exponential function of its argument (`e`
! 953: raised to the power of its argument). On some implementations (notably
! 954: suns), exp(-x) returns undefined for very large x. A user-defined function
! 955: like safe(x) = x<-100 ? 0 : exp(x) might prove useful in these cases.
! 956:
! 957: @node floor, gamma, exp, Functions
! 958: @subsubsection floor
! 959:
! 960: @c ?expressions functions floor
! 961: @c ?functions floor
! 962: @cindex floor
! 963: @findex floor
! 964:
! 965:
! 966: The `floor(x)` function returns the largest integer not greater than its
! 967: argument. For complex numbers, @ref{floor} returns the largest integer not
! 968: greater than the real part of its argument.
! 969:
! 970: @node gamma, ibeta, floor, Functions
! 971: @subsubsection gamma
! 972:
! 973: @c ?expressions functions gamma
! 974: @c ?functions gamma
! 975: @cindex gamma
! 976: @findex gamma
! 977:
! 978:
! 979: The `gamma(x)` function returns the gamma function of the real part of its
! 980: argument. For integer n, gamma(n+1) = n!. If the argument is a complex
! 981: value, the imaginary component is ignored.
! 982:
! 983: @node ibeta, inverf, gamma, Functions
! 984: @subsubsection ibeta
! 985:
! 986: @c ?expressions functions ibeta
! 987: @c ?functions ibeta
! 988: @cindex ibeta
! 989: @findex ibeta
! 990:
! 991:
! 992: The `ibeta(p,q,x)` function returns the incomplete beta function of the real
! 993: parts of its arguments. p, q > 0 and x in [0:1]. If the arguments are
! 994: complex, the imaginary components are ignored.
! 995:
! 996: @node inverf, igamma, ibeta, Functions
! 997: @subsubsection inverf
! 998:
! 999: @c ?expressions functions inverf
! 1000: @c ?functions inverf
! 1001: @cindex inverf
! 1002: @findex inverf
! 1003:
! 1004:
! 1005: The `inverf(x)` function returns the inverse error function of the real part
! 1006: of its argument.
! 1007:
! 1008: @node igamma, imag, inverf, Functions
! 1009: @subsubsection igamma
! 1010:
! 1011: @c ?expressions functions igamma
! 1012: @c ?functions igamma
! 1013: @cindex igamma
! 1014: @findex igamma
! 1015:
! 1016:
! 1017: The `igamma(a,x)` function returns the incomplete gamma function of the real
! 1018: parts of its arguments. a > 0 and x >= 0. If the arguments are complex,
! 1019: the imaginary components are ignored.
! 1020:
! 1021: @node imag, invnorm, igamma, Functions
! 1022: @subsubsection imag
! 1023:
! 1024: @c ?expressions functions imag
! 1025: @c ?functions imag
! 1026: @cindex imag
! 1027: @findex imag
! 1028:
! 1029:
! 1030: The `imag(x)` function returns the imaginary part of its argument as a real
! 1031: number.
! 1032:
! 1033: @node invnorm, int, imag, Functions
! 1034: @subsubsection invnorm
! 1035:
! 1036: @c ?expressions functions invnorm
! 1037: @c ?functions invnorm
! 1038: @cindex invnorm
! 1039: @findex invnorm
! 1040:
! 1041:
! 1042: The `invnorm(x)` function returns the inverse normal distribution function of
! 1043: the real part of its argument.
! 1044:
! 1045: @node int, lgamma, invnorm, Functions
! 1046: @subsubsection int
! 1047:
! 1048: @c ?expressions functions int
! 1049: @c ?functions int
! 1050: @cindex int
! 1051: @findex int
! 1052:
! 1053:
! 1054: The `int(x)` function returns the integer part of its argument, truncated
! 1055: toward zero.
! 1056:
! 1057: @node lgamma, log, int, Functions
! 1058: @subsubsection lgamma
! 1059:
! 1060: @c ?expressions functions lgamma
! 1061: @c ?functions lgamma
! 1062: @cindex lgamma
! 1063: @findex lgamma
! 1064:
! 1065:
! 1066: The `lgamma(x)` function returns the natural logarithm of the gamma function
! 1067: of the real part of its argument. If the argument is a complex value, the
! 1068: imaginary component is ignored.
! 1069:
! 1070: @node log, log10, lgamma, Functions
! 1071: @subsubsection log
! 1072:
! 1073: @c ?expressions functions log
! 1074: @c ?functions log
! 1075: @cindex log
! 1076: @findex log
! 1077:
! 1078:
! 1079: The `log(x)` function returns the natural logarithm (base `e`) of its
! 1080: argument.
! 1081:
! 1082: @node log10, norm, log, Functions
! 1083: @subsubsection log10
! 1084:
! 1085: @c ?expressions functions log10
! 1086: @c ?functions log10
! 1087: @cindex log10
! 1088: @findex log10
! 1089:
! 1090:
! 1091: The `log10(x)` function returns the logarithm (base 10) of its argument.
! 1092:
! 1093: @node norm, rand, log10, Functions
! 1094: @subsubsection norm
! 1095:
! 1096: @c ?expressions functions norm
! 1097: @c ?functions norm
! 1098: @cindex norm
! 1099: @findex norm
! 1100:
! 1101:
! 1102: The `norm(x)` function returns the normal distribution function (or Gaussian)
! 1103: of the real part of its argument.
! 1104:
! 1105: @node rand, real, norm, Functions
! 1106: @subsubsection rand
! 1107:
! 1108: @c ?expressions functions rand
! 1109: @c ?functions rand
! 1110: @cindex rand
! 1111: @findex rand
! 1112:
! 1113:
! 1114: The `rand(x)` function returns a pseudo random number in the interval [0:1]
! 1115: using the real part of its argument as a seed. If seed < 0, the sequence
! 1116: is (re)initialized. If the argument is a complex value, the imaginary
! 1117: component is ignored.
! 1118:
! 1119: @node real, sgn, rand, Functions
! 1120: @subsubsection real
! 1121:
! 1122: @c ?expressions functions real
! 1123: @c ?functions real
! 1124: @cindex real
! 1125: @findex real
! 1126:
! 1127:
! 1128: The `real(x)` function returns the real part of its argument.
! 1129:
! 1130: @node sgn, sin, real, Functions
! 1131: @subsubsection sgn
! 1132:
! 1133: @c ?expressions functions sgn
! 1134: @c ?functions sgn
! 1135: @cindex sgn
! 1136: @findex sgn
! 1137:
! 1138:
! 1139: The `sgn(x)` function returns 1 if its argument is positive, -1 if its
! 1140: argument is negative, and 0 if its argument is 0. If the argument is a
! 1141: complex value, the imaginary component is ignored.
! 1142:
! 1143: @node sin, sinh, sgn, Functions
! 1144: @subsubsection sin
! 1145:
! 1146: @c ?expressions functions sin
! 1147: @c ?functions sin
! 1148: @cindex sin
! 1149: @findex sin
! 1150:
! 1151:
! 1152: The `sin(x)` function returns the sine of its argument. `sin` expects its
! 1153: argument to be in radians or degrees, as selected by @ref{angles}.
! 1154:
! 1155: @node sinh, sqrt, sin, Functions
! 1156: @subsubsection sinh
! 1157:
! 1158: @c ?expressions functions sinh
! 1159: @c ?functions sinh
! 1160: @cindex sinh
! 1161: @findex sinh
! 1162:
! 1163:
! 1164: The `sinh(x)` function returns the hyperbolic sine of its argument. @ref{sinh}
! 1165: expects its argument to be in radians.
! 1166:
! 1167: @node sqrt, tan, sinh, Functions
! 1168: @subsubsection sqrt
! 1169:
! 1170: @c ?expressions functions sqrt
! 1171: @c ?functions sqrt
! 1172: @cindex sqrt
! 1173: @findex sqrt
! 1174:
! 1175:
! 1176: The `sqrt(x)` function returns the square root of its argument.
! 1177:
! 1178: @node tan, tanh, sqrt, Functions
! 1179: @subsubsection tan
! 1180:
! 1181: @c ?expressions functions tan
! 1182: @c ?functions tan
! 1183: @cindex tan
! 1184: @findex tan
! 1185:
! 1186:
! 1187: The `tan(x)` function returns the tangent of its argument. `tan` expects
! 1188: its argument to be in radians or degrees, as selected by @ref{angles}.
! 1189:
! 1190: @node tanh, column, tan, Functions
! 1191: @subsubsection tanh
! 1192:
! 1193: @c ?expressions functions tanh
! 1194: @c ?functions tanh
! 1195: @cindex tanh
! 1196: @findex tanh
! 1197:
! 1198:
! 1199: The `tanh(x)` function returns the hyperbolic tangent of its argument. @ref{tanh}
! 1200: expects its argument to be in radians.
! 1201:
! 1202:
! 1203: A few additional functions are also available.
! 1204:
! 1205:
! 1206:
! 1207: @node column, tm_hour, tanh, Functions
! 1208: @subsubsection column
! 1209:
! 1210: @c ?expressions functions column
! 1211: @c ?functions column
! 1212: @cindex column
! 1213: @findex column
! 1214:
! 1215:
! 1216: `column(x)` may be used only in expressions as part of @ref{using} manipulations
! 1217: to fits or datafile plots. See @ref{using}.
! 1218:
! 1219: @node tm_hour, tm_mday, column, Functions
! 1220: @subsubsection tm_hour
! 1221:
! 1222: @c ?expressions tm_hour
! 1223: @findex tm_hour
! 1224: @c ?functions tm_hour
! 1225: The @ref{tm_hour} function interprets its argument as a time, in seconds from
! 1226: 1 Jan 2000. It returns the hour (an integer in the range 0--23) as a real.
! 1227:
! 1228: @node tm_mday, tm_min, tm_hour, Functions
! 1229: @subsubsection tm_mday
! 1230:
! 1231: @c ?expressions tm_mday
! 1232: @findex tm_mday
! 1233: @c ?functions tm_mday
! 1234: The @ref{tm_mday} function interprets its argument as a time, in seconds from
! 1235: 1 Jan 2000. It returns the day of the month (an integer in the range 1--31)
! 1236: as a real.
! 1237:
! 1238: @node tm_min, tm_mon, tm_mday, Functions
! 1239: @subsubsection tm_min
! 1240:
! 1241: @c ?expressions tm_min
! 1242: @findex tm_min
! 1243: @c ?functions tm_min
! 1244: The @ref{tm_min} function interprets its argument as a time, in seconds from
! 1245: 1 Jan 2000. It returns the minute (an integer in the range 0--59) as a real.
! 1246:
! 1247: @node tm_mon, tm_sec, tm_min, Functions
! 1248: @subsubsection tm_mon
! 1249:
! 1250: @c ?expressions tm_mon
! 1251: @findex tm_mon
! 1252: @c ?functions tm_mon
! 1253: The @ref{tm_mon} function interprets its argument as a time, in seconds from
! 1254: 1 Jan 2000. It returns the month (an integer in the range 1--12) as a real.
! 1255:
! 1256: @node tm_sec, tm_wday, tm_mon, Functions
! 1257: @subsubsection tm_sec
! 1258:
! 1259: @c ?expressions tm_sec
! 1260: @findex tm_sec
! 1261: @c ?functions tm_sec
! 1262: The @ref{tm_sec} function interprets its argument as a time, in seconds from
! 1263: 1 Jan 2000. It returns the second (an integer in the range 0--59) as a real.
! 1264:
! 1265: @node tm_wday, tm_yday, tm_sec, Functions
! 1266: @subsubsection tm_wday
! 1267:
! 1268: @c ?expressions tm_wday
! 1269: @findex tm_wday
! 1270: @c ?functions tm_wday
! 1271: The @ref{tm_wday} function interprets its argument as a time, in seconds from
! 1272: 1 Jan 2000. It returns the day of the week (an integer in the range 1--7) as
! 1273: a real.
! 1274:
! 1275: @node tm_yday, tm_year, tm_wday, Functions
! 1276: @subsubsection tm_yday
! 1277:
! 1278: @c ?expressions tm_yday
! 1279: @findex tm_yday
! 1280: @c ?functions tm_yday
! 1281: The @ref{tm_yday} function interprets its argument as a time, in seconds from
! 1282: 1 Jan 2000. It returns the day of the year (an integer in the range 1--366)
! 1283: as a real.
! 1284:
! 1285: @node tm_year, valid, tm_yday, Functions
! 1286: @subsubsection tm_year
! 1287:
! 1288: @c ?expressions tm_year
! 1289: @findex tm_year
! 1290: @c ?functions tm_year
! 1291: The @ref{tm_year} function interprets its argument as a time, in seconds from
! 1292: 1 Jan 2000. It returns the year (an integer) as a real.
! 1293:
! 1294: @node valid, , tm_year, Functions
! 1295: @subsubsection valid
! 1296:
! 1297: @c ?expressions functions valid
! 1298: @c ?functions valid
! 1299: @cindex valid
! 1300: @findex valid
! 1301:
! 1302:
! 1303: `valid(x)` may be used only in expressions as part of @ref{using} manipulations
! 1304: to fits or datafile plots. See @ref{using}.
! 1305:
! 1306: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html,Use of functions and complex variables for airfoils }
! 1307:
! 1308: @node Operators, User-defined, Functions, Expressions
! 1309: @subsection Operators
! 1310:
! 1311: @c ?expressions operators
! 1312: @cindex operators
! 1313:
! 1314: The operators in `gnuplot` are the same as the corresponding operators in the
! 1315: C programming language, except that all operators accept integer, real, and
! 1316: complex arguments, unless otherwise noted. The ** operator (exponentiation)
! 1317: is supported, as in FORTRAN.
! 1318:
! 1319: Parentheses may be used to change order of evaluation.
! 1320:
! 1321: @menu
! 1322: * Unary::
! 1323: * Binary::
! 1324: * Ternary::
! 1325: @end menu
! 1326:
! 1327: @node Unary, Binary, Operators, Operators
! 1328: @subsubsection Unary
! 1329:
! 1330: @c ?expressions operators unary
! 1331: @c ?operators unary
! 1332: @cindex unary
! 1333:
! 1334: The following is a list of all the unary operators and their usages:
! 1335:
! 1336:
! 1337: @example
! 1338: Symbol Example Explanation
! 1339: - -a unary minus
! 1340: + +a unary plus (no-operation)
! 1341: ~ ~a * one's complement
! 1342: ! !a * logical negation
! 1343: ! a! * factorial
! 1344: $ $3 * call arg/column during @ref{using} manipulation
! 1345:
! 1346: @end example
! 1347:
! 1348: (*) Starred explanations indicate that the operator requires an integer
! 1349: argument.
! 1350:
! 1351: Operator precedence is the same as in Fortran and C. As in those languages,
! 1352: parentheses may be used to change the order of operation. Thus -2**2 = -4,
! 1353: but (-2)**2 = 4.
! 1354:
! 1355: The factorial operator returns a real number to allow a greater range.
! 1356:
! 1357: @node Binary, Ternary, Unary, Operators
! 1358: @subsubsection Binary
! 1359:
! 1360: @c ?expressions operators binary
! 1361: @c ?operators binary
! 1362: @cindex binary
! 1363:
! 1364: The following is a list of all the binary operators and their usages:
! 1365:
! 1366:
! 1367: @example
! 1368: Symbol Example Explanation
! 1369: ** a**b exponentiation
! 1370: * a*b multiplication
! 1371: / a/b division
! 1372: % a%b * modulo
! 1373: + a+b addition
! 1374: - a-b subtraction
! 1375: == a==b equality
! 1376: != a!=b inequality
! 1377: < a<b less than
! 1378: <= a<=b less than or equal to
! 1379: > a>b greater than
! 1380: >= a>=b greater than or equal to
! 1381: & a&b * bitwise AND
! 1382: ^ a^b * bitwise exclusive OR
! 1383: | a|b * bitwise inclusive OR
! 1384: && a&&b * logical AND
! 1385: || a||b * logical OR
! 1386:
! 1387: @end example
! 1388:
! 1389:
! 1390: (*) Starred explanations indicate that the operator requires integer
! 1391: arguments.
! 1392:
! 1393: Logical AND (&&) and OR (||) short-circuit the way they do in C. That is,
! 1394: the second `&&` operand is not evaluated if the first is false; the second
! 1395: `||` operand is not evaluated if the first is true.
! 1396:
! 1397: @node Ternary, , Binary, Operators
! 1398: @subsubsection Ternary
! 1399:
! 1400: @c ?expressions operators ternary
! 1401: @c ?operators ternary
! 1402: @cindex ternary
! 1403:
! 1404: There is a single ternary operator:
! 1405:
! 1406:
! 1407: @example
! 1408: Symbol Example Explanation
! 1409: ?: a?b:c ternary operation
! 1410:
! 1411: @end example
! 1412:
! 1413:
! 1414: The ternary operator behaves as it does in C. The first argument (a), which
! 1415: must be an integer, is evaluated. If it is true (non-zero), the second
! 1416: argument (b) is evaluated and returned; otherwise the third argument (c) is
! 1417: evaluated and returned.
! 1418:
! 1419: The ternary operator is very useful both in constructing piecewise functions
! 1420: and in plotting points only when certain conditions are met.
! 1421:
! 1422: Examples:
! 1423:
! 1424: Plot a function that is to equal sin(x) for 0 <= x < 1, 1/x for 1 <= x < 2,
! 1425: and undefined elsewhere:
! 1426: @example
! 1427: f(x) = 0<=x && x<1 ? sin(x) : 1<=x && x<2 ? 1/x : 1/0
! 1428: plot f(x)
! 1429: @end example
! 1430:
! 1431: @c ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/ternary.gif" alt="[ternary.gif]" width=640 height=480>
! 1432: Note that `gnuplot` quietly ignores undefined values, so the final branch of
! 1433: the function (1/0) will produce no plottable points. Note also that f(x)
! 1434: will be plotted as a continuous function across the discontinuity if a line
! 1435: style is used. To plot it discontinuously, create separate functions for the
! 1436: two pieces. (Parametric functions are also useful for this purpose.)
! 1437:
! 1438: For data in a file, plot the average of the data in columns 2 and 3 against
! 1439: the datum in column 1, but only if the datum in column 4 is non-negative:
! 1440:
! 1441: @example
! 1442: plot 'file' using 1:( $4<0 ? 1/0 : ($2+$3)/2 )
! 1443:
! 1444: @end example
! 1445:
! 1446: Please see @ref{using} for an explanation of the @ref{using} syntax.
! 1447:
! 1448: @node User-defined, , Operators, Expressions
! 1449: @subsection User-defined
! 1450:
! 1451: @c ?expressions user-defined
! 1452: @cindex user-defined
! 1453:
! 1454: @cindex variables
! 1455: @opindex variables
! 1456:
! 1457:
! 1458: New user-defined variables and functions of one through five variables may
! 1459: be declared and used anywhere, including on the @ref{plot} command itself.
! 1460:
! 1461: User-defined function syntax:
! 1462: @example
! 1463: <func-name>( <dummy1> @{,<dummy2>@} ... @{,<dummy5>@} ) = <expression>
! 1464:
! 1465: @end example
! 1466:
! 1467: where <expression> is defined in terms of <dummy1> through <dummy5>.
! 1468:
! 1469: User-defined variable syntax:
! 1470: @example
! 1471: <variable-name> = <constant-expression>
! 1472:
! 1473: @end example
! 1474:
! 1475: Examples:
! 1476: @example
! 1477: w = 2
! 1478: q = floor(tan(pi/2 - 0.1))
! 1479: f(x) = sin(w*x)
! 1480: sinc(x) = sin(pi*x)/(pi*x)
! 1481: delta(t) = (t == 0)
! 1482: ramp(t) = (t > 0) ? t : 0
! 1483: min(a,b) = (a < b) ? a : b
! 1484: comb(n,k) = n!/(k!*(n-k)!)
! 1485: len3d(x,y,z) = sqrt(x*x+y*y+z*z)
! 1486: plot f(x) = sin(x*a), a = 0.2, f(x), a = 0.4, f(x)
! 1487:
! 1488: @end example
! 1489:
! 1490: @c ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/userdefined.gif" alt="[userdefined.gif]" width=640 height=480>
! 1491: Note that the variable `pi` is already defined. But it is in no way magic;
! 1492: you may redefine it to be whatever you like.
! 1493:
! 1494: Valid names are the same as in most programming languages: they must begin
! 1495: with a letter, but subsequent characters may be letters, digits, "$", or "_".
! 1496: Note, however, that the `fit` mechanism uses several variables with names
! 1497: that begin "FIT_". It is safest to avoid using such names. "FIT_LIMIT",
! 1498: however, is one that you may wish to redefine. See the documentation
! 1499: on `fit` for details.
! 1500:
! 1501:
! 1502: See @ref{functions}, @ref{variables}, and `fit`.
! 1503:
! 1504: @node Glossary, Plotting, Expressions, gnuplot
! 1505: @section Glossary
! 1506:
! 1507: @cindex glossary
! 1508:
! 1509: Throughout this document an attempt has been made to maintain consistency of
! 1510: nomenclature. This cannot be wholly successful because as `gnuplot` has
! 1511: evolved over time, certain command and keyword names have been adopted that
! 1512: preclude such perfection. This section contains explanations of the way
! 1513: some of these terms are used.
! 1514:
! 1515: A "page" or "screen" is the entire area addressable by `gnuplot`. On a
! 1516: monitor, it is the full screen; on a plotter, it is a single sheet of paper.
! 1517:
! 1518: A screen may contain one or more "plots". A plot is defined by an abscissa
! 1519: and an ordinate, although these need not actually appear on it, as well as
! 1520: the margins and any text written therein.
! 1521:
! 1522: A plot contains one "graph". A graph is defined by an abscissa and an
! 1523: ordinate, although these need not actually appear on it.
! 1524:
! 1525: A graph may contain one or more "lines". A line is a single function or
! 1526: data set. "Line" is also a plotting style. The word will also be used in
! 1527: sense "a line of text". Presumably the context will remove any ambiguity.
! 1528:
! 1529: The lines on a graph may have individual names. These may be listed
! 1530: together with a sample of the plotting style used to represent them in
! 1531: the "key", sometimes also called the "legend".
! 1532:
! 1533: The word "title" occurs with multiple meanings in `gnuplot`. In this
! 1534: document, it will always be preceded by the adjective "plot", "line", or
! 1535: "key" to differentiate among them.
! 1536:
! 1537: A graph may have up to four labelled axes. Various commands have the name of
! 1538: an axis built into their names, such as @ref{xlabel}. Other commands have
! 1539: one or more axis names as options, such as `set logscale xy`. The names of
! 1540: the four axes for these usages are "x" for the axis along the bottom border
! 1541: of the plot, "y" for the left border, "x2" for the top border, and "y2" for
! 1542: the right border. "z" also occurs in commands used with 3-d plotting.
! 1543:
! 1544: When discussing data files, the term "record" will be resurrected and used
! 1545: to denote a single line of text in the file, that is, the characters between
! 1546: newline or end-of-record characters. A "point" is the datum extracted from
! 1547: a single record. A "datablock" is a set of points from consecutive records,
! 1548: delimited by blank records. A line, when referred to in the context of a
! 1549: data file, is a subset of a datablock.
! 1550:
! 1551: @node Plotting, Start-up, Glossary, gnuplot
! 1552: @section Plotting
! 1553:
! 1554: @cindex plotting
! 1555:
! 1556: There are three `gnuplot` commands which actually create a plot: @ref{plot},
! 1557: `splot` and @ref{replot}. @ref{plot} generates 2-d plots, `splot` generates 3-d
! 1558: plots (actually 2-d projections, of course), and @ref{replot} appends its
! 1559: arguments to the previous @ref{plot} or `splot` and executes the modified
! 1560: command.
! 1561:
! 1562: Much of the general information about plotting can be found in the discussion
! 1563: of @ref{plot}; information specific to 3-d can be found in the `splot` section.
! 1564:
! 1565: @ref{plot} operates in either rectangular or polar coordinates -- see `set polar`
! 1566: for details of the latter. `splot` operates only in rectangular coordinates,
! 1567: but the @ref{mapping} command allows for a few other coordinate systems to be
! 1568: treated. In addition, the @ref{using} option allows both @ref{plot} and `splot` to
! 1569: treat almost any coordinate system you'd care to define.
! 1570:
! 1571: `splot` can plot surfaces and contours in addition to points and/or lines.
! 1572: In addition to `splot`, see @ref{isosamples} for information about defining
! 1573: the grid for a 3-d function; `splot datafile` for information about the
! 1574: requisite file structure for 3-d data values; and @ref{contour} and @ref{cntrparam} for information about contours.
! 1575:
! 1576: @node Start-up, Substitution, Plotting, gnuplot
! 1577: @section Start-up
! 1578:
! 1579: @cindex startup
! 1580:
! 1581: @cindex start
! 1582:
! 1583: @cindex .gnuplot
! 1584:
! 1585: When `gnuplot` is run, it looks for an initialization file to load. This
! 1586: file is called `.gnuplot` on Unix and AmigaOS systems, and `GNUPLOT.INI` on
! 1587: other systems. If this file is not found in the current directory, the
! 1588: program will look for it in the home directory (under AmigaOS,
! 1589: Atari(single)TOS, MS-DOS and OS/2, the environment variable `gnuplot` should
! 1590: contain the name of this directory). Note: if NOCWDRC is defined during the
! 1591: installation, `gnuplot` will not read from the current directory.
! 1592:
! 1593: If the initialization file is found, `gnuplot` executes the commands in it.
! 1594: These may be any legal `gnuplot` commands, but typically they are limited to
! 1595: setting the terminal and defining frequently-used functions or variables.
! 1596:
! 1597: @node Substitution, Syntax, Start-up, gnuplot
! 1598: @section Substitution
! 1599:
! 1600: @cindex substitution
! 1601:
! 1602: Command-line substitution is specified by a system command enclosed in
! 1603: backquotes. This command is spawned and the output it produces replaces
! 1604: the name of the command (and backquotes) on the command line. Some
! 1605: implementations also support pipes; see @ref{special-filenames}.
! 1606:
! 1607: Newlines in the output produced by the spawned command are replaced with
! 1608: blanks.
! 1609:
! 1610: Command-line substitution can be used anywhere on the `gnuplot` command
! 1611: line.
! 1612:
! 1613: Example:
! 1614:
! 1615: This will run the program `leastsq` and replace `leastsq` (including
! 1616: backquotes) on the command line with its output:
! 1617: @example
! 1618: f(x) = `leastsq`
! 1619:
! 1620: @end example
! 1621:
! 1622: or, in VMS
! 1623: @example
! 1624: f(x) = `run leastsq`
! 1625:
! 1626: @end example
! 1627:
! 1628: @node Syntax, Time/Date_data, Substitution, gnuplot
! 1629: @section Syntax
! 1630:
! 1631: @cindex syntax
! 1632:
! 1633: @cindex specify
! 1634:
! 1635: @cindex punctuation
! 1636:
! 1637: The general rules of syntax and punctuation in `gnuplot` are that keywords
! 1638: and options are order-dependent. Options and any accompanying parameters are
! 1639: separated by spaces whereas lists and coordinates are separated by commas.
! 1640: Ranges are separated by colons and enclosed in brackets [], text and file
! 1641: names are enclosed in quotes, and a few miscellaneous things are enclosed
! 1642: in parentheses. Braces @{@} are used for a few special purposes.
! 1643:
! 1644: Commas are used to separate coordinates on the `set` commands @ref{arrow},
! 1645: @ref{key}, and @ref{label}; the list of variables being fitted (the list after the
! 1646: `via` keyword on the `fit` command); lists of discrete contours or the loop
! 1647: parameters which specify them on the @ref{cntrparam} command; the arguments
! 1648: of the `set` commands @ref{dgrid3d}, @ref{dummy}, @ref{isosamples}, @ref{offsets}, @ref{origin},
! 1649: @ref{samples}, @ref{size}, `time`, and @ref{view}; lists of tics or the loop parameters
! 1650: which specify them; the offsets for titles and axis labels; parametric
! 1651: functions to be used to calculate the x, y, and z coordinates on the @ref{plot},
! 1652: @ref{replot} and `splot` commands; and the complete sets of keywords specifying
! 1653: individual plots (data sets or functions) on the @ref{plot}, @ref{replot} and `splot`
! 1654: commands.
! 1655:
! 1656: Parentheses are used to delimit sets of explicit tics (as opposed to loop
! 1657: parameters) and to indicate computations in the @ref{using} filter of the `fit`,
! 1658: @ref{plot}, @ref{replot} and `splot` commands.
! 1659:
! 1660: (Parentheses and commas are also used as usual in function notation.)
! 1661:
! 1662: Brackets are used to delimit ranges, whether they are given on `set`, @ref{plot}
! 1663: or `splot` commands.
! 1664:
! 1665: Colons are used to separate extrema in `range` specifications (whether they
! 1666: are given on `set`, @ref{plot} or `splot` commands) and to separate entries in
! 1667: the @ref{using} filter of the @ref{plot}, @ref{replot}, `splot` and `fit` commands.
! 1668:
! 1669: Semicolons are used to separate commands given on a single command line.
! 1670:
! 1671: Braces are used in text to be specially processed by some terminals, like
! 1672: `postscript`. They are also used to denote complex numbers: @{3,2@} = 3 + 2i.
! 1673:
! 1674: Text may be enclosed in single- or double-quotes. Backslash processing of
! 1675: sequences like \n (newline) and \345 (octal character code) is performed for
! 1676: double-quoted strings, but not for single-quoted strings.
! 1677:
! 1678: The justification is the same for each line of a multi-line string. Thus the
! 1679: center-justified string
! 1680: @example
! 1681: "This is the first line of text.\nThis is the second line."
! 1682: @end example
! 1683:
! 1684: will produce
! 1685: @example
! 1686: This is the first line of text.
! 1687: This is the second line.
! 1688: @end example
! 1689:
! 1690: but
! 1691: @example
! 1692: 'This is the first line of text.\nThis is the second line.'
! 1693: @end example
! 1694:
! 1695: will produce
! 1696: @example
! 1697: This is the first line of text.\nThis is the second line.
! 1698:
! 1699: @end example
! 1700:
! 1701: Filenames may be entered with either single- or double-quotes. In this
! 1702: manual the command examples generally single-quote filenames and double-quote
! 1703: other string tokens for clarity.
! 1704:
! 1705: At present you should not embed \n inside @{@} when using the enhanced option
! 1706: of the postscript terminal.
! 1707:
! 1708: The EEPIC, Imagen, Uniplex, LaTeX, and TPIC drivers allow a newline to be
! 1709: specified by \\ in a single-quoted string or \\\\ in a double-quoted string.
! 1710:
! 1711: Back-quotes are used to enclose system commands for substitution.
! 1712:
! 1713: @node Time/Date_data, , Syntax, gnuplot
! 1714: @section Time/Date data
! 1715:
! 1716: @cindex time/date
! 1717:
! 1718: `gnuplot` supports the use of time and/or date information as input data.
! 1719: This feature is activated by the commands `set xdata time`, `set ydata time`,
! 1720: etc.
! 1721:
! 1722: Internally all times and dates are converted to the number of seconds from
! 1723: the year 2000. The command @ref{timefmt} defines the format for all inputs:
! 1724: data files, ranges, tics, label positions---in short, anything that accepts a
! 1725: data value must receive it in this format. Since only one input format can
! 1726: be in force at a given time, all time/date quantities being input at the same
! 1727: time must be presented in the same format. Thus if both x and y data in a
! 1728: file are time/date, they must be in the same format.
! 1729:
! 1730: The conversion to and from seconds assumes Universal Time (which is the same
! 1731: as Greenwich Standard Time). There is no provision for changing the time
! 1732: zone or for daylight savings. If all your data refer to the same time zone
! 1733: (and are all either daylight or standard) you don't need to worry about these
! 1734: things. But if the absolute time is crucial for your application, you'll
! 1735: need to convert to UT yourself.
! 1736:
! 1737: Commands like @ref{xrange} will re-interpret the integer according to
! 1738: @ref{timefmt}. If you change @ref{timefmt}, and then `show` the quantity again, it
! 1739: will be displayed in the new @ref{timefmt}. For that matter, if you give the
! 1740: deactivation command (like @ref{xdata}), the quantity will be shown in its
! 1741: numerical form.
! 1742:
! 1743: The command `set format` defines the format that will be used for tic labels,
! 1744: whether or not the specified axis is time/date.
! 1745:
! 1746: If time/date information is to be plotted from a file, the @ref{using} option
! 1747: _must_ be used on the @ref{plot} or `splot` command. These commands simply use
! 1748: white space to separate columns, but white space may be embedded within the
! 1749: time/date string. If you use tabs as a separator, some trial-and-error may
! 1750: be necessary to discover how your system treats them.
! 1751:
! 1752: The following example demonstrates time/date plotting.
! 1753:
! 1754: Suppose the file "data" contains records like
! 1755:
! 1756: @example
! 1757: 03/21/95 10:00 6.02e23
! 1758:
! 1759: @end example
! 1760:
! 1761: This file can be plotted by
! 1762:
! 1763: @example
! 1764: set xdata time
! 1765: set timefmt "%m/%d/%y"
! 1766: set xrange ["03/21/95":"03/22/95"]
! 1767: set format x "%m/%d"
! 1768: set timefmt "%m/%d/%y %H:%M"
! 1769: plot "data" using 1:3
! 1770:
! 1771: @end example
! 1772:
! 1773: which will produce xtic labels that look like "03/21".
! 1774:
! 1775: See the descriptions of each command for more details.
! 1776:
! 1777: @node Commands, Graphical_User_Interfaces, gnuplot, Top
! 1778: @chapter Commands
! 1779:
! 1780: @cindex commands
! 1781:
! 1782: This section lists the commands acceptable to `gnuplot` in alphabetical
! 1783: order. Printed versions of this document contain all commands; on-line
! 1784: versions may not be complete. Indeed, on some systems there may be no
! 1785: commands at all listed under this heading.
! 1786:
! 1787: Note that in most cases unambiguous abbreviations for command names and their
! 1788: options are permissible, i.e., "`p f(x) w l`" instead of "`plot f(x) with
! 1789: lines`".
! 1790:
! 1791: In the syntax descriptions, braces (@{@}) denote optional arguments and a
! 1792: vertical bar (|) separates mutually exclusive choices.
! 1793:
! 1794: @menu
! 1795: * cd::
! 1796: * call::
! 1797: * clear::
! 1798: * exit::
! 1799: * fit::
! 1800: * help::
! 1801: * if::
! 1802: * load::
! 1803: * pause::
! 1804: * plot::
! 1805: * print::
! 1806: * pwd::
! 1807: * quit::
! 1808: * replot::
! 1809: * reread::
! 1810: * reset::
! 1811: * save::
! 1812: * set-show::
! 1813: * shell::
! 1814: * splot::
! 1815: * test::
! 1816: * update::
! 1817: @end menu
! 1818:
! 1819: @node cd, call, Commands, Commands
! 1820: @section cd
! 1821:
! 1822: @c ?commands cd
! 1823: @cindex cd
! 1824: @cmindex cd
! 1825:
! 1826:
! 1827: The @ref{cd} command changes the working directory.
! 1828:
! 1829: Syntax:
! 1830: @example
! 1831: cd '<directory-name>'
! 1832:
! 1833: @end example
! 1834:
! 1835: The directory name must be enclosed in quotes.
! 1836:
! 1837: Examples:
! 1838: @example
! 1839: cd 'subdir'
! 1840: cd ".."
! 1841:
! 1842: @end example
! 1843:
! 1844: DOS users _must_ use single-quotes---backslash [\] has special significance
! 1845: inside double-quotes. For example,
! 1846: @example
! 1847: cd "c:\newdata"
! 1848: @end example
! 1849:
! 1850: fails, but
! 1851: @example
! 1852: cd 'c:\newdata'
! 1853: @end example
! 1854:
! 1855: works as expected.
! 1856:
! 1857: @node call, clear, cd, Commands
! 1858: @section call
! 1859:
! 1860: @c ?commands call
! 1861: @cindex call
! 1862: @cmindex call
! 1863:
! 1864:
! 1865: The @ref{call} command is identical to the load command with one exception: you
! 1866: can have up to ten additional parameters to the command (delimited according
! 1867: to the standard parser rules) which can be substituted into the lines read
! 1868: from the file. As each line is read from the @ref{call}ed input file, it is
! 1869: scanned for the sequence `$` (dollar-sign) followed by a digit (0--9). If
! 1870: found, the sequence is replaced by the corresponding parameter from the
! 1871: @ref{call} command line. If the parameter was specified as a string in the
! 1872: @ref{call} line, it is substituted without its enclosing quotes. `$` followed by
! 1873: any character other than a digit will be that character. E.g. use `$$` to
! 1874: get a single `$`. Providing more than ten parameters on the @ref{call} command
! 1875: line will cause an error. A parameter that was not provided substitutes as
! 1876: nothing. Files being @ref{call}ed may themselves contain @ref{call} or @ref{load}
! 1877: commands.
! 1878:
! 1879: The @ref{call} command _must_ be the last command on a multi-command line.
! 1880:
! 1881: Syntax:
! 1882: @example
! 1883: call "<input-file>" <parameter-0> <parm-1> ... <parm-9>
! 1884:
! 1885: @end example
! 1886:
! 1887: The name of the input file must be enclosed in quotes, and it is recommended
! 1888: that parameters are similarly enclosed in quotes (future versions of gnuplot
! 1889: may treat quoted and unquoted arguments differently).
! 1890:
! 1891: Example:
! 1892:
! 1893: If the file 'calltest.gp' contains the line:
! 1894: @example
! 1895: print "p0=$0 p1=$1 p2=$2 p3=$3 p4=$4 p5=$5 p6=$6 p7=x$7x"
! 1896:
! 1897: @end example
! 1898:
! 1899: entering the command:
! 1900: @example
! 1901: call 'calltest.gp' "abcd" 1.2 + "'quoted'" -- "$2"
! 1902:
! 1903: @end example
! 1904:
! 1905: will display:
! 1906: @example
! 1907: p0=abcd p1=1.2 p2=+ p3='quoted' p4=- p5=- p6=$2 p7=xx
! 1908:
! 1909: @end example
! 1910:
! 1911: NOTE: there is a clash in syntax with the datafile @ref{using} callback
! 1912: operator. Use `$$n` or `column(n)` to access column n from a datafile inside
! 1913: a @ref{call}ed datafile plot.
! 1914:
! 1915: @node clear, exit, call, Commands
! 1916: @section clear
! 1917:
! 1918: @c ?commands clear
! 1919: @cindex clear
! 1920: @cmindex clear
! 1921:
! 1922:
! 1923: The @ref{clear} command erases the current screen or output device as specified
! 1924: by @ref{output}. This usually generates a formfeed on hardcopy devices. Use
! 1925: @ref{terminal} to set the device type.
! 1926:
! 1927: For some terminals @ref{clear} erases only the portion of the plotting surface
! 1928: defined by @ref{size}, so for these it can be used in conjunction with @ref{multiplot} to create an inset.
! 1929:
! 1930: Example:
! 1931: @example
! 1932: set multiplot
! 1933: plot sin(x)
! 1934: set origin 0.5,0.5
! 1935: set size 0.4,0.4
! 1936: clear
! 1937: plot cos(x)
! 1938: set nomultiplot
! 1939:
! 1940: @end example
! 1941:
! 1942: Please see @ref{multiplot}, @ref{size}, and @ref{origin} for details of these
! 1943: commands.
! 1944:
! 1945: @node exit, fit, clear, Commands
! 1946: @section exit
! 1947:
! 1948: @c ?commands exit
! 1949: @cindex exit
! 1950: @cmindex exit
! 1951:
! 1952:
! 1953: The commands @ref{exit} and @ref{quit} and the END-OF-FILE character will exit the
! 1954: current `gnuplot` command file and @ref{load} the next one. See "help
! 1955: batch/interactive" for more details.
! 1956:
! 1957: Each of these commands will clear the output device (as does the @ref{clear}
! 1958: command) before exiting.
! 1959:
! 1960: @node fit, help, exit, Commands
! 1961: @section fit
! 1962:
! 1963: @c ?commands fit
! 1964: @cindex fit
! 1965: @cmindex fit
! 1966:
! 1967:
! 1968: @cindex least-squares
! 1969:
! 1970: @cindex Marquardt
! 1971:
! 1972: The `fit` command can fit a user-defined function to a set of data points
! 1973: (x,y) or (x,y,z), using an implementation of the nonlinear least-squares
! 1974: (NLLS) Marquardt-Levenberg algorithm. Any user-defined variable occurring in
! 1975: the function body may serve as a fit parameter, but the return type of the
! 1976: function must be real.
! 1977:
! 1978: Syntax:
! 1979: @example
! 1980: fit @{[xrange] @{[yrange]@}@} <function> '<datafile>'
! 1981: @{datafile-modifiers@}
! 1982: via '<parameter file>' | <var1>@{,<var2>,...@}
! 1983:
! 1984: @end example
! 1985:
! 1986: Ranges may be specified to temporarily limit the data which is to be fitted;
! 1987: any out-of-range data points are ignored. The syntax is
! 1988: @example
! 1989: [@{dummy_variable=@}@{<min>@}@{:<max>@}],
! 1990: @end example
! 1991:
! 1992: analogous to @ref{plot}; see @ref{ranges}.
! 1993:
! 1994: <function> is any valid `gnuplot` expression, although it is usual to use a
! 1995: previously user-defined function of the form f(x) or f(x,y).
! 1996:
! 1997: <datafile> is treated as in the @ref{plot} command. All the `plot datafile`
! 1998: modifiers (@ref{using}, @ref{every},...) except @ref{smooth} are applicable to `fit`.
! 1999: See `plot datafile`.
! 2000:
! 2001: The default data formats for fitting functions with a single independent
! 2002: variable, y=f(x), are @{x:@}y or x:y:s; those formats can be changed with
! 2003: the datafile @ref{using} qualifier. The third item, (a column number or an
! 2004: expression), if present, is interpreted as the standard deviation of the
! 2005: corresponding y value and is used to compute a weight for the datum, 1/s**2.
! 2006: Otherwise, all data points are weighted equally, with a weight of one.
! 2007:
! 2008: To fit a function with two independent variables, z=f(x,y), the required
! 2009: format is @ref{using} with four items, x:y:z:s. The complete format must be
! 2010: given---no default columns are assumed for a missing token. Weights for
! 2011: each data point are evaluated from 's' as above. If error estimates are
! 2012: not available, a constant value can be specified as a constant expression
! 2013: (see @ref{using}), e.g., `using 1:2:3:(1)`.
! 2014:
! 2015: Multiple datasets may be simultaneously fit with functions of one
! 2016: independent variable by making y a 'pseudo-variable', e.g., the dataline
! 2017: number, and fitting as two independent variables. See `fit multibranch`.
! 2018:
! 2019: The `via` qualifier specifies which parameters are to be adjusted, either
! 2020: directly, or by referencing a parameter file.
! 2021:
! 2022: Examples:
! 2023: @example
! 2024: f(x) = a*x**2 + b*x + c
! 2025: g(x,y) = a*x**2 + b*y**2 + c*x*y
! 2026: FIT_LIMIT = 1e-6
! 2027: fit f(x) 'measured.dat' via 'start.par'
! 2028: fit f(x) 'measured.dat' using 3:($7-5) via 'start.par'
! 2029: fit f(x) './data/trash.dat' using 1:2:3 via a, b, c
! 2030: fit g(x,y) 'surface.dat' using 1:2:3:(1) via a, b, c
! 2031:
! 2032: @end example
! 2033:
! 2034: After each iteration step, detailed information about the current state
! 2035: of the fit is written to the display. The same information about the
! 2036: initial and final states is written to a log file, "fit.log". This file
! 2037: is always appended to, so as to not lose any previous fit history; it
! 2038: should be deleted or renamed as desired.
! 2039:
! 2040: The fit may be interrupted by pressing Ctrl-C (any key but Ctrl-C under
! 2041: MSDOS and Atari Multitasking Systems). After the current iteration
! 2042: completes, you have the option to (1) stop the fit and accept the current
! 2043: parameter values, (2) continue the fit, (3) execute a `gnuplot` command
! 2044: as specified by the environment variable FIT_SCRIPT. The default for
! 2045: FIT_SCRIPT is @ref{replot}, so if you had previously plotted both the data
! 2046: and the fitting function in one graph, you can display the current state
! 2047: of the fit.
! 2048:
! 2049: Once `fit` has finished, the @ref{update} command may be used to store final
! 2050: values in a file for subsequent use as a parameter file. See @ref{update}
! 2051: for details.
! 2052:
! 2053: @menu
! 2054: * adjustable_parameters::
! 2055: * beginner's_guide::
! 2056: * error_estimates::
! 2057: * fit_controlling::
! 2058: * multi-branch::
! 2059: * starting_values::
! 2060: * tips::
! 2061: @end menu
! 2062:
! 2063: @node adjustable_parameters, beginner's_guide, fit, fit
! 2064: @subsection adjustable parameters
! 2065:
! 2066: @c ?commands fit parameters
! 2067: @c ?fit parameters
! 2068: @c ?commands fit adjustable_parameters
! 2069: @c ?fit adjustable_parameters
! 2070: @cindex fit_parameters
! 2071:
! 2072: There are two ways that `via` can specify the parameters to be adjusted,
! 2073: either directly on the command line or indirectly, by referencing a
! 2074: parameter file. The two use different means to set initial values.
! 2075:
! 2076: Adjustable parameters can be specified by a comma-separated list of variable
! 2077: names after the `via` keyword. Any variable that is not already defined is
! 2078: is created with an initial value of 1.0. However, the fit is more likely
! 2079: to converge rapidly if the variables have been previously declared with more
! 2080: appropriate starting values.
! 2081:
! 2082: In a parameter file, each parameter to be varied and a corresponding initial
! 2083: value are specified, one per line, in the form
! 2084: @example
! 2085: varname = value
! 2086:
! 2087: @end example
! 2088:
! 2089: Comments, marked by '#', and blank lines are permissible. The
! 2090: special form
! 2091: @example
! 2092: varname = value # FIXED
! 2093:
! 2094: @end example
! 2095:
! 2096: means that the variable is treated as a 'fixed parameter', initialized by the
! 2097: parameter file, but not adjusted by `fit`. For clarity, it may be useful to
! 2098: designate variables as fixed parameters so that their values are reported by
! 2099: `fit`. The keyword `# FIXED` has to appear in exactly this form.
! 2100:
! 2101:
! 2102: @node beginner's_guide, error_estimates, adjustable_parameters, fit
! 2103: @subsection beginner's guide
! 2104:
! 2105: @c ?commands fit beginners_guide
! 2106: @c ?fit beginners_guide
! 2107: @c ?fit guide
! 2108: @cindex fitting
! 2109:
! 2110: `fit` is used to find a set of parameters that 'best' fits your data to your
! 2111: user-defined function. The fit is judged on the basis of the the sum of the
! 2112: squared differences or 'residuals' (SSR) between the input data points and
! 2113: the function values, evaluated at the same places. This quantity is often
! 2114: called 'chisquare' (i.e., the Greek letter chi, to the power of 2). The
! 2115: algorithm attempts to minimize SSR, or more precisely, WSSR, as the residuals
! 2116: are 'weighted' by the input data errors (or 1.0) before being squared; see
! 2117: `fit error_estimates` for details.
! 2118:
! 2119: That's why it is called 'least-squares fitting'. Let's look at an example
! 2120: to see what is meant by 'non-linear', but first we had better go over some
! 2121: terms. Here it is convenient to use z as the dependent variable for
! 2122: user-defined functions of either one independent variable, z=f(x), or two
! 2123: independent variables, z=f(x,y). A parameter is a user-defined variable
! 2124: that `fit` will adjust, i.e., an unknown quantity in the function
! 2125: declaration. Linearity/non-linearity refers to the relationship of the
! 2126: dependent variable, z, to the parameters which `fit` is adjusting, not of
! 2127: z to the independent variables, x and/or y. (To be technical, the
! 2128: second @{and higher@} derivatives of the fitting function with respect to
! 2129: the parameters are zero for a linear least-squares problem).
! 2130:
! 2131: For linear least-squares (LLS), the user-defined function will be a sum of
! 2132: simple functions, not involving any parameters, each multiplied by one
! 2133: parameter. NLLS handles more complicated functions in which parameters can
! 2134: be used in a large number of ways. An example that illustrates the
! 2135: difference between linear and nonlinear least-squares is the Fourier series.
! 2136: One member may be written as
! 2137: @example
! 2138: z=a*sin(c*x) + b*cos(c*x).
! 2139: @end example
! 2140:
! 2141: If a and b are the unknown parameters and c is constant, then estimating
! 2142: values of the parameters is a linear least-squares problem. However, if
! 2143: c is an unknown parameter, the problem is nonlinear.
! 2144:
! 2145: In the linear case, parameter values can be determined by comparatively
! 2146: simple linear algebra, in one direct step. However LLS is a special case
! 2147: which is also solved along with more general NLLS problems by the iterative
! 2148: procedure that `gnuplot` uses. `fit` attempts to find the minimum by doing
! 2149: a search. Each step (iteration) calculates WSSR with a new set of parameter
! 2150: values. The Marquardt-Levenberg algorithm selects the parameter values for
! 2151: the next iteration. The process continues until a preset criterium is met,
! 2152: either (1) the fit has "converged" (the relative change in WSSR is less than
! 2153: FIT_LIMIT), or (2) it reaches a preset iteration count limit, FIT_MAXITER
! 2154: (see @ref{variables}). The fit may also be interrupted
! 2155: and subsequently halted from the keyboard (see `fit`).
! 2156:
! 2157: Often the function to be fitted will be based on a model (or theory) that
! 2158: attempts to describe or predict the behaviour of the data. Then `fit` can
! 2159: be used to find values for the free parameters of the model, to determine
! 2160: how well the data fits the model, and to estimate an error range for each
! 2161: parameter. See `fit error_estimates`.
! 2162:
! 2163: Alternatively, in curve-fitting, functions are selected independent of
! 2164: a model (on the basis of experience as to which are likely to describe
! 2165: the trend of the data with the desired resolution and a minimum number
! 2166: of parameters*functions.) The `fit` solution then provides an analytic
! 2167: representation of the curve.
! 2168:
! 2169: However, if all you really want is a smooth curve through your data points,
! 2170: the @ref{smooth} option to @ref{plot} may be what you've been looking for rather
! 2171: than `fit`.
! 2172:
! 2173: @node error_estimates, fit_controlling, beginner's_guide, fit
! 2174: @subsection error estimates
! 2175:
! 2176: @c ?commands fit error_estimate
! 2177: @c ?fit error_estimate
! 2178: @c ?fit errors
! 2179: In `fit`, the term "error" is used in two different contexts, data error
! 2180: estimates and parameter error estimates.
! 2181:
! 2182: Data error estimates are used to calculate the relative weight of each data
! 2183: point when determining the weighted sum of squared residuals, WSSR or
! 2184: chisquare. They can affect the parameter estimates, since they determine
! 2185: how much influence the deviation of each data point from the fitted function
! 2186: has on the final values. Some of the `fit` output information, including
! 2187: the parameter error estimates, is more meaningful if accurate data error
! 2188: estimates have been provided.
! 2189:
! 2190: The 'statistical overview' describes some of the `fit` output and gives some
! 2191: background for the 'practical guidelines'.
! 2192:
! 2193: @menu
! 2194: * statistical_overview::
! 2195: * practical_guidelines::
! 2196: @end menu
! 2197:
! 2198: @node statistical_overview, practical_guidelines, error_estimates, error_estimates
! 2199: @subsubsection statistical overview
! 2200:
! 2201: @c ?commands fit error statistical_overview
! 2202: @c ?fit error statistical_overview
! 2203: @cindex statistical_overview
! 2204:
! 2205: The theory of non-linear least-squares (NLLS) is generally described in terms
! 2206: of a normal distribution of errors, that is, the input data is assumed to be
! 2207: a sample from a population having a given mean and a Gaussian (normal)
! 2208: distribution about the mean with a given standard deviation. For a sample of
! 2209: sufficiently large size, and knowing the population standard deviation, one
! 2210: can use the statistics of the chisquare distribution to describe a "goodness
! 2211: of fit" by looking at the variable often called "chisquare". Here, it is
! 2212: sufficient to say that a reduced chisquare (chisquare/degrees of freedom,
! 2213: where degrees of freedom is the number of datapoints less the number of
! 2214: parameters being fitted) of 1.0 is an indication that the weighted sum of
! 2215: squared deviations between the fitted function and the data points is the
! 2216: same as that expected for a random sample from a population characterized by
! 2217: the function with the current value of the parameters and the given standard
! 2218: deviations.
! 2219:
! 2220: If the standard deviation for the population is not constant, as in counting
! 2221: statistics where variance = counts, then each point should be individually
! 2222: weighted when comparing the observed sum of deviations and the expected sum
! 2223: of deviations.
! 2224:
! 2225: At the conclusion `fit` reports 'stdfit', the standard deviation of the fit,
! 2226: which is the rms of the residuals, and the variance of the residuals, also
! 2227: called 'reduced chisquare' when the data points are weighted. The number of
! 2228: degrees of freedom (the number of data points minus the number of fitted
! 2229: parameters) is used in these estimates because the parameters used in
! 2230: calculating the residuals of the datapoints were obtained from the same data.
! 2231:
! 2232: To estimate confidence levels for the parameters, one can use the minimum
! 2233: chisquare obtained from the fit and chisquare statistics to determine the
! 2234: value of chisquare corresponding to the desired confidence level, but
! 2235: considerably more calculation is required to determine the combinations of
! 2236: parameters which produce such values.
! 2237:
! 2238: Rather than determine confidence intervals, `fit` reports parameter error
! 2239: estimates which are readily obtained from the variance-covariance matrix
! 2240: after the final iteration. By convention, these estimates are called
! 2241: "standard errors" or "asymptotic standard errors", since they are calculated
! 2242: in the same way as the standard errors (standard deviation of each parameter)
! 2243: of a linear least-squares problem, even though the statistical conditions for
! 2244: designating the quantity calculated to be a standard deviation are not
! 2245: generally valid for the NLLS problem. The asymptotic standard errors are
! 2246: generally over-optimistic and should not be used for determining confidence
! 2247: levels, but are useful for qualitative purposes.
! 2248:
! 2249: The final solution also produces a correlation matrix, which gives an
! 2250: indication of the correlation of parameters in the region of the solution;
! 2251: if one parameter is changed, increasing chisquare, does changing another
! 2252: compensate? The main diagonal elements, autocorrelation, are all 1; if
! 2253: all parameters were independent, all other elements would be nearly 0. Two
! 2254: variables which completely compensate each other would have an off-diagonal
! 2255: element of unit magnitude, with a sign depending on whether the relation is
! 2256: proportional or inversely proportional. The smaller the magnitudes of the
! 2257: off-diagonal elements, the closer the estimates of the standard deviation
! 2258: of each parameter would be to the asymptotic standard error.
! 2259:
! 2260: @node practical_guidelines, , statistical_overview, error_estimates
! 2261: @subsubsection practical guidelines
! 2262:
! 2263: @c ?commands fit error practical_guidelines
! 2264: @c ?fit error practical_guidelines
! 2265: @cindex practical_guidelines
! 2266:
! 2267: @cindex guidelines
! 2268:
! 2269: If you have a basis for assigning weights to each data point, doing so lets
! 2270: you make use of additional knowledge about your measurements, e.g., take into
! 2271: account that some points may be more reliable than others. That may affect
! 2272: the final values of the parameters.
! 2273:
! 2274: Weighting the data provides a basis for interpreting the additional `fit`
! 2275: output after the last iteration. Even if you weight each point equally,
! 2276: estimating an average standard deviation rather than using a weight of 1
! 2277: makes WSSR a dimensionless variable, as chisquare is by definition.
! 2278:
! 2279: Each fit iteration will display information which can be used to evaluate
! 2280: the progress of the fit. (An '*' indicates that it did not find a smaller
! 2281: WSSR and is trying again.) The 'sum of squares of residuals', also called
! 2282: 'chisquare', is the WSSR between the data and your fitted function; `fit`
! 2283: has minimized that. At this stage, with weighted data, chisquare is expected
! 2284: to approach the number of degrees of freedom (data points minus parameters).
! 2285: The WSSR can be used to calculate the reduced chisquare (WSSR/ndf) or stdfit,
! 2286: the standard deviation of the fit, sqrt(WSSR/ndf). Both of these are
! 2287: reported for the final WSSR.
! 2288:
! 2289: If the data are unweighted, stdfit is the rms value of the deviation of the
! 2290: data from the fitted function, in user units.
! 2291:
! 2292: If you supplied valid data errors, the number of data points is large enough,
! 2293: and the model is correct, the reduced chisquare should be about unity. (For
! 2294: details, look up the 'chi-squared distribution' in your favourite statistics
! 2295: reference.) If so, there are additional tests, beyond the scope of this
! 2296: overview, for determining how well the model fits the data.
! 2297:
! 2298: A reduced chisquare much larger than 1.0 may be due to incorrect data error
! 2299: estimates, data errors not normally distributed, systematic measurement
! 2300: errors, 'outliers', or an incorrect model function. A plot of the residuals,
! 2301: e.g., `plot 'datafile' using 1:($2-f($1))`, may help to show any systematic
! 2302: trends. Plotting both the data points and the function may help to suggest
! 2303: another model.
! 2304:
! 2305: Similarly, a reduced chisquare less than 1.0 indicates WSSR is less than that
! 2306: expected for a random sample from the function with normally distributed
! 2307: errors. The data error estimates may be too large, the statistical
! 2308: assumptions may not be justified, or the model function may be too general,
! 2309: fitting fluctuations in a particular sample in addition to the underlying
! 2310: trends. In the latter case, a simpler function may be more appropriate.
! 2311:
! 2312: You'll have to get used to both `fit` and the kind of problems you apply it
! 2313: to before you can relate the standard errors to some more practical estimates
! 2314: of parameter uncertainties or evaluate the significance of the correlation
! 2315: matrix.
! 2316:
! 2317: Note that `fit`, in common with most NLLS implementations, minimizes the
! 2318: weighted sum of squared distances (y-f(x))**2. It does not provide any means
! 2319: to account for "errors" in the values of x, only in y. Also, any "outliers"
! 2320: (data points outside the normal distribution of the model) will have an
! 2321: exaggerated effect on the solution.
! 2322:
! 2323: @node fit_controlling, multi-branch, error_estimates, fit
! 2324: @subsection fit controlling
! 2325:
! 2326: @c ?commands fit_control
! 2327: @cindex fit_control
! 2328:
! 2329: @c ?fit control
! 2330: There are a number of `gnuplot` variables that can be defined to affect
! 2331: `fit`. Those which can be defined once `gnuplot` is running are listed
! 2332: under 'control_variables' while those defined before starting `gnuplot`
! 2333: are listed under 'environment_variables'.
! 2334:
! 2335: @menu
! 2336: * control_variables::
! 2337: * environment_variables::
! 2338: @end menu
! 2339:
! 2340: @node control_variables, environment_variables, fit_controlling, fit_controlling
! 2341: @subsubsection control variables
! 2342:
! 2343: @c ?commands fit_control variables
! 2344: @c ?fit_control variables
! 2345: @c ?fit control variables
! 2346: The default epsilon limit (1e-5) may be changed by declaring a value for
! 2347: @example
! 2348: FIT_LIMIT
! 2349: @end example
! 2350:
! 2351: When the sum of squared residuals changes between two iteration steps by
! 2352: a factor less than this number (epsilon), the fit is considered to have
! 2353: 'converged'.
! 2354:
! 2355: The maximum number of iterations may be limited by declaring a value for
! 2356: @example
! 2357: FIT_MAXITER
! 2358: @end example
! 2359:
! 2360: A value of 0 (or not defining it at all) means that there is no limit.
! 2361:
! 2362: If you need even more control about the algorithm, and know the
! 2363: Marquardt-Levenberg algorithm well, there are some more variables to
! 2364: influence it. The startup value of `lambda` is normally calculated
! 2365: automatically from the ML-matrix, but if you want to, you may provide
! 2366: your own one with
! 2367: @example
! 2368: FIT_START_LAMBDA
! 2369: @end example
! 2370:
! 2371: Specifying FIT_START_LAMBDA as zero or less will re-enable the automatic
! 2372: selection. The variable
! 2373: @example
! 2374: FIT_LAMBDA_FACTOR
! 2375: @end example
! 2376:
! 2377: gives the factor by which `lambda` is increased or decreased whenever
! 2378: the chi-squared target function increased or decreased significantly.
! 2379: Setting FIT_LAMBDA_FACTOR to zero re-enables the default factor of
! 2380: 10.0.
! 2381:
! 2382: Oher variables with the FIT_ prefix may be added to `fit`, so it is safer
! 2383: not to use that prefix for user-defined variables.
! 2384:
! 2385: The variables FIT_SKIP and FIT_INDEX were used by earlier releases of
! 2386: `gnuplot` with a 'fit' patch called `gnufit` and are no longer available.
! 2387: The datafile @ref{every} modifier provides the functionality of FIT_SKIP.
! 2388: FIT_INDEX was used for multi-branch fitting, but multi-branch fitting of
! 2389: one independent variable is now done as a pseudo-3D fit in which the
! 2390: second independent variable and @ref{using} are used to specify the branch.
! 2391: See @ref{multi-branch}.
! 2392:
! 2393: @node environment_variables, , control_variables, fit_controlling
! 2394: @subsubsection environment variables
! 2395:
! 2396: @c ?commands fit_control environment
! 2397: @c ?fit_control environment
! 2398: @c ?fit control environment
! 2399: The environment variables must be defined before `gnuplot` is executed; how
! 2400: to do so depends on your operating system.
! 2401:
! 2402: @example
! 2403: FIT_LOG
! 2404: @end example
! 2405:
! 2406: changes the name (and/or path) of the file to which the fit log will be
! 2407: written from the default of "fit.log" in the working directory.
! 2408:
! 2409: @example
! 2410: FIT_SCRIPT
! 2411: @end example
! 2412:
! 2413: specifies a command that may be executed after an user interrupt. The default
! 2414: is @ref{replot}, but a @ref{plot} or @ref{load} command may be useful to display a plot
! 2415: customized to highlight the progress of the fit.
! 2416:
! 2417: @node multi-branch, starting_values, fit_controlling, fit
! 2418: @subsection multi-branch
! 2419:
! 2420: @c ?commands fit multi-branch
! 2421: @c ?fit multi-branch
! 2422: @cindex multi-branch
! 2423:
! 2424: @cindex branch
! 2425:
! 2426: In multi-branch fitting, multiple data sets can be simultaneously fit with
! 2427: functions of one independent variable having common parameters by minimizing
! 2428: the total WSSR. The function and parameters (branch) for each data set are
! 2429: selected by using a 'pseudo-variable', e.g., either the dataline number (a
! 2430: 'column' index of -1) or the datafile index (-2), as the second independent
! 2431: variable.
! 2432:
! 2433: Example: Given two exponential decays of the form, z=f(x), each describing
! 2434: a different data set but having a common decay time, estimate the values of
! 2435: the parameters. If the datafile has the format x:z:s, then
! 2436: @example
! 2437: f(x,y) = (y==0) ? a*exp(-x/tau) : b*exp(-x/tau)
! 2438: fit f(x,y) 'datafile' using 1:-1:2:3 via a, b, tau
! 2439:
! 2440: @end example
! 2441:
! 2442: For a more complicated example, see the file "hexa.fnc" used by the
! 2443: "fit.dem" demo.
! 2444:
! 2445: Appropriate weighting may be required since unit weights may cause one
! 2446: branch to predominate if there is a difference in the scale of the dependent
! 2447: variable. Fitting each branch separately, using the multi-branch solution
! 2448: as initial values, may give an indication as to the relative effect of each
! 2449: branch on the joint solution.
! 2450:
! 2451: @node starting_values, tips, multi-branch, fit
! 2452: @subsection starting values
! 2453:
! 2454: @c ?commands fit starting_values
! 2455: @c ?fit starting_values
! 2456: @cindex starting_values
! 2457:
! 2458: Nonlinear fitting is not guaranteed to converge to the global optimum (the
! 2459: solution with the smallest sum of squared residuals, SSR), and can get stuck
! 2460: at a local minimum. The routine has no way to determine that; it is up to
! 2461: you to judge whether this has happened.
! 2462:
! 2463: `fit` may, and often will get "lost" if started far from a solution, where
! 2464: SSR is large and changing slowly as the parameters are varied, or it may
! 2465: reach a numerically unstable region (e.g., too large a number causing a
! 2466: floating point overflow) which results in an "undefined value" message
! 2467: or `gnuplot` halting.
! 2468:
! 2469: To improve the chances of finding the global optimum, you should set the
! 2470: starting values at least roughly in the vicinity of the solution, e.g.,
! 2471: within an order of magnitude, if possible. The closer your starting values
! 2472: are to the solution, the less chance of stopping at another minimum. One way
! 2473: to find starting values is to plot data and the fitting function on the same
! 2474: graph and change parameter values and @ref{replot} until reasonable similarity
! 2475: is reached. The same plot is also useful to check whether the fit stopped at
! 2476: a minimum with a poor fit.
! 2477:
! 2478: Of course, a reasonably good fit is not proof there is not a "better" fit (in
! 2479: either a statistical sense, characterized by an improved goodness-of-fit
! 2480: criterion, or a physical sense, with a solution more consistent with the
! 2481: model.) Depending on the problem, it may be desirable to `fit` with various
! 2482: sets of starting values, covering a reasonable range for each parameter.
! 2483:
! 2484: @node tips, , starting_values, fit
! 2485: @subsection tips
! 2486:
! 2487: @c ?commands fit tips
! 2488: @c ?fit tips
! 2489: @cindex tips
! 2490:
! 2491: Here are some tips to keep in mind to get the most out of `fit`. They're not
! 2492: very organized, so you'll have to read them several times until their essence
! 2493: has sunk in.
! 2494:
! 2495: The two forms of the `via` argument to `fit` serve two largely distinct
! 2496: purposes. The `via "file"` form is best used for (possibly unattended) batch
! 2497: operation, where you just supply the startup values in a file and can later
! 2498: use @ref{update} to copy the results back into another (or the same) parameter
! 2499: file.
! 2500:
! 2501: The `via var1, var2, ...` form is best used interactively, where the command
! 2502: history mechanism may be used to edit the list of parameters to be fitted or
! 2503: to supply new startup values for the next try. This is particularly useful
! 2504: for hard problems, where a direct fit to all parameters at once won't work
! 2505: without good starting values. To find such, you can iterate several times,
! 2506: fitting only some of the parameters, until the values are close enough to the
! 2507: goal that the final fit to all parameters at once will work.
! 2508:
! 2509: Make sure that there is no mutual dependency among parameters of the function
! 2510: you are fitting. For example, don't try to fit a*exp(x+b), because
! 2511: a*exp(x+b)=a*exp(b)*exp(x). Instead, fit either a*exp(x) or exp(x+b).
! 2512:
! 2513: A technical issue: the parameters must not be too different in magnitude.
! 2514: The larger the ratio of the largest and the smallest absolute parameter
! 2515: values, the slower the fit will converge. If the ratio is close to or above
! 2516: the inverse of the machine floating point precision, it may take next to
! 2517: forever to converge, or refuse to converge at all. You will have to adapt
! 2518: your function to avoid this, e.g., replace 'parameter' by '1e9*parameter' in
! 2519: the function definition, and divide the starting value by 1e9.
! 2520:
! 2521: If you can write your function as a linear combination of simple functions
! 2522: weighted by the parameters to be fitted, by all means do so. That helps a
! 2523: lot, because the problem is no longer nonlinear and should converge with only
! 2524: a small number of iterations, perhaps just one.
! 2525:
! 2526: Some prescriptions for analysing data, given in practical experimentation
! 2527: courses, may have you first fit some functions to your data, perhaps in a
! 2528: multi-step process of accounting for several aspects of the underlying
! 2529: theory one by one, and then extract the information you really wanted from
! 2530: the fitting parameters of those functions. With `fit`, this may often be
! 2531: done in one step by writing the model function directly in terms of the
! 2532: desired parameters. Transforming data can also quite often be avoided,
! 2533: though sometimes at the cost of a more difficult fit problem. If you think
! 2534: this contradicts the previous paragraph about simplifying the fit function,
! 2535: you are correct.
! 2536:
! 2537: A "singular matrix" message indicates that this implementation of the
! 2538: Marquardt-Levenberg algorithm can't calculate parameter values for the next
! 2539: iteration. Try different starting values, writing the function in another
! 2540: form, or a simpler function.
! 2541:
! 2542: Finally, a nice quote from the manual of another fitting package (fudgit),
! 2543: that kind of summarizes all these issues: "Nonlinear fitting is an art!"
! 2544:
! 2545: @node help, if, fit, Commands
! 2546: @section help
! 2547:
! 2548: @c ?commands help
! 2549: @cindex help
! 2550: @cmindex help
! 2551:
! 2552:
! 2553: The @ref{help} command displays on-line help. To specify information on a
! 2554: particular topic use the syntax:
! 2555:
! 2556: @example
! 2557: help @{<topic>@}
! 2558:
! 2559: @end example
! 2560:
! 2561: If <topic> is not specified, a short message is printed about `gnuplot`.
! 2562: After help for the requested topic is given, a menu of subtopics is given;
! 2563: help for a subtopic may be requested by typing its name, extending the help
! 2564: request. After that subtopic has been printed, the request may be extended
! 2565: again or you may go back one level to the previous topic. Eventually, the
! 2566: `gnuplot` command line will return.
! 2567:
! 2568: If a question mark (?) is given as the topic, the list of topics currently
! 2569: available is printed on the screen.
! 2570:
! 2571: @node if, load, help, Commands
! 2572: @section if
! 2573:
! 2574: @c ?commands if
! 2575: @cindex if
! 2576: @cmindex if
! 2577:
! 2578:
! 2579: The @ref{if} command allows commands to be executed conditionally.
! 2580:
! 2581: Syntax:
! 2582: @example
! 2583: if (<condition>) <command-line>
! 2584:
! 2585: @end example
! 2586:
! 2587: <condition> will be evaluated. If it is true (non-zero), then the command(s)
! 2588: of the <command-line> will be executed. If <condition> is false (zero), then
! 2589: the entire <command-line> is ignored. Note that use of `;` to allow multiple
! 2590: commands on the same line will _not_ end the conditionalized commands.
! 2591:
! 2592: Examples:
! 2593: @example
! 2594: pi=3
! 2595: if (pi!=acos(-1)) print "?Fixing pi!"; pi=acos(-1); print pi
! 2596: @end example
! 2597:
! 2598: will display:
! 2599: @example
! 2600: ?Fixing pi!
! 2601: 3.14159265358979
! 2602: @end example
! 2603:
! 2604: but
! 2605: @example
! 2606: if (1==2) print "Never see this"; print "Or this either"
! 2607: @end example
! 2608:
! 2609: will not display anything.
! 2610:
! 2611: See @ref{reread} for an example of how @ref{if} and @ref{reread} can be used together to
! 2612: perform a loop.
! 2613:
! 2614: @node load, pause, if, Commands
! 2615: @section load
! 2616:
! 2617: @c ?commands load
! 2618: @cindex load
! 2619: @cmindex load
! 2620:
! 2621:
! 2622: The @ref{load} command executes each line of the specified input file as if it
! 2623: had been typed in interactively. Files created by the @ref{save} command can
! 2624: later be @ref{load}ed. Any text file containing valid commands can be created
! 2625: and then executed by the @ref{load} command. Files being @ref{load}ed may themselves
! 2626: contain @ref{load} or @ref{call} commands. See `comment` for information about
! 2627: comments in commands. To @ref{load} with arguments, see @ref{call}.
! 2628:
! 2629: The @ref{load} command _must_ be the last command on a multi-command line.
! 2630:
! 2631: Syntax:
! 2632: @example
! 2633: load "<input-file>"
! 2634:
! 2635: @end example
! 2636:
! 2637: The name of the input file must be enclosed in quotes.
! 2638:
! 2639: The special filename "-" may be used to @ref{load} commands from standard input.
! 2640: This allows a `gnuplot` command file to accept some commands from standard
! 2641: input. Please see "help batch/interactive" for more details.
! 2642:
! 2643: Examples:
! 2644: @example
! 2645: load 'work.gnu'
! 2646: load "func.dat"
! 2647:
! 2648: @end example
! 2649:
! 2650: The @ref{load} command is performed implicitly on any file names given as
! 2651: arguments to `gnuplot`. These are loaded in the order specified, and
! 2652: then `gnuplot` exits.
! 2653:
! 2654: @node pause, plot, load, Commands
! 2655: @section pause
! 2656:
! 2657: @c ?commands pause
! 2658: @cindex pause
! 2659: @cmindex pause
! 2660:
! 2661:
! 2662: The @ref{pause} command displays any text associated with the command and then
! 2663: waits a specified amount of time or until the carriage return is pressed.
! 2664: @ref{pause} is especially useful in conjunction with @ref{load} files.
! 2665:
! 2666: Syntax:
! 2667: @example
! 2668: pause <time> @{"<string>"@}
! 2669:
! 2670: @end example
! 2671:
! 2672: <time> may be any integer constant or expression. Choosing -1 will wait
! 2673: until a carriage return is hit, zero (0) won't pause at all, and a positive
! 2674: integer will wait the specified number of seconds. `pause 0` is synonymous
! 2675: with @ref{print}.
! 2676:
! 2677: Note: Since @ref{pause} communicates with the operating system rather than the
! 2678: graphics, it may behave differently with different device drivers (depending
! 2679: upon how text and graphics are mixed).
! 2680:
! 2681: Examples:
! 2682: @example
! 2683: pause -1 # Wait until a carriage return is hit
! 2684: pause 3 # Wait three seconds
! 2685: pause -1 "Hit return to continue"
! 2686: pause 10 "Isn't this pretty? It's a cubic spline."
! 2687:
! 2688: @end example
! 2689:
! 2690:
! 2691: @node plot, print, pause, Commands
! 2692: @section plot
! 2693:
! 2694: @c ?commands plot
! 2695: @cindex plot
! 2696: @cmindex plot
! 2697:
! 2698:
! 2699: @ref{plot} is the primary command for drawing plots with `gnuplot`. It creates
! 2700: plots of functions and data in many, many ways. @ref{plot} is used to draw 2-d
! 2701: functions and data; `splot` draws 2-d projections of 3-d surfaces and data.
! 2702: @ref{plot} and `splot` contain many common features; see `splot` for differences.
! 2703: Note specifically that `splot`'s @ref{binary} and @ref{matrix} options do not exist
! 2704: for @ref{plot}.
! 2705:
! 2706: Syntax:
! 2707: @example
! 2708: plot @{<ranges>@}
! 2709: @{<function> | @{"<datafile>" @{datafile-modifiers@}@}@}
! 2710: @{axes <axes>@} @{<title-spec>@} @{with <style>@}
! 2711: @{, @{definitions,@} <function> ...@}
! 2712:
! 2713: @end example
! 2714:
! 2715: where either a <function> or the name of a data file enclosed in quotes is
! 2716: supplied. A function is a mathematical expression or a pair of mathematical
! 2717: expressions in parametric mode. The expressions may be defined completely or
! 2718: in part earlier in the stream of `gnuplot` commands (see `user-defined`).
! 2719:
! 2720: It is also possible to define functions and parameters on the @ref{plot} command
! 2721: itself. This is done merely by isolating them from other items with commas.
! 2722:
! 2723: There are four possible sets of axes available; the keyword <axes> is used to
! 2724: select the axes for which a particular line should be scaled. `x1y1` refers
! 2725: to the axes on the bottom and left; `x2y2` to those on the top and right;
! 2726: `x1y2` to those on the bottom and right; and `x2y1` to those on the top and
! 2727: left. Ranges specified on the @ref{plot} command apply only to the first set of
! 2728: axes (bottom left).
! 2729:
! 2730: Examples:
! 2731: @example
! 2732: plot sin(x)
! 2733: plot f(x) = sin(x*a), a = .2, f(x), a = .4, f(x)
! 2734: plot [t=1:10] [-pi:pi*2] tan(t), \
! 2735: "data.1" using (tan($2)):($3/$4) smooth csplines \
! 2736: axes x1y2 notitle with lines 5
! 2737:
! 2738: @end example
! 2739:
! 2740:
! 2741: @menu
! 2742: * data-file::
! 2743: * errorbars::
! 2744: * parametric::
! 2745: * ranges::
! 2746: * title::
! 2747: * with::
! 2748: @end menu
! 2749:
! 2750: @node data-file, errorbars, plot, plot
! 2751: @subsection data-file
! 2752:
! 2753: @c ?commands plot datafile
! 2754: @c ?plot datafile
! 2755: @cindex data-file
! 2756:
! 2757: @cindex datafile
! 2758:
! 2759: @cindex data
! 2760:
! 2761: Discrete data contained in a file can be displayed by specifying the name of
! 2762: the data file (enclosed in single or double quotes) on the @ref{plot} command line.
! 2763:
! 2764: Syntax:
! 2765: @example
! 2766: plot '<file_name>' @{index <index list>@}
! 2767: @{every <every list>@}
! 2768: @{thru <thru expression>@}
! 2769: @{using <using list>@}
! 2770: @{smooth <option>@}
! 2771:
! 2772: @end example
! 2773:
! 2774: The modifiers @ref{index}, @ref{every}, @ref{thru}, @ref{using}, and @ref{smooth} are discussed
! 2775: separately. In brief, @ref{index} selects which data sets in a multi-data-set
! 2776: file are to be plotted, @ref{every} specifies which points within a single data
! 2777: set are to be plotted, @ref{using} determines how the columns within a single
! 2778: record are to be interpreted (@ref{thru} is a special case of @ref{using}), and
! 2779: @ref{smooth} allows for simple interpolation and approximation. ('splot' has a
! 2780: similar syntax, but does not support the @ref{smooth} and @ref{thru} options.)
! 2781:
! 2782: Data files should contain at least one data point per record (@ref{using} can
! 2783: select one data point from the record). Records beginning with `#` (and
! 2784: also with `!` on VMS) will be treated as comments and ignored. Each data
! 2785: point represents an (x,y) pair. For @ref{plot}s with error bars (see @ref{errorbars}), each data point is (x,y,ydelta), (x,y,ylow,yhigh), (x,y,xdelta),
! 2786: (x,y,xlow,xhigh), or (x,y,xlow,xhigh,ylow,yhigh). In all cases, the numbers
! 2787: on each record of a data file must be separated by white space (one or more
! 2788: blanks or tabs), unless a format specifier is provided by the @ref{using} option.
! 2789: This white space divides each record into columns.
! 2790:
! 2791: Data may be written in exponential format with the exponent preceded by the
! 2792: letter e, E, d, D, q, or Q.
! 2793:
! 2794: Only one column (the y value) need be provided. If x is omitted, `gnuplot`
! 2795: provides integer values starting at 0.
! 2796:
! 2797: In datafiles, blank records (records with no characters other than blanks and
! 2798: a newline and/or carriage return) are significant---pairs of blank records
! 2799: separate @ref{index}es (see @ref{index}). Data separated by double
! 2800: blank records are treated as if they were in separate data files.
! 2801:
! 2802: Single blank records designate discontinuities in a @ref{plot}; no line will join
! 2803: points separated by a blank records (if they are plotted with a line style).
! 2804:
! 2805: If autoscaling has been enabled (@ref{autoscale}), the axes are automatically
! 2806: extended to include all datapoints, with a whole number of tic marks if tics
! 2807: are being drawn. This has two consequences: i) For `splot`, the corner of
! 2808: the surface may not coincide with the corner of the base. In this case, no
! 2809: vertical line is drawn. ii) When plotting data with the same x range on a
! 2810: dual-axis graph, the x coordinates may not coincide if the x2tics are not
! 2811: being drawn. This is because the x axis has been autoextended to a whole
! 2812: number of tics, but the x2 axis has not. The following example illustrates
! 2813: the problem:
! 2814:
! 2815: @example
! 2816: reset; plot '-', '-'
! 2817: 1 1
! 2818: 19 19
! 2819: e
! 2820: 1 1
! 2821: 19 19
! 2822: e
! 2823:
! 2824: @end example
! 2825:
! 2826: @menu
! 2827: * every::
! 2828: * example_datafile::
! 2829: * index::
! 2830: * smooth::
! 2831: * special-filenames::
! 2832: * thru::
! 2833: * using::
! 2834: @end menu
! 2835:
! 2836: @node every, example_datafile, data-file, data-file
! 2837: @subsubsection every
! 2838:
! 2839: @c ?commands plot datafile every
! 2840: @c ?plot datafile every
! 2841: @c ?plot every
! 2842: @c ?data-file every
! 2843: @c ?datafile every
! 2844: @cindex every
! 2845:
! 2846: The @ref{every} keyword allows a periodic sampling of a data set to be plotted.
! 2847:
! 2848: In the discussion a "point" is a datum defined by a single record in the
! 2849: file; "block" here will mean the same thing as "datablock" (see `glossary`).
! 2850:
! 2851: Syntax:
! 2852: @example
! 2853: plot 'file' every @{<point_incr>@}
! 2854: @{:@{<block_incr>@}
! 2855: @{:@{<start_point>@}
! 2856: @{:@{<start_block>@}
! 2857: @{:@{<end_point>@}
! 2858: @{:<end_block>@}@}@}@}@}
! 2859:
! 2860: @end example
! 2861:
! 2862: The data points to be plotted are selected according to a loop from
! 2863: <`start_point`> to <`end_point`> with increment <`point_incr`> and the
! 2864: blocks according to a loop from <`start_block`> to <`end_block`> with
! 2865: increment <`block_incr`>.
! 2866:
! 2867: The first datum in each block is numbered '0', as is the first block in the
! 2868: file.
! 2869:
! 2870: Note that records containing unplottable information are counted.
! 2871:
! 2872: Any of the numbers can be omitted; the increments default to unity, the start
! 2873: values to the first point or block, and the end values to the last point or
! 2874: block. If @ref{every} is not specified, all points in all lines are plotted.
! 2875:
! 2876: Examples:
! 2877: @example
! 2878: every :::3::3 # selects just the fourth block ('0' is first)
! 2879: every :::::9 # selects the first 10 blocks
! 2880: every 2:2 # selects every other point in every other block
! 2881: every ::5::15 # selects points 5 through 15 in each block
! 2882: @end example
! 2883:
! 2884: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/simple.html,Simple Plot Demos },
! 2885: @uref{http://www.nas.nasa.gov/~woo/gnuplot/surfacea/surfacea.html,Non-parametric splot demos }, and
! 2886: @uref{http://www.nas.nasa.gov/~woo/gnuplot/surfaceb/surfaceb.html,Parametric splot demos.}
! 2887:
! 2888: @node example_datafile, index, every, data-file
! 2889: @subsubsection example datafile
! 2890:
! 2891: @c ?commands plot datafile example
! 2892: @c ?plot datafile example
! 2893: @c ?plot example
! 2894: @c ?datafile example
! 2895: @c ?data-file example
! 2896: @cindex example
! 2897:
! 2898: This example plots the data in the file "population.dat" and a theoretical
! 2899: curve:
! 2900:
! 2901: @example
! 2902: pop(x) = 103*exp((1965-x)/10)
! 2903: plot [1960:1990] 'population.dat', pop(x)
! 2904:
! 2905: @end example
! 2906:
! 2907: The file "population.dat" might contain:
! 2908:
! 2909: @example
! 2910: # Gnu population in Antarctica since 1965
! 2911: 1965 103
! 2912: 1970 55
! 2913: 1975 34
! 2914: 1980 24
! 2915: 1985 10
! 2916:
! 2917: @end example
! 2918:
! 2919: @c ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/population.gif" alt="[population.gif]" width=640 height=480>
! 2920:
! 2921: @node index, smooth, example_datafile, data-file
! 2922: @subsubsection index
! 2923:
! 2924: @c ?commands plot datafile index
! 2925: @c ?plot datafile index
! 2926: @c ?plot index
! 2927: @c ?data-file index
! 2928: @c ?datafile index
! 2929: @cindex index
! 2930:
! 2931: The @ref{index} keyword allows only some of the data sets in a multi-data-set
! 2932: file to be plotted.
! 2933:
! 2934: Syntax:
! 2935: @example
! 2936: plot 'file' index <m>@{@{:<n>@}:<p>@}
! 2937:
! 2938: @end example
! 2939:
! 2940: Data sets are separated by pairs of blank records. `index <m>` selects only
! 2941: set <m>; `index <m>:<n>` selects sets in the range <m> to <n>; and `index
! 2942: <m>:<n>:<p>` selects indices <m>, <m>+<p>, <m>+2<p>, etc., but stopping at
! 2943: <n>. Following C indexing, the index 0 is assigned to the first data set in
! 2944: the file. Specifying too large an index results in an error message. If
! 2945: @ref{index} is not specified, all sets are plotted as a single data set.
! 2946:
! 2947: Example:
! 2948: @example
! 2949: plot 'file' index 4:5
! 2950: @end example
! 2951:
! 2952: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/multimsh.html,splot with indices demo. }
! 2953:
! 2954: @node smooth, special-filenames, index, data-file
! 2955: @subsubsection smooth
! 2956:
! 2957: @c ?commands plot datafile smooth
! 2958: @c ?plot datafile smooth
! 2959: @c ?plot smooth
! 2960: @c ?data-file smooth
! 2961: @c ?datafile smooth
! 2962: @cindex smooth
! 2963:
! 2964: `gnuplot` includes a few general-purpose routines for interpolation and
! 2965: approximation of data; these are grouped under the @ref{smooth} option. More
! 2966: sophisticated data processing may be performed by preprocessing the data
! 2967: externally or by using `fit` with an appropriate model.
! 2968:
! 2969: Syntax:
! 2970: @example
! 2971: smooth @{unique | csplines | acsplines | bezier | sbezier@}
! 2972:
! 2973: @end example
! 2974:
! 2975: `unique` plots the data after making them monotonic. Each of the other
! 2976: routines uses the data to determine the coefficients of a continuous curve
! 2977: between the endpoints of the data. This curve is then plotted in the same
! 2978: manner as a function, that is, by finding its value at uniform intervals
! 2979: along the abscissa (see @ref{samples}) and connecting these points with
! 2980: straight line segments (if a line style is chosen).
! 2981:
! 2982: If @ref{autoscale} is in effect, the ranges will be computed such that the
! 2983: plotted curve lies within the borders of the graph.
! 2984:
! 2985: If too few points are available to allow the selected option to be applied,
! 2986: an error message is produced. The minimum number is one for `unique`, four
! 2987: for `acsplines`, and three for the others.
! 2988:
! 2989: The @ref{smooth} options have no effect on function plots.
! 2990:
! 2991:
! 2992: @noindent --- ACSPLINES ---
! 2993:
! 2994: @c ?commands plot datafile smooth acsplines
! 2995: @c ?plot datafile smooth acsplines
! 2996: @c ?data-file smooth acsplines
! 2997: @c ?datafile smooth acsplines
! 2998: @c ?plot smooth acsplines
! 2999: @c ?plot acsplines
! 3000: @c ?smooth acsplines
! 3001: @cindex acsplines
! 3002:
! 3003: The `acsplines` option approximates the data with a "natural smoothing spline".
! 3004: After the data are made monotonic in x (see `smooth unique`), a curve is
! 3005: piecewise constructed from segments of cubic polynomials whose coefficients
! 3006: are found by the weighting the data points; the weights are taken from the
! 3007: third column in the data file. That default can be modified by the third
! 3008: entry in the @ref{using} list, e.g.,
! 3009: @example
! 3010: plot 'data-file' using 1:2:(1.0) smooth acsplines
! 3011:
! 3012: @end example
! 3013:
! 3014: Qualitatively, the absolute magnitude of the weights determines the number
! 3015: of segments used to construct the curve. If the weights are large, the
! 3016: effect of each datum is large and the curve approaches that produced by
! 3017: connecting consecutive points with natural cubic splines. If the weights are
! 3018: small, the curve is composed of fewer segments and thus is smoother; the
! 3019: limiting case is the single segment produced by a weighted linear least
! 3020: squares fit to all the data. The smoothing weight can be expressed in terms
! 3021: of errors as a statistical weight for a point divided by a "smoothing factor"
! 3022: for the curve so that (standard) errors in the file can be used as smoothing
! 3023: weights.
! 3024:
! 3025: Example:
! 3026: @example
! 3027: sw(x,S)=1/(x*x*S)
! 3028: plot 'data_file' using 1:2:(sw($3,100)) smooth acsplines
! 3029:
! 3030: @end example
! 3031:
! 3032:
! 3033: @noindent --- BEZIER ---
! 3034:
! 3035: @c ?commands plot datafile smooth bezier
! 3036: @c ?plot datafile smooth bezier
! 3037: @c ?plot smooth bezier
! 3038: @c ?data-file smooth bezier
! 3039: @c ?datafile smooth bezier
! 3040: @c ?plot bezier
! 3041: @c ?smooth bezier
! 3042: @cindex bezier
! 3043:
! 3044: The `bezier` option approximates the data with a Bezier curve of degree n
! 3045: (the number of data points) that connects the endpoints.
! 3046:
! 3047:
! 3048: @noindent --- CSPLINES ---
! 3049:
! 3050: @c ?commands plot datafile smooth csplines
! 3051: @c ?plot datafile smooth csplines
! 3052: @c ?plot smooth csplines
! 3053: @c ?data-file smooth csplines
! 3054: @c ?datafile smooth csplines
! 3055: @c ?plot csplines
! 3056: @c ?smooth csplines
! 3057: @cindex csplines
! 3058:
! 3059: The `csplines` option connects consecutive points by natural cubic splines
! 3060: after rendering the data monotonic (see `smooth unique`).
! 3061:
! 3062:
! 3063: @noindent --- SBEZIER ---
! 3064:
! 3065: @c ?commands plot datafile smooth sbezier
! 3066: @c ?plot datafile smooth sbezier
! 3067: @c ?plot smooth sbezier
! 3068: @c ?data-file smooth sbezier
! 3069: @c ?datafile smooth sbezier
! 3070: @c ?plot sbezier
! 3071: @c ?smooth sbezier
! 3072: @cindex sbezier
! 3073:
! 3074: The `sbezier` option first renders the data monotonic (`unique`) and then
! 3075: applies the `bezier` algorithm.
! 3076:
! 3077:
! 3078: @noindent --- UNIQUE ---
! 3079:
! 3080: @c ?commands plot datafile smooth unique
! 3081: @c ?plot datafile smooth unique
! 3082: @c ?plot smooth unique
! 3083: @c ?data-file smooth unique
! 3084: @c ?datafile smooth unique
! 3085: @c ?plot unique
! 3086: @c ?smooth unique
! 3087: @cindex unique
! 3088:
! 3089: The `unique` option makes the data monotonic in x; points with the same
! 3090: x-value are replaced by a single point having the average y-value. The
! 3091: resulting points are then connected by straight line segments.
! 3092: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/mgr.html,See demos. }
! 3093:
! 3094: @node special-filenames, thru, smooth, data-file
! 3095: @subsubsection special-filenames
! 3096:
! 3097: @c ?commands plot datafile special-filenames
! 3098: @c ?plot datafile special-filenames
! 3099: @c ?plot special-filenames
! 3100: @c ?datafile special-filenames
! 3101: @cindex special-filenames
! 3102:
! 3103: A special filename of `'-'` specifies that the data are inline; i.e., they
! 3104: follow the command. Only the data follow the command; @ref{plot} options like
! 3105: filters, titles, and line styles remain on the 'plot' command line. This is
! 3106: similar to << in unix shell script, and $DECK in VMS DCL. The data are
! 3107: entered as though they are being read from a file, one data point per record.
! 3108: The letter "e" at the start of the first column terminates data entry. The
! 3109: @ref{using} option can be applied to these data---using it to filter them through
! 3110: a function might make sense, but selecting columns probably doesn't!
! 3111:
! 3112: `'-'` is intended for situations where it is useful to have data and commands
! 3113: together, e.g., when `gnuplot` is run as a sub-process of some front-end
! 3114: application. Some of the demos, for example, might use this feature. While
! 3115: @ref{plot} options such as @ref{index} and @ref{every} are recognized, their use forces
! 3116: you to enter data that won't be used. For example, while
! 3117:
! 3118: @example
! 3119: plot '-' index 0, '-' index 1
! 3120: 2
! 3121: 4
! 3122: 6
! 3123:
! 3124: @end example
! 3125:
! 3126:
! 3127: @example
! 3128: 10
! 3129: 12
! 3130: 14
! 3131: e
! 3132: 2
! 3133: 4
! 3134: 6
! 3135:
! 3136: @end example
! 3137:
! 3138:
! 3139: @example
! 3140: 10
! 3141: 12
! 3142: 14
! 3143: e
! 3144:
! 3145: @end example
! 3146:
! 3147: does indeed work,
! 3148:
! 3149: @example
! 3150: plot '-', '-'
! 3151: 2
! 3152: 4
! 3153: 6
! 3154: e
! 3155: 10
! 3156: 12
! 3157: 14
! 3158: e
! 3159:
! 3160: @end example
! 3161:
! 3162: is a lot easier to type.
! 3163:
! 3164: If you use `'-'` with @ref{replot}, you may need to enter the data more than once
! 3165: (see @ref{replot}).
! 3166:
! 3167: A blank filename ('') specifies that the previous filename should be reused.
! 3168: This can be useful with things like
! 3169:
! 3170: @example
! 3171: plot 'a/very/long/filename' using 1:2, '' using 1:3, '' using 1:4
! 3172:
! 3173: @end example
! 3174:
! 3175: (If you use both `'-'` and `''` on the same @ref{plot} command, you'll need to
! 3176: have two sets of inline data, as in the example above.)
! 3177:
! 3178: On some computer systems with a popen function (Unix), the datafile can be
! 3179: piped through a shell command by starting the file name with a '<'. For
! 3180: example,
! 3181:
! 3182: @example
! 3183: pop(x) = 103*exp(-x/10)
! 3184: plot "< awk '@{print $1-1965, $2@}' population.dat", pop(x)
! 3185:
! 3186: @end example
! 3187:
! 3188: would plot the same information as the first population example but with
! 3189: years since 1965 as the x axis. If you want to execute this example, you
! 3190: have to delete all comments from the data file above or substitute the
! 3191: following command for the first part of the command above (the part up to
! 3192: the comma):
! 3193:
! 3194: @example
! 3195: plot "< awk '$0 !~ /^#/ @{print $1-1965, $2@}' population.dat"
! 3196:
! 3197: @end example
! 3198:
! 3199: While this approach is most flexible, it is possible to achieve simple
! 3200: filtering with the @ref{using} or @ref{thru} keywords.
! 3201:
! 3202: @node thru, using, special-filenames, data-file
! 3203: @subsubsection thru
! 3204:
! 3205: @c ?commands plot datafile thru
! 3206: @c ?plot datafile thru
! 3207: @c ?plot thru
! 3208: @c ?data-file thru
! 3209: @c ?datafile thru
! 3210: @cindex thru
! 3211:
! 3212: The @ref{thru} function is provided for backward compatibility.
! 3213:
! 3214: Syntax:
! 3215: @example
! 3216: plot 'file' thru f(x)
! 3217:
! 3218: @end example
! 3219:
! 3220: It is equivalent to:
! 3221:
! 3222: @example
! 3223: plot 'file' using 1:(f($2))
! 3224:
! 3225: @end example
! 3226:
! 3227: While the latter appears more complex, it is much more flexible. The more
! 3228: natural
! 3229:
! 3230: @example
! 3231: plot 'file' thru f(y)
! 3232:
! 3233: @end example
! 3234:
! 3235: also works (i.e. you can use y as the dummy variable).
! 3236:
! 3237: @ref{thru} is parsed for `splot` and `fit` but has no effect.
! 3238:
! 3239: @node using, , thru, data-file
! 3240: @subsubsection using
! 3241:
! 3242: @c ?commands plot datafile using
! 3243: @c ?plot datafile using
! 3244: @c ?plot using
! 3245: @c ?data-file using
! 3246: @c ?datafile using
! 3247: @cindex using
! 3248:
! 3249: The most common datafile modifier is @ref{using}.
! 3250:
! 3251: Syntax:
! 3252: @example
! 3253: plot 'file' using @{<entry> @{:<entry> @{:<entry> ...@}@}@} @{'format'@}
! 3254:
! 3255: @end example
! 3256:
! 3257: If a format is specified, each datafile record is read using the C library's
! 3258: 'scanf' function, with the specified format string. Otherwise the record is
! 3259: read and broken into columns at spaces or tabs. A format cannot be specified
! 3260: if time-format data is being used (this must be done by `set data time`).
! 3261:
! 3262: The resulting array of data is then sorted into columns according to the
! 3263: entries. Each <entry> may be a simple column number, which selects the
! 3264: datum, an expression enclosed in parentheses, or empty. The expression can
! 3265: use $1 to access the first item read, $2 for the second item, and so on. It
! 3266: can also use `column(x)` and `valid(x)` where x is an arbitrary expression
! 3267: resulting in an integer. `column(x)` returns the x'th datum; `valid(x)`
! 3268: tests that the datum in the x'th column is a valid number. A column number
! 3269: of 0 generates a number increasing (from zero) with each point, and is reset
! 3270: upon encountering two blank records. A column number of -1 gives the
! 3271: dataline number, which starts at 0, increments at single blank records, and
! 3272: is reset at double blank records. A column number of -2 gives the index
! 3273: number, which is incremented only when two blank records are found. An empty
! 3274: <entry> will default to its order in the list of entries. For example,
! 3275: `using ::4` is interpreted as `using 1:2:4`.
! 3276:
! 3277: N.B.---the @ref{call} command also uses $'s as a special character. See @ref{call}
! 3278: for details about how to include a column number in a @ref{call} argument list.
! 3279:
! 3280: If the @ref{using} list has but a single entry, that <entry> will be used for y
! 3281: and the data point number is used for x; for example, "`plot 'file' using 1`"
! 3282: is identical to "`plot 'file' using 0:1`". If the @ref{using} list has two
! 3283: entries, these will be used for x and y. Additional entries are usually
! 3284: errors in x and/or y. See @ref{style} for details about plotting styles that
! 3285: make use of error information, and `fit` for use of error information in
! 3286: curve fitting.
! 3287:
! 3288: 'scanf' accepts several numerical specifications but `gnuplot` requires all
! 3289: inputs to be double-precision floating-point variables, so `lf` is the only
! 3290: permissible specifier. 'scanf' expects to see white space---a blank, tab
! 3291: ("\t"), newline ("\n"), or formfeed ("\f")---between numbers; anything else
! 3292: in the input stream must be explicitly skipped.
! 3293:
! 3294: Note that the use of "\t", "\n", or "\f" or requires use of double-quotes
! 3295: rather than single-quotes.
! 3296:
! 3297: Examples:
! 3298:
! 3299: This creates a plot of the sum of the 2nd and 3rd data against the first:
! 3300: (The format string specifies comma- rather than space-separated columns.)
! 3301: @example
! 3302: plot 'file' using 1:($2+$3) '%lf,%lf,%lf'
! 3303:
! 3304: @end example
! 3305:
! 3306: In this example the data are read from the file "MyData" using a more
! 3307: complicated format:
! 3308: @example
! 3309: plot 'MyData' using "%*lf%lf%*20[^\n]%lf"
! 3310:
! 3311: @end example
! 3312:
! 3313: The meaning of this format is:
! 3314:
! 3315: @example
! 3316: %*lf ignore a number
! 3317: %lf read a double-precision number (x by default)
! 3318: %*20[^\n] ignore 20 non-newline characters
! 3319: %lf read a double-precision number (y by default)
! 3320:
! 3321: @end example
! 3322:
! 3323: One trick is to use the ternary `?:` operator to filter data:
! 3324:
! 3325: @example
! 3326: plot 'file' using 1:($3>10 ? $2 : 1/0)
! 3327:
! 3328: @end example
! 3329:
! 3330: which plots the datum in column two against that in column one provided
! 3331: the datum in column three exceeds ten. `1/0` is undefined; `gnuplot`
! 3332: quietly ignores undefined points, so unsuitable points are suppressed.
! 3333:
! 3334: In fact, you can use a constant expression for the column number, provided it
! 3335: doesn't start with an opening parenthesis; constructs like `using
! 3336: 0+(complicated expression)` can be used. The crucial point is that the
! 3337: expression is evaluated once if it doesn't start with a left parenthesis, or
! 3338: once for each data point read if it does.
! 3339:
! 3340: If timeseries data are being used, the time can span multiple columns. The
! 3341: starting column should be specified. Note that the spaces within the time
! 3342: must be included when calculating starting columns for other data. E.g., if
! 3343: the first element on a line is a time with an embedded space, the y value
! 3344: should be specified as column three.
! 3345:
! 3346: It should be noted that `plot 'file'`, `plot 'file' using 1:2`, and `plot
! 3347: 'file' using ($1):($2)` can be subtly different: 1) if `file` has some lines
! 3348: with one column and some with two, the first will invent x values when they
! 3349: are missing, the second will quietly ignore the lines with one column, and
! 3350: the third will store an undefined value for lines with one point (so that in
! 3351: a plot with lines, no line joins points across the bad point); 2) if a line
! 3352: contains text at the first column, the first will abort the plot on an error,
! 3353: but the second and third should quietly skip the garbage.
! 3354:
! 3355: In fact, it is often possible to plot a file with lots of lines of garbage at
! 3356: the top simply by specifying
! 3357:
! 3358: @example
! 3359: plot 'file' using 1:2
! 3360:
! 3361: @end example
! 3362:
! 3363: However, if you want to leave text in your data files, it is safer to put the
! 3364: comment character (#) in the first column of the text lines.
! 3365: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/using.html,Feeble using demos. }
! 3366:
! 3367: @node errorbars, parametric, data-file, plot
! 3368: @subsection errorbars
! 3369:
! 3370: @c ?commands plot errorbars
! 3371: @c ?commands splot errorbars
! 3372: @c ?plot errorbars
! 3373: @c ?splot errorbars
! 3374: @cindex errorbars
! 3375:
! 3376: Error bars are supported for 2-d data file plots by reading one to four
! 3377: additional columns (or @ref{using} entries); these additional values are used in
! 3378: different ways by the various errorbar styles.
! 3379:
! 3380: In the default situation, `gnuplot` expects to see three, four, or six
! 3381: numbers on each line of the data file---either
! 3382:
! 3383: @example
! 3384: (x, y, ydelta),
! 3385: (x, y, ylow, yhigh),
! 3386: (x, y, xdelta),
! 3387: (x, y, xlow, xhigh),
! 3388: (x, y, xdelta, ydelta), or
! 3389: (x, y, xlow, xhigh, ylow, yhigh).
! 3390:
! 3391: @end example
! 3392:
! 3393: The x coordinate must be specified. The order of the numbers must be
! 3394: exactly as given above, though the @ref{using} qualifier can manipulate the order
! 3395: and provide values for missing columns. For example,
! 3396:
! 3397: @example
! 3398: plot 'file' with errorbars
! 3399: plot 'file' using 1:2:(sqrt($1)) with xerrorbars
! 3400: plot 'file' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars
! 3401:
! 3402: @end example
! 3403:
! 3404: The last example is for a file containing an unsupported combination of
! 3405: relative x and absolute y errors. The @ref{using} entry generates absolute x min
! 3406: and max from the relative error.
! 3407:
! 3408: The y error bar is a vertical line plotted from (x, ylow) to (x, yhigh).
! 3409: If ydelta is specified instead of ylow and yhigh, ylow = y - ydelta and
! 3410: yhigh = y + ydelta are derived. If there are only two numbers on the record,
! 3411: yhigh and ylow are both set to y. The x error bar is a horizontal line
! 3412: computed in the same fashion. To get lines plotted between the data points,
! 3413: @ref{plot} the data file twice, once with errorbars and once with lines (but
! 3414: remember to use the `notitle` option on one to avoid two entries in the key).
! 3415:
! 3416: The error bars have crossbars at each end unless @ref{bar} is used (see @ref{bar} for details).
! 3417:
! 3418: If autoscaling is on, the ranges will be adjusted to include the error bars.
! 3419: @uref{http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html,Errorbar demos. }
! 3420:
! 3421: See @ref{using}, @ref{with}, and @ref{style} for more information.
! 3422:
! 3423: @node parametric, ranges, errorbars, plot
! 3424: @subsection parametric
! 3425:
! 3426: @c ?commands plot parametric
! 3427: @c ?commands splot parametric
! 3428: @c ?plot parametric
! 3429: @c ?splot parametric
! 3430: @cindex parametric
! 3431: @opindex parametric
! 3432:
! 3433:
! 3434: When in parametric mode (`set parametric`) mathematical expressions must be
! 3435: given in pairs for @ref{plot} and in triplets for `splot`.
! 3436:
! 3437: Examples:
! 3438: @example
! 3439: plot sin(t),t**2
! 3440: splot cos(u)*cos(v),cos(u)*sin(v),sin(u)
! 3441:
! 3442: @end example
! 3443:
! 3444: Data files are plotted as before, except any preceding parametric function
! 3445: must be fully specified before a data file is given as a plot. In other
! 3446: words, the x parametric function (`sin(t)` above) and the y parametric
! 3447: function (`t**2` above) must not be interrupted with any modifiers or data
! 3448: functions; doing so will generate a syntax error stating that the parametric
! 3449: function is not fully specified.
! 3450:
! 3451: Other modifiers, such as @ref{with} and `title`, may be specified only after the
! 3452: parametric function has been completed:
! 3453:
! 3454: @example
! 3455: plot sin(t),t**2 title 'Parametric example' with linespoints
! 3456: @end example
! 3457:
! 3458: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/param.html,Parametric Mode Demos. }
! 3459:
! 3460: @node ranges, title, parametric, plot
! 3461: @subsection ranges
! 3462:
! 3463: @c ?commands plot ranges
! 3464: @c ?commands splot ranges
! 3465: @c ?plot ranges
! 3466: @c ?splot ranges
! 3467: @cindex ranges
! 3468:
! 3469: The optional ranges specify the region of the graph that will be displayed.
! 3470:
! 3471: Syntax:
! 3472: @example
! 3473: [@{<dummy-var>=@}@{@{<min>@}:@{<max>@}@}]
! 3474: [@{@{<min>@}:@{<max>@}@}]
! 3475:
! 3476: @end example
! 3477:
! 3478: The first form applies to the independent variable (@ref{xrange} or @ref{trange}, if
! 3479: in parametric mode). The second form applies to the dependent variable
! 3480: @ref{yrange} (and @ref{xrange}, too, if in parametric mode). <dummy-var> is a new
! 3481: name for the independent variable. (The defaults may be changed with @ref{dummy}.) The optional <min> and <max> terms can be constant expressions or *.
! 3482:
! 3483: In non-parametric mode, the order in which ranges must be given is @ref{xrange}
! 3484: and @ref{yrange}.
! 3485:
! 3486: In parametric mode, the order for the @ref{plot} command is @ref{trange}, @ref{xrange},
! 3487: and @ref{yrange}. The following @ref{plot} command shows setting the @ref{trange} to
! 3488: [-pi:pi], the @ref{xrange} to [-1.3:1.3] and the @ref{yrange} to [-1:1] for the
! 3489: duration of the graph:
! 3490:
! 3491: @example
! 3492: plot [-pi:pi] [-1.3:1.3] [-1:1] sin(t),t**2
! 3493:
! 3494: @end example
! 3495:
! 3496: Note that the x2range and y2range cannot be specified here---@ref{x2range}
! 3497: and @ref{y2range} must be used.
! 3498:
! 3499: Ranges are interpreted in the order listed above for the appropriate mode.
! 3500: Once all those needed are specified, no further ones must be listed, but
! 3501: unneeded ones cannot be skipped---use an empty range `[]` as a placeholder.
! 3502:
! 3503: `*` can be used to allow autoscaling of either of min and max. See also
! 3504: @ref{autoscale}.
! 3505:
! 3506: Ranges specified on the @ref{plot} or `splot` command line affect only that
! 3507: graph; use the @ref{xrange}, @ref{yrange}, etc., commands to change the
! 3508: default ranges for future graphs.
! 3509:
! 3510: With time data, you must provide the range (in the same manner as the time
! 3511: appears in the datafile) within quotes. `gnuplot` uses the @ref{timefmt} string
! 3512: to read the value---see @ref{timefmt}.
! 3513:
! 3514: Examples:
! 3515:
! 3516: This uses the current ranges:
! 3517: @example
! 3518: plot cos(x)
! 3519:
! 3520: @end example
! 3521:
! 3522: This sets the x range only:
! 3523: @example
! 3524: plot [-10:30] sin(pi*x)/(pi*x)
! 3525:
! 3526: @end example
! 3527:
! 3528: This is the same, but uses t as the dummy-variable:
! 3529: @example
! 3530: plot [t = -10 :30] sin(pi*t)/(pi*t)
! 3531:
! 3532: @end example
! 3533:
! 3534: This sets both the x and y ranges:
! 3535: @example
! 3536: plot [-pi:pi] [-3:3] tan(x), 1/x
! 3537:
! 3538: @end example
! 3539:
! 3540: This sets only the y range, and turns off autoscaling on both axes:
! 3541: @example
! 3542: plot [ ] [-2:sin(5)*-8] sin(x)**besj0(x)
! 3543:
! 3544: @end example
! 3545:
! 3546: This sets xmax and ymin only:
! 3547: @example
! 3548: plot [:200] [-pi:] exp(sin(x))
! 3549:
! 3550: @end example
! 3551:
! 3552: This sets the x range for a timeseries:
! 3553: @example
! 3554: set timefmt "%d/%m/%y %H:%M"
! 3555: plot ["1/6/93 12:00":"5/6/93 12:00"] 'timedata.dat'
! 3556:
! 3557: @end example
! 3558:
! 3559: @uref{http://www.nas.nasa.gov/~woo/gnuplot/ranges/ranges.html,See Demo. }
! 3560:
! 3561: @node title, with, ranges, plot
! 3562: @subsection title
! 3563:
! 3564: @c ?commands plot title
! 3565: @c ?commands splot title
! 3566: @c ?plot title
! 3567: @c ?splot title
! 3568: A line title for each function and data set appears in the key, accompanied
! 3569: by a sample of the line and/or symbol used to represent it. It can be
! 3570: changed by using the `title` option.
! 3571:
! 3572: Syntax:
! 3573: @example
! 3574: title "<title>" | notitle
! 3575:
! 3576: @end example
! 3577:
! 3578: where <title> is the new title of the line and must be enclosed in quotes.
! 3579: The quotes will not be shown in the key. A special character may be given as
! 3580: a backslash followed by its octal value ("\345"). The tab character "\t" is
! 3581: understood. Note that backslash processing occurs only for strings enclosed
! 3582: in double quotes---use single quotes to prevent such processing. The newline
! 3583: character "\n" is not processed in key entries in either type of string.
! 3584:
! 3585: The line title and sample can be omitted from the key by using the keyword
! 3586: `notitle`. A null title (`title ''`) is equivalent to `notitle`. If only
! 3587: the sample is wanted, use one or more blanks (`title ' '`).
! 3588:
! 3589: By default the line title is the function or file name as it appears on the
! 3590: @ref{plot} command. If it is a file name, any datafile modifiers specified will
! 3591: be included in the default title.
! 3592:
! 3593: The layout of the key itself (position, title justification, etc.) can be
! 3594: controlled by @ref{key}. Please see @ref{key} for details.
! 3595:
! 3596: Examples:
! 3597:
! 3598: This plots y=x with the title 'x':
! 3599: @example
! 3600: plot x
! 3601:
! 3602: @end example
! 3603:
! 3604: This plots x squared with title "x^2" and file "data.1" with title
! 3605: "measured data":
! 3606: @example
! 3607: plot x**2 title "x^2", 'data.1' t "measured data"
! 3608:
! 3609: @end example
! 3610:
! 3611: This puts an untitled circular border around a polar graph:
! 3612: @example
! 3613: set polar; plot my_function(t), 1 notitle
! 3614:
! 3615: @end example
! 3616:
! 3617: @node with, , title, plot
! 3618: @subsection with
! 3619:
! 3620: @c ?commands plot with
! 3621: @c ?commands splot with
! 3622: @c ?commands plot style
! 3623: @c ?commands splot style
! 3624: @c ?plot with
! 3625: @c ?plot style
! 3626: @c ?splot with
! 3627: @c ?splot style
! 3628: @cindex style
! 3629: @opindex style
! 3630:
! 3631:
! 3632: @cindex with
! 3633:
! 3634: Functions and data may be displayed in one of a large number of styles.
! 3635: The @ref{with} keyword provides the means of selection.
! 3636:
! 3637: Syntax:
! 3638: @example
! 3639: with <style> @{ @{linestyle | ls <line_style>@}
! 3640: | @{@{linetype | lt <line_type>@}
! 3641: @{linewidth | lw <line_width>@}
! 3642: @{pointtype | pt <point_type>@}
! 3643: @{pointsize | ps <point_size>@}@} @}
! 3644:
! 3645: @end example
! 3646:
! 3647: where <style> is either `lines`, `points`, @ref{linespoints}, @ref{impulses}, @ref{dots},
! 3648: @ref{steps}, @ref{fsteps}, @ref{histeps}, @ref{errorbars}, @ref{xerrorbars}, @ref{yerrorbars},
! 3649: @ref{xyerrorbars}, @ref{boxes}, @ref{boxerrorbars}, @ref{boxxyerrorbars}, @ref{financebars},
! 3650: @ref{candlesticks} or @ref{vector}. Some of these styles require additional
! 3651: information. See `set style <style>` for details of each style.
! 3652:
! 3653: Default styles are chosen with the @ref{style} and @ref{style}
! 3654: commands.
! 3655:
! 3656: By default, each function and data file will use a different line type and
! 3657: point type, up to the maximum number of available types. All terminal
! 3658: drivers support at least six different point types, and re-use them, in
! 3659: order, if more are required. The LaTeX driver supplies an additional six
! 3660: point types (all variants of a circle), and thus will only repeat after 12
! 3661: curves are plotted with points. The PostScript drivers (`postscript`)
! 3662: supplies a total of 64.
! 3663:
! 3664: If you wish to choose the line or point type for a single plot, <line_type>
! 3665: and <point_type> may be specified. These are positive integer constants (or
! 3666: expressions) that specify the line type and point type to be used for the
! 3667: plot. Use @ref{test} to display the types available for your terminal.
! 3668:
! 3669: You may also scale the line width and point size for a plot by using
! 3670: <line_width> and <point_size>, which are specified relative to the default
! 3671: values for each terminal. The pointsize may also be altered globally---see
! 3672: @ref{pointsize} for details. But note that both <point_size> as set here and
! 3673: as set by @ref{pointsize} multiply the default point size---their effects are
! 3674: not cumulative. That is, `set pointsize 2; plot x w p ps 3` will use points
! 3675: three times default size, not six.
! 3676:
! 3677: If you have defined specific line type/width and point type/size combinations
! 3678: with @ref{linestyle}, one of these may be selected by setting <line_style> to
! 3679: the index of the desired style.
! 3680:
! 3681: The keywords may be abbreviated as indicated.
! 3682:
! 3683: Note that the `linewidth` and @ref{pointsize} options are not supported by all
! 3684: terminals.
! 3685:
! 3686: Examples:
! 3687:
! 3688: This plots sin(x) with impulses:
! 3689: @example
! 3690: plot sin(x) with impulses
! 3691:
! 3692: @end example
! 3693:
! 3694: This plots x with points, x**2 with the default:
! 3695: @example
! 3696: plot x*y w points, x**2 + y**2
! 3697:
! 3698: @end example
! 3699:
! 3700: This plots tan(x) with the default function style, file "data.1" with lines:
! 3701: @example
! 3702: plot [ ] [-2:5] tan(x), 'data.1' with l
! 3703:
! 3704: @end example
! 3705:
! 3706: This plots "leastsq.dat" with impulses:
! 3707: @example
! 3708: plot 'leastsq.dat' w i
! 3709:
! 3710: @end example
! 3711:
! 3712: This plots the data file "population" with boxes:
! 3713: @example
! 3714: plot 'population' with boxes
! 3715:
! 3716: @end example
! 3717:
! 3718: This plots "exper.dat" with errorbars and lines connecting the points
! 3719: (errorbars require three or four columns):
! 3720: @example
! 3721: plot 'exper.dat' w lines, 'exper.dat' notitle w errorbars
! 3722:
! 3723: @end example
! 3724:
! 3725: This plots sin(x) and cos(x) with linespoints, using the same line type but
! 3726: different point types:
! 3727: @example
! 3728: plot sin(x) with linesp lt 1 pt 3, cos(x) with linesp lt 1 pt 4
! 3729:
! 3730: @end example
! 3731:
! 3732: This plots file "data" with points of type 3 and twice usual size:
! 3733: @example
! 3734: plot 'data' with points pointtype 3 pointsize 2
! 3735:
! 3736: @end example
! 3737:
! 3738: This plots two data sets with lines differing only by weight:
! 3739: @example
! 3740: plot 'd1' t "good" w l lt 2 lw 3, 'd2' t "bad" w l lt 2 lw 1
! 3741:
! 3742: @end example
! 3743:
! 3744: See @ref{style} to change the default styles.
! 3745: @uref{http://www.nas.nasa.gov/~woo/gnuplot/styles/styles.html,Styles demos. }
! 3746:
! 3747: @node print, pwd, plot, Commands
! 3748: @section print
! 3749:
! 3750: @c ?commands print
! 3751: @cindex print
! 3752: @cmindex print
! 3753:
! 3754:
! 3755: The @ref{print} command prints the value of <expression> to the screen. It is
! 3756: synonymous with `pause 0`. <expression> may be anything that `gnuplot` can
! 3757: evaluate that produces a number, or it can be a string.
! 3758:
! 3759: Syntax:
! 3760: @example
! 3761: print <expression> @{, <expression>, ...@}
! 3762:
! 3763: @end example
! 3764:
! 3765: See `expressions`.
! 3766:
! 3767: @node pwd, quit, print, Commands
! 3768: @section pwd
! 3769:
! 3770: @c ?commands pwd
! 3771: @cindex pwd
! 3772: @cmindex pwd
! 3773:
! 3774:
! 3775: The @ref{pwd} command prints the name of the working directory to the screen.
! 3776:
! 3777: @node quit, replot, pwd, Commands
! 3778: @section quit
! 3779:
! 3780: @c ?commands quit
! 3781: @cindex quit
! 3782: @cmindex quit
! 3783:
! 3784:
! 3785: The @ref{exit} and @ref{quit} commands and END-OF-FILE character will exit `gnuplot`.
! 3786: Each of these commands will clear the output device (as does the @ref{clear}
! 3787: command) before exiting.
! 3788:
! 3789: @node replot, reread, quit, Commands
! 3790: @section replot
! 3791:
! 3792: @c ?commands replot
! 3793: @cindex replot
! 3794: @cmindex replot
! 3795:
! 3796:
! 3797: The @ref{replot} command without arguments repeats the last @ref{plot} or `splot`
! 3798: command. This can be useful for viewing a plot with different `set` options,
! 3799: or when generating the same plot for several devices.
! 3800:
! 3801: Arguments specified after a @ref{replot} command will be added onto the last
! 3802: @ref{plot} or `splot` command (with an implied ',' separator) before it is
! 3803: repeated. @ref{replot} accepts the same arguments as the @ref{plot} and `splot`
! 3804: commands except that ranges cannot be specified. Thus you can use @ref{replot}
! 3805: to plot a function against the second axes if the previous command was @ref{plot}
! 3806: but not if it was `splot`, and similarly you can use @ref{replot} to add a plot
! 3807: from a binary file only if the previous command was `splot`.
! 3808:
! 3809: N.B.---use of
! 3810:
! 3811: @example
! 3812: plot '-' ; ... ; replot
! 3813:
! 3814: @end example
! 3815:
! 3816: is not recommended. `gnuplot` does not store the inline data internally, so
! 3817: since @ref{replot} appends new information to the previous @ref{plot} and then
! 3818: executes the modified command, the `'-'` from the initial @ref{plot} will expect
! 3819: to read inline data again.
! 3820:
! 3821: Note that @ref{replot} does not work in @ref{multiplot} mode, since it reproduces
! 3822: only the last plot rather than the entire screen.
! 3823:
! 3824: See also `command-line-editing` for ways to edit the last @ref{plot} (`splot`)
! 3825: command.
! 3826:
! 3827: @node reread, reset, replot, Commands
! 3828: @section reread
! 3829:
! 3830: @c ?commands reread
! 3831: @cindex reread
! 3832: @cmindex reread
! 3833:
! 3834:
! 3835: The @ref{reread} command causes the current `gnuplot` command file, as specified
! 3836: by a @ref{load} command or on the command line, to be reset to its starting
! 3837: point before further commands are read from it. This essentially implements
! 3838: an endless loop of the commands from the beginning of the command file to
! 3839: the @ref{reread} command. (But this is not necessarily a disaster---@ref{reread} can
! 3840: be very useful when used in conjunction with @ref{if}. See @ref{if} for details.)
! 3841: The @ref{reread} command has no effect if input from standard input.
! 3842:
! 3843: Examples:
! 3844:
! 3845: Suppose the file "looper" contains the commands
! 3846: @example
! 3847: a=a+1
! 3848: plot sin(x*a)
! 3849: pause -1
! 3850: if(a<5) reread
! 3851: @end example
! 3852:
! 3853: and from within `gnuplot` you submit the commands
! 3854: @example
! 3855: a=0
! 3856: load 'looper'
! 3857: @end example
! 3858:
! 3859: The result will be four plots (separated by the @ref{pause} message).
! 3860:
! 3861: Suppose the file "data" contains six columns of numbers with a total yrange
! 3862: from 0 to 10; the first is x and the next are five different functions of x.
! 3863: Suppose also that the file "plotter" contains the commands
! 3864: @example
! 3865: c_p = c_p+1
! 3866: plot "$0" using 1:c_p with lines linetype c_p
! 3867: if(c_p < n_p) reread
! 3868: @end example
! 3869:
! 3870: and from within `gnuplot` you submit the commands
! 3871: @example
! 3872: n_p=6
! 3873: c_p=1
! 3874: set nokey
! 3875: set yrange [0:10]
! 3876: set multiplot
! 3877: call 'plotter' 'data'
! 3878: set nomultiplot
! 3879: @end example
! 3880:
! 3881: The result is a single graph consisting of five plots. The yrange must be
! 3882: set explicitly to guarantee that the five separate graphs (drawn on top of
! 3883: each other in multiplot mode) will have exactly the same axes. The linetype
! 3884: must be specified; otherwise all the plots would be drawn with the same type.
! 3885: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/animate.html,Reread Animation Demo}
! 3886:
! 3887: @node reset, save, reread, Commands
! 3888: @section reset
! 3889:
! 3890: @c ?commands reset
! 3891: @cindex reset
! 3892: @cmindex reset
! 3893:
! 3894:
! 3895: The @ref{reset} command causes all options that can be set with the `set`
! 3896: command to take on their default values. The only exceptions are that the
! 3897: terminal set with `set term` and the output file set with @ref{output} are
! 3898: left unchanged. This command is useful, e.g., to restore the default
! 3899: settings at the end of a command file, or to return to a defined state after
! 3900: lots of settings have been changed within a command file. Please refer to
! 3901: the `set` command to see the default values that the various options take.
! 3902:
! 3903: @node save, set-show, reset, Commands
! 3904: @section save
! 3905:
! 3906: @c ?commands save
! 3907: @cindex save
! 3908: @cmindex save
! 3909:
! 3910:
! 3911: The @ref{save} command saves user-defined functions, variables, `set` options,
! 3912: or all three, plus the last @ref{plot} (`splot`) command to the specified file.
! 3913:
! 3914: Syntax:
! 3915: @example
! 3916: save @{<option>@} '<filename>'
! 3917:
! 3918: @end example
! 3919:
! 3920: where <option> is @ref{functions}, @ref{variables} or `set`. If no option is used,
! 3921: `gnuplot` saves functions, variables, `set` options and the last @ref{plot}
! 3922: (`splot`) command.
! 3923:
! 3924: @ref{save}d files are written in text format and may be read by the @ref{load}
! 3925: command.
! 3926:
! 3927: The filename must be enclosed in quotes.
! 3928:
! 3929: Examples:
! 3930: @example
! 3931: save 'work.gnu'
! 3932: save functions 'func.dat'
! 3933: save var 'var.dat'
! 3934: save set 'options.dat'
! 3935:
! 3936: @end example
! 3937:
! 3938: @node set-show, shell, save, Commands
! 3939: @section set-show
! 3940:
! 3941: @c ?commands set
! 3942: @c ?commands show
! 3943: @cindex set
! 3944:
! 3945: @cindex show
! 3946:
! 3947: @c ?show all
! 3948: The `set` command can be used to sets _lots_ of options. No screen is
! 3949: drawn, however, until a @ref{plot}, `splot`, or @ref{replot} command is given.
! 3950:
! 3951: The `show` command shows their settings; `show all` shows all the
! 3952: settings.
! 3953:
! 3954: If a variable contains time/date data, `show` will display it according to
! 3955: the format currently defined by @ref{timefmt}, even if that was not in effect
! 3956: when the variable was initially defined.
! 3957:
! 3958: @menu
! 3959: * angles::
! 3960: * arrow::
! 3961: * autoscale::
! 3962: * bar::
! 3963: * bmargin::
! 3964: * border::
! 3965: * boxwidth::
! 3966: * clabel::
! 3967: * clip::
! 3968: * cntrparam::
! 3969: * contour::
! 3970: * data_style::
! 3971: * dgrid3d::
! 3972: * dummy::
! 3973: * encoding::
! 3974: * format::
! 3975: * function_style::
! 3976: * functions::
! 3977: * grid::
! 3978: * hidden3d::
! 3979: * isosamples::
! 3980: * key::
! 3981: * label::
! 3982: * linestyle::
! 3983: * lmargin::
! 3984: * locale::
! 3985: * logscale::
! 3986: * mapping::
! 3987: * margin::
! 3988: * missing::
! 3989: * multiplot::
! 3990: * mx2tics::
! 3991: * mxtics::
! 3992: * my2tics::
! 3993: * mytics::
! 3994: * mztics::
! 3995: * offsets::
! 3996: * origin::
! 3997: * output::
! 3998: * parametric_::
! 3999: * pointsize::
! 4000: * polar::
! 4001: * rmargin::
! 4002: * rrange::
! 4003: * samples::
! 4004: * size::
! 4005: * style::
! 4006: * surface::
! 4007: * terminal::
! 4008: * tics::
! 4009: * ticslevel::
! 4010: * ticscale::
! 4011: * timestamp::
! 4012: * timefmt::
! 4013: * title_::
! 4014: * tmargin::
! 4015: * trange::
! 4016: * urange::
! 4017: * variables::
! 4018: * version::
! 4019: * view::
! 4020: * vrange::
! 4021: * x2data::
! 4022: * x2dtics::
! 4023: * x2label::
! 4024: * x2mtics::
! 4025: * x2range::
! 4026: * x2tics::
! 4027: * x2zeroaxis::
! 4028: * xdata::
! 4029: * xdtics::
! 4030: * xlabel::
! 4031: * xmtics::
! 4032: * xrange::
! 4033: * xtics::
! 4034: * xzeroaxis::
! 4035: * y2data::
! 4036: * y2dtics::
! 4037: * y2label::
! 4038: * y2mtics::
! 4039: * y2range::
! 4040: * y2tics::
! 4041: * y2zeroaxis::
! 4042: * ydata::
! 4043: * ydtics::
! 4044: * ylabel::
! 4045: * ymtics::
! 4046: * yrange::
! 4047: * ytics::
! 4048: * yzeroaxis::
! 4049: * zdata::
! 4050: * zdtics::
! 4051: * zero::
! 4052: * zeroaxis::
! 4053: * zlabel::
! 4054: * zmtics::
! 4055: * zrange::
! 4056: * ztics::
! 4057: @end menu
! 4058:
! 4059: @node angles, arrow, set-show, set-show
! 4060: @subsection angles
! 4061:
! 4062: @c ?commands set angles
! 4063: @c ?commands show angles
! 4064: @c ?set angles
! 4065: @c ?show angles
! 4066: @cindex angles
! 4067: @opindex angles
! 4068:
! 4069:
! 4070: @c ?commands set angles degrees
! 4071: @c ?set angles degrees
! 4072: @c ?angles degrees
! 4073: @cindex degrees
! 4074:
! 4075: By default, `gnuplot` assumes the independent variable in polar graphs is in
! 4076: units of radians. If `set angles degrees` is specified before `set polar`,
! 4077: then the default range is [0:360] and the independent variable has units of
! 4078: degrees. This is particularly useful for plots of data files. The angle
! 4079: setting also applies to 3-d mapping as set via the @ref{mapping} command.
! 4080:
! 4081: Syntax:
! 4082: @example
! 4083: set angles @{degrees | radians@}
! 4084: show angles
! 4085:
! 4086: @end example
! 4087:
! 4088: The angle specified in `set grid polar` is also read and displayed in the
! 4089: units specified by @ref{angles}.
! 4090:
! 4091: @ref{angles} also affects the arguments of the machine-defined functions
! 4092: sin(x), cos(x) and tan(x), and the outputs of asin(x), acos(x), atan(x),
! 4093: atan2(x), and arg(x). It has no effect on the arguments of hyperbolic
! 4094: functions or Bessel functions. However, the output arguments of inverse
! 4095: hyperbolic functions of complex arguments are affected; if these functions
! 4096: are used, `set angles radians` must be in effect to maintain consistency
! 4097: between input and output arguments.
! 4098:
! 4099: @example
! 4100: x=@{1.0,0.1@}
! 4101: set angles radians
! 4102: y=sinh(x)
! 4103: print y #prints @{1.16933, 0.154051@}
! 4104: print asinh(y) #prints @{1.0, 0.1@}
! 4105: @end example
! 4106:
! 4107: but
! 4108: @example
! 4109: set angles degrees
! 4110: y=sinh(x)
! 4111: print y #prints @{1.16933, 0.154051@}
! 4112: print asinh(y) #prints @{57.29578, 5.729578@}
! 4113: @end example
! 4114:
! 4115: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html,Polar plot using @ref{angles}. }
! 4116:
! 4117: @node arrow, autoscale, angles, set-show
! 4118: @subsection arrow
! 4119:
! 4120: @c ?commands set arrow
! 4121: @c ?commands set noarrow
! 4122: @c ?commands show arrow
! 4123: @c ?set arrow
! 4124: @c ?set noarrow
! 4125: @c ?show arrow
! 4126: @cindex arrow
! 4127: @opindex arrow
! 4128:
! 4129:
! 4130: @cindex noarrow
! 4131:
! 4132: Arbitrary arrows can be placed on a plot using the @ref{arrow} command.
! 4133:
! 4134: Syntax:
! 4135: @example
! 4136: set arrow @{<tag>@} @{from <position>@} @{to <position>@} @{@{no@}head@}
! 4137: @{ @{linestyle | ls <line_style>@}
! 4138: | @{linetype | lt <line_type>@}
! 4139: @{linewidth | lw <line_width@} @}
! 4140: set noarrow @{<tag>@}
! 4141: show arrow
! 4142:
! 4143: @end example
! 4144:
! 4145: <tag> is an integer that identifies the arrow. If no tag is given, the
! 4146: lowest unused tag value is assigned automatically. The tag can be used to
! 4147: delete or change a specific arrow. To change any attribute of an existing
! 4148: arrow, use the @ref{arrow} command with the appropriate tag and specify the
! 4149: parts of the arrow to be changed.
! 4150:
! 4151: The <position>s are specified by either x,y or x,y,z, and may be preceded by
! 4152: `first`, `second`, `graph`, or `screen` to select the coordinate system.
! 4153: Unspecified coordinates default to 0. The endpoints can be specified in
! 4154: one of four coordinate systems---`first` or `second` axes, `graph` or
! 4155: `screen`. See `coordinates` for details. A coordinate system specifier
! 4156: does not carry over from the "from" position to the "to" position. Arrows
! 4157: outside the screen boundaries are permitted but may cause device errors.
! 4158:
! 4159: Specifying `nohead` produces an arrow drawn without a head---a line segment.
! 4160: This gives you yet another way to draw a line segment on the plot. By
! 4161: default, arrows have heads.
! 4162:
! 4163: The line style may be selected from a user-defined list of line styles (see
! 4164: @ref{linestyle}) or may be defined here by providing values for <line_type>
! 4165: (an index from the default list of styles) and/or <line_width> (which is a
! 4166: multiplier for the default width).
! 4167:
! 4168: Note, however, that if a user-defined line style has been selected, its
! 4169: properties (type and width) cannot be altered merely by issuing another
! 4170: @ref{arrow} command with the appropriate index and `lt` or `lw`.
! 4171:
! 4172: Examples:
! 4173:
! 4174: To set an arrow pointing from the origin to (1,2) with user-defined style 5,
! 4175: use:
! 4176: @example
! 4177: set arrow to 1,2 ls 5
! 4178:
! 4179: @end example
! 4180:
! 4181: To set an arrow from bottom left of plotting area to (-5,5,3), and tag the
! 4182: arrow number 3, use:
! 4183: @example
! 4184: set arrow 3 from graph 0,0 to -5,5,3
! 4185:
! 4186: @end example
! 4187:
! 4188: To change the preceding arrow to end at 1,1,1, without an arrow head and
! 4189: double its width, use:
! 4190: @example
! 4191: set arrow 3 to 1,1,1 nohead lw 2
! 4192:
! 4193: @end example
! 4194:
! 4195: To draw a vertical line from the bottom to the top of the graph at x=3, use:
! 4196: @example
! 4197: set arrow from 3, graph 0 to 3, graph 1 nohead
! 4198:
! 4199: @end example
! 4200:
! 4201: To delete arrow number 2, use:
! 4202: @example
! 4203: set noarrow 2
! 4204:
! 4205: @end example
! 4206:
! 4207: To delete all arrows, use:
! 4208: @example
! 4209: set noarrow
! 4210:
! 4211: @end example
! 4212:
! 4213: To show all arrows (in tag order), use:
! 4214: @example
! 4215: show arrow
! 4216: @end example
! 4217:
! 4218: @uref{http://www.nas.nasa.gov/~woo/gnuplot/arrows/arrows.html,Arrows Demos. }
! 4219:
! 4220: @node autoscale, bar, arrow, set-show
! 4221: @subsection autoscale
! 4222:
! 4223: @c ?commands set autoscale
! 4224: @c ?commands set noautoscale
! 4225: @c ?commands show autoscale
! 4226: @c ?set autoscale
! 4227: @c ?set noautoscale
! 4228: @c ?show autoscale
! 4229: @cindex autoscale
! 4230: @opindex autoscale
! 4231:
! 4232:
! 4233: @cindex noautoscale
! 4234:
! 4235: Autoscaling may be set individually on the x, y or z axis or globally on all
! 4236: axes. The default is to autoscale all axes.
! 4237:
! 4238: Syntax:
! 4239: @example
! 4240: set autoscale @{<axes>@{min|max@}@}
! 4241: set noautoscale @{<axes>@{min|max@}@}
! 4242: show autoscale
! 4243:
! 4244: @end example
! 4245:
! 4246: where <axes> is either `x`, `y`, `z`, `x2`, `y2` or `xy`. A keyword with
! 4247: `min` or `max` appended (this cannot be done with `xy`) tells `gnuplot` to
! 4248: autoscale just the minimum or maximum of that axis. If no keyword is given,
! 4249: all axes are autoscaled.
! 4250:
! 4251: When autoscaling, the axis range is automatically computed and the dependent
! 4252: axis (y for a @ref{plot} and z for `splot`) is scaled to include the range of the
! 4253: function or data being plotted.
! 4254:
! 4255: If autoscaling of the dependent axis (y or z) is not set, the current y or z
! 4256: range is used.
! 4257:
! 4258: Autoscaling the independent variables (x for @ref{plot} and x,y for `splot`) is a
! 4259: request to set the domain to match any data file being plotted. If there are
! 4260: no data files, autoscaling an independent variable has no effect. In other
! 4261: words, in the absence of a data file, functions alone do not affect the x
! 4262: range (or the y range if plotting z = f(x,y)).
! 4263:
! 4264: Please see @ref{xrange} for additional information about ranges.
! 4265:
! 4266: The behavior of autoscaling remains consistent in parametric mode, (see `set
! 4267: parametric`). However, there are more dependent variables and hence more
! 4268: control over x, y, and z axis scales. In parametric mode, the independent or
! 4269: dummy variable is t for @ref{plot}s and u,v for `splot`s. @ref{autoscale} in
! 4270: parametric mode, then, controls all ranges (t, u, v, x, y, and z) and allows
! 4271: x, y, and z to be fully autoscaled.
! 4272:
! 4273: Autoscaling works the same way for polar mode as it does for parametric mode
! 4274: for @ref{plot}, with the extension that in polar mode @ref{dummy} can be used to
! 4275: change the independent variable from t (see @ref{dummy}).
! 4276:
! 4277: When tics are displayed on second axes but no plot has been specified for
! 4278: those axes, x2range and y2range are inherited from xrange and yrange. This
! 4279: is done _before_ xrange and yrange are autoextended to a whole number of
! 4280: tics, which can cause unexpected results.
! 4281:
! 4282: Examples:
! 4283:
! 4284: This sets autoscaling of the y axis (other axes are not affected):
! 4285: @example
! 4286: set autoscale y
! 4287:
! 4288: @end example
! 4289:
! 4290: This sets autoscaling only for the minimum of the y axis (the maximum of the
! 4291: y axis and the other axes are not affected):
! 4292: @example
! 4293: set autoscale ymin
! 4294:
! 4295: @end example
! 4296:
! 4297: This sets autoscaling of the x and y axes:
! 4298: @example
! 4299: set autoscale xy
! 4300:
! 4301: @end example
! 4302:
! 4303: This sets autoscaling of the x, y, z, x2 and y2 axes:
! 4304: @example
! 4305: set autoscale
! 4306:
! 4307: @end example
! 4308:
! 4309: This disables autoscaling of the x, y, z, x2 and y2 axes:
! 4310: @example
! 4311: set noautoscale
! 4312:
! 4313: @end example
! 4314:
! 4315: This disables autoscaling of the z axis only:
! 4316: @example
! 4317: set noautoscale z
! 4318:
! 4319: @end example
! 4320:
! 4321: @menu
! 4322: * parametric_mode::
! 4323: * polar_mode::
! 4324: @end menu
! 4325:
! 4326: @node parametric_mode, polar_mode, autoscale, autoscale
! 4327: @subsubsection parametric mode
! 4328:
! 4329: @c ?commands set autoscale parametric
! 4330: @c ?set autoscale parametric
! 4331: @c ?set autoscale t
! 4332: When in parametric mode (`set parametric`), the xrange is as fully scalable
! 4333: as the y range. In other words, in parametric mode the x axis can be
! 4334: automatically scaled to fit the range of the parametric function that is
! 4335: being plotted. Of course, the y axis can also be automatically scaled just
! 4336: as in the non-parametric case. If autoscaling on the x axis is not set, the
! 4337: current x range is used.
! 4338:
! 4339: Data files are plotted the same in parametric and non-parametric mode.
! 4340: However, there is a difference in mixed function and data plots: in
! 4341: non-parametric mode with autoscaled x, the x range of the datafile controls
! 4342: the x range of the functions; in parametric mode it has no influence.
! 4343:
! 4344: For completeness a last command `set autoscale t` is accepted. However, the
! 4345: effect of this "scaling" is very minor. When `gnuplot` determines that the
! 4346: t range would be empty, it makes a small adjustment if autoscaling is true.
! 4347: Otherwise, `gnuplot` gives an error. Such behavior may, in fact, not be very
! 4348: useful and the command `set autoscale t` is certainly questionable.
! 4349:
! 4350: `splot` extends the above ideas as you would expect. If autoscaling is set,
! 4351: then x, y, and z ranges are computed and each axis scaled to fit the
! 4352: resulting data.
! 4353:
! 4354: @node polar_mode, , parametric_mode, autoscale
! 4355: @subsubsection polar mode
! 4356:
! 4357: @c ?commands set autoscale polar
! 4358: @c ?set autoscale polar
! 4359: @c ?set autoscale t
! 4360: When in polar mode (`set polar`), the xrange and the yrange are both found
! 4361: from the polar coordinates, and thus they can both be automatically scaled.
! 4362: In other words, in polar mode both the x and y axes can be automatically
! 4363: scaled to fit the ranges of the polar function that is being plotted.
! 4364:
! 4365: When plotting functions in polar mode, the rrange may be autoscaled. When
! 4366: plotting data files in polar mode, the trange may also be autoscaled. Note
! 4367: that if the trange is contained within one quadrant, autoscaling will produce
! 4368: a polar plot of only that single quadrant.
! 4369:
! 4370: Explicitly setting one or two ranges but not others may lead to unexpected
! 4371: results.
! 4372: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html,See polar demos }
! 4373:
! 4374: @node bar, bmargin, autoscale, set-show
! 4375: @subsection bar
! 4376:
! 4377: @c ?commands set bar
! 4378: @c ?commands show bar
! 4379: @c ?set bar
! 4380: @c ?show bar
! 4381: The @ref{bar} command controls the tics at the ends of errorbars.
! 4382:
! 4383: Syntax:
! 4384: @example
! 4385: set bar @{small | large | <size>@}
! 4386: show bar
! 4387:
! 4388: @end example
! 4389:
! 4390: `small` is a synonym for 0.0, and `large` for 1.0.
! 4391: The default is 1.0 if no size is given.
! 4392:
! 4393: @node bmargin, border, bar, set-show
! 4394: @subsection bmargin
! 4395:
! 4396: @c ?commands set bmargin
! 4397: @c ?set bmargin
! 4398: @cindex bmargin
! 4399: @opindex bmargin
! 4400:
! 4401:
! 4402: The command @ref{bmargin} sets the size of the bottom margin. Please see
! 4403: @ref{margin} for details.
! 4404:
! 4405: @node border, boxwidth, bmargin, set-show
! 4406: @subsection border
! 4407:
! 4408: @c ?commands set border
! 4409: @c ?commands set noborder
! 4410: @c ?commands show border
! 4411: @c ?set border
! 4412: @c ?set noborder
! 4413: @c ?show border
! 4414: @cindex border
! 4415: @opindex border
! 4416:
! 4417:
! 4418: @cindex noborder
! 4419:
! 4420: The @ref{border} and `set noborder` commands control the display of the graph
! 4421: borders for the @ref{plot} and `splot` commands.
! 4422:
! 4423: Syntax:
! 4424: @example
! 4425: set border @{<integer> @{ @{linestyle | ls <line_style>@}
! 4426: | @{linetype | lt <line_type> @}
! 4427: @{linewidth | lw <line_width>@} @} @}
! 4428: set noborder
! 4429: show border
! 4430:
! 4431: @end example
! 4432:
! 4433: The borders are encoded in a 12-bit integer: the bottom four bits control the
! 4434: border for @ref{plot} and the sides of the base for `splot`; The next four bits
! 4435: control the verticals in `splot`; the top four bits control the edges on top
! 4436: of the `splot`. In detail, the `<integer>` should be the sum of the
! 4437: appropriate entries from the following table:
! 4438:
! 4439:
! 4440: @example
! 4441: plot border splot splot
! 4442: Side splot base verticals top
! 4443: bottom (south) 1 16 256
! 4444: left (west) 2 32 512
! 4445: top (north) 4 64 1024
! 4446: right (east) 8 128 2048
! 4447:
! 4448: @end example
! 4449:
! 4450:
! 4451: The default is 31, which is all four sides for @ref{plot}, and base and z axis
! 4452: for `splot`.
! 4453:
! 4454: Using the optional <line_style>, <line_type> and <line_width>
! 4455: specifiers, the way the border lines are drawn can be influenced
! 4456: (limited by what the current terminal driver supports). By default,
! 4457: the border is drawn with twice the usual linewidth. The <line_width>
! 4458: specifier scales this default value; for example, `set border 15 lw 2`
! 4459: will produce a border with four times the usual linewidth.
! 4460:
! 4461: Various axes or combinations of axes may be added together in the command.
! 4462:
! 4463: To have tics on edges other than bottom and left, disable the usual tics and
! 4464: enable the second axes.
! 4465:
! 4466: Examples:
! 4467:
! 4468: Draw all borders:
! 4469: @example
! 4470: set border
! 4471:
! 4472: @end example
! 4473:
! 4474: Draw only the SOUTHWEST borders:
! 4475: @example
! 4476: set border 3
! 4477:
! 4478: @end example
! 4479:
! 4480: Draw a complete box around a `splot`:
! 4481: @example
! 4482: set border 4095
! 4483:
! 4484: @end example
! 4485:
! 4486: Draw a partial box, omitting the front vertical:
! 4487: @example
! 4488: set border 127+256+512
! 4489:
! 4490: @end example
! 4491:
! 4492: Draw only the NORTHEAST borders:
! 4493: @example
! 4494: set noxtics; set noytics; set x2tics; set y2tics; set border 12
! 4495:
! 4496: @end example
! 4497:
! 4498: @uref{http://www.nas.nasa.gov/~woo/gnuplot/borders/borders.html,Borders Demo. }
! 4499:
! 4500: @node boxwidth, clabel, border, set-show
! 4501: @subsection boxwidth
! 4502:
! 4503: @c ?commands set boxwidth
! 4504: @c ?commands show boxwidth
! 4505: @c ?set boxwidth
! 4506: @c ?show boxwidth
! 4507: @cindex boxwidth
! 4508: @opindex boxwidth
! 4509:
! 4510:
! 4511: The @ref{boxwidth} command is used to set the default width of boxes in the
! 4512: @ref{boxes} and @ref{boxerrorbars} styles.
! 4513:
! 4514: Syntax:
! 4515: @example
! 4516: set boxwidth @{<width>@}
! 4517: show boxwidth
! 4518:
! 4519: @end example
! 4520:
! 4521: If a data file is plotted without the width being specified in the third,
! 4522: fourth, or fifth column (or @ref{using} entry), or if a function is plotted, the
! 4523: width of each box is set by the @ref{boxwidth} command. (If a width is given
! 4524: both in the file and by the @ref{boxwidth} command, the one in the file is
! 4525: used.) If the width is not specified in one of these ways, the width of each
! 4526: box will be calculated automatically so that it touches the adjacent boxes.
! 4527: In a four-column data set, the fourth column will be interpreted as the box
! 4528: width unless the width is set to -2.0, in which case the width will be
! 4529: calculated automatically. See @ref{boxerrorbars} for more details.
! 4530:
! 4531: To set the box width to automatic use the command
! 4532: @example
! 4533: set boxwidth
! 4534: @end example
! 4535:
! 4536: or, for four-column data,
! 4537: @example
! 4538: set boxwidth -2
! 4539:
! 4540: @end example
! 4541:
! 4542: The same effect can be achieved with the @ref{using} keyword in @ref{plot}:
! 4543: @example
! 4544: plot 'file' using 1:2:3:4:(-2)
! 4545:
! 4546: @end example
! 4547:
! 4548: @node clabel, clip, boxwidth, set-show
! 4549: @subsection clabel
! 4550:
! 4551: @c ?commands set clabel
! 4552: @c ?commands set noclabel
! 4553: @c ?commands show clabel
! 4554: @c ?set clabel
! 4555: @c ?set noclabel
! 4556: @c ?show clabel
! 4557: @cindex clabel
! 4558: @opindex clabel
! 4559:
! 4560:
! 4561: @cindex noclabel
! 4562:
! 4563: `gnuplot` will vary the linetype used for each contour level when clabel is
! 4564: set. When this option on (the default), a legend labels each linestyle with
! 4565: the z level it represents. It is not possible at present to separate the
! 4566: contour labels from the surface key.
! 4567:
! 4568: Syntax:
! 4569: @example
! 4570: set clabel @{'<format>'@}
! 4571: set noclabel
! 4572: show clabel
! 4573:
! 4574: @end example
! 4575:
! 4576: The default for the format string is %8.3g, which gives three decimal places.
! 4577: This may produce poor label alignment if the key is altered from its default
! 4578: configuration.
! 4579:
! 4580: The first contour linetype, or only contour linetype when clabel is off, is
! 4581: the surface linetype +1; contour points are the same style as surface points.
! 4582:
! 4583: See also @ref{contour}.
! 4584:
! 4585: @node clip, cntrparam, clabel, set-show
! 4586: @subsection clip
! 4587:
! 4588: @c ?commands set clip
! 4589: @c ?commands set noclip
! 4590: @c ?commands show clip
! 4591: @c ?set clip
! 4592: @c ?set noclip
! 4593: @c ?show clip
! 4594: @cindex clip
! 4595: @opindex clip
! 4596:
! 4597:
! 4598: @cindex noclip
! 4599:
! 4600: `gnuplot` can clip data points and lines that are near the boundaries of a
! 4601: graph.
! 4602:
! 4603: Syntax:
! 4604: @example
! 4605: set clip <clip-type>
! 4606: set noclip <clip-type>
! 4607: show clip
! 4608:
! 4609: @end example
! 4610:
! 4611: Three clip types are supported by `gnuplot`: `points`, `one`, and `two`.
! 4612: One, two, or all three clip types may be active for a single graph.
! 4613:
! 4614: The `points` clip type forces `gnuplot` to clip (actually, not plot at all)
! 4615: data points that fall within but too close to the boundaries. This is done
! 4616: so that large symbols used for points will not extend outside the boundary
! 4617: lines. Without clipping points near the boundaries, the plot may look bad.
! 4618: Adjusting the x and y ranges may give similar results.
! 4619:
! 4620: Setting the `one` clip type causes `gnuplot` to draw a line segment which has
! 4621: only one of its two endpoints within the graph. Only the in-range portion of
! 4622: the line is drawn. The alternative is to not draw any portion of the line
! 4623: segment.
! 4624:
! 4625: Some lines may have both endpoints out of range, but pass through the graph.
! 4626: Setting the `two` clip-type allows the visible portion of these lines to be
! 4627: drawn.
! 4628:
! 4629: In no case is a line drawn outside the graph.
! 4630:
! 4631: The defaults are `noclip points`, `clip one`, and `noclip two`.
! 4632:
! 4633: To check the state of all forms of clipping, use
! 4634: @example
! 4635: show clip
! 4636:
! 4637: @end example
! 4638:
! 4639: For backward compatibility with older versions, the following forms are also
! 4640: permitted:
! 4641: @example
! 4642: set clip
! 4643: set noclip
! 4644:
! 4645: @end example
! 4646:
! 4647: @ref{clip} is synonymous with `set clip points`; `set noclip` turns off all
! 4648: three types of clipping.
! 4649:
! 4650: @node cntrparam, contour, clip, set-show
! 4651: @subsection cntrparam
! 4652:
! 4653: @c ?commands set cntrparam
! 4654: @c ?commands show cntrparam
! 4655: @c ?set cntrparam
! 4656: @c ?show cntrparam
! 4657: @cindex cntrparam
! 4658: @opindex cntrparam
! 4659:
! 4660:
! 4661: @ref{cntrparam} controls the generation of contours and their smoothness for
! 4662: a contour plot. @ref{contour} displays current settings of @ref{cntrparam} as
! 4663: well as @ref{contour}.
! 4664:
! 4665: Syntax:
! 4666: @example
! 4667: set cntrparam @{ @{linear | cubicspline | bspline@}
! 4668: @{ points <n>@} @{ order <n> @}
! 4669: @{ levels auto @{<n>@} | <n>
! 4670: | discrete <z1> @{,<z2>@{,<z3>...@}@}
! 4671: | incremental <start>, <incr> @{,<end>@}
! 4672: @}
! 4673: @}
! 4674: show contour
! 4675:
! 4676: @end example
! 4677:
! 4678: This command has two functions. First, it sets the values of z for which
! 4679: contour points are to be determined (by linear interpolation between data
! 4680: points or function isosamples.) Second, it controls the way contours are
! 4681: drawn between the points determined to be of equal z. <n> should be an
! 4682: integral constant expression and <z1>, <z2> ... any constant expressions.
! 4683: The parameters are:
! 4684:
! 4685: `linear`, `cubicspline`, `bspline`---Controls type of approximation or
! 4686: interpolation. If `linear`, then straight line segments connect points of
! 4687: equal z magnitude. If `cubicspline`, then piecewise-linear contours are
! 4688: interpolated between the same equal z points to form somewhat smoother
! 4689: contours, but which may undulate. If `bspline`, a guaranteed-smoother curve
! 4690: is drawn, which only approximates the position of the points of equal-z.
! 4691:
! 4692: `points`---Eventually all drawings are done with piecewise-linear strokes.
! 4693: This number controls the number of line segments used to approximate the
! 4694: `bspline` or `cubicspline` curve. Number of cubicspline or bspline
! 4695: segments (strokes) = `points` * number of linear segments.
! 4696:
! 4697: `order`---Order of the bspline approximation to be used. The bigger this
! 4698: order is, the smoother the resulting contour. (Of course, higher order
! 4699: bspline curves will move further away from the original piecewise linear
! 4700: data.) This option is relevant for `bspline` mode only. Allowed values are
! 4701: integers in the range from 2 (linear) to 10.
! 4702:
! 4703: `levels`--- Selection of contour levels, controlled by `auto` (default),
! 4704: `discrete`, `incremental`, and <n>, number of contour levels, limited to
! 4705: @example
! 4706: MAX_DISCRETE_LEVELS as defined in plot.h (30 is standard.)
! 4707:
! 4708: @end example
! 4709:
! 4710: For `auto`, <n> specifies a nominal number of levels; the actual number will
! 4711: be adjusted to give simple labels. If the surface is bounded by zmin and zmax,
! 4712: contours will be generated at integer multiples of dz between zmin and zmax,
! 4713: where dz is 1, 2, or 5 times some power of ten (like the step between two
! 4714: tic marks).
! 4715:
! 4716: For `levels discrete`, contours will be generated at z = <z1>, <z2> ... as
! 4717: specified; the number of discrete levels sets the number of contour levels.
! 4718: In `discrete` mode, any `set cntrparms levels <n>` are ignored.
! 4719:
! 4720: For `incremental`, contours are generated at values of z beginning at <start>
! 4721: and increasing by <increment>, until the number of contours is reached. <end>
! 4722: is used to determine the number of contour levels, which will be changed by
! 4723: any subsequent `set cntrparam levels <n>`.
! 4724:
! 4725: If the command @ref{cntrparam} is given without any arguments specified, the
! 4726: defaults are used: linear, 5 points, order 4, 5 auto levels.
! 4727:
! 4728: Examples:
! 4729: @example
! 4730: set cntrparam bspline
! 4731: set cntrparam points 7
! 4732: set cntrparam order 10
! 4733:
! 4734: @end example
! 4735:
! 4736: To select levels automatically, 5 if the level increment criteria are met:
! 4737: @example
! 4738: set cntrparam levels auto 5
! 4739:
! 4740: @end example
! 4741:
! 4742: To specify discrete levels at .1, .37, and .9:
! 4743: @example
! 4744: set cntrparam levels discrete .1,1/exp(1),.9
! 4745:
! 4746: @end example
! 4747:
! 4748: To specify levels from 0 to 4 with increment 1:
! 4749: @example
! 4750: set cntrparam levels incremental 0,1,4
! 4751:
! 4752: @end example
! 4753:
! 4754: To set the number of levels to 10 (changing an incremental end or possibly
! 4755: the number of auto levels):
! 4756: @example
! 4757: set cntrparam levels 10
! 4758:
! 4759: @end example
! 4760:
! 4761: To set the start and increment while retaining the number of levels:
! 4762: @example
! 4763: set cntrparam levels incremental 100,50
! 4764:
! 4765: @end example
! 4766:
! 4767: See also @ref{contour} for control of where the contours are drawn, and @ref{clabel} for control of the format of the contour labels and linetypes.
! 4768: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/contours.html,Contours Demo} and
! 4769: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/discrete.html,contours with User Defined Levels.}
! 4770:
! 4771: @node contour, data_style, cntrparam, set-show
! 4772: @subsection contour
! 4773:
! 4774: @c ?commands set contour
! 4775: @c ?commands set nocontour
! 4776: @c ?commands show contour
! 4777: @c ?set contour
! 4778: @c ?set nocontour
! 4779: @c ?show contour
! 4780: @cindex contour
! 4781: @opindex contour
! 4782:
! 4783:
! 4784: @cindex nocontour
! 4785:
! 4786: @ref{contour} enables contour drawing for surfaces. This option is available
! 4787: for `splot` only.
! 4788:
! 4789: Syntax:
! 4790: @example
! 4791: set contour @{base | surface | both@}
! 4792: set nocontour
! 4793: show contour
! 4794:
! 4795: @end example
! 4796:
! 4797: The three options specify where to draw the contours: `base` draws the
! 4798: contours on the grid base where the x/ytics are placed, @ref{surface} draws the
! 4799: contours on the surfaces themselves, and `both` draws the contours on both
! 4800: the base and the surface. If no option is provided, the default is `base`.
! 4801:
! 4802: See also @ref{cntrparam} for the parameters that affect the drawing of
! 4803: contours, and @ref{clabel} for control of labelling of the contours.
! 4804:
! 4805: The surface can be switched off (see @ref{surface}), giving a contour-only
! 4806: graph. Though it is possible to use @ref{size} to enlarge the plot to fill
! 4807: the screen, more control over the output format can be obtained by writing
! 4808: the contour information to a file, and rereading it as a 2-d datafile plot:
! 4809:
! 4810: @example
! 4811: set nosurface
! 4812: set contour
! 4813: set cntrparam ...
! 4814: set term table
! 4815: set out 'filename'
! 4816: splot ...
! 4817: set out
! 4818: # contour info now in filename
! 4819: set term <whatever>
! 4820: plot 'filename'
! 4821:
! 4822: @end example
! 4823:
! 4824: In order to draw contours, the data should be organized as "grid data". In
! 4825: such a file all the points for a single y-isoline are listed, then all the
! 4826: points for the next y-isoline, and so on. A single blank line (a line
! 4827: containing no characters other than blank spaces and a carriage return and/or
! 4828: a line feed) separates one y-isoline from the next. See also `splot datafile`.
! 4829:
! 4830: If contours are desired from non-grid data, @ref{dgrid3d} can be used to
! 4831: create an appropriate grid. See @ref{dgrid3d} for more information.
! 4832: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/contours.html,Contours Demo} and
! 4833: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/discrete.html,contours with User Defined Levels.}
! 4834:
! 4835: @node data_style, dgrid3d, contour, set-show
! 4836: @subsection data style
! 4837:
! 4838: @c ?commands set data style
! 4839: @c ?commands show data style
! 4840: @c ?set data style
! 4841: @c ?show data style
! 4842: @c ?data style
! 4843: The @ref{style} command changes the default plotting style for data
! 4844: plots.
! 4845:
! 4846: Syntax:
! 4847: @example
! 4848: set data style <style-choice>
! 4849: show data style
! 4850:
! 4851: @end example
! 4852:
! 4853: See @ref{style} for the choices. If no choice is given, the choices are
! 4854: listed. @ref{style} shows the current default data plotting style.
! 4855:
! 4856: @node dgrid3d, dummy, data_style, set-show
! 4857: @subsection dgrid3d
! 4858:
! 4859: @c ?commands set dgrid3d
! 4860: @c ?commands set nodgrid3d
! 4861: @c ?commands show dgrid3d
! 4862: @c ?set dgrid3d
! 4863: @c ?set nodgrid3d
! 4864: @c ?show dgrid3d
! 4865: @cindex dgrid3d
! 4866: @opindex dgrid3d
! 4867:
! 4868:
! 4869: @cindex nodgrid3d
! 4870:
! 4871: The @ref{dgrid3d} command enables, and can set parameters for, non-grid
! 4872: to grid data mapping.
! 4873:
! 4874: Syntax:
! 4875: @example
! 4876: set dgrid3d @{<row_size>@} @{,@{<col_size>@} @{,<norm>@}@}
! 4877: set nodgrid3d
! 4878: show dgrid3d
! 4879:
! 4880: @end example
! 4881:
! 4882: By default @ref{dgrid3d} is disabled. When enabled, 3-d data read from a file
! 4883: are always treated as a scattered data set. A grid with dimensions derived
! 4884: from a bounding box of the scattered data and size as specified by the
! 4885: row/col_size parameters is created for plotting and contouring. The grid
! 4886: is equally spaced in x (rows) and in y (columns); the z values are computed
! 4887: as weighted averages of the scattered points' z values.
! 4888:
! 4889: The third parameter, norm, controls the weighting: Each data point is
! 4890: weighted inversely by its distance from the grid point raised to the norm
! 4891: power. (Actually, the weights are given by the inverse of dx^norm + dy^norm,
! 4892: where dx and dy are the components of the separation of the grid point from
! 4893: each data point. For some norms that are powers of two, specifically 4, 8,
! 4894: and 16, the computation is optimized by using the Euclidean distance in the
! 4895: weight calculation, (dx^2+dx^2)^norm/2. However, any non-negative integer
! 4896: can be used.)
! 4897:
! 4898: The closer the data point is to a grid point, the more effect it has on
! 4899: that grid point and the larger the value of norm the less effect more
! 4900: distant data points have on that grid point.
! 4901:
! 4902: The @ref{dgrid3d} option is a simple low pass filter that converts scattered
! 4903: data to a grid data set. More sophisticated approaches to this problem
! 4904: exist and should be used to preprocess the data outside `gnuplot` if this
! 4905: simple solution is found inadequate.
! 4906:
! 4907: (The z values are found by weighting all data points, not by interpolating
! 4908: between nearby data points; also edge effects may produce unexpected and/or
! 4909: undesired results. In some cases, small norm values produce a grid point
! 4910: reflecting the average of distant data points rather than a local average,
! 4911: while large values of norm may produce "steps" with several grid points
! 4912: having the same value as the closest data point, rather than making a smooth
! 4913: transition between adjacent data points. Some areas of a grid may be filled
! 4914: by extrapolation, to an arbitrary boundary condition. The variables are
! 4915: not normalized; consequently the units used for x and y will affect the
! 4916: relative weights of points in the x and y directions.)
! 4917:
! 4918: Examples:
! 4919: @example
! 4920: set dgrid3d 10,10,1 # defaults
! 4921: set dgrid3d ,,4
! 4922:
! 4923: @end example
! 4924:
! 4925: The first specifies that a grid of size 10 by 10 is to be constructed using
! 4926: a norm value of 1 in the weight computation. The second only modifies the
! 4927: norm, changing it to 4.
! 4928: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/scatter.html,Dgrid3d Demo.}
! 4929:
! 4930:
! 4931: @node dummy, encoding, dgrid3d, set-show
! 4932: @subsection dummy
! 4933:
! 4934: @c ?commands set dummy
! 4935: @c ?commands show dummy
! 4936: @c ?set dummy
! 4937: @c ?show dummy
! 4938: @cindex dummy
! 4939: @opindex dummy
! 4940:
! 4941:
! 4942: The @ref{dummy} command changes the default dummy variable names.
! 4943:
! 4944: Syntax:
! 4945: @example
! 4946: set dummy @{<dummy-var>@} @{,<dummy-var>@}
! 4947: show dummy
! 4948:
! 4949: @end example
! 4950:
! 4951: By default, `gnuplot` assumes that the independent, or "dummy", variable for
! 4952: the @ref{plot} command is "t" if in parametric or polar mode, or "x" otherwise.
! 4953: Similarly the independent variables for the `splot` command are "u" and "v"
! 4954: in parametric mode (`splot` cannot be used in polar mode), or "x" and "y"
! 4955: otherwise.
! 4956:
! 4957: It may be more convenient to call a dummy variable by a more physically
! 4958: meaningful or conventional name. For example, when plotting time functions:
! 4959:
! 4960: @example
! 4961: set dummy t
! 4962: plot sin(t), cos(t)
! 4963:
! 4964: @end example
! 4965:
! 4966: At least one dummy variable must be set on the command; @ref{dummy} by itself
! 4967: will generate an error message.
! 4968:
! 4969: Examples:
! 4970: @example
! 4971: set dummy u,v
! 4972: set dummy ,s
! 4973:
! 4974: @end example
! 4975:
! 4976: The second example sets the second variable to s.
! 4977:
! 4978: @node encoding, format, dummy, set-show
! 4979: @subsection encoding
! 4980:
! 4981: @c ?commands set encoding
! 4982: @c ?commands show encoding
! 4983: @c ?set encoding
! 4984: @c ?show encoding
! 4985: @cindex encoding
! 4986: @opindex encoding
! 4987:
! 4988:
! 4989: The @ref{encoding} command selects a character encoding. Valid values are
! 4990: `default`, which tells a terminal to use its default; `iso_8859_1` (known in
! 4991: the PostScript world as `ISO-Latin1`), which is used on many Unix workstations
! 4992: and with MS-Windows; `cp850`, for OS/2; and `cp437`, for MS-DOS.
! 4993:
! 4994: Syntax:
! 4995: @example
! 4996: set encoding @{<value>@}
! 4997: show encoding
! 4998:
! 4999: @end example
! 5000:
! 5001: Note that encoding is not supported by all terminal drivers and that
! 5002: the device must be able to produce the desired non-standard characters.
! 5003:
! 5004: @node format, function_style, encoding, set-show
! 5005: @subsection format
! 5006:
! 5007: @c ?commands set format
! 5008: @c ?commands show format
! 5009: @c ?set format
! 5010: @c ?show format
! 5011: @cindex format
! 5012: @opindex format
! 5013:
! 5014:
! 5015: The format of the tic-mark labels can be set with the `set format` command.
! 5016:
! 5017: Syntax:
! 5018: @example
! 5019: set format @{<axes>@} @{"<format-string>"@}
! 5020: set format @{<axes>@} @{'<format-string>'@}
! 5021: show format
! 5022:
! 5023: @end example
! 5024:
! 5025: where <axes> is either `x`, `y`, `z`, `xy`, `x2`, `y2` or nothing (which is
! 5026: the same as `xy`). The length of the string representing a tic mark (after
! 5027: formatting with 'printf') is restricted to 100 characters. If the format
! 5028: string is omitted, the format will be returned to the default "%g". For
! 5029: LaTeX users, the format "$%g$" is often desirable. If the empty string "" is
! 5030: used, no label will be plotted with each tic, though the tic mark will still
! 5031: be plotted. To eliminate all tic marks, use `set noxtics` or `set noytics`.
! 5032:
! 5033: Newline (\n) is accepted in the format string. Use double-quotes rather than
! 5034: single-quotes to enable such interpretation. See also `syntax`.
! 5035:
! 5036: The default format for both axes is "%g", but other formats such as "%.2f" or
! 5037: "%3.0em" are often desirable. Anything accepted by 'printf' when given a
! 5038: double precision number, and accepted by the terminal, will work. Some other
! 5039: options have been added. If the format string looks like a floating point
! 5040: format, then `gnuplot` tries to construct a reasonable format.
! 5041:
! 5042: Characters not preceded by "%" are printed verbatim. Thus you can include
! 5043: spaces and labels in your format string, such as "%g m", which will put " m"
! 5044: after each number. If you want "%" itself, double it: "%g %%".
! 5045:
! 5046: See also @ref{xtics} for more information about tic labels.
! 5047: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/electron.html,See demo. }
! 5048:
! 5049: @menu
! 5050: * format_specifiers::
! 5051: * time/date_specifiers::
! 5052: @end menu
! 5053:
! 5054: @node format_specifiers, time/date_specifiers, format, format
! 5055: @subsubsection format specifiers
! 5056:
! 5057: @c ?commands set format specifiers
! 5058: @c ?set format specifiers
! 5059: @c ?format specifiers
! 5060: @cindex format_specifiers
! 5061:
! 5062: The acceptable formats (if not in time/date mode) are:
! 5063:
! 5064:
! 5065: @example
! 5066: Format Explanation
! 5067: %f floating point notation
! 5068: %e or %E exponential notation; an "e" or "E" before the power
! 5069: %g or %G the shorter of %e (or %E) and %f
! 5070: %x or %X hex
! 5071: %o or %O octal
! 5072: %t mantissa to base 10
! 5073: %l mantissa to base of current logscale
! 5074: %s mantissa to base of current logscale; scientific power
! 5075: %T power to base 10
! 5076: %L power to base of current logscale
! 5077: %S scientific power
! 5078: %c character replacement for scientific power
! 5079: %P multiple of pi
! 5080:
! 5081: @end example
! 5082:
! 5083:
! 5084: A 'scientific' power is one such that the exponent is a multiple of three.
! 5085: Character replacement of scientific powers (`"%c"`) has been implemented
! 5086: for powers in the range -18 to +18. For numbers outside of this range the
! 5087: format reverts to exponential.
! 5088:
! 5089: Other acceptable modifiers (which come after the "%" but before the format
! 5090: specifier) are "-", which left-justifies the number; "+", which forces all
! 5091: numbers to be explicitly signed; "#", which places a decimal point after
! 5092: floats that have only zeroes following the decimal point; a positive integer,
! 5093: which defines the field width; "0" (the digit, not the letter) immediately
! 5094: preceding the field width, which indicates that leading zeroes are to be used
! 5095: instead of leading blanks; and a decimal point followed by a non-negative
! 5096: integer, which defines the precision (the minimum number of digits of an
! 5097: integer, or the number of digits following the decimal point of a float).
! 5098:
! 5099: Some releases of 'printf' may not support all of these modifiers but may also
! 5100: support others; in case of doubt, check the appropriate documentation and
! 5101: then experiment.
! 5102:
! 5103: Examples:
! 5104: @example
! 5105: set format y "%t"; set ytics (5,10) # "5.0" and "1.0"
! 5106: set format y "%s"; set ytics (500,1000) # "500" and "1.0"
! 5107: set format y "+-12.3f"; set ytics(12345) # "+12345.000 "
! 5108: set format y "%.2t*10^%+03T"; set ytic(12345)# "1.23*10^+04"
! 5109: set format y "%s*10^@{%S@}"; set ytic(12345) # "12.345*10^@{3@}"
! 5110: set format y "%s %cg"; set ytic(12345) # "12.345 kg"
! 5111: set format y "%.0P pi"; set ytic(6.283185) # "2 pi"
! 5112: set format y "%.0P%%"; set ytic(50) # "50%"
! 5113:
! 5114: @end example
! 5115:
! 5116: @example
! 5117: set log y 2; set format y '%l'; set ytics (1,2,3)
! 5118: #displays "1.0", "1.0" and "1.5" (since 3 is 1.5 * 2^1)
! 5119:
! 5120: @end example
! 5121:
! 5122: There are some problem cases that arise when numbers like 9.999 are printed
! 5123: with a format that requires both rounding and a power.
! 5124:
! 5125: If the data type for the axis is time/date, the format string must contain
! 5126: valid codes for the 'strftime' function (outside of `gnuplot`, type "man
! 5127: strftime"). See @ref{timefmt} for a list of the allowed input format codes.
! 5128:
! 5129: @node time/date_specifiers, , format_specifiers, format
! 5130: @subsubsection time/date specifiers
! 5131:
! 5132: @c ?commands set format time/date_specifiers
! 5133: @c ?set format time/date_specifiers
! 5134: @c ?set time/date_specifiers
! 5135: @cindex time/date_specifiers
! 5136:
! 5137: In time/date mode, the acceptable formats are:
! 5138:
! 5139:
! 5140: @example
! 5141: Format Explanation
! 5142: %a abbreviated name of day of the week
! 5143: %A full name of day of the week
! 5144: %b or %h abbreviated name of the month
! 5145: %B full name of the month
! 5146: %d day of the month, 1--31
! 5147: %D shorthand for "%m/%d/%y"
! 5148: %H or %k hour, 0--24
! 5149: %I or %l hour, 0--12
! 5150: %j day of the year, 1--366
! 5151: %m month, 1--12
! 5152: %M minute, 0--60
! 5153: %p "am" or "pm"
! 5154: %r shorthand for "%I:%M:%S %p"
! 5155: %R shorthand for %H:%M"
! 5156: %S second, 0--60
! 5157: %T shorthand for "%H:%M:%S"
! 5158: %U week of the year (week starts on Sunday)
! 5159: %w day of the week, 0--6 (Sunday = 0)
! 5160: %W week of the year (week starts on Monday)
! 5161: %y year, 0-99
! 5162: %Y year, 4-digit
! 5163:
! 5164: @end example
! 5165:
! 5166:
! 5167: Except for the non-numerical formats, these may be preceded by a "0" ("zero",
! 5168: not "oh") to pad the field length with leading zeroes, and a positive digit,
! 5169: to define the minimum field width (which will be overridden if the specified
! 5170: width is not large enough to contain the number). There is a 24-character
! 5171: limit to the length of the printed text; longer strings will be truncated.
! 5172:
! 5173: Examples:
! 5174:
! 5175: Suppose the text is "76/12/25 23:11:11". Then
! 5176: @example
! 5177: set format x # defaults to "12/25/76" \n "23:11"
! 5178: set format x "%A, %d %b %Y" # "Saturday, 25 Dec 1976"
! 5179: set format x "%r %d" # "11:11:11 pm 12/25/76"
! 5180:
! 5181: @end example
! 5182:
! 5183: Suppose the text is "98/07/06 05:04:03". Then
! 5184: @example
! 5185: set format x "%1y/%2m/%3d %01H:%02M:%03S" # "98/ 7/ 6 5:04:003"
! 5186:
! 5187: @end example
! 5188:
! 5189: @node function_style, functions, format, set-show
! 5190: @subsection function style
! 5191:
! 5192: @c ?commands set function style
! 5193: @c ?commands show function style
! 5194: @c ?set function style
! 5195: @c ?show function style
! 5196: @c ?function style
! 5197: The @ref{style} command changes the default plotting style for
! 5198: function plots.
! 5199:
! 5200: Syntax:
! 5201: @example
! 5202: set function style <style-choice>
! 5203: show function style
! 5204:
! 5205: @end example
! 5206:
! 5207: See @ref{style} for the choices. If no choice is given, the choices are
! 5208: listed. @ref{style} shows the current default function plotting
! 5209: style.
! 5210:
! 5211: @node functions, grid, function_style, set-show
! 5212: @subsection functions
! 5213:
! 5214: @c ?commands show functions
! 5215: @c ?show functions
! 5216: The @ref{functions} command lists all user-defined functions and their
! 5217: definitions.
! 5218:
! 5219: Syntax:
! 5220: @example
! 5221: show functions
! 5222:
! 5223: @end example
! 5224:
! 5225: For information about the definition and usage of functions in `gnuplot`,
! 5226: please see `expressions`.
! 5227: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/spline.html,Splines as User Defined Functions.}
! 5228: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html,Use of functions and complex variables for airfoils }
! 5229:
! 5230: @node grid, hidden3d, functions, set-show
! 5231: @subsection grid
! 5232:
! 5233: @c ?commands set grid
! 5234: @c ?commands set nogrid
! 5235: @c ?commands show grid
! 5236: @c ?set grid
! 5237: @c ?set nogrid
! 5238: @c ?show grid
! 5239: @cindex grid
! 5240: @opindex grid
! 5241:
! 5242:
! 5243: @cindex nogrid
! 5244:
! 5245: The `set grid` command allows grid lines to be drawn on the plot.
! 5246:
! 5247: Syntax:
! 5248: @example
! 5249: set grid @{@{no@}@{m@}xtics@} @{@{no@}@{m@}ytics@} @{@{no@}@{m@}ztics@}
! 5250: @{@{no@}@{m@}x2tics@} @{@{no@}@{m@}y2tics@}
! 5251: @{polar @{<angle>@}@}
! 5252: @{ @{linestyle <major_linestyle>@}
! 5253: | @{linetype | lt <major_linetype>@}
! 5254: @{linewidth | lw <major_linewidth>@}
! 5255: @{ , @{linestyle | ls <minor_linestyle>@}
! 5256: | @{linetype | lt <minor_linetype>@}
! 5257: @{linewidth | lw <minor_linewidth>@} @} @}
! 5258: set nogrid
! 5259: show grid
! 5260:
! 5261: @end example
! 5262:
! 5263: The grid can be enabled and disabled for the major and/or minor tic
! 5264: marks on any axis, and the linetype and linewidth can be specified
! 5265: for major and minor grid lines, also via a predefined linestyle, as
! 5266: far as the active terminal driver supports this.
! 5267:
! 5268: Additionally, a polar grid can be selected for 2-d plots---circles are drawn
! 5269: to intersect the selected tics, and radial lines are drawn at definable
! 5270: intervals. (The interval is given in degrees or radians ,depending on the
! 5271: @ref{angles} setting.) Note that a polar grid is no longer automatically
! 5272: generated in polar mode.
! 5273:
! 5274: The pertinent tics must be enabled before `set grid` can draw them; `gnuplot`
! 5275: will quietly ignore instructions to draw grid lines at non-existent tics, but
! 5276: they will appear if the tics are subsequently enabled.
! 5277:
! 5278: If no linetype is specified for the minor gridlines, the same linetype as the
! 5279: major gridlines is used. The default polar angle is 30 degrees.
! 5280:
! 5281: By default, grid lines are drawn with half the usual linewidth. The major and
! 5282: minor linewidth specifiers scale this default value; for example, `set grid
! 5283: lw .5` will draw grid lines with one quarter the usual linewidth.
! 5284:
! 5285: Z grid lines are drawn on the back of the plot. This looks better if a
! 5286: partial box is drawn around the plot---see @ref{border}.
! 5287:
! 5288: @node hidden3d, isosamples, grid, set-show
! 5289: @subsection hidden3d
! 5290:
! 5291: @c ?commands set hidden3d
! 5292: @c ?commands set nohidden3d
! 5293: @c ?commands show hidden3d
! 5294: @c ?set hidden3d
! 5295: @c ?set nohidden3d
! 5296: @c ?show hidden3d
! 5297: @cindex hidden3d
! 5298: @opindex hidden3d
! 5299:
! 5300:
! 5301: @cindex nohidden3d
! 5302:
! 5303: The @ref{hidden3d} command enables hidden line removal for surface plotting
! 5304: (see `splot`). Some optional features of the underlying algorithm can also
! 5305: be controlled using this command.
! 5306:
! 5307: Syntax:
! 5308: @example
! 5309: set hidden3d @{defaults@} |
! 5310: @{ @{@{offset <offset>@} | @{nooffset@}@}
! 5311: @{trianglepattern <bitpattern>@}
! 5312: @{@{undefined <level>@} | @{noundefined@}@}
! 5313: @{@{no@}altdiagonal@}
! 5314: @{@{no@}bentover@} @}
! 5315: set nohidden3d
! 5316: show hidden3d
! 5317:
! 5318: @end example
! 5319:
! 5320: In contrast to the usual display in gnuplot, hidden line removal actually
! 5321: treats the given function or data grids as real surfaces that can't be seen
! 5322: through, so parts behind the surface will be hidden by it. For this to be
! 5323: possible, the surface needs to have 'grid structure' (see `splot datafile`
! 5324: about this), and it has to be drawn `with lines` or @ref{linespoints}.
! 5325:
! 5326: When @ref{hidden3d} is set, both the hidden portion of the surface and possibly
! 5327: its contours drawn on the base (see @ref{contour}) as well as the grid will
! 5328: be hidden. Each surface has its hidden parts removed with respect to itself
! 5329: and to other surfaces, if more than one surface is plotted. Contours drawn
! 5330: on the surface (@ref{surface}) don't work. Labels and arrows are
! 5331: always visible and are unaffected. The key is also never hidden by the
! 5332: surface.
! 5333:
! 5334: Functions are evaluated at isoline intersections. The algorithm interpolates
! 5335: linearly between function points or data points when determining the visible
! 5336: line segments. This means that the appearance of a function may be different
! 5337: when plotted with @ref{hidden3d} than when plotted with `nohidden3d` because in
! 5338: the latter case functions are evaluated at each sample. Please see @ref{samples} and @ref{isosamples} for discussion of the difference.
! 5339:
! 5340: The algorithm used to remove the hidden parts of the surfaces has some
! 5341: additional features controllable by this command. Specifying `defaults` will
! 5342: set them all to their default settings, as detailed below. If `defaults` is
! 5343: not given, only explicitly specified options will be influenced: all others
! 5344: will keep their previous values, so you can turn on/off hidden line removal
! 5345: via `set @{no@}hidden3d`, without modifying the set of options you chose.
! 5346:
! 5347: The first option, `offset`, influences the linestyle used for lines on the
! 5348: 'back' side. Normally, they are drawn in a linestyle one index number higher
! 5349: than the one used for the front, to make the two sides of the surface
! 5350: distinguishable. You can specify a different line style offset to add
! 5351: instead of the default 1, by `offset <offset>`. Option `nooffset` stands for
! 5352: `offset 0`, making the two sides of the surface use the same linestyle.
! 5353:
! 5354: Next comes the option `trianglepattern <bitpattern>`. <bitpattern> must be
! 5355: a number between 0 and 7, interpreted as a bit pattern. Each bit determines
! 5356: the visibility of one edge of the triangles each surface is split up into.
! 5357: Bit 0 is for the 'horizontal' edges of the grid, Bit 1 for the 'vertical'
! 5358: ones, and Bit 2 for the diagonals that split each cell of the original grid
! 5359: into two triangles. The default pattern is 3, making all horizontal and
! 5360: vertical lines visible, but not the diagonals. You may want to choose 7 to
! 5361: see those diagonals as well.
! 5362:
! 5363: The `undefined <level>` option lets you decide what the algorithm is to do
! 5364: with data points that are undefined (missing data, or undefined function
! 5365: values), or exceed the given x-, y- or z-ranges. Such points can either be
! 5366: plotted nevertheless, or taken out of the input data set. All surface
! 5367: elements touching a point that is taken out will be taken out as well, thus
! 5368: creating a hole in the surface. If <level> = 3, equivalent to option
! 5369: `noundefined`, no points will be thrown away at all. This may produce all
! 5370: kinds of problems elsewhere, so you should avoid this. <level> = 2 will
! 5371: throw away undefined points, but keep the out-of-range ones. <level> = 1,
! 5372: the default, will get rid of out-of-range points as well.
! 5373:
! 5374: By specifying `noaltdiagonal`, you can override the default handling of a
! 5375: special case can occur if `undefined` is active (i.e. <level> is not 3).
! 5376: Each cell of the grid-structured input surface will be divided in two
! 5377: triangles along one of its diagonals. Normally, all these diagonals have
! 5378: the same orientation relative to the grid. If exactly one of the four cell
! 5379: corners is excluded by the `undefined` handler, and this is on the usual
! 5380: diagonal, both triangles will be excluded. However if the default setting
! 5381: of `altdiagonal` is active, the other diagonal will be chosen for this cell
! 5382: instead, minimizing the size of the hole in the surface.
! 5383:
! 5384: The `bentover` option controls what happens to another special case, this
! 5385: time in conjunction with the `trianglepattern`. For rather crumply surfaces,
! 5386: it can happen that the two triangles a surface cell is divided into are seen
! 5387: from opposite sides (i.e. the original quadrangle is 'bent over'), as
! 5388: illustrated in the following ASCII art:
! 5389:
! 5390: @example
! 5391: C----B
! 5392: original quadrangle: A--B displayed quadrangle: |\ |
! 5393: ("set view 0,0") | /| ("set view 75,75" perhaps) | \ |
! 5394: |/ | | \ |
! 5395: C--D | \|
! 5396: A D
! 5397:
! 5398: @end example
! 5399:
! 5400: If the diagonal edges of the surface cells aren't generally made visible by
! 5401: bit 2 of the <bitpattern> there, the edge CB above wouldn't be drawn at all,
! 5402: normally, making the resulting display hard to understand. Therefore, the
! 5403: default option of `bentover` will turn it visible in this case. If you don't
! 5404: want that, you may choose `nobentover` instead.
! 5405: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/hidden.html,Hidden Line Removal Demo} and
! 5406: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/singulr.html,Complex Hidden Line Demo. }
! 5407:
! 5408: @node isosamples, key, hidden3d, set-show
! 5409: @subsection isosamples
! 5410:
! 5411: @c ?commands set isosamples
! 5412: @c ?commands show isosamples
! 5413: @c ?set isosamples
! 5414: @c ?show isosamples
! 5415: @cindex isosamples
! 5416: @opindex isosamples
! 5417:
! 5418:
! 5419: The isoline density (grid) for plotting functions as surfaces may be changed
! 5420: by the @ref{isosamples} command.
! 5421:
! 5422: Syntax:
! 5423: @example
! 5424: set isosamples <iso_1> @{,<iso_2>@}
! 5425: show isosamples
! 5426:
! 5427: @end example
! 5428:
! 5429: Each function surface plot will have <iso_1> iso-u lines and <iso_2> iso-v
! 5430: lines. If you only specify <iso_1>, <iso_2> will be set to the same value
! 5431: as <iso_1>. By default, sampling is set to 10 isolines per u or v axis.
! 5432: A higher sampling rate will produce more accurate plots, but will take longer.
! 5433: These parameters have no effect on data file plotting.
! 5434:
! 5435: An isoline is a curve parameterized by one of the surface parameters while
! 5436: the other surface parameter is fixed. Isolines provide a simple means to
! 5437: display a surface. By fixing the u parameter of surface s(u,v), the iso-u
! 5438: lines of the form c(v) = s(u0,v) are produced, and by fixing the v parameter,
! 5439: the iso-v lines of the form c(u) = s(u,v0) are produced.
! 5440:
! 5441: When a function surface plot is being done without the removal of hidden
! 5442: lines, @ref{samples} controls the number of points sampled along each
! 5443: isoline; see @ref{samples} and @ref{hidden3d}. The contour algorithm
! 5444: assumes that a function sample occurs at each isoline intersection, so
! 5445: change in @ref{samples} as well as @ref{isosamples} may be desired when changing
! 5446: the resolution of a function surface/contour.
! 5447:
! 5448: @node key, label, isosamples, set-show
! 5449: @subsection key
! 5450:
! 5451: @c ?commands set key
! 5452: @c ?commands set nokey
! 5453: @c ?commands show key
! 5454: @c ?set key
! 5455: @c ?set nokey
! 5456: @c ?show key
! 5457: @cindex key
! 5458: @opindex key
! 5459:
! 5460:
! 5461: @cindex nokey
! 5462:
! 5463: @cindex legend
! 5464:
! 5465: The @ref{key} enables a key (or legend) describing plots on a plot.
! 5466:
! 5467: The contents of the key, i.e., the names given to each plotted data set and
! 5468: function and samples of the lines and/or symbols used to represent them, are
! 5469: determined by the `title` and @ref{with} options of the @{`s`@}@ref{plot} command.
! 5470: Please see `plot title` and @ref{with} for more information.
! 5471:
! 5472: Syntax:
! 5473: @example
! 5474: set key @{ left | right | top | bottom | outside | below
! 5475: | <position>@}
! 5476: @{Left | Right@} @{@{no@}reverse@}
! 5477: @{samplen <sample_length>@} @{spacing <vertical_spacing>@}
! 5478: @{width <width_increment>@}
! 5479: @{title "<text>"@}
! 5480: @{@{no@}box @{ @{linestyle | ls <line_style>@}
! 5481: | @{linetype | lt <line_type>@}
! 5482: @{linewidth | lw <line_width>@}@}@}
! 5483: set nokey
! 5484: show key
! 5485:
! 5486: @end example
! 5487:
! 5488: By default the key is placed in the upper right corner of the graph. The
! 5489: keywords `left`, `right`, `top`, `bottom`, `outside` and `below` may be used
! 5490: to place the key in the other corners inside the graph or to the right
! 5491: (outside) or below the graph. They may be given alone or combined.
! 5492:
! 5493: Justification of the labels within the key is controlled by `Left` or `Right`
! 5494: (default is `Right`). The text and sample can be reversed (`reverse`) and a
! 5495: box can be drawn around the key (`box @{...@}`) in a specified `linetype`
! 5496: and `linewidth`, or a user-defined @ref{linestyle}. Note that not all
! 5497: terminal drivers support linewidth selection, though.
! 5498:
! 5499: The length of the sample line can be controlled by `samplen`. The sample
! 5500: length is computed as the sum of the tic length and <sample_length> times the
! 5501: character width. `samplen` also affects the positions of point samples in
! 5502: the key since these are drawn at the midpoint of the sample line, even if it
! 5503: is not drawn. <sample_length> must be an integer.
! 5504:
! 5505: The vertical spacing between lines is controlled by `spacing`. The spacing
! 5506: is set equal to the product of the pointsize, the vertical tic size, and
! 5507: <vertical_spacing>. The program will guarantee that the vertical spacing is
! 5508: no smaller than the character height.
! 5509:
! 5510: The <width_increment> is a number of character widths to be added to or
! 5511: subtracted from the length of the string. This is useful only when you are
! 5512: putting a box around the key and you are using control characters in the text.
! 5513: `gnuplot` simply counts the number of characters in the string when computing
! 5514: the box width; this allows you to correct it.
! 5515:
! 5516: A title can be put on the key (`title "<text>"`)---see also `syntax` for the
! 5517: distinction between text in single- or double-quotes. The key title uses the
! 5518: same justification as do the plot titles.
! 5519:
! 5520: The defaults for @ref{key} are `right`, `top`, `Right`, `noreverse`, `samplen
! 5521: 4`, `spacing 1.25`, `title ""`, and `nobox`. The default <linetype> is the
! 5522: same as that used for the plot borders. Entering @ref{key} with no options
! 5523: returns the key to its default configuration.
! 5524:
! 5525: The <position> can be a simple x,y,z as in previous versions, but these can
! 5526: be preceded by one of four keywords (`first`, `second`, `graph`, `screen`)
! 5527: which selects the coordinate system in which the position is specified. See
! 5528: `coordinates` for more details.
! 5529:
! 5530: The key is drawn as a sequence of lines, with one plot described on each
! 5531: line. On the right-hand side (or the left-hand side, if `reverse` is
! 5532: selected) of each line is a representation that attempts to mimic the way the
! 5533: curve is plotted. On the other side of each line is the text description
! 5534: (the line title), obtained from the @ref{plot} command. The lines are vertically
! 5535: arranged so that an imaginary straight line divides the left- and right-hand
! 5536: sides of the key. It is the coordinates of the top of this line that are
! 5537: specified with the @ref{key} command. In a @ref{plot}, only the x and y
! 5538: coordinates are used to specify the line position. For a `splot`, x, y and
! 5539: z are all used as a 3-d location mapped using the same mapping as the graph
! 5540: itself to form the required 2-d screen position of the imaginary line.
! 5541:
! 5542: Some or all of the key may be outside of the graph boundary, although this
! 5543: may interfere with other labels and may cause an error on some devices. If
! 5544: you use the keywords `outside` or `below`, `gnuplot` makes space for the keys
! 5545: and the graph becomes smaller. Putting keys outside to the right, they
! 5546: occupy as few columns as possible, and putting them below, as many columns as
! 5547: possible (depending of the length of the labels), thus stealing as little
! 5548: space from the graph as possible.
! 5549:
! 5550: When using the TeX or PostScript drivers, or similar drivers where formatting
! 5551: information is embedded in the string, `gnuplot` is unable to calculate
! 5552: correctly the width of the string for key positioning. If the key is to be
! 5553: positioned at the left, it may be convenient to use the combination `set key
! 5554: left Left reverse`. The box and gap in the grid will be the width of the
! 5555: literal string.
! 5556:
! 5557: If `splot` is being used to draw contours, the contour labels will be listed
! 5558: in the key. If the alignment of these labels is poor or a different number
! 5559: of decimal places is desired, the label format can be specified. See @ref{clabel} for details.
! 5560:
! 5561: Examples:
! 5562:
! 5563: This places the key at the default location:
! 5564: @example
! 5565: set key
! 5566:
! 5567: @end example
! 5568:
! 5569: This disables the key:
! 5570: @example
! 5571: set nokey
! 5572:
! 5573: @end example
! 5574:
! 5575: This places a key at coordinates 2,3.5,2 in the default (first) coordinate
! 5576: system:
! 5577: @example
! 5578: set key 2,3.5,2
! 5579:
! 5580: @end example
! 5581:
! 5582: This places the key below the graph:
! 5583: @example
! 5584: set key below
! 5585:
! 5586: @end example
! 5587:
! 5588: This places the key in the bottom left corner, left-justifies the text,
! 5589: gives it a title, and draws a box around it in linetype 3:
! 5590: @example
! 5591: set key left bottom Left title 'Legend' box 3
! 5592:
! 5593: @end example
! 5594:
! 5595: @node label, linestyle, key, set-show
! 5596: @subsection label
! 5597:
! 5598: @c ?commands set label
! 5599: @c ?commands set nolabel
! 5600: @c ?commands show label
! 5601: @c ?set label
! 5602: @c ?set nolabel
! 5603: @c ?show label
! 5604: @cindex label
! 5605: @opindex label
! 5606:
! 5607:
! 5608: @cindex nolabel
! 5609:
! 5610: Arbitrary labels can be placed on the plot using the @ref{label} command.
! 5611:
! 5612: Syntax:
! 5613: @example
! 5614: set label @{<tag>@} @{"<label_text>"@} @{at <position>@}
! 5615: @{<justification>@} @{@{no@}rotate@} @{font "<name><,size>"@}
! 5616: set nolabel @{<tag>@}
! 5617: show label
! 5618:
! 5619: @end example
! 5620:
! 5621: The <position> is specified by either x,y or x,y,z, and may be preceded by
! 5622: `first`, `second`, `graph`, or `screen` to select the coordinate system.
! 5623: See `coordinates` for details.
! 5624:
! 5625: The tag is an integer that is used to identify the label. If no <tag> is
! 5626: given, the lowest unused tag value is assigned automatically. The tag can be
! 5627: used to delete or modify a specific label. To change any attribute of an
! 5628: existing label, use the @ref{label} command with the appropriate tag, and
! 5629: specify the parts of the label to be changed.
! 5630:
! 5631: By default, the text is placed flush left against the point x,y,z. To adjust
! 5632: the way the label is positioned with respect to the point x,y,z, add the
! 5633: parameter <justification>, which may be `left`, `right` or `center`,
! 5634: indicating that the point is to be at the left, right or center of the text.
! 5635: Labels outside the plotted boundaries are permitted but may interfere with
! 5636: axis labels or other text.
! 5637:
! 5638: If `rotate` is given, the label is written vertically (if the terminal can do
! 5639: so, of course).
! 5640:
! 5641: If one (or more) axis is timeseries, the appropriate coordinate should be
! 5642: given as a quoted time string according to the @ref{timefmt} format string. See
! 5643: @ref{xdata} and @ref{timefmt}.
! 5644:
! 5645: The EEPIC, Imagen, LaTeX, and TPIC drivers allow \\ in a string to specify
! 5646: a newline.
! 5647:
! 5648: Examples:
! 5649:
! 5650: To set a label at (1,2) to "y=x", use:
! 5651: @example
! 5652: set label "y=x" at 1,2
! 5653:
! 5654: @end example
! 5655:
! 5656: To set a Sigma of size 24, from the Symbol font set, at the center of
! 5657: the graph, use:
! 5658: @example
! 5659: set label "S" at graph 0.5,0.5 center font "Symbol,24"
! 5660:
! 5661: @end example
! 5662:
! 5663: To set a label "y=x^2" with the right of the text at (2,3,4), and tag the
! 5664: label as number 3, use:
! 5665: @example
! 5666: set label 3 "y=x^2" at 2,3,4 right
! 5667:
! 5668: @end example
! 5669:
! 5670: To change the preceding label to center justification, use:
! 5671: @example
! 5672: set label 3 center
! 5673:
! 5674: @end example
! 5675:
! 5676: To delete label number 2, use:
! 5677: @example
! 5678: set nolabel 2
! 5679:
! 5680: @end example
! 5681:
! 5682: To delete all labels, use:
! 5683: @example
! 5684: set nolabel
! 5685:
! 5686: @end example
! 5687:
! 5688: To show all labels (in tag order), use:
! 5689: @example
! 5690: show label
! 5691:
! 5692: @end example
! 5693:
! 5694: To set a label on a graph with a timeseries on the x axis, use, for example:
! 5695: @example
! 5696: set timefmt "%d/%m/%y,%H:%M"
! 5697: set label "Harvest" at "25/8/93",1
! 5698:
! 5699: @end example
! 5700:
! 5701: @node linestyle, lmargin, label, set-show
! 5702: @subsection linestyle
! 5703:
! 5704: @c ?commands set linestyle
! 5705: @c ?commands set nolinestyle
! 5706: @c ?commands show linestyle
! 5707: @c ?set linestyle
! 5708: @c ?set nolinestyle
! 5709: @c ?show linestyle
! 5710: @cindex linestyle
! 5711: @opindex linestyle
! 5712:
! 5713:
! 5714: Each terminal has a default set of line and point types, which can be seen
! 5715: by using the command @ref{test}. @ref{linestyle} defines a set of line types
! 5716: and widths and point types and sizes so that you can refer to them later by
! 5717: an index instead of repeating all the information at each invocation.
! 5718:
! 5719: Syntax:
! 5720: @example
! 5721: set linestyle <index> @{linetype | lt <line_type>@}
! 5722: @{linewidth | lw <line_width>@}
! 5723: @{pointtype | pt <point_type>@}
! 5724: @{pointsize | ps <point_size>@}
! 5725: set nolinestyle
! 5726: show linestyle
! 5727:
! 5728: @end example
! 5729:
! 5730: The line and point types are taken from the default types for the terminal
! 5731: currently in use. The line width and point size are multipliers for the
! 5732: default width and size (but note that <point_size> here is unaffected by
! 5733: the multiplier given on 'set pointsize').
! 5734:
! 5735: The defaults for the line and point types is the index. The defaults for
! 5736: the width and size are both unity.
! 5737:
! 5738: Linestyles created by this mechanism do not replace the default styles;
! 5739: both may be used.
! 5740:
! 5741: Not all terminals support the `linewidth` and @ref{pointsize} features; if
! 5742: not supported, the option will be ignored.
! 5743:
! 5744: Note that this feature is not completely implemented; linestyles defined by
! 5745: this mechanism may be used with 'plot', 'splot', 'replot', and 'set arrow',
! 5746: but not by other commands that allow the default index to be used, such as
! 5747: 'set grid'.
! 5748:
! 5749: Example:
! 5750: Suppose that the default lines for indices 1, 2, and 3 are red, green, and
! 5751: blue, respectively, and the default point shapes for the same indices are a
! 5752: square, a cross, and a triangle, respectively. Then
! 5753:
! 5754: @example
! 5755: set linestyle 1 lt 2 lw 2 pt 3 ps 0.5
! 5756:
! 5757: @end example
! 5758:
! 5759: defines a new linestyle that is green and twice the default width and a new
! 5760: pointstyle that is a half-sized triangle. The commands
! 5761:
! 5762: @example
! 5763: set function style lines
! 5764: plot f(x) lt 3, g(x) ls 1
! 5765:
! 5766: @end example
! 5767:
! 5768: will create a plot of f(x) using the default blue line and a plot of g(x)
! 5769: using the user-defined wide green line. Similarly the commands
! 5770:
! 5771: @example
! 5772: set function style linespoints
! 5773: plot p(x) lt 1 pt 3, q(x) ls 1
! 5774:
! 5775: @end example
! 5776:
! 5777: will create a plot of f(x) using the default triangles connected by a red
! 5778: line and q(x) using small triangles connected by a green line.
! 5779:
! 5780: @node lmargin, locale, linestyle, set-show
! 5781: @subsection lmargin
! 5782:
! 5783: @c ?commands set lmargin
! 5784: @c ?set lmargin
! 5785: @cindex lmargin
! 5786: @opindex lmargin
! 5787:
! 5788:
! 5789: The command @ref{lmargin} sets the size of the left margin. Please see
! 5790: @ref{margin} for details.
! 5791:
! 5792: @node locale, logscale, lmargin, set-show
! 5793: @subsection locale
! 5794:
! 5795: @c ?commands set locale
! 5796: @c ?commands show logscale
! 5797: @c ?set locale
! 5798: @c ?show logscale
! 5799: @cindex locale
! 5800: @opindex locale
! 5801:
! 5802:
! 5803: The @ref{locale} setting determines the language with which `@{x,y,z@}@{d,m@}tics`
! 5804: will write the days and months.
! 5805:
! 5806: Syntax:
! 5807: @example
! 5808: set locale @{"<locale>"@}
! 5809:
! 5810: @end example
! 5811:
! 5812: <locale> may be any language designation acceptable to your installation.
! 5813: See your system documentation for the available options. The default value
! 5814: is determined from the LANG environment variable.
! 5815:
! 5816: @node logscale, mapping, locale, set-show
! 5817: @subsection logscale
! 5818:
! 5819: @c ?commands set logscale
! 5820: @c ?commands set nologscale
! 5821: @c ?commands show logscale
! 5822: @c ?set logscale
! 5823: @c ?set nologscale
! 5824: @c ?show logscale
! 5825: @cindex logscale
! 5826: @opindex logscale
! 5827:
! 5828:
! 5829: @cindex nologscale
! 5830:
! 5831: Log scaling may be set on the x, y, z, x2 and/or y2 axes.
! 5832:
! 5833: Syntax:
! 5834: @example
! 5835: set logscale <axes> <base>
! 5836: set nologscale <axes>
! 5837: show logscale
! 5838:
! 5839: @end example
! 5840:
! 5841: where <axes> may be any combinations of `x`, `y`, and `z`, in any order, or
! 5842: `x2` or `y2` and where <base> is the base of the log scaling. If <base> is
! 5843: not given, then 10 is assumed. If <axes> is not given, then all axes are
! 5844: assumed. `set nologscale` turns off log scaling for the specified axes.
! 5845:
! 5846: Examples:
! 5847:
! 5848: To enable log scaling in both x and z axes:
! 5849: @example
! 5850: set logscale xz
! 5851:
! 5852: @end example
! 5853:
! 5854: To enable scaling log base 2 of the y axis:
! 5855: @example
! 5856: set logscale y 2
! 5857:
! 5858: @end example
! 5859:
! 5860: To disable z axis log scaling:
! 5861: @example
! 5862: set nologscale z
! 5863:
! 5864: @end example
! 5865:
! 5866: @node mapping, margin, logscale, set-show
! 5867: @subsection mapping
! 5868:
! 5869: @c ?commands set mapping
! 5870: @c ?commands show mapping
! 5871: @c ?set mapping
! 5872: @c ?show mapping
! 5873: @cindex mapping
! 5874: @opindex mapping
! 5875:
! 5876:
! 5877: If data are provided to `splot` in spherical or cylindrical coordinates,
! 5878: the @ref{mapping} command should be used to instruct `gnuplot` how to
! 5879: interpret them.
! 5880:
! 5881: Syntax:
! 5882: @example
! 5883: set mapping @{cartesian | spherical | cylindrical@}
! 5884:
! 5885: @end example
! 5886:
! 5887: A cartesian coordinate system is used by default.
! 5888:
! 5889: For a spherical coordinate system, the data occupy two or three columns (or
! 5890: @ref{using} entries). The first two are interpreted as the polar and azimuthal
! 5891: angles theta and phi (in the units specified by @ref{angles}). The radius r
! 5892: is taken from the third column if there is one, or is set to unity if there
! 5893: is no third column. The mapping is:
! 5894:
! 5895: @example
! 5896: x = r * cos(theta) * cos(phi)
! 5897: y = r * sin(theta) * cos(phi)
! 5898: z = r * sin(phi)
! 5899:
! 5900: @end example
! 5901:
! 5902: Note that this is a "geographic" spherical system, rather than a "polar" one.
! 5903:
! 5904: For a cylindrical coordinate system, the data again occupy two or three
! 5905: columns. The first two are interpreted as theta (in the units specified by
! 5906: @ref{angles}) and z. The radius is either taken from the third column or set
! 5907: to unity, as in the spherical case. The mapping is:
! 5908:
! 5909: @example
! 5910: x = r * cos(theta)
! 5911: y = r * sin(theta)
! 5912: z = z
! 5913:
! 5914: @end example
! 5915:
! 5916: The effects of @ref{mapping} can be duplicated with the @ref{using} filter on the
! 5917: `splot` command, but @ref{mapping} may be more convenient if many data files are
! 5918: to be processed. However even if @ref{mapping} is used, @ref{using} may still be
! 5919: necessary if the data in the file are not in the required order.
! 5920:
! 5921: @ref{mapping} has no effect on @ref{plot}.
! 5922: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/world.html,Mapping Demos.}
! 5923:
! 5924: @node margin, missing, mapping, set-show
! 5925: @subsection margin
! 5926:
! 5927: @c ?commands set margin
! 5928: @c ?commands show margin
! 5929: @c ?set margin
! 5930: @c ?show margin
! 5931: @cindex margin
! 5932: @opindex margin
! 5933:
! 5934:
! 5935: The computed margins can be overridden by the @ref{margin} commands. @ref{margin} shows the current settings.
! 5936:
! 5937: Syntax:
! 5938: @example
! 5939: set bmargin @{<margin>@}
! 5940: set lmargin @{<margin>@}
! 5941: set rmargin @{<margin>@}
! 5942: set tmargin @{<margin>@}
! 5943: show margin
! 5944:
! 5945: @end example
! 5946:
! 5947: The units of <margin> are character heights or widths, as appropriate. A
! 5948: positive value defines the absolute size of the margin. A negative value
! 5949: (or none) causes `gnuplot` to revert to the computed value.
! 5950:
! 5951: Normally the margins of a plot are automatically calculated based on tics,
! 5952: tic labels, axis labels, the plot title, the timestamp and the size of the
! 5953: key if it is outside the borders. If, however, tics are attached to the
! 5954: axes (`set xtics axis`, for example), neither the tics themselves nor their
! 5955: labels will be included in either the margin calculation or the calculation
! 5956: of the positions of other text to be written in the margin. This can lead
! 5957: to tic labels overwriting other text if the axis is very close to the border.
! 5958:
! 5959: @node missing, multiplot, margin, set-show
! 5960: @subsection missing
! 5961:
! 5962: @c ?commands set missing
! 5963: @c ?set missing
! 5964: @cindex missing
! 5965: @opindex missing
! 5966:
! 5967:
! 5968: The @ref{missing} command allows you to tell `gnuplot` what character is
! 5969: used in a data file to denote missing data.
! 5970:
! 5971: Syntax:
! 5972: @example
! 5973: set missing @{"<character>"@}
! 5974: show missing
! 5975:
! 5976: @end example
! 5977:
! 5978: Example:
! 5979: @example
! 5980: set missing "?"
! 5981:
! 5982: @end example
! 5983:
! 5984: would mean that, when plotting a file containing
! 5985:
! 5986: @example
! 5987: 1 1
! 5988: 2 ?
! 5989: 3 2
! 5990:
! 5991: @end example
! 5992:
! 5993: the middle line would be ignored.
! 5994:
! 5995: There is no default character for @ref{missing}.
! 5996:
! 5997: @node multiplot, mx2tics, missing, set-show
! 5998: @subsection multiplot
! 5999:
! 6000: @c ?commands set multiplot
! 6001: @c ?commands set nomultiplot
! 6002: @c ?set multiplot
! 6003: @c ?set nomultiplot
! 6004: @cindex multiplot
! 6005: @opindex multiplot
! 6006:
! 6007:
! 6008: @cindex nomultiplot
! 6009:
! 6010: The command @ref{multiplot} places `gnuplot` in the multiplot mode, in which
! 6011: several plots are placed on the same page, window, or screen.
! 6012:
! 6013: Syntax:
! 6014: @example
! 6015: set multiplot
! 6016: set nomultiplot
! 6017:
! 6018: @end example
! 6019:
! 6020: For some terminals, no plot is displayed until the command `set nomultiplot`
! 6021: is given, which causes the entire page to be drawn and then returns `gnuplot`
! 6022: to its normal single-plot mode. For other terminals, each separate @ref{plot}
! 6023: command produces a plot, but the screen may not be cleared between plots.
! 6024:
! 6025: Any labels or arrows that have been defined will be drawn for each plot
! 6026: according to the current size and origin (unless their coordinates are
! 6027: defined in the `screen` system). Just about everything else that can be
! 6028: `set` is applied to each plot, too. If you want something to appear only
! 6029: once on the page, for instance a single time stamp, you'll need to put a `set
! 6030: time`/`set notime` pair around one of the @ref{plot}, `splot` or @ref{replot}
! 6031: commands within the @ref{multiplot}/`set nomultiplot` block.
! 6032:
! 6033: The commands @ref{origin} and @ref{size} must be used to correctly position
! 6034: each plot; see @ref{origin} and @ref{size} for details of their usage.
! 6035:
! 6036: Example:
! 6037: @example
! 6038: set size 0.7,0.7
! 6039: set origin 0.1,0.1
! 6040: set multiplot
! 6041: set size 0.4,0.4
! 6042: set origin 0.1,0.1
! 6043: plot sin(x)
! 6044: set size 0.2,0.2
! 6045: set origin 0.5,0.5
! 6046: plot cos(x)
! 6047: set nomultiplot
! 6048:
! 6049: @end example
! 6050:
! 6051: displays a plot of cos(x) stacked above a plot of sin(x). Note the initial
! 6052: @ref{size} and @ref{origin}. While these are not always required, their
! 6053: inclusion is recommended. Some terminal drivers require that bounding box
! 6054: information be available before any plots can be made, and the form given
! 6055: above guarantees that the bounding box will include the entire plot array
! 6056: rather than just the bounding box of the first plot.
! 6057:
! 6058: @ref{size} and @ref{origin} refer to the entire plotting area used for each
! 6059: plot. If you want to have the axes themselves line up, you can guarantee
! 6060: that the margins are the same size with the @ref{margin} commands. See
! 6061: @ref{margin} for their use. Note that the margin settings are absolute,
! 6062: in character units, so the appearance of the graph in the remaining space
! 6063: will depend on the screen size of the display device, e.g., perhaps quite
! 6064: different on a video display and a printer.
! 6065: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/multiplt.html,See demo. }
! 6066:
! 6067: @node mx2tics, mxtics, multiplot, set-show
! 6068: @subsection mx2tics
! 6069:
! 6070: @c ?commands set mx2tics
! 6071: @c ?commands set nomx2tics
! 6072: @c ?commands show mx2tics
! 6073: @c ?set mx2tics
! 6074: @c ?set nomx2tics
! 6075: @c ?show mx2tics
! 6076: @cindex mx2tics
! 6077: @opindex mx2tics
! 6078:
! 6079:
! 6080: @cindex nomx2tics
! 6081:
! 6082: Minor tic marks along the x2 (top) axis are controlled by @ref{mx2tics}.
! 6083: Please see @ref{mxtics}.
! 6084:
! 6085: @node mxtics, my2tics, mx2tics, set-show
! 6086: @subsection mxtics
! 6087:
! 6088: @c ?commands set mxtics
! 6089: @c ?commands set nomxtics
! 6090: @c ?commands show mxtics
! 6091: @c ?set mxtics
! 6092: @c ?set nomxtics
! 6093: @c ?show mxtics
! 6094: @cindex mxtics
! 6095: @opindex mxtics
! 6096:
! 6097:
! 6098: @cindex nomxtics
! 6099:
! 6100: Minor tic marks along the x axis are controlled by @ref{mxtics}. They can be
! 6101: turned off with `set nomxtics`. Similar commands control minor tics along
! 6102: the other axes.
! 6103:
! 6104: Syntax:
! 6105: @example
! 6106: set mxtics @{<freq> | default@}
! 6107: set nomxtics
! 6108: show mxtics
! 6109:
! 6110: @end example
! 6111:
! 6112: The same syntax applies to @ref{mytics}, @ref{mztics}, @ref{mx2tics} and @ref{my2tics}.
! 6113:
! 6114: <freq> is the number of sub-intervals (NOT the number of minor tics) between
! 6115: major tics (ten is the default for a linear axis, so there are nine minor
! 6116: tics between major tics). Selecting `default` will return the number of minor
! 6117: ticks to its default value.
! 6118:
! 6119: If the axis is logarithmic, the number of sub-intervals will be set to a
! 6120: reasonable number by default (based upon the length of a decade). This will
! 6121: be overridden if <freq> is given. However the usual minor tics (2, 3, ...,
! 6122: 8, 9 between 1 and 10, for example) are obtained by setting <freq> to 10,
! 6123: even though there are but nine sub-intervals.
! 6124:
! 6125: Minor tics can be used only with uniformly spaced major tics. Since major
! 6126: tics can be placed arbitrarily by `set @{x|x2|y|y2|z@}tics`, minor tics cannot
! 6127: be used if major tics are explicitly `set`.
! 6128:
! 6129: By default, minor tics are off for linear axes and on for logarithmic axes.
! 6130: They inherit the settings for `axis|border` and `@{no@}mirror` specified for
! 6131: the major tics. Please see @ref{xtics} for information about these.
! 6132:
! 6133: @node my2tics, mytics, mxtics, set-show
! 6134: @subsection my2tics
! 6135:
! 6136: @c ?commands set my2tics
! 6137: @c ?commands set nomy2tics
! 6138: @c ?commands show my2tics
! 6139: @c ?set my2tics
! 6140: @c ?set nomy2tics
! 6141: @c ?show my2tics
! 6142: @cindex my2tics
! 6143: @opindex my2tics
! 6144:
! 6145:
! 6146: @cindex nomy2tics
! 6147:
! 6148: Minor tic marks along the y2 (right-hand) axis are controlled by @ref{my2tics}. Please see @ref{mxtics}.
! 6149:
! 6150: @node mytics, mztics, my2tics, set-show
! 6151: @subsection mytics
! 6152:
! 6153: @c ?commands set mytics
! 6154: @c ?commands set nomytics
! 6155: @c ?commands show mytics
! 6156: @c ?set mytics
! 6157: @c ?set nomytics
! 6158: @c ?show mytics
! 6159: @cindex mytics
! 6160: @opindex mytics
! 6161:
! 6162:
! 6163: @cindex nomytics
! 6164:
! 6165: Minor tic marks along the y axis are controlled by @ref{mytics}. Please
! 6166: see @ref{mxtics}.
! 6167:
! 6168: @node mztics, offsets, mytics, set-show
! 6169: @subsection mztics
! 6170:
! 6171: @c ?commands set mztics
! 6172: @c ?commands set nomztics
! 6173: @c ?commands show mztics
! 6174: @c ?set mztics
! 6175: @c ?set nomztics
! 6176: @c ?show mztics
! 6177: @cindex mztics
! 6178: @opindex mztics
! 6179:
! 6180:
! 6181: @cindex nomztics
! 6182:
! 6183: Minor tic marks along the z axis are controlled by @ref{mztics}. Please
! 6184: see @ref{mxtics}.
! 6185:
! 6186: @node offsets, origin, mztics, set-show
! 6187: @subsection offsets
! 6188:
! 6189: @c ?commands set offsets
! 6190: @c ?commands set nooffsets
! 6191: @c ?commands show offsets
! 6192: @c ?set offsets
! 6193: @c ?set nooffsets
! 6194: @c ?show offsets
! 6195: @cindex offsets
! 6196: @opindex offsets
! 6197:
! 6198:
! 6199: @cindex nooffsets
! 6200:
! 6201: Offsets provide a mechanism to put a boundary around the data inside of an
! 6202: autoscaled graph.
! 6203:
! 6204: Syntax:
! 6205: @example
! 6206: set offsets <left>, <right>, <top>, <bottom>
! 6207: set nooffsets
! 6208: show offsets
! 6209:
! 6210: @end example
! 6211:
! 6212: Each offset may be a constant or an expression. Each defaults to 0. Left
! 6213: and right offsets are given in units of the x axis, top and bottom offsets in
! 6214: units of the y axis. A positive offset expands the graph in the specified
! 6215: direction, e.g., a positive bottom offset makes ymin more negative. Negative
! 6216: offsets, while permitted, can have unexpected interactions with autoscaling
! 6217: and clipping.
! 6218:
! 6219: Offsets are ignored in `splot`s.
! 6220:
! 6221: Example:
! 6222: @example
! 6223: set offsets 0, 0, 2, 2
! 6224: plot sin(x)
! 6225:
! 6226: @end example
! 6227:
! 6228: This graph of sin(x) will have a y range [-3:3] because the function
! 6229: will be autoscaled to [-1:1] and the vertical offsets are each two.
! 6230:
! 6231: @node origin, output, offsets, set-show
! 6232: @subsection origin
! 6233:
! 6234: @c ?commands set origin
! 6235: @c ?commands show origin
! 6236: @c ?set origin
! 6237: @c ?show origin
! 6238: @cindex origin
! 6239: @opindex origin
! 6240:
! 6241:
! 6242: The @ref{origin} command is used to specify the origin of a plotting surface
! 6243: (i.e., the graph and its margins) on the screen. The coordinates are given
! 6244: in the `screen` coordinate system (see `coordinates` for information about
! 6245: this system).
! 6246:
! 6247: Syntax:
! 6248: @example
! 6249: set origin <x-origin>,<y-origin>
! 6250:
! 6251: @end example
! 6252:
! 6253: @node output, parametric_, origin, set-show
! 6254: @subsection output
! 6255:
! 6256: @c ?commands set output
! 6257: @c ?commands show output
! 6258: @c ?set output
! 6259: @c ?show output
! 6260: @cindex output
! 6261: @opindex output
! 6262:
! 6263:
! 6264: By default, screens are displayed to the standard output. The @ref{output}
! 6265: command redirects the display to the specified file or device.
! 6266:
! 6267: Syntax:
! 6268: @example
! 6269: set output @{"<filename>"@}
! 6270: show output
! 6271:
! 6272: @end example
! 6273:
! 6274: The filename must be enclosed in quotes. If the filename is omitted, any
! 6275: output file opened by a previous invocation of @ref{output} will be closed
! 6276: and new output will be sent to STDOUT. (If you give the command `set output
! 6277: "STDOUT"`, your output may be sent to a file named "STDOUT"! ["May be", not
! 6278: "will be", because some terminals, like `x11`, ignore @ref{output}.])
! 6279:
! 6280: MSDOS users should note that the \ character has special significance in
! 6281: double-quoted strings, so single-quotes should be used for filenames in
! 6282: different directories.
! 6283:
! 6284: When both @ref{terminal} and @ref{output} are used together, it is safest to
! 6285: give @ref{terminal} first, because some terminals set a flag which is needed
! 6286: in some operating systems. This would be the case, for example, if the
! 6287: operating system needs to know whether or not a file is to be formatted in
! 6288: order to open it properly.
! 6289:
! 6290: On machines with popen functions (Unix), output can be piped through a shell
! 6291: command if the first non-whitespace character of the filename is '|'.
! 6292: For instance,
! 6293:
! 6294: @example
! 6295: set output "|lpr -Plaser filename"
! 6296: set output "|lp -dlaser filename"
! 6297:
! 6298: @end example
! 6299:
! 6300: On MSDOS machines, `set output "PRN"` will direct the output to the default
! 6301: printer. On VMS, output can be sent directly to any spooled device. It is
! 6302: also possible to send the output to DECnet transparent tasks, which allows
! 6303: some flexibility.
! 6304:
! 6305: @node parametric_, pointsize, output, set-show
! 6306: @subsection parametric
! 6307:
! 6308: @c ?commands set parametric
! 6309: @c ?commands set noparametric
! 6310: @c ?commands show parametric
! 6311: @c ?set parametric
! 6312: @c ?set noparametric
! 6313: @c ?show parametric
! 6314: @cindex parametric
! 6315: @opindex parametric
! 6316:
! 6317:
! 6318: @cindex noparametric
! 6319:
! 6320: The `set parametric` command changes the meaning of @ref{plot} (`splot`) from
! 6321: normal functions to parametric functions. The command `set noparametric`
! 6322: restores the plotting style to normal, single-valued expression plotting.
! 6323:
! 6324: Syntax:
! 6325: @example
! 6326: set parametric
! 6327: set noparametric
! 6328: show parametric
! 6329:
! 6330: @end example
! 6331:
! 6332: For 2-d plotting, a parametric function is determined by a pair of parametric
! 6333: functions operating on a parameter. An example of a 2-d parametric function
! 6334: would be `plot sin(t),cos(t)`, which draws a circle (if the aspect ratio is
! 6335: set correctly---see @ref{size}). `gnuplot` will display an error message if
! 6336: both functions are not provided for a parametric @ref{plot}.
! 6337:
! 6338: For 3-d plotting, the surface is described as x=f(u,v), y=g(u,v), z=h(u,v).
! 6339: Therefore a triplet of functions is required. An example of a 3-d parametric
! 6340: function would be `cos(u)*cos(v),cos(u)*sin(v),sin(u)`, which draws a sphere.
! 6341: `gnuplot` will display an error message if all three functions are not
! 6342: provided for a parametric `splot`.
! 6343:
! 6344: The total set of possible plots is a superset of the simple f(x) style plots,
! 6345: since the two functions can describe the x and y values to be computed
! 6346: separately. In fact, plots of the type t,f(t) are equivalent to those
! 6347: produced with f(x) because the x values are computed using the identity
! 6348: function. Similarly, 3-d plots of the type u,v,f(u,v) are equivalent to
! 6349: f(x,y).
! 6350:
! 6351: Note that the order the parametric functions are specified is xfunction,
! 6352: yfunction (and zfunction) and that each operates over the common parametric
! 6353: domain.
! 6354:
! 6355: Also, the `set parametric` function implies a new range of values. Whereas
! 6356: the normal f(x) and f(x,y) style plotting assume an xrange and yrange (and
! 6357: zrange), the parametric mode additionally specifies a trange, urange, and
! 6358: vrange. These ranges may be set directly with @ref{trange}, @ref{urange},
! 6359: and @ref{vrange}, or by specifying the range on the @ref{plot} or `splot`
! 6360: commands. Currently the default range for these parametric variables is
! 6361: [-5:5]. Setting the ranges to something more meaningful is expected.
! 6362:
! 6363: @node pointsize, polar, parametric_, set-show
! 6364: @subsection pointsize
! 6365:
! 6366: @c ?commands set pointsize
! 6367: @c ?commands show pointsize
! 6368: @c ?set pointsize
! 6369: @c ?show pointsize
! 6370: @cindex pointsize
! 6371: @opindex pointsize
! 6372:
! 6373:
! 6374: The @ref{pointsize} command scales the size of the points used in plots.
! 6375:
! 6376: Syntax:
! 6377: @example
! 6378: set pointsize <multiplier>
! 6379: show pointsize
! 6380:
! 6381: @end example
! 6382:
! 6383: The default is a multiplier of 1.0. Larger pointsizes may be useful to
! 6384: make points more visible in bitmapped graphics.
! 6385:
! 6386: The pointsize of a single plot may be changed on the @ref{plot} command. See
! 6387: @ref{with} for details.
! 6388:
! 6389: Please note that the pointsize setting is not supported by all terminal
! 6390: types.
! 6391:
! 6392: @node polar, rmargin, pointsize, set-show
! 6393: @subsection polar
! 6394:
! 6395: @c ?commands set polar
! 6396: @c ?commands set nopolar
! 6397: @c ?commands show polar
! 6398: @c ?set polar
! 6399: @c ?set nopolar
! 6400: @c ?show polar
! 6401: @cindex polar
! 6402: @opindex polar
! 6403:
! 6404:
! 6405: @cindex nopolar
! 6406:
! 6407: The `set polar` command changes the meaning of the plot from rectangular
! 6408: coordinates to polar coordinates.
! 6409:
! 6410: Syntax:
! 6411: @example
! 6412: set polar
! 6413: set nopolar
! 6414: show polar
! 6415:
! 6416: @end example
! 6417:
! 6418: There have been changes made to polar mode in version 3.7, so that scripts
! 6419: for `gnuplot` versions 3.5 and earlier will require modification. The main
! 6420: change is that the dummy variable t is used for the angle so that the x and
! 6421: y ranges can be controlled independently. Other changes are:
! 6422: 1) tics are no longer put along the zero axes automatically
! 6423: ---use `set xtics axis nomirror`; `set ytics axis nomirror`;
! 6424: 2) the grid, if selected, is not automatically polar
! 6425: ---use `set grid polar`;
! 6426: 3) the grid is not labelled with angles
! 6427: ---use @ref{label} as necessary.
! 6428:
! 6429: In polar coordinates, the dummy variable (t) is an angle. The default range
! 6430: of t is [0:2*pi], or, if degree units have been selected, to [0:360] (see
! 6431: @ref{angles}).
! 6432:
! 6433: The command `set nopolar` changes the meaning of the plot back to the default
! 6434: rectangular coordinate system.
! 6435:
! 6436: The `set polar` command is not supported for `splot`s. See the @ref{mapping}
! 6437: command for similar functionality for `splot`s.
! 6438:
! 6439: While in polar coordinates the meaning of an expression in t is really
! 6440: r = f(t), where t is an angle of rotation. The trange controls the domain
! 6441: (the angle) of the function, and the x and y ranges control the range of the
! 6442: graph in the x and y directions. Each of these ranges, as well as the
! 6443: rrange, may be autoscaled or set explicitly. See @ref{xrange} for details
! 6444: of all the `set range` commands.
! 6445:
! 6446: Example:
! 6447: @example
! 6448: set polar
! 6449: plot t*sin(t)
! 6450: plot [-2*pi:2*pi] [-3:3] [-3:3] t*sin(t)
! 6451:
! 6452: @end example
! 6453:
! 6454: The first @ref{plot} uses the default polar angular domain of 0 to 2*pi. The
! 6455: radius and the size of the graph are scaled automatically. The second @ref{plot}
! 6456: expands the domain, and restricts the size of the graph to [-3:3] in both
! 6457: directions.
! 6458:
! 6459: You may want to `set size square` to have `gnuplot` try to make the aspect
! 6460: ratio equal to unity, so that circles look circular.
! 6461: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/polar.html,Polar demos }
! 6462: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html,Polar Data Plot. }
! 6463:
! 6464: @node rmargin, rrange, polar, set-show
! 6465: @subsection rmargin
! 6466:
! 6467: @c ?commands set rmargin
! 6468: @c ?set rmargin
! 6469: @cindex rmargin
! 6470: @opindex rmargin
! 6471:
! 6472:
! 6473: The command @ref{rmargin} sets the size of the right margin. Please see
! 6474: @ref{margin} for details.
! 6475:
! 6476: @node rrange, samples, rmargin, set-show
! 6477: @subsection rrange
! 6478:
! 6479: @c ?commands set rrange
! 6480: @c ?commands show rrange
! 6481: @c ?set rrange
! 6482: @c ?show rrange
! 6483: @cindex rrange
! 6484: @opindex rrange
! 6485:
! 6486:
! 6487: The @ref{rrange} command sets the range of the radial coordinate for a
! 6488: graph in polar mode. Please see @ref{xrange} for details.
! 6489:
! 6490: @node samples, size, rrange, set-show
! 6491: @subsection samples
! 6492:
! 6493: @c ?commands set samples
! 6494: @c ?commands show samples
! 6495: @c ?set samples
! 6496: @c ?show samples
! 6497: @cindex samples
! 6498: @opindex samples
! 6499:
! 6500:
! 6501: The sampling rate of functions, or for interpolating data, may be changed
! 6502: by the @ref{samples} command.
! 6503:
! 6504: Syntax:
! 6505: @example
! 6506: set samples <samples_1> @{,<samples_2>@}
! 6507: show samples
! 6508:
! 6509: @end example
! 6510:
! 6511: By default, sampling is set to 100 points. A higher sampling rate will
! 6512: produce more accurate plots, but will take longer. This parameter has no
! 6513: effect on data file plotting unless one of the interpolation/approximation
! 6514: options is used. See @ref{smooth} re 2-d data and @ref{cntrparam} and
! 6515: @ref{dgrid3d} re 3-d data.
! 6516:
! 6517: When a 2-d graph is being done, only the value of <samples_1> is relevant.
! 6518:
! 6519: When a surface plot is being done without the removal of hidden lines, the
! 6520: value of samples specifies the number of samples that are to be evaluated for
! 6521: the isolines. Each iso-v line will have <sample_1> samples and each iso-u
! 6522: line will have <sample_2> samples. If you only specify <samples_1>,
! 6523: <samples_2> will be set to the same value as <samples_1>. See also @ref{isosamples}.
! 6524:
! 6525: @node size, style, samples, set-show
! 6526: @subsection size
! 6527:
! 6528: @c ?commands set size
! 6529: @c ?commands show size
! 6530: @c ?set size
! 6531: @c ?show size
! 6532: @cindex size
! 6533: @opindex size
! 6534:
! 6535:
! 6536: The @ref{size} command scales the displayed size of the plot.
! 6537:
! 6538: Syntax:
! 6539: @example
! 6540: set size @{@{no@}square | ratio <r> | noratio@} @{<xscale>,<yscale>@}
! 6541: show size
! 6542:
! 6543: @end example
! 6544:
! 6545: The <xscale> and <yscale> values are the scaling factors for the size of the
! 6546: plot, which includes the graph and the margins.
! 6547:
! 6548: `ratio` causes `gnuplot` to try to create a graph with an aspect ratio of <r>
! 6549: (the ratio of the y-axis length to the x-axis length) within the portion of
! 6550: the plot specified by <xscale> and <yscale>.
! 6551:
! 6552: The meaning of a negative value for <r> is different. If <r>=-1, gnuplot
! 6553: tries to set the scales so that the unit has the same length on both the x
! 6554: and y axes (suitable for geographical data, for instance). If <r>=-2, the
! 6555: unit on y has twice the length of the unit on x, and so on.
! 6556:
! 6557: The success of `gnuplot` in producing the requested aspect ratio depends on
! 6558: the terminal selected. The graph area will be the largest rectangle of
! 6559: aspect ratio <r> that will fit into the specified portion of the output
! 6560: (leaving adequate margins, of course).
! 6561:
! 6562: `square` is a synonym for `ratio 1`.
! 6563:
! 6564: Both `noratio` and `nosquare` return the graph to the default aspect ratio
! 6565: of the terminal, but do not return <xscale> or <yscale> to their default
! 6566: values (1.0).
! 6567:
! 6568: `ratio` and `square` have no effect on 3-d plots.
! 6569:
! 6570: @ref{size} is relative to the default size, which differs from terminal to
! 6571: terminal. Since `gnuplot` fills as much of the available plotting area as
! 6572: possible by default, it is safer to use @ref{size} to decrease the size of
! 6573: a plot than to increase it. See @ref{terminal} for the default sizes.
! 6574:
! 6575: On some terminals, changing the size of the plot will result in text being
! 6576: misplaced.
! 6577:
! 6578: Examples:
! 6579:
! 6580: To set the size to normal size use:
! 6581: @example
! 6582: set size 1,1
! 6583:
! 6584: @end example
! 6585:
! 6586: To make the graph half size and square use:
! 6587: @example
! 6588: set size square 0.5,0.5
! 6589:
! 6590: @end example
! 6591:
! 6592: To make the graph twice as high as wide use:
! 6593: @example
! 6594: set size ratio 2
! 6595:
! 6596: @end example
! 6597:
! 6598: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html,See demo. }
! 6599:
! 6600: @node style, surface, size, set-show
! 6601: @subsection style
! 6602:
! 6603: @c ?commands set function style
! 6604: @c ?commands show function style
! 6605: @c ?commands set data style
! 6606: @c ?commands show data style
! 6607: @c ?set function style
! 6608: @c ?show function style
! 6609: @c ?set data style
! 6610: @c ?show data style
! 6611: @c ?set style
! 6612: @c ?show style
! 6613: Default styles are chosen with the @ref{style} and @ref{style}
! 6614: commands. See @ref{with} for information about how to override the default
! 6615: plotting style for individual functions and data sets.
! 6616:
! 6617: Syntax:
! 6618: @example
! 6619: set function style <style>
! 6620: set data style <style>
! 6621: show function style
! 6622: show data style
! 6623:
! 6624: @end example
! 6625:
! 6626: The types used for all line and point styles (i.e., solid, dash-dot, color,
! 6627: etc. for lines; circles, squares, crosses, etc. for points) will be either
! 6628: those specified on the @ref{plot} or `splot` command or will be chosen
! 6629: sequentially from the types available to the terminal in use. Use the
! 6630: command @ref{test} to see what is available.
! 6631:
! 6632: None of the styles requiring more than two columns of information (e.g.,
! 6633: @ref{errorbars}) can be used with `splot`s or function @ref{plot}s. Neither @ref{boxes}
! 6634: nor any of the @ref{steps} styles can be used with `splot`s. If an inappropriate
! 6635: style is specified, it will be changed to `points`.
! 6636:
! 6637: For 2-d data with more than two columns, `gnuplot` is picky about the allowed
! 6638: `errorbar` styles. The @ref{using} option on the @ref{plot} command can be used to
! 6639: set up the correct columns for the style you want. (In this discussion,
! 6640: "column" will be used to refer both to a column in the data file and an entry
! 6641: in the @ref{using} list.)
! 6642:
! 6643: For three columns, only @ref{xerrorbars}, @ref{yerrorbars} (or @ref{errorbars}), @ref{boxes},
! 6644: and @ref{boxerrorbars} are allowed. If another plot style is used, the style
! 6645: will be changed to @ref{yerrorbars}. The @ref{boxerrorbars} style will calculate the
! 6646: boxwidth automatically.
! 6647:
! 6648: For four columns, only @ref{xerrorbars}, @ref{yerrorbars} (or @ref{errorbars}),
! 6649: @ref{xyerrorbars}, @ref{boxxyerrorbars}, and @ref{boxerrorbars} are allowed. An illegal
! 6650: style will be changed to @ref{yerrorbars}.
! 6651:
! 6652: Five-column data allow only the @ref{boxerrorbars}, @ref{financebars}, and
! 6653: @ref{candlesticks} styles. (The last two of these are primarily used for plots
! 6654: of financial prices.) An illegal style will be changed to @ref{boxerrorbars}
! 6655: before plotting.
! 6656:
! 6657: Six- and seven-column data only allow the @ref{xyerrorbars} and @ref{boxxyerrorbars}
! 6658: styles. Illegal styles will be changed to @ref{xyerrorbars} before plotting.
! 6659:
! 6660: For more information about error bars, please see @ref{errorbars}.
! 6661:
! 6662: @menu
! 6663: * boxerrorbars::
! 6664: * boxes::
! 6665: * boxxyerrorbars::
! 6666: * candlesticks::
! 6667: * dots::
! 6668: * financebars::
! 6669: * fsteps::
! 6670: * histeps::
! 6671: * impulses::
! 6672: * lines::
! 6673: * linespoints::
! 6674: * points::
! 6675: * steps::
! 6676: * vector::
! 6677: * xerrorbars::
! 6678: * xyerrorbars::
! 6679: * yerrorbars::
! 6680: @end menu
! 6681:
! 6682: @node boxerrorbars, boxes, style, style
! 6683: @subsubsection boxerrorbars
! 6684:
! 6685: @c ?commands set style boxerrorbars
! 6686: @c ?set style boxerrorbars
! 6687: @c ?style boxerrorbars
! 6688: @cindex boxerrorbars
! 6689:
! 6690: The @ref{boxerrorbars} style is only relevant to 2-d data plotting. It is a
! 6691: combination of the @ref{boxes} and @ref{yerrorbars} styles. The boxwidth will come
! 6692: from the fourth column if the y errors are in the form of "ydelta" and the
! 6693: boxwidth was not previously set equal to -2.0 (`set boxwidth -2.0`) or from
! 6694: the fifth column if the y errors are in the form of "ylow yhigh". The
! 6695: special case `boxwidth = -2.0` is for four-column data with y errors in the
! 6696: form "ylow yhigh". In this case the boxwidth will be calculated so that each
! 6697: box touches the adjacent boxes. The width will also be calculated in cases
! 6698: where three-column data are used.
! 6699:
! 6700: The box height is determined from the y error in the same way as it is for
! 6701: the @ref{yerrorbars} style---either from y-ydelta to y+ydelta or from ylow to
! 6702: yhigh, depending on how many data columns are provided.
! 6703: @uref{http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html,See Demo. }
! 6704:
! 6705: @node boxes, boxxyerrorbars, boxerrorbars, style
! 6706: @subsubsection boxes
! 6707:
! 6708: @c ?commands set style boxes
! 6709: @c ?commands set style bargraph
! 6710: @c ?set style boxes
! 6711: @c ?set style bargraph
! 6712: @c ?style boxes
! 6713: @c ?style bargraph
! 6714: @cindex boxes
! 6715:
! 6716: @cindex bargraph
! 6717:
! 6718: The @ref{boxes} style is only relevant to 2-d plotting. It draws a box centered
! 6719: about the given x coordinate from the x axis (not the graph border) to the
! 6720: given y coordinate. The width of the box is obtained in one of three ways.
! 6721: If it is a data plot and the data file has a third column, this will be used
! 6722: to set the width of the box. If not, if a width has been set using the @ref{boxwidth} command, this will be used. If neither of these is available, the
! 6723: width of each box will be calculated automatically so that it touches the
! 6724: adjacent boxes.
! 6725:
! 6726: @node boxxyerrorbars, candlesticks, boxes, style
! 6727: @subsubsection boxxyerrorbars
! 6728:
! 6729: @c ?commands set style boxxyerrorbars
! 6730: @c ?set style boxxyerrorbars
! 6731: @c ?style boxxyerrorbars
! 6732: @cindex boxxyerrorbars
! 6733:
! 6734: The @ref{boxxyerrorbars} style is only relevant to 2-d data plotting. It is a
! 6735: combination of the @ref{boxes} and @ref{xyerrorbars} styles.
! 6736:
! 6737: The box width and height are determined from the x and y errors in the same
! 6738: way as they are for the @ref{xyerrorbars} style---either from xlow to xhigh and
! 6739: from ylow to yhigh, or from x-xdelta to x+xdelta and from y-ydelta to
! 6740: y+ydelta , depending on how many data columns are provided.
! 6741:
! 6742: @node candlesticks, dots, boxxyerrorbars, style
! 6743: @subsubsection candlesticks
! 6744:
! 6745: @c ?commands set style candlesticks
! 6746: @c ?set style candlesticks
! 6747: @c ?style candlesticks
! 6748: @cindex candlesticks
! 6749:
! 6750: The @ref{candlesticks} style is only relevant for 2-d data plotting of financial
! 6751: data. Five columns of data are required; in order, these should be the x
! 6752: coordinate (most likely a date) and the opening, low, high, and closing
! 6753: prices. The symbol is an open rectangle, centered horizontally at the x
! 6754: coordinate and limited vertically by the opening and closing prices. A
! 6755: vertical line segment at the x coordinate extends up from the top of the
! 6756: rectangle to the high price and another down to the low. The width of the
! 6757: rectangle may be changed by @ref{bar}. The symbol will be unchanged if the
! 6758: low and high prices are interchanged or if the opening and closing prices
! 6759: are interchanged. See @ref{bar} and @ref{financebars}.
! 6760: @uref{http://www.nas.nasa.gov/~woo/gnuplot/finance/finance.html,See demos.}
! 6761:
! 6762: @node dots, financebars, candlesticks, style
! 6763: @subsubsection dots
! 6764:
! 6765: @c ?commands set style dots
! 6766: @c ?set style dots
! 6767: @c ?style dots
! 6768: @cindex dots
! 6769:
! 6770: The @ref{dots} style plots a tiny dot at each point; this is useful for scatter
! 6771: plots with many points.
! 6772:
! 6773: @node financebars, fsteps, dots, style
! 6774: @subsubsection financebars
! 6775:
! 6776: @c ?commands set style financebars
! 6777: @c ?set style financebars
! 6778: @c ?style financebars
! 6779: @cindex financebars
! 6780:
! 6781: The @ref{financebars} style is only relevant for 2-d data plotting of financial
! 6782: data. Five columns of data are required; in order, these should be the x
! 6783: coordinate (most likely a date) and the opening, low, high, and closing
! 6784: prices. The symbol is a vertical line segment, located horizontally at the x
! 6785: coordinate and limited vertically by the high and low prices. A horizontal
! 6786: tic on the left marks the opening price and one on the right marks the
! 6787: closing price. The length of these tics may be changed by @ref{bar}. The
! 6788: symbol will be unchanged if the high and low prices are interchanged. See
! 6789: @ref{bar} and @ref{candlesticks}.
! 6790: @uref{http://www.nas.nasa.gov/~woo/gnuplot/finance/finance.html,See demos.}
! 6791:
! 6792: @node fsteps, histeps, financebars, style
! 6793: @subsubsection fsteps
! 6794:
! 6795: @c ?commands set style fsteps
! 6796: @c ?set style fsteps
! 6797: @c ?style fsteps
! 6798: @cindex fsteps
! 6799:
! 6800: The @ref{fsteps} style is only relevant to 2-d plotting. It connects consecutive
! 6801: points with two line segments: the first from (x1,y1) to (x1,y2) and the
! 6802: second from (x1,y2) to (x2,y2).
! 6803: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html,See demo. }
! 6804:
! 6805: @node histeps, impulses, fsteps, style
! 6806: @subsubsection histeps
! 6807:
! 6808: @c ?commands set style histeps
! 6809: @c ?set style histeps
! 6810: @c ?style histeps
! 6811: @cindex histeps
! 6812:
! 6813: The @ref{histeps} style is only relevant to 2-d plotting. It is intended for
! 6814: plotting histograms. Y-values are assumed to be centered at the x-values;
! 6815: the point at x1 is represented as a horizontal line from ((x0+x1)/2,y1) to
! 6816: ((x1+x2)/2,y1). The lines representing the end points are extended so that
! 6817: the step is centered on at x. Adjacent points are connected by a vertical
! 6818: line at their average x, that is, from ((x1+x2)/2,y1) to ((x1+x2)/2,y2).
! 6819:
! 6820: If @ref{autoscale} is in effect, it selects the xrange from the data rather than
! 6821: the steps, so the end points will appear only half as wide as the others.
! 6822: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html,See demo. }
! 6823:
! 6824: @ref{histeps} is only a plotting style; `gnuplot` does not have the ability to
! 6825: create bins and determine their population from some data set.
! 6826:
! 6827: @node impulses, lines, histeps, style
! 6828: @subsubsection impulses
! 6829:
! 6830: @c ?commands set style impulses
! 6831: @c ?set style impulses
! 6832: @c ?style impulses
! 6833: @cindex impulses
! 6834:
! 6835: The @ref{impulses} style displays a vertical line from the x axis (not the graph
! 6836: border), or from the grid base for `splot`, to each point.
! 6837:
! 6838: @node lines, linespoints, impulses, style
! 6839: @subsubsection lines
! 6840:
! 6841: @c ?commands set style lines
! 6842: @c ?set style lines
! 6843: @c ?style lines
! 6844: @cindex lines
! 6845:
! 6846: The `lines` style connects adjacent points with straight line segments.
! 6847:
! 6848: @node linespoints, points, lines, style
! 6849: @subsubsection linespoints
! 6850:
! 6851: @c ?commands set style linespoints
! 6852: @c ?commands set style lp
! 6853: @c ?set style linespoints
! 6854: @c ?set style lp
! 6855: @c ?style linespoints
! 6856: @c ?style lp
! 6857: @cindex linespoints
! 6858:
! 6859: @cindex lp
! 6860:
! 6861: The @ref{linespoints} style does both `lines` and `points`, that is, it draws a
! 6862: small symbol at each point and then connects adjacent points with straight
! 6863: line segments. The command @ref{pointsize} may be used to change the size of
! 6864: the points. See @ref{pointsize} for its usage.
! 6865:
! 6866: @ref{linespoints} may be abbreviated `lp`.
! 6867:
! 6868: @node points, steps, linespoints, style
! 6869: @subsubsection points
! 6870:
! 6871: @c ?commands set style points
! 6872: @c ?set style points
! 6873: @c ?style points
! 6874: @cindex points
! 6875:
! 6876: The `points` style displays a small symbol at each point. The command @ref{pointsize} may be used to change the size of the points. See @ref{pointsize}
! 6877: for its usage.
! 6878:
! 6879: @node steps, vector, points, style
! 6880: @subsubsection steps
! 6881:
! 6882: @c ?commands set style steps
! 6883: @c ?set style steps
! 6884: @c ?style steps
! 6885: @cindex steps
! 6886:
! 6887: The @ref{steps} style is only relevant to 2-d plotting. It connects consecutive
! 6888: points with two line segments: the first from (x1,y1) to (x2,y1) and the
! 6889: second from (x2,y1) to (x2,y2).
! 6890: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html,See demo. }
! 6891:
! 6892: @node vector, xerrorbars, steps, style
! 6893: @subsubsection vector
! 6894:
! 6895: @c ?commands set style vector
! 6896: @c ?set style vector
! 6897: @c ?style vector
! 6898: @cindex vector
! 6899:
! 6900: The @ref{vector} style draws a vector from (x,y) to (x+xdelta,y+ydelta). Thus
! 6901: it requires four columns of data. It also draws a small arrowhead at the
! 6902: end of the vector.
! 6903:
! 6904: The @ref{vector} style is still experimental: it doesn't get clipped properly
! 6905: and other things may also be wrong with it. Use it at your own risk.
! 6906:
! 6907: @node xerrorbars, xyerrorbars, vector, style
! 6908: @subsubsection xerrorbars
! 6909:
! 6910: @c ?commands set style xerrorbars
! 6911: @c ?set style xerrorbars
! 6912: @c ?style xerrorbars
! 6913: @cindex xerrorbars
! 6914:
! 6915: The @ref{xerrorbars} style is only relevant to 2-d data plots. @ref{xerrorbars} is
! 6916: like @ref{dots}, except that a horizontal error bar is also drawn. At each point
! 6917: (x,y), a line is drawn from (xlow,y) to (xhigh,y) or from (x-xdelta,y) to
! 6918: (x+xdelta,y), depending on how many data columns are provided. A tic mark
! 6919: is placed at the ends of the error bar (unless @ref{bar} is used---see @ref{bar} for details).
! 6920:
! 6921: @node xyerrorbars, yerrorbars, xerrorbars, style
! 6922: @subsubsection xyerrorbars
! 6923:
! 6924: @c ?commands set style xyerrorbars
! 6925: @c ?set style xyerrorbars
! 6926: @c ?style xyerrorbars
! 6927: @cindex xyerrorbars
! 6928:
! 6929: The @ref{xyerrorbars} style is only relevant to 2-d data plots. @ref{xyerrorbars} is
! 6930: like @ref{dots}, except that horizontal and vertical error bars are also drawn.
! 6931: At each point (x,y), lines are drawn from (x,y-ydelta) to (x,y+ydelta) and
! 6932: from (x-xdelta,y) to (x+xdelta,y) or from (x,ylow) to (x,yhigh) and from
! 6933: (xlow,y) to (xhigh,y), depending upon the number of data columns provided. A
! 6934: tic mark is placed at the ends of the error bar (unless @ref{bar} is
! 6935: used---see @ref{bar} for details).
! 6936:
! 6937: If data are provided in an unsupported mixed form, the @ref{using} filter on the
! 6938: @ref{plot} command should be used to set up the appropriate form. For example,
! 6939: if the data are of the form (x,y,xdelta,ylow,yhigh), then you can use
! 6940:
! 6941: @example
! 6942: plot 'data' using 1:2:($1-$3),($1+$3),4,5 with xyerrorbars
! 6943:
! 6944: @end example
! 6945:
! 6946: @node yerrorbars, , xyerrorbars, style
! 6947: @subsubsection yerrorbars
! 6948:
! 6949: @c ?commands set style yerrorbars
! 6950: @c ?commands set style errorbars
! 6951: @c ?set style yerrorbars
! 6952: @c ?set style errorbars
! 6953: @c ?style yerrorbars
! 6954: @c ?style errorbars
! 6955: @cindex yerrorbars
! 6956:
! 6957: @cindex errorbars
! 6958:
! 6959: The @ref{yerrorbars} (or @ref{errorbars}) style is only relevant to 2-d data plots.
! 6960: @ref{yerrorbars} is like @ref{dots}, except that a vertical error bar is also drawn.
! 6961: At each point (x,y), a line is drawn from (x,y-ydelta) to (x,y+ydelta) or
! 6962: from (x,ylow) to (x,yhigh), depending on how many data columns are provided.
! 6963: A tic mark is placed at the ends of the error bar (unless @ref{bar} is
! 6964: used---see @ref{bar} for details).
! 6965: @uref{http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html,See demo. }
! 6966:
! 6967: @node surface, terminal, style, set-show
! 6968: @subsection surface
! 6969:
! 6970: @c ?commands set surface
! 6971: @c ?commands set nosurface
! 6972: @c ?commands show surface
! 6973: @c ?set surface
! 6974: @c ?set nosurface
! 6975: @c ?show surface
! 6976: @cindex surface
! 6977: @opindex surface
! 6978:
! 6979:
! 6980: @cindex nosurface
! 6981:
! 6982: The command @ref{surface} controls the display of surfaces by `splot`.
! 6983:
! 6984: Syntax:
! 6985: @example
! 6986: set surface
! 6987: set nosurface
! 6988: show surface
! 6989:
! 6990: @end example
! 6991:
! 6992: The surface is drawn with the style specifed by @ref{with}, or else the
! 6993: appropriate style, data or function.
! 6994:
! 6995: Whenever `set nosurface` is issued, `splot` will not draw points or lines
! 6996: corresponding to the function or data file points. Contours may be still be
! 6997: drawn on the surface, depending on the @ref{contour} option. `set nosurface;
! 6998: set contour base` is useful for displaying contours on the grid base. See
! 6999: also @ref{contour}.
! 7000: @c ^ <h2> Terminal Types </h2>
! 7001:
! 7002: @node terminal, tics, surface, set-show
! 7003: @subsection terminal
! 7004:
! 7005: @c ?commands set terminal
! 7006: @c ?commands show terminal
! 7007: @c ?set terminal
! 7008: @c ?set term
! 7009: @c ?show terminal
! 7010: @cindex terminal
! 7011: @opindex terminal
! 7012:
! 7013:
! 7014: @cindex term
! 7015:
! 7016: `gnuplot` supports many different graphics devices. Use @ref{terminal} to
! 7017: tell `gnuplot` what kind of output to generate. Use @ref{output} to redirect
! 7018: that output to a file or device.
! 7019:
! 7020: Syntax:
! 7021: @example
! 7022: set terminal @{<terminal-type>@}
! 7023: show terminal
! 7024:
! 7025: @end example
! 7026:
! 7027: If <terminal-type> is omitted, `gnuplot` will list the available terminal
! 7028: types. <terminal-type> may be abbreviated.
! 7029:
! 7030: If both @ref{terminal} and @ref{output} are used together, it is safest to
! 7031: give @ref{terminal} first, because some terminals set a flag which is needed
! 7032: in some operating systems.
! 7033:
! 7034: Several terminals have additional options. For example, see `dumb`,
! 7035: `iris4d`, `hpljii` or `postscript`.
! 7036:
! 7037: This document may describe drivers that are not available to you because they
! 7038: were not installed, or it may not describe all the drivers that are available
! 7039: to you, depending on its output format.
! 7040: @@c <4 -- all terminal stuff is pulled from the .trm files
! 7041:
! 7042: @menu
! 7043: * aifm::
! 7044: * cgm::
! 7045: * corel::
! 7046: * dumb::
! 7047: * dxf::
! 7048: * eepic::
! 7049: * epson-180dpi::
! 7050: * fig::
! 7051: * gif::
! 7052: * gpic::
! 7053: * hp2623a::
! 7054: * hp2648::
! 7055: * hp500c::
! 7056: * hpgl::
! 7057: * hpljii::
! 7058: * hppj::
! 7059: * imagen::
! 7060: * latex::
! 7061: * mf::
! 7062: * mif::
! 7063: * pbm::
! 7064: * png::
! 7065: * postscript::
! 7066: * pslatex_and_pstex::
! 7067: * pstricks::
! 7068: * qms::
! 7069: * regis::
! 7070: * sun::
! 7071: * tek410x::
! 7072: * table::
! 7073: * tek40::
! 7074: * texdraw::
! 7075: * tgif::
! 7076: * tkcanvas::
! 7077: * tpic::
! 7078: * x11::
! 7079: * xlib::
! 7080: @end menu
! 7081:
! 7082: @node aifm, cgm, terminal, terminal
! 7083: @subsubsection aifm
! 7084:
! 7085: @c ?commands set terminal aifm
! 7086: @c ?set terminal aifm
! 7087: @c ?set term aifm
! 7088: @c ?terminal aifm
! 7089: @c ?term aifm
! 7090: @cindex aifm
! 7091: @tmindex aifm
! 7092:
! 7093:
! 7094: Several options may be set in `aifm`---the Adobe Illustrator 3.0+ driver.
! 7095:
! 7096: Syntax:
! 7097: @example
! 7098: set terminal aifm @{<color>@} @{"<fontname>"@} @{<fontsize>@}
! 7099:
! 7100: @end example
! 7101:
! 7102: <color> is either `color` or `monochrome`; "<fontname>" is the name of a
! 7103: valid PostScript font; <fontsize> is the size of the font in PostScript
! 7104: points, before scaling by the @ref{size} command. Selecting `default` sets
! 7105: all options to their default values: `monochrome`, "Helvetica", and 14pt.
! 7106:
! 7107: Since AI does not really support multiple pages, multiple graphs will be
! 7108: drawn directly on top of one another. However, each graph will be grouped
! 7109: individually, making it easy to separate them inside AI (just pick them up
! 7110: and move them).
! 7111:
! 7112: Examples:
! 7113: @example
! 7114: set term aifm
! 7115: set term aifm 22
! 7116: set size 0.7,1.4; set term aifm color "Times-Roman" 14"
! 7117:
! 7118: @end example
! 7119:
! 7120: @node cgm, corel, aifm, terminal
! 7121: @subsubsection cgm
! 7122:
! 7123: @c ?commands set terminal cgm
! 7124: @c ?set terminal cgm
! 7125: @c ?set term cgm
! 7126: @c ?terminal cgm
! 7127: @c ?term cgm
! 7128: @cindex cgm
! 7129: @tmindex cgm
! 7130:
! 7131:
! 7132: The `cgm` terminal generates a Computer Graphics Metafile. This file format
! 7133: is a subset of the ANSI X3.122-1986 standard entitled "Computer Graphics -
! 7134: Metafile for the Storage and Transfer of Picture Description Information".
! 7135: Several options may be set in `cgm`.
! 7136:
! 7137: Syntax:
! 7138: @example
! 7139: set terminal cgm @{<mode>@} @{<color>@} @{<rotation>@} @{solid | dashed@}
! 7140: @{width <plot_width>@} @{linewidth <line_width>@}
! 7141: @{"<font>"@} @{<fontsize>@}
! 7142:
! 7143: @end example
! 7144:
! 7145: where <mode> is `landscape`, `portrait`, or `default`;
! 7146: <color> is either `color` or `monochrome`;
! 7147: <rotation> is either `rotate` or `norotate`;
! 7148: `solid` draws all curves with solid lines, overriding any dashed patterns;
! 7149: <plot_width> is the width of the page in points;
! 7150: <line_width> is the line width in points;
! 7151: <font> is the name of a font; and
! 7152: `<fontsize>` is the size of the font in points.
! 7153:
! 7154: By default, `cgm` uses rotated text for the Y axis label.
! 7155:
! 7156: The first six options can be in any order. Selecting `default` sets all
! 7157: options to their default values.
! 7158:
! 7159: Examples:
! 7160: @example
! 7161: set terminal cgm landscape color rotate dashed width 432 \\
! 7162: linewidth 1 'Arial Bold' 12 # defaults
! 7163: set terminal cgm 14 linewidth 2 14 # wider lines & larger font
! 7164: set terminal cgm portrait 'Times Roman Italic' 12
! 7165: set terminal cgm color solid # no pesky dashes!
! 7166:
! 7167: @end example
! 7168:
! 7169:
! 7170: @noindent --- FONT ---
! 7171:
! 7172: @c ?commands set terminal cgm font
! 7173: @c ?set terminal cgm font
! 7174: @c ?set term cgm font
! 7175: @c ?cgm font
! 7176: The first part of a Computer Graphics Metafile, the metafile description,
! 7177: includes a font table. In the picture body, a font is designated by an
! 7178: index into this table. By default, this terminal generates a table with
! 7179: the following fonts:
! 7180:
! 7181: @example
! 7182: Arial
! 7183: Arial Italic
! 7184: Arial Bold
! 7185: Arial Bold Italic
! 7186: Times Roman
! 7187: Times Roman Italic
! 7188: Times Roman Bold
! 7189: Times Roman Bold Italic
! 7190: Helvetica
! 7191: Roman
! 7192:
! 7193: @end example
! 7194:
! 7195: Case is not distinct, but the modifiers must appear in the above order (that
! 7196: is, not 'Arial Italic Bold'). 'Arial Bold' is the default font.
! 7197:
! 7198: You may also specify a font name which does not appear in the default font
! 7199: table. In that case, a new font table is constructed with the specified
! 7200: font as its only entry. You must ensure that the spelling, capitalization,
! 7201: and spacing of the name are appropriate for the application that will read
! 7202: the CGM file.
! 7203:
! 7204:
! 7205: @noindent --- FONTSIZE ---
! 7206:
! 7207: @c ?commands set terminal cgm fontsize
! 7208: @c ?set terminal cgm fontsize
! 7209: @c ?set term cgm fontsize
! 7210: @c ?cgm fontsize
! 7211: Fonts are scaled assuming the page is 6 inches wide. If the @ref{size} command
! 7212: is used to change the aspect ratio of the page or the CGM file is converted
! 7213: to a different width (e.g. it is imported into a document in which the
! 7214: margins are not 6 inches apart), the resulting font sizes will be different.
! 7215: To change the assumed width, use the `width` option.
! 7216:
! 7217:
! 7218: @noindent --- LINEWIDTH ---
! 7219:
! 7220: @c ?commands set terminal cgm linewidth
! 7221: @c ?set terminal cgm linewidth
! 7222: @c ?set term cgm linewidth
! 7223: @c ?cgm linewidth
! 7224: The `linewidth` option sets the width of lines in pt. The default width is
! 7225: 1 pt. Scaling is affected by the actual width of the page, as discussed
! 7226: under the `fontsize` and `width` options
! 7227:
! 7228:
! 7229: @noindent --- ROTATE ---
! 7230:
! 7231: @c ?commands set terminal cgm rotate
! 7232: @c ?set terminal cgm rotate
! 7233: @c ?set term cgm rotate
! 7234: @c ?cgm rotate
! 7235: The `norotate` option may be used to disable text rotation. For example,
! 7236: the CGM input filter for Word for Windows 6.0c can accept rotated text, but
! 7237: the DRAW editor within Word cannot. If you edit a graph (for example, to
! 7238: label a curve), all rotated text is restored to horizontal. The Y axis
! 7239: label will then extend beyond the clip boundary. With `norotate`, the Y
! 7240: axis label starts in a less attractive location, but the page can be edited
! 7241: without damage. The `rotate` option confirms the default behavior.
! 7242:
! 7243:
! 7244: @noindent --- SOLID ---
! 7245:
! 7246: @c ?set terminal cgm solid
! 7247: @c ?set term cgm solid
! 7248: @c ?cgm solid
! 7249: The `solid` option may be used to disable dashed line styles in the
! 7250: plots. This is useful when color is enabled and the dashing of the lines
! 7251: detracts from the appearance of the plot. The `dashed` option confirms the
! 7252: default behavior, which gives a different dash pattern to each curve.
! 7253:
! 7254:
! 7255: @noindent --- SIZE ---
! 7256:
! 7257: @c ?commands set terminal cgm size
! 7258: @c ?set terminal cgm size
! 7259: @c ?set term cgm size
! 7260: @c ?scgm size
! 7261: Default size of a CGM page is 32599 units wide and 23457 units high for
! 7262: landscape, or 23457 units wide by 32599 units high for portrait.
! 7263:
! 7264:
! 7265: @noindent --- WIDTH ---
! 7266:
! 7267: @c ?commands set terminal cgm width
! 7268: @c ?set terminal cgm width
! 7269: @c ?set term cgm width
! 7270: @c ?cgm width
! 7271: All distances in the CGM file are in abstract units. The application that
! 7272: reads the file determines the size of the final page. By default, the width
! 7273: of the final page is assumed to be 6 inches (15.24 cm). This distance is
! 7274: used to calculate the correct font size, and may be changed with the `width`
! 7275: option. The keyword should be followed by the width in points. (Here, a
! 7276: point is 1/72 inch, as in PostScript. This unit is known as a "big point"
! 7277: in TeX.) `gnuplot` arithmetic can be used to convert from other units, as
! 7278: follows:
! 7279: @example
! 7280: set terminal cgm width 432 # default
! 7281: set terminal cgm width 6*72 # same as above
! 7282: set terminal cgm width 10/2.54*72 # 10 cm wide
! 7283:
! 7284: @end example
! 7285:
! 7286:
! 7287: @noindent --- WINWORD6 ---
! 7288:
! 7289: @c ?commands set terminal cgm winword6
! 7290: @c ?set terminal cgm winword6
! 7291: @c ?set term cgm winword6
! 7292: @c ?cgm winword6
! 7293: The default font table was chosen to match, where possible, the default font
! 7294: assignments made by the Computer Graphics Metafile input filter for
! 7295: Microsoft Word 6.0c, although the filter makes available only 'Arial' and
! 7296: 'Times Roman' fonts and their bold and/or italic variants. Other fonts such
! 7297: as 'Helvetica' and 'Roman' are not available. If the CGM file includes a
! 7298: font table, the filter mostly ignores it. However, it changes certain font
! 7299: assignments so that they disagree with the table. As a workaround, the
! 7300: `winword6` option deletes the font table from the CGM file. In this case,
! 7301: the filter makes predictable font assignments. 'Arial Bold' is correctly
! 7302: assigned even with the font table present, which is one reason it was chosen
! 7303: as the default.
! 7304:
! 7305: `winword6` disables the color tables for a similar reason---with the color
! 7306: table included, Microsoft Word displays black for color 7.
! 7307:
! 7308: Linewidths and pointsizes may be changed with @ref{linestyle}."
! 7309:
! 7310: @node corel, dumb, cgm, terminal
! 7311: @subsubsection corel
! 7312:
! 7313: @c ?commands set terminal corel
! 7314: @c ?set terminal corel
! 7315: @c ?set term corel
! 7316: @c ?terminal corel
! 7317: @c ?term corel
! 7318: @cindex corel
! 7319: @tmindex corel
! 7320:
! 7321:
! 7322: The `corel` terminal driver supports CorelDraw.
! 7323:
! 7324: Syntax:
! 7325: @example
! 7326: set terminal corel @{ default
! 7327: | @{monochrome | color
! 7328: @{<fontname> @{"<fontsize>"
! 7329: @{<xsize> <ysize> @{<linewidth> @}@}@}@}@}
! 7330:
! 7331: @end example
! 7332:
! 7333: where the fontsize and linewidth are specified in points and the sizes in
! 7334: inches. The defaults are monochrome, "SwitzerlandLight", 22, 8.2, 10 and 1.2."
! 7335:
! 7336: @node dumb, dxf, corel, terminal
! 7337: @subsubsection dumb
! 7338:
! 7339: @c ?commands set terminal dumb
! 7340: @c ?set terminal dumb
! 7341: @c ?set term dumb
! 7342: @c ?terminal dumb
! 7343: @c ?term dumb
! 7344: @cindex dumb
! 7345: @tmindex dumb
! 7346:
! 7347:
! 7348: The `dumb` terminal driver has an optional size specification and trailing
! 7349: linefeed control.
! 7350:
! 7351: Syntax:
! 7352: @example
! 7353: set terminal dumb @{[no]feed@} @{<xsize> <ysize>@}
! 7354:
! 7355: @end example
! 7356:
! 7357: where <xsize> and <ysize> set the size of the dumb terminals. Default is
! 7358: 79 by 24. The last newline is printed only if `feed` is enabled.
! 7359:
! 7360: Examples:
! 7361: @example
! 7362: set term dumb nofeed
! 7363: set term dumb 79 49 # VGA screen---why would anyone do that?"
! 7364:
! 7365: @end example
! 7366:
! 7367: @node dxf, eepic, dumb, terminal
! 7368: @subsubsection dxf
! 7369:
! 7370: @c ?commands set terminal dxf
! 7371: @c ?set terminal dxf
! 7372: @c ?set term dxf
! 7373: @c ?terminal dxf
! 7374: @c ?term dxf
! 7375: @cindex dxf
! 7376: @tmindex dxf
! 7377:
! 7378:
! 7379: The `dxf` terminal driver creates pictures that can be imported into AutoCad
! 7380: (Release 10.x). It has no options of its own, but some features of its plots
! 7381: may be modified by other means. The default size is 120x80 AutoCad units,
! 7382: which can be changed by @ref{size}. `dxf` uses seven colors (white, red,
! 7383: yellow, green, cyan, blue and magenta), which can be changed only by
! 7384: modifying the source file. If a black-and-white plotting device is used, the
! 7385: colors are mapped to differing line thicknesses. See the description of the
! 7386: AutoCad print/plot command."
! 7387:
! 7388: @node eepic, epson-180dpi, dxf, terminal
! 7389: @subsubsection eepic
! 7390:
! 7391: @c ?commands set terminal eepic
! 7392: @c ?set terminal eepic
! 7393: @c ?set term eepic
! 7394: @c ?terminal eepic
! 7395: @c ?term eepic
! 7396: @cindex eepic
! 7397: @tmindex eepic
! 7398:
! 7399:
! 7400: The `eepic` terminal driver supports the extended LaTeX picture environment.
! 7401: It is an alternative to the `latex` driver.
! 7402:
! 7403: The output of this terminal is intended for use with the "eepic.sty" macro
! 7404: package for LaTeX. To use it, you need "eepic.sty", "epic.sty" and a
! 7405: printer driver that supports the "tpic" \\specials. If your printer driver
! 7406: doesn't support those \\specials, "eepicemu.sty" will enable you to use some
! 7407: of them.
! 7408:
! 7409: Although dotted and dashed lines are possible with `eepic` and are tempting,
! 7410: they do not work well for high-sample-rate curves, fusing the dashes all
! 7411: together into a solid line. For now, the `eepic` driver creates only solid
! 7412: lines. There is another gnuplot driver (`tpic`) that supports dashed lines,
! 7413: but it cannot be used if your DVI driver doesn't support "tpic" \\specials.
! 7414:
! 7415: All drivers for LaTeX offer a special way of controlling text positioning:
! 7416: If any text string begins with '@{', you also need to include a '@}' at the
! 7417: end of the text, and the whole text will be centered both horizontally
! 7418: and vertically by LaTeX. --- If the text string begins with '[', you need
! 7419: to continue it with: a position specification (up to two out of t,b,l,r),
! 7420: ']@{', the text itself, and finally, '@}'. The text itself may be anything
! 7421: LaTeX can typeset as an LR-box. \\rule@{@}@{@}'s may help for best positioning.
! 7422:
! 7423: The `eepic` terminal has no options.
! 7424:
! 7425: Examples:
! 7426: About label positioning:
! 7427: Use gnuplot defaults (mostly sensible, but sometimes not really best):
! 7428: @example
! 7429: set title '\\LaTeX\\ -- $ \\gamma $'
! 7430: @end example
! 7431:
! 7432: Force centering both horizontally and vertically:
! 7433: @example
! 7434: set label '@{\\LaTeX\\ -- $ \\gamma $@}' at 0,0
! 7435: @end example
! 7436:
! 7437: Specify own positioning (top here):
! 7438: @example
! 7439: set xlabel '[t]@{\\LaTeX\\ -- $ \\gamma $@}'
! 7440: @end example
! 7441:
! 7442: The other label -- account for long ticlabels:
! 7443: @example
! 7444: set ylabel '[r]@{\\LaTeX\\ -- $ \\gamma $\\rule@{7mm@}@{0pt@}'"
! 7445:
! 7446: @end example
! 7447:
! 7448: @node epson-180dpi, fig, eepic, terminal
! 7449: @subsubsection epson-180dpi
! 7450:
! 7451: @c ?commands set terminal epson-180dpi
! 7452: @c ?set terminal epson-180dpi
! 7453: @c ?set term epson-180dpi
! 7454: @c ?terminal epson-180dpi
! 7455: @c ?term epson-180dpi
! 7456: @cindex epson-180dpi
! 7457: @tmindex epson-180dpi
! 7458:
! 7459:
! 7460: @c ?commands set terminal epson-60dpi
! 7461: @c ?set terminal epson-60dpi
! 7462: @c ?set term epson-60dpi
! 7463: @c ?terminal epson-60dpi
! 7464: @c ?term epson-60dpi
! 7465: @cindex epson-60dpi
! 7466: @tmindex epson-60dpi
! 7467:
! 7468:
! 7469: @c ?commands set terminal epson-lx800
! 7470: @c ?set terminal epson-lx800
! 7471: @c ?set term epson-lx800
! 7472: @c ?terminal epson-lx800
! 7473: @c ?term epson-lx800
! 7474: @cindex epson-lx800
! 7475: @tmindex epson-lx800
! 7476:
! 7477:
! 7478: @c ?commands set terminal nec-cp6
! 7479: @c ?set terminal nec-cp6
! 7480: @c ?set term nec-cp6
! 7481: @c ?terminal nec-cp6
! 7482: @c ?term nec-cp6
! 7483: @cindex nec-cp6
! 7484: @tmindex nec-cp6
! 7485:
! 7486:
! 7487: @c ?commands set terminal okidata
! 7488: @c ?set terminal okidata
! 7489: @c ?set term okidata
! 7490: @c ?terminal okidata
! 7491: @c ?term okidata
! 7492: @cindex okidata
! 7493: @tmindex okidata
! 7494:
! 7495:
! 7496: @c ?commands set terminal starc
! 7497: @c ?set terminal starc
! 7498: @c ?set term starc
! 7499: @c ?terminal starc
! 7500: @c ?term starc
! 7501: @cindex starc
! 7502: @tmindex starc
! 7503:
! 7504:
! 7505: @c ?commands set terminal tandy-60dpi
! 7506: @c ?set terminal tandy-60dpi
! 7507: @c ?set term tandy-60dpi
! 7508: @c ?terminal tandy-60dpi
! 7509: @c ?term tandy-60dpi
! 7510: @cindex tandy-60dpi
! 7511: @tmindex tandy-60dpi
! 7512:
! 7513:
! 7514: This driver supports a family of Epson printers and derivatives.
! 7515:
! 7516: `epson-180dpi` and `epson-60dpi` are drivers for Epson LQ-style 24-pin
! 7517: printers with resolutions of 180 and 60 dots per inch, respectively.
! 7518:
! 7519: `epson-lx800` is a generic 9-pin driver appropriate for printers like the
! 7520: Epson LX-800, the Star NL-10 and NX-1000, the PROPRINTER, and so forth.
! 7521:
! 7522: `nec-cp6` is generix 24-pin driver that can be used for printers like the
! 7523: NEC CP6 and the Epson LQ-800.
! 7524:
! 7525: The `okidata` driver supports the 9-pin OKIDATA 320/321 Standard printers.
! 7526:
! 7527: The `starc` driver is for the Star Color Printer.
! 7528:
! 7529: The `tandy-60dpi` driver is for the Tandy DMP-130 series of 9-pin, 60-dpi
! 7530: printers.
! 7531:
! 7532: Only `nec-cp6` has any options.
! 7533:
! 7534: Syntax:
! 7535: @example
! 7536: set terminal nec-cp6 @{monochrome | colour | draft@}
! 7537:
! 7538: @end example
! 7539:
! 7540: which defaults to monochrome.
! 7541:
! 7542: With each of these drivers, a binary copy is required on a PC to print. Do
! 7543: not use @ref{print}---use instead `copy file /b lpt1:`."
! 7544:
! 7545: @node fig, gif, epson-180dpi, terminal
! 7546: @subsubsection fig
! 7547:
! 7548: @c ?commands set terminal fig
! 7549: @c ?set terminal fig
! 7550: @c ?set term fig
! 7551: @c ?terminal fig
! 7552: @c ?term fig
! 7553: @cindex fig
! 7554: @tmindex fig
! 7555:
! 7556:
! 7557: The `fig` terminal device generates output in the Fig graphics language.
! 7558:
! 7559: Syntax:
! 7560: @example
! 7561: set terminal fig @{monochrome | color@} @{small | big@}
! 7562: @{pointsmax <max_points>@}
! 7563: @{landscape | portrait@}
! 7564: @{metric | inches@}
! 7565: @{fontsize <fsize>@}
! 7566: @{size <xsize> <ysize>@}
! 7567: @{thickness <units>@}
! 7568: @{depth <layer>@}
! 7569:
! 7570: @end example
! 7571:
! 7572: `monochrome` and `color` determine whether the picture is black-and-white or
! 7573: `color`. `small` and `big` produce a 5x3 or 8x5 inch graph in the default
! 7574: `landscape` mode and 3x5 or 5x8 inches in `portrait` mode. <max_points>
! 7575: sets the maximum number of points per polyline. Default units for editing
! 7576: with "xfig" may be `metric` or `inches`. `fontsize` sets the size of the
! 7577: text font to <fsize> points. @ref{size} sets (overrides) the size of the drawing
! 7578: area to <xsize>*<ysize> in units of inches or centimeters depending on the
! 7579: `inches` or `metric` setting in effect. `depth` sets the default depth layer
! 7580: for all lines and text. The default depth is 10 to leave room for adding
! 7581: material with "xfig" on top of the plot.
! 7582:
! 7583: `thickness` sets the default line thickness, which is 1 if not specified.
! 7584: Overriding the thickness can be achieved by adding a multiple of 100 to the
! 7585: to the `linetype` value for a @ref{plot} command. In a similar way the `depth`
! 7586: of plot elements (with respect to the default depth) can be controlled by
! 7587: adding a multiple of 1000 to <linetype>. The depth is then <layer> +
! 7588: <linetype>/1000 and the thickness is (<linetype>%1000)/100 or, if that is
! 7589: zero, the default line thickness.
! 7590:
! 7591: Additional point-plot symbols are also available with the `fig` driver. The
! 7592: symbols can be used through `pointtype` values % 100 above 50, with different
! 7593: fill intensities controlled by <pointtype> % 5 and outlines in black (for
! 7594: <pointtype> % 10 < 5) or in the current color. Available symbols are
! 7595: @example
! 7596: 50 - 59: circles
! 7597: 60 - 69: squares
! 7598: 70 - 79: diamonds
! 7599: 80 - 89: upwards triangles
! 7600: 90 - 99: downwards triangles
! 7601: @end example
! 7602:
! 7603: The size of these symbols is linked to the font size. The depth of symbols
! 7604: is by default one less than the depth for lines to achieve nice error bars.
! 7605: If <pointtype> is above 1000, the depth is <layer> + <pointtype>/1000-1. If
! 7606: <pointtype>%1000 is above 100, the fill color is (<pointtype>%1000)/100-1.
! 7607:
! 7608: Available fill colors are (from 1 to 9): black, blue, green, cyan, red,
! 7609: magenta, yellow, white and dark blue (in monochrome mode: black for 1 to 6
! 7610: and white for 7 to 9).
! 7611:
! 7612: See @ref{with} for details of <linetype> and <pointtype>.
! 7613:
! 7614: The `big` option is a substitute for the `bfig` terminal in earlier versions,
! 7615: which is no longer supported.
! 7616:
! 7617: Examples:
! 7618: @example
! 7619: set terminal fig monochrome small pointsmax 1000 # defaults
! 7620:
! 7621: @end example
! 7622:
! 7623: @example
! 7624: plot 'file.dat' with points linetype 102 pointtype 759
! 7625: @end example
! 7626:
! 7627: would produce circles with a blue outline of width 1 and yellow fill color.
! 7628:
! 7629: @example
! 7630: plot 'file.dat' using 1:2:3 with err linetype 1 pointtype 554
! 7631: @end example
! 7632:
! 7633: would produce errorbars with black lines and circles filled red. These
! 7634: circles are one layer above the lines (at depth 9 by default).
! 7635:
! 7636: To plot the error bars on top of the circles use
! 7637: @example
! 7638: plot 'file.dat' using 1:2:3 with err linetype 1 pointtype 2554"
! 7639:
! 7640: @end example
! 7641:
! 7642: @node gif, gpic, fig, terminal
! 7643: @subsubsection gif
! 7644:
! 7645: @c ?commands set terminal gif
! 7646: @c ?set terminal gif
! 7647: @c ?set term gif
! 7648: @c ?terminal gif
! 7649: @c ?term gif
! 7650: @cindex gif
! 7651: @tmindex gif
! 7652:
! 7653:
! 7654: The `gif` terminal driver generates output in GIF format. It uses Thomas
! 7655: Boutell's gd library, which is available from http://www.boutell.com/gd/
! 7656:
! 7657: By default, the `gif` terminal driver uses a shared Web-friendy palette."
! 7658:
! 7659: Syntax:
! 7660: @example
! 7661: set terminal gif @{transparent@} @{interlace@}
! 7662: @{tiny | small | medium | large | giant@}
! 7663: @{size <x>,<y>@}
! 7664: @{<color0> <color1> <color2> ...@}
! 7665:
! 7666: @end example
! 7667:
! 7668: `transparent` instructs the driver to generate transparent GIFs. The first
! 7669: color will be the transparent one.
! 7670:
! 7671: `interlace` instructs the driver to generate interlaced GIFs.
! 7672:
! 7673: The choice of fonts is `tiny` (5x8 pixels), `small` (6x12 pixels), `medium`
! 7674: (7x13 Bold), `large` (8x16) or `giant` (9x15 pixels)
! 7675:
! 7676: The size <x,y> is given in pixels---it defaults to 640x480. The number of
! 7677: pixels can be also modified by scaling with the @ref{size} command.
! 7678:
! 7679: Each color must be of the form 'xrrggbb', where x is the literal character
! 7680: 'x' and 'rrggbb' are the red, green and blue components in hex. For example,
! 7681: 'x00ff00' is green. The background color is set first, then the border
! 7682: colors, then the X & Y axis colors, then the plotting colors. The maximum
! 7683: number of colors that can be set is 256.
! 7684:
! 7685: Examples:
! 7686: @example
! 7687: set terminal gif small size 640,480 \\
! 7688: xffffff x000000 x404040 \\
! 7689: xff0000 xffa500 x66cdaa xcdb5cd \\
! 7690: xadd8e6 x0000ff xdda0dd x9500d3 # defaults
! 7691:
! 7692: @end example
! 7693:
! 7694: which uses white for the non-transparent background, black for borders, gray
! 7695: for the axes, and red, orange, medium aquamarine, thistle 3, light blue, blue,
! 7696: plum and dark violet for eight plotting colors.
! 7697:
! 7698: @example
! 7699: set terminal gif transparent xffffff \\
! 7700: x000000 x202020 x404040 x606060 \\
! 7701: x808080 xA0A0A0 xC0C0C0 xE0E0E0 \\
! 7702: @end example
! 7703:
! 7704: which uses white for the transparent background, black for borders, dark
! 7705: gray for axes, and a gray-scale for the six plotting colors.
! 7706:
! 7707: The page size is 640x480 pixels. The `gif` driver can create either color
! 7708: or monochromatic output, but you have no control over which is produced.
! 7709:
! 7710: The current version of the `gif` driver does not support animated GIFs."
! 7711:
! 7712: @node gpic, hp2623a, gif, terminal
! 7713: @subsubsection gpic
! 7714:
! 7715: @c ?commands set terminal gpic
! 7716: @c ?set terminal gpic
! 7717: @c ?set term gpic
! 7718: @c ?terminal gpic
! 7719: @c ?term gpic
! 7720: @cindex gpic
! 7721: @tmindex gpic
! 7722:
! 7723:
! 7724: The `gpic` terminal driver generates GPIC graphs in the Free Software
! 7725: Foundations's "groff" package. The default size is 5 x 3 inches. The only
! 7726: option is the origin, which defaults to (0,0).
! 7727:
! 7728: Syntax:
! 7729: @example
! 7730: set terminal gpic @{<x> <y>@}
! 7731:
! 7732: @end example
! 7733:
! 7734: where `x` and `y` are in inches.
! 7735:
! 7736: A simple graph can be formatted using
! 7737:
! 7738: @example
! 7739: groff -p -mpic -Tps file.pic > file.ps.
! 7740:
! 7741: @end example
! 7742:
! 7743: The output from pic can be pipe-lined into eqn, so it is possible to put
! 7744: complex functions in a graph with the @ref{label} and `set @{x/y@}label`
! 7745: commands. For instance,
! 7746:
! 7747: @example
! 7748: set ylab '@@space 0 int from 0 to x alpha ( t ) roman d t@@'
! 7749:
! 7750: @end example
! 7751:
! 7752: will label the y axis with a nice integral if formatted with the command:
! 7753:
! 7754: @example
! 7755: gpic filename.pic | geqn -d@@@@ -Tps | groff -m[macro-package] -Tps
! 7756: > filename.ps
! 7757:
! 7758: @end example
! 7759:
! 7760: Figures made this way can be scaled to fit into a document. The pic language
! 7761: is easy to understand, so the graphs can be edited by hand if need be. All
! 7762: co-ordinates in the pic-file produced by `gnuplot` are given as x+gnuplotx
! 7763: and y+gnuploty. By default x and y are given the value 0. If this line is
! 7764: removed with an editor in a number of files, one can put several graphs in
! 7765: one figure like this (default size is 5.0x3.0 inches):
! 7766:
! 7767: @example
! 7768: .PS 8.0
! 7769: x=0;y=3
! 7770: copy "figa.pic"
! 7771: x=5;y=3
! 7772: copy "figb.pic"
! 7773: x=0;y=0
! 7774: copy "figc.pic"
! 7775: x=5;y=0
! 7776: copy "figd.pic"
! 7777: .PE
! 7778:
! 7779: @end example
! 7780:
! 7781: This will produce an 8-inch-wide figure with four graphs in two rows on top
! 7782: of each other.
! 7783:
! 7784: One can also achieve the same thing by the command
! 7785:
! 7786: @example
! 7787: set terminal gpic x y
! 7788:
! 7789: @end example
! 7790:
! 7791: for example, using
! 7792:
! 7793: @example
! 7794: .PS 6.0
! 7795: copy "trig.pic"
! 7796: .PE"
! 7797:
! 7798: @end example
! 7799:
! 7800: @node hp2623a, hp2648, gpic, terminal
! 7801: @subsubsection hp2623a
! 7802:
! 7803: @c ?commands set terminal hp2623a
! 7804: @c ?set terminal hp2623a
! 7805: @c ?set term hp2623a
! 7806: @c ?terminal hp2623a
! 7807: @c ?term hp2623a
! 7808: @cindex hp2623a
! 7809: @tmindex hp2623a
! 7810:
! 7811:
! 7812: The `hp2623a` terminal driver supports the Hewlett Packard HP2623A. It has
! 7813: no options."
! 7814:
! 7815: @node hp2648, hp500c, hp2623a, terminal
! 7816: @subsubsection hp2648
! 7817:
! 7818: @c ?commands set terminal hp2648
! 7819: @c ?set terminal hp2648
! 7820: @c ?set term hp2648
! 7821: @c ?terminal hp2648
! 7822: @c ?term hp2648
! 7823: @cindex hp2648
! 7824: @tmindex hp2648
! 7825:
! 7826:
! 7827: The `hp2648` terminal driver supports the Hewlett Packard HP2647 and HP2648.
! 7828: It has no options."
! 7829:
! 7830: @node hp500c, hpgl, hp2648, terminal
! 7831: @subsubsection hp500c
! 7832:
! 7833: @c ?commands set terminal hp500c
! 7834: @c ?set terminal hp500c
! 7835: @c ?set term hp500c
! 7836: @c ?terminal hp500c
! 7837: @c ?term hp500c
! 7838: @cindex hp500c
! 7839: @tmindex hp500c
! 7840:
! 7841:
! 7842: The `hp500c` terminal driver supports the Hewlett Packard HP DeskJet 500c.
! 7843: It has options for resolution and compression.
! 7844:
! 7845: Syntax:
! 7846: @example
! 7847: set terminal hp500c @{<res>@} @{<comp>@}
! 7848:
! 7849: @end example
! 7850:
! 7851: where `res` can be 75, 100, 150 or 300 dots per inch and `comp` can be "rle",
! 7852: or "tiff". Any other inputs are replaced by the defaults, which are 75 dpi
! 7853: and no compression. Rasterization at the higher resolutions may require a
! 7854: large amount of memory."
! 7855:
! 7856: @node hpgl, hpljii, hp500c, terminal
! 7857: @subsubsection hpgl
! 7858:
! 7859: @c ?commands set terminal hpgl
! 7860: @c ?set terminal hpgl
! 7861: @c ?set term hpgl
! 7862: @c ?terminal hpgl
! 7863: @c ?term hpgl
! 7864: @cindex hpgl
! 7865: @tmindex hpgl
! 7866:
! 7867:
! 7868: @c ?commands set terminal pcl5
! 7869: @c ?set terminal pcl5
! 7870: @c ?set term pcl5
! 7871: @c ?terminal pcl5
! 7872: @c ?term pcl5
! 7873: @cindex pcl5
! 7874: @tmindex pcl5
! 7875:
! 7876:
! 7877: The `hpgl` driver produces HPGL output for devices like the HP7475A plotter.
! 7878: There are two options which can be set---the number of pens and "eject", which
! 7879: tells the plotter to eject a page when done. The default is to use 6 pens
! 7880: and not to eject the page when done.
! 7881:
! 7882: The international character sets ISO-8859-1 and CP850 are recognized via
! 7883: `set encoding iso_8859_1` or `set encoding cp850` (see @ref{encoding} for
! 7884: details).
! 7885:
! 7886: Syntax:
! 7887: @example
! 7888: set terminal hpgl @{<number_of_pens>@} @{eject@}
! 7889:
! 7890: @end example
! 7891:
! 7892: The selection
! 7893:
! 7894: @example
! 7895: set terminal hpgl 8 eject
! 7896:
! 7897: @end example
! 7898:
! 7899: is equivalent to the previous `hp7550` terminal, and the selection
! 7900:
! 7901: @example
! 7902: set terminal hpgl 4
! 7903:
! 7904: @end example
! 7905:
! 7906: is equivalent to the previous `hp7580b` terminal.
! 7907:
! 7908: The `pcl5` driver supports the Hewlett-Packard Laserjet III. It actually uses
! 7909: HPGL-2, but there is a name conflict among the terminal devices. It has
! 7910: several options
! 7911:
! 7912: Syntax:
! 7913: @example
! 7914: set terminal pcl5 @{<mode>@} @{<font>@} @{<fontsize>@}
! 7915:
! 7916: @end example
! 7917:
! 7918: where <mode> is `landscape`, or `portrait`, <font> is `stick`, `univers`, or
! 7919: `cg_times`, and <fontsize> is the size in points.
! 7920:
! 7921: With `pcl5` international characters are handled by the printer; you just put
! 7922: the appropriate 8-bit character codes into the text strings. You don't need
! 7923: to bother with @ref{encoding}.
! 7924:
! 7925: HPGL graphics can be imported by many software packages."
! 7926:
! 7927: @node hpljii, hppj, hpgl, terminal
! 7928: @subsubsection hpljii
! 7929:
! 7930: @c ?commands set terminal hpljii
! 7931: @c ?set terminal hpljii
! 7932: @c ?set term hpljii
! 7933: @c ?terminal hpljii
! 7934: @c ?term hpljii
! 7935: @cindex hpljii
! 7936: @tmindex hpljii
! 7937:
! 7938:
! 7939: @c ?commands set terminal hpdj
! 7940: @c ?set terminal hpdj
! 7941: @c ?set term hpdj
! 7942: @c ?terminal hpdj
! 7943: @c ?term hpdj
! 7944: @cindex hpdj
! 7945: @tmindex hpdj
! 7946:
! 7947:
! 7948: The `hpljii` terminal driver supports the HP Laserjet Series II printer. The
! 7949: `hpdj` driver supports the HP DeskJet 500 printer. These drivers allow a
! 7950: choice of resolutions.
! 7951:
! 7952: Syntax:
! 7953: @example
! 7954: set terminal hpljii | hpdj @{<res>@}
! 7955:
! 7956: @end example
! 7957:
! 7958: where `res` may be 75, 100, 150 or 300 dots per inch; the default is 75.
! 7959: Rasterization at the higher resolutions may require a large amount of memory.
! 7960:
! 7961: The `hp500c` terminal is similar to `hpdj`; `hp500c` additionally supports
! 7962: color and compression."
! 7963:
! 7964: @node hppj, imagen, hpljii, terminal
! 7965: @subsubsection hppj
! 7966:
! 7967: @c ?commands set terminal hppj
! 7968: @c ?set terminal hppj
! 7969: @c ?set term hppj
! 7970: @c ?terminal hppj
! 7971: @c ?term hppj
! 7972: @cindex hppj
! 7973: @tmindex hppj
! 7974:
! 7975:
! 7976: The `hppj` terminal driver supports the HP PaintJet and HP3630 printers. The
! 7977: only option is the choice of font.
! 7978:
! 7979: Syntax:
! 7980: @example
! 7981: set terminal hppj @{FNT5X9 | FNT9X17 | FNT13X25@}
! 7982:
! 7983: @end example
! 7984:
! 7985: with the middle-sized font (FNT9X17) being the default."
! 7986:
! 7987: @node imagen, latex, hppj, terminal
! 7988: @subsubsection imagen
! 7989:
! 7990: @c ?commands set terminal imagen
! 7991: @c ?set terminal imagen
! 7992: @c ?set term imagen
! 7993: @c ?terminal imagen
! 7994: @c ?term imagen
! 7995: @cindex imagen
! 7996: @tmindex imagen
! 7997:
! 7998:
! 7999: The `imagen` terminal driver supports Imagen laser printers. It is capable
! 8000: of placing multiple graphs on a single page.
! 8001:
! 8002: Syntax:
! 8003: @example
! 8004: set terminal imagen @{<fontsize>@} @{portrait | landscape@}
! 8005: @{[<horiz>,<vert>]@}
! 8006:
! 8007: @end example
! 8008:
! 8009: where `fontsize` defaults to 12 points and the layout defaults to `landscape`.
! 8010: `<horiz>` and `<vert>` are the number of graphs in the horizontal and
! 8011: vertical directions; these default to unity.
! 8012:
! 8013: Example:
! 8014: @example
! 8015: set terminal imagen portrait [2,3]
! 8016:
! 8017: @end example
! 8018:
! 8019: puts six graphs on the page in three rows of two in portrait orientation."
! 8020:
! 8021: @node latex, mf, imagen, terminal
! 8022: @subsubsection latex
! 8023:
! 8024: @c ?commands set terminal emtex
! 8025: @c ?set terminal emtex
! 8026: @c ?set term emtex
! 8027: @c ?terminal emtex
! 8028: @c ?term emtex
! 8029: @cindex latex
! 8030: @tmindex latex
! 8031:
! 8032:
! 8033: @c ?commands set terminal latex
! 8034: @c ?set terminal latex
! 8035: @c ?set term latex
! 8036: @c ?terminal latex
! 8037: @c ?term latex
! 8038: @cindex emtex
! 8039: @tmindex emtex
! 8040:
! 8041:
! 8042: The `latex` and `emtex` drivers allow two options.
! 8043:
! 8044: Syntax:
! 8045: @example
! 8046: set terminal latex | emtex @{courier | roman | default@} @{<fontsize>@}
! 8047:
! 8048: @end example
! 8049:
! 8050: `fontsize` may be any size you specify. The default is for the plot to
! 8051: inherit its font setting from the embedding document.
! 8052:
! 8053: Unless your driver is capable of building fonts at any size (e.g. dvips),
! 8054: stick to the standard 10, 11 and 12 point sizes.
! 8055:
! 8056: METAFONT users beware: METAFONT does not like odd sizes.
! 8057:
! 8058: All drivers for LaTeX offer a special way of controlling text positioning:
! 8059: If any text string begins with '@{', you also need to include a '@}' at the
! 8060: end of the text, and the whole text will be centered both horizontally and
! 8061: vertically. If the text string begins with '[', you need to follow this with
! 8062: a position specification (up to two out of t,b,l,r), ']@{', the text itself,
! 8063: and finally '@}'. The text itself may be anything LaTeX can typeset as an
! 8064: LR-box. '\\rule@{@}@{@}'s may help for best positioning.
! 8065:
! 8066: Points, among other things, are drawn using the LaTeX commands "\\Diamond" and
! 8067: "\\Box". These commands no longer belong to the LaTeX2e core; they are included
! 8068: in the latexsym package, which is part of the base distribution and thus part
! 8069: of any LaTeX implementation. Please do not forget to use this package.
! 8070:
! 8071: Points are drawn with the LaTex commands \\Diamond and \\Box. These
! 8072: commands do no longer belong to the LaTeX2e core, but are included in the
! 8073: latexsym-package in the base distribution, and are hence part of all LaTeX
! 8074: implementations. Please do not forget to use this package.
! 8075:
! 8076: Examples:
! 8077: About label positioning:
! 8078: Use gnuplot defaults (mostly sensible, but sometimes not really best):
! 8079: @example
! 8080: set title '\\LaTeX\\ -- $ \\gamma $'
! 8081: @end example
! 8082:
! 8083: Force centering both horizontally and vertically:
! 8084: @example
! 8085: set label '@{\\LaTeX\\ -- $ \\gamma $@}' at 0,0
! 8086: @end example
! 8087:
! 8088: Specify own positioning (top here):
! 8089: @example
! 8090: set xlabel '[t]@{\\LaTeX\\ -- $ \\gamma $@}'
! 8091: @end example
! 8092:
! 8093: The other label -- account for long ticlabels:
! 8094: @example
! 8095: set ylabel '[r]@{\\LaTeX\\ -- $ \\gamma $\\rule@{7mm@}@{0pt@}'"
! 8096:
! 8097: @end example
! 8098:
! 8099: @node mf, mif, latex, terminal
! 8100: @subsubsection mf
! 8101:
! 8102: @c ?commands set terminal mf
! 8103: @c ?set terminal mf
! 8104: @c ?set term mf
! 8105: @c ?terminal mf
! 8106: @c ?term mf
! 8107: @cindex mf
! 8108:
! 8109: @cindex metafont
! 8110:
! 8111: The `mf` terminal driver creates a input file to the METAFONT program. Thus a
! 8112: figure may be used in the TeX document in the same way as is a character.
! 8113:
! 8114: To use a picture in a document, the METAFONT program must be run with the
! 8115: output file from `gnuplot` as input. Thus, the user needs a basic knowledge
! 8116: of the font creating process and the procedure for including a new font in a
! 8117: document. However, if the METAFONT program is set up properly at the local
! 8118: site, an unexperienced user could perform the operation without much trouble.
! 8119:
! 8120: The text support is based on a METAFONT character set. Currently the
! 8121: Computer Modern Roman font set is input, but the user is in principal free to
! 8122: chose whatever fonts he or she needs. The METAFONT source files for the
! 8123: chosen font must be available. Each character is stored in a separate
! 8124: picture variable in METAFONT. These variables may be manipulated (rotated,
! 8125: scaled etc.) when characters are needed. The drawback is the interpretation
! 8126: time in the METAFONT program. On some machines (i.e. PC) the limited amount
! 8127: of memory available may also cause problems if too many pictures are stored.
! 8128:
! 8129: The `mf` terminal has no options.
! 8130:
! 8131:
! 8132: @noindent --- METAFONT INSTRUCTIONS ---
! 8133:
! 8134: @c ?commands set terminal mf detailed
! 8135: @c ?set terminal mf detailed
! 8136: @c ?set term mf detailed
! 8137: @c ?mf detailed
! 8138: @c ?metafont detailed
! 8139:
! 8140: - Set your terminal to METAFONT:
! 8141: @example
! 8142: set terminal mf
! 8143: @end example
! 8144:
! 8145: - Select an output-file, e.g.:
! 8146: @example
! 8147: set output "myfigures.mf"
! 8148: @end example
! 8149:
! 8150: - Create your pictures. Each picture will generate a separate character. Its
! 8151: default size will be 5*3 inches. You can change the size by saying `set size
! 8152: 0.5,0.5` or whatever fraction of the default size you want to have.
! 8153:
! 8154: - Quit `gnuplot`.
! 8155:
! 8156: - Generate a TFM and GF file by running METAFONT on the output of `gnuplot`.
! 8157: Since the picture is quite large (5*3 in), you will have to use a version of
! 8158: METAFONT that has a value of at least 150000 for memmax. On Unix systems
! 8159: these are conventionally installed under the name bigmf. For the following
! 8160: assume that the command virmf stands for a big version of METAFONT. For
! 8161: example:
! 8162:
! 8163: - Invoke METAFONT:
! 8164: @example
! 8165: virmf '&plain'
! 8166: @end example
! 8167:
! 8168: - Select the output device: At the METAFONT prompt ('*') type:
! 8169: @example
! 8170: \\mode:=CanonCX; % or whatever printer you use
! 8171: @end example
! 8172:
! 8173: - Optionally select a magnification:
! 8174: @example
! 8175: mag:=1; % or whatever you wish
! 8176: @end example
! 8177:
! 8178: - Input the `gnuplot`-file:
! 8179: @example
! 8180: input myfigures.mf
! 8181: @end example
! 8182:
! 8183: On a typical Unix machine there will usually be a script called "mf" that
! 8184: executes virmf '&plain', so you probably can substitute mf for virmf &plain.
! 8185: This will generate two files: mfput.tfm and mfput.$$$gf (where $$$ indicates
! 8186: the resolution of your device). The above can be conveniently achieved by
! 8187: typing everything on the command line, e.g.:
! 8188: virmf '&plain' '\\mode:=CanonCX; mag:=1; input myfigures.mf'
! 8189: In this case the output files will be named myfigures.tfm and
! 8190: myfigures.300gf.
! 8191:
! 8192: - Generate a PK file from the GF file using gftopk:
! 8193: @example
! 8194: gftopk myfigures.300gf myfigures.300pk
! 8195: @end example
! 8196:
! 8197: The name of the output file for gftopk depends on the DVI driver you use.
! 8198: Ask your local TeX administrator about the naming conventions. Next, either
! 8199: install the TFM and PK files in the appropriate directories, or set your
! 8200: environment variables properly. Usually this involves setting TEXFONTS to
! 8201: include the current directory and doing the same thing for the environment
! 8202: variable that your DVI driver uses (no standard name here...). This step is
! 8203: necessary so that TeX will find the font metric file and your DVI driver will
! 8204: find the PK file.
! 8205:
! 8206: - To include your pictures in your document you have to tell TeX the font:
! 8207: @example
! 8208: \\font\\gnufigs=myfigures
! 8209: @end example
! 8210:
! 8211: Each picture you made is stored in a single character. The first picture is
! 8212: character 0, the second is character 1, and so on... After doing the above
! 8213: step, you can use the pictures just like any other characters. Therefore, to
! 8214: place pictures 1 and 2 centered in your document, all you have to do is:
! 8215: @example
! 8216: \\centerline@{\\gnufigs\\char0@}
! 8217: \\centerline@{\\gnufigs\\char1@}
! 8218: @end example
! 8219:
! 8220: in plain TeX. For LaTeX you can, of course, use the picture environment and
! 8221: place the picture wherever you wish by using the \\makebox and \\put macros.
! 8222:
! 8223: This conversion saves you a lot of time once you have generated the font;
! 8224: TeX handles the pictures as characters and uses minimal time to place them,
! 8225: and the documents you make change more often than the pictures do. It also
! 8226: saves a lot of TeX memory. One last advantage of using the METAFONT driver
! 8227: is that the DVI file really remains device independent, because no \\special
! 8228: commands are used as in the eepic and tpic drivers."
! 8229:
! 8230: @node mif, pbm, mf, terminal
! 8231: @subsubsection mif
! 8232:
! 8233: @c ?commands set terminal mif
! 8234: @c ?set terminal mif
! 8235: @c ?set term mif
! 8236: @c ?terminal mif
! 8237: @c ?term mif
! 8238: @cindex mif
! 8239: @tmindex mif
! 8240:
! 8241:
! 8242: The `mif` terminal driver produces Frame Maker MIF format version 3.00. It
! 8243: plots in MIF Frames with the size 15*10 cm, and plot primitives with the same
! 8244: pen will be grouped in the same MIF group. Plot primitives in a `gnuplot`
! 8245: page will be plotted in a MIF Frame, and several MIF Frames are collected in
! 8246: one large MIF Frame. The MIF font used for text is "Times".
! 8247:
! 8248: Several options may be set in the MIF 3.00 driver.
! 8249:
! 8250: Syntax:
! 8251: @example
! 8252: set terminal mif @{colour | monochrome@} @{polyline | vectors@}
! 8253: @{help | ?@}
! 8254:
! 8255: @end example
! 8256:
! 8257: `colour` plots lines with line types >= 0 in colour (MIF sep. 2--7) and
! 8258: `monochrome` plots all line types in black (MIF sep. 0).
! 8259: `polyline` plots curves as continuous curves and `vectors` plots curves as
! 8260: collections of vectors.
! 8261: @ref{help} and `?` print online help on standard error output---both print a
! 8262: short description of the usage; @ref{help} also lists the options;
! 8263:
! 8264: Examples:
! 8265: @example
! 8266: set term mif colour polylines # defaults
! 8267: set term mif # defaults
! 8268: set term mif vectors
! 8269: set term mif help"
! 8270:
! 8271: @end example
! 8272:
! 8273: @node pbm, png, mif, terminal
! 8274: @subsubsection pbm
! 8275:
! 8276: @c ?commands set terminal pbm
! 8277: @c ?set terminal pbm
! 8278: @c ?set term pbm
! 8279: @c ?terminal pbm
! 8280: @c ?term pbm
! 8281: @cindex pbm
! 8282: @tmindex pbm
! 8283:
! 8284:
! 8285: Several options may be set in the `pbm` terminal---the driver for PBMplus.
! 8286:
! 8287: Syntax:
! 8288: @example
! 8289: set terminal pbm @{<fontsize>@} @{<mode>@}
! 8290:
! 8291: @end example
! 8292:
! 8293: where <fontsize> is `small`, `medium`, or `large` and <mode> is `monochrome`,
! 8294: `gray` or `color`. The default plot size is 640 pixels wide and 480 pixels
! 8295: high; this may be changed by @ref{size}.
! 8296:
! 8297: The output of the `pbm` driver depends upon <mode>: `monochrome` produces a
! 8298: portable bitmap (one bit per pixel), `gray` a portable graymap (three bits
! 8299: per pixel) and `color` a portable pixmap (color, four bits per pixel).
! 8300:
! 8301: The output of this driver can be used with Jef Poskanzer's excellent PBMPLUS
! 8302: package, which provides programs to convert the above PBMPLUS formats to GIF,
! 8303: TIFF, MacPaint, Macintosh PICT, PCX, X11 bitmap and many others. PBMPLUS may
! 8304: be obtained from ftp.x.org. The relevant files have names that begin with
! 8305: "netpbm-1mar1994.p1"; they reside in /contrib/utilities. The package can
! 8306: probably also be obtained from one of the many sites that mirrors ftp.x.org.
! 8307:
! 8308: Examples:
! 8309: @example
! 8310: set terminal pbm small monochrome # defaults
! 8311: set size 2,2; set terminal pbm color medium"
! 8312:
! 8313: @end example
! 8314:
! 8315: @node png, postscript, pbm, terminal
! 8316: @subsubsection png
! 8317:
! 8318: @c ?commands set terminal png
! 8319: @c ?set terminal png
! 8320: @c ?set term png
! 8321: @c ?terminal png
! 8322: @c ?term png
! 8323: @cindex png
! 8324: @tmindex png
! 8325:
! 8326:
! 8327: The `png` terminal driver supports Portable Network Graphics. To compile it,
! 8328: you will need the third-party libraries "libpng" and "zlib"; both are
! 8329: available at ftp://ftp.uu.net/graphics/png. `png` has two options.
! 8330:
! 8331: Syntax:
! 8332: @example
! 8333: set terminal png @{small | medium | large@}
! 8334: @{monochrome | gray | color@}
! 8335:
! 8336: @end example
! 8337:
! 8338: The defaults are small (fontsize) and monochrome. Default size of the output
! 8339: is 640*480 pixel."
! 8340:
! 8341: @node postscript, pslatex_and_pstex, png, terminal
! 8342: @subsubsection postscript
! 8343:
! 8344: @c ?commands set terminal postscript
! 8345: @c ?set terminal postscript
! 8346: @c ?set term postscript
! 8347: @c ?terminal postscript
! 8348: @c ?term postscript
! 8349: @cindex postscript
! 8350: @tmindex postscript
! 8351:
! 8352:
! 8353: Several options may be set in the `postscript` driver.
! 8354:
! 8355: Syntax:
! 8356: @example
! 8357: set terminal postscript @{<mode>@} @{enhanced | noenhanced@}
! 8358: @{color | monochrome@} @{solid | dashed@}
! 8359: @{<duplexing>@}
! 8360: @{"<fontname>"@} @{<fontsize>@}
! 8361:
! 8362: @end example
! 8363:
! 8364: where <mode> is `landscape`, `portrait`, `eps` or `default`;
! 8365: `solid` draws all plots with solid lines, overriding any dashed patterns;
! 8366: <duplexing> is `defaultplex`, `simplex` or `duplex` ("duplexing" in
! 8367: PostScript is the ability of the printer to print on both sides of the same
! 8368: page---don't set this if your printer can't do it);
! 8369: `enhanced` activates the "enhanced PostScript" features (subscripts,
! 8370: superscripts and mixed fonts);
! 8371: `"<fontname>"` is the name of a valid PostScript font; and `<fontsize>` is
! 8372: the size of the font in PostScript points.
! 8373:
! 8374: `default` mode sets all options to their defaults: `landscape`, `monochrome`,
! 8375: `dashed`, `defaultplex`, `noenhanced`, "Helvetica" and 14pt.
! 8376: @example
! 8377: Default size of a PostScript plot is 10 inches wide and 7 inches high.
! 8378:
! 8379: @end example
! 8380:
! 8381: `eps` mode generates EPS (Encapsulated PostScript) output, which is just
! 8382: regular PostScript with some additional lines that allow the file to be
! 8383: imported into a variety of other applications. (The added lines are
! 8384: PostScript comment lines, so the file may still be printed by itself.) To
! 8385: get EPS output, use the `eps` mode and make only one plot per file. In `eps`
! 8386: mode the whole plot, including the fonts, is reduced to half of the default
! 8387: size.
! 8388:
! 8389: Examples:
! 8390: @example
! 8391: set terminal postscript default # old postscript
! 8392: set terminal postscript enhanced # old enhpost
! 8393: set terminal postscript landscape 22 # old psbig
! 8394: set terminal postscript eps 14 # old epsf1
! 8395: set terminal postscript eps 22 # old epsf2
! 8396: set size 0.7,1.4; set term post portrait color "Times-Roman" 14
! 8397:
! 8398: @end example
! 8399:
! 8400: Linewidths and pointsizes may be changed with @ref{linestyle}.
! 8401:
! 8402: The `postscript` driver supports about 70 distinct pointtypes, selectable
! 8403: through the `pointtype` option on @ref{plot} and @ref{linestyle}.
! 8404:
! 8405: Several possibly useful files about `gnuplot`'s PostScript are included
! 8406: in the /docs/ps subdirectory of the `gnuplot` distribution and at the
! 8407: distribution sites. These are "ps_symbols.gpi" (a `gnuplot` command file
! 8408: that, when executed, creates the file "ps_symbols.ps" which shows all the
! 8409: symbols available through the `postscript` terminal), "ps_guide.ps" (a
! 8410: PostScript file that contains a summary of the enhanced syntax and a page
! 8411: showing what the octal codes produce with text and symbol fonts) and
! 8412: "ps_file.doc" (a text file that contains a discussion of the organization
! 8413: of a PostScript file written by `gnuplot`).
! 8414:
! 8415: A PostScript file is editable, so once `gnuplot` has created one, you are
! 8416: free to modify it to your heart's desire. See the "editing postscript"
! 8417: section for some hints.
! 8418:
! 8419:
! 8420: @noindent --- ENHANCED POSTSCRIPT ---
! 8421:
! 8422: @c ?commands set terminal postscript enhanced
! 8423: @c ?set terminal postscript enhanced
! 8424: @c ?set term postscript enhanced
! 8425: @c ?terminal postscript enhanced
! 8426: @c ?term postscript enhanced
! 8427: @cindex enhanced_postscript
! 8428:
! 8429:
! 8430: @example
! 8431: Control Examples Explanation
! 8432: ^ a^x superscript
! 8433: _ a_x subscript
! 8434: @@ @@x or a@@^b_c phantom box (occupies no width)
! 8435: & &@{space@} inserts space of specified length
! 8436:
! 8437: @end example
! 8438:
! 8439:
! 8440: Braces can be used to place multiple-character text where a single character
! 8441: is expected (e.g., 2^@{10@}). To change the font and/or size, use the full
! 8442: form: @{/[fontname][=fontsize | *fontscale] text@}. Thus @{/Symbol=20 G@} is a
! 8443: 20-point GAMMA) and @{/*0.75 K@} is a K at three-quarters of whatever fontsize
! 8444: is currently in effect. (The '/' character MUST be the first character after
! 8445: the '@{'.)
! 8446:
! 8447: If the encoding vector has been changed by @ref{encoding}, the default
! 8448: encoding vector can be used instead by following the slash with a dash. This
! 8449: is unnecessary if you use the Symbol font, however---since /Symbol uses its
! 8450: own encoding vector, `gnuplot` will not apply any other encoding vector to
! 8451: it.
! 8452:
! 8453: The phantom box is useful for a@@^b_c to align superscripts and subscripts
! 8454: but does not work well for overwriting an accent on a letter. (To do the
! 8455: latter, it is much better to use `set encoding iso_8859_1` to change to the
! 8456: ISO Latin-1 encoding vector, which contains a large variety of letters with
! 8457: accents or other diacritical marks.) Since the box is non-spacing, it is
! 8458: sensible to put the shorter of the subscript or superscript in the box (that
! 8459: is, after the @@).
! 8460:
! 8461: Space equal in length to a string can be inserted using the '&' character.
! 8462: Thus
! 8463: @example
! 8464: 'abc&@{def@}ghi'
! 8465: @end example
! 8466:
! 8467: would produce
! 8468: @example
! 8469: 'abc ghi'.
! 8470:
! 8471: @end example
! 8472:
! 8473: You can access special symbols numerically by specifying \\character-code (in
! 8474: octal), e.g., @{/Symbol \\245@} is the symbol for infinity.
! 8475:
! 8476: You can escape control characters using \\, e.g., \\\\, \\@{, and so on.
! 8477:
! 8478: But be aware that strings in double-quotes are parsed differently than those
! 8479: enclosed in single-quotes. The major difference is that backslashes may need
! 8480: to be doubled when in double-quoted strings.
! 8481:
! 8482: Examples (these are hard to describe in words---try them!):
! 8483: @example
! 8484: set xlabel 'Time (10^6 @{/Symbol m@}s)'
! 8485: set title '@{/Symbol=18 \\362@@_@{/=9.6 0@}^@{/=12 x@}@} \\
! 8486: @{/Helvetica e^@{-@{/Symbol m@}^2/2@} d@}@{/Symbol m@}'
! 8487:
! 8488: @end example
! 8489:
! 8490: The file "ps_guide.ps" in the /docs/ps subdirectory of the `gnuplot` source
! 8491: distribution contains more examples of the enhanced syntax.
! 8492:
! 8493:
! 8494: @noindent --- EDITING POSTSCRIPT ---
! 8495:
! 8496: @c ?commands set terminal postscript editing
! 8497: @c ?set terminal postscript editing
! 8498: @c ?set term postscript editing
! 8499: @c ?terminal postscript editing
! 8500: @c ?term postscript editing
! 8501: @cindex editing_postscript
! 8502:
! 8503: The PostScript language is a very complex language---far too complex to
! 8504: describe in any detail in this document. Nevertheless there are some things
! 8505: in a PostScript file written by `gnuplot` that can be changed without risk of
! 8506: introducing fatal errors into the file.
! 8507:
! 8508: For example, the PostScript statement "/Color true def" (written into the
! 8509: file in response to the command `set terminal postscript color`), may be
! 8510: altered in an obvious way to generate a black-and-white version of a plot.
! 8511: Similarly line colors, text colors, line weights and symbol sizes can also be
! 8512: altered in straight-forward ways. Text (titles and labels) can be edited to
! 8513: correct misspellings or to change fonts. Anything can be repositioned, and
! 8514: of course anything can be added or deleted, but modifications such as these
! 8515: may require deeper knowledge of the PostScript language.
! 8516:
! 8517: The organization of a PostScript file written by `gnuplot` is discussed in
! 8518: the text file "ps_file.doc" in the /docs/ps subdirectory."
! 8519:
! 8520: @node pslatex_and_pstex, pstricks, postscript, terminal
! 8521: @subsubsection pslatex and pstex
! 8522:
! 8523: @c ?commands set terminal pslatex
! 8524: @c ?set terminal pslatex
! 8525: @c ?set term pslatex
! 8526: @c ?terminal pslatex
! 8527: @c ?term pslatex
! 8528: @cindex pslatex
! 8529: @tmindex pslatex
! 8530:
! 8531:
! 8532: @c ?commands set terminal pstex
! 8533: @c ?set terminal pstex
! 8534: @c ?set term pstex
! 8535: @c ?terminal pstex
! 8536: @c ?term pstex
! 8537: @cindex pstex
! 8538: @tmindex pstex
! 8539:
! 8540:
! 8541: The `pslatex` and `pstex` drivers generate output for further processing by
! 8542: LaTeX and TeX, respectively. Figures generated by `pstex` can be included
! 8543: in any plain-based format (including LaTeX).
! 8544:
! 8545: Syntax:
! 8546: @example
! 8547: set terminal pslatex | |pstex @{<color>@} @{<dashed>@} @{<rotate>@}
! 8548: @{auxfile@} @{<font_size>@}
! 8549:
! 8550: @end example
! 8551:
! 8552: <color> is either `color` or `monochrome`. <rotate> is either `rotate` or
! 8553: `norotate` and determines if the y-axis label is rotated. <font_size> is
! 8554: used to scale the font from its usual size.
! 8555:
! 8556: If `auxfile` is specified, it directs the driver to put the PostScript
! 8557: commands into an auxiliary file instead of directly into the LaTeX file.
! 8558: This is useful if your pictures are large enough that dvips cannot handle
! 8559: them. The name of the auxiliary PostScript file is derived from the name of
! 8560: the TeX file given on the @ref{output} command; it is determined by replacing
! 8561: the trailing `.tex` (actually just the final extent in the file name) with
! 8562: `.ps` in the output file name, or, if the TeX file has no extension, `.ps`
! 8563: is appended. Remember to close the file before leaving `gnuplot`.
! 8564:
! 8565: All drivers for LaTeX offer a special way of controlling text positioning:
! 8566: If any text string begins with '@{', you also need to include a '@}' at the
! 8567: end of the text, and the whole text will be centered both horizontally
! 8568: and vertically by LaTeX. --- If the text string begins with '[', you need
! 8569: to continue it with: a position specification (up to two out of t,b,l,r),
! 8570: ']@{', the text itself, and finally, '@}'. The text itself may be anything
! 8571: LaTeX can typeset as an LR-box. \\rule@{@}@{@}'s may help for best positioning.
! 8572:
! 8573: Examples:
! 8574: @example
! 8575: set term pslatex monochrome dashed rotate # set to defaults
! 8576: @end example
! 8577:
! 8578: To write the PostScript commands into the file "foo.ps":
! 8579: @example
! 8580: set term pslatex auxfile
! 8581: set output "foo.tex"; plot ...: set output
! 8582: @end example
! 8583:
! 8584: About label positioning:
! 8585: Use gnuplot defaults (mostly sensible, but sometimes not really best):
! 8586: @example
! 8587: set title '\\LaTeX\\ -- $ \\gamma $'
! 8588: @end example
! 8589:
! 8590: Force centering both horizontally and vertically:
! 8591: @example
! 8592: set label '@{\\LaTeX\\ -- $ \\gamma $@}' at 0,0
! 8593: @end example
! 8594:
! 8595: Specify own positioning (top here):
! 8596: @example
! 8597: set xlabel '[t]@{\\LaTeX\\ -- $ \\gamma $@}'
! 8598: @end example
! 8599:
! 8600: The other label -- account for long ticlabels:
! 8601: @example
! 8602: set ylabel '[r]@{\\LaTeX\\ -- $ \\gamma $\\rule@{7mm@}@{0pt@}'
! 8603:
! 8604: @end example
! 8605:
! 8606: Linewidths and pointsizes may be changed with @ref{linestyle}."
! 8607:
! 8608: @node pstricks, qms, pslatex_and_pstex, terminal
! 8609: @subsubsection pstricks
! 8610:
! 8611: @c ?commands set terminal pstricks
! 8612: @c ?set terminal pstricks
! 8613: @c ?set term pstricks
! 8614: @c ?terminal pstricks
! 8615: @c ?term pstricks
! 8616: @cindex pstricks
! 8617: @tmindex pstricks
! 8618:
! 8619:
! 8620: The `pstricks` driver is intended for use with the "pstricks.sty" macro
! 8621: package for LaTeX. It is an alternative to the `eepic` and `latex` drivers.
! 8622: You need "pstricks.sty", and, of course, a printer that understands
! 8623: PostScript, or a converter such as Ghostscript.
! 8624:
! 8625: PSTricks is available via anonymous ftp from the /pub directory at
! 8626: Princeton.EDU. This driver definitely does not come close to using the full
! 8627: capability of the PSTricks package.
! 8628:
! 8629: Syntax:
! 8630: @example
! 8631: set terminal pstricks @{hacktext | nohacktext@} @{unit | nounit@}
! 8632:
! 8633: @end example
! 8634:
! 8635: The first option invokes an ugly hack that gives nicer numbers; the second
! 8636: has to do with plot scaling. The defaults are `hacktext` and `nounit`."
! 8637:
! 8638: @node qms, regis, pstricks, terminal
! 8639: @subsubsection qms
! 8640:
! 8641: @c ?commands set terminal qms
! 8642: @c ?set terminal qms
! 8643: @c ?set term qms
! 8644: @c ?terminal qms
! 8645: @c ?term qms
! 8646: @cindex qms
! 8647: @tmindex qms
! 8648:
! 8649:
! 8650: The `qms` terminal driver supports the QMS/QUIC Laser printer, the Talaris
! 8651: 1200 and others. It has no options."
! 8652:
! 8653: @node regis, sun, qms, terminal
! 8654: @subsubsection regis
! 8655:
! 8656: @c ?commands set terminal regis
! 8657: @c ?set terminal regis
! 8658: @c ?set term regis
! 8659: @c ?terminal regis
! 8660: @c ?term regis
! 8661: @cindex regis
! 8662: @tmindex regis
! 8663:
! 8664:
! 8665: The `regis` terminal device generates output in the REGIS graphics language.
! 8666: It has the option of using 4 (the default) or 16 colors.
! 8667:
! 8668: Syntax:
! 8669: @example
! 8670: set terminal regis @{4 | 16@}"
! 8671:
! 8672: @end example
! 8673:
! 8674: @node sun, tek410x, regis, terminal
! 8675: @subsubsection sun
! 8676:
! 8677: @c ?commands set terminal sun
! 8678: @c ?set terminal sun
! 8679: @c ?set term sun
! 8680: @c ?terminal sun
! 8681: @c ?term sun
! 8682: @cindex sun
! 8683: @tmindex sun
! 8684:
! 8685:
! 8686: The `sun` terminal driver supports the SunView window system. It has no
! 8687: options."
! 8688:
! 8689: @node tek410x, table, sun, terminal
! 8690: @subsubsection tek410x
! 8691:
! 8692: @c ?commands set terminal tek410x
! 8693: @c ?set terminal tek410x
! 8694: @c ?set term tek410x
! 8695: @c ?terminal tek410x
! 8696: @c ?term tek410x
! 8697: @cindex tek410x
! 8698: @tmindex tek410x
! 8699:
! 8700:
! 8701: The `tek410x` terminal driver supports the 410x and 420x family of Tektronix
! 8702: terminals. It has no options."
! 8703:
! 8704: @node table, tek40, tek410x, terminal
! 8705: @subsubsection table
! 8706:
! 8707: @c ?commands set terminal table
! 8708: @c ?set terminal table
! 8709: @c ?set term table
! 8710: @c ?terminal table
! 8711: @c ?term table
! 8712: @cindex table
! 8713: @tmindex table
! 8714:
! 8715:
! 8716: Instead of producing a graph, the `table` terminal prints out the points on
! 8717: which a graph would be based, i.e., the results of processing the @ref{plot} or
! 8718: `splot` command, in a multicolumn ASCII table of X Y @{Z@} R values. The
! 8719: character R takes on one of three values: "i" if the point is in the active
! 8720: range, "o" if it is out-of-range, or "u" if it is undefined. The data
! 8721: format is determined by the format of the axis labels (see `set format`).
! 8722:
! 8723: For those times when you want the numbers, you can display them on the
! 8724: screen or save them to a file. This can be useful if you want to generate
! 8725: contours and then save them for further use, perhaps for plotting with
! 8726: @ref{plot}; see @ref{contour} for an example. The same method can be used to
! 8727: save interpolated data (see @ref{samples} and @ref{dgrid3d})."
! 8728:
! 8729: @node tek40, texdraw, table, terminal
! 8730: @subsubsection tek40
! 8731:
! 8732: @c ?commands set terminal tek40xx
! 8733: @c ?set terminal tek40xx
! 8734: @c ?set term tek40xx
! 8735: @c ?terminal tek40xx
! 8736: @c ?terminal tek40xx
! 8737: @cindex tek40
! 8738: @tmindex tek40
! 8739:
! 8740:
! 8741: @c ?commands set terminal vttek
! 8742: @c ?set terminal vttek
! 8743: @c ?set term vttek
! 8744: @c ?terminal vttek
! 8745: @c ?term vttek
! 8746: @cindex vttek
! 8747: @tmindex vttek
! 8748:
! 8749:
! 8750: @c ?commands set terminal kc-tek40xx
! 8751: @c ?set terminal kc-tek40xx
! 8752: @c ?set term kc-tek40xx
! 8753: @c ?terminal kc-tek40xx
! 8754: @c ?term kc-tek40xx
! 8755: @cindex kc-tek40xx
! 8756: @tmindex kc-tek40xx
! 8757:
! 8758:
! 8759: @c ?commands set terminal km-tek40xx
! 8760: @c ?set terminal km-tek40xx
! 8761: @c ?set term km-tek40xx
! 8762: @c ?terminal km-tek40xx
! 8763: @c ?term km-tek40xx
! 8764: @cindex km-tek40xx
! 8765: @tmindex km-tek40xx
! 8766:
! 8767:
! 8768: @c ?commands set terminal selanar
! 8769: @c ?set terminal selanar
! 8770: @c ?set term selanar
! 8771: @c ?terminal selanar
! 8772: @c ?term selanar
! 8773: @cindex selanar
! 8774: @tmindex selanar
! 8775:
! 8776:
! 8777: @c ?commands set terminal bitgraph
! 8778: @c ?set terminal bitgraph
! 8779: @c ?set term bitgraph
! 8780: @c ?terminal bitgraph
! 8781: @c ?term bitgraph
! 8782: @cindex bitgraph
! 8783: @tmindex bitgraph
! 8784:
! 8785:
! 8786: This family of terminal drivers supports a variety of VT-like terminals.
! 8787: `tek40xx` supports Tektronix 4010 and others as well as most TEK emulators;
! 8788: `vttek` supports VT-like tek40xx terminal emulators; `kc-tek40xx` supports
! 8789: MS-DOS Kermit Tek4010 terminal emulators in color: `km-tek40xx` supports them
! 8790: in monochrome; `selanar` supports Selanar graphics; and `bitgraph` supports
! 8791: BBN Bitgraph terminals. None have any options."
! 8792:
! 8793: @node texdraw, tgif, tek40, terminal
! 8794: @subsubsection texdraw
! 8795:
! 8796: @c ?commands set terminal texdraw
! 8797: @c ?set terminal texdraw
! 8798: @c ?set term texdraw
! 8799: @c ?terminal texdraw
! 8800: @c ?term texdraw
! 8801: @cindex texdraw
! 8802: @tmindex texdraw
! 8803:
! 8804:
! 8805: The `texdraw` terminal driver supports the LaTeX texdraw environment. It is
! 8806: intended for use with "texdraw.sty" and "texdraw.tex" in the texdraw package.
! 8807:
! 8808: It has no options."
! 8809:
! 8810: @node tgif, tkcanvas, texdraw, terminal
! 8811: @subsubsection tgif
! 8812:
! 8813: @c ?commands set terminal tgif
! 8814: @c ?set terminal tgif
! 8815: @c ?set term tgif
! 8816: @c ?terminal tgif
! 8817: @c ?term tgif
! 8818: @cindex tgif
! 8819: @tmindex tgif
! 8820:
! 8821:
! 8822: Tgif is an X11-based drawing tool---it has nothing to do with GIF.
! 8823:
! 8824: The `tgif` driver supports different pointsizes (with @ref{pointsize}),
! 8825: different label fonts and font sizes (e.g. `set label "Hallo" at x,y font
! 8826: "Helvetica,34"`) and multiple graphs on the page. The proportions of the
! 8827: axes are not changed.
! 8828:
! 8829: Syntax:
! 8830: @example
! 8831: set terminal tgif @{portrait | landscape@} @{<[x,y]>@}
! 8832: @{solid | dashed@}
! 8833: @{"<fontname>"@} @{<fontsize>@}
! 8834:
! 8835: @end example
! 8836:
! 8837: where <[x,y]> specifies the number of graphs in the x and y directions on the
! 8838: page, "<fontname>" is the name of a valid PostScript font, and <fontsize>
! 8839: specifies the size of the PostScript font. Defaults are `portrait`, `[1,1]`,
! 8840: `dashed`, `"Helvetica"`, and `18`.
! 8841:
! 8842: The `solid` option is usually prefered if lines are colored, as they often
! 8843: are in the editor. Hardcopy will be black-and-white, so `dashed` should be
! 8844: chosen for that.
! 8845:
! 8846: Multiplot is implemented in two different ways.
! 8847:
! 8848: The first multiplot implementation is the standard gnuplot multiplot feature:
! 8849:
! 8850: @example
! 8851: set terminal tgif
! 8852: set output "file.obj"
! 8853: set multiplot
! 8854: set origin x01,y01
! 8855: set size xs,ys
! 8856: plot ...
! 8857: ...
! 8858: set origin x02,y02
! 8859: plot ...
! 8860: set nomultiplot
! 8861:
! 8862: @end example
! 8863:
! 8864: See @ref{multiplot} for further information.
! 8865:
! 8866: The second version is the [x,y] option for the driver itself. The advantage
! 8867: of this implementation is that everything is scaled and placed automatically
! 8868: without the need for setting origins and sizes; the graphs keep their natural
! 8869: x/y proportions of 3/2 (or whatever is fixed by @ref{size}).
! 8870:
! 8871: If both multiplot methods are selected, the standard method is chosen and a
! 8872: warning message is given.
! 8873:
! 8874: Examples of single plots (or standard multiplot):
! 8875: @example
! 8876: set terminal tgif # defaults
! 8877: set terminal tgif "Times-Roman" 24
! 8878: set terminal tgif landscape
! 8879: set terminal tgif landscape solid
! 8880:
! 8881: @end example
! 8882:
! 8883: Examples using the built-in multiplot mechanism:
! 8884: @example
! 8885: set terminal tgif portrait [2,4] # portrait; 2 plots in the x-
! 8886: # and 4 in the y-direction
! 8887: set terminal tgif [1,2] # portrait; 1 plot in the x-
! 8888: # and 2 in the y-direction
! 8889: set terminal tgif landscape [3,3] # landscape; 3 plots in both
! 8890: # directions"
! 8891:
! 8892: @end example
! 8893:
! 8894: @node tkcanvas, tpic, tgif, terminal
! 8895: @subsubsection tkcanvas
! 8896:
! 8897: @c ?commands set terminal tkcanvas
! 8898: @c ?set terminal tkcanvas
! 8899: @c ?set term tkcanvas
! 8900: @c ?terminal tkcanvas
! 8901: @c ?term tkcanvas
! 8902: @cindex tkcanvas
! 8903: @tmindex tkcanvas
! 8904:
! 8905:
! 8906: This terminal driver generates Tk canvas widget commands based on Tcl/Tk
! 8907: (default) or Perl. To use it, rebuild `gnuplot` (after uncommenting or
! 8908: inserting the appropriate line in "term.h"), then
! 8909:
! 8910: @example
! 8911: gnuplot> set term tkcanvas @{perltk@} @{interactive@}
! 8912: gnuplot> set output 'plot.file'
! 8913:
! 8914: @end example
! 8915:
! 8916: After invoking "wish", execute the following sequence of Tcl/Tk commands:
! 8917:
! 8918: @example
! 8919: % source plot.file
! 8920: % canvas .c
! 8921: % pack .c
! 8922: % gnuplot .c
! 8923:
! 8924: @end example
! 8925:
! 8926: Or, for Perl/Tk use a program like this:
! 8927:
! 8928: @example
! 8929: use Tk;
! 8930: my $top = MainWindow->new;
! 8931: my $c = $top->Canvas;
! 8932: $c->pack();
! 8933: do "plot.pl";
! 8934: gnuplot->($c);
! 8935: MainLoop;
! 8936:
! 8937: @end example
! 8938:
! 8939: The code generated by `gnuplot` creates a procedure called "gnuplot"
! 8940: that takes the name of a canvas as its argument. When the procedure is
! 8941: called, it clears the canvas, finds the size of the canvas and draws the plot
! 8942: in it, scaled to fit.
! 8943:
! 8944: For 2-dimensional plotting (@ref{plot}) two additional procedures are defined:
! 8945: "gnuplot_plotarea" will return a list containing the borders of the plotting
! 8946: area "xleft, xright, ytop, ybot" in canvas screen coordinates, while the ranges
! 8947: of the two axes "x1min, x1max, y1min, y1max, x2min, x2max, y2min, y2max" in plot
! 8948: coordinates can be obtained calling "gnuplot_axisranges".
! 8949: If the "interactive" option is specified, mouse clicking on a line segment
! 8950: will print the coordinates of its midpoint to stdout. Advanced actions
! 8951: can happen instead if the user supplies a procedure named
! 8952: "user_gnuplot_coordinates", which takes the following arguments:
! 8953: "win id x1s y1s x2s y2s x1e y1e x2e y2e x1m y1m x2m y2m",
! 8954: the name of the canvas and the id of the line segment followed by the
! 8955: coordinates of its start and end point in the two possible axis ranges; the
! 8956: coordinates of the midpoint are only filled for logarithmic axes.
! 8957:
! 8958: The current version of `tkcanvas` supports neither @ref{multiplot} nor @ref{replot}."
! 8959:
! 8960: @node tpic, x11, tkcanvas, terminal
! 8961: @subsubsection tpic
! 8962:
! 8963: @c ?commands set terminal tpic
! 8964: @c ?set terminal tpic
! 8965: @c ?set term tpic
! 8966: @c ?terminal tpic
! 8967: @c ?term tpic
! 8968: @cindex tpic
! 8969: @tmindex tpic
! 8970:
! 8971:
! 8972: The `tpic` terminal driver supports the LaTeX picture environment with tpic
! 8973: \\specials. It is an alternative to the `latex` and `eepic` terminal drivers.
! 8974: Options are the point size, line width, and dot-dash interval.
! 8975:
! 8976: Syntax:
! 8977: @example
! 8978: set terminal tpic <pointsize> <linewidth> <interval>
! 8979:
! 8980: @end example
! 8981:
! 8982: where @ref{pointsize} and `linewidth` are integers in milli-inches and `interval`
! 8983: is a float in inches. If a non-positive value is specified, the default is
! 8984: chosen: pointsize = 40, linewidth = 6, interval = 0.1.
! 8985:
! 8986: All drivers for LaTeX offer a special way of controlling text positioning:
! 8987: If any text string begins with '@{', you also need to include a '@}' at the
! 8988: end of the text, and the whole text will be centered both horizontally
! 8989: and vertically by LaTeX. --- If the text string begins with '[', you need
! 8990: to continue it with: a position specification (up to two out of t,b,l,r),
! 8991: ']@{', the text itself, and finally, '@}'. The text itself may be anything
! 8992: LaTeX can typeset as an LR-box. \\rule@{@}@{@}'s may help for best positioning.
! 8993:
! 8994: Examples:
! 8995: About label positioning:
! 8996: Use gnuplot defaults (mostly sensible, but sometimes not really best):
! 8997: @example
! 8998: set title '\\LaTeX\\ -- $ \\gamma $'
! 8999: @end example
! 9000:
! 9001: Force centering both horizontally and vertically:
! 9002: @example
! 9003: set label '@{\\LaTeX\\ -- $ \\gamma $@}' at 0,0
! 9004: @end example
! 9005:
! 9006: Specify own positioning (top here):
! 9007: @example
! 9008: set xlabel '[t]@{\\LaTeX\\ -- $ \\gamma $@}'
! 9009: @end example
! 9010:
! 9011: The other label -- account for long ticlabels:
! 9012: @example
! 9013: set ylabel '[r]@{\\LaTeX\\ -- $ \\gamma $\\rule@{7mm@}@{0pt@}'"
! 9014:
! 9015: @end example
! 9016:
! 9017: @node x11, xlib, tpic, terminal
! 9018: @subsubsection x11
! 9019:
! 9020: @c ?commands set terminal x11
! 9021: @c ?set terminal x11
! 9022: @c ?set term x11
! 9023: @c ?terminal x11
! 9024: @c ?term x11
! 9025: @cindex x11
! 9026:
! 9027: @cindex X11
! 9028:
! 9029: `gnuplot` provides the `x11` terminal type for use with X servers. This
! 9030: terminal type is set automatically at startup if the `DISPLAY` environment
! 9031: variable is set, if the `TERM` environment variable is set to `xterm`, or
! 9032: if the `-display` command line option is used.
! 9033:
! 9034: Syntax:
! 9035: @example
! 9036: set terminal x11 @{reset@} @{<n>@}
! 9037:
! 9038: @end example
! 9039:
! 9040: Multiple plot windows are supported: `set terminal x11 <n>` directs the
! 9041: output to plot window number n. If n>0, the terminal number will be
! 9042: appended to the window title and the icon will be labeled `gplt <n>`.
! 9043: The active window may distinguished by a change in cursor (from default
! 9044: to crosshair.)
! 9045:
! 9046: Plot windows remain open even when the `gnuplot` driver is changed to a
! 9047: different device. A plot window can be closed by pressing the letter q
! 9048: while that window has input focus, or by choosing `close` from a window
! 9049: manager menu. All plot windows can be closed by specifying @ref{reset}, which
! 9050: actually terminates the subprocess which maintains the windows (unless
! 9051: `-persist` was specified).
! 9052:
! 9053: Plot windows will automatically be closed at the end of the session
! 9054: unless the `-persist` option was given.
! 9055:
! 9056: The size or aspect ratio of a plot may be changed by resizing the `gnuplot`
! 9057: window.
! 9058:
! 9059: Linewidths and pointsizes may be changed from within `gnuplot` with
! 9060: @ref{linestyle}.
! 9061:
! 9062: For terminal type `x11`, `gnuplot` accepts (when initialized) the standard
! 9063: X Toolkit options and resources such as geometry, font, and name from the
! 9064: command line arguments or a configuration file. See the X(1) man page
! 9065: (or its equivalent) for a description of such options.
! 9066:
! 9067: A number of other `gnuplot` options are available for the `x11` terminal.
! 9068: These may be specified either as command-line options when `gnuplot` is
! 9069: invoked or as resources in the configuration file "/.Xdefaults". They are
! 9070: set upon initialization and cannot be altered during a `gnuplot` session.
! 9071:
! 9072:
! 9073: @noindent --- COMMAND-LINE_OPTIONS ---
! 9074:
! 9075: @c ?commands set terminal x11 command-line-options
! 9076: @c ?set terminal x11 command-line-options
! 9077: @c ?set term x11 command-line-options
! 9078: @c ?x11 command-line-options
! 9079: @cindex command-line-options
! 9080:
! 9081: In addition to the X Toolkit options, the following options may be specified
! 9082: on the command line when starting `gnuplot` or as resources in your
! 9083: ".Xdefaults" file:
! 9084:
! 9085: @example
! 9086: `-clear` requests that the window be cleared momentarily before a
! 9087: new plot is displayed.
! 9088: `-gray` requests grayscale rendering on grayscale or color displays.
! 9089: (Grayscale displays receive monochrome rendering by default.)
! 9090: `-mono` forces monochrome rendering on color displays.
! 9091: `-persist` plot windows survive after main gnuplot program exits
! 9092: `-raise` raise plot window after each plot
! 9093: `-noraise` do not raise plot window after each plot
! 9094: `-tvtwm` requests that geometry specifications for position of the
! 9095: window be made relative to the currently displayed portion
! 9096: of the virtual root.
! 9097:
! 9098: @end example
! 9099:
! 9100: The options are shown above in their command-line syntax. When entered as
! 9101: resources in ".Xdefaults", they require a different syntax.
! 9102:
! 9103: Example:
! 9104: @example
! 9105: gnuplot*gray: on
! 9106:
! 9107: @end example
! 9108:
! 9109: `gnuplot` also provides a command line option (`-pointsize <v>`) and a
! 9110: resource, `gnuplot*pointsize: <v>`, to control the size of points plotted
! 9111: with the `points` plotting style. The value `v` is a real number (greater
! 9112: than 0 and less than or equal to ten) used as a scaling factor for point
! 9113: sizes. For example, `-pointsize 2` uses points twice the default size, and
! 9114: `-pointsize 0.5` uses points half the normal size.
! 9115:
! 9116:
! 9117: @noindent --- MONOCHOME_OPTIONS ---
! 9118:
! 9119: @c ?commands set terminal x11 monochrome_options
! 9120: @c ?set terminal x11 monochrome_options
! 9121: @c ?set term x11 monochrome_options
! 9122: @c ?x11 monochrome_options
! 9123: @cindex monochrome_options
! 9124:
! 9125: For monochrome displays, `gnuplot` does not honor foreground or background
! 9126: colors. The default is black-on-white. `-rv` or `gnuplot*reverseVideo: on`
! 9127: requests white-on-black.
! 9128:
! 9129:
! 9130:
! 9131: @noindent --- COLOR_RESOURCES ---
! 9132:
! 9133: @c ?commands set terminal x11 color_resources
! 9134: @c ?set terminal x11 color_resources
! 9135: @c ?set term x11 color_resources
! 9136: @c ?x11 color_resources
! 9137: @cindex color_resources
! 9138:
! 9139: For color displays, `gnuplot` honors the following resources (shown here
! 9140: with their default values) or the greyscale resources. The values may be
! 9141: color names as listed in the X11 rgb.txt file on your system, hexadecimal
! 9142: RGB color specifications (see X11 documentation), or a color name followed
! 9143: by a comma and an `intensity` value from 0 to 1. For example, `blue, 0.5`
! 9144: means a half intensity blue.
! 9145:
! 9146: @example
! 9147: gnuplot*background: white
! 9148: gnuplot*textColor: black
! 9149: gnuplot*borderColor: black
! 9150: gnuplot*axisColor: black
! 9151: gnuplot*line1Color: red
! 9152: gnuplot*line2Color: green
! 9153: gnuplot*line3Color: blue
! 9154: gnuplot*line4Color: magenta
! 9155: gnuplot*line5Color: cyan
! 9156: gnuplot*line6Color: sienna
! 9157: gnuplot*line7Color: orange
! 9158: gnuplot*line8Color: coral
! 9159:
! 9160: @end example
! 9161:
! 9162:
! 9163: The command-line syntax for these is, for example,
! 9164:
! 9165: Example:
! 9166: @example
! 9167: gnuplot -background coral
! 9168:
! 9169: @end example
! 9170:
! 9171:
! 9172:
! 9173: @noindent --- GRAYSCALE_RESOURCES ---
! 9174:
! 9175: @c ?commands set terminal x11 grayscale_resources
! 9176: @c ?set terminal x11 grayscale_resources
! 9177: @c ?set term x11 grayscale_resources
! 9178: @c ?x11 grayscale_resources
! 9179: @cindex grayscale_resources
! 9180:
! 9181: When `-gray` is selected, `gnuplot` honors the following resources for
! 9182: grayscale or color displays (shown here with their default values). Note
! 9183: that the default background is black.
! 9184:
! 9185: @example
! 9186: gnuplot*background: black
! 9187: gnuplot*textGray: white
! 9188: gnuplot*borderGray: gray50
! 9189: gnuplot*axisGray: gray50
! 9190: gnuplot*line1Gray: gray100
! 9191: gnuplot*line2Gray: gray60
! 9192: gnuplot*line3Gray: gray80
! 9193: gnuplot*line4Gray: gray40
! 9194: gnuplot*line5Gray: gray90
! 9195: gnuplot*line6Gray: gray50
! 9196: gnuplot*line7Gray: gray70
! 9197: gnuplot*line8Gray: gray30
! 9198:
! 9199: @end example
! 9200:
! 9201:
! 9202:
! 9203:
! 9204: @noindent --- LINE_RESOURCES ---
! 9205:
! 9206: @c ?commands set terminal x11 line_resources
! 9207: @c ?set terminal x11 line_resources
! 9208: @c ?set term x11 line_resources
! 9209: @c ?x11 line_resources
! 9210: @cindex line_resources
! 9211:
! 9212: `gnuplot` honors the following resources for setting the width (in pixels) of
! 9213: plot lines (shown here with their default values.) 0 or 1 means a minimal
! 9214: width line of 1 pixel width. A value of 2 or 3 may improve the appearance of
! 9215: some plots.
! 9216:
! 9217: @example
! 9218: gnuplot*borderWidth: 2
! 9219: gnuplot*axisWidth: 0
! 9220: gnuplot*line1Width: 0
! 9221: gnuplot*line2Width: 0
! 9222: gnuplot*line3Width: 0
! 9223: gnuplot*line4Width: 0
! 9224: gnuplot*line5Width: 0
! 9225: gnuplot*line6Width: 0
! 9226: gnuplot*line7Width: 0
! 9227: gnuplot*line8Width: 0
! 9228:
! 9229: @end example
! 9230:
! 9231:
! 9232: `gnuplot` honors the following resources for setting the dash style used for
! 9233: plotting lines. 0 means a solid line. A two-digit number `jk` (`j` and `k`
! 9234: are >= 1 and <= 9) means a dashed line with a repeated pattern of `j` pixels
! 9235: on followed by `k` pixels off. For example, '16' is a "dotted" line with one
! 9236: pixel on followed by six pixels off. More elaborate on/off patterns can be
! 9237: specified with a four-digit value. For example, '4441' is four on, four off,
! 9238: four on, one off. The default values shown below are for monochrome displays
! 9239: or monochrome rendering on color or grayscale displays. For color displays,
! 9240: the default for each is 0 (solid line) except for `axisDashes` which defaults
! 9241: to a '16' dotted line.
! 9242:
! 9243: @example
! 9244: gnuplot*borderDashes: 0
! 9245: gnuplot*axisDashes: 16
! 9246: gnuplot*line1Dashes: 0
! 9247: gnuplot*line2Dashes: 42
! 9248: gnuplot*line3Dashes: 13
! 9249: gnuplot*line4Dashes: 44
! 9250: gnuplot*line5Dashes: 15
! 9251: gnuplot*line6Dashes: 4441
! 9252: gnuplot*line7Dashes: 42
! 9253: gnuplot*line8Dashes: 13
! 9254:
! 9255: @end example
! 9256:
! 9257:
! 9258: @node xlib, , x11, terminal
! 9259: @subsubsection xlib
! 9260:
! 9261: @c ?commands set terminal xlib
! 9262: @c ?set terminal xlib
! 9263: @c ?set term xlib
! 9264: @c ?terminal xlib
! 9265: @c ?term xlib
! 9266: @cindex xlib
! 9267: @tmindex xlib
! 9268:
! 9269:
! 9270: The `xlib` terminal driver supports the X11 Windows System. It generates
! 9271: gnulib_x11 commands. `set term x11` behaves similarly to `set terminal xlib;
! 9272: set output "|gnuplot_x11"`. `xlib` has no options, but see `x11`."
! 9273:
! 9274: @node tics, ticslevel, terminal, set-show
! 9275: @subsection tics
! 9276:
! 9277: @c ?commands set tics
! 9278: @c ?commands show tics
! 9279: @c ?set tics
! 9280: @c ?show tics
! 9281: @cindex tics
! 9282: @opindex tics
! 9283:
! 9284:
! 9285: The `set tics` command can be used to change the tics to be drawn outwards.
! 9286:
! 9287: Syntax:
! 9288: @example
! 9289: set tics @{<direction>@}
! 9290: show tics
! 9291:
! 9292: @end example
! 9293:
! 9294: where <direction> may be `in` (the default) or `out`.
! 9295:
! 9296: See also @ref{xtics} for more control of major (labelled) tic marks and @ref{mxtics} for control of minor tic marks.
! 9297:
! 9298: @node ticslevel, ticscale, tics, set-show
! 9299: @subsection ticslevel
! 9300:
! 9301: @c ?commands set ticslevel
! 9302: @c ?commands show ticslevel
! 9303: @c ?set ticslevel
! 9304: @c ?show ticslevel
! 9305: @cindex ticslevel
! 9306: @opindex ticslevel
! 9307:
! 9308:
! 9309: Using `splot`, one can adjust the relative height of the vertical (Z) axis
! 9310: using @ref{ticslevel}. The numeric argument provided specifies the location
! 9311: of the bottom of the scale (as a fraction of the z-range) above the xy-plane.
! 9312: The default value is 0.5. Negative values are permitted, but tic labels on
! 9313: the three axes may overlap.
! 9314:
! 9315: To place the xy-plane at a position 'pos' on the z-axis, @ref{ticslevel} should
! 9316: be set equal to (pos - zmin) / (zmin - zmax).
! 9317:
! 9318: Syntax:
! 9319: @example
! 9320: set ticslevel @{<level>@}
! 9321: show tics
! 9322:
! 9323: @end example
! 9324:
! 9325: See also @ref{view}.
! 9326:
! 9327: @node ticscale, timestamp, ticslevel, set-show
! 9328: @subsection ticscale
! 9329:
! 9330: @c ?commands set ticscale
! 9331: @c ?commands show ticscale
! 9332: @c ?set ticscale
! 9333: @c ?show ticscale
! 9334: @cindex ticscale
! 9335: @opindex ticscale
! 9336:
! 9337:
! 9338: The size of the tic marks can be adjusted with @ref{ticscale}.
! 9339:
! 9340: Syntax:
! 9341: @example
! 9342: set ticscale @{<major> @{<minor>@}@}
! 9343: show tics
! 9344:
! 9345: @end example
! 9346:
! 9347: If <minor> is not specified, it is 0.5*<major>. The default size is 1.0 for
! 9348: major tics and 0.5 for minor tics. Note that it is possible to have the tic
! 9349: marks pointing outward by specifying a negative size.
! 9350:
! 9351: @node timestamp, timefmt, ticscale, set-show
! 9352: @subsection timestamp
! 9353:
! 9354: @c ?commands set timestamp
! 9355: @c ?commands set time
! 9356: @c ?commands set notimestamp
! 9357: @c ?commands show timestamp
! 9358: @c ?set timestamp
! 9359: @c ?set time
! 9360: @c ?set notimestamp
! 9361: @c ?show timestamp
! 9362: @cindex timestamp
! 9363: @opindex timestamp
! 9364:
! 9365:
! 9366: @cindex notimestamp
! 9367:
! 9368: The command @ref{timestamp} places the time and date of the plot in the left
! 9369: margin.
! 9370:
! 9371: Syntax:
! 9372: @example
! 9373: set timestamp @{"<format>"@} @{top|bottom@} @{@{no@}rotate@}
! 9374: @{<xoff>@}@{,<yoff>@} @{"<font>"@}
! 9375: set notimestamp
! 9376: show timestamp
! 9377:
! 9378: @end example
! 9379:
! 9380: The format string allows you to choose the format used to write the date and
! 9381: time. Its default value is what asctime() uses: "%a %b %d %H:%M:%S %Y"
! 9382: (weekday, month name, day of the month, hours, minutes, seconds, four-digit
! 9383: year). With `top` or `bottom` you can place the timestamp at the top or
! 9384: bottom of the left margin (default: bottom). `rotate` lets you write the
! 9385: timestamp vertically, if your terminal supports vertical text. The constants
! 9386: <xoff> and <off> are offsets from the default position given in character
! 9387: screen coordinates. <font> is used to specify the font with which the time
! 9388: is to be written.
! 9389:
! 9390: The abbreviation `time` may be used in place of @ref{timestamp}.
! 9391:
! 9392: Example:
! 9393: @example
! 9394: set timestamp "%d/%m/%y %H:%M" 80,-2 "Helvetica"
! 9395:
! 9396: @end example
! 9397:
! 9398: See @ref{timefmt} for more information about time format strings.
! 9399:
! 9400: @node timefmt, title_, timestamp, set-show
! 9401: @subsection timefmt
! 9402:
! 9403: @c ?commands set timefmt
! 9404: @c ?commands show timefmt
! 9405: @c ?set timefmt
! 9406: @c ?show timefmt
! 9407: @cindex timefmt
! 9408: @opindex timefmt
! 9409:
! 9410:
! 9411: This command applies to timeseries where data are composed of dates/times.
! 9412: It has no meaning unless the command `set xdata time` is given also.
! 9413:
! 9414: Syntax:
! 9415: @example
! 9416: set timefmt "<format string>"
! 9417: show timefmt
! 9418:
! 9419: @end example
! 9420:
! 9421: The string argument tells `gnuplot` how to read timedata from the datafile.
! 9422: The valid formats are:
! 9423:
! 9424:
! 9425: @example
! 9426: Format Explanation
! 9427: %d day of the month, 1--31
! 9428: %m month of the year, 1--12
! 9429: %y year, 0--99
! 9430: %Y year, 4-digit
! 9431: %j day of the year, 1--365
! 9432: %H hour, 0--24
! 9433: %M minute, 0--60
! 9434: %S second, 0--60
! 9435: %b three-character abbreviation of the name of the month
! 9436: %B name of the month
! 9437:
! 9438: @end example
! 9439:
! 9440: Any character is allowed in the string, but must match exactly. \t (tab) is
! 9441: recognized. Backslash-octals (\nnn) are converted to char. If there is no
! 9442: separating character between the time/date elements, then %d, %m, %y, %H, %M
! 9443: and %S read two digits each, %Y reads four digits and %j reads three digits.
! 9444: %b requires three characters, and %B requires as many as it needs.
! 9445:
! 9446: Spaces are treated slightly differently. A space in the string stands for
! 9447: zero or more whitespace characters in the file. That is, "%H %M" can be used
! 9448: to read "1220" and "12 20" as well as "12 20".
! 9449:
! 9450: Each set of non-blank characters in the timedata counts as one column in the
! 9451: `using n:n` specification. Thus `11:11 25/12/76 21.0` consists of three
! 9452: columns. To avoid confusion, `gnuplot` requires that you provide a complete
! 9453: @ref{using} specification if your file contains timedata.
! 9454:
! 9455: Since `gnuplot` cannot read non-numerical text, if the date format includes
! 9456: the day or month in words, the format string must exclude this text. But
! 9457: it can still be printed with the "%a", "%A", "%b", or "%B" specifier: see
! 9458: `set format` for more details about these and other options for printing
! 9459: timedata. (`gnuplot` will determine the proper month and weekday from the
! 9460: numerical values.)
! 9461:
! 9462: See also @ref{xdata} and `Time/date` for more information.
! 9463:
! 9464: Example:
! 9465: @example
! 9466: set timefmt "%d/%m/%Y\t%H:%M"
! 9467: @end example
! 9468:
! 9469: tells `gnuplot` to read date and time separated by tab. (But look closely at
! 9470: your data---what began as a tab may have been converted to spaces somewhere
! 9471: along the line; the format string must match what is actually in the file.)
! 9472: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/timedat.html,Time Data Demo }
! 9473:
! 9474: @node title_, tmargin, timefmt, set-show
! 9475: @subsection title
! 9476:
! 9477: @c ?commands set title
! 9478: @c ?commands show title
! 9479: @c ?set title
! 9480: @c ?show title
! 9481: @cindex title
! 9482: @opindex title
! 9483:
! 9484:
! 9485: The `set title` command produces a plot title that is centered at the top of
! 9486: the plot. `set title` is a special case of @ref{label}.
! 9487:
! 9488: Syntax:
! 9489: @example
! 9490: set title @{"<title-text>"@} @{<xoff>@}@{,<yoff>@} @{"<font>,@{<size>@}"@}
! 9491: show title
! 9492:
! 9493: @end example
! 9494:
! 9495: Specifying constants <xoff> or <yoff> as optional offsets for the title will
! 9496: move the title <xoff> or <yoff> character screen coordinates (not graph
! 9497: coordinates). For example, "`set title ,-1`" will change only the y offset
! 9498: of the title, moving the title down by roughly the height of one character.
! 9499:
! 9500: <font> is used to specify the font with which the title is to be written;
! 9501: the units of the font <size> depend upon which terminal is used.
! 9502:
! 9503: `set title` with no parameters clears the title.
! 9504:
! 9505: See `syntax` for details about the processing of backslash sequences and
! 9506: the distinction between single- and double-quotes.
! 9507:
! 9508: @node tmargin, trange, title_, set-show
! 9509: @subsection tmargin
! 9510:
! 9511: @c ?commands set tmargin
! 9512: @c ?set tmargin
! 9513: @cindex tmargin
! 9514: @opindex tmargin
! 9515:
! 9516:
! 9517: The command @ref{tmargin} sets the size of the top margin. Please see
! 9518: @ref{margin} for details.
! 9519:
! 9520: @node trange, urange, tmargin, set-show
! 9521: @subsection trange
! 9522:
! 9523: @c ?commands set trange
! 9524: @c ?commands show trange
! 9525: @c ?set trange
! 9526: @c ?show trange
! 9527: @cindex trange
! 9528: @opindex trange
! 9529:
! 9530:
! 9531: The @ref{trange} command sets the parametric range used to compute x and y
! 9532: values when in parametric or polar modes. Please see @ref{xrange} for
! 9533: details.
! 9534:
! 9535: @node urange, variables, trange, set-show
! 9536: @subsection urange
! 9537:
! 9538: @c ?commands set urange
! 9539: @c ?commands show urange
! 9540: @c ?set urange
! 9541: @c ?show urange
! 9542: @cindex urange
! 9543: @opindex urange
! 9544:
! 9545:
! 9546: The @ref{urange} and @ref{vrange} commands set the parametric ranges used
! 9547: to compute x, y, and z values when in `splot` parametric mode. Please see
! 9548: @ref{xrange} for details.
! 9549:
! 9550: @node variables, version, urange, set-show
! 9551: @subsection variables
! 9552:
! 9553: @c ?commands show variables
! 9554: @c ?show variables
! 9555: The @ref{variables} command lists all user-defined variables and their
! 9556: values.
! 9557:
! 9558: Syntax:
! 9559: @example
! 9560: show variables
! 9561:
! 9562: @end example
! 9563:
! 9564: @node version, view, variables, set-show
! 9565: @subsection version
! 9566:
! 9567: @c ?show version
! 9568: The @ref{version} command lists the version of gnuplot being run, its last
! 9569: modification date, the copyright holders, and email addresses for the FAQ,
! 9570: the info-gnuplot mailing list, and reporting bugs--in short, the information
! 9571: listed on the screen when the program is invoked interactively.
! 9572:
! 9573: Syntax:
! 9574: @example
! 9575: show version @{long@}
! 9576:
! 9577: @end example
! 9578:
! 9579: When the `long` option is given, it also lists the operating system, the
! 9580: compilation options used when `gnuplot` was installed, the location of the
! 9581: help file, and (again) the useful email addresses.
! 9582:
! 9583: @node view, vrange, version, set-show
! 9584: @subsection view
! 9585:
! 9586: @c ?commands set view
! 9587: @c ?commands show view
! 9588: @c ?set view
! 9589: @c ?show view
! 9590: @cindex view
! 9591: @opindex view
! 9592:
! 9593:
! 9594: The @ref{view} command sets the viewing angle for `splot`s. It controls how
! 9595: the 3-d coordinates of the plot are mapped into the 2-d screen space. It
! 9596: provides controls for both rotation and scaling of the plotted data, but
! 9597: supports orthographic projections only.
! 9598:
! 9599: Syntax:
! 9600: @example
! 9601: set view <rot_x> @{,@{<rot_z>@}@{,@{<scale>@}@{,<scale_z>@}@}@}
! 9602: show view
! 9603:
! 9604: @end example
! 9605:
! 9606: where <rot_x> and <rot_z> control the rotation angles (in degrees) in a
! 9607: virtual 3-d coordinate system aligned with the screen such that initially
! 9608: (that is, before the rotations are performed) the screen horizontal axis is
! 9609: x, screen vertical axis is y, and the axis perpendicular to the screen is z.
! 9610: The first rotation applied is <rot_x> around the x axis. The second rotation
! 9611: applied is <rot_z> around the new z axis.
! 9612:
! 9613: <rot_x> is bounded to the [0:180] range with a default of 60 degrees, while
! 9614: <rot_z> is bounded to the [0:360] range with a default of 30 degrees.
! 9615: <scale> controls the scaling of the entire `splot`, while <scale_z> scales
! 9616: the z axis only. Both scales default to 1.0.
! 9617:
! 9618: Examples:
! 9619: @example
! 9620: set view 60, 30, 1, 1
! 9621: set view ,,0.5
! 9622:
! 9623: @end example
! 9624:
! 9625: The first sets all the four default values. The second changes only scale,
! 9626: to 0.5.
! 9627:
! 9628: See also @ref{ticslevel}.
! 9629:
! 9630: @node vrange, x2data, view, set-show
! 9631: @subsection vrange
! 9632:
! 9633: @c ?commands set vrange
! 9634: @c ?commands show vrange
! 9635: @c ?set vrange
! 9636: @c ?show vrange
! 9637: @cindex vrange
! 9638: @opindex vrange
! 9639:
! 9640:
! 9641: The @ref{urange} and @ref{vrange} commands set the parametric ranges used
! 9642: to compute x, y, and z values when in `splot` parametric mode. Please see
! 9643: @ref{xrange} for details.
! 9644:
! 9645: @node x2data, x2dtics, vrange, set-show
! 9646: @subsection x2data
! 9647:
! 9648: @c ?commands set x2data
! 9649: @c ?commands show x2data
! 9650: @c ?set x2data
! 9651: @c ?show x2data
! 9652: @cindex x2data
! 9653: @opindex x2data
! 9654:
! 9655:
! 9656: The @ref{x2data} command sets data on the x2 (top) axis to timeseries
! 9657: (dates/times). Please see @ref{xdata}.
! 9658:
! 9659: @node x2dtics, x2label, x2data, set-show
! 9660: @subsection x2dtics
! 9661:
! 9662: @c ?commands set x2dtics
! 9663: @c ?commands set nox2dtics
! 9664: @c ?commands show x2dtics
! 9665: @c ?set x2dtics
! 9666: @c ?set nox2dtics
! 9667: @c ?show x2dtics
! 9668: @cindex x2dtics
! 9669: @opindex x2dtics
! 9670:
! 9671:
! 9672: @cindex nox2dtics
! 9673:
! 9674: The @ref{x2dtics} command changes tics on the x2 (top) axis to days of the
! 9675: week. Please see @ref{xdtics} for details.
! 9676:
! 9677: @node x2label, x2mtics, x2dtics, set-show
! 9678: @subsection x2label
! 9679:
! 9680: @c ?commands set x2label
! 9681: @c ?commands show x2label
! 9682: @c ?set x2label
! 9683: @c ?show x2label
! 9684: @cindex x2label
! 9685: @opindex x2label
! 9686:
! 9687:
! 9688: The @ref{x2label} command sets the label for the x2 (top) axis. Please see
! 9689: @ref{xlabel}.
! 9690:
! 9691: @node x2mtics, x2range, x2label, set-show
! 9692: @subsection x2mtics
! 9693:
! 9694: @c ?commands set x2mtics
! 9695: @c ?commands set nox2mtics
! 9696: @c ?commands show x2mtics
! 9697: @c ?set x2mtics
! 9698: @c ?set nox2mtics
! 9699: @c ?show x2mtics
! 9700: @cindex x2mtics
! 9701: @opindex x2mtics
! 9702:
! 9703:
! 9704: @cindex nox2mtics
! 9705:
! 9706: The @ref{x2mtics} command changes tics on the x2 (top) axis to months of the
! 9707: year. Please see @ref{xmtics} for details.
! 9708:
! 9709: @node x2range, x2tics, x2mtics, set-show
! 9710: @subsection x2range
! 9711:
! 9712: @c ?commands set x2range
! 9713: @c ?commands show x2range
! 9714: @c ?set x2range
! 9715: @c ?show x2range
! 9716: @cindex x2range
! 9717: @opindex x2range
! 9718:
! 9719:
! 9720: The @ref{x2range} command sets the horizontal range that will be displayed on
! 9721: the x2 (top) axis. Please see @ref{xrange} for details.
! 9722:
! 9723: @node x2tics, x2zeroaxis, x2range, set-show
! 9724: @subsection x2tics
! 9725:
! 9726: @c ?commands set x2tics
! 9727: @c ?commands set nox2tics
! 9728: @c ?commands show x2tics
! 9729: @c ?set x2tics
! 9730: @c ?set nox2tics
! 9731: @c ?show x2tics
! 9732: @cindex x2tics
! 9733: @opindex x2tics
! 9734:
! 9735:
! 9736: @cindex nox2tics
! 9737:
! 9738: The @ref{x2tics} command controls major (labelled) tics on the x2 (top) axis.
! 9739: Please see @ref{xtics} for details.
! 9740:
! 9741: @node x2zeroaxis, xdata, x2tics, set-show
! 9742: @subsection x2zeroaxis
! 9743:
! 9744: @c ?commands set x2zeroaxis
! 9745: @c ?commands set nox2zeroaxis
! 9746: @c ?commands show x2zeroaxis
! 9747: @c ?set x2zeroaxis
! 9748: @c ?set nox2zeroaxis
! 9749: @c ?show x2zeroaxis
! 9750: @cindex x2zeroaxis
! 9751: @opindex x2zeroaxis
! 9752:
! 9753:
! 9754: @cindex nox2zeroaxis
! 9755:
! 9756: The @ref{x2zeroaxis} command draws a line at the origin of the x2 (top) axis
! 9757: (y2 = 0). For details, please see
! 9758: @ref{zeroaxis}.
! 9759:
! 9760: @node xdata, xdtics, x2zeroaxis, set-show
! 9761: @subsection xdata
! 9762:
! 9763: @c ?commands set xdata
! 9764: @c ?commands show xdata
! 9765: @c ?set xdata
! 9766: @c ?show xdata
! 9767: @cindex xdata
! 9768: @opindex xdata
! 9769:
! 9770:
! 9771: This command sets the datatype on the x axis to time/date. A similar command
! 9772: does the same thing for each of the other axes.
! 9773:
! 9774: Syntax:
! 9775: @example
! 9776: set xdata @{time@}
! 9777: show xdata
! 9778:
! 9779: @end example
! 9780:
! 9781: The same syntax applies to @ref{ydata}, @ref{zdata}, @ref{x2data} and @ref{y2data}.
! 9782:
! 9783: The `time` option signals that the datatype is indeed time/date. If the
! 9784: option is not specified, the datatype reverts to normal.
! 9785:
! 9786: See @ref{timefmt} to tell `gnuplot` how to read date or time data. The
! 9787: time/date is converted to seconds from start of the century. There is
! 9788: currently only one timefmt, which implies that all the time/date columns must
! 9789: confirm to this format. Specification of ranges should be supplied as quoted
! 9790: strings according to this format to avoid interpretation of the time/date as
! 9791: an expression.
! 9792:
! 9793: The function 'strftime' (type "man strftime" on unix to look it up) is used
! 9794: to print tic-mark labels. `gnuplot` tries to figure out a reasonable format
! 9795: for this unless the `set format x "string"` has supplied something that does
! 9796: not look like a decimal format (more than one '%' or neither %f nor %g).
! 9797:
! 9798: See also `Time/date` for more information.
! 9799:
! 9800: @node xdtics, xlabel, xdata, set-show
! 9801: @subsection xdtics
! 9802:
! 9803: @c ?commands set xdtics
! 9804: @c ?commands set noxdtics
! 9805: @c ?commands show xdtics
! 9806: @c ?set xdtics
! 9807: @c ?set noxdtics
! 9808: @c ?show xdtics
! 9809: @cindex xdtics
! 9810: @opindex xdtics
! 9811:
! 9812:
! 9813: @cindex noxdtics
! 9814:
! 9815: The @ref{xdtics} commands converts the x-axis tic marks to days of the week
! 9816: where 0=Sun and 6=Sat. Overflows are converted modulo 7 to dates. `set
! 9817: noxdtics` returns the labels to their default values. Similar commands do
! 9818: the same things for the other axes.
! 9819:
! 9820: Syntax:
! 9821: @example
! 9822: set xdtics
! 9823: set noxdtics
! 9824: show xdtics
! 9825:
! 9826: @end example
! 9827:
! 9828: The same syntax applies to @ref{ydtics}, @ref{zdtics}, @ref{x2dtics} and @ref{y2dtics}.
! 9829:
! 9830: See also the `set format` command.
! 9831:
! 9832: @node xlabel, xmtics, xdtics, set-show
! 9833: @subsection xlabel
! 9834:
! 9835: @c ?commands set xlabel
! 9836: @c ?commands show xlabel
! 9837: @c ?set xlabel
! 9838: @c ?show xlabel
! 9839: @cindex xlabel
! 9840: @opindex xlabel
! 9841:
! 9842:
! 9843: The @ref{xlabel} command sets the x axis label. Similar commands set labels
! 9844: on the other axes.
! 9845:
! 9846: Syntax:
! 9847: @example
! 9848: set xlabel @{"<label>"@} @{<xoff>@}@{,<yoff>@} @{"<font>@{,<size>@}"@}
! 9849: show xlabel
! 9850:
! 9851: @end example
! 9852:
! 9853: The same syntax applies to @ref{x2label}, @ref{ylabel}, @ref{y2label} and @ref{zlabel}.
! 9854:
! 9855: Specifying the constants <xoff> or <yoff> as optional offsets for a label
! 9856: will move it <xoff> or <yoff> character widths or heights. For example,
! 9857: "` set xlabel -1`" will change only the x offset of the xlabel, moving the
! 9858: label roughly one character width to the left. The size of a character
! 9859: depends on both the font and the terminal.
! 9860:
! 9861: <font> is used to specify the font in which the label is written; the units
! 9862: of the font <size> depend upon which terminal is used.
! 9863:
! 9864: To clear a label, put no options on the command line, e.g., "@ref{y2label}".
! 9865:
! 9866: The default positions of the axis labels are as follows:
! 9867:
! 9868: xlabel: The x-axis label is centered below the bottom axis.
! 9869:
! 9870: ylabel: The position of the y-axis label depends on the terminal, and can be
! 9871: one of the following three positions:
! 9872:
! 9873: 1. Horizontal text flushed left at the top left of the plot. Terminals that
! 9874: cannot rotate text will probably use this method. If @ref{x2tics} is also
! 9875: in use, the ylabel may overwrite the left-most x2tic label. This may be
! 9876: remedied by adjusting the ylabel position or the left margin.
! 9877:
! 9878: 2. Vertical text centered vertically at the left of the plot. Terminals
! 9879: that can rotate text will probably use this method.
! 9880:
! 9881: 3. Horizontal text centered vertically at the left of the plot. The EEPIC,
! 9882: LaTeX and TPIC drivers use this method. The user must insert line breaks
! 9883: using \\ to prevent the ylabel from overwriting the plot. To produce a
! 9884: vertical row of characters, add \\ between every printing character (but this
! 9885: is ugly).
! 9886:
! 9887: zlabel: The z-axis label is centered along the z axis and placed in the space
! 9888: above the grid level.
! 9889:
! 9890: y2label: The y2-axis label is placed to the right of the y2 axis. The
! 9891: position is terminal-dependent in the same manner as is the y-axis label.
! 9892:
! 9893: x2label: The x2-axis label is placed above the top axis but below the plot
! 9894: title. It is also possible to create an x2-axis label by using new-line
! 9895: characters to make a multi-line plot title, e.g.,
! 9896:
! 9897: @example
! 9898: set title "This is the title\n\nThis is the x2label"
! 9899:
! 9900: @end example
! 9901:
! 9902: Note that double quotes must be used. The same font will be used for both
! 9903: lines, of course.
! 9904:
! 9905: If you are not satisfied with the default position of an axis label, use @ref{label} instead--that command gives you much more control over where text is
! 9906: placed.
! 9907:
! 9908: Please see `set syntax` for further information about backslash processing
! 9909: and the difference between single- and double-quoted strings.
! 9910:
! 9911: @node xmtics, xrange, xlabel, set-show
! 9912: @subsection xmtics
! 9913:
! 9914: @c ?commands set xmtics
! 9915: @c ?commands set noxmtics
! 9916: @c ?commands show xmtics
! 9917: @c ?set xmtics
! 9918: @c ?set noxmtics
! 9919: @c ?show xmtics
! 9920: @cindex xmtics
! 9921: @opindex xmtics
! 9922:
! 9923:
! 9924: @cindex noxmtics
! 9925:
! 9926: The @ref{xmtics} commands converts the x-axis tic marks to months of the
! 9927: year where 1=Jan and 12=Dec. Overflows are converted modulo 12 to months.
! 9928: The tics are returned to their default labels by `set noxmtics`. Similar
! 9929: commands perform the same duties for the other axes.
! 9930:
! 9931: Syntax:
! 9932: @example
! 9933: set xmtics
! 9934: set noxmtics
! 9935: show xmtics
! 9936:
! 9937: @end example
! 9938:
! 9939: The same syntax applies to @ref{x2mtics}, @ref{ymtics}, @ref{y2mtics}, and @ref{zmtics}.
! 9940:
! 9941: See also the `set format` command.
! 9942:
! 9943: @node xrange, xtics, xmtics, set-show
! 9944: @subsection xrange
! 9945:
! 9946: @c ?commands set xrange
! 9947: @c ?commands show xrange
! 9948: @c ?set xrange
! 9949: @c ?show xrange
! 9950: @cindex xrange
! 9951: @opindex xrange
! 9952:
! 9953:
! 9954: The @ref{xrange} command sets the horizontal range that will be displayed.
! 9955: A similar command exists for each of the other axes, as well as for the
! 9956: polar radius r and the parametric variables t, u, and v.
! 9957:
! 9958: Syntax:
! 9959: @example
! 9960: set xrange [@{@{<min>@}:@{<max>@}@}] @{@{no@}reverse@} @{@{no@}writeback@}
! 9961: show xrange
! 9962:
! 9963: @end example
! 9964:
! 9965: where <min> and <max> terms are constants, expressions or an asterisk to set
! 9966: autoscaling. If the data are time/date, you must give the range as a quoted
! 9967: string according to the @ref{timefmt} format. Any value omitted will not be
! 9968: changed.
! 9969:
! 9970: The same syntax applies to @ref{yrange}, @ref{zrange}, @ref{x2range}, @ref{y2range},
! 9971: @ref{rrange}, @ref{trange}, @ref{urange} and @ref{vrange}.
! 9972:
! 9973: The `reverse` option reverses the direction of the axis, e.g., `set xrange
! 9974: [0:1] reverse` will produce an axis with 1 on the left and 0 on the right.
! 9975: This is identical to the axis produced by `set xrange [1:0]`, of course.
! 9976: `reverse` is intended primarily for use with @ref{autoscale}.
! 9977:
! 9978: The `writeback` option essentially saves the range found by @ref{autoscale} in
! 9979: the buffers that would be filled by @ref{xrange}. This is useful if you wish
! 9980: to plot several functions together but have the range determined by only
! 9981: some of them. The `writeback` operation is performed during the @ref{plot}
! 9982: execution, so it must be specified before that command. For example,
! 9983:
! 9984: @example
! 9985: set xrange [-10:10]
! 9986: set yrange [] writeback
! 9987: plot sin(x)
! 9988: set noautoscale y
! 9989: replot x/2
! 9990:
! 9991: @end example
! 9992:
! 9993: results in a yrange of [-1:1] as found only from the range of sin(x); the
! 9994: [-5:5] range of x/2 is ignored. Executing @ref{yrange} after each command
! 9995: in the above example should help you understand what is going on.
! 9996:
! 9997: In 2-d, @ref{xrange} and @ref{yrange} determine the extent of the axes, @ref{trange}
! 9998: determines the range of the parametric variable in parametric mode or the
! 9999: range of the angle in polar mode. Similarly in parametric 3-d, @ref{xrange},
! 10000: @ref{yrange}, and @ref{zrange} govern the axes and @ref{urange} and @ref{vrange} govern the
! 10001: parametric variables.
! 10002:
! 10003: In polar mode, @ref{rrange} determines the radial range plotted. <rmin> acts as
! 10004: an additive constant to the radius, whereas <rmax> acts as a clip to the
! 10005: radius---no point with radius greater than <rmax> will be plotted. @ref{xrange}
! 10006: and @ref{yrange} are affected---the ranges can be set as if the graph was of
! 10007: r(t)-rmin, with rmin added to all the labels.
! 10008:
! 10009: Any range may be partially or totally autoscaled, although it may not make
! 10010: sense to autoscale a parametric variable unless it is plotted with data.
! 10011:
! 10012: Ranges may also be specified on the @ref{plot} command line. A range given on
! 10013: the plot line will be used for that single @ref{plot} command; a range given by
! 10014: a `set` command will be used for all subsequent plots that do not specify
! 10015: their own ranges. The same holds true for `splot`.
! 10016:
! 10017: Examples:
! 10018:
! 10019: To set the xrange to the default:
! 10020: @example
! 10021: set xrange [-10:10]
! 10022:
! 10023: @end example
! 10024:
! 10025: To set the yrange to increase downwards:
! 10026: @example
! 10027: set yrange [10:-10]
! 10028:
! 10029: @end example
! 10030:
! 10031: To change zmax to 10 without affecting zmin (which may still be autoscaled):
! 10032: @example
! 10033: set zrange [:10]
! 10034:
! 10035: @end example
! 10036:
! 10037: To autoscale xmin while leaving xmax unchanged:
! 10038: @example
! 10039: set xrange [*:]
! 10040:
! 10041: @end example
! 10042:
! 10043: @node xtics, xzeroaxis, xrange, set-show
! 10044: @subsection xtics
! 10045:
! 10046: @c ?commands set xtics
! 10047: @c ?commands set noxtics
! 10048: @c ?commands show xtics
! 10049: @c ?set xtics
! 10050: @c ?set noxtics
! 10051: @c ?show xtics
! 10052: @cindex xtics
! 10053: @opindex xtics
! 10054:
! 10055:
! 10056: @cindex noxtics
! 10057:
! 10058: Fine control of the major (labelled) tics on the x axis is possible with the
! 10059: @ref{xtics} command. The tics may be turned off with the `set noxtics`
! 10060: command, and may be turned on (the default state) with @ref{xtics}. Similar
! 10061: commands control the major tics on the y, z, x2 and y2 axes.
! 10062:
! 10063: Syntax:
! 10064: @example
! 10065: set xtics @{axis | border@} @{@{no@}mirror@} @{@{no@}rotate@}
! 10066: @{ autofreq
! 10067: | <incr>
! 10068: | <start>, <incr> @{,<end>@}
! 10069: | (@{"<label>"@} <pos> @{,@{"<label>"@} <pos>@}...) @}
! 10070: set noxtics
! 10071: show xtics
! 10072:
! 10073: @end example
! 10074:
! 10075: The same syntax applies to @ref{ytics}, @ref{ztics}, @ref{x2tics} and @ref{y2tics}.
! 10076:
! 10077: `axis` or @ref{border} tells `gnuplot` to put the tics (both the tics themselves
! 10078: and the accompanying labels) along the axis or the border, respectively. If
! 10079: the axis is very close to the border, the `axis` option can result in tic
! 10080: labels overwriting other text written in the margin.
! 10081:
! 10082: `mirror` tells `gnuplot` to put unlabelled tics at the same positions on the
! 10083: opposite border. `nomirror` does what you think it does.
! 10084:
! 10085: `rotate` asks `gnuplot` to rotate the text through 90 degrees, which will be
! 10086: done if the terminal driver in use supports text rotation. `norotate`
! 10087: cancels this.
! 10088:
! 10089: The defaults are `border mirror norotate` for tics on the x and y axes, and
! 10090: `border nomirror norotate` for tics on the x2 and y2 axes. For the z axis,
! 10091: the the `@{axis | border@}` option is not available and the default is
! 10092: `nomirror`. If you do want to mirror the z-axis tics, you might want to
! 10093: create a bit more room for them with @ref{border}.
! 10094:
! 10095: @ref{xtics} with no options restores the default border or axis if xtics are
! 10096: being displayed; otherwise it has no effect. Any previously specified tic
! 10097: frequency or position @{and labels@} are retained.
! 10098:
! 10099: Positions of the tics are calculated automatically by default or if the
! 10100: `autofreq` option is given; otherwise they may be specified in either of
! 10101: two forms:
! 10102:
! 10103: The implicit <start>, <incr>, <end> form specifies that a series of tics will
! 10104: be plotted on the axis between the values <start> and <end> with an increment
! 10105: of <incr>. If <end> is not given, it is assumed to be infinity. The
! 10106: increment may be negative. If neither <start> nor <end> is given, <start> is
! 10107: assumed to be negative infinity, <end> is assumed to be positive infinity,
! 10108: and the tics will be drawn at integral multiples of <step>. If the axis is
! 10109: logarithmic, the increment will be used as a multiplicative factor.
! 10110:
! 10111: Examples:
! 10112:
! 10113: Make tics at 0, 0.5, 1, 1.5, ..., 9.5, 10.
! 10114: @example
! 10115: set xtics 0,.5,10
! 10116:
! 10117: @end example
! 10118:
! 10119: Make tics at ..., -10, -5, 0, 5, 10, ...
! 10120: @example
! 10121: set xtics 5
! 10122:
! 10123: @end example
! 10124:
! 10125: Make tics at 1, 100, 1e4, 1e6, 1e8.
! 10126: @example
! 10127: set logscale x; set xtics 1,100,10e8
! 10128:
! 10129: @end example
! 10130:
! 10131: The explicit ("<label>" <pos>, ...) form allows arbitrary tic positions or
! 10132: non-numeric tic labels. A set of tics is a set of positions, each with its
! 10133: own optional label. Note that the label is a string enclosed by quotes. It
! 10134: may be a constant string, such as "hello", may contain formatting information
! 10135: for converting the position into its label, such as "%3f clients", or may be
! 10136: empty, "". See `set format` for more information. If no string is given,
! 10137: the default label (numerical) is used. In this form, the tics do not need to
! 10138: be listed in numerical order.
! 10139:
! 10140: Examples:
! 10141: @example
! 10142: set xtics ("low" 0, "medium" 50, "high" 100)
! 10143: set xtics (1,2,4,8,16,32,64,128,256,512,1024)
! 10144: set ytics ("bottom" 0, "" 10, "top" 20)
! 10145:
! 10146: @end example
! 10147:
! 10148: In the second example, all tics are labelled. In the third, only the end
! 10149: tics are labelled.
! 10150:
! 10151: However they are specified, tics will only be plotted when in range.
! 10152:
! 10153: Format (or omission) of the tic labels is controlled by `set format`, unless
! 10154: the explicit text of a labels is included in the `set xtic (`<label>`)` form.
! 10155:
! 10156: Minor (unlabelled) tics can be added by the @ref{mxtics} command.
! 10157:
! 10158: In case of timeseries data, position values must be given as quoted dates
! 10159: or times according to the format @ref{timefmt}. If the <start>, <incr>, <end>
! 10160: form is used, <start> and <end> must be given according to @ref{timefmt}, but
! 10161: <incr> must be in seconds. Times will be written out according to the format
! 10162: given on `set format`, however.
! 10163:
! 10164: Examples:
! 10165: @example
! 10166: set xdata time
! 10167: set timefmt "%d/%m"
! 10168: set format x "%b %d"
! 10169: set xrange ["01/12":"06/12"]
! 10170: set xtics "01/12", 172800, "05/12"
! 10171:
! 10172: @end example
! 10173:
! 10174: @example
! 10175: set xdata time
! 10176: set timefmt "%d/%m"
! 10177: set format x "%b %d"
! 10178: set xrange ["01/12":"06/12"]
! 10179: set xtics ("01/12", "" "03/12", "05/12")
! 10180: @end example
! 10181:
! 10182: Both of these will produce tics "Dec 1", "Dec 3", and "Dec 5", but in the
! 10183: second example the tic at "Dec 3" will be unlabelled.
! 10184:
! 10185:
! 10186: @node xzeroaxis, y2data, xtics, set-show
! 10187: @subsection xzeroaxis
! 10188:
! 10189: @c ?commands set xzeroaxis
! 10190: @c ?commands set noxzeroaxis
! 10191: @c ?commands show xzeroaxis
! 10192: @c ?set xzeroaxis
! 10193: @c ?set noxzeroaxis
! 10194: @c ?show xzeroaxis
! 10195: @cindex xzeroaxis
! 10196: @opindex xzeroaxis
! 10197:
! 10198:
! 10199: @cindex noxzeroaxis
! 10200:
! 10201: The @ref{xzeroaxis} command draws a line at y = 0. For details, please see
! 10202: @ref{zeroaxis}.
! 10203:
! 10204: @node y2data, y2dtics, xzeroaxis, set-show
! 10205: @subsection y2data
! 10206:
! 10207: @c ?commands set y2data
! 10208: @c ?commands show y2data
! 10209: @c ?set y2data
! 10210: @c ?show y2data
! 10211: @cindex y2data
! 10212: @opindex y2data
! 10213:
! 10214:
! 10215: The @ref{y2data} command sets y2 (right-hand) axis data to timeseries
! 10216: (dates/times). Please see @ref{xdata}.
! 10217:
! 10218: @node y2dtics, y2label, y2data, set-show
! 10219: @subsection y2dtics
! 10220:
! 10221: @c ?commands set y2dtics
! 10222: @c ?commands set noy2dtics
! 10223: @c ?set y2dtics
! 10224: @c ?set noy2dtics
! 10225: @c ?show y2dtics
! 10226: @cindex y2dtics
! 10227: @opindex y2dtics
! 10228:
! 10229:
! 10230: @cindex noy2dtics
! 10231:
! 10232: The @ref{y2dtics} command changes tics on the y2 (right-hand) axis to days of
! 10233: the week. Please see @ref{xdtics} for details.
! 10234:
! 10235: @node y2label, y2mtics, y2dtics, set-show
! 10236: @subsection y2label
! 10237:
! 10238: @c ?commands set y2label
! 10239: @c ?commands show y2label
! 10240: @c ?set y2label
! 10241: @c ?show y2label
! 10242: @cindex y2label
! 10243: @opindex y2label
! 10244:
! 10245:
! 10246: The @ref{y2dtics} command sets the label for the y2 (right-hand) axis.
! 10247: Please see @ref{xlabel}.
! 10248:
! 10249: @node y2mtics, y2range, y2label, set-show
! 10250: @subsection y2mtics
! 10251:
! 10252: @c ?commands set y2mtics
! 10253: @c ?commands set noy2mtics
! 10254: @c ?commands show y2mtics
! 10255: @c ?set y2mtics
! 10256: @c ?set noy2mtics
! 10257: @c ?show y2mtics
! 10258: @cindex y2mtics
! 10259: @opindex y2mtics
! 10260:
! 10261:
! 10262: @cindex noy2mtics
! 10263:
! 10264: The @ref{y2mtics} command changes tics on the y2 (right-hand) axis to months
! 10265: of the year. Please see @ref{xmtics} for details.
! 10266:
! 10267: @node y2range, y2tics, y2mtics, set-show
! 10268: @subsection y2range
! 10269:
! 10270: @c ?commands set y2range
! 10271: @c ?commands show y2range
! 10272: @c ?set y2range
! 10273: @c ?show y2range
! 10274: @cindex y2range
! 10275: @opindex y2range
! 10276:
! 10277:
! 10278: The @ref{y2range} command sets the vertical range that will be displayed on
! 10279: the y2 (right-hand) axis. Please see @ref{xrange} for details.
! 10280:
! 10281: @node y2tics, y2zeroaxis, y2range, set-show
! 10282: @subsection y2tics
! 10283:
! 10284: @c ?commands set y2tics
! 10285: @c ?commands set noy2tics
! 10286: @c ?commands show y2tics
! 10287: @c ?set y2tics
! 10288: @c ?set noy2tics
! 10289: @c ?show y2tics
! 10290: @cindex y2tics
! 10291: @opindex y2tics
! 10292:
! 10293:
! 10294: @cindex noy2tics
! 10295:
! 10296: The @ref{y2tics} command controls major (labelled) tics on the y2 (right-hand)
! 10297: axis. Please see @ref{xtics} for details.
! 10298:
! 10299: @node y2zeroaxis, ydata, y2tics, set-show
! 10300: @subsection y2zeroaxis
! 10301:
! 10302: @c ?commands set y2zeroaxis
! 10303: @c ?commands set noy2zeroaxis
! 10304: @c ?commands show y2zeroaxis
! 10305: @c ?set y2zeroaxis
! 10306: @c ?set noy2zeroaxis
! 10307: @c ?show y2zeroaxis
! 10308: @cindex y2zeroaxis
! 10309: @opindex y2zeroaxis
! 10310:
! 10311:
! 10312: @cindex noy2zeroaxis
! 10313:
! 10314: The @ref{y2zeroaxis} command draws a line at the origin of the y2 (right-hand)
! 10315: axis (x2 = 0). For details, please see @ref{zeroaxis}.
! 10316:
! 10317: @node ydata, ydtics, y2zeroaxis, set-show
! 10318: @subsection ydata
! 10319:
! 10320: @c ?commands set ydata
! 10321: @c ?commands show ydata
! 10322: @c ?set ydata
! 10323: @c ?show ydata
! 10324: @cindex ydata
! 10325: @opindex ydata
! 10326:
! 10327:
! 10328: Sets y-axis data to timeseries (dates/times). Please see @ref{xdata}.
! 10329:
! 10330: @node ydtics, ylabel, ydata, set-show
! 10331: @subsection ydtics
! 10332:
! 10333: @c ?commands set ydtics
! 10334: @c ?commands set noydtics
! 10335: @c ?commands show ydtics
! 10336: @c ?set ydtics
! 10337: @c ?set noydtics
! 10338: @c ?show ydtics
! 10339: @cindex ydtics
! 10340: @opindex ydtics
! 10341:
! 10342:
! 10343: @cindex noydtics
! 10344:
! 10345: The @ref{ydtics} command changes tics on the y axis to days of the week.
! 10346: Please see @ref{xdtics} for details.
! 10347:
! 10348: @node ylabel, ymtics, ydtics, set-show
! 10349: @subsection ylabel
! 10350:
! 10351: @c ?commands set ylabel
! 10352: @c ?commands show ylabel
! 10353: @c ?set ylabel
! 10354: @c ?show ylabel
! 10355: @cindex ylabel
! 10356: @opindex ylabel
! 10357:
! 10358:
! 10359: This command sets the label for the y axis. Please see @ref{xlabel}.
! 10360:
! 10361: @node ymtics, yrange, ylabel, set-show
! 10362: @subsection ymtics
! 10363:
! 10364: @c ?commands set ymtics
! 10365: @c ?commands set noymtics
! 10366: @c ?commands show ymtics
! 10367: @c ?set ymtics
! 10368: @c ?set noymtics
! 10369: @c ?show ymtics
! 10370: @cindex ymtics
! 10371: @opindex ymtics
! 10372:
! 10373:
! 10374: @cindex noymtics
! 10375:
! 10376: The @ref{ymtics} command changes tics on the y axis to months of the year.
! 10377: Please see @ref{xmtics} for details.
! 10378:
! 10379: @node yrange, ytics, ymtics, set-show
! 10380: @subsection yrange
! 10381:
! 10382: @c ?commands set yrange
! 10383: @c ?commands show yrange
! 10384: @c ?set yrange
! 10385: @c ?show yrange
! 10386: @cindex yrange
! 10387: @opindex yrange
! 10388:
! 10389:
! 10390: The @ref{yrange} command sets the vertical range that will be displayed on
! 10391: the y axis. Please see @ref{xrange} for details.
! 10392:
! 10393: @node ytics, yzeroaxis, yrange, set-show
! 10394: @subsection ytics
! 10395:
! 10396: @c ?commands set ytics
! 10397: @c ?commands set noytics
! 10398: @c ?commands show ytics
! 10399: @c ?set ytics
! 10400: @c ?set noytics
! 10401: @c ?show ytics
! 10402: @cindex ytics
! 10403: @opindex ytics
! 10404:
! 10405:
! 10406: @cindex noytics
! 10407:
! 10408: The @ref{ytics} command controls major (labelled) tics on the y axis.
! 10409: Please see @ref{xtics} for details.
! 10410:
! 10411: @node yzeroaxis, zdata, ytics, set-show
! 10412: @subsection yzeroaxis
! 10413:
! 10414: @c ?commands set yzeroaxis
! 10415: @c ?commands set noyzeroaxis
! 10416: @c ?commands show yzeroaxis
! 10417: @c ?set yzeroaxis
! 10418: @c ?set noyzeroaxis
! 10419: @c ?show yzeroaxis
! 10420: @cindex yzeroaxis
! 10421: @opindex yzeroaxis
! 10422:
! 10423:
! 10424: @cindex noyzeroaxis
! 10425:
! 10426: The @ref{yzeroaxis} command draws a line at x = 0. For details, please see
! 10427: @ref{zeroaxis}.
! 10428:
! 10429: @node zdata, zdtics, yzeroaxis, set-show
! 10430: @subsection zdata
! 10431:
! 10432: @c ?commands set zdata
! 10433: @c ?commands show zdata
! 10434: @c ?set zdata
! 10435: @c ?show zdata
! 10436: @cindex zdata
! 10437: @opindex zdata
! 10438:
! 10439:
! 10440: Set zaxis date to timeseries (dates/times). Please see @ref{xdata}.
! 10441:
! 10442: @node zdtics, zero, zdata, set-show
! 10443: @subsection zdtics
! 10444:
! 10445: @c ?commands set zdtics
! 10446: @c ?commands set nozdtics
! 10447: @c ?commands show zdtics
! 10448: @c ?set zdtics
! 10449: @c ?set nozdtics
! 10450: @c ?show zdtics
! 10451: @cindex zdtics
! 10452: @opindex zdtics
! 10453:
! 10454:
! 10455: @cindex nozdtics
! 10456:
! 10457: The @ref{zdtics} command changes tics on the z axis to days of the week.
! 10458: Please see @ref{xdtics} for details.
! 10459:
! 10460: @node zero, zeroaxis, zdtics, set-show
! 10461: @subsection zero
! 10462:
! 10463: @c ?commands set zero
! 10464: @c ?commands show zero
! 10465: @c ?set zero
! 10466: @c ?show zero
! 10467: @cindex zero
! 10468: @opindex zero
! 10469:
! 10470:
! 10471: The `zero` value is the default threshold for values approaching 0.0.
! 10472:
! 10473: Syntax:
! 10474: @example
! 10475: set zero <expression>
! 10476: show zero
! 10477:
! 10478: @end example
! 10479:
! 10480: `gnuplot` will not plot a point if its imaginary part is greater in magnitude
! 10481: than the `zero` threshold. This threshold is also used in various other
! 10482: parts of `gnuplot` as a (crude) numerical-error threshold. The default
! 10483: `zero` value is 1e-8. `zero` values larger than 1e-3 (the reciprocal of the
! 10484: number of pixels in a typical bitmap display) should probably be avoided, but
! 10485: it is not unreasonable to set `zero` to 0.0.
! 10486:
! 10487: @node zeroaxis, zlabel, zero, set-show
! 10488: @subsection zeroaxis
! 10489:
! 10490: @c ?commands set zeroaxis
! 10491: @c ?commands set nozeroaxis
! 10492: @c ?commands show zeroaxis
! 10493: @c ?set zeroaxis
! 10494: @c ?set nozeroaxis
! 10495: @c ?show zeroaxis
! 10496: @cindex zeroaxis
! 10497: @opindex zeroaxis
! 10498:
! 10499:
! 10500: @cindex nozeroaxis
! 10501:
! 10502: The x axis may be drawn by @ref{xzeroaxis} and removed by `set noxzeroaxis`.
! 10503: Similar commands behave similarly for the y, x2, and y2 axes.
! 10504:
! 10505: Syntax:
! 10506: @example
! 10507: set @{x|x2|y|y2|@}zeroaxis @{ @{linestyle | ls <line_style>@}
! 10508: | @{ linetype | lt <line_type>@}
! 10509: @{ linewidth | lw <line_width>@}@}
! 10510: set no@{x|x2|y|y2|@}zeroaxis
! 10511: show @{x|y|@}zeroaxis
! 10512:
! 10513: @end example
! 10514:
! 10515:
! 10516: By default, these options are off. The selected zero axis is drawn
! 10517: with a line of type <line_type> and width <line_width> (if supported
! 10518: by the terminal driver currently in use), or a user-defined style
! 10519: <line_style>.
! 10520:
! 10521: If no linetype is specified, any zero axes selected will be drawn
! 10522: using the axis linetype (linetype 0).
! 10523:
! 10524: `set zeroaxis l` is equivalent to `set xzeroaxis l; set yzeroaxis l`. `set
! 10525: nozeroaxis` is equivalent to `set noxzeroaxis; set noyzeroaxis`.
! 10526:
! 10527: @node zlabel, zmtics, zeroaxis, set-show
! 10528: @subsection zlabel
! 10529:
! 10530: @c ?commands set zlabel
! 10531: @c ?commands show zlabel
! 10532: @c ?set zlabel
! 10533: @c ?show zlabel
! 10534: @cindex zlabel
! 10535: @opindex zlabel
! 10536:
! 10537:
! 10538: This command sets the label for the z axis. Please see @ref{xlabel}.
! 10539:
! 10540: @node zmtics, zrange, zlabel, set-show
! 10541: @subsection zmtics
! 10542:
! 10543: @c ?commands set zmtics
! 10544: @c ?commands set nozmtics
! 10545: @c ?commands show zmtics
! 10546: @c ?set zmtics
! 10547: @c ?set nozmtics
! 10548: @c ?show zmtics
! 10549: @cindex zmtics
! 10550: @opindex zmtics
! 10551:
! 10552:
! 10553: @cindex nozmtics
! 10554:
! 10555: The @ref{zmtics} command changes tics on the z axis to months of the year.
! 10556: Please see @ref{xmtics} for details.
! 10557:
! 10558: @node zrange, ztics, zmtics, set-show
! 10559: @subsection zrange
! 10560:
! 10561: @c ?commands set zrange
! 10562: @c ?commands show zrange
! 10563: @c ?set zrange
! 10564: @c ?show zrange
! 10565: @cindex zrange
! 10566: @opindex zrange
! 10567:
! 10568:
! 10569: The @ref{zrange} command sets the range that will be displayed on the z axis.
! 10570: The zrange is used only by `splot` and is ignored by @ref{plot}. Please see @ref{xrange} for details.
! 10571:
! 10572: @node ztics, , zrange, set-show
! 10573: @subsection ztics
! 10574:
! 10575: @c ?commands set ztics
! 10576: @c ?commands set noztics
! 10577: @c ?commands show ztics
! 10578: @c ?set ztics
! 10579: @c ?set noztics
! 10580: @c ?show ztics
! 10581: @cindex ztics
! 10582: @opindex ztics
! 10583:
! 10584:
! 10585: @cindex noztics
! 10586:
! 10587: The @ref{ztics} command controls major (labelled) tics on the z axis.
! 10588: Please see @ref{xtics} for details.
! 10589:
! 10590: @node shell, splot, set-show, Commands
! 10591: @section shell
! 10592:
! 10593: @c ?commands shell
! 10594: @cindex shell
! 10595: @cmindex shell
! 10596:
! 10597:
! 10598: The @ref{shell} command spawns an interactive shell. To return to `gnuplot`,
! 10599: type `logout` if using VMS, @ref{exit} or the END-OF-FILE character if using
! 10600: Unix, `endcli` if using AmigaOS, or @ref{exit} if using MS-DOS or OS/2.
! 10601:
! 10602: A single shell command may be spawned by preceding it with the ! character
! 10603: ($ if using VMS) at the beginning of a command line. Control will return
! 10604: immediately to `gnuplot` after this command is executed. For example, in
! 10605: Unix, AmigaOS, MS-DOS or OS/2,
! 10606:
! 10607: @example
! 10608: ! dir
! 10609:
! 10610: @end example
! 10611:
! 10612: prints a directory listing and then returns to `gnuplot`.
! 10613:
! 10614: On an Atari, the `!` command first checks whether a shell is already loaded
! 10615: and uses it, if available. This is practical if `gnuplot` is run from
! 10616: `gulam`, for example.
! 10617:
! 10618: @node splot, test, shell, Commands
! 10619: @section splot
! 10620:
! 10621: @c ?commands splot
! 10622: @cindex splot
! 10623: @cmindex splot
! 10624:
! 10625:
! 10626: `splot` is the command for drawing 3-d plots (well, actually projections on
! 10627: a 2-d surface, but you knew that). It can create a plot from functions or
! 10628: a data file in a manner very similar to the @ref{plot} command.
! 10629:
! 10630: See @ref{plot} for features common to the @ref{plot} command; only differences are
! 10631: discussed in detail here. Note specifically that the @ref{binary} and @ref{matrix}
! 10632: options (discussed under "datafile-modifiers") are not available for @ref{plot}.
! 10633:
! 10634: Syntax:
! 10635: @example
! 10636: splot @{<ranges>@}
! 10637: <function> | "<datafile>" @{datafile-modifiers@}@}
! 10638: @{<title-spec>@} @{with <style>@}
! 10639: @{, @{definitions,@} <function> ...@}
! 10640:
! 10641: @end example
! 10642:
! 10643: where either a <function> or the name of a data file enclosed in quotes is
! 10644: supplied. The function can be a mathematical expression, or a triple of
! 10645: mathematical expressions in parametric mode.
! 10646:
! 10647: By default `splot` draws the xy plane completely below the plotted data.
! 10648: The offset between the lowest ztic and the xy plane can be changed by @ref{ticslevel}. The orientation of a `splot` projection is controlled by
! 10649: @ref{view}. See @ref{view} and @ref{ticslevel} for more information.
! 10650:
! 10651: The syntax for setting ranges on the `splot` command is the same as for
! 10652: @ref{plot}. In non-parametric mode, the order in which ranges must be given is
! 10653: @ref{xrange}, @ref{yrange}, and @ref{zrange}. In parametric mode, the order is @ref{urange},
! 10654: @ref{vrange}, @ref{xrange}, @ref{yrange}, and @ref{zrange}.
! 10655:
! 10656: The `title` option is the same as in @ref{plot}. The operation of @ref{with} is also
! 10657: the same as in @ref{plot}, except that the plotting styles available to `splot`
! 10658: are limited to `lines`, `points`, @ref{linespoints}, @ref{dots}, and @ref{impulses}; the
! 10659: error-bar capabilities of @ref{plot} are not available for `splot`.
! 10660:
! 10661: The datafile options have more differences.
! 10662:
! 10663: @menu
! 10664: * data-file_::
! 10665: * grid_data::
! 10666: * splot_overview::
! 10667: @end menu
! 10668:
! 10669: @node data-file_, grid_data, splot, splot
! 10670: @subsection data-file
! 10671:
! 10672: @c ?commands splot datafile
! 10673: @c ?splot datafile
! 10674: @c ?splot data-file
! 10675: As for @ref{plot}, discrete data contained in a file can be displayed by
! 10676: specifying the name of the data file, enclosed in quotes, on the `splot`
! 10677: command line.
! 10678:
! 10679: Syntax:
! 10680: @example
! 10681: splot '<file_name>' @{binary | matrix@}
! 10682: @{index <index list>@}
! 10683: @{every <every list>@}
! 10684: @{using <using list>@}
! 10685:
! 10686: @end example
! 10687:
! 10688: The special filenames `""` and `"-"` are permitted, as in @ref{plot}.
! 10689:
! 10690: In brief, @ref{binary} and @ref{matrix} indicate that the the data are in a special
! 10691: form, @ref{index} selects which data sets in a multi-data-set file are to be
! 10692: plotted, @ref{every} specifies which datalines (subsets) within a single data
! 10693: set are to be plotted, and @ref{using} determines how the columns within a single
! 10694: record are to be interpreted.
! 10695:
! 10696: The options @ref{index} and @ref{every} behave the same way as with @ref{plot}; @ref{using}
! 10697: does so also, except that the @ref{using} list must provide three entries
! 10698: instead of two.
! 10699:
! 10700: The @ref{plot} options @ref{thru} and @ref{smooth} are not available for `splot`, but
! 10701: `cntrparams` and @ref{dgrid3d} provide limited smoothing cabilities.
! 10702:
! 10703: Data file organization is essentially the same as for @ref{plot}, except that
! 10704: each point is an (x,y,z) triple. If only a single value is provided, it
! 10705: will be used for z, the datablock number will be used for y, and the index
! 10706: of the data point in the datablock will be used for x. If two values are
! 10707: provided, `gnuplot` gives you an error message. Three values are interpreted
! 10708: as an (x,y,z) triple. Additional values are generally used as errors, which
! 10709: can be used by `fit`.
! 10710:
! 10711: Single blank records separate datablocks in a `splot` datafile; `splot`
! 10712: treats datablocks as the equivalent of function y-isolines. No line will
! 10713: join points separated by a blank record. If all datablocks contain the same
! 10714: number of points, `gnuplot` will draw cross-isolines between datablocks,
! 10715: connecting corresponding points. This is termed "grid data", and is required
! 10716: for drawing a surface, for contouring (@ref{contour}) and hidden-line removal
! 10717: (@ref{hidden3d}). See also `splot grid data`
! 10718:
! 10719: It is no longer necessary to specify `parametric` mode for three-column
! 10720: `splot`s.
! 10721:
! 10722: @menu
! 10723: * binary::
! 10724: * example_datafile_::
! 10725: * matrix::
! 10726: @end menu
! 10727:
! 10728: @node binary, example_datafile_, data-file_, data-file_
! 10729: @subsubsection binary
! 10730:
! 10731: @c ?commands splot datafile binary
! 10732: @c ?splot datafile binary
! 10733: @c ?splot binary
! 10734: @c ?data-file binary
! 10735: @c ?datafile binary
! 10736: @cindex binary
! 10737:
! 10738: @c ?binary data
! 10739: @c ?binary files
! 10740: `splot` can read binary files written with a specific format (and on a
! 10741: system with a compatible binary file representation.)
! 10742:
! 10743: In previous versions, `gnuplot` dynamically detected binary data files. It
! 10744: is now necessary to specify the keyword @ref{binary} directly after the filename.
! 10745:
! 10746: Single precision floats are stored in a binary file as follows:
! 10747:
! 10748: @example
! 10749: <N+1> <y0> <y1> <y2> ... <yN>
! 10750: <x0> <z0,0> <z0,1> <z0,2> ... <z0,N>
! 10751: <x1> <z1,0> <z1,1> <z1,2> ... <z1,N>
! 10752: : : : : ... :
! 10753:
! 10754: @end example
! 10755:
! 10756: which are converted into triplets:
! 10757: @example
! 10758: <x0> <y0> <z0,0>
! 10759: <x0> <y1> <z0,1>
! 10760: <x0> <y2> <z0,2>
! 10761: : : :
! 10762: <x0> <yN> <z0,N>
! 10763:
! 10764: @end example
! 10765:
! 10766: @example
! 10767: <x1> <y0> <z1,0>
! 10768: <x1> <y1> <z1,1>
! 10769: : : :
! 10770:
! 10771: @end example
! 10772:
! 10773: These triplets are then converted into `gnuplot` iso-curves and then
! 10774: `gnuplot` proceeds in the usual manner to do the rest of the plotting.
! 10775:
! 10776: A collection of matrix and vector manipulation routines (in C) is provided
! 10777: in `binary.c`. The routine to write binary data is
! 10778:
! 10779: @example
! 10780: int fwrite_matrix(file,m,nrl,nrl,ncl,nch,row_title,column_title)
! 10781:
! 10782: @end example
! 10783:
! 10784: An example of using these routines is provided in the file `bf_test.c`, which
! 10785: generates binary files for the demo file `demo/binary.dem`.
! 10786:
! 10787: The @ref{index} keyword is not supported, since the file format allows only one
! 10788: surface per file. The @ref{every} and @ref{using} filters are supported. @ref{using}
! 10789: operates as if the data were read in the above triplet form.
! 10790: @uref{http://www.gnuplot.vt.edu/gnuplot/gpdocs/binary.html,Binary File Splot Demo.}
! 10791:
! 10792: @node example_datafile_, matrix, binary, data-file_
! 10793: @subsubsection example datafile
! 10794:
! 10795: @c ?commands splot datafile example
! 10796: @c ?splot datafile example
! 10797: @c ?splot example
! 10798: A simple example of plotting a 3-d data file is
! 10799:
! 10800: @example
! 10801: splot 'datafile.dat'
! 10802:
! 10803: @end example
! 10804:
! 10805: where the file "datafile.dat" might contain:
! 10806:
! 10807: @example
! 10808: # The valley of the Gnu.
! 10809: 0 0 10
! 10810: 0 1 10
! 10811: 0 2 10
! 10812:
! 10813: @end example
! 10814:
! 10815: @example
! 10816: 1 0 10
! 10817: 1 1 5
! 10818: 1 2 10
! 10819:
! 10820: @end example
! 10821:
! 10822: @example
! 10823: 2 0 10
! 10824: 2 1 1
! 10825: 2 2 10
! 10826:
! 10827: @end example
! 10828:
! 10829: @example
! 10830: 3 0 10
! 10831: 3 1 0
! 10832: 3 2 10
! 10833:
! 10834: @end example
! 10835:
! 10836: Note that "datafile.dat" defines a 4 by 3 grid ( 4 rows of 3 points each ).
! 10837: Rows (datablocks) are separated by blank records.
! 10838:
! 10839: @c ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/splot.gif" alt="[splot.gif]" width=640 height=480>
! 10840: Note also that the x value is held constant within each dataline. If you
! 10841: instead keep y constant, and plot with hidden-line removal enabled, you will
! 10842: find that the surface is drawn 'inside-out'.
! 10843:
! 10844: Actually for grid data it is not necessary to keep the x values constant
! 10845: within a datablock, nor is it necessary to keep the same sequence of y
! 10846: values. `gnuplot` requires only that the number of points be the same for
! 10847: each datablock. However since the surface mesh, from which contours are
! 10848: derived, connects sequentially corresponding points, the effect of an
! 10849: irregular grid on a surface plot is unpredictable and should be examined
! 10850: on a case-by-case basis.
! 10851:
! 10852: @node matrix, , example_datafile_, data-file_
! 10853: @subsubsection matrix
! 10854:
! 10855: @c ?commands splot datafile matrix
! 10856: @c ?splot datafile matrix
! 10857: @c ?splot matrix
! 10858: @c ?data-file matrix
! 10859: @c ?datafile matrix
! 10860: @cindex matrix
! 10861:
! 10862: The @ref{matrix} flag indicates that the ASCII data are stored in matrix format.
! 10863: The z-values are read in a row at a time, i. e.,
! 10864: @example
! 10865: z11 z12 z13 z14 ...
! 10866: z21 z22 z23 z24 ...
! 10867: z31 z32 z33 z34 ...
! 10868: @end example
! 10869:
! 10870: and so forth. The row and column indices are used for the x- and y-values.
! 10871:
! 10872: @node grid_data, splot_overview, data-file_, splot
! 10873: @subsection grid_data
! 10874:
! 10875: @c ?commands splot grid_data
! 10876: @c ?splot grid_data
! 10877: @cindex grid_data
! 10878:
! 10879: The 3D routines are designed for points in a grid format, with one sample,
! 10880: datapoint, at each mesh intersection; the datapoints may originate from
! 10881: either evaluating a function, see @ref{isosamples}, or reading a datafile,
! 10882: see `splot datafile`. The term "isoline" is applied to the mesh lines for
! 10883: both functions and data. Note that the mesh need not be rectangular in x
! 10884: and y, as it may be parameterized in u and v, see @ref{isosamples}.
! 10885:
! 10886: However, `gnuplot` does not require that format. In the case of functions,
! 10887: 'samples' need not be equal to 'isosamples', i.e., not every x-isoline
! 10888: sample need intersect a y-isoline. In the case of data files, if there
! 10889: are an equal number of scattered data points in each datablock, then
! 10890: "isolines" will connect the points in a datablock, and "cross-isolines"
! 10891: will connect the corresponding points in each datablock to generate a
! 10892: "surface". In either case, contour and hidden3d modes may give different
! 10893: plots than if the points were in the intended format. Scattered data can be
! 10894: converted to a @{different@} grid format with @ref{dgrid3d}.
! 10895:
! 10896: The contour code tests for z intensity along a line between a point on a
! 10897: y-isoline and the corresponding point in the next y-isoline. Thus a `splot`
! 10898: contour of a surface with samples on the x-isolines that do not coincide with
! 10899: a y-isoline intersection will ignore such samples. Try:
! 10900: @example
! 10901: set xrange [-pi/2:pi/2]; set yrange [-pi/2:pi/2]
! 10902: set function style lp
! 10903: set contour
! 10904: set isosamples 10,10; set samples 10,10;
! 10905: splot cos(x)*cos(y)
! 10906: set samples 4,10; replot
! 10907: set samples 10,4; replot
! 10908:
! 10909: @end example
! 10910:
! 10911:
! 10912: @node splot_overview, , grid_data, splot
! 10913: @subsection splot_overview
! 10914:
! 10915: @c ?commands splot_overview
! 10916: @c ? splot_overview
! 10917: `splot` can display a surface as a collection of points, or by connecting
! 10918: those points. As with @ref{plot}, the points may be read from a data file or
! 10919: result from evaluation of a function at specified intervals, see @ref{isosamples}. The surface may be approximated by connecting the points
! 10920: with straight line segments, see @ref{surface}, in which case the surface
! 10921: can be made opaque with `set hidden3d.` The orientation from which the 3d
! 10922: surface is viewed can be changed with @ref{view}.
! 10923:
! 10924: Additionally, for points in a grid format, `splot` can interpolate points
! 10925: having a common amplitude (see @ref{contour}) and can then connect those
! 10926: new points to display contour lines, either directly with straight-line
! 10927: segments or smoothed lines (see `set cntrparams`). Functions are already
! 10928: evaluated in a grid format, determined by @ref{isosamples} and @ref{samples},
! 10929: while file data must either be in a grid format, as described in `data-file`,
! 10930: or be used to generate a grid (see @ref{dgrid3d}).
! 10931:
! 10932: Contour lines may be displayed either on the surface or projected onto the
! 10933: base. The base projections of the contour lines may be written to a
! 10934: file, and then read with @ref{plot}, to take advantage of @ref{plot}'s additional
! 10935: formatting capabilities.
! 10936:
! 10937: @node test, update, splot, Commands
! 10938: @section test
! 10939:
! 10940: @c ?commands test
! 10941: @cindex test
! 10942: @cmindex test
! 10943:
! 10944:
! 10945: @ref{test} creates a display of line and point styles and other useful things
! 10946: appropriate for the terminal you are using.
! 10947:
! 10948: Syntax:
! 10949: @example
! 10950: test
! 10951:
! 10952: @end example
! 10953:
! 10954: @node update, , test, Commands
! 10955: @section update
! 10956:
! 10957: @c ?commands update
! 10958: @cindex update
! 10959: @cmindex update
! 10960:
! 10961:
! 10962: This command writes the current values of the fit parameters into the given
! 10963: file, formatted as an initial-value file (as described in the `fit`section).
! 10964: This is useful for saving the current values for later use or for restarting
! 10965: a converged or stopped fit.
! 10966:
! 10967: Syntax:
! 10968: @example
! 10969: update <filename> @{<filename>@}
! 10970:
! 10971: @end example
! 10972:
! 10973: If a second filename is supplied, the updated values are written to this
! 10974: file, and the original parameter file is left unmodified.
! 10975:
! 10976: Otherwise, if the file already exists, `gnuplot` first renames it by
! 10977: appending `.old` and then opens a new file. That is, "`update 'fred'`"
! 10978: behaves the same as "`!rename fred fred.old; update 'fred.old' 'fred'`".
! 10979: [On DOS and other systems that use the twelve-character "filename.ext"
! 10980: naming convention, "ext" will be "`old`" and "filename" will be related
! 10981: (hopefully recognizably) to the initial name. Renaming is not done at all
! 10982: on VMS systems, since they use file-versioning.]
! 10983:
! 10984: Please see `fit` for more information.
! 10985:
! 10986: @node Graphical_User_Interfaces, Bugs, Commands, Top
! 10987: @chapter Graphical User Interfaces
! 10988:
! 10989: @c ?graphical user interfaces
! 10990: @cindex gui's
! 10991:
! 10992: Several graphical user interfaces have been written for `gnuplot` and one for
! 10993: win32 is included in this distribution. In addition, there is a Macintosh
! 10994: interface at
! 10995: @uref{ftp://ftp.ee.gatech.edu/pub/mac/gnuplot,ftp://ftp.ee.gatech.edu/pub/mac/gnuplot
! 10996: }
! 10997: and several X11 interfaces include three Tcl/Tk located at the usual Tcl/Tk
! 10998: repositories.
! 10999:
! 11000: @node Bugs, Concept_Index, Graphical_User_Interfaces, Top
! 11001: @chapter Bugs
! 11002:
! 11003: @cindex bugs
! 11004:
! 11005: Floating point exceptions (floating point number too large/small, divide by
! 11006: zero, etc.) may occasionally be generated by user defined functions. Some of
! 11007: the demos in particular may cause numbers to exceed the floating point range.
! 11008: Whether the system ignores such exceptions (in which case `gnuplot` labels
! 11009: the corresponding point as undefined) or aborts `gnuplot` depends on the
! 11010: compiler/runtime environment.
! 11011:
! 11012: The bessel functions do not work for complex arguments.
! 11013:
! 11014: The gamma function does not work for complex arguments.
! 11015:
! 11016: As of `gnuplot` version 3.7, all development has been done using ANSI C.
! 11017: With current operating system, compiler, and library releases, the OS
! 11018: specific bugs documented in release 3.5, now relegated to `old_bugs`, may
! 11019: no longer be relevant.
! 11020:
! 11021: Bugs reported since the current release may be located via the official
! 11022: distribution site:
! 11023: @example
! 11024: ftp://ftp.dartmouth.edu/pub/gnuplot
! 11025: http://www.cs.dartmouth.edu/gnuplot_info.html
! 11026:
! 11027: @end example
! 11028:
! 11029: Please e-mail any bugs to bug-gnuplot@@dartmouth.edu.
! 11030:
! 11031: @menu
! 11032: * Old_bugs::
! 11033: @end menu
! 11034:
! 11035: @node Old_bugs, , Bugs, Bugs
! 11036: @section Old_bugs
! 11037:
! 11038: @cindex old_bugs
! 11039:
! 11040: @cindex os_bugs
! 11041:
! 11042: There is a bug in the stdio library for old Sun operating systems (SunOS
! 11043: Sys4-3.2). The "%g" format for 'printf' sometimes incorrectly prints numbers
! 11044: (e.g., 200000.0 as "2"). Thus, tic mark labels may be incorrect on a Sun4
! 11045: version of `gnuplot`. A work-around is to rescale the data or use the `set
! 11046: format` command to change the tic mark format to "%7.0f" or some other
! 11047: appropriate format. This appears to have been fixed in SunOS 4.0.
! 11048:
! 11049: Another bug: On a Sun3 under SunOS 4.0, and on Sun4's under Sys4-3.2 and
! 11050: SunOS 4.0, the 'sscanf' routine incorrectly parses "00 12" with the format
! 11051: "%f %f" and reads 0 and 0 instead of 0 and 12. This affects data input. If
! 11052: the data file contains x coordinates that are zero but are specified like
! 11053: '00', '000', etc, then you will read the wrong y values. Check any data
! 11054: files or upgrade the SunOS. It appears to have been fixed in SunOS 4.1.1.
! 11055:
! 11056: Suns appear to overflow when calculating exp(-x) for large x, so `gnuplot`
! 11057: gets an undefined result. One work-around is to make a user-defined function
! 11058: like e(x) = x<-500 ? 0 : exp(x). This affects plots of Gaussians (exp(-x*x))
! 11059: in particular, since x*x grows quite rapidly.
! 11060:
! 11061: Microsoft C 5.1 has a nasty bug associated with the %g format for 'printf'.
! 11062: When any of the formats "%.2g", "%.1g", "%.0g", "%.g" are used, 'printf' will
! 11063: incorrectly print numbers in the range 1e-4 to 1e-1. Numbers that should be
! 11064: printed in the %e format are incorrectly printed in the %f format, with the
! 11065: wrong number of zeros after the decimal point. To work around this problem,
! 11066: use the %e or %f formats explicitly.
! 11067:
! 11068: `gnuplot`, when compiled with Microsoft C, did not work correctly on two VGA
! 11069: displays that were tested. The CGA, EGA and VGA drivers should probably be
! 11070: rewritten to use the Microsoft C graphics library. `gnuplot` compiled with
! 11071: Borland C++ uses the Turbo C graphics drivers and does work correctly with
! 11072: VGA displays.
! 11073:
! 11074: VAX/VMS 4.7 C compiler release 2.4 also has a poorly implemented %g format
! 11075: for 'printf'. The numbers are printed numerically correct, but may not be in
! 11076: the requested format. The K&R second edition says that for the %g format, %e
! 11077: is used if the exponent is less than -4 or greater than or equal to the
! 11078: precision. The VAX uses %e format if the exponent is less than -1. The VAX
! 11079: appears to take no notice of the precision when deciding whether to use %e or
! 11080: %f for numbers less than 1. To work around this problem, use the %e or %f
! 11081: formats explicitly. From the VAX C 2.4 release notes: e,E,f,F,g,G Result
! 11082: will always contain a decimal point. For g and G, trailing zeros will not
! 11083: be removed from the result.
! 11084:
! 11085: VAX/VMS 5.2 C compiler release 3.0 has a slightly better implemented %g
! 11086: format than release 2.4, but not much. Trailing decimal points are now
! 11087: removed, but trailing zeros are still not removed from %g numbers in
! 11088: exponential format.
! 11089:
! 11090: The two preceding problems are actually in the libraries rather than in the
! 11091: compilers. Thus the problems will occur whether `gnuplot` is built using
! 11092: either the DEC compiler or some other one (e.g. the latest gcc).
! 11093:
! 11094: ULTRIX X11R3 has a bug that causes the X11 driver to display "every other"
! 11095: graph. The bug seems to be fixed in DEC's release of X11R4 so newer releases
! 11096: of ULTRIX don't seem to have the problem. Solutions for older sites include
! 11097: upgrading the X11 libraries (from DEC or direct from MIT) or defining
! 11098: ULTRIX_KLUDGE when compiling the x11.trm file. Note that the kludge is not
! 11099: an ideal fix, however.
! 11100:
! 11101: The constant HUGE was incorrectly defined in the NeXT OS 2.0 operating
! 11102: system. HUGE should be set to 1e38 in plot.h. This error has been corrected
! 11103: in the 2.1 version of NeXT OS.
! 11104:
! 11105: Some older models of HP plotters do not have a page eject command 'PG'. The
! 11106: current HPGL driver uses this command in HPGL_reset. This may need to be
! 11107: removed for these plotters. The current PCL5 driver uses HPGL/2 for text as
! 11108: well as graphics. This should be modified to use scalable PCL fonts.
! 11109:
! 11110: On the Atari version, it is not possible to send output directly to the
! 11111: printer (using `/dev/lp` as output file), since CRs are added to LFs in
! 11112: binary output. As a work-around, write the output to a file and copy it to
! 11113: the printer afterwards using a shell command.
! 11114:
! 11115: On AIX 4, the literal 'NaNq' in a datafile causes the special internal value
! 11116: 'not-a-number' to be stored, rather than setting an internal 'undefined'
! 11117: flag. A workaround is to use `set missing 'NaNq'`.
! 11118:
! 11119: There may be an up-to-date list of bugs since the release on the WWW page:
! 11120: @example
! 11121: http://www.cs.dartmouth.edu/gnuplot_info.html
! 11122:
! 11123: @end example
! 11124:
! 11125: Please report any bugs to bug-gnuplot@@dartmouth.edu.
! 11126: @node Concept_Index, Command_Index, Bugs, Top
! 11127: @unnumbered Concept Index
! 11128: @printindex cp
! 11129:
! 11130: @node Command_Index, Options_Index, Concept_Index, Top
! 11131: @unnumbered Command Index
! 11132: @printindex cm
! 11133:
! 11134: @node Options_Index, Function_Index, Command_Index, Top
! 11135: @unnumbered Options Index
! 11136: @printindex op
! 11137:
! 11138: @node Function_Index, Terminal_Index, Options_Index, Top
! 11139: @unnumbered Function Index
! 11140: @printindex fn
! 11141:
! 11142: @node Terminal_Index, , Function_Index, Top
! 11143: @unnumbered Terminal Index
! 11144: @printindex tm
! 11145:
! 11146: @c @shortcontents
! 11147: @contents
! 11148: @bye
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gnuplot.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gnuplot / docs