If you are looking at this on the web, and I hope you find it useful. But, a useful method of using this file to learn is to download the plain text .org file, open it in Emacs, and explore it, editing and/or evaluating the various blocks provided, seeing what they do, changing things, trying again, how did it change – all those pedagogical techniques. (If you somehow mess up, you can always download the file again!)

The structure of this document was originally designed to (and may still) parallel that of the short beamer presentation from the same project. There are pointers to other presentations and tutorials under below. In particular, you may find the Org Mode Quick Start guide, as well as a tutorial by Erik Iverson, org-mode-R-tutorial.org, and a more recent one from Vikas Rawal, orgpapers.org, useful.

A string inside square brackets, [abecde], means you, the user, should type the string, leaving out the square brackets.

Also, the Emacs convention for control and modifier (alt) keys is used. So, [C-x b] means type control x, then the letter b. And, [M-x b] would mean type modifier x (maybe better known as 'alt x'), then the letter b (almost certainly an error!).

Here's a brief map. After a brief introduction to Org Mode, we discuss

• the basics of source blocks, in which code is embedded;
• how to evaluate a source block (to produce results);
• how to export a .org file, including the code of source blocks and/or the results of evaluating them;
• how to extract source blocks from the .org file and write them to a file (a process known as tangling);
• the two options for editing source blocks;
• some of the header arguments that can be used; and, finally
• pointers to more information

Various sorts of "blocks" are supported in Org Mode files. These start with #+begin_..., and end with a corresponding #+end_..., where the ... are something like src, example, quote. A skeleton for some of these can conveniently be created with the command [M-x org-insert-structure-template] ([C-c C-,]), and entering the type of block you are interested in creating, e.g.,

