-
Notifications
You must be signed in to change notification settings - Fork 99
Expand file tree
/
Copy pathgnuplot.doc
More file actions
18903 lines (16480 loc) · 799 KB
/
gnuplot.doc
File metadata and controls
18903 lines (16480 loc) · 799 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
C Copyright (C) 1986 - 1993, 1998, 1999, 2000, 2001, 2004 Thomas Williams, Colin Kelley et al.
C
1 Gnuplot
?gnuplot
^<h2 align="center"> An Interactive Plotting Program </h2>
^<p align="center"> Thomas Williams & Colin Kelley</p>
^<p align="center"> Version 6 organized by Ethan A Merritt</p>
^<p align="center">Major contributors (alphabetic order):<br>
^<br>
^ Hans-Bernhard Broeker, John Campbell,<br>
^ Robert Cunningham, David Denholm,<br>
^ Gershon Elber, Roger Fearick,<br>
^ Carsten Grammes, Lucas Hart, Lars Hecking,<br>
^ Péter Juhász, Thomas Koenig, David Kotz,<br>
^ Ed Kubaitis, Russell Lang, Timothée Lecomte,<br>
^ Alexander Lehmann, Alexander Mai, Bastian Märkisch,<br>
^ Tatsuro Matsuoka, Ethan A Merritt, Petr Mikulík,<br>
^ Hiroki Motoyoshi, Carsten Steger, Shigeharu Takeno,<br>
^ Tom Tkacik, Jos Van der Woude,<br>
^ James R. Van Zandt, Alex Woo, Johannes Zellner<br>
^</p>
^<p align="center"> Copyright (C) 1986 - 1993, 1998 - 2004 Thomas Williams, Colin Kelley<br>
^ Copyright (C) 2004 - 2023 various authors</p>
^<p align="center"> Mailing list for comments: <tt>[email protected]</tt><br>
^ Gnuplot <a href="http://gnuplot.info"> home page </a><br>
^ Issue trackers:
^<a href="https://sourceforge.net/p/gnuplot/bugs"> bugs </a>
^<a href="https://sourceforge.net/p/gnuplot/feature-requests"> feature requests </a>
^<p align="center"> This manual was originally prepared by Dick Crawford</p>
^<!-- end of titlepage -->
2 Copyright
?copyright
?license
Copyright (C) 1986 - 1993, 1998, 2004, 2007 Thomas Williams, Colin Kelley
Copyright (C) 2004-2023 various authors
Permission to use, copy, and distribute this software and its
documentation for any purpose with or without fee is hereby granted,
provided that the above copyright notice appear in all copies and
that both that copyright notice and this permission notice appear
in supporting documentation.
Permission to modify the software is granted, but not the right to
distribute the complete modified source code. Modifications are to
be distributed as patches to the released version. Permission to
distribute binaries produced by compiling modified sources is granted,
provided you
1. distribute the corresponding source modifications from the
released version in the form of a patch file along with the binaries,
2. add special version identification to distinguish your version
in addition to the base release version number,
3. provide your name and address as the primary contact for the
support of your modified version, and
4. retain our contact information in regard to use of the base software.
Permission to distribute the released version of the source code along
with corresponding source modifications in the form of a patch file is
granted with same provisions 2 through 4 for binary distributions.
This software is provided "as is" without express or implied warranty
to the extent permitted by applicable law.
AUTHORS
Original Software:
Thomas Williams, Colin Kelley.
Gnuplot 2.0 additions:
Russell Lang, Dave Kotz, John Campbell.
Gnuplot 3.0 additions:
Gershon Elber and many others.
Gnuplot 4.0 and subsequent releases:
See list of contributors at head of this document.
2 Introduction
?introduction
?
`Gnuplot` is a portable command-line driven graphing utility for Linux, OS/2,
MS Windows, macOS, and many other platforms. The source code is copyrighted
but freely distributed (i.e., you don't have to pay for it). It was originally
created to allow scientists and students to visualize mathematical functions
and data interactively, but has grown to support many non-interactive uses
such as web scripting. It is also used as a plotting engine by third-party
applications like Octave. Gnuplot has been supported and under active
development since 1986.
Gnuplot can generate many types of plot in 2D and 3D. It can draw using lines,
points, boxes, contours, vector fields, images, surfaces, and associated text.
It also supports specialized graphs such as heat maps, spider plots, polar
projection, histograms, boxplots, bee swarm plots, and nonlinear coordinates.
Gnuplot supports many different types of output: interactive screen terminals
(with mouse and hotkey input), direct output to pen plotters or modern
printers, and output to many file formats (eps, emf, fig, jpeg, LaTeX, pdf, png,
postscript, ...). Gnuplot is easily extensible to include new output modes.
A recent example is support for webp animation. Mouseable plots embedded in
web pages can be generated using the svg or HTML5 canvas terminal drivers.
The command language of `gnuplot` is case sensitive, i.e. commands and
function names written in lowercase are not the same as those written in
capitals. All command names may be abbreviated as long as the abbreviation is
not ambiguous. Any number of commands may appear on a line, separated by
semicolons (;). Strings may be set off by either single or double quotes,
although there are some subtle differences. See `syntax` and `quotes` for
more details. Example:
set title "My First Plot"; plot 'data'; print "all done!"
Commands may extend over several input lines by ending each line but the last
with a backslash (\). The backslash must be the _last_ character on each
line. The effect is as if the backslash and newline were not there. That
is, no white space is implied, nor is a comment terminated. Therefore,
commenting out a continued line comments out the entire command
(see `comments`). But note that if an error occurs somewhere on a multi-line
command, the parser may not be able to locate precisely where the error is
and in that case will not necessarily point to the correct line.
In this document, curly braces ({}) denote optional arguments and a vertical
bar (|) separates mutually exclusive choices. `Gnuplot` keywords or `help`
topics are indicated by backquotes or `boldface` (where available). Angle
brackets (<>) are used to mark replaceable tokens. In many cases, a default
value of the token will be taken for optional arguments if the token is
omitted, but these cases are not always denoted with braces around the angle
brackets.
For built-in help on any topic, type `help` followed by the name of the topic
or `help ?` to get a menu of available topics.
A large set of demo plots is available on the web page
^ <a href="http://www.gnuplot.info/demo/">
http://www.gnuplot.info/demo/
^ </a>
When run from command line, gnuplot is invoked using the syntax
gnuplot {OPTIONS} file1 file2 ...
where file1, file2, etc. are input files as in the `load` command.
Options interpreted by gnuplot may come anywhere on the line. Files are
executed in the order specified, as are commands supplied by the -e option,
for example
gnuplot file1.in -e "reset" file2.in
The special filename "-" is used to force reading from stdin. `Gnuplot` exits
after the last file is processed. If no load files are named, `Gnuplot` takes
interactive input from stdin. See help `batch/interactive` for more details.
See `command-line-options` for more details, or type
gnuplot --help
In sessions with an interactive plot window you can hit 'h' anywhere on the
plot for help about `hotkeys` and `mousing` features.
2 Seeking-assistance / Bugs
?help-desk
?faq
?FAQ
?bugs
?seeking-assistance
The canonical gnuplot home page can be found at
^ <a href="http://www.gnuplot.info">
http://www.gnuplot.info
^ </a>
Before seeking help, please check file FAQ.pdf or the above website for a
^ <a href="http://www.gnuplot.info/faq/">
FAQ (Frequently Asked Questions) list.
^ </a>
Another resource for help with specific plotting problems (not bugs) is
https://stackoverflow.com/questions/tagged/gnuplot
Bug reports and feature requests should be uploaded to the trackers at
https://sourceforge.net/p/gnuplot/_list/tickets
Please check previous reports to see if the bug you want to report has
already been fixed in a newer version.
When reporting a bug or posting a question, please include full details
of the gnuplot version, the terminal type, and the operating system.
A short self-contained script demonstrating the problem is very helpful.
Instructions for subscribing to gnuplot mailing lists may be
found via the gnuplot development website
^ <a href="http://sourceforge.net/projects/gnuplot">
http://sourceforge.net/projects/gnuplot
^ </a>
Please note that before you write to any of the gnuplot mailing lists you
must first subscribe to the list. This helps reduce the amount of spam.
The address for mailing to list members is:
A mailing list for those interested in the development version of gnuplot is:
2 New features in version 6
?new version_6
?new
?version
Version 6 is the latest major release in a history of gnuplot development
dating back to 1986. It follows major version 5 (2015) and subsequent
minor version releases 5.2 (2017) and 5.4 (2020). Development continues
in a separate unreleased branch in the project git repository on SourceForge.
Some features described in this document are present only if chosen and
configured at the time gnuplot is compiled from source. To determine what
configuration options were used to build the particular copy of gnuplot you
are running, type `show version long`.
3 Function blocks and scoped variables
?new function blocks
This version of gnuplot introduces a mechanism for invoking a block of
standard gnuplot commands as a callable function. A function block can
accept from 0 to 9 parameters and returns a value. Function blocks can be
used to calculate and assign a new value to a variable, to combine with other
functions and operators, or to perform a repetitive task preparing data.
There are three components to this mechanism.
See `local`, `scope`, `function blocks`, `return`.
#start
#b The `local` qualifier allows optional declaration of a variable or array
## whose scope is limited to the duration of execution of the program unit in
## which it is found. These units currently include execution of a
## `load` or `call` statement, function block evaluation, and the code block
## in curly brackets following an `if`, `else`, `do for`, or `while` statement.
## If the name of a local variable duplicates the name of a global variable,
## the global variable is shadowed until exit from the local scope.
#b The `function` command declares a named function block (effectively an
## array of strings) containing gnuplot commands. When the function block
## is invoked, commands are executed successively until the end of the block
## or until a `return` command is encountered.
#b The `return <expression>` command terminates execution of a function block.
## The result of evaluating <expression> is returned as the value of the
## function. Anywhere outside a function block `return` acts like `exit`.
#end
Please see `function_block.dem` for an example of using this mechanism
to define and plot a non-trivial function that is too complicated for a
simple one-line definition `f(x) = ...`.
3 Special and complex-valued functions
?new math
Gnuplot 6 provides an expanded set of complex-valued functions and updated
versions of some functions that were present in earlier versions.
#start
#b New: Riemann zeta function with complex domain and range. See `zeta`.
#b Updated lower incomplete gamma function with improved domain and precision.
## Complex arguments accepted.
## See `igamma`.
#b New upper incomplete gamma function (real arguments only).
## See `uigamma`.
#b Updated incomplete beta function with improved domain and precision.
## See `ibeta`.
#b New function for the inverse incomplete gamma function.
## See `invigamma`.
#b New function for the inverse incomplete beta function.
## See `invibeta`.
#b New complex function LambertW(z,k) returns the kth branch of multivalued
## function W_k(z).
^<br>
## Note that the older function lambertw(x) = real(LambertW( real(z), 0 )).
## See `LambertW`.
#b New complex function lnGamma(z).
## Note that existing function lgamma(x) = real(lnGamma(real(z)).
## See `lnGamma`.
#b Complex function conj(z) returns the complex conjugate of z.
#b Synchrotron function F(x), see `SynchrotronF`.
#b acosh(z) domain extended to cover negative real axis.
#b asin(z) asinh(z) improved precision for complex arguments.
#b Predefined variable I = sqrt(-1) = {0,1} for convenience.
^<br>
## This is useful because gnuplot does not accept {a,b} as a valid complex
## constant but does accept (a + b*I) as a valid complex expression.
#end
Additional special functions are supported if a suitable external
library is found at build time. See `special_functions`.
#start
#b Complex Bessel functions Iν(z), Jν(z), Kν(z), Yν(z) of order ν (real)
## with complex argument z. See `BesselK`.
#b Complex Hankel functions H1ν(z), H2ν(z) of order ν with complex z.
## See `BesselH1`.
#b Complex Airy functions Ai(z), Bi(z).
#b Complex exponential integral of order n. See `expint`.
#b Fresnel integrals C(x) and S(x). See `FresnelC`.
#b Function `VP_fwhm(sigma,gamma)` returns the full width at half maximum
## of the Voigt profile. See `VP`, `VP_fwhm`.
#end
3 New plot styles
?new styles
#start
#b The plot style `with surface` works in 2D polar coordinates to produce
## a solid-fill gridded representation of the plane, colored by weighted
## contributions from an arbitrary set of input points. This is analogous to
## the use of `dgrid3d` and style `with pm3d` to produce a 3D gridded surface.
## See `set polar grid` and `polar heatmap`.
#b New 2D plot style `with sectors` is an alternative to generating a full
## polar gridded surface. For each input data point it generates a single
## annular wedge in a conceptual polar grid. Unlike polar mode `with surface`
## it can be used in either a polar or cartesian coordinate graph.
#b New 2D plot style `with hsteps` allows construction of step-like plots with
## a variety of representations in addition to those offered by existing styles
## `steps`, `histeps`, `fsteps`, and `fillsteps`. See `hsteps`.
#b Plot style `with lines` now has a filter option `sharpen`. This filter
## detects spikes in a function plot that appear truncated in the output
## because the peak lies between two x-coordinates at which the function has
## been sampled. It adds a new sample point at the location of each such peak.
## See `filters`.
#b Although it is not strictly speaking a new plot style, the combination
## of the concave hull filter with along-path smoothing of filled areas
## allows creation of 'blobby region' plots showing, for example,
## the extents of overlapping data clusters. See `concavehull`.
#b 3D plot style `with pm3d` accepts an optional modifier `zclip [zmin:zmax]`
## that selects only a slice of the full surface. Successive plots with
## incremental changes to the clipping limits can be used to animate a
## cross-sectional cutaway view in 3D or to create a filled area contour map.
## This is automated by a new plot style `with contourfill`, that is
## particularly useful in 2D projection. See `set contourfill`.
#end
D polargrid 4
DB
D windrose 1
D sectors 4
DB
D sharpen 1
D iris 2
DB
D contourfill 4
DB
D logic_timing 1
D rank_sequence 1
3 Hulls, masks, and smoothing
?new hulls
#start
#b A cluster of 2D points can be replaced by its bounding polygon using the
## new filter `convexhull`. A path-smoothed bounding curve can be plotted
## as a filled area using "convexhull smooth path with filledcurves".
## See `convexhull`.
#b An alternative experimental filter `concavehull` generates a bounding
## polygon that is not necessarily convex; instead it forms a χ-shape
## determined by a characteristic length parameter that controls the degree
## of concavity. This essentially draws a blob around the data points.
## See `concavehull`.
#b A convex hull or other polygon can be used as a mask to display only
## selected portions of a pm3d surface or an image plot.
## See new plot style `with mask` (defines a mask) and keyword `mask`
## (applies the mask to a subsequent plot component).
#b curve smoothing using along-path cubic splines suitable for closed curves
## or for 2D curves that are not monotonic on x. See `smooth path`.
## This allows smoothing of hulls and masks.
#b cubic spline smoothing of 3D lines. See `splot smooth csplines`
#b Smoothing options apply to plotting `with filledcurves` {above|below|between}.
#b New keyword `period` for smoothing periodic data. See `smooth kdensity`.
#end
D convex_hull 2
D mask_pm3d 3
D smooth_path 2
3 Named palettes
?new colormaps
#start
#b The current palette can be saved to a named colormap for future use.
## See `set colormap`.
#b pm3d and image plots can specify a previously saved palette by name.
## This permits the use of multiple palettes in a single plot command.
## See `colorspec palette`.
#b Named palette colormaps can be manipulated as arrays of 32-bit ARGB
## color values. This permits addition of alpha-channel values or other
## modifications not easily specified in a `set palette` command.
#b There is a new predefined color scheme `set palette viridis`.
#b Palettes read from a file or datablock (`set palette file`) may be specified
## either using fractional color components or 24-bit packed RGB values.
#end
D named_palettes 4
D viridis 1
3 New data formats
?new data_formats
#start
#b The `sparse matrix=(cols,rows)` option to `plot` and `splot` generates
## a uniform pixel grid into which individual pixel values may be loaded in
## any order. This is useful for plotting heat maps from incomplete data.
## See `sparse`.
#b During input of non-uniform matrix data, column(0) now returns the linear
## ordering of matrix elements. I.e. for element A[i,j] in an MxN matrix A,
## column(0)/M gives the row index i, and column(0)%M gives the column index j.
#end
3 New built-in functions and array operations
?new built-in functions
#start
#b `palette(z)` returns the current RGB palette color mapping z into cbrange.
#b `rgbcolor("name")` returns the 32bit ARGB value for a named color.
#b `index( Array, element )` returns the first index `i` for which
## Array[i] is equal to element. See `arrays`.
#b User-defined functions allow an array as a parameter.
^<br>
## Example: dot(A,B) = sum [i=1:|A|] A[i]*B[i]
#b Array slices are generated by appending a range to the array name.
## Array[n] is single element. Array[n:n+5] is a six element slice of
## the original array. See `arrays`, `slice`.
#b `split("string", "separator")` unpacks the fields in a string into
## an array of strings. See `split`.
#b `join(array, "separator")` is the complement to `split`. It concatenates
## the elements of a string array into a single string with field separators.
## See `join`.
#b `stats <non-existent file>` yields a testable value. See `stats test`.
#b `stats $vgrid` finds min/max/mean/stddev of voxels in grid
#end
3 Program control flow
?control flow
#start
#b New syntax `if ... else if ... else ...`
#b XDG base directory conventions for configuration preferences are supported.
## The program reads initial commands from $XDG_CONFIG_HOME/gnuplot/gnuplotrc.
## Session command history is saved to $XDG_STATE_HOME/gnuplot_history.
## If these files are not found, $HOME/.gnuplot and $HOME/.gnuplot_history
## are used as in previous gnuplot versions.
#b `unset warnings` suppresses output of warning messages to the console.
#b Exception handling for the "fit" command. Control always returns to the
## next line of input, even in the case of fit errors. On return, FIT_ERROR is
## non-zero if an error occurred. This allows scripted recovery from a bad fit.
## See `fit error_recovery`.
#end
3 New terminals and terminal options
?new terminals
#start
#b New terminals `kittygd` and `kittycairo` provide in-window graphics for
## terminal emulators that support the kitty protocol. Kitty is an alternative
## to sixel graphics that offers full 24-bit RGB color. See `kittycairo`.
#b New terminal `block` for text-mode pseudo-graphics uses Unicode
## block or Braille characters to offer improved resolution compared
## to the `dumb` or `caca` terminals.
#b New terminal `webp` generates a single frame or an animation sequence
## using webp encoding. Frames are generated using pngcairo, then
## encoded through the WebPAnimEncoder API exported by libwebp and libwebpmux.
#b Terminals that use the same window for text entry and graphical display,
## including `dumb`, `sixel`, `kitty`, and `block`, now respond to keyboard
## input during a `pause mouse` command. While paused, they interpret keystrokes
## in the same way that a mousing terminal would. See `pseudo-mousing`.
## For example the left/right/up/down arrow keys change the view angle of 3D
## plots and perform incremental pan/zoom steps for 2D plots.
#end
3 Watchpoints
?new watchpoints
Watchpoints are target values associated with individual plots in a graph.
As that plot is drawn, each component line segment is monitored to see if
its endpoints bracket the target value of a watchpoint coordinate (x, y, or z)
or function f(x,y). If a match is found, the [x,y] coordinates of the
match point are saved for later use. See `watchpoints`.
Possible uses include
#start
#b Find the intersection points of two curves
#b Find zeros of a function
#b Find and notate where a dependent variable (y or z) or function f(x,y)
## crosses a threshold value
#b Use the mouse to track values along multiple plots simultaneously
#end
3 Week-date time support
?new week-date time
The Covid-19 pandemic of 2020/2021 generated increased interest in plotting
epidemiological data, which is often tabulated using a "week date" reporting
convention. Deficiencies with gnuplot support for this convention were
remedied and the support for week-date time was extended.
#start
#b Time specifier format %W has been brought into accord with the
## ISO 8601 week date standard.
#b Time specifier format %U has been brought into accord with the
## CDC/MMWR week date standard.
#b New function `tm_week(time, std)` returns ISO or CDC standard week of year.
#b New function `weekdate_iso(year, week, day)` converts ISO standard week date
## to calendar time.
#b New function `weekdate_cdc(year, week, day)` converts CDC standard week date
## to calendar time.
#end
D epi_data 1
3 Other new features
?new features
#start
#b `Time units for setting major and minor tics.`
## Both major and minor tics along a time axis now accept tic intervals given
## in units of minutes/hours/days/weeks/months/years.
## See `set xtics`, `set mxtics time`.
#b The character sequence $# in a `using` specifier evaluates to the total
## number of columns available in the current line of data. For example
## "plot FOO using 0:(column($# - 1))" plots the last-but-one field of each row.
#b keyword `binvalue=avg` plots the average, rather than the sum, of binned data.
#b `set colorbox bottom` places a horizontal color box underneath the plot
## rather than a vertical box on the right.
#b Improved rendering of intersecting pm3d surfaces - overlapping surface tiles
## are split into two pieces along the line of intersection so that tiles
## from one surface do not incorrectly protrude though the other surface.
#b User-controlled spotlight added to the pm3d lighting model.
## See `set pm3d spotlight`.
#b New options to force total key width and number of columns. See `key layout`.
#b `set pm3d border retrace` draws a border around each pm3d quadrangle in the
## same color as the filled area. In principle this should have no visible
## effect, but it prevents some display modes like glitchy pdf or postscript
## viewers from introducing aliasing artifacts.
#b `set isotropic` adjusts the axis scaling in both 2D and 3D plots such that
## the x, y, and z axes all have the same scale.
#b Change: Text rotation angle is not limited to integral degrees.
#b Special (non-numerical) linetypes `lt nodraw`, `lt black`, `lt bgnd`
## See `special_linetypes`.
#b Data-driven color assignments in histogram plots. See `histograms colors`.
#b The position of the key box can be manually tweaked by specifying an
## offset to be added to whatever position the program would otherwise use.
## See `set key offset`.
#end
3 Brief summary of features introduced in version 5
?new version_5
?version_5
4 Features introduced in 5.4
?new version_5 version_5.4
?version_5 version_5.4
#start
#b Expressions and functions use 64-bit integer arithmetic. See `integer`
#b 2D plot styles `polygons`, `spiderplot`, `arrows`
#b 3D plot styles `boxes`, `circles`, `polygons`, `isosurface` and
## other representations of gridded voxel data
#b Data preprocessing filter `zsort`
#b Construction of customized keys using `keyentry`
#b New LaTeX terminal pict2e supersedes older terminals `latex`, `emtex`, `eepic`,
## and `tpic`. The older terminals are no longer built by default
#b `set pixmap` imports a png/jpeg/gif image as a pixmap that can be scaled and
## positioned anywhere in a plot or on the page
#b Enhanced text mode accepts \U+xxxx (xxxx is a 4 or 5 character hexadecimal)
## as representing a Unicode code point that is converted to the corresponding
## UTF-8 byte sequence on output
#b Revised syntax for `with parallelaxes` allows convenient iteration inside the
## plot command, similar to plot styles `histogram` and `spiderplot`
#end
4 Features introduced in 5.2
?new version_5 version_5.2
?version_5 version_5.2
#start
#b Nonlinear coordinate systems (see `set nonlinear`)
#b Automated binning of data (see `bins`)
#b 2D beeswarm plots. See `set jitter`
#b 3D plot style `zerrorfill`
#b 3D lighting model provides shading and specular highlighted (see `lighting`).
#b Array data type, associated commands and operators. See `arrays`.
#b New terminals `sixelgd`, `domterm`
#b New format descriptors tH tM tS handle relative times (interval lengths).
## See `time_specifiers`.
#end
4 Features introduced in 5.0
?new version_5 version_5.0
?version_5 version_5.0
#start
#b Terminal independent dash types.
#b The default sequence of colors used for successive elements in a plot is
## more easily distinguished by users with color-vision defects.
#b New plot types `with parallelaxes`, `with table`.
#b Hypertext labels activated by a mouse-over event.
#b Explicit sampling ranges in 2D and 3D function plots and pseudofiles
## '+' and '++'.
#b Plugin support through new command `import` that attaches a user-defined
## function name to a function provided by an external shared object.
#end
2 Differences between versions 5 and 6
Some changes introduced in version 5 could cause certain scripts written
for earlier versions of gnuplot to fail or to behave differently.
There are very few such changes in version 6.
3 Deprecated syntax
?deprecated syntax
Deprecated in version 5.4, removed in 6.0
# use of a file containing `reread` to perform iteration
N = 0; load "file-containing-reread";
file content:
N = N+1
plot func(N,x)
pause -1
if (N<5) reread
Current equivalent
do for [N=1:5] {
plot func(N, x)
pause -1
}
Deprecated in version 5.4, removed in 6.0
set dgrid3d ,,foo # no keyword to indicate meaning of foo
Current equivalent
set dgrid3d qnorm foo # (example only; qnorm is not the only option)
Deprecated in version 5.0, removed in 6.0
set style increment user
Current equivalent
use "set linetype" to redefine a convenient range of linetypes
Deprecated in version 5.0, removed in 6.0
show palette fit2rgbformulae
2 Demos and Online Examples
?demos
?online examples
?examples
The `gnuplot` distribution contains a collection of examples in the `demo`
directory. You can browse on-line versions of these examples produced by the
png, svg, and canvas terminals at
^ <a href="http://gnuplot.info/demos/">
http://gnuplot.info/demos
^ </a>
The commands that produced each demo plot are shown next to the plot, and
the corresponding gnuplot script can be downloaded to serve as a model for
generating similar plots.
2 Batch/Interactive Operation
?batch/interactive
`Gnuplot` may be executed in either batch or interactive modes, and the two
may even be mixed together.
Command-line arguments are assumed to be either program options or names
of files containing `gnuplot` commands.
Each file or command string will be executed in the order specified.
The special filename "-" is indicates that commands are to be read from stdin.
`Gnuplot` exits after the last file is processed. If no load files and no
command strings are specified, `gnuplot` accepts interactive input from stdin.
3 command line options
?command-line-options
?batch/interactive command-line-options
Gnuplot accepts the following options on the command line
-V, --version
-h, --help
-p, --persist
-d, --default-settings
-s, --slow
-e "command1; command2; ..."
-c scriptfile ARG1 ARG2 ...
-p tells the program not to close any remaining interactive plot windows
when the program exits.
-d tells the program not to execute any private or system initialization
(see `initialization`).
-s tells the program to wait for slow font initialization on startup.
Otherwise it prints an error and continues with bad font metrics.
-e "command" tells gnuplot to execute that single command before continuing.
-c is equivalent to -e "call scriptfile ARG1 ARG2 ...". See `call`.
3 Examples
?batch/interactive examples
To launch an interactive session:
gnuplot
To execute two command files "input1" and "input2" in batch mode:
gnuplot input1 input2
To launch an interactive session after an initialization file "header" and
followed by another command file "trailer":
gnuplot header - trailer
To give `gnuplot` commands directly in the command line, using the "-persist"
option so that the plot remains on the screen afterwards:
gnuplot -persist -e "set title 'Sine curve'; plot sin(x)"
To set user-defined variables a and s prior to executing commands from a file:
gnuplot -e "a=2; s='file.png'" input.gpl
2 Canvas size
?canvas size
?canvas
?set term size
This documentation uses the term "canvas" to mean the full drawing area
available for positioning the plot and associated elements like labels,
titles, key, etc. NB: For information about the HTML5 canvas terminal
see `set term canvas`.
`set term <terminal_type> size <XX>, <YY>` controls the size of the output
file, or "canvas". By default, the plot will fill this canvas.
`set size <XX>, <YY>` scales the plot itself relative to the size of the
canvas. Scale values less than 1 will cause the plot to not fill the entire
canvas. Scale values larger than 1 will cause only a portion of the plot to
fit on the canvas. Please be aware that setting scale values larger than 1
may cause problems.
Example:
set size 0.5, 0.5
set term png size 600, 400
set output "figure.png"
plot "data" with lines
These commands produce an output file "figure.png" that is 600 pixels wide
and 400 pixels tall. The plot will fill the lower left quarter of this canvas.
Note: In early versions of gnuplot some terminal types used `set size`
to control the size of the output canvas. This was deprecated in version 4.
2 Command-line-editing
?line-editing
?editing
?command-line-editing
Command-line editing and command history are supported using either an
external gnu readline library, an external BSD libedit library, or a
built-in equivalent. This choice is a configuration option at the time
gnuplot is built.
The editing commands of the built-in version are given below. Please note that
the action of the DEL key is system-dependent. The gnu readline and BSD libedit
libraries have their own documentation.
@start table - first is interactive cleartext form
`Line-editing`:
^B moves back a single character.
^F moves forward a single character.
^A moves to the beginning of the line.
^E moves to the end of the line.
^H deletes the previous character.
DEL deletes the current character.
^D deletes current character, sends EOF if the line is empty.
^K deletes from current position to the end of line.
^L redraws line in case it gets trashed.
^U deletes the entire line.
^W deletes previous word.
^V inhibits the interpretation of the following key as editing command.
TAB performs filename-completion.
`History`:
^P moves back through history.
^N moves forward through history.
^R starts a backward-search.
#\begin{tabular}{|cl|} \hline
#\multicolumn{2}{|c|}{Command-line Editing Commands} \\ \hline \hline
#Character & Function \\ \hline
# & \multicolumn{1}{|c|}{Line Editing}\\ \cline{2-2}
#\verb~^B~ & move back a single character.\\
#\verb~^F~ & move forward a single character.\\
#\verb~^A~ & move to the beginning of the line.\\
#\verb~^E~ & move to the end of the line.\\
#\verb~^H~ & delete the previous character.\\
#\verb~DEL~ & delete the current character.\\
#\verb~^D~ & delete current character. EOF if line is empty.\\
#\verb~^K~ & delete from current position to the end of line.\\
#\verb~^L~ & redraw line in case it gets trashed.\\
#\verb~^U~ & delete the entire line. \\
#\verb~^W~ & delete previous word. \\
#\verb~^V~ & inhibits the interpretation of the following key as editing command. \\
#\verb~TAB~ & performs filename-completion. \\ \hline
# & \multicolumn{1}{|c|}{History} \\ \cline{2-2}
#\verb~^P~ & move back through history.\\
#\verb~^N~ & move forward through history.\\
#\verb~^R~ & starts a backward-search.\\
%c l .
%Character@Function
%_
%@Line Editing
%^B@move back a single character.
%^F@move forward a single character.
%^A@move to the beginning of the line.
%^E@move to the end of the line.
%^H@delete the previous character.
%DEL@delete the current character.
%^D@delete current character. EOF if line is empty.
%^K@delete from current position to the end of line.
%^L@redraw line in case it gets trashed.
%^U@delete the entire line.
%^W@delete previous word.
%_
%^V@inhibits the interpretation of the following key as editing command.
%TAB@performs filename-completion.
%_
%@History
%^P@move back through history.
%^N@move forward through history.
%^R@starts a backward-search.
@end table
^<table align="center" border="1" rules="groups" frame="hsides" cellpadding="3">
^<colgroup>
^ <col align="center">
^ <col align="left">
^</colgroup>
^<thead>
^<tr> <th>Character</th> <th>Function</th></tr>
^</thead>
^<tbody>
^<tr> <td></td> <th>Line Editing</th></tr>
^<tr> <td><tt>^B</tt></td> <td>move back a single character.</td></tr>
^<tr> <td><tt>^F</tt></td> <td>move forward a single character.</td></tr>
^<tr> <td><tt>^A</tt></td> <td>move to the beginning of the line.</td></tr>
^<tr> <td><tt>^E</tt></td> <td>move to the end of the line.</td></tr>
^<tr> <td><tt>^H</tt></td> <td>delete the previous character.</td></tr>
^<tr> <td><tt>DEL</tt></td> <td>delete the current character.</td></tr>
^<tr> <td><tt>^D</tt></td> <td>delete current character. EOF if line is empty</td></tr>
^<tr> <td><tt>^K</tt></td> <td>delete from current position to the end of line.</td></tr>
^<tr> <td><tt>^L</tt></td> <td>redraw line in case it gets trashed.</td></tr>
^<tr> <td><tt>^U</tt></td> <td>delete the entire line.</td></tr>
^<tr> <td><tt>^W</tt></td> <td>delete previous word.</td></tr>
^<tr> <td><tt>^V</tt></td> <td>inhibits the interpretation of the following key as editing command.</td></tr>
^<tr> <td><tt>TAB</tt></td> <td>performs filename-completion.</td></tr>
^</tbody>
^<tbody>
^<tr> <th></th> <th>History</th></tr>
^<tr> <td><tt>^P</tt></td> <td>move back through history.</td></tr>
^<tr> <td><tt>^N</tt></td> <td>move forward through history.</td></tr>
^<tr> <td><tt>^R</tt></td> <td>starts a backward-search.</td></tr>
^</tbody>
^</table>
2 Comments
?comments
The comment character `#` may appear almost anywhere in a command line, and
`gnuplot` will ignore the rest of that line. A `#` does not have this effect
inside a quoted string. Note that if a commented line ends in '\' then the
subsequent line is also treated as part of the comment.
See also `set datafile commentschars` for specifying a comment character for
data files.
2 Coordinates
?coordinates
=axes
The commands `set arrow`, `set key`, `set label` and `set object` allow you
to draw something at an arbitrary position on the graph. This position is
specified by the syntax:
{<system>} <x>, {<system>} <y> {,{<system>} <z>}
Each <system> can either be `first`, `second`, `polar`, `graph`, `screen`, or
`character`.
`first` places the x, y, or z coordinate in the system defined by the left
and bottom axes; `second` places it in the system defined by the x2,y2 axes
(top and right); `graph` specifies the area within the axes---0,0 is bottom
left and 1,1 is top right (for splot, 0,0,0 is bottom left of plotting area;
use negative z to get to the base---see `set xyplane`); `screen`
specifies the screen area (the entire area---not just the portion selected by
`set size`), with 0,0 at bottom left and 1,1 at top right. `character`
coordinates are used primarily for offsets, not absolute positions.
The `character` vertical and horizontal size depend on the current font.
`polar` causes the first two values to be interpreted as angle theta and radius
r rather than as x and y. This could be used, for example, to place labels on
a 2D plot in polar coordinates or a 3D plot in cylindrical coordinates.
If the coordinate system for x is not specified, `first` is used. If the
system for y is not specified, the one used for x is adopted.
In some cases, the given coordinate is not an absolute position but a
relative value (e.g., the second position in `set arrow` ... `rto`). In
most cases, the given value serves as difference to the first position.
If the given coordinate belongs to a log-scaled axis, a relative value is
interpreted as multiplier. For example,
set logscale x
set arrow 100,5 rto 10,2
plots an arrow from position 100,5 to position 1000,7 since the x axis is
logarithmic while the y axis is linear.
If one (or more) axis is timeseries, the appropriate coordinate should
be given as a quoted time string according to the `timefmt` format string.
See `set xdata` and `set timefmt`. `Gnuplot` will also accept an integer
expression, which will be interpreted as seconds relative to 1 January 1970.
2 Datastrings
?datastrings
Data files may contain string data consisting of either an arbitrary string
of printable characters containing no whitespace or an arbitrary string of
characters, possibly including whitespace, delimited by double quotes.
The following line from a datafile is interpreted to contain four
columns, with a text field in column 3:
1.000 2.000 "Third column is all of this text" 4.00
Text fields can be positioned within a 2-D or 3-D plot using the commands:
plot 'datafile' using 1:2:4 with labels
splot 'datafile' using 1:2:3:4 with labels
A column of text data can also be used to label the ticmarks along one or more
of the plot axes. The example below plots a line through a series of points
with (X,Y) coordinates taken from columns 3 and 4 of the input datafile.
However, rather than generating regularly spaced tics along the x axis
labeled numerically, gnuplot will position a tic mark along the x axis at the
X coordinate of each point and label the tic mark with text taken from column
1 of the input datafile.
set xtics
plot 'datafile' using 3:4:xticlabels(1) with linespoints
=columnheader
There is also an option that will interpret the first entry in a column of
input data (i.e. the column heading) as a text field, and use it as the key
title for data plotted from that column. The example given below will use the
first entry in column 2 to generate a title in the key box, while processing
the remainder of columns 2 and 4 to draw the required line:
plot 'datafile' using 1:(f($2)/$4) with lines title columnhead(2)
Another example:
plot for [i=2:6] 'datafile' using i title "Results for ".columnhead(i)
This use of column headings is automated by `set datafile columnheaders` or
`set key autotitle columnhead`.
See `labels`, `using xticlabels`, `plot title`, `using`, `key autotitle`.
2 Enhanced text mode
?enhanced text
?enhanced
?text_markup
?markup
?bold
?italic
Many terminal types support an enhanced text mode in which additional
formatting information can be embedded in the text string. For example, "x^2"
will write x-squared as we are used to seeing it, with a superscript 2.
This mode is selected by default when you set the terminal, but may be
toggled afterward using "set termoption [no]enhanced", or disabled for
individual strings as in `set label "x_2" noenhanced`.
Note: For output to TeX-based terminals (e.g. cairolatex, pict2e, pslatex,
tikz) all text strings should instead use TeX/LaTeX syntax. See `latex`.
@start table - first is interactive cleartext form
Control Examples Explanation
^ a^x superscript
_ a_x subscript
@ @x or a@^b_{cd} phantom box (occupies no width)
& &{space} inserts space of specified length
~ ~a{.8-} overprints '-' on 'a', raised by .8
times the current fontsize
{/Times abc} print abc in font Times at current size
{/Times*2 abc} print abc in font Times at twice current size
{/Times:Italic abc} print abc in font Times with style italic
{/Arial:Bold=20 abc} print abc in boldface Arial font size 20
\U+ \U+221E Unicode point U+221E (INFINITY)
#\begin{tabular}{|clll|} \hline
#\multicolumn{4}{|c|}{Enhanced Text Control Codes} \\ \hline
#Control & Example & Result & Explanation \\ \hline
#\verb~^~ & \verb~a^x~ & $a^x$ & superscript\\
#\verb~_~ & \verb~a_x~ & $a_x$ & subscript\\
#\verb~@~ & \verb~a@^b_{cd}~ & $a^b_{cd}$ &phantom box (occupies no width)\\
#\verb~&~ & \verb~d&{space}b~ & d\verb*+ +b & inserts space of specified length\\
#\verb|~| & \verb|~a{.8-}| & $\tilde{a}$ & overprints '-' on 'a', raised by .8\\
#\verb~ ~ & \verb~ ~ & ~ ~ & times the current fontsize\\
#\verb| | & \verb|{/Times abc}| & {\rm abc} & print abc in font Times at current size\\
#\verb| | & \verb|{/Times*2 abc}| & \Large{\rm abc} & print abc in font Times at twice current size\\
#\verb| | & \verb|{/Times:Italic abc}| & {\it abc} & print abc in font Times with style italic\\
#\verb| | & \verb|{/Arial:Bold=20 abc}| & \Large\textsf{\textbf{abc}} & print abc in boldface Arial font size 20\\
#\verb|\U+| & \verb|\U+221E| & $\infty$ & Unicode point U+221E INFINITY\\
%c c l .
C ugly - doc2ms uses @ for column separator, but here we
C need @ in table, so end and restart the table !
%.TE
%.TS
%center box tab ($) ;
%c c l .
%Control$Examples$Explanation
%_
%^$a^x$superscript
%\&_$a\&_x$subscript
% @ $ @x or a\&@^b\&_{cd}$phantom box (occupies no width)
% & $ &{space}$inserts space of specified length
% ~ $ ~a{.8-}$overprints '-' on 'a', raised by .8
% $ $times the current fontsize
@end table
^<table align="center" border="1" rules="groups" frame="hsides" cellpadding="3">
^<colgroup>
^ <col align="center">
^ <col align="center">
^ <col align="left">
^</colgroup>
^<thead>
^<tr> <th>Control</th> <th>Examples</th> <th>Explanation</th></tr>
^</thead>
^<tbody>
^<tr> <td><tt> ^ </tt></td> <td><tt>a^x</tt></td> <td>superscript</td></tr>
^<tr> <td><tt> _ </tt></td> <td><tt>a_x</tt></td> <td>subscript</td></tr>
^<tr> <td><tt> @ </tt></td> <td><tt> @x</tt> or <tt>a@^b_{cd}</tt></td> <td>phantom box (occupies no width)</td></tr>
^<tr> <td><tt> &</tt></td> <td><tt> &{space}</tt></td> <td>inserts space of specified length</td></tr>
^<tr> <td><tt> ~ </tt></td> <td><tt> ~a{.8-}</tt></td> <td>overprints '-' on 'a', raised by .8<br>times the current fontsize</td></tr>
^</tbody>
^</table>
The markup control characters act on the following single character or
bracketed clause. The bracketed clause may contain a string of characters with
no additional markup, e.g. 2^{10}, or it may contain additional markup that
changes font properties. Font specifiers MUST be preceded by a '/' character
that immediately follows the opening '{'. If a font name contains spaces it
must be enclosed in single or double quotes.
Examples: The first example illustrates nesting one bracketed clause inside
another to produce a boldface A with an italic subscript i, all in the current
font. If the clause introduced by :Normal were omitted the subscript would be
both italic and boldface. The second example illustrates the same markup
applied to font "Times New Roman" at 20 point size.
{/:Bold A_{/:Normal{/:Italic i}}}