I looked at the documentation on worg for org-plot and much of it is
out-of-date and/or no longer works (e.g. dead links, non-working
examples). Attached is a patch for the first half of the documentation.
The patch ends at the end of the section on 2d graphs.
Comments are appreciated. I also ask for advice on later sections, below.
From 4e262898feb349dad2f5b5afe8960c8e09723862 Mon Sep 17 00:00:00 2001
From: Leo Butler <leo.but...@umanitoba.ca>
Date: Wed, 24 Apr 2024 12:57:58 -0500
Subject: [PATCH] org-tutorials/org-plot.org: update documentation and examples
- Replace dead link to org-plot.el with link to it on the Org
repository.
- Put discussion of keybinding into a subsection distinct from
installation. Replace instructions about an idiosyncratic keybinding
with mention of the established keybinding for org-plot/gnuplot.
- Restructure ``2d plots'' section.
- Put lines example in one subsection, histogram example in a
second.
- Show the #+PLOT options that are used to create each example.
- Fix internal link.
- Add names/captions to tables.
- Remove the second histogram example, because the instructions are
incorrect and it does not work.
---
org-tutorials/org-plot.org | 70 +++++++++++++++++++++-----------------
1 file changed, 39 insertions(+), 31 deletions(-)
diff --git a/org-tutorials/org-plot.org b/org-tutorials/org-plot.org
index a0f3564b..98401fd3 100644
--- a/org-tutorials/org-plot.org
+++ b/org-tutorials/org-plot.org
@@ -43,38 +43,46 @@ following
First we need to make sure that org-plot is on your system and
available to emacs. If you have a recent version of org-mode (version
6.07 or later) then org-plot is already included. Otherwise you can
-grab the latest org-plot.el from [[http://github.com/eschulte/org-plot/tree/master][github/eschulte/org-plot]]. Once you
-have org-plot loaded it may be useful to bind the main plotting
-command =org-plot/gnuplot= to a key chord, I use =C-M-g= for the
-mnemonic "graph" which can be done by executing the following elisp
-snippet. This command will be the only org-plot command needed for
-the remainder of this tutorial.
+grab the latest ~org-plot.el~ from the [[https://git.sr.ht/~bzg/org-mode/tree/main/item/lisp/org-plot.el][Org repository]].
-[[elisp:(local-set-key "\M-\C-g" 'org-plot/gnuplot)]]
-
-Alright, we're now ready to start generating some graphs.
+** Keybinding
+The main plotting command, =org-plot/gnuplot=, is bound to the
+key-chord =C-c " g=. This is the only org-plot command used in this
+tutorial.
* Examples
** 2d plots (lines and histograms)
+*** Lines
-First, to plot the following table use the key sequence defined above
-=C-M-g=. This will call =org-plot/gnuplot= which finds and plots the
-nearest table. The options specified in any =#+PLOT= lines above the
-table are read and applied to the plot. Notice that the second
-=#+PLOT:= line specifies labels for each column, if this line is
-removed the labels will default to the column headers in the table,
-try removing this line and re-plotting.
+To plot [[org-plot-example-1][Table 1]], execute the =org-plot/gnuplot= command. This command
+finds and plots the nearest table. The result, saved as a =png= file,
+is displayed in [[org-plot-example-1-plot][Figure 1]].
+#+NAME: org-plot-example-1-plot
+#+CAPTION: Plot of Table 1.
[[file:../images/org-plot/example-1.png]]
+The options specified in any =#+PLOT= lines above the table are read
+and applied to the plot. Notice that the second =#+PLOT= line
+specifies labels for each column; if this line is removed the labels
+will default to the column headers in the table. Here are the =#+PLOT=
+lines used to create Figure 1.
+
+#+NAME: org-plot-example-1-plot-options
+#+BEGIN_EXAMPLE
+#+PLOT: title:"example table" ind:1 type:2d with:lines
+#+PLOT: labels:("first new label" "second column" "last column")
+#+END_EXAMPLE
+
For a complete list of all of the options and their meanings see the
-[[options]] section at the end of this file. For more information on
+[[options][options]] section at the end of this file. For more information on
gnuplot options see [[http://gnuplot.sourceforge.net/documentation.html][the gnuplot documentation]], nearly all gnuplot
options should be accessible through org-plot.
+#+NAME: org-plot-example-1
+#+CAPTION: Data used to plot Figure 1.
#+PLOT: title:"example table" ind:1 type:2d with:lines
#+PLOT: labels:("first new label" "second column" "last column")
-#+TBLNAME:org-plot-example-1
| independent var | first dependent var | second dependent var |
|-----------------+---------------------+----------------------|
| 0.1 | 0.425 | 0.375 |
@@ -107,14 +115,22 @@ options should be accessible through org-plot.
| 2.8 | 0.1598214 | 0.18928565 |
| 2.9 | 0.15603453 | 0.1844828 |
+*** Historgrams
+Org-plot can also produce histograms from 2d data. [[org-plot-example-2-plot][Figure 2]] is
+created with the following options:
+#+begin_example
+#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
+#+end_example
+Notice that the column specified as =ind= contains textual non-numeric
+data; when this is the case org-plot will use the data as labels for
+the x-axis using the gnuplot =xticlabels()= function.
-Org-plot can also produce histograms from 2d data, plot the following
-table. Notice that the column specified as =ind= contains textual
-non-numeric data, when this is the case org-plot will use the data as
-labels for the x-axis using the gnuplot =xticlabels()= function.
-
+#+NAME: org-plot-example-2-plot
+#+CAPTION: H-index of selected cities.
[[file:../images/org-plot/example-2.png]]
+#+NAME: org-plot-example-2
+#+CAPTION: Example 2.
#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
| Sede | Max cites | H-index |
|-----------+-----------+---------|
@@ -124,14 +140,6 @@ labels for the x-axis using the gnuplot =xticlabels()= function.
| Stockholm | 134.19 | 14.33 |
| Morelia | 257.56 | 17.67 |
-
-For another example of plotting histograms instead of lines, change
-the following options on the first table on this page, and replot
-1) remove the =ind:1= option
-2) replace the =with:lines= option with =with:histograms=
-
-[[file:../images/org-plot/example-3.png]]
-
** 3d grid plots
There are also some functions for plotting 3d or grid data. To see an
--
2.43.0
Advice sought: The section, 3d grid plots, is tricky:
example-{4,5,6}.png are not reprocible using the code in the file. I am
not sure they can even be produced using org-plot and gnuplot as each
exists now, without some drastic surgery. For example, to produce a
facsimile of example-5.png, I need something like
#+name: org-mode-figure.gnuplot
#+header: :var table=org-plot-org-mode-table
#+begin_src gnuplot :exports none :results none
unset key
set xrange [0:16]
set yrange [0:13]
plot table matrix with image title 'org mode'
#+end_src
where `org-plot-org-mode-table' is the un-named table that occurs after
these figures. Of course, that does not exercise the features of
org-plot that are intended.
To produce something like example-{4,5}.png, I can do the following (set
view 15,30 for example-4). But, this example seems like an excursion
into gnuplot coding. And, again, I am not using "type:grid", despite the
name of the section.
#+NAME: org-plot-org-mode-table
#+PLOT: type:3d with:"pm3d" title:"org mode"
#+PLOT: set:"pm3d corners2color mean interpolate 0,0"
#+PLOT: set:"view 0,0; unset colorbox"
#+PLOT: set:"object 1 rectangle from screen 0, screen 0 to screen 1, screen 1
fc rgb 'black' fillstyle solid 1.0"
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 0 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1 | 0 | 0 |
| 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
| 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
| 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 1 | 1 | 0 |
| 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 |
| 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 |
| 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
| 0 | 1 | 0 | 0 | 1 | 0 | 1 | 1 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
| 0 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 1 | 1 | 0 | 0 | 1 | 1 | 1 | 0 | 0 |
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
Leo