• e for an example block (line wrapping does not apply) (#+begin_example)
• q for a quote block (line wrapping applies) (#+begin_quote)
• s for a source block (#+begin_src)

there are various other blocks; you can experiment by typing [M-x org-insert-structure-template] ([C-c C-,]) and then one of the following

• a
• c
• C
• E
• h
• l
• v

and seeing what you get, looking in the manual for enlightenment. (Of course, one can always search the manual for #[+]begin_.)

In addition to the source blocks mentioned above (and elaborated on below), Org Mode allows short bits of "verbatim" code to be introduced by a colon as the first non-blank column of a line

: this is verbatim

One can have longer runs of verbatim ("example") data (which is not word wrapped, etc.:

#+name: ex
#+begin_example
this is a block
that
holds more verbatim text
#+end_example

As well as longer bits of text that will be wrapped ("quote"):

#+begin_quote
this is a bit of
text that should
show up, eventually, strung out in a smaller
number
of
lines when "filled"
(e.g., [M-x org-fill-paragraph] ([M-q]))
#+end_quote

Blocks can optionally have names. These names can be used as :noweb references, or to use the value of a block (or, if a source block, of the block's results) as input (a :var) to another block in the file.²

Org Mode drawers are a way of "closing away" information you normally won't want to see. These start with a line :NAME:, where NAME is a string, and end with a simple(r) :end:.

A property allows you to associate values with keys. Of particular interest to us here are property drawers, which combine the two concepts to provide a place to put parameters that customize the environment in which Org Mode processes your file (and, in particular, for our case, the context in which source code is evaluated).

Source blocks can also be expressed using a =src_LANG= construct; a
=#+name:= line can be used to name the =src_LANG= block.  for example,
src_R{"hello, world"} {{{results(=hello\, world=)}}}.

Inline source blocks have their own syntax for header arguments:
src_R[:results output]{cat("hello, again")} {{{results(=hello\, again=)}}}.

And, the results of an inline source block can be used as input (via :var) to another source block.

#+name: whyo
src_R{"42"} {{{results(=42=)}}}

#+begin_src R :var x=whyo :exports results
x
#+end_src

#+RESULTS:
| 42 |
|    |

Source blocks can also be evaluated by call statements in the .org file. Call statements have two forms, somewhat similar to the two forms of source blocks.

First, a #+call line can trigger evaluation of a source block. To trigger the triggering, you will need to type [M-x org-babel-execute-src-block] ([C-c C-c]) with point positioned on the call line.

#+call: first-r-block()

#+RESULTS:
: this block has been evaluated

Similarly, there is an inline call statement form which can trigger
evaluation of a source block.  here it is, inline!
call_first-r-block() {{{results(=this block has been evaluated=)}}}.

inline call statements have a syntax for block-specific header arguments similar to that of inline source blocks.

When processing a table result of a previous source block to be used as an input variable to another code block, the :colnames header argument instructs Org Mode how to interpret the first row: should it be assumed to be a row of column names, a row of data, or should Org Mode use a heuristic to make that determination.

Similarly, Org Mode uses :rownames to determine whether the first column of each row should be considered as a name for that row, or simply as the data of the first column of that row.

Also, when processing the results of a code block, these header arguments tell some Org Mode language support routines how to deal with column and row names of the returned result. If left off, the Org Mode result of evaluation will drop any language-specific column and row names. However, if these header arguments are set to yes, language-specific column and row names will be included in the results placed in the Org Mode buffer.

#+BEGIN_SRC R
mtcars[1:3,]
#+END_SRC

#+RESULTS:
|   21 | 6 | 160 | 110 |  3.9 |  2.62 | 16.46 | 0 | 1 | 4 | 4 |
|   21 | 6 | 160 | 110 |  3.9 | 2.875 | 17.02 | 0 | 1 | 4 | 4 |
| 22.8 | 4 | 108 |  93 | 3.85 |  2.32 | 18.61 | 1 | 1 | 4 | 1 |

#+begin_src R :colnames yes :rownames yes
mtcars[1:3,]
#+end_src

#+RESULTS:
|               |  mpg | cyl | disp |  hp | drat |    wt |  qsec | vs | am | gear | carb |
|---------------+------+-----+------+-----+------+-------+-------+----+----+------+------|
| Mazda RX4     |   21 |   6 |  160 | 110 |  3.9 |  2.62 | 16.46 |  0 |  1 |    4 |    4 |
| Mazda RX4 Wag |   21 |   6 |  160 | 110 |  3.9 | 2.875 | 17.02 |  0 |  1 |    4 |    4 |
| Datsun 710    | 22.8 |   4 |  108 |  93 | 3.85 |  2.32 | 18.61 |  1 |  1 |    4 |    1 |

Many (most?) programming languages have a way of "including" the "textual" contents of one source file in the compilation or execution phase of another source file. I think of #include <stdio.h, for example, in C. Literate programming defines a way of doing this known as "noweb".

In Org Mode's implementation, inside a source block, a reference to a previous block of code named NAME is denoted by <<NAME>>. The double angle brackets signal that this is a noweb reference.⁴ However, by default, noweb processing is disabled in an Org Mode buffer. The :noweb header argument defaults to no, but can be set to yes to enable noweb processing. Again, as with all header arguments, this can be done on a per-file, per-subtree, or per-(referring-)source block basis.

The noweb reference <<NAME>> can refer to either the name of another source block in the .org file:

#+name: a-noweb-name
#+begin_src R :noweb no
  cm <- "copy me!"
#+end_src

#+RESULTS: a-noweb-name
: copy me!

or with the :noweb-ref header argument:

#+begin_src R :noweb-ref another-noweb-name :noweb no
  cmt <- "copy me, too!"
#+end_src

#+RESULTS:
: copy me, too!

#+begin_src R :noweb yes :results output
  <<a-noweb-name>>
  <<another-noweb-name>>
  cat(cm, "\n", cmt, "\n", sep="")
#+end_src

#+RESULTS:
: copy me!
: copy me, too!

(If you edit the header of the previous source block by changing "yes" to "no" and then evaluate it, you will get an error as R tries to parse a line that begins with <<.)

Note that, like the :noweb header argument, the :noweb-ref header argument can be set on a subtree basis. (I dread to think of what would happen were it to be set on a file basis. Okay, I have to try. Be right back… Not much happened. I suppose this is special-cased.)

In Org Mode, the evaluation of source blocks can include initializing variables, using the :var header argument.

#+name: gives-pi
#+begin_src R :var pi=3.14
  pi
#+end_src

#+RESULTS: gives-pi
: 3.14

The left hand side of the argument to :var is the name of the variable as seen by the code inside the source block. The right hand side can be a constant (as above), or can designate the output of another source block in the .org file. In that case, the right hand side is the name (#+name:) of the source block providing the desired result.

If you evaluate the following source block, you will be asked to allow evaluation twice: once to produce the result from the above source block, and a second time to produce the result from the source block you are evaluating.

#+begin_src R :var pitoo=gives-pi :session R :results output
  cat("you were", pitoo/pi, "close!\n")
#+end_src

#+RESULTS:
: you were 0.999493 close!

The language of the source block providing the value of the variable does same as the language of the source block receiving the value. In general, though, there may be some adaptation required to mould the shape of the input value to that needed by the source code.

#+name: from-python
#+begin_src python :results value
  return 21
#+end_src

#+RESULTS: from-python
: 21

#+name: to-r
#+begin_src R :var howmany=from-python
  2*howmany
#+end_src

#+RESULTS: to-r
: 42

The name on the right hand side, instead of naming another source block in the file, can also name, e.g., an Org Mode table.

In the following code block, the :colnames header argument is set to yes so that the first row is considered a row of column names.

#+begin_src R :var tbl=a-table :colnames yes :session R
  summary(tbl)
#+end_src

#+RESULTS:
| student          | first.exam   | second.exam  | final       |
|------------------+--------------+--------------+-------------|
| Length:4         | Min.   :1.00 | Min.   :1.00 | Min.   :2.0 |
| Class :character | 1st Qu.:1.75 | 1st Qu.:1.75 | 1st Qu.:2.0 |
| Mode  :character | Median :2.50 | Median :2.50 | Median :2.0 |
| nil              | Mean   :2.50 | Mean   :2.50 | Mean   :2.5 |
| nil              | 3rd Qu.:3.25 | 3rd Qu.:3.25 | 3rd Qu.:2.5 |
| nil              | Max.   :4.00 | Max.   :4.00 | Max.   :4.0 |

For R code, a second effect of setting :colnames to yes is that if the result is an R data frame, its column names (colnames()) will be preserved in the resulting Org Mode table

#+begin_src R :colnames yes
  mtcars[1:4,]
#+end_src

#+RESULTS:
|  mpg | cyl | disp |  hp | drat |    wt |  qsec | vs | am | gear | carb |
|------+-----+------+-----+------+-------+-------+----+----+------+------|
|   21 |   6 |  160 | 110 |  3.9 |  2.62 | 16.46 |  0 |  1 |    4 |    4 |
|   21 |   6 |  160 | 110 |  3.9 | 2.875 | 17.02 |  0 |  1 |    4 |    4 |
| 22.8 |   4 |  108 |  93 | 3.85 |  2.32 | 18.61 |  1 |  1 |    4 |    1 |
| 21.4 |   6 |  258 | 110 | 3.08 | 3.215 | 19.44 |  1 |  0 |    3 |    1 |

#+begin_src R :colnames no
  mtcars[1:4,]
#+end_src

#+RESULTS:
|   21 | 6 | 160 | 110 |  3.9 |  2.62 | 16.46 | 0 | 1 | 4 | 4 |
|   21 | 6 | 160 | 110 |  3.9 | 2.875 | 17.02 | 0 | 1 | 4 | 4 |
| 22.8 | 4 | 108 |  93 | 3.85 |  2.32 | 18.61 | 1 | 1 | 4 | 1 |
| 21.4 | 6 | 258 | 110 | 3.08 | 3.215 | 19.44 | 1 | 0 | 3 | 1 |

The :results header argument specifies many things. First, it specifies whether the results of an evaluation consist in the value "returned" by the evaluated source block, or by the output (to standard output) produced by the source block. The "value returned" means, in many programming languages (include R), the value of the last statement executed in the source block. You may have noticed examples of this use of :results in some of the previous source blocks. The values here are value and output.

#+name: usenowebhere
#+begin_src R :results none
  truepi <- pi
  cat(truepi, "\n", sep="")
  invisible(truepi*2)
#+end_src

#+begin_src R :results output
  <<usenowebhere>>
#+end_src

#+RESULTS:
: 3.141593

#+begin_src R :results value
  <<usenowebhere>>
#+end_src

#+RESULTS:
: 6.28318530717959

Normally, when Org Mode evaluates a source block, in instantiates a new process of the appropriate type (the R command, for example), provides that process with the source from the source block (expanding :noweb references), and lets it run.

This ensures that each run starts from a "clean state". On the other hand, it means that artefacts left behind by previous runs are not available to a future run in cases where that might be desirable. And, it can complicate debugging.

Thus, Org Mode provdies a :session header argument which names a buffer (that Org Mode will create, if it doesn't already exist) in which evaluations of the current source block (or, all source blocks in the file, or all in a subtree) will occur.

During a given Emacs instance, the first time you type [M-x org-babel-execute-src-block] ([C-c C-c]) in a source block with a given :session name, Emacs will prompt you for the name of the starting directory (with a default being the directory of the current file). It will then start up such a process, attach it to a buffer (i'm not totally sure of the Emacs terminology here) with the name provided as the argument to the :session header argument (or, use a language-specific default), and evaluate your code. This works for interpreted languages but not, to my knowledge, for compiled languages.

#+begin_src R :session R-session-name :exports code :eval never-export :results none
x <- 1
#+end_src

#+begin_src R :session R-session-name :eval never-export :exports code
x
#+end_src

If you evaluate the above two blocks in order, the second will return as a result the value of x set by the first.

After evaluations, you can use [M-x switch-to-buffer] ([C-x b]) to switch to that buffer and inspect the state, maybe set debug breakpoints, or debug after error or debug statement (browser(), say) in your code.

For R, the session buffer uses ESS[R] mode. (As well as in the OrgSrc minor mode.)

As I said above, the fact that future evaluations of the given source block, or of any other source block with the same :session argument, will run in the same R process is both a feature and a bug. On the bug side, you may end up developing code that only works with the accumulated state in the current buffer.

For example, say you are developing an R package and are testing it with some code that imports (require()) that package. And, say your test code points out an error in your package code, and that you fix your package code and re-build and re-install your package. Now, if you once again evaluate your test code, it will execute the require() statement but will do nothing as, as far as R is concerned, your package is already loaded. So, you will need to detach and unload your package which, if my memory serves me right

detach(package:PACKAGENAME, unload=TRUE)

or some such. Then, R will load the new version of your package the next time you or your code require's it.

Still, I find :session immensely valuable while developing code or doing an analysis. If you find yourself wanting to use a debugger to debug your code, or to incrementally build up state as your are working, I recommend (carefully) using it.

Sometimes you will have a long-running computation, the results of which are used as input to other computations, or for export. In this case, you may not want to have to re-run the computation if its results won't change. To help with this situation, Org Mode has the :cache header argument.

If a source block is marked with :cache yes is scheduled to be evaluated, Org Mode checks the following:

• the contents of the source block itself
• the header arguments to the source block
• the values of the sources of all the :var header arguments

If none of these have changed (as testified by a cryptographic hash over these) since the last evaluation of the source block, then the value of the previous evaluation is used as the value of the current evaluation.

Of course, if a source code block takes input from some external source, such as a file, that may have changed since the previous evaluation, Org Mode won't notice, and you may get incorrect results. Also, a source code block that makes use of the results of a random number generator will not be re-evaluated. It is the responsibility of the programmer to not mark source blocks of these types with :cache yes.

Here is an example. When it is actually evaluated, this source code block will block for two seconds. If you evaluate it a second time, the results will appear immediately.

#+name: long-computation
#+begin_src R :cache yes
  Sys.sleep(2)
  42
#+end_src

#+RESULTS[1850a21ec1cef57306973138b0c17881d00f9820]: long-computation
: 42

Now, we look at how :cache deals with one of the inputs changing. First, here is a source which produces the same value each time it is run:

#+name: stable
#+begin_src R
  23
#+end_src

#+RESULTS: stable
: 23

Then, a source that produces a different value each second:

#+name: unstable
#+begin_src R
  Sys.time()
#+end_src

#+RESULTS: unstable
: 2021-04-15 09:40:05

Then, two functions. The first uses results of the unvarying source code block as input. The first time you evaluate it with [M-x org-babel-execute-src-block] ([C-c C-c]), it will sleep the two seconds. However, after that, evaluating it will return results immediately.

#+begin_src R :var input=stable :cache yes
  Sys.sleep(2)
  input
#+end_src

#+RESULTS[1de9d77db24319fea2fea80b19d13eb552cda0f3]:
: 23

This function, on the other hand, takes as input results from the varying function. Each time (well, separated by at least one second) you evaluate it, it will take the full two seconds.

#+begin_src R :var input=unstable :cache yes
  Sys.sleep(2)
  input
#+end_src

#+RESULTS[0f1dc4a63574d3b29d8ea59bd124cad3d096b5e5]:
: 2021-04-15 09:40:08