23 lines
19 KiB
HTML
23 lines
19 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Basic usage · Gnuplot.jl</title><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="../"><img src="../assets/logo.png" alt="Gnuplot.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit">Gnuplot.jl</span></div><form class="docs-search" action="../search/"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../">Home</a></li><li><a class="tocitem" href="../install/">Installation</a></li><li class="is-active"><a class="tocitem" href>Basic usage</a><ul class="internal"><li><a class="tocitem" href="#plots2d-1"><span>2D plots</span></a></li><li><a class="tocitem" href="#Keywords-for-common-commands-1"><span>Keywords for common commands</span></a></li><li><a class="tocitem" href="#Plot-images-1"><span>Plot images</span></a></li><li><a class="tocitem" href="#plots3d-1"><span>3D plots</span></a></li><li><a class="tocitem" href="#Palettes-and-line-types-1"><span>Palettes and line types</span></a></li><li><a class="tocitem" href="#Exporting-plots-to-files-1"><span>Exporting plots to files</span></a></li><li><a class="tocitem" href="#Gnuplot-scripts-1"><span>Gnuplot scripts</span></a></li></ul></li><li><a class="tocitem" href="../advanced/">Advanced techniques</a></li><li><a class="tocitem" href="../tips/">Tips</a></li><li><a class="tocitem" href="../examples/">Examples</a></li><li><a class="tocitem" href="../api/">API</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Basic usage</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Basic usage</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/gcalderone/Gnuplot.jl/blob/master/docs/src/basic.md" title="Edit on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">Edit on GitHub</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Basic-usage-1"><a class="docs-heading-anchor" href="#Basic-usage-1">Basic usage</a><a class="docs-heading-anchor-permalink" href="#Basic-usage-1" title="Permalink"></a></h1><p>The main purpose of the <strong>Gnuplot.jl</strong> package is to send data and commands to the underlying <code>gnuplot</code> process, in order to generate plots. Unlike other packages, however, the actual commands to plot, or the plot attributes, are not specified through function calls. This is what makes <strong>Gnuplot.jl</strong> <em>easy to learn and use</em>: there are no functions or keywords names to memorize<sup class="footnote-reference"><a id="citeref-1" href="#footnote-1">[1]</a></sup>.</p><p>The most important symbols exported by the package are the <a href="../api/#Gnuplot.@gp"><code>@gp</code></a> (for 2D plots) and <a href="../api/#Gnuplot.@gsp"><code>@gsp</code></a> (for 3D plots) macros, both accepting any number of arguments, and whose meaning is interpreted as follows:</p><ul><li><p>one, or a group of consecutive, array(s) build up a dataset. The different arrays are accessible as columns 1, 2, etc. from the <code>gnuplot</code> process. The number of required input arrays depends on the chosen plot style (see <code>gnuplot</code> documentation);</p></li><li><p>a string occurring before a dataset is interpreted as a <code>gnuplot</code> command (e.g. <code>set grid</code>);</p></li><li><p>a string occurring immediately after a dataset is interpreted as a <em>plot element</em> for the dataset, by which you can specify <code>using</code> clause, <code>with</code> clause, line styles, etc.;</p></li><li><p>the special symbol <code>:-</code>, whose meaning is to avoid starting a new plot (if given as first argument), or to avoid immediately running all commands to create the final plot (if given as last argument). Its purpose is to allow splitting one long statement into multiple (shorter) ones.</p></li></ul><p>The above lists all the required concepts to follow the examples presented below. The <a href="../api/#Gnuplot.@gp"><code>@gp</code></a> and <a href="../api/#Gnuplot.@gsp"><code>@gsp</code></a> macros also accepts further arguments, but their use will be discussed in <a href="../advanced/#Advanced-techniques-1">Advanced techniques</a>.</p><h2 id="plots2d-1"><a class="docs-heading-anchor" href="#plots2d-1">2D plots</a><a class="docs-heading-anchor-permalink" href="#plots2d-1" title="Permalink"></a></h2><p>Here we will show a few examples to generate 2D plots. The examples are intentionally very simple to highlight the behavior of <strong>Gnuplot.jl</strong>. See <a href="../examples/#Examples-1">Examples</a> for more complex ones.</p><p>Remember to run:</p><pre><code class="language-julia">using Gnuplot</code></pre><p>before running the examples.</p><h3 id="Simple-examples-involving-just-gnuplot-commands:-1"><a class="docs-heading-anchor" href="#Simple-examples-involving-just-gnuplot-commands:-1">Simple examples involving just <code>gnuplot</code> commands:</a><a class="docs-heading-anchor-permalink" href="#Simple-examples-involving-just-gnuplot-commands:-1" title="Permalink"></a></h3><hr/><h4 id="Plot-a-sinusoid:-1"><a class="docs-heading-anchor" href="#Plot-a-sinusoid:-1">Plot a sinusoid:</a><a class="docs-heading-anchor-permalink" href="#Plot-a-sinusoid:-1" title="Permalink"></a></h4><pre><code class="language-julia">@gp "plot sin(x)"</code></pre><p><img src="../assets/basic1.png" alt/></p><hr/><h4 id="Plot-two-curves:-1"><a class="docs-heading-anchor" href="#Plot-two-curves:-1">Plot two curves:</a><a class="docs-heading-anchor-permalink" href="#Plot-two-curves:-1" title="Permalink"></a></h4><pre><code class="language-julia">@gp "set key left" "plot sin(x)" "pl cos(x)"</code></pre><p><img src="../assets/basic2.png" alt/></p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>Note that all <code>gnuplot</code> commands can be abbreviated as long as the resulting string is not ambiguous. In the example above we used <code>pl</code> in place of <code>plot</code>.</p></div></div><hr/><h4 id="Split-a-@gp-call-in-three-statements:-1"><a class="docs-heading-anchor" href="#Split-a-@gp-call-in-three-statements:-1">Split a <code>@gp</code> call in three statements:</a><a class="docs-heading-anchor-permalink" href="#Split-a-@gp-call-in-three-statements:-1" title="Permalink"></a></h4><pre><code class="language-julia">@gp "set grid" :-
|
|
@gp :- "p sin(x)" :-
|
|
@gp :- "plo cos(x)"</code></pre><p><img src="../assets/basic3.png" alt/></p><h3 id="Send-data-from-Julia-to-gnuplot:-1"><a class="docs-heading-anchor" href="#Send-data-from-Julia-to-gnuplot:-1">Send data from Julia to <code>gnuplot</code>:</a><a class="docs-heading-anchor-permalink" href="#Send-data-from-Julia-to-gnuplot:-1" title="Permalink"></a></h3><h4 id="Plot-a-parabola-1"><a class="docs-heading-anchor" href="#Plot-a-parabola-1">Plot a parabola</a><a class="docs-heading-anchor-permalink" href="#Plot-a-parabola-1" title="Permalink"></a></h4><pre><code class="language-julia">@gp (1:20).^2</code></pre><p><img src="../assets/basic4.png" alt/></p><hr/><h4 id="Plot-a-parabola-with-scaled-x-axis,-lines-and-legend-1"><a class="docs-heading-anchor" href="#Plot-a-parabola-with-scaled-x-axis,-lines-and-legend-1">Plot a parabola with scaled x axis, lines and legend</a><a class="docs-heading-anchor-permalink" href="#Plot-a-parabola-with-scaled-x-axis,-lines-and-legend-1" title="Permalink"></a></h4><pre><code class="language-julia">x = 1:20
|
|
@gp "set key left" x ./ 20 x.^2 "with lines tit 'Parabola'"</code></pre><p><img src="../assets/basic5.png" alt/></p><hr/><h4 id="Multiple-datasets,-logarithmic-axis,-labels-and-colors,-etc.-1"><a class="docs-heading-anchor" href="#Multiple-datasets,-logarithmic-axis,-labels-and-colors,-etc.-1">Multiple datasets, logarithmic axis, labels and colors, etc.</a><a class="docs-heading-anchor-permalink" href="#Multiple-datasets,-logarithmic-axis,-labels-and-colors,-etc.-1" title="Permalink"></a></h4><pre><code class="language-julia">x = 1:0.1:10
|
|
@gp "set grid" "set key left" "set logscale y"
|
|
@gp :- "set title 'Plot title'" "set label 'X label'" "set xrange [0:12]"
|
|
@gp :- x x.^0.5 "w l tit 'Pow 0.5' dt 2 lw 2 lc rgb 'red'"
|
|
@gp :- x x "w l tit 'Pow 1' dt 1 lw 3 lc rgb 'blue'"
|
|
@gp :- x x.^2 "w l tit 'Pow 2' dt 3 lw 2 lc rgb 'purple'"</code></pre><p><img src="../assets/basic6.png" alt/></p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>The above example lacks the trailing <code>:-</code> symbol. This means the plot will be updated at each command, adding one curve at a time.</p></div></div><hr/><h2 id="Keywords-for-common-commands-1"><a class="docs-heading-anchor" href="#Keywords-for-common-commands-1">Keywords for common commands</a><a class="docs-heading-anchor-permalink" href="#Keywords-for-common-commands-1" title="Permalink"></a></h2><p>In order to avoid typing long, and very frequently used <code>gnuplot</code> commands, <strong>Gnuplot.jl</strong> provides a few keywords which can be used in both <code>@gp</code> and <code>@sgp</code> calls:</p><ul><li><code>xrange=[low, high]</code> => <code>"set xrange [low:high]</code>;</li><li><code>yrange=[low, high]</code> => <code>"set yrange [low:high]</code>;</li><li><code>zrange=[low, high]</code> => <code>"set zrange [low:high]</code>;</li><li><code>cbrange=[low, high]</code>=> <code>"set cbrange[low:high]</code>;</li><li><code>key="..."</code> => <code>"set key ..."</code>;</li><li><code>title="..."</code> => <code>"set title \"...\""</code>;</li><li><code>xlabel="..."</code> => <code>"set xlabel \"...\""</code>;</li><li><code>ylabel="..."</code> => <code>"set ylabel \"...\""</code>;</li><li><code>zlabel="..."</code> => <code>"set zlabel \"...\""</code>;</li><li><code>xlog=true</code> => <code>set logscale x</code>;</li><li><code>ylog=true</code> => <code>set logscale y</code>;</li><li><code>zlog=true</code> => <code>set logscale z</code>;</li></ul><p>All such keywords can be abbreviated to unambiguous names.</p><p>By using the above keywords the first lines of the previous example:</p><pre><code class="language-julia">@gp "set grid" "set key left" "set logscale y"
|
|
@gp :- "set title 'Plot title'" "set label 'X label'" "set xrange [0:12]"</code></pre><p>can be replaced with a shorter version:</p><pre><code class="language-julia">@gp "set grid" k="left" ylog=true
|
|
@gp :- tit="Plot title" xlab="X label" xr=[0,12]</code></pre><h2 id="Plot-images-1"><a class="docs-heading-anchor" href="#Plot-images-1">Plot images</a><a class="docs-heading-anchor-permalink" href="#Plot-images-1" title="Permalink"></a></h2><p><strong>Gnuplot.jl</strong> can also display images, i.e. 2D arrays:</p><pre><code class="language-julia">img = randn(Float64, 30, 50)
|
|
img[10,:] .= -4
|
|
@gp img "w image notit"</code></pre><p><img src="../assets/basic7a.png" alt/></p><p>Note that the first index corresponds to the <code>X</code> coordinate when the image is displayed.</p><p>The following example shows how to fix orientation of an image by means of the <code>using</code> clause (the <code>TestImages</code> package is required to run this example):</p><pre><code class="language-julia">using TestImages
|
|
img = testimage("lena");
|
|
@gp "set size square" "set autoscale fix" img "u 2:(-\$1):3:4:5 with rgbimage notit"</code></pre><p><img src="../assets/basic7b.jpg" alt/></p><h2 id="plots3d-1"><a class="docs-heading-anchor" href="#plots3d-1">3D plots</a><a class="docs-heading-anchor-permalink" href="#plots3d-1" title="Permalink"></a></h2><p>3D plots follow the same rules as 2D ones, just replace the <code>@gp</code> macro with <code>@gsp</code> and add the required columns (according to the plotting style).</p><p>E.g., to plot a spiral increasing in size along the <code>X</code> direction:</p><pre><code class="language-julia">x = 0:0.1:10pi
|
|
@gsp x sin.(x) .* x cos.(x) .* x x./20 "w p pt 7 ps var lc pal"</code></pre><p><img src="../assets/basic8.png" alt/></p><p>The keywords discussed above can also be used in 3D plots.</p><h2 id="Palettes-and-line-types-1"><a class="docs-heading-anchor" href="#Palettes-and-line-types-1">Palettes and line types</a><a class="docs-heading-anchor-permalink" href="#Palettes-and-line-types-1" title="Permalink"></a></h2><p>The <strong>Gnuplot.jl</strong> package comes with all the <a href="https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1">ColorSchemes</a> palettes readily available.</p><p>A <code>gnuplot</code>-compliant palette can be retrieved with <code>palette()</code>, and used as any other command. The previous example may use an alternative palette with:</p><pre><code class="language-julia">x = 0:0.1:10pi
|
|
@gsp palette(:viridis) x sin.(x) .* x cos.(x) .* x x./20 "w p pt 7 ps var lc pal"</code></pre><p><img src="../assets/basic8a.png" alt/></p><p>The <a href="https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1">ColorSchemes</a> palettes can also be used to generate line types (actually just color attributes), by means of the <code>linetypes()</code> function, e.g.</p><pre><code class="language-julia">@gp linetypes(:deepsea)
|
|
x = 1:0.1:4pi
|
|
for i in 1:5
|
|
@gp :- x i.* sin.(x) "w l notit lw 5"
|
|
end</code></pre><p><img src="../assets/basic9.png" alt/></p><h2 id="Exporting-plots-to-files-1"><a class="docs-heading-anchor" href="#Exporting-plots-to-files-1">Exporting plots to files</a><a class="docs-heading-anchor-permalink" href="#Exporting-plots-to-files-1" title="Permalink"></a></h2><p>The <code>save()</code> function allows to export all plots (as well as multiplots, see <a href="../advanced/#Multiplot-1">Multiplot</a>) to a file using one of the many available <code>gnuplot</code> terminals. To check which terminals are available in your platform type <code>set term</code> in your <code>gnuplot</code> terminal.</p><p>All plots in this page have been saved with:</p><pre><code class="language-julia">save(term="pngcairo size 480,360", output="assets/output.png")</code></pre><p>except the <em>Lena</em> image, saved with the <code>jpeg</code> terminal:</p><pre><code class="language-julia">save(term="jpeg size 480,360", output="assets/output.png")</code></pre><h2 id="Gnuplot-scripts-1"><a class="docs-heading-anchor" href="#Gnuplot-scripts-1">Gnuplot scripts</a><a class="docs-heading-anchor-permalink" href="#Gnuplot-scripts-1" title="Permalink"></a></h2><p>Besides exporting plots in a file <strong>Gnuplot.jl</strong> can also save a <em>script</em>, i.e. a file containing the minimum set of data and commands required to generate a plot within <code>gnuplot</code>.</p><p>To generate a script for one of the example above use:</p><pre><code class="language-julia">save("script.gp")</code></pre><p>after the plot has been displayed. The script can then be used within a <code>gnuplot</code> session as follows:</p><pre><code class="language-none">gunplot> load 'script.gp'</code></pre><p>to generate a plot identical to the original one, without using the Julia language.</p><p>The purpose of <code>gnuplot</code> scripts is to allow sharing all data, alongside a plot, in order to foster collaboration among scientists and replicability of results. Moreover, a script can be used at any time to change the details of a plot, without the need to re-run the Julia code used to generate it the first time.</p><p>Finally, the scripts are the only possible output when <a href="../advanced/#Dry-sessions-1">Dry sessions</a> are used (i.e. when <code>gnuplot</code> is not available in the user platform.</p><section class="footnotes is-size-7"><ul><li class="footnote" id="footnote-1"><a class="tag is-link" href="#citeref-1">1</a>a previous knowledge of <a href="http://gnuplot.sourceforge.net/documentation.html"><code>gnuplot</code></a> usage is, nevertheless, required.</li></ul></section></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../install/">« Installation</a><a class="docs-footer-nextpage" href="../advanced/">Advanced techniques »</a></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> on <span class="colophon-date" title="Thursday 26 March 2020 12:59">Thursday 26 March 2020</span>. Using Julia version 1.3.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|