The Spreadsheet and Plotting
An Org table can compute. You attach formulas to a table, and Org fills in fields from other fields: totals, averages, conversions, durations, text built from other columns. The formulas are stored as plain text under the table, so the computation lives in the same file as the data and the prose that explains it. This makes Org a good fit for the small calculations that appear in notes: a budget in a project plan, the hours in an invoice, the results of a benchmark.
Org’s spreadsheet is not a copy of a conventional spreadsheet program. It has column formulas that apply to a whole column without copying, it references rows relative to horizontal rules, and recalculation happens when you ask for it. This chapter explains how references work, how to write formulas in Calc and in Emacs Lisp, how to name things, how to recalculate and debug, and finally how to plot a table. It assumes you know the table editor from The Table Editor.
Every table in this chapter that shows results was recalculated with Org 9.8.13 in Emacs 31.1, and the output is pasted unchanged.
A first formula
Here is a small budget. The cost of each item is the quantity times the unit price, and the last row holds the total.
| Item | Qty | Unit price | Cost |
|----------+-----+------------+------|
| Keyboard | 2 | 49.50 | |
| Monitor | 1 | 219.00 | |
| Cables | 5 | 3.20 | |
|----------+-----+------------+------|
| Total | | | |
To fill the Cost column, move to the first Cost field, type =$2*$3;%.2f and press TAB. The leading = tells Org that this is a column formula: one formula for every field of the column. $2 and $3 mean “the second and third field of the same row”, and ;%.2f formats the result with two decimals.
For the total, move to the bottom field of the Cost column, type :=vsum(@I..@II);%.2f and press TAB. The leading := makes it a field formula, valid only for that field. @I..@II is the range between the first and the second horizontal rule, and vsum adds it up.
Each TAB stored a formula and computed only the field you typed it in. Org keeps both formulas in a #+TBLFM: line under the table, separated by ::, so at this point the table reads:
| Item | Qty | Unit price | Cost |
|----------+-----+------------+-------|
| Keyboard | 2 | 49.50 | 99.00 |
| Monitor | 1 | 219.00 | |
| Cables | 5 | 3.20 | |
|----------+-----+------------+-------|
| Total | | | 99.00 |
#+TBLFM: $4=$2*$3;%.2f::@5$4=vsum(@I..@II);%.2f
To compute the rest, recalculate the whole table with C-u C-c * (or press C-c C-c on the #+TBLFM: line):
| Item | Qty | Unit price | Cost |
|----------+-----+------------+--------|
| Keyboard | 2 | 49.50 | 99.00 |
| Monitor | 1 | 219.00 | 219.00 |
| Cables | 5 | 3.20 | 16.00 |
|----------+-----+------------+--------|
| Total | | | 334.00 |
#+TBLFM: $4=$2*$3;%.2f::@5$4=vsum(@I..@II);%.2f
Org stored the field formula under the absolute address of the field: @5$4 is row 5 (horizontal rules do not count), column 4. The column formula did not overwrite the header, because column formulas skip the rows above the first hline, and it did not overwrite the total, because a field formula takes precedence over a column formula in its field.
If you add rows with the table commands, Org updates @5$4 for you. You can also edit the #+TBLFM: line and write @>$4 (last row, fourth column) instead, which stays correct however the table grows. From now on, the table recalculates when you ask: change a quantity, press C-u C-c *, and the cost and the total follow.
References
A formula refers to other fields by their position. Org’s native notation is @ROW$COLUMN: @ introduces a row and $ a column. Rows are numbered from 1 and count only data lines; horizontal rules are not rows. Spreadsheet-style names like C2 also work as input, but Org shows formulas in its own notation unless you set org-table-use-standard-references to t.
Figure 7.1: Rows are counted without hlines, hlines have their own Roman-numeral names, and a relative reference is measured from the field being computed.
The grid in the figure was produced by Org itself: a range formula wrote each field’s own coordinates into it, using @# and $#, which expand to the row and column of the field being computed.
| A | B | C | D |
|------+------+------+------|
| @2$1 | @2$2 | @2$3 | @2$4 |
| @3$1 | @3$2 | @3$3 | @3$4 |
|------+------+------+------|
| @4$1 | @4$2 | @4$3 | @4$4 |
#+TBLFM: @2$1..@>$>='(format "@%s$%s" @# $#)
In a live buffer you do not need such a trick: C-c } overlays row and column numbers on the table, and C-c ? shows the coordinates of the field at point.
Absolute and relative references
A reference with an unsigned number is absolute: @2$3 is always the same field, whichever field the formula computes. A reference with a sign is relative: @-1 is the row above the current one, $+2 the column two to the right. If you leave out the row or the column, the current one is used, so $2 alone means “column 2 of this row” and @2 alone means “row 2 of this column”.
| Reference | Meaning |
|---|---|
@2$3 | Row 2, column 3 (spreadsheet name C2). |
$5 | Column 5 in the current row. |
@2 | Row 2 in the current column. |
@-1$-3 | One row up, three columns to the left. |
@<, @> | The first and the last row. |
$<, $> | The first and the last column. $>>> is the third column from the right. |
@0, $0 | The current row and column. |
@I, @II, … | The first, second, … hline. |
@-I, @+I | The first hline above, or below, the current row. |
@III+2 | The second data row after the third hline. |
@-I$2 | Column 2 of the row just below the hline above the current row. |
The symbolic references @<, @>, $<, $> and the hline references are worth preferring. When you insert or delete rows and columns with the table commands, Org adjusts absolute references in the stored formulas, but a reference anchored to the table edge or to a rule does not need adjusting at all. A total written as vsum(@I..@II) stays correct no matter how many rows you add between the rules.
Hline references make grouped tables easy. In this table, each subtotal sums the rows between the second and the first rule above it:
| Quarter | Region | Sales |
|---------+--------+-------|
| Q1 | North | 120 |
| Q1 | South | 95 |
|---------+--------+-------|
| Q1 | Total | 215 |
|---------+--------+-------|
| Q2 | North | 140 |
| Q2 | South | 110 |
|---------+--------+-------|
| Q2 | Total | 250 |
#+TBLFM: @4$3=vsum(@-II..@-I)::@7$3=vsum(@-II..@-I)
Both formulas are identical apart from their target; the relative hline references find the right rows from each total.
Ranges
Two references joined by .. form a range, a rectangle that includes both corners. If both ends are in the current row, a short form is allowed ($2..$7); otherwise the first end must start with @.
| Range | Fields |
|---|---|
$1..$3 | The first three fields of the current row. |
@2$1..@4$3 | The 9 fields of the rectangle A2..C4. |
$<<<..$>> | From the third column to the last but one, in the current row. |
@-1$-2..@-1 | Three fields in the row above, starting two columns to the left. |
@I..II | Between the first and the second hline (short for @I..@II). |
A range becomes a vector of values. Calc’s vector functions (vsum, vmean, vmax, vmin, vcount and many others) take it directly. Empty fields are normally left out of the vector, which matters for averages; the section on Calc modes shows how to change that.
Kinds of formulas
The part of a formula before = decides where its result goes. Org knows five kinds:
| Left-hand side | Kind | Applies to |
|---|---|---|
$4= | Column formula | Every field of column 4, except header rows and fields with their own formula. |
@>$4= | Field formula | One field. |
@1$2..@4$3= | Range formula | Every field in the rectangle. |
@3= | Row formula | Every field of row 3. |
$total= | Named field formula | The field named total (see “Names and parameters” below). |
A column formula must use a column number or $> on its left-hand side, never a column name. Only one formula per column is kept: typing a new =... in a column replaces the previous column formula. To reuse the stored formula in a field, type = alone.
You can enter formulas in three ways. Typing =... or :=... into a field and pressing TAB, RET or C-c C-c stores and applies it. C-c = (org-table-eval-formula) prompts for the column formula of the current column, and C-u C-c = for the field formula of the current field. Range, row and named formulas have no shortcut; write them in the formula editor (see below) or directly in the #+TBLFM: line, and apply them with C-c C-c on that line.
Clearing a field does not remove its formula, because the formula lives in the #+TBLFM: line; the next recalculation fills the field again. To remove a formula, delete it from that line, or give an empty answer to C-c =.
Formulas in Calc
By default, a formula is an algebraic expression for Calc, the calculator that comes with Emacs. Org substitutes the references with field values and passes the result to Calc. Calc handles numbers of any size, fractions, units, dates, vectors and symbolic algebra, so even complicated arithmetic usually needs only one line.
One rule of Calc catches everyone at least once: / binds more loosely than *. In Calc, a/b*c means a/(b*c). Compare the three columns in the middle:
| a | b | c | a/b*c | (a/b)*c | a*c/b | sqrt(a) |
|----+---+---+-------+---------+-------+---------|
| 12 | 2 | 3 | 2 | 18 | 18 | 3.464 |
| 10 | 4 | 5 | 0.5 | 12.5 | 12.5 | 3.162 |
#+TBLFM: $4=$1/$2*$3::$5=($1/$2)*$3::$6=$1*$3/$2::$7=sqrt($1);%.3f
When a formula divides and multiplies, add the parentheses you mean, or put the multiplication first.
Modes and formats
After the formula, a semicolon introduces a mode string: letters that change how Calc computes and how Org prints the result. They combine freely, as in ;Dp3%.1e.
| Mode | Effect |
|---|---|
p20 | Compute with 20 digits of precision (default 12). |
n3, s3, e2, f4 | Show the result in normal, scientific, engineering or fixed format with that many digits. |
D, R | Angles in degrees (default) or radians. |
F, S | Fraction mode, symbolic mode. |
u | Simplify units in the result. |
T, t, U | Treat values as durations (see below). |
E | Keep empty fields in ranges instead of dropping them. |
N | Treat every field as a number; non-numbers become 0. |
L | Literal interpolation, for Lisp formulas only. |
%.2f | A printf-style format applied to the result. |
Org’s defaults, set in org-calc-default-modes, keep the output short: Calc computes with 12 digits but displays at most 8 significant digits. A % format is the most common mode; without it, a result like 576 may appear as 576., which is how Calc writes a floating-point number with no fraction.
Empty fields
Empty fields are where Org differs most from other spreadsheets, and the E and N modes are how you control them. Consider measurements with a missing value:
| Run | t1 | t2 | t3 | Mean | Mean E | Mean EN |
|-----+----+----+----+------+--------+---------|
| a | 12 | 15 | 18 | 15 | 15 | 15 |
| b | 10 | | 14 | 12 | nan | 8 |
#+TBLFM: $5=vmean($2..$4)::$6=vmean($2..$4);E::$7=vmean($2..$4);EN
- Without a mode, the empty field is dropped: the mean of 10 and 14 is 12.
- With
E, the empty field is kept asnan(not a number), so the result isnan. This is right when a missing value means the result is unknown. - With
EN, the empty field counts as 0: the mean of 10, 0 and 14 is 8. Use this only when a blank really means zero.
Calc’s if function lets a formula react to empty input, for example if("$2" == "nan", string(""), $2*1.2);E leaves the result empty when $2 is empty.
Formulas in Emacs Lisp
Calc is excellent with numbers but awkward with text. When a formula needs string manipulation, conditionals or a call to an existing Lisp function, write it in Emacs Lisp. A formula that starts with '( is a Lisp form. Before evaluating it, Org replaces each reference with the field content.
How the content is inserted depends on the mode:
| Mode | A reference becomes | Use for |
|---|---|---|
| (none) | A Lisp string, "Ada" | Text processing. |
N | A Lisp number, 12; non-numbers become 0 | Arithmetic. |
L | The raw text, unquoted | Mixing strings and numbers; quote string references yourself as "$1". |
The following table derives three columns from names. The first two formulas work on strings; the third uses L and writes the quotes itself.
| First | Last | Login | Chars | Initials |
|-------+----------+-----------+-------+----------|
| Ada | Lovelace | alovelace | 11 | A.L. |
| Alan | Turing | aturing | 10 | A.T. |
#+TBLFM: $3='(downcase (concat (substring $1 0 1) $2))::$4='(+ (length $1) (length $2))::$5='(concat (substring "$1" 0 1) "." (substring "$2" 0 1) ".");L
The default string interpolation is a common source of errors when you do arithmetic. In the first table below, (+ $1 $2) becomes (+ "1" "2"), which fails, and Org writes #ERROR into the field. With ;N the references become numbers, and the text foo becomes 0:
| a | b | a+b |
|---+-----+--------|
| 1 | 2 | #ERROR |
| 3 | foo | #ERROR |
#+TBLFM: $3='(+ $1 $2)
| a | b | a+b |
|---+-----+-----|
| 1 | 2 | 3 |
| 3 | foo | 3 |
#+TBLFM: $3='(+ $1 $2);N
A range in a Lisp formula becomes a sequence of values separated by spaces, so you can wrap it in a list: '(apply #'+ '($1..$4));N adds four columns. Because a semicolon starts the mode string, a formula that contains a semicolon in a string needs an extra ; at the end, as in '(concat $1 ";");, to tell Org that the earlier semicolons belong to the formula.
Durations and times
Times of day and durations in the form HH:MM or HH:MM:SS are text to Calc. The modes T, U and t turn them into numbers of seconds for the computation and format the result:
TprintsHH:MM:SS.UprintsHH:MM.tprints a decimal number in the unit oforg-table-duration-custom-format(hours by default).
| Task | Start | End | Spent | Spent U | Hours |
|----------+-------+-------+----------+---------+-------|
| Review | 09:15 | 10:40 | 01:25:00 | 01:25 | 1.42 |
| Meeting | 13:00 | 14:30 | 01:30:00 | 01:30 | 1.50 |
| Write-up | 15:05 | 17:50 | 02:45:00 | 02:45 | 2.75 |
|----------+-------+-------+----------+---------+-------|
| Total | | | 05:40:00 | 05:40 | 5.67 |
#+TBLFM: $4=$3-$2;T::$5=$3-$2;U::$6=$3-$2;t::@>$4=vsum(@I..@II);T::@>$5=vsum(@I..@II);U::@>$6=$4;t
The total of the Hours column is computed from the duration in the same row ($4 with t), not by adding the rounded decimal values, which avoids rounding errors. Negative durations work too, and plain integers count as seconds. Whether hours are padded to two digits is controlled by org-table-duration-hour-zero-padding. For timing work you actually do, Org’s clock is usually the better tool; see Clocking, Effort and Timers.
Names, constants and parameters
Formulas full of $4 and @II are compact but hard to read a month later. Org lets you give names to values at three levels.
Constants for a file or for all files
A #+CONSTANTS: line defines names for the whole file, and org-table-formula-constants defines them for every file. A property of the current entry (or of an ancestor) is available as $PROP_Name. All of these are written with a $ in formulas:
#+CONSTANTS: vat=0.19 fee=2.5
* Shop order
:PROPERTIES:
:Discount: 0.1
:END:
| Item | Net | Gross | Paid |
|------+------+-------+-------|
| Pen | 4.00 | 4.76 | 6.78 |
| Pad | 9.50 | 11.30 | 12.67 |
#+TBLFM: $3=$2*(1+$vat);%.2f::$4=$3*(1-$PROP_Discount)+$fee;%.2f
Taking the discount from a property means that the same table can be copied into another entry with a different Discount value and give the right result there.
Names inside a table
For names that belong to one table, reserve the first column for marking characters. A mark in the first field of a row gives the row a special role:
| Mark | Meaning of the row |
|---|---|
! | Its fields name the columns, so $Tot can stand for $6. |
^ | Its fields name the fields in the row above. |
_ | Its fields name the fields in the row below. |
$ | Its fields define parameters such as max=50, used as $max. |
# | Recalculate this row automatically on TAB, RET and S-TAB, and with C-u C-c *. |
* | Recalculate this row with C-u C-c *, but not automatically. |
/ | Do not export this row (useful for cookie and column-group rows). |
C-# (org-table-rotate-recalc-marks) cycles the mark of the current row, or of all rows in the region. Here is an estimate that uses column names, a parameter and two named fields:
|---+---------+-------+------+------+---------|
| | Item | Hours | Rate | Net | Gross |
| ! | | h | r | net | gross |
|---+---------+-------+------+------+---------|
| # | Design | 6 | 80 | 480 | 576.00 |
| # | Build | 14 | 70 | 980 | 1176.00 |
| # | Test | 5 | 60 | 300 | 360.00 |
|---+---------+-------+------+------+---------|
| # | Total | | | 1760 | 2112.00 |
| ^ | | | | tnet | tgross |
| $ | vat=0.2 | | | | |
|---+---------+-------+------+------+---------|
#+TBLFM: $5=$h*$r::$6=$net*(1+$vat);%.2f::$tnet=vsum(@II..@III)::$tgross=vsum(@II..@III);%.2f
The formulas now read almost like prose: net is hours times rate, gross is net plus VAT, and the two totals are named tnet and tgross. Note that the column formulas still use $5 and $6 on the left-hand side; column names are allowed only on the right, while a named field such as $tnet may also appear on the left.
In a table with marks, recalculation works differently. C-u C-c * recomputes only rows marked # or * and fields that have their own formula, and column formulas are not applied in rows whose first field is empty. Rows marked # also recompute as you move through them with TAB or RET, which gives semi-automatic recalculation while you type. If that makes editing slow in a large table, use * instead.
Using other tables
A formula can read from another table with remote(NAME,REF). NAME is the #+NAME: of a table in the same file, or the ID of an entry, possibly in another file, in which case the first table in that entry is used. REF is an absolute reference or range inside that table.
#+NAME: hours
| Week | Hours |
|------+-------|
| 46 | 32 |
| 47 | 41 |
|------+-------|
| Sum | 73 |
#+TBLFM: @>$2=vsum(@I..@II)
| Rate | Weeks 46-47 | Invoice |
|------+-------------+---------|
| 65 | 73 | 4745 |
#+TBLFM: $2=remote(hours,@>$2)::$3=$1*$2
This lets you keep raw data in one place and build summaries elsewhere in the file. Recalculate the source table first, or use M-x org-table-iterate-buffer-tables, which recalculates all tables in the buffer until the values stop changing.
Lookups
To look up a value by key, combine remote with one of Org’s lookup functions in a Lisp formula. (org-lookup-first VAL S-LIST R-LIST) finds the first element of S-LIST that equals VAL and returns the element at the same position in R-LIST. org-lookup-last returns the last match, and org-lookup-all returns every match as a list, for use inside a larger Lisp expression. An optional fourth argument replaces equal as the comparison.
#+NAME: rates
| Currency | Per EUR |
|----------+---------|
| USD | 1.08 |
| JPY | 162.40 |
| CAD | 1.49 |
| Item | EUR | Currency | Rate | Local |
|--------+-----+----------+-------+----------|
| Hotel | 240 | JPY | 162.4 | 38976.00 |
| Train | 85 | CAD | 1.49 | 126.65 |
| Dinner | 60 | USD | 1.08 | 64.80 |
#+TBLFM: $4='(org-lookup-first '$3 '(remote(rates,@2$1..@>$1)) '(remote(rates,@2$2..@>$2)));L::$5=$2*$4;%.2f
The L mode inserts the currency codes and rates without quotes, so the Lisp form compares symbols ('JPY against the list (USD JPY CAD)) and returns a number. When the ranges in a lookup may contain empty fields, add E so that the two lists stay aligned.
Editing and debugging formulas
Once a table has several formulas, the #+TBLFM: line becomes hard to read. Org offers several ways to see and edit formulas in context.
| Key | Command | Effect |
|---|---|---|
C-c = | org-table-eval-formula | Edit the column formula of the current column in the minibuffer. |
C-u C-c = | org-table-eval-formula | Edit the field formula of the current field. |
C-u C-u C-c = | org-table-eval-formula | Put the active formula into the field, to edit it in place. |
C-c ? | org-table-field-info | Show the coordinates of the field, or highlight the fields that the reference at point refers to. |
C-c } | org-table-toggle-coordinate-overlays | Show or hide row and column numbers. |
C-c { | org-table-toggle-formula-debugger | Turn the formula debugger on or off. |
C-c ' | org-table-edit-formulas | Edit all formulas of the table in a separate buffer. |
The formula editor opened by C-c ' is the most comfortable of these. It lists one formula per line and highlights the fields that the reference at point refers to. Inside it:
| Key | Effect |
|---|---|
C-c C-c or C-x C-s | Store the formulas and return; with C-u, also recalculate the table. |
C-c C-q | Return without storing. |
C-c C-r | Toggle between @3$2 notation and B3 notation. |
S-UP, S-DOWN, S-LEFT, S-RIGHT | Shift the reference at point to the neighboring field. |
TAB | Pretty-print or indent a Lisp formula. |
M-UP, M-DOWN | Scroll the window that shows the table. |
When a formula fails, the field shows #ERROR. To see why, turn on the debugger with C-c { and recompute a single field, for example with C-u C-u C-c = RET. Org then shows each step: the formula after reference substitution, the expression sent to Calc or Lisp, and the result.
Several formula lines
A table may have more than one #+TBLFM: line. Pressing C-c C-c on one of them applies that line only, which lets you switch between alternative calculations. In this table, C-c C-c on the second line computed the reduced rate:
| Net | Tax |
|-----+-------|
| 100 | 7.00 |
| 250 | 17.50 |
#+TBLFM: $2=$1*0.19;%.2f
#+TBLFM: $2=$1*0.07;%.2f
A normal recalculation (C-u C-c *) always uses the first line, and gives back the standard rate:
| Net | Tax |
|-----+-------|
| 100 | 19.00 |
| 250 | 47.50 |
#+TBLFM: $2=$1*0.19;%.2f
#+TBLFM: $2=$1*0.07;%.2f
Recalculation
Org never recalculates on its own, except in rows marked #. This keeps editing fast and the file stable, but it means you must recalculate after changing input values.
| Key | Effect |
|---|---|
C-c * | Recalculate the current row. |
C-u C-c * or C-u C-c C-c | Recalculate the whole table. |
C-u C-u C-c * or C-u C-u C-c C-c | Recalculate the table repeatedly until it stops changing (org-table-iterate). |
C-c C-c on a #+TBLFM: line | Apply that formula line to the whole table. |
M-x org-table-recalculate-buffer-tables | Recalculate every table in the buffer. |
M-x org-table-iterate-buffer-tables | Iterate every table in the buffer until all are stable. |
To know when one pass is enough, you need to know the order in which Org evaluates formulas. A full recalculation goes through the table once, in a fixed order:
flowchart TD
A["C-u C-c * : recalculate table"] --> B["Read the TBLFM line, expand names"]
B --> C["Column formulas: each data row, top to bottom, columns left to right"]
C -- "skip fields that have a field formula" --> D["Field and range formulas"]
D --> E["Align the table"]
E --> F{"Iterating, and the table changed?"}
F -- "yes, at most 10 passes" --> B
F -- "no" --> G["Done"]
Figure 7.2: Column formulas run before field formulas, so a column formula that reads a field computed by a field formula sees the old value until the next pass.
One pass is enough when every formula reads only fields that are input or that were computed earlier in this order. A running balance breaks that rule. In the next table, the column formula adds each amount to the balance in the row above, and a field formula seeds the first balance:
| Date | Amount | Balance |
|------------+--------+---------|
| 2026-11-01 | 1200 | |
| 2026-11-03 | -350 | |
| 2026-11-10 | -80 | |
| 2026-11-15 | 400 | |
#+TBLFM: $3=@-1$3+$2::@2$3=$2
A single C-u C-c * gives a wrong result, because the column formula for the second row ran before the field formula had filled the first balance:
| Date | Amount | Balance |
|------------+--------+---------|
| 2026-11-01 | 1200 | 1200 |
| 2026-11-03 | -350 | -350 |
| 2026-11-10 | -80 | -430 |
| 2026-11-15 | 400 | -30 |
#+TBLFM: $3=@-1$3+$2::@2$3=$2
C-u C-u C-c * repeats the calculation until the table no longer changes, and gives the correct balances:
| Date | Amount | Balance |
|------------+--------+---------|
| 2026-11-01 | 1200 | 1200 |
| 2026-11-03 | -350 | 850 |
| 2026-11-10 | -80 | 770 |
| 2026-11-15 | 400 | 1170 |
#+TBLFM: $3=@-1$3+$2::@2$3=$2
When a table needs iteration, it is often clearer to remove the dependency instead. Here, a column formula that sums all amounts from the first rule down to the current row computes each balance directly, and one pass is enough:
| Date | Amount | Balance |
|------------+--------+---------|
| 2026-11-01 | 1200 | 1200 |
| 2026-11-03 | -350 | 850 |
| 2026-11-10 | -80 | 770 |
| 2026-11-15 | 400 | 1170 |
#+TBLFM: $3=vsum(@I$2..@0$2)
Plotting
Numbers in a table often make more sense as a picture. Org can draw a table in two ways: through Gnuplot, or as ASCII bars inside the table itself.
Graphs with Gnuplot
C-c " g (org-plot/gnuplot) plots the table at point. It needs the Gnuplot program and the gnuplot Emacs package (gnuplot-mode). Options go in a #+PLOT: line directly above the table:
#+PLOT: title:"Build time per release" ind:1 deps:(2 3) type:2d with:linespoints set:"yrange [0:]" file:"build-time.png"
| Release | Debug (s) | Release (s) |
|---------+-----------+-------------|
| 1.0 | 212 | 340 |
| 1.1 | 198 | 322 |
| 1.2 | 175 | 301 |
| 1.3 | 160 | 288 |
Org writes the data rows to a temporary file, separated by tabs, and generates a Gnuplot script from the options. The column headers become the series titles. For the table above, Org 9.8.13 generated this script (file names are shortened here):
reset
set term png
set output '.../build-time.png'
set title 'Build time per release'
set yrange [0:]
set datafile separator "\t"
plot '/tmp/org-plot...' using 1:2 with linespoints title 'Debug (s)',\
'/tmp/org-plot...' using 1:3 with linespoints title 'Release (s)'
Seeing the script explains the options: ind chooses the x column, deps the y columns, with the Gnuplot style, and set passes a raw Gnuplot command. The most useful options are:
| Option | Meaning |
|---|---|
title | Title of the plot. |
ind | Column used for the x axis. |
timeind | Like ind, for a column of timestamps. |
deps | Columns to plot, as a list such as (2 3); default: all others. |
type | 2d, 3d, grid or radar; more types can be added through org-plot/preset-plot-types. |
with | Gnuplot style for each series: lines, points, boxes, histograms, … |
file | Write the plot to this file instead of a window. |
labels | Series names, replacing the column headers. |
set, line | Extra Gnuplot commands; may be repeated. |
transpose | Plot rows as series instead of columns. |
min, max, ticks | Axis limits and tick count, used by plot types such as radar. |
timefmt | How Gnuplot should parse timestamps. |
script | Use your own Gnuplot script; $datafile in it is replaced by the data file name. |
With file:, the plot is a file that you can link from the document and show inline (see Markup for Rich Contents), which turns the table and its chart into one self-contained report.
ASCII bar plots
For a quick look without any external program, C-c " a (orgtbl-ascii-plot) adds a column of text bars next to the column at point. The bars are an ordinary column formula that calls orgtbl-ascii-draw, so they update with the table:
| Month | Commits | |
|-------+---------+--------------|
| Jan | 42 | WWWWWWWW |
| Feb | 17 | WWW: |
| Mar | 63 | WWWWWWWWWWWW |
| Apr | 8 | W! |
#+TBLFM: $3='(orgtbl-ascii-draw $2 0 63 12)
The arguments of orgtbl-ascii-draw are the value, the value that gives an empty bar, the value that fills the bar, and the width of the bar in characters (12 by default). Values outside the range are shown as too small or too large. The last character of a bar is finer than a whole W, so short bars still show differences.
Summary
- Type
=formulain a field for a column formula and:=formulafor a field formula; both are stored in#+TBLFM:. @ROW$COLUMNaddresses fields; rows count data lines only,@Iand@-Iaddress hlines, and@<,@>,$<,$>stay valid when the table grows.- Calc formulas handle numbers, vectors and units; remember that
/binds more loosely than*. - Modes after
;set precision, formats, empty-field handling (E,N) and durations (T,U,t). - Lisp formulas start with
'(; references are strings unless you useNorL. #+CONSTANTS:,$PROP_properties and marked rows (!,^,_,$) give names to values.remote()andorg-lookup-firstread from other tables.- Recalculate with
C-u C-c *; iterate withC-u C-u C-c *when formulas depend on later results; debug withC-c ',C-c ?andC-c {. C-c " gplots with Gnuplot from a#+PLOT:line, andC-c " aadds ASCII bars.
Further reading
- Official manual: The Spreadsheet, References, Formula syntax for Calc, Formula syntax for Lisp, Durations and time values, Field and range formulas, Column formulas, Lookup functions, Editing and debugging formulas, Updating the table, Advanced features, Org Plot.
- The Emacs Calc manual, for functions and modes: Calc.
- Source at release 9.8.13: lisp/org-table.el (formulas and recalculation), lisp/org-plot.el (plotting).