View source for Gnuplot

{{Split}}

gnuplot is a command-line driven multiplatform plotting program. Despite the name, it is not associated with GNU project and is not covered by GNU GPL. The source code license is a gratis one, but not a copyleft one; "Permission to modify the software is granted, but not the right to distribute the complete modified source code."[http://gnuplot.cvs.sourceforge.net/gnuplot/gnuplot/Copyright?view=markup]

== Usage ==
gnuplot can be used interactively, in batch mode, or embedded in (scripted by) another program, such as [[w:GNU Octave|GNU Octave]].

* Interactively, run <tt>gnuplot</tt> at the command line.
* In batch mode, run <tt>gnuplot input.plt</tt> (where <tt>input.plt</tt> is the name of the input file) at the command line.
* In another program, use that program’s plotting facilities – gnuplot will be called transparently.
* For use in one’s own programs, one can run gnuplot via <tt>[http://pubs.opengroup.org/onlinepubs/007908799/xsh/popen.html popen],</tt> or use a library that wraps gnuplot for the programming language. These wrapper libraries exist for C, C++(e.g. [http://www.stahlke.org/dan/gnuplot-iostream/ Gnuplot-iostream], [http://code.google.com/p/gnuplot-cpp/ gnuplot-cpp]) Python, Perl, Java, Fortran95, and others.

=== Example ===
As very simple usage, start gnuplot and type:
 plot sin(x)
 exit
This will display a plot of the sine function, and then exit.

=== Outline ===
To plot a function or functions:
* define the '''function;'''
* determine the '''range''' of ''inputs'' and ''outputs;''
* determine the '''style''' for the ''region'' and the ''graphs;''
* plot it (using the <tt>plot</tt> function)

To plot data, collect the data in a file instead of defining a function.

== Format ==
=== Plain ===
Unsetting the default decorations will yield a completely plain graph area:
 unset title
 unset key
 unset xtics
 unset ytics
 set border 0
These fields can now be set individually, if desired.

=== Axes ===
==== Percentage ====
To format an axis as a percentage, multiply the number by 100 and suffix a “%” symbol using <tt>format,</tt> as in:
 set format y "%g %%"
 plot "dat1.txt" using 1:($2*100)

== Types of functions ==
=== Piecewise-defined functions ===
:''See: [[w:Piecewise function|Piecewise function]]''


Several ways are possible. 
==== The ?  operator ====

One can plot [[w:Piecewise function|piecewise-defined functions]] in gnuplot with the ternary condition operator (<tt>[[w:?:|?:]]</tt>). For instance, one can manually define the absolute value function by:
 f(x) = x > 0 ? x : -x
Read this as “if…then…else”: “if ''x'' is greater than 0, then <math>f(x)=x,</math> else <math>f(x)=-x.</math>”

One can chain these, for instance by:
 f(x) = x < 1 ? 1 \
      : x < 2 ? 3 \
              : 5
This corresponds to the piecewise function
:<math>f(x)=\begin{cases}
1 & \text{if } x < 1 \\
3 & \text{if } x \geq 1 \text{ and } x < 2 \\
5 & \text{otherwise}
\end{cases}</math>

For piecewise functions, you will likely want many samples, so that discontinuities appear as vertical lines, and corners appear sharp, so:
 set sample 1001
(Using 1001 instead of 1000 avoids artifacts of having a sample point appear directly on a discontinuity, which can introduce "stair steps.")

==== plot each function individually ====
Or you can plot each function individually, like you appear to be doing now.

 f(x) = a1*x**2+b1*x+c1  for x in [t11,t12]
 f(x) = a2*x**2+b2*x+c2  for x in [t21,t22]
 f(x) = a3*x**2+b3*x+c3  for x in [t31,t32]
 ....
 ....
 ...
where 
 t11<=t12<=t21<=t22, etc.

==== Parametric mode ====
Better yet, switch to parametric mode, map a common t interval [0:1] to 
your individual t ranges, and then:

	x1(t) = t11+t*(t12-t11)
	...

	plot x1(t), f1(x1(t)), x2(t), f2(x2(t)), ...
plot each function individually

== Source files ==
gnuplot allows one to load files via the <tt>load</tt> command, or by passing them as arguments on the command line.  This is very useful for complicated graphs.

There is no official standard extension, but some semi-official extensions are used:
* <tt>.plt, .gnu, .gpi,</tt> or <tt>.gih</tt> for general gnuplot files;
* <tt>.dat</tt> for data;
* <tt>.fnc</tt> for function definitions.

For formatting source code, two useful pieces of syntax are:
;comments: The hash (<tt>#</tt>) character starts inline comments, which continue to the end of the line.
;line continuation: A trailing backslash (<tt>\</tt>) is a line continuation character, and allows one to split a long expression over multiple lines. One can also indent/line up the continuing lines for legibility (as in piecewise functions), as initial whitespace is ignored.

=== Debugging ===
For debugging a gnuplot file, it is often useful to:
* Change the terminal to interactive (instead of outputting to a file), by commenting out <tt>set terminal</tt> and <tt>output</tt> lines.
* Start gnuplot interactively, then <tt>load</tt> the file in question.
* Put <tt>pause -1</tt> (pause until carriage return) at the end of the file, then run it from the command line.
** Alternatively, run gnuplot with the <tt>-persist</tt> command line switch, so gnuplot exits, but the window persists.
* Make the file itself executable, by shebang (<tt>#!</tt>) notation (depends on exact path):
 #!/usr/bin/gnuplot -persist

=== Syntax highlighting ===
[[w:vim|vim]] has automatic syntax highlighting for gnuplot ([http://www.vim.org/scripts/script.php?script_id=1737 gnuplot.vim]) as long as the file extension is <code>.gpi</code>.

Alternatively, other file extensions, such as <tt>.plt</tt>, can be added in the usual autocommand way:
 au BufNewFile,BufRead *.plt,*.gnuplot setf gnuplot

Also see a [https://github.com/vlaadbrain/gnuplot.vim github repository] compatible with pathogen's auto filetype detection features.

==Color ==
* [[Gnuplot/color|colorspec]]
* [[Gnuplot/palette|palette]]
* color sequence

=== colorsequence===

Syntax:

    set colorsequence {default|classic|podo}

Offline help:

    help set colorsequence

*cycle set:

 <syntaxhighlight lang=gnuplot>
 set linetype 1 lc rgb "dark-violet" lw 2 pt 0
   set linetype 2 lc rgb "sea-green"   lw 2 pt 7
   set linetype 3 lc rgb "cyan"        lw 2 pt 6 pi -1
   set linetype 4 lc rgb "dark-red"    lw 2 pt 5 pi -1
   set linetype 5 lc rgb "blue"        lw 2 pt 8
   set linetype 6 lc rgb "dark-orange" lw 2 pt 3
   set linetype 7 lc rgb "black"       lw 2 pt 11
   set linetype 8 lc rgb "goldenrod"   lw 2
   set linetype cycle 8

 </syntaxhighlight>
    
    

9 cycle set:
<syntaxhighlight lang=gnuplot>
# https://stackoverflow.com/questions/46775612/colorsequence-for-more-than-8-colors-gnuplot
# Ethan A Merritt - my preference for gnuplot colors
 # 2 3 4 5 6 8 are borrowed from the colors_podo set
 #
 set linetype  1 lc rgb "dark-violet" lw 1
 set linetype  2 lc rgb "#009e73" lw 1
 set linetype  3 lc rgb "#56b4e9" lw 1
 set linetype  4 lc rgb "#e69f00" lw 1
 set linetype  5 lc rgb "#f0e442" lw 1
 set linetype  6 lc rgb "#0072b2" lw 1
 set linetype  7 lc rgb "#e51e10" lw 1
 set linetype  8 lc rgb "black"   lw 1
 set linetype  9 lc rgb "gray50"  lw 1
 set linetype cycle  9
</syntaxhighlight>
===code===
* gnuplot/src/getcolor.c
* gnuplot/src/graphics.c
* gnuplot/src/color.c

== Generating Wikimedia graphs ==
:''See: [[w:Wikipedia:How_to_create_graphs_for_Wikipedia_articles#gnuplot|How to create graphs for Wikipedia articles: gnuplot]]''

To generate graphs for Wikimedia:
* Store your code in a ''file,'' preferably with ''comments''
* Use ''high quality'' (vector graphic) ''SVG'' output.
* Generate the SVG.
* Optionally post-process.
* Upload the ''graph'' and ''source code'' to Wikimedia Commons.

Details follow.


=== gnuplot options ===
Here is a sample header:
 set terminal svg enhanced size 300 300
 set samples 1001  # high quality
 set border 31 linewidth .3 # thin border
 set output "filename.svg"
(The ''file name'' should be ''changed'' to something more descriptive, though this is not strictly necessary.)

This will create an SVG which is nominally 300 × 300, a common Wikimedia display size:
it is easiest to make graphs whose nominal size is the expected display size, but beware that images can and are resized, and that this affects ''thickness'' and ''legibility'' – if using a large nominal size, so that it will likely be resized down, use ''large fonts'' and ''thick lines.''

Beware that with horizontal writing, the y-axis labels will likely take up more space (horizontally) than the x-axis labels take (vertically), and thus a nominally square graph will have an actually graphing area which is slightly taller than it is wide.

One can set the font via:
 set terminal svg enhanced size 300 300 fname "Times" fsize 36

==== Technical details ====
;set terminal svg: sets output to be an SVG file
;enhanced: means to use enhanced text output, when Greek letters are needed. a table can be found [[http://t16web.lanl.gov/Kawano/gnuplot/label-e.html here]].
;size 300 300: sets the nominal size of the SVG as 300 × 300
;set samples 1001: this sets many samples for high quality; the 1001 (instead of 1000) is so that a sample is unlikely to land directly on a pixel or discontinuity, which can cause aliasing. If you have unexpected aliasing, try changing this to 1002 or 1003, as that will move all sample points, possibly fixing the problem.
;set border 31 linewidth .3: “31” is 1111 in binary, meaning “all borders”; use “3” (0011) in binary for just the lower and left borders. The thin linewidth makes the border less prominent, emphasizing the line. <small>[Note, 31 actually is 11111 in binary.  The fifth bit is irrelevant to this example and the example should be rewritten with 15 instead of 31.]</small>  Note, use interactive gnuplot command "help set border" to see an explanation of what each bit controls.
;set output "filename.svg": This sets the output file name.  In normal use, choose a filename more descriptive of file contents.

=== Post-processing ===
One may wish to post-process the SVG, either in a vector graphics program such as [[Inkscape]], or by hand (as SVG files are text). This can be useful to add annotations which would be otherwise hard to produce in gnuplot, or one may incorporate the plot as one component of a larger or more complex figure.

=== Wikimedia Commons Upload ===
* Please use the template <tt>{{[[commons:Template:gnuplot|gnuplot]]}}</tt> to flag it as made with gnuplot.
* The source code may be included in the “Source” section of the description (if brief), or more often in a separate <tt>== gnuplot source ==</tt> section.
* The source is most legible if wrapped in [[mw:Extension:SyntaxHighlight GeSHi|Syntax highlighting]] via:
 <nowiki><syntaxhighlight lang="gnuplot">
...
</syntaxhighlight></nowiki>
* If you use text, it may be translated – please use the template <tt>{{[[commons:Translation possible|Translation possible]]}}</tt> to indicate that translation is possible.
** Alternatively, minimize the use of text (place in a separate caption) to aid reuse of the image in other languages.

== Design considerations ==
There are a number of design considerations in graphs, considered as information graphics. A good resource are the works and writings of information graphic designers, such as the highly regarded works of Edward Tufte: his ''The Visual Display of Quantitative Information'' is most relevant for graphs, but his and others other work can be insightful and inspiring.

The first consideration is what to graph, and whether a graph is the best way to convey certain information: graphs can be unexpectedly useful, or conversely, a graph may not be the best way to convey information. Further, how a graph is connected an integrated with other material is a question – is it referred to? Described and discussed?

Other media that can be an alternative to a graph, or support it, include:
* text, either running text, a list, or an isolated single item (pull quote)
* tables
* schematic diagrams
* animations (possibly animated graphs)
* photographs
Often it is useful to portray the same information in several ways.

A second question is how many graphs to use.
* Most obviously one may use a '''single,''' large, detailed graph, and this is often appropriate, such as if the details of the data are important.
* Alternatively, consider using '''small multiples''' – several small graphs to make a point, through repetition and variation, analogous with written “compare and contrast”.
*:It is especially helpful to align graphs or place them on a grid, so the eye can easily switch between them.
*:Presenting the same data on different scales can also be revealing; a simple example is shown at estimated sign, where the same data is shown on an absolute scale and relative scale.
* One can also use graphs '''in-line,''' as in sparklines.

Beyond these general considerations, there are finer questions:
* Which range of data to display?
* What scale to use? For example, should the range of the graph area agree with the range of the data (maximizing use of space), or should the range be larger, providing context? Often a log scale or log-log scale is appropriate, but may be confusing to novice readers.
* How to distinguish data? What color and line styles to use?
* How prominent to make various data – how thick or thin to make different lines, how large to make text?

== Other Wikimedia resources ==
* [[w:gnuplot|gnuplot]] at Wikipedia
* [[w:Wikipedia:How_to_create_graphs_for_Wikipedia_articles|How to create graphs for Wikipedia articles]] has a section on [[w:Wikipedia:How_to_create_graphs_for_Wikipedia_articles#gnuplot|gnuplot]]
* The book [[Ad Hoc Data Analysis From The Unix Command Line]] has a chapter on [[Ad Hoc Data Analysis From The Unix Command Line/Quick Plotting With gnuplot|Quick Plotting With gnuplot]]
* commons :
** [[commons:Category:Gnuplot diagrams]] has many examples of gnuplot graphs, many with source code.
** [[commons:Category:Images with Gnuplot source code|Images with Gnuplot src code]]

== References ==
* [[w:Information graphics|Information graphics]]
** [[w:Category:Information graphic designers|Information graphic designers]] and their work, such as the highly regarded works of [[w:Edward Tufte|Edward Tufte]]

== External resources ==
* [http://www.gnuplot.info/ gnuplot Central] – homepage
** [http://www.gnuplot.info/documentation.html l Official documentation] ([http://www.gnuplot.info/docs/gnuplot.pdf PDF])
** [http://www.gnuplot.info/docs_4.0/gpcard.pdf Reference card]
** [http://www.gnuplot.info/faq/index.html FAQ]
* [https://www.algorithm-archive.org/contents/domain_coloring/domain_coloring.html domain_coloring ( gnuplot)]
* {{cite web|url=http://t16web.lanl.gov/Kawano/gnuplot/index-e.html|title=gnuplot not so Frequently Asked Questions|archiveurl=http://web.archive.org/web/20121029110317/http://t16web.lanl.gov/Kawano/gnuplot/index-e.html|archivedate=2012-10-29}}
* {{citation
| first1      = Philipp K.
| last1       = Janert
| year        = 2015
| title       = Gnuplot in Action, Second Edition
| publisher   = Manning Publications, New York, USA
| pages       = 425
| isbn        = 978-1-633430-18-1
| url         = http://www.manning.com/janert2/
}}.
* {{citation
| first1      = Lee
| last1       = Phillips
| year        = 2012
| title       = gnuplot Cookbook
| publisher   = Packt Publishing
| pages       = 220
| isbn        = 184951724X
| url         = http://www.packtpub.com/gnuplot-visual-guide-with-plotting-software-cookbook/book
}}.

{{Shelves|2D graphics software}}
{{alphabetical|G}}
{{status|0%}}

[[pl:Gnuplot]]