{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Displaying options\n",
"\n",
"The display behaviour of **Gnuplot.jl** depends on the value of the `Gnuplot.options.gpviewer` boolean option:\n",
"\n",
"- if `true` the plot is displayed in a gnuplot window, using one of the interactive terminals such as `wxt`, `qt` or `aqua`. There is exactly one window for each session, and the plots are updated by replacing the displayed image. The preferred terminal can optionally be set using `Gnuplot.options.term`;\n",
"\n",
"- if `false` the plot is displayed through the Julia [multimedia interface](https://docs.julialang.org/en/v1/base/io-network/#Multimedia-I/O-1), i.e. it is exported as either a `png`, `svg` or `html` file, and displayed in an external viewer. In this case the package is unable to replace a previous plot, hence each update results in a separate image being displayed. The terminal options to export the images are set in `Gnuplot.options.mime`.\n",
"\n",
"The latter approach can only be used when running a Jupyter, JupyterLab or Juno session, while the former approach is appropriate in all cases (most notably, for the standard Julia REPL). The `Gnuplot.options.gpviewer` flag is automatically set when the package is first loaded according to the runtime environment, however the user can change its value at any time to fit specific needs. The following examples show the difference between the two approaches. \n",
"\n",
"Recall that the `:-` symbol has a special meaning in **Gnuplot.jl**:\n",
"\n",
"- if given as first argument to a `@gp` or `@gsp` call, it append data and commands to a previously started plot. To start a new plot omit `:-` as first arugment;\n",
"- if given as last argument it avoids updating the current plot, although data and commands are saved to be used at a later time. To actually update a plot omit `:-` as last arugment.\n",
"\n",
"The `:-` symbol has been chosen since it reminds of hyphenation in natural language, and allow to split `@gp` and `@gsp` calls into multiple, possibly non-contiguous, statements.\n",
"\n",
"\n",
"## Display plots in a REPL session\n",
"Even if the following examples run in a notebook we can simulate a REPL session by explicitly setting `Gnuplot.options.gpviewer` to `true`:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"using Gnuplot\n",
"Gnuplot.options.gpviewer = true; # simulate usage in a REPL\n",
"\n",
"# Optionally, we can set a custom terminal for interactive use\n",
"Gnuplot.options.term = \"wxt size 800,400\";\n",
"\n",
"# Terminate all sessions\n",
"Gnuplot.quitall()\n",
"\n",
"# Generate some numbers to plot\n",
"x = 1:0.1:10\n",
"y1 = sin.(x)\n",
"y2 = cos.(x)\n",
"y3 = y1.+y2;"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Start a new plot using the `y1` dataset:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "",
"image/svg+xml": [],
"text/html": [],
"text/plain": []
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"@gp x y1 \"w l t 'sin'\" :-"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As expected, nothing is displayed since we used the `:-` symbol as last argument to `@gp`.\n",
"Now add a second dataset (`y2`), and omit the trailing `:-` symbol:"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "",
"image/svg+xml": [],
"text/html": [],
"text/plain": []
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"@gp :- x y2 \"w l t 'cos'\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"A new window should popup showing the plot with two datasets. Now add a third dataset (`y3`):"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [],
"source": [
"@gp :- x y3 \"w l t 'sin+cos' lw 2\";"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The plot has been updated by replacing the window content. The presence of the semicolon has no effect here, and the same applies when we involke `display()` on the returned value: "
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "",
"image/svg+xml": [],
"text/html": [],
"text/plain": []
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(ans) # nothing happens here"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now insert the same `@gp` calls into a (possibly very long and complex) function, and invoke it:"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [],
"source": [
"function complex_function()\n",
" # ...\n",
" x = 1:0.1:10\n",
" y1 = sin.(x)\n",
" y2 = cos.(x)\n",
" y3 = y1.+y2;\n",
" @gp :dummy x y1 \"w l t 'sin'\" :-\n",
" @gp :- :dummy x y2 \"w l t 'cos'\"\n",
" @gp :- :dummy x y3 \"w l t 'sin+cos' lw 2\";\n",
" #...\n",
" return nothing\n",
"end\n",
"\n",
"complex_function()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here we used a separate session called `dummy` to show the plot in a separate window. Note that the same code, used in the REPL or within a function, generates the same plot. Also note that the plot is updated two times since there is no trailing `:-` symbol on both lines 8 and 9. We could slightly improve the performances by adding a trailing `:-` to line 8, and display the final plot in line 9 (although in this case the plot is too simple to produce any measurable improvement).\n",
"\n",
"\n",
"## Display plots in an external viewer\n",
"\n",
"Let's repeat the above examples redirecting the images on this notebook:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [],
"source": [
"Gnuplot.options.gpviewer = false; # use Julia multimedia interface\n",
"\n",
"#=\n",
"Gnuplot.jl export images using the following MIME types:\n",
"- image/png\n",
"- image/svg+xml\n",
"- text/html\n",
"and the corresponding terminal options are set through the `Gnuplot.options.mime` dictionary.\n",
"\n",
"Jupyter would store images in all such formats in the notebook. To shrink the notebook size\n",
"you may choose the format providing best results, and disable the others:\n",
"=#\n",
"Gnuplot.options.mime[MIME\"image/png\"] = \"\";\n",
"Gnuplot.options.mime[MIME\"image/svg+xml\"] = \"\";\n",
"Gnuplot.options.mime[MIME\"text/html\"] = \"svg enhanced standalone mouse size 800,400\";"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "",
"image/svg+xml": [],
"text/html": [],
"text/plain": []
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"@gp x y1 \"w l t 'sin'\" :-"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Again, the trailing `:-` symbol avoids creating a plot. If we omit it:"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "",
"image/svg+xml": [],
"text/html": [
"\n",
"\n",
"\n"
],
"text/plain": []
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"@gp :- x y2 \"w l t 'cos'\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"we obtain an inline plot with two datasets. Now the third dataset:"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [],
"source": [
"@gp :- x y3 \"w l t 'sin+cos' lw 2\";"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"According to the Julia convention, no plot is shown here since we added a trailing `;`, however all data have already been sent to gnuplot.\n",
"\n",
"To display the updated plot we need an explicit call to `display()` on the returned value:"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "",
"image/svg+xml": [],
"text/html": [
"\n",
"\n",
"\n"
],
"text/plain": []
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(ans)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Unlike the previous case, note that the updated a plot now appears in a **separate** image.\n",
"\n",
"The above code produced two inline images. Now invoke the same code within the `complex_function()` function:"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [],
"source": [
"complex_function()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Unlike the previous case nothing appeared here since we need to explicitly invoke `display()` on the proper session:"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "",
"image/svg+xml": [],
"text/html": [
"\n",
"\n",
"\n"
],
"text/plain": []
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(@gp :dummy)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Clearly, the plot appears in the same notebook, even if the session is different.\n",
"\n",
"## Summary\n",
"\n",
"The following tables summarize the main aspects of the approaches discussed above:\n",
"\n",
"\n",
"| `Gnuplot.options.gpviewer = true` | REPL, Jupyter or Juno\n",
"| :------------- | :-------------:\n",
"| Plots are shown | in dedicated window(s)\n",
"| Updating a plot | updates window content\n",
"| Output of different session goes to | separate windows\n",
"| How many simultaneous plots can be shown? | all windows fitting the screen\n",
"| Calls to `display()` / automatic display (trailing `;`) | does nothing / not applicable\n",
"| The top level code works also within a function? | yes, explicit `display()` calls are not required\n",
"| Terminal options are specified in | `Gnuplot.options.term`\n",
"\n",
"\n",
"| `Gnuplot.options.gpviewer = false` | REPL | Jupyter | Juno\n",
"| :------------- | :-------------: | :------------: | :-------------:\n",
"| Plots are shown | not shown | as inline images in the notebook | as image in the plot pane\n",
"| Updating a plot | not shown | creates a separate image | overwrites the plot pane content\n",
"| Output of different session goes to | not shown | the same notebook | the plot pane\n",
"| How many simultaneous plots can be shown? | not shown | all those fitting in the visible part of the notebook | only one\n",
"| Calls to `display()` / automatic display (trailing `;`) | not applicable | updates the plot / applicable | updates the plot / applicable\n",
"| The top level code works also within a function? | not applicable | no, explicit `display()` calls are required | no, explicit `display()` calls are are required\n",
"| Terminal options are specified in | not applicable | `Gnuplot.options.mime` | `Gnuplot.options.mime`\n"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Julia 1.4.0",
"language": "julia",
"name": "julia-1.4"
},
"language_info": {
"file_extension": ".jl",
"mimetype": "application/julia",
"name": "julia",
"version": "1.4.0"
}
},
"nbformat": 4,
"nbformat_minor": 4
}