mantao/Gnuplot.jl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Gnuplot.jl/v1.2.0/search_index.js
Giorgio Calderone dedf32715d Release v1.2.0
2020-04-20 18:46:36 +02:00

4 lines
101 KiB
JavaScript
Raw Blame History

var documenterSearchIndex = {"docs":
[{"location":"style/#Style-Guide-1","page":"Style guide","title":"Style Guide","text":"","category":"section"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"The Gnuplot.jl loose syntax allows to create a plot using very different approaches. While this was one of the initial purposes for the package, it may lead to decreased code readability if not used judiciously.","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"Here I will summarize a few, non-mandatory, guidelines which allows to maintain a neat syntax and a high readability:","category":"page"},{"location":"style/#Use-macros-without-parentheses-and-commas:-1","page":"Style guide","title":"1 - Use macros without parentheses and commas:","text":"","category":"section"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"The two most important symbols exported by the package (@gp and @gsp) are macros. As such they are supposed to be invoked without parentheses and commas. E.g. use:","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp x y \"with lines\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"in place of","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp(x, y, \"with lines\")","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"If you have very long lines you may split them in multiple statements using the :- symbol, which resembles both hyphenation in natural language and indentation for the plot-producing code:","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp \"set grid\" :-\n@gp :- x y \"with lines\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"Note that the trailing :- symbol is not mandatory. If omitted, the plot will be updated at each statement (rather than at the last one).","category":"page"},{"location":"style/#Use-keywords-in-place-of-gnuplot-commands:-1","page":"Style guide","title":"2 - Use keywords in place of gnuplot commands:","text":"","category":"section"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"As discussed in Keywords for common commands several commonly used gnuplot commands can be replaced with a keyword. E.g. you can use","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp ... xrange=[-1,5] ...","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"in place of","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp ... \"set xrange [-1:5]\" ...","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"This help reducing the number of strings, as well as the associated interpolating characters ($), and results in a more concise syntax.","category":"page"},{"location":"style/#Use-abbreviations-for-commands-and-keywords:-1","page":"Style guide","title":"3 - Use abbreviations for commands and keywords:","text":"","category":"section"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"Many gnuplot commands, as well as all keywords (see Keywords for common commands), can be abbreviated as long as the abbreviation is unambiguous. E.g., the following code:","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp \"set grid\" \"set key left\" \"set logscale y\"\n@gp :- \"set title 'Plot title'\" \"set label 'X label'\" \"set xrange [0:*]\"\n@gp :- x y \"with lines\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"can be replaced with a shorter version:","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp \"set grid\" k=\"left\" ylog=true\n@gp :- tit=\"Plot title\" xlab=\"X label\" xr=[0,NaN]\n@gp :- x y \"w l\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"Besides being more idiomatic, the possibility to exploit abbreviations is of great importance when performing interactive data exploration.","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"Moreover, in many gnuplot examples and documentation it is very common to use abbreviations (i.e. w l in place of with lines) so there is no reason to avoid them in Gnuplot.jl.","category":"page"},{"location":"style/#If-possible,-follow-the-*commands*-*data*-*plot-specs*-order-1","page":"Style guide","title":"4 - If possible, follow the commands -> data + plot specs order","text":"","category":"section"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"The two following examples produce exactly the same plot:","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"x = -10.:10\n@gp \"set grid\" \"set multiplot layout 2,1\"\n@gp :- 1 x x.^2 \"w l t 'f(x) = x^2\" # first plot\n@gp :- 2 x x.^3 \"w l t 'f(x) = x^3\" # second plot","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"and","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp 2 x x.^3 \"w l t 'f(x) = x^3\" # second plot\n@gp :- 1 x x.^2 \"w l t 'f(x) = x^2\" # first plot\n@gp :- \"set grid\" \"set multiplot layout 2,1\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"However, the first form appears more logical and easy to follow.","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"In analogy with previous example, even on single plot, the following form","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp \"set grid\"\n@gp :- x x.^2 \"w l t 'f(x) = x^2\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"should be preferred over","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp x x.^2 \"w l t 'f(x) = x^2\"\n@gp :- \"set grid\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"even if the output is exactly the same.","category":"page"},{"location":"style/#Join-multiple-command-strings:-1","page":"Style guide","title":"5 - Join multiple command strings:","text":"","category":"section"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"Instead of specifying several commands as strings","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp :- \"set key off\" \"set auto fix\" \"set size square\"\n@gp :- \"set offsets graph .05, graph .05, graph .05, graph .05\"\n@gp :- \"set border lw 1 lc rgb 'white'\"","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"join them in a single string using triple quotes and ;","category":"page"},{"location":"style/#","page":"Style guide","title":"Style guide","text":"@gp :- \"\"\"set key off; set auto fix; set size square;\n set offsets graph .05, graph .05, graph .05, graph .05;\n set border lw 1 lc rgb 'white'; \"\"\"","category":"page"},{"location":"api/#API-1","page":"API","title":"API","text":"","category":"section"},{"location":"api/#Index-1","page":"API","title":"Index","text":"","category":"section"},{"location":"api/#","page":"API","title":"API","text":"","category":"page"},{"location":"api/#Exported-symbols-1","page":"API","title":"Exported symbols","text":"","category":"section"},{"location":"api/#","page":"API","title":"API","text":"The list of Gnuplot.jl exported symbols is as follows:","category":"page"},{"location":"api/#","page":"API","title":"API","text":"@gp\n@gsp\nboxxy\ncontourlines\ndataset_names\ngpexec\ngpmargins\ngpranges\ngpvars\nhist\nlinetypes\npalette\npalette_names\nrecipe\nsave\nsession_names\nstats\nterminals\nterminal\ntest_terminal","category":"page"},{"location":"api/#Gnuplot.@gp","page":"API","title":"Gnuplot.@gp","text":"@gp args...\n\nThe @gp macro, and its companion @gsp for 3D plots, allows to send data and commands to the gnuplot using an extremely concise syntax. The macros accepts any number of arguments, with the following meaning:\n\none, or a group of consecutive, array(s) of either Real or String build up a dataset. The different arrays are accessible as columns 1, 2, etc. from the gnuplot process. The number of required input arrays depends on the chosen plot style (see gnuplot documentation);\na string occurring before a dataset is interpreted as a gnuplot command (e.g. set grid);\na string occurring immediately after a dataset is interpreted as a plot element for the dataset, by which you can specify using clause, with clause, line styles, etc.. All keywords may be abbreviated following gnuplot conventions. Moreover, \"plot\" and \"splot\" can be abbreviated to \"p\" and \"s\" respectively;\nthe special symbol :- allows to split one long statement into multiple (shorter) ones. If given as first argument it avoids starting a new plot. If it given as last argument it avoids immediately running all commands to create the final plot;\nany other symbol is interpreted as a session ID;\nan Int (>= 1) is interpreted as the plot destination in a multi-plot session (this specification applies to subsequent arguments, not previous ones);\nan input in the form \"\\$name\"=>(array1, array2, etc...) is interpreted as a named dataset. Note that the dataset name must always start with a \"$\";\nan input in the form keyword=value is interpreted as a keyword/value pair. The accepted keywords and their corresponding gnuplot commands are as follows:\nxrange=[low, high] => \"set xrange [low:high];\nyrange=[low, high] => \"set yrange [low:high];\nzrange=[low, high] => \"set zrange [low:high];\ncbrange=[low, high]=> \"set cbrange[low:high];\nkey=\"...\" => \"set key ...\";\ntitle=\"...\" => \"set title \"...\"\";\nxlabel=\"...\" => \"set xlabel \"...\"\";\nylabel=\"...\" => \"set ylabel \"...\"\";\nzlabel=\"...\" => \"set zlabel \"...\"\";\ncblabel=\"...\" => \"set cblabel \"...\"\";\nxlog=true => set logscale x;\nylog=true => set logscale y;\nzlog=true => set logscale z.\ncblog=true => set logscale cb;\nmargins=... => set margins ...;\nlmargin=... => set lmargin ...;\nrmargin=... => set rmargin ...;\nbmargin=... => set bmargin ...;\ntmargin=... => set tmargin ...;\n\nAll Keyword names can be abbreviated as long as the resulting name is unambiguous. E.g. you can use xr=[1,10] in place of xrange=[1,10].\n\na PlotElement object is expanded in its fields and processed as one of the previous arguments;\nany other data type is processed through an implicit recipe. If a suitable recipe do not exists an error is raised.\n\n\n\n\n\n","category":"macro"},{"location":"api/#Gnuplot.@gsp","page":"API","title":"Gnuplot.@gsp","text":"@gsp args...\n\nThis macro accepts the same syntax as @gp, but produces a 3D plot instead of a 2D one.\n\n\n\n\n\n","category":"macro"},{"location":"api/#Gnuplot.boxxy","page":"API","title":"Gnuplot.boxxy","text":"boxxy(x, y; xmin=NaN, ymin=NaN, xmax=NaN, ymax=NaN, cartesian=false)\nboxxy(h::Histogram2D)\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.contourlines","page":"API","title":"Gnuplot.contourlines","text":"contourlines(x::Vector{Float64}, y::Vector{Float64}, z::Matrix{Float64}, cntrparam=\"level auto 10\")\ncontourlines(h::Histogram2D, cntrparam=\"level auto 10\")\n\nCompute paths of contour lines for 2D data, and return a vector of IsoContourLines object.\n\nnote: Note\nThis feature is not available in dry mode and will raise an error if used.\n\nArguments:\n\nx, y: Coordinates;\nz: the levels on which iso contour lines are to be calculated\ncntrparam: settings to compute contour line paths (see gnuplot documentation for cntrparam).\n\nExample\n\nx = randn(5000);\ny = randn(5000);\nh = hist(x, y, nbins1=20, nbins2=20);\nclines = contourlines(h, \"levels discrete 15, 30, 45\");\n\n# Use implicit recipe\n@gp clines\n\n# ...or use IsoContourLines fields:\n@gp \"set size ratio -1\"\nfor i in 1:length(clines)\n @gp :- clines[i].data \"w l t '$(clines[i].z)' lw $i dt $i\"\nend\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.dataset_names","page":"API","title":"Gnuplot.dataset_names","text":"dataset_names(sid::Symbol)\ndataset_names()\n\nReturn a vector with all dataset names for the sid session. If sid is not provided the default session is considered.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.gpexec","page":"API","title":"Gnuplot.gpexec","text":"gpexec(sid::Symbol, command::String)\ngpexec(command::String)\n\nExecute the gnuplot command command on the underlying gnuplot process of the sid session, and return the results as a Vector{String}. If a gnuplot error arises it is propagated as an ErrorException.\n\nIf the sid argument is not provided, the default session is considered.\n\nExamples:\n\ngpexec(\"print GPVAL_TERM\")\ngpexec(\"plot sin(x)\")\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.gpmargins","page":"API","title":"Gnuplot.gpmargins","text":"gpmargins(sid::Symbol)\ngpmargins()\n\nReturn a NamedTuple with keys l, r, b and t containing respectively the left, rigth, bottom and top margins of the current plot (in screen coordinates).\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.gpranges","page":"API","title":"Gnuplot.gpranges","text":"gpranges(sid::Symbol)\ngpranges()\n\nReturn a NamedTuple with keys x, y, z and cb containing respectively the current plot ranges for the X, Y, Z and color box axis.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.gpvars","page":"API","title":"Gnuplot.gpvars","text":"gpvars(sid::Symbol)\ngpvars()\n\nReturn a NamedTuple with all currently defined gnuplot variables. If the sid argument is not provided, the default session is considered.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.hist","page":"API","title":"Gnuplot.hist","text":"hist(v::Vector{T}; range=extrema(v), bs=NaN, nbins=0, pad=true) where T <: Real\n\nCalculates the histogram of the values in v and returns a Histogram1D structure.\n\nArguments\n\nv: a vector of values to compute the histogra;\nrange: values of the left edge of the first bin and of the right edge of the last bin;\nbs: size of histogram bins;\nnbins: number of bins in the histogram;\npad: if true add one dummy bins with zero counts before the first bin and after the last.\n\nIf bs is given nbins is ignored.\n\nExample\n\nv = randn(1000)\nh = hist(v, bs=0.5)\n@gp h # preview\n@gp h.bins h.counts \"w histep notit\"\n\n\n\n\n\nhist(v1::Vector{T1 <: Real}, v2::Vector{T2 <: Real}; range1=[NaN,NaN], bs1=NaN, nbins1=0, range2=[NaN,NaN], bs2=NaN, nbins2=0)\n\nCalculates the 2D histogram of the values in v1 and v2 and returns a Histogram2D structure.\n\nArguments\n\nv1: a vector of values along the first dimension;\nv2: a vector of values along the second dimension;\nrange1: values of the left edge of the first bin and of the right edge of the last bin, along the first dimension;\nrange1: values of the left edge of the first bin and of the right edge of the last bin, along the second dimension;\nbs1: size of histogram bins along the first dimension;\nbs2: size of histogram bins along the second dimension;\nnbins1: number of bins along the first dimension;\nnbins2: number of bins along the second dimension;\n\nIf bs1 (bs2) is given nbins1 (nbins2) is ignored.\n\nExample\n\nv1 = randn(1000)\nv2 = randn(1000)\nh = hist(v1, v2, bs1=0.5, bs2=0.5)\n@gp h # preview\n@gp \"set size ratio -1\" \"set auto fix\" h.bins1 h.bins2 h.counts \"w image notit\"\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.linetypes","page":"API","title":"Gnuplot.linetypes","text":"linetypes(cmap::ColorScheme; lw=1, ps=1, dashed=false, rev=false)\nlinetypes(s::Symbol; lw=1, ps=1, dashed=false, rev=false)\n\nConvert a ColorScheme object into a string containing the gnuplot commands to set up linetype colors.\n\nIf the argument is a Symbol it is interpreted as the name of one of the predefined schemes in ColorSchemes.\n\nIf rev=true the line colors are reversed. If a numeric or string value is provided through the lw and ps keywords thay are used to set the line width and the point size respectively. If dashed is true the linetypes with index greater than 1 will be displayed with dashed pattern.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.palette","page":"API","title":"Gnuplot.palette","text":"palette(cmap::ColorScheme; rev=false)\npalette(s::Symbol; rev=false)\n\nConvert a ColorScheme object into a string containing the gnuplot commands to set up the corresponding palette.\n\nIf the argument is a Symbol it is interpreted as the name of one of the predefined schemes in ColorSchemes. If rev=true the palette is reversed.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.palette_names","page":"API","title":"Gnuplot.palette_names","text":"palette_names()\n\nReturn a vector with all available color schemes for the palette and linetypes function.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.recipe","page":"API","title":"Gnuplot.recipe","text":"recipe(h::Histogram1D)\nrecipe(h::Histogram2D)\n\nImplicit recipes to visualize 1D and 2D histograms.\n\n\n\n\n\nrecipe(c::IsoContourLines)\nrecipe(v::Vector{IsoContourLines})\n\nImplicit recipes to visualize iso-contour lines.\n\n\n\n\n\nrecipe(M::Matrix{ColorTypes.RGB{T}}, opt=\"flipy\")\nrecipe(M::Matrix{ColorTypes.RGBA{T}}, opt=\"flipy\")\nrecipe(M::Matrix{ColorTypes.Gray{T}}, opt=\"flipy\")\nrecipe(M::Matrix{ColorTypes.GrayA{T}}, opt=\"flipy\")\n\nImplicit recipes to show images.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.save","page":"API","title":"Gnuplot.save","text":"save(sid::Symbol; term=\"\", output=\"\")\nsave(sid::Symbol, script_filename::String, ;term=\"\", output=\"\")\nsave(; term=\"\", output=\"\")\nsave(script_filename::String ;term=\"\", output=\"\")\n\nExport a (multi-)plot into the external file name provided in the output= keyword. The gnuplot terminal to use is provided through the term= keyword.\n\nIf the script_filename argument is provided a gnuplot script will be written in place of the output image. The latter can then be used in a pure gnuplot session (Julia is no longer needed) to generate exactly the same original plot.\n\nIf the sid argument is provided the operation applies to the corresponding session.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.session_names","page":"API","title":"Gnuplot.session_names","text":"session_names()\n\nReturn a vector with all currently active sessions.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.stats","page":"API","title":"Gnuplot.stats","text":"stats(sid::Symbol,name::String)\nstats(name::String)\nstats(sid::Symbol)\nstats()\n\nPrint a statistical summary for the name dataset, belonging to sid session. If name is not provdied a summary is printed for each dataset in the session. If sid is not provided the default session is considered.\n\nThis function is actually a wrapper for the gnuplot command stats.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.terminals","page":"API","title":"Gnuplot.terminals","text":"terminals()\n\nReturn a Vector{String} with the names of all the available gnuplot terminals.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.terminal","page":"API","title":"Gnuplot.terminal","text":"terminal(sid::Symbol)\nterminal()\n\nReturn a String with the current gnuplot terminal (and its options) of the process associated to session sid, or to the default session (if sid is not provided).\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.test_terminal","page":"API","title":"Gnuplot.test_terminal","text":"test_terminal(term=nothing; linetypes=nothing, palette=nothing)\n\nRun the test and test palette commands on a gnuplot terminal.\n\nIf no term is given it will use the default terminal. If lt and pal are given they are used as input to the linetypes and palette function repsetcively to load the associated color scheme.\n\nExamples\n\ntest_terminal()\ntest_terminal(\"wxt\", lt=:rust, pal=:viridis)\n\n\n\n\n\n","category":"function"},{"location":"api/#Non-exported-symbols-1","page":"API","title":"Non-exported symbols","text":"","category":"section"},{"location":"api/#","page":"API","title":"API","text":"The following functions are not exported by the Gnuplot.jl package since they are typically not used in every day work, or aimed to debugging purposes. Still, they can be useful in some case, hence they are documented here.","category":"page"},{"location":"api/#","page":"API","title":"API","text":"In order to call these functions you should add the Gnuplot. prefix to the function name.","category":"page"},{"location":"api/#","page":"API","title":"API","text":"Gnuplot.Dataset\nGnuplot.DatasetEmpty\nGnuplot.DatasetText\nGnuplot.DatasetBin\nGnuplot.Histogram1D\nGnuplot.Histogram2D\nGnuplot.IsoContourLines\nGnuplot.Options\nGnuplot.Path2d\nGnuplot.PlotElement\nGnuplot.gpversion\nGnuplot.quit\nGnuplot.quitall\nGnuplot.repl_init\nGnuplot.version","category":"page"},{"location":"api/#Gnuplot.Dataset","page":"API","title":"Gnuplot.Dataset","text":"Dataset\n\nAbstract type for all dataset structures.\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.DatasetEmpty","page":"API","title":"Gnuplot.DatasetEmpty","text":"DatasetEmpty\n\nAn empty dataset.\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.DatasetText","page":"API","title":"Gnuplot.DatasetText","text":"DatasetText\n\nA dataset whose data are stored as a text buffer.\n\nTransmission to gnuplot may be slow for large datasets, but no temporary file is involved, and the dataset can be saved directly into a gnuplot script. Also, the constructor allows to build more flexible datasets (i.e. mixing arrays with different dimensions).\n\nConstructors are defined as follows:\n\nDatasetText(data::Vector{String})\nDatasetText(data::Vararg{AbstractArray, N}) where N =\n\nIn the second form the type of elements of each array must be one of Real, AbstractString and Missing.\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.DatasetBin","page":"API","title":"Gnuplot.DatasetBin","text":"DatasetBin\n\nA dataset whose data are stored as a binary file.\n\nEnsure best performances for large datasets, but involve use of a temporary files. When saving a script the file is stored in a directory with the same name as the main script file.\n\nConstructors are defined as follows:\n\nDatasetBin(cols::Vararg{AbstractMatrix, N}) where N\nDatasetBin(cols::Vararg{AbstractVector, N}) where N\n\nIn both cases the element of the arrays must be a numeric type.\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.Histogram1D","page":"API","title":"Gnuplot.Histogram1D","text":"Histogram1D\n\nA 1D histogram data.\n\nFields\n\nbins::Vector{Float64}: bin center values;\ncounts::Vector{Float64}: counts in the bins;\nbinsize::Float64: size of each bin;\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.Histogram2D","page":"API","title":"Gnuplot.Histogram2D","text":"Histogram2D\n\nA 2D histogram data.\n\nFields\n\nbins1::Vector{Float64}: bin center values along first dimension;\nbins2::Vector{Float64}: bin center values along second dimension;\ncounts::Vector{Float64}: counts in the bins;\nbinsize1::Float64: size of each bin along first dimension;\nbinsize2::Float64: size of each bin along second dimension;\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.IsoContourLines","page":"API","title":"Gnuplot.IsoContourLines","text":"IsoContourLines\n\nCoordinates of all contour lines of a given level.\n\nFields\n\npaths::Vector{Path2d}: vector of Path2d objects, one for each continuous path;\ndata::Vector{String}: vector with string representation of all paths (ready to be sent to gnuplot);\nz::Float64: level of the contour lines.\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.Options","page":"API","title":"Gnuplot.Options","text":"Options\n\nStructure containing the package global options, accessible through Gnuplot.options.\n\nFields\n\ndry::Bool: whether to use dry sessions, i.e. without an underlying Gnuplot process (default: false)\ncmd::String: command to start the Gnuplot process (default: \"gnuplot\")\ndefault::Symbol: default session name (default: :default)\nterm::String: default terminal for interactive use (default: empty string, i.e. use gnuplot settings);\nterm_svg::String: terminal to save png files (default \"svg background rgb 'white' dynamic\");\nterm_png::String: terminal to save png files (default \"pngcairo\");\ninit::Vector{String}: commands to initialize the session when it is created or reset (e.g., to set default palette);\nverbose::Bool: verbosity flag (default: false)\npreferred_format::Symbol: preferred format to send data to gnuplot. Value must be one of:\nbin: fastest solution for large datasets, but uses temporary files;\ntext: may be slow for large datasets, but no temporary file is involved;\nauto (default) automatically choose the best strategy.\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.Path2d","page":"API","title":"Gnuplot.Path2d","text":"Path2d\n\nA path in 2D.\n\nFields\n\nx::Vector{Float64}\ny::Vector{Float64}\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.PlotElement","page":"API","title":"Gnuplot.PlotElement","text":"PlotElement\n\nStructure containing element(s) of a plot (commands, data, plot specifications) that can be used directly in @gp and @gsp calls.\n\nFields\n\nmid::Int: multiplot ID (use 0 for single plots);\nis3d::Bool: true if the data are supposed to be displayed in a 3D plot;\ncmds::Vector{String}: commands to set plot properties;\nname::String: name of the dataset (use \"\" to automatically generate a unique name);\ndata::Dataset: a dataset\nplot::Vector{String}: plot specifications for the associated Dataset;\n\nThe constructor is defined as follows:\n\nPlotElement(;mid::Int=0, is3d::Bool=false,\n cmds::Union{String, Vector{String}}=Vector{String}(),\n name::String=\"\",\n data::Dataset=DatasetEmpty(),\n plot::Union{String, Vector{String}}=Vector{String}(),\n kwargs...)\n\nNo field is mandatory, i.e. even Gnuplot.PlotElement() provides a valid structure. The constructor also accept all the keywords accepted by parseKeywords.\n\n\n\n\n\n","category":"type"},{"location":"api/#Gnuplot.gpversion","page":"API","title":"Gnuplot.gpversion","text":"Gnuplot.gpversion()\n\nReturn the gnuplot application version.\n\nRaise an error if version is < 5.0 (required to use data blocks).\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.quit","page":"API","title":"Gnuplot.quit","text":"Gnuplot.quit(sid::Symbol)\n\nQuit the session identified by sid and the associated gnuplot process (if any).\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.quitall","page":"API","title":"Gnuplot.quitall","text":"Gnuplot.quitall()\n\nQuit all the sessions and the associated gnuplot processes.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.repl_init","page":"API","title":"Gnuplot.repl_init","text":"Gnuplot.init_repl(; start_key='>')\n\nInstall a hook to replace the common Julia REPL with a gnuplot one. The key to start the REPL is the one provided in start_key (default: >).\n\nNote: the gnuplot REPL operates only on the default session.\n\n\n\n\n\n","category":"function"},{"location":"api/#Gnuplot.version","page":"API","title":"Gnuplot.version","text":"Gnuplot.version()\n\nReturn the Gnuplot.jl package version.\n\n\n\n\n\n","category":"function"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"using Gnuplot\nGnuplot.quitall()\nmkpath(\"assets\")\nGnuplot.splash(\"assets/logo.png\")\nGnuplot.options.term = \"unknown\"\nempty!(Gnuplot.options.init)\npush!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))\nsaveas(file) = save(term=\"pngcairo size 550,350 fontscale 0.8\", output=\"assets/$(file).png\")","category":"page"},{"location":"basic/#Basic-usage-1","page":"Basic usage","title":"Basic usage","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The main purpose of the Gnuplot.jl package is to send data and commands to the underlying gnuplot 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 Gnuplot.jl easy to learn and use: there are no functions or keywords names to memorize[1].","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The most important symbols exported by the package are the @gp (for 2D plots) and @gsp (for 3D plots) macros. The simplemost example is as follows:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"using Gnuplot\n@gp 1:20\nsaveas(\"basic000\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The plots are displayed either in an interactive window (if running in the Julia REPL), as an inline image (if running in Jupyter) or in the plot pane (if running in Juno). See Options and Jupyter and Juno for further informations.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Both the @gp and @gsp macros accept any number of arguments, whose meaning is interpreted as follows:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"one, or a group of consecutive, array(s) build up a dataset. The different arrays are accessible as columns 1, 2, etc. from the gnuplot process. The number of required input arrays depends on the chosen plot style (see gnuplot documentation);\na string occurring before a dataset is interpreted as a gnuplot command (e.g. set grid);\na string occurring immediately after a dataset is interpreted as a plot element for the dataset, by which you can specify using clause, with clause, line styles, etc.;\nthe special symbol :-, 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.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The above list shows all the fundamental concepts to follow the examples presented below. The @gp and @gsp macros also accepts further arguments, but their use will be discussed in Advanced usage.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"[1]: a previous knowledge of gnuplot usage is, nevertheless, required.","category":"page"},{"location":"basic/#plots2d-1","page":"Basic usage","title":"2D plots","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Here we will show a few examples to generate 2D plots. The examples are intentionally very simple to highlight the behavior of Gnuplot.jl. See Examples for more complex ones.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Remember to run:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"using Gnuplot","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"before running the examples.","category":"page"},{"location":"basic/#Simple-examples-involving-just-gnuplot-commands:-1","page":"Basic usage","title":"Simple examples involving just gnuplot commands:","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"","category":"page"},{"location":"basic/#Plot-a-sinusoid:-1","page":"Basic usage","title":"Plot a sinusoid:","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp \"plot sin(x)\"\nsaveas(\"basic001\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"","category":"page"},{"location":"basic/#Plot-two-curves:-1","page":"Basic usage","title":"Plot two curves:","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp \"set key left\" \"plot sin(x)\" \"pl cos(x)\"\nsaveas(\"basic002\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"note: Note\nNote that all gnuplot commands can be abbreviated as long as the resulting string is not ambiguous. In the example above we used pl in place of plot.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"","category":"page"},{"location":"basic/#Split-a-@gp-call-in-three-statements:-1","page":"Basic usage","title":"Split a @gp call in three statements:","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp \"set grid\" :-\n@gp :- \"p sin(x)\" :-\n@gp :- \"plo cos(x)\"\nsaveas(\"basic003\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"note: Note\nThe trailing :- symbol means the plot will not be updated until the last statement.","category":"page"},{"location":"basic/#Send-data-from-Julia-to-gnuplot:-1","page":"Basic usage","title":"Send data from Julia to gnuplot:","text":"","category":"section"},{"location":"basic/#Plot-a-parabola-1","page":"Basic usage","title":"Plot a parabola","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp (1:20).^2\nsaveas(\"basic004\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"","category":"page"},{"location":"basic/#Plot-a-parabola-with-scaled-x-axis,-lines-and-legend-1","page":"Basic usage","title":"Plot a parabola with scaled x axis, lines and legend","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"x = 1:20\n@gp \"set key left\" x ./ 20 x.^2 \"with lines tit 'Parabola'\"\nsaveas(\"basic005\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"","category":"page"},{"location":"basic/#Multiple-datasets,-logarithmic-axis,-labels-and-colors,-etc.-1","page":"Basic usage","title":"Multiple datasets, logarithmic axis, labels and colors, etc.","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"x = 1:0.1:10\n@gp \"set grid\" \"set key left\" \"set logscale y\"\n@gp :- \"set title 'Plot title'\" \"set label 'X label'\" \"set xrange [0:*]\"\n@gp :- x x.^0.5 \"w l tit 'Pow 0.5' dt 2 lw 2 lc rgb 'red'\"\n@gp :- x x \"w l tit 'Pow 1' dt 1 lw 3 lc rgb 'blue'\"\n@gp :- x x.^2 \"w l tit 'Pow 2' dt 3 lw 2 lc rgb 'purple'\"\nsaveas(\"basic006\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"note: Note\nThe above example lacks the trailing :- symbol. This means the plot will be updated at each command, adding one curve at a time.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"","category":"page"},{"location":"basic/#Keywords-for-common-commands-1","page":"Basic usage","title":"Keywords for common commands","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"In order to avoid typing long, and very frequently used gnuplot commands, Gnuplot.jl provides a few keywords which can be used in both @gp and @sgp calls:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"xrange=[low, high] => \"set xrange [low:high];\nyrange=[low, high] => \"set yrange [low:high];\nzrange=[low, high] => \"set zrange [low:high];\ncbrange=[low, high]=> \"set cbrange[low:high];\nkey=\"...\" => \"set key ...\";\ntitle=\"...\" => \"set title \\\"...\\\"\";\nxlabel=\"...\" => \"set xlabel \\\"...\\\"\";\nylabel=\"...\" => \"set ylabel \\\"...\\\"\";\nzlabel=\"...\" => \"set zlabel \\\"...\\\"\";\ncblabel=\"...\" => \"set cblabel \\\"...\\\"\";\nxlog=true => set logscale x;\nylog=true => set logscale y;\nzlog=true => set logscale z;\nmargins=... => set margins ...;\nlmargin=... => set lmargin ...;\nrmargin=... => set rmargin ...;\nbmargin=... => set bmargin ...;\ntmargin=... => set tmargin ...;","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"All such keywords can be abbreviated to unambiguous names.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"By using the above keywords the first lines of the previous example:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp \"set grid\" \"set key left\" \"set logscale y\"\n@gp :- \"set title 'Plot title'\" \"set label 'X label'\" \"set xrange [0:*]\"","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"can be replaced with a shorter version:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp \"set grid\" k=\"left\" ylog=true\n@gp :- tit=\"Plot title\" xlab=\"X label\" xr=[0,NaN]","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"where NaN in the xrange keyword means using axis autoscaling.","category":"page"},{"location":"basic/#Plot-matrix-as-images-1","page":"Basic usage","title":"Plot matrix as images","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Gnuplot.jl can display a 2D matrix as an image:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"img = randn(Float64, 8, 5)\nimg[2,:] .= -5\n@gp img \"w image notit\"\nsaveas(\"basic007a\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Note that the first index in the img matrix corresponds to the rows in the displayed image.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"A simple way to remember the convention is to compare how a matrix is displayed in the REPL:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"img = reshape(1:15, 5, 3)","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"and its image representation, which is essentially upside down (since the Y coordinates increase upwards):","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp img \"w image notit\"\nsaveas(\"basic007b\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Also note that the img[1,1] pixel is shown at coordinates x=0, y=0. See Image recipes for further info.","category":"page"},{"location":"basic/#plots3d-1","page":"Basic usage","title":"3D plots","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"3D plots follow the same rules as 2D ones, just replace the @gp macro with @gsp and add the required columns (according to the plotting style).","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"E.g., to plot a spiral increasing in size along the X direction:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"x = 0:0.1:10pi\n@gsp cbr=[-1,1].*30 x x.*sin.(x) x.*cos.(x) x./20 \"w p pt 7 ps var lc pal\"\nsaveas(\"basic008\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Note that the fourth array in the dataset, x./20, is used as by gnuplot as point size (ps var). Also note that all the keywords discussed above can also be used in 3D plots.","category":"page"},{"location":"basic/#Palettes-and-line-types-1","page":"Basic usage","title":"Palettes and line types","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The Gnuplot.jl package comes with all the ColorSchemes palettes readily available.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"A gnuplot-compliant palette can be retrieved with palette(), and used as any other command. The previous example may use an alternative palette with:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"x = 0:0.1:10pi\n@gsp palette(:viridis) cbr=[-1,1].*30 :-\n@gsp :- x x.*sin.(x) x.*cos.(x) x./20 \"w p pt 7 ps var lc pal\"\nsaveas(\"basic008a\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The list of all available palette can be retrieved with palette_names():","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"palette_names()","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The ColorSchemes palettes can also be used to generate line type colors, and optionally the line width, point size and dashed pattern, by means of the linetypes() function, e.g.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp key=\"left\" linetypes(:Set1_5, lw=2)\nfor i in 1:10\n @gp :- i .* (0:10) \"w lp t '$i'\"\nend\nsaveas(\"basic009a\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"@gp key=\"left\" linetypes(:Set1_5, dashed=true, ps=2)\nfor i in 1:10\n @gp :- i .* (0:10) \"w lp t '$i'\"\nend\nsaveas(\"basic009b\") # hide","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(Image: )","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The first plot features the :Set1_5 palette, with solid lines whose width is 2 times the default. The second plot shows the same palette but default line widths are 1, default point size is 2 (for the first N line types, where N is the number of discrete colors in the palette), and the dashed pattern is automatically changed.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"As discussed in Options, you may set a default line types for all plots with:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"push!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"All plot in this documentation were generated with these settings.","category":"page"},{"location":"basic/#Exporting-plots-to-files-1","page":"Basic usage","title":"Exporting plots to files","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Gnuplot.jl can export all plots (as well as multiplots, see Multiplot) to an external file using one of the many available gnuplot terminals. To check which terminals are available in your platform type:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"terminals()","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"(see also terminal() to check your current terminal).","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Once you choose the proper terminal (i.e. format of the exported file), use the save() function to export. As an example, all the plots in this page have been saved with:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"save(term=\"pngcairo size 550,350 fontscale 0.8\", output=\"assets/output.png\")","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Note that you can pass both the terminal name and its options via the term= keyword. See Gnuplot terminals for further info on the terminals.","category":"page"},{"location":"basic/#Gnuplot-scripts-1","page":"Basic usage","title":"Gnuplot scripts","text":"","category":"section"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Besides exporting plots in image files, Gnuplot.jl can also save a script, i.e. a file containing the minimum set of data and commands required to re-create a figure using just gnuplot.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The script allows a complete decoupling of plot data and aethetics, from the Julia code used to generate them. With scripts you can:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"modify all aesthetic details of a plot without re-running the (possibly complex and time-consuming) code used to generate it;\nshare both data and plots with colleagues without the need to share the Julia code.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"To generate a script for one of the examples above use:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"save(\"script.gp\")","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"after the plot has been displayed. Note that when images or large datasets are involved, save() may store the data in binary files under a directory named <script name>_data. In order to work properly both the script and the associated directory must be available in the same directory.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"E.g., the following code:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"x = 1:10\n@gp x x.^2 \"w l\"\nsave(\"script1.gp\")","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"will produce the following file, named script1.gp:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"reset session\n$data1 << EOD\n 1 1\n 2 4\n 3 9\n 4 16\n 5 25\n 6 36\n 7 49\n 8 64\n 9 81\n 10 100\nEOD\nplot \\\n $data1 w l\nset output","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"While the following:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"img = randn(100, 300);\n@gp \"set size ratio -1\" \"set autoscale fix\" img \"flipy with image notit\"\nsave(\"script2.gp\")","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"will produce:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"reset session\nset size ratio -1\nset autoscale fix\nplot \\\n './script2_data/jl_OQrt9A' binary array=(300, 100) flipy with image notit\nset output","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The above scripts can be loaded into a pure gnuplot session (Julia is no longer needed) as follows:","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"gunplot> load 'script1.gp'\ngunplot> load 'script2.gp'","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"to generate a plot identical to the original one.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"The purpose of gnuplot 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.","category":"page"},{"location":"basic/#","page":"Basic usage","title":"Basic usage","text":"Finally, the scripts are the only possible output when Dry sessions are used (i.e. when gnuplot is not available in the user platform.","category":"page"},{"location":"examples/#Examples-1","page":"Examples","title":"Examples","text":"","category":"section"},{"location":"examples/#","page":"Examples","title":"Examples","text":"The official gallery of high quality examples is maintained in a separate repository:","category":"page"},{"location":"examples/#","page":"Examples","title":"Examples","text":"https://lazarusa.github.io/gnuplot-examples/","category":"page"},{"location":"examples/#","page":"Examples","title":"Examples","text":"The examples in this documentation are intentionally very simple, in order to focus on the package functionalities. The only relatively complex, publication-quality plot, is discussed in The cairolatex terminal section.","category":"page"},{"location":"examples/#","page":"Examples","title":"Examples","text":"Keep in mind that Gnuplot.jl is just an interface to gnuplot, so everything you can do with the latter is achievable from Julia. Further gnuplot examples can be found here:","category":"page"},{"location":"examples/#","page":"Examples","title":"Examples","text":"http://gnuplot.sourceforge.net/demo_5.2/\nhttp://www.gnuplotting.org/","category":"page"},{"location":"terminals/#Gnuplot-terminals-1","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"","category":"section"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"Gnuplot provides dozens of terminals to display plots or export them into files (see terminals() to get a list of enabled terminals on your platform). This section discuss a few tips on how to use the most common terminals.","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"To use a specific terminal for interactive use you may either set it as initialization command for all new session with (see Options):","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"Gnuplot.options.term = \"wxt\")","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"or directly send the command to a specific session (see Direct command execution)","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"gpexec(\"set term wxt\")","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"See official gnuplot documentation for further info on terminals and their options.","category":"page"},{"location":"terminals/#Interactive-terminals-(wxt-and-qt)-1","page":"Gnuplot terminals","title":"Interactive terminals (wxt and qt)","text":"","category":"section"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"The multiplatform wxt and qt terminals are among the most widely used ones for their nicely looking outputs on display and for their interactive capabilities.","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"You may set them as terminal with:","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"\"set term wxt size 800,600\"","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"or","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"\"set term qt size 800,600\"","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"(the size 800,600 is optional and can be omitted).","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"Press the h key on the window to display an help message with all available keyboard shortcuts. In particular press 6 to enable printing plot coordinates on Julia stdout (ensure mouse is enabled with m).","category":"page"},{"location":"terminals/#Plot-in-a-terminal-application-(dumb,-sixel-and-sixelgd)-1","page":"Gnuplot terminals","title":"Plot in a terminal application (dumb, sixel and sixelgd)","text":"","category":"section"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"Gnuplot supports plotting in a terminal application, with no need for X11 or other GUI support, via the dumb, sixel and sixelgd terminals. These are extremely useful when you run Julia on a remote shell through ssh, with no X11 forwarding.","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"The dumb terminal uses ASCII characters to draw a plot, while sixel and sixelgd actually use bitmaps (but require Sixel support to be enabled in the terminal, e.g. xterm -ti vt340). A sixel plot on xterm looks as follows: (Image: )","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"The above terminals are available if gnuplot has been compiled with the --with-bitmap-terminals option enabled and Libgd (only for sixelgd).","category":"page"},{"location":"terminals/#Export-to-image-files-1","page":"Gnuplot terminals","title":"Export to image files","text":"","category":"section"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"Gnuplot provides dozens of terminals able to export on files. Examples are:","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"cairopng to export PNG files;\npdfcairo for PDF;\njpeg for JPG;\ngif for GIF (see Animations).","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"All the above terminals support the size and fontscale options to quickly adjust the size of the rasterized image and the size of the font respectively. E.g.:","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"save(term=\"pngcairo size 480,360 fontscale 0.8\", output=\"output.png\")","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"(see also save()).","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"Gnuplot is also able to export vector (i.e. non-raster) plots through the svg terminal.","category":"page"},{"location":"terminals/#The-cairolatex-terminal-1","page":"Gnuplot terminals","title":"The cairolatex terminal","text":"","category":"section"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"The cairolatex terminal allows to produce high quality plots by splitting the output into a PDF file (containing a rasterized image of a plot) and a .tex file (containing all the text as LaTeX code). The following example shows how to write plot tics and an equation in LaTeX:","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"x = LinRange(-2pi, 2pi, 1000)\n@gp t=\"Polynomial approximation of sin(x)\" \"set style fill transparent solid 0.6 noborder\"\n@gp :- raw\"\"\"set xtics ('$-\\pi$' -pi, '$-\\pi/2$' -pi/2, 0, '$\\pi/2$' pi/2, '$\\pi$' pi)\"\"\"\n@gp :- xr=3.8.*[-1, 1] yr=[-1.5,1.5] key=\"box opaque left horiz\" linetypes(:Blues_3) \"set grid front\"\nlatex = raw\"\"\"\\begin{minipage}[c]{\\textwidth}\\begin{equation*}\"\"\" *\n\traw\"\"\"\\sin(x) = \\sum_0^{+\\infty} \\frac{(-1)^n}{(2n + 1)!} x^{2n+1}\"\"\" * \n\traw\"\"\"\\end{equation*} \\end{minipage}\"\"\"\n@gp :- \"set label at graph 0.62,0.2 front center '$latex'\"\napprox = fill(0., length(x));\n@gp :- x sin.(x) approx .+= x \"w filledcurve t 'n=0' lt 1\"\n@gp :- x sin.(x) approx .+= -x.^3/6 \"w filledcurve t 'n=1' lt 2\"\n@gp :- x sin.(x) approx .+= x.^5/120 \"w filledcurve t 'n=2' lt 3\"\n@gp :- x sin.(x) approx .+= -x.^7/5040 \"w filledcurve t 'n=3' lt 4\"\n@gp :- x sin.(x) \"w l t 'sin(x)' lw 2 lc rgb 'black'\"\nsave(term=\"cairolatex pdf input color dashed size 5in,3.3in\", output=\"test.tex\")","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"warning: Warning\nIf you add a path in the output= keyword this will also be copied in the the .tex file. I suggest to use just filenames, with no path, in order to avoid possible errors when compiling LaTeX code.","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"The two output files (test.tex and test.pdf) can then be included in a LaTeX file as follows:","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"\\documentclass{article}\n\\usepackage{amsmath}\n\\usepackage{graphicx}\n\\usepackage{color}\n\n\\begin{document}\n\\begin{figure}\n \\input{test.tex}\n\\end{figure}\n\\end{document}","category":"page"},{"location":"terminals/#","page":"Gnuplot terminals","title":"Gnuplot terminals","text":"And the output is: (Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"using Gnuplot\nGnuplot.quitall()\nmkpath(\"assets\")\n\nGnuplot.options.term = \"unknown\"\nempty!(Gnuplot.options.init)\npush!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))\nsaveas(file) = save(term=\"pngcairo size 550,350 fontscale 0.8\", output=\"assets/$(file).png\")","category":"page"},{"location":"advanced/#Advanced-usage-1","page":"Advanced usage","title":"Advanced usage","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Here we will show a few advanced techniques for data visualization using Gnuplot.jl.","category":"page"},{"location":"advanced/#Named-datasets-1","page":"Advanced usage","title":"Named datasets","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"A dataset may have an associated name whose purpose is to use it multiple times for plotting, while sending it only once to gnuplot. A dataset name must begin with a $.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"A named dataset is defined as a Pair{String, Tuple}, e.g.:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"\"\\$name\" => (1:10,)","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"and can be used as an argument to both @gp and gsp, e.g.:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = range(-2pi, stop=2pi, length=100);\ny = sin.(x)\nname = \"\\$MyDataSet1\"\n@gp name=>(x, y) \"plot $name w l lc rgb 'black'\" \"pl $name u 1:(1.5*\\$2) w l lc rgb 'red'\"\nsaveas(\"advanced010\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Both curves use the same input data, but the red curve has the second column (\\$2, corresponding to the y value) multiplied by a factor 1.5.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"A named dataset comes in hand also when using gnuplot to fit experimental data to a model, e.g.:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"# Generate data and some noise to simulate measurements\nx = range(-2pi, stop=2pi, length=20);\ny = 1.5 * sin.(0.3 .+ 0.7x);\nerr = 0.1 * maximum(abs.(y)) .* fill(1, size(x));\ny += err .* randn(length(x));\nname = \"\\$MyDataSet1\"\n\n@gp \"f(x) = a * sin(b + c*x)\" :- # define an analytical model\n@gp :- \"a=1\" \"b=1\" \"c=1\" :- # set parameter initial values\n@gp :- name=>(x, y, err) :- # define a named dataset\n@gp :- \"fit f(x) $name via a, b, c;\" # fit the data","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The parameter best fit values can be retrieved as follows:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"vars = gpvars();\n@info(\"Best fit values:\",\n a = vars.a,\n b = vars.b,\n c = vars.c)","category":"page"},{"location":"advanced/#Multiplot-1","page":"Advanced usage","title":"Multiplot","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Gnuplot.jl can draw multiple plots in the same figure by exploiting the multiplot command. Each plot is identified by a positive integer number, which can be used as argument to @gp to redirect commands to the appropriate plot.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Recycling data from the previous example we can plot both data and best fit model (in plot 1) and residuals (in plot 2):","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"@gp \"f(x) = a * sin(b + c*x)\"\n@gp :- \"a=$(vars.a)\" \"b=$(vars.b)\" \"c=$(vars.c)\"\n@gp :- name=>(x, y, err)\n@gp :- \"set multiplot layout 2,1\"\n@gp :- 1 \"p $name w errorbars t 'Data'\"\n@gp :- \"p $name u 1:(f(\\$1)) w l t 'Best fit model'\"\n@gp :- 2 \"p $name u 1:((f(\\$1)-\\$2) / \\$3):(1) w errorbars t 'Resid. [{/Symbol s}]'\"\n@gp :- [extrema(x)...] [0,0] \"w l notit dt 2 lc rgb 'black'\" # reference line\nsaveas(\"advanced011\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Note that the order of the plots is not relevant, i.e. we would get the same results with:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"@gp \"f(x) = a * sin(b + c*x)\"\n@gp :- \"a=$(vars.a)\" \"b=$(vars.b)\" \"c=$(vars.c)\"\n@gp :- name=>(x, y, err)\n@gp :- \"set multiplot layout 2,1\"\n@gp :- 2 \"p $name u 1:((f(\\$1)-\\$2) / \\$3):(1) w errorbars t 'Resid. [{/Symbol s}]'\"\n@gp :- [extrema(x)...] [0,0] \"w l notit dt 2 lc rgb 'black'\" # reference line\n@gp :- 1 \"p $name w errorbars t 'Data'\"\n@gp :- \"p $name u 1:(f(\\$1)) w l t 'Best fit model'\"","category":"page"},{"location":"advanced/#Customized-layout-1","page":"Advanced usage","title":"Customized layout","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"It is also possible to customize the plot layout using the margin keywords (see Histograms for further info on how to generate andi display histograms):","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"# Generate random numbers\nx = randn(1000);\ny = randn(1000);\n\n# Overall plot margins (normalized in the range 0:1)\nmargins = (l=0.08, r=0.98, b=0.13, t=0.98)\n\n# Right and top margins of main plot\nright, top = 0.8, 0.75\n\n# Gap between main plot and histograms\ngap = 0.015\n\n# Main plot\n@gp \"set multiplot\"\n@gp :- 1 ma=margins rma=right tma=top :-\n@gp :- x y \"w p notit\" xlab=\"X\" ylab=\"Y\"\nxr = gpranges().x # save current X range\nyr = gpranges().y # save current Y range\n\n# Histogram on X\nh = hist(x, nbins=10)\n@gp :- 2 ma=margins bma=top+gap rma=right :-\n@gp :- \"set xtics format ''\" \"set ytics format ''\" xlab=\"\" ylab=\"\" :-\nbs = fill(h.binsize, length(h.bins));\n@gp :- xr=xr h.bins h.counts./2 bs./2 h.counts./2 \"w boxxy notit fs solid 0.4\" :-\n\n# Histogram on Y\nh = hist(y, nbins=10)\n@gp :- 3 ma=margins lma=right+gap tma=top :-\n@gp :- \"unset xrange\" :-\nbs = fill(h.binsize, length(h.bins));\n@gp :- yr=yr h.counts./2 h.bins h.counts./2 bs./2 \"w boxxy notit fs solid 0.4\" :-\n@gp\nsaveas(\"advanced011b\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#Mixing-2D-and-3D-plots-1","page":"Advanced usage","title":"Mixing 2D and 3D plots","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"A multiplot can also mix 2D and 3D plots:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = y = -10:0.33:10\n@gp \"set multiplot layout 1,2\"\n\n# 2D\n@gp :- 1 x sin.(x) ./ x \"w l notit\"\n\n# 3D\nsinc2d(x,y) = sin.(sqrt.(x.^2 + y.^2))./sqrt.(x.^2+y.^2)\nfxy = [sinc2d(x,y) for x in x, y in y]\n@gsp :- 2 x y fxy \"w pm3d notit\"\nsaveas(\"advanced012\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#Multiple-sessions-1","page":"Advanced usage","title":"Multiple sessions","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Gnuplot.jl can handle multiple sessions, i.e. multiple gnuplot processes running simultaneously. Each session is identified by an ID (sid::Symbol, in the documentation).","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"In order to redirect commands to a specific session simply insert a symbol into your @gp or @gsp call, e.g.:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"@gp :GP1 \"plot sin(x)\" # opens first window\n@gp :GP2 \"plot sin(x)\" # opens secondo window\n@gp :- :GP1 \"plot cos(x)\" # add a plot on first window","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The session ID can appear in every position in the argument list, but only one ID can be present in each call. If the session ID is not specified the :default session is used.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The names of all current sessions can be retrieved with session_names():","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"println(session_names())","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"To quit a specific session use Gnuplot.quit():","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Gnuplot.quit(:GP1)","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The output value is the exit status of the underlying gnuplot process.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"You may also quit all active sessions at once with Gnuplot.quitall():","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Gnuplot.quitall()","category":"page"},{"location":"advanced/#Histograms-1","page":"Advanced usage","title":"Histograms","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Gnuplot.jl provides facilities to compute and display histograms, e.g.:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = randn(1000);\n@gp hist(x)\nsaveas(\"advanced013a\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The hist() function also accept keywords to set the range to consider (range= keyword) and either the bin size (bs=) or the total number of bins (nbins=) in the histogram. A finer control on the output is achieved by exploiting the fields of the returned (Gnuplot.Histogram1D) structure, e.g.:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = randn(1000);\nh = hist(x, range=3 .* [-1,1], bs=0.5)\n@gp h.bins h.counts \"w histep t 'Data' lc rgb 'red'\"\nsaveas(\"advanced013b\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The hist() function compute also 2D histograms by passing two vectors (with the same lengths), e.g.: ","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = randn(10_000)\ny = randn(10_000)\nh = hist(x, y)\n@gp h\nsaveas(\"advanced014a\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Again, a finer control can be achieved by specifying ranges, bin size or number of bins (along both dimensions) and by explicitly using the content of the returned Gnuplot.Histogram2D structure:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = randn(10_000)\ny = randn(10_000)\nh = hist(x, y, bs1=0.25, nbins2=20, range1=[-3,3], range2=[-3,3])\n@gp \"set size ratio -1\" h.bins1 h.bins2 h.counts \"w image notit\"\nsaveas(\"advanced014b\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Alternatively, 2D histograms may be displayed using the boxxyerror plot style which allows more flexibility in, e.g., handling transparencies and drawing the histogram grid. In this case the data can be prepared using the boxxy() function, as follows:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"@gp \"set size ratio -1\" \"set style fill solid 0.5 border lc rgb 'gray'\" :-\n@gp :- boxxy(h) \"w boxxy notit lc pal\"\nsaveas(\"advanced014c\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#Contour-lines-1","page":"Advanced usage","title":"Contour lines","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Although gnuplot already handles contours by itself (with the set contour command), Gnuplot.jl provides a way to calculate contour lines paths before displaying them, using the contourlines() function. We may preview such lines with:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = randn(10_000)\ny = randn(10_000)\nh = hist(x, y)\nclines = contourlines(h, \"levels discrete 10, 30, 60, 90\");\n@gp clines\nsaveas(\"advanced014d\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"By exploiting the fields of the Gnuplot.IsoContourLines structure we may also customize line widths, colors and dashed pattern according to their z level, and plot them on top of the 2D histogram:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"@gp \"set size ratio -1\" \"set style fill solid 0.5 border lc rgb 'gray'\" :-\n@gp :- boxxy(h) \"w boxxy notit lc pal\"\nfor i in 1:length(clines)\n @gp :- clines[i].data \"w l t '$(clines[i].z)' lw $i dt $i lc pal\" :-\nend\n@gp :- key=\"outside top center box horizontal\"\nsaveas(\"advanced014e\") # hide","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#Animations-1","page":"Advanced usage","title":"Animations","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The Multiplot capabilities can also be used to stack plots one above the other in order to create an animation, as in the following example:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"x = y = -10:0.33:10\nfz(x,y) = sin.(sqrt.(x.^2 + y.^2))./sqrt.(x.^2+y.^2)\nfxy = [fz(x,y) for x in x, y in y]\n@gsp \"set xyplane at 0\" \"unset colorbox\" cbr=[-1,1] zr=[-1,1]\nframe = 0\nfor direction in [-1,1]\n for factor in -1:0.1:1\n global frame += 1\n @gsp :- frame x y direction * factor .* fxy \"w pm3d notit\" :-\n end\nend\n@gsp","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Here the frame variable is used as multiplot index. The animation can be saved in a GIF file with:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"save(term=\"gif animate size 480,360 delay 5\", output=\"assets/animation.gif\")","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"(Image: )","category":"page"},{"location":"advanced/#Direct-command-execution-1","page":"Advanced usage","title":"Direct command execution","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"When gnuplot commands are passed to @gp or @gsp they are stored in a session for future use, or to be saved in Gnuplot scripts. If you simply wish to execute a command without storing it in the session, and possibly retrieve a value, use gpexec. E.g., to retrieve the value of a gnuplot variable:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"gpexec(\"print GPVAL_TERM\")","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"You may also provide a session ID as first argument (see Multiple sessions) to redirect the command to a specific session.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Alternatively you may start the The gnuplot REPL to type commands directly from the Julia prompt.","category":"page"},{"location":"advanced/#The-gnuplot-REPL-1","page":"Advanced usage","title":"The gnuplot REPL","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The Gnuplot.jl package comes with a built-in REPL mode to directly send commands to the underlying gnuplot process. Since the REPL is a global resource, the gnuplot mode is not enabled by default. You can start it with:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Gnuplot.repl_init(start_key='>')","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"The customizable start_key character is the key which triggers activation of the REPL mode. To quit the gnuplot REPL mode hit the backspace key.","category":"page"},{"location":"advanced/#Dry-sessions-1","page":"Advanced usage","title":"Dry sessions","text":"","category":"section"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"A \"dry session\" is a session with no underlying gnuplot process. To enable dry sessions type:","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Gnuplot.options.dry = true;","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"before starting a session (see also Options). Note that the dry option is a global one, i.e. it affects all sessions started after setting the option.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"Clearly, no plot can be generated in dry sessions. Still, they are useful to run Gnuplot.jl code without raising errors (no attempt will be made to communicate with the underlying process). Moreover, Gnuplot scripts can also be generated in a dry session, without the additional overhead of sending data to the gnuplot process.","category":"page"},{"location":"advanced/#","page":"Advanced usage","title":"Advanced usage","text":"If a gnuplot process can not be started the package will print a warning, and automatically enable dry sessions.","category":"page"},{"location":"install/#Installation-1","page":"Installation","title":"Installation","text":"","category":"section"},{"location":"install/#Prerequisite-1","page":"Installation","title":"Prerequisite","text":"","category":"section"},{"location":"install/#","page":"Installation","title":"Installation","text":"In order to use the Gnuplot.jl package you'll need gnuplot (ver. >= 5.0) installed on your system, and its executable available in your path.","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"If gnuplot is not available in your platform you can still use Gnuplot.jl in \"dry\" mode (see Dry sessions). In this case a plot can not be generated, but you may still generate Gnuplot scripts.","category":"page"},{"location":"install/#Package-installation-1","page":"Installation","title":"Package installation","text":"","category":"section"},{"location":"install/#","page":"Installation","title":"Installation","text":"In the Julia REPL type:","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"julia> ]add Gnuplot","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"The ] character starts the Julia package manager. Hit backspace key to return to Julia prompt.","category":"page"},{"location":"install/#Check-installation-1","page":"Installation","title":"Check installation","text":"","category":"section"},{"location":"install/#","page":"Installation","title":"Installation","text":"Check Gnuplot.jl version with:","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"julia> ]st Gnuplot\nStatus `~/.julia/environments/v1.4/Project.toml`\n [dc211083] Gnuplot v1.2.0","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"If the displayed version is not v1.2.0 you are probably having a dependency conflict. In this case try forcing installation of the latest version with:","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"julia> ]add Gnuplot@1.2.0","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"and check which package is causing the conflict.","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"Check execution and version of the underlying gnuplot process:","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"using Gnuplot\nGnuplot.gpversion()","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"The minimum required version is v5.0.","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"Generate the first plot:","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"julia> @gp 1:9","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"Test default terminal capabilities:","category":"page"},{"location":"install/#","page":"Installation","title":"Installation","text":"test_terminal()","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"using Gnuplot\nGnuplot.quitall()\nmkpath(\"assets\")\n\nGnuplot.options.term = \"unknown\"\nempty!(Gnuplot.options.init)\npush!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))\nsaveas(file) = save(term=\"pngcairo size 550,350 fontscale 0.8\", output=\"assets/$(file).png\")","category":"page"},{"location":"options/#Package-options-and-initialization-1","page":"Package options","title":"Package options and initialization","text":"","category":"section"},{"location":"options/#Options-1","page":"Package options","title":"Options","text":"","category":"section"},{"location":"options/#","page":"Package options","title":"Package options","text":"The package options are stored in a global structure available in Julia as Gnuplot.option (the type of the structure is Gnuplot.Options). The most important settings are as follows:","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"dry::Bool: if true all new sessions will be started as Dry sessions. Default is false, but if the package is not able to start a gnuplot process it will automatically switch to true;\ncmd::String: command to start the gnuplot process, default value is \"gnuplot\". Use this field to specify a custom path to the gnuplot executable;\nterm::String: default terminal for interactive use (default is an empty string, i.e. use gnuplot settings). A custom terminal can be set with, e.g.:","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"Gnuplot.options.term = \"wxt size 700,400\";","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"term_svg::String: terminal to save png files (default: \"svg background rgb 'white' dynamic\");\nterm_png::String: terminal to save png files (default: \"pngcairo\");\ninit::Vector{String}: commands to initialize the session when it is created or reset. It can be used to, e.g., set a custom linetypes or palette:","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"push!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5));","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"Note that this option affect all the sessions, and that all inserted commands are saved in Gnuplot scripts;","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"verbose::Bool: a flag to set verbosity of the package. If true all communication with the underlying process will be printed on stdout. E.g.:","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"empty!(Gnuplot.options.init); # hide\ngpexec(\"set term wxt\"); # hide\nGnuplot.options.verbose = true;\nx = 1.:10;\n@gp x x.^2 \"w l t 'Parabola'\"\nsave(term=\"pngcairo size 480,360 fontscale 0.8\", output=\"output.png\")\nGnuplot.options.verbose = false # hide\npush!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5)); # hide\ngpexec(\"set term unknown\"); # hide","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"Each line reports the package name (GNUPLOT), the session name (default), the command or string being sent to gnuplot process, and the returned response (line starting with ->). Default value is false;","category":"page"},{"location":"options/#Jupyter-and-Juno-1","page":"Package options","title":"Jupyter and Juno","text":"","category":"section"},{"location":"options/#","page":"Package options","title":"Package options","text":"Gnuplot.jl can display plots in Jupyter and Juno by exporting images in the PNG and SVG formats. To customize the terminals used to export the images set the term_png or term_svg fields of the Gnuplot.Options structure, e.g.:","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"Gnuplot.options.term_png = \"pngcairo size 700,400 linewidth 2\";\nGnuplot.options.term_svg = \"svg dynamic\";","category":"page"},{"location":"options/#Package-initialization-1","page":"Package options","title":"Package initialization","text":"","category":"section"},{"location":"options/#","page":"Package options","title":"Package options","text":"If you use Gnuplot.jl frequently you may find convenient to collect all the package settings (Options) in a single place, to quickly recall them in a Julia session. I suggest to put the following code in the ~/.julia/config/startup.jl initialization file (further info here):","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"macro gnuplotrc()\n return :(\n using Revise, Gnuplot;\n\n # Uncomment following to true if you don't have the gnuplot\n # executable installed on your platform:\n #Gnuplot.options.dry = true;\n\n # Uncomment the following and set the proper path if the\n # gnuplot executable is not available in your $PATH\n #Gnuplot.options.cmd = \"/path/to/gnuplot\";\n\n # Set the default terminal for interacitve use\n Gnuplot.options.term = \"wxt size 700,400\";\n\n # Set the default linetypes\n empty!(Gnuplot.options.init);\n push!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5));\n\n # Initialize the gnuplot REPL using the provided `start_key`.\n # Comment the following to disable the REPL.\n Gnuplot.repl_init(start_key='>');\n )\nend","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"At the Julia prompt you may load the package and the associated settings by typing:","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"julia> @gnuplotrc","category":"page"},{"location":"options/#","page":"Package options","title":"Package options","text":"and you're ready to go.","category":"page"},{"location":"#Gnuplot.jl-1","page":"Home","title":"Gnuplot.jl","text":"","category":"section"},{"location":"#A-Julia-interface-to-gnuplot.-1","page":"Home","title":"A Julia interface to gnuplot.","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"(Image: Stars)","category":"page"},{"location":"#","page":"Home","title":"Home","text":"The Gnuplot.jl package allows easy and fast use of gnuplot as a data visualization tool in Julia. Have a look at Basic usage and Examples for a quick overview. The package main features are:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"fast time-to-first-plot;\nextremely concise yet meaningful syntax, makes it ideal for interactive data exploration;\nno need to learn new API functions or keywords: only two macros (@gp for 2D plots, @gsp for 3D plots) and a basic knowledge of gnuplot are enough to generate most plots;\ntransparent interface between Julia and gnuplot to exploit all functionalities of the latter, both present and future ones;\navailability of all the palettes from ColorSchemes;\nsupport for multiple plots in one window, multiple plotting windows, as well as ASCII and Sixel plots (to plot directly in a terminal);\nsupport for histograms (both 1D and 2D);\nenhanced support for contour plots;\nexport to a huge number of formats such as pdf, png, gif, LaTeX, svg, etc. (actually all those supported by gnuplot);\ncompatibility with Jupyter and Juno;\nsave sessions into gnuplot scripts, to enable easy plot customization and reproducibility.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"If you're unfamiliar with gnuplot have a look at:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Main gnuplot site\ngnuplot FAQ","category":"page"},{"location":"#Yet-another-plotting-package?-1","page":"Home","title":"Yet another plotting package?","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"A powerful plotting framework is among the most important tool in the toolbox of any modern scientist and engineer. As such, it is hard to find a single package to fit all needs, and many solutions are indeed available in the Julia ecosystem.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Gnuplot.jl package fills the niche of users who needs:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"publication-quality plots, by exploiting the capabilities of a widely used tool such as gnuplot, and its many output formats available;\na well-documented framework, by taking advantage of all the gnuplot documentation, tutorials and examples available on the web;\na fast response, by relying on an external program (rather than on a large Julia code base);\nan interactive data exploration framework, by exposing a carefully designed, extremely concise and easy to remember syntax (at least for users with minimal gnuplot knowledge);\na procedure to decouple plot data and aesthetics from the Julia code used to generate them.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Unlike other packages Gnuplot.jl is not a pure Julia solution as it depends on an external package to actually generate plots. However, if gnuplot is not available on a given platform, the package could still be used in \"dry\" mode, and no error for a missing dependency will be raised (see Dry sessions).","category":"page"},{"location":"#","page":"Home","title":"Home","text":"The Gnuplot.jl package development follows a minimalistic approach: it is essentially a thin layer to send data and commands to gnuplot. This way all underlying capabilities, both present and future ones, are automatically exposed to the Julia user, with no need to implement dedicated wrappers.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"The functionalities 1, 2 and 3 listed above are similar to those provided by the Gaston package. Gnuplot.jl also provides features 4 and 5, as well as the minimalistic approach.","category":"page"},{"location":"#Does-Gnuplot.jl-suit-my-needs?-1","page":"Home","title":"Does Gnuplot.jl suit my needs?","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Any modern plotting framework is able to produce a simple scatter plot, with custom symbols, line styles, colors and axis labels. Indeed, this is exactly the example that is reported in every package documentation (also here: see 2D plots). Still, producing complex and publication-quality plots is not an easy task. As a consequence is also hard to tell whether a package can cope with the most difficult cases, unless you actually try it out. A reasonable choice, then, is to rely on the size of the user base, the availability of documentation / tutorials, and the possibility to preview complex examples.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"By allowing transparent access to the underlying gnuplot process, the Gnuplot.jl package immediately exposes all capabilities of the backend and allows to take advantage of the many resources available online. The minimalistic approach allows to value the widely spread knowledge of gnuplot syntax, and ensures a shallow learning curve for the package. Finally, its extremely concise syntax makes it ideal for interactive data exploration.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"As a final remark, note that the Gnuplot.jl features directly maps onto the different stages of production of a plot:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"syntax conciseness, interactivity, Plot recipes => preliminary data exploration;\naccess to all gnuplot capabilities, allowing to tweak even the smallest detail of a plot => plot preparation;\nGnuplot scripts => post-production.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Before continuing, have a look at the Examples page!","category":"page"},{"location":"#Notation-1","page":"Home","title":"Notation","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"In this documentation:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"\"Gnuplot.jl\" refers to the Julia package;\n\"gnuplot\" refers to the gnuplot application.","category":"page"},{"location":"#Table-of-Contents-1","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Pages = [\"index.md\", \"install.md\", \"basic.md\", \"advanced.md\", \"options.md\", \"style.md\", \"terminals.md\", \"recipes.md\", \"examples.md\", \"api.md\"]","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"using Gnuplot\nGnuplot.quitall()\nmkpath(\"assets\")\n\nGnuplot.options.term = \"unknown\"\nempty!(Gnuplot.options.init)\npush!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))\nsaveas(file) = save(term=\"pngcairo size 550,350 fontscale 0.8\", output=\"assets/$(file).png\")","category":"page"},{"location":"recipes/#Plot-recipes-1","page":"Plot recipes","title":"Plot recipes","text":"","category":"section"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"A plot recipe is a quicklook visualization procedure aimed at reducing the amount of repetitive code to generate a plot. More specifically, a recipe is a function that convert data from the \"Julia world\" into a form suitable to be ingested in Gnuplot.jl, namely a scalar (or a vector of) Gnuplot.PlotElement object(s). The latter contain informations on how to create a plot, or a part of it, and can be used directly as arguments in a @gp or @gsp call.","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"There are two kinds of recipes:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"explicit recipe: a function which is explicitly invoked by the user. It can have any name and accept any number of arguments and keywords. It is typically used when the visualization of a data type requires some extra information, beside data itself (e.g. to plot data from a DataFrame object, see Explicit recipe (example));\nimplicit recipe: a function which is automatically called by Gnuplot.jl. It must extend the recipe() function, and accept exactly one mandatory argument. It is typically used when the visualization is completely determined by the data type itself (e.g. the visualization of a Matrix{ColorTypes.RGB} object as an image, see Image recipes);","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"An implicit recipe is invoked whenever the data type of an argument to @gp or @gsp is not among the allowed ones (see @gp() documentation). If a suitable recipe do not exists an error is raised. On the other hand, an explicit recipe needs to be invoked by the user, and the output passed directly to @gp or @gsp.","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"Although recipes provides very efficient tools for data exploration, their use typically hide the details of plot generation. As a consequence they provide less flexibility than the approaches described in Basic usage and Advanced usage.","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"Currently, the Gnuplot.jl package provides no built-in explicit recipe. The implicit recipes are implemented in recipes.jl.","category":"page"},{"location":"recipes/#Explicit-recipe-(example)-1","page":"Plot recipes","title":"Explicit recipe (example)","text":"","category":"section"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"To generate a plot using the data contained in a DataFrame object we need, beside the data itself, the name of the columns to use for the X and Y coordinates. The following example shows how to implement an explicit recipe to plot a DataFrame object:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"using RDatasets, DataFrames, Gnuplot\nimport Gnuplot: PlotElement, DatasetText\n\nfunction plotdf(df::DataFrame, colx::Symbol, coly::Symbol; group=nothing)\n if isnothing(group)\n return PlotElement(data=DatasetText(df[:, colx], df[:, coly]),\n plot=\"w p notit\",\n xlab=string(colx), ylab=string(coly))\n end\n\n out = Vector{Gnuplot.PlotElement}()\n push!(out, PlotElement(;xlab=string(colx), ylab=string(coly)))\n for g in sort(unique(df[:, group]))\n i = findall(df[:, group] .== g)\n if length(i) > 0\n push!(out, PlotElement(data=DatasetText(df[i, colx], df[i, coly]),\n plot=\"w p t '$g'\"))\n end\n end\n return out\nend\n\n# Load a DataFrame and convert it to a PlotElement\niris = dataset(\"datasets\", \"iris\")\n@gp plotdf(iris, :SepalLength, :SepalWidth, group=:Species)\nsaveas(\"recipes001\") # hide","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"(Image: )","category":"page"},{"location":"recipes/#Histogram-recipes-1","page":"Plot recipes","title":"Histogram recipes","text":"","category":"section"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"The object returned by the hist() function can be readily visualized by means of implicit recipes defined on the Gnuplot.Histogram1D and Gnuplot.Histogram2D types:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"x = randn(1000);\n@gp hist(x)\nsaveas(\"recipes002\") # hide","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"(Image: )","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"x = randn(10_000);\ny = randn(10_000);\n@gp hist(x, y)\nsaveas(\"recipes002a\") # hide","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"(Image: )","category":"page"},{"location":"recipes/#Contour-lines-recipes-1","page":"Plot recipes","title":"Contour lines recipes","text":"","category":"section"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"The object returned by the contourlines() function can be readily visualized by means of implicit recipes defined on the Gnuplot.IsoContourLines types:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"x = randn(10_000);\ny = randn(10_000);\nh = hist(x, y)\nclines = contourlines(h, \"levels discrete 10, 30, 60, 90\");\n@gp clines\nsaveas(\"recipes002b\") # hide","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"(Image: )","category":"page"},{"location":"recipes/#Image-recipes-1","page":"Plot recipes","title":"Image recipes","text":"","category":"section"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"The Gnuplot.jl package provides implicit recipes to display images in the following formats:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"Matrix{ColorTypes.RGB{T}};\nMatrix{ColorTypes.RGBA{T}}\nMatrix{ColorTypes.Gray{T}};\nMatrix{ColorTypes.GrayA{T}};","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"To use these recipes simply pass an image to @gp, e.g.:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"using TestImages\nimg = testimage(\"lighthouse\");\n@gp img\nsaveas(\"recipes007b\") # hide","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"(Image: )","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"All such recipes are defined as:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"function recipe(M::Matrix{ColorTypes.RGB{T}}, opt=\"flipy\")\n ...\nend","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"with only one mandatory argument. In order to exploit the optional keyword we can explicitly invoke the recipe as follows:","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"img = testimage(\"walkbridge\");\n@gp palette(:gray) recipe(img, \"flipy rot=15deg\")\nsaveas(\"recipes007c\") # hide","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"(Image: )","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"Note that we used both a palette (:gray, see Palettes and line types) and a custom rotation angle.","category":"page"},{"location":"recipes/#","page":"Plot recipes","title":"Plot recipes","text":"The flipy option is necessary for proper visualization (see discussion in Plot matrix as images).","category":"page"}]
}
Reference in New Issue View Git Blame Copy Permalink