Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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”.

ReferenceMeaning
@2$3Row 2, column 3 (spreadsheet name C2).
$5Column 5 in the current row.
@2Row 2 in the current column.
@-1$-3One 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, $0The current row and column.
@I, @II, …The first, second, … hline.
@-I, @+IThe first hline above, or below, the current row.
@III+2The second data row after the third hline.
@-I$2Column 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 @.

RangeFields
$1..$3The first three fields of the current row.
@2$1..@4$3The 9 fields of the rectangle A2..C4.
$<<<..$>>From the third column to the last but one, in the current row.
@-1$-2..@-1Three fields in the row above, starting two columns to the left.
@I..IIBetween 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 sideKindApplies to
$4=Column formulaEvery field of column 4, except header rows and fields with their own formula.
@>$4=Field formulaOne field.
@1$2..@4$3=Range formulaEvery field in the rectangle.
@3=Row formulaEvery field of row 3.
$total=Named field formulaThe 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.

ModeEffect
p20Compute with 20 digits of precision (default 12).
n3, s3, e2, f4Show the result in normal, scientific, engineering or fixed format with that many digits.
D, RAngles in degrees (default) or radians.
F, SFraction mode, symbolic mode.
uSimplify units in the result.
T, t, UTreat values as durations (see below).
EKeep empty fields in ranges instead of dropping them.
NTreat every field as a number; non-numbers become 0.
LLiteral interpolation, for Lisp formulas only.
%.2fA 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 as nan (not a number), so the result is nan. 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:

ModeA reference becomesUse for
(none)A Lisp string, "Ada"Text processing.
NA Lisp number, 12; non-numbers become 0Arithmetic.
LThe raw text, unquotedMixing 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:

  • T prints HH:MM:SS.
  • U prints HH:MM.
  • t prints a decimal number in the unit of org-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:

MarkMeaning 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.

KeyCommandEffect
C-c =org-table-eval-formulaEdit the column formula of the current column in the minibuffer.
C-u C-c =org-table-eval-formulaEdit the field formula of the current field.
C-u C-u C-c =org-table-eval-formulaPut the active formula into the field, to edit it in place.
C-c ?org-table-field-infoShow the coordinates of the field, or highlight the fields that the reference at point refers to.
C-c }org-table-toggle-coordinate-overlaysShow or hide row and column numbers.
C-c {org-table-toggle-formula-debuggerTurn the formula debugger on or off.
C-c 'org-table-edit-formulasEdit 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:

KeyEffect
C-c C-c or C-x C-sStore the formulas and return; with C-u, also recalculate the table.
C-c C-qReturn without storing.
C-c C-rToggle between @3$2 notation and B3 notation.
S-UP, S-DOWN, S-LEFT, S-RIGHTShift the reference at point to the neighboring field.
TABPretty-print or indent a Lisp formula.
M-UP, M-DOWNScroll 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.

KeyEffect
C-c *Recalculate the current row.
C-u C-c * or C-u C-c C-cRecalculate the whole table.
C-u C-u C-c * or C-u C-u C-c C-cRecalculate the table repeatedly until it stops changing (org-table-iterate).
C-c C-c on a #+TBLFM: lineApply that formula line to the whole table.
M-x org-table-recalculate-buffer-tablesRecalculate every table in the buffer.
M-x org-table-iterate-buffer-tablesIterate 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:

OptionMeaning
titleTitle of the plot.
indColumn used for the x axis.
timeindLike ind, for a column of timestamps.
depsColumns to plot, as a list such as (2 3); default: all others.
type2d, 3d, grid or radar; more types can be added through org-plot/preset-plot-types.
withGnuplot style for each series: lines, points, boxes, histograms, …
fileWrite the plot to this file instead of a window.
labelsSeries names, replacing the column headers.
set, lineExtra Gnuplot commands; may be repeated.
transposePlot rows as series instead of columns.
min, max, ticksAxis limits and tick count, used by plot types such as radar.
timefmtHow Gnuplot should parse timestamps.
scriptUse 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 =formula in a field for a column formula and :=formula for a field formula; both are stored in #+TBLFM:.
  • @ROW$COLUMN addresses fields; rows count data lines only, @I and @-I address 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 use N or L.
  • #+CONSTANTS:, $PROP_ properties and marked rows (!, ^, _, $) give names to values.
  • remote() and org-lookup-first read from other tables.
  • Recalculate with C-u C-c *; iterate with C-u C-u C-c * when formulas depend on later results; debug with C-c ', C-c ? and C-c {.
  • C-c " g plots with Gnuplot from a #+PLOT: line, and C-c " a adds ASCII bars.

Further reading