Who should read this document
I recently learned about org mode for Emacs. Among other things, it allows to mix text and R source code similar to SWeave, but the markup for text is very simple.
To get things working can be complicated, especially if one is not an experienced user. Therefore this documents is intended to help novices with Emacs getting up and running as fast as possible.
Emacs is heavily keyboard based. In the following text C- will indicate the Control key pressed together with another key. Likewise, M- is the Altkey
(Meta key was the original name), and S- is set shift key. So C-c indicates Control key pressed simultaneously with c key, M-x indicates Alt key pressed simultaneously with x key.
A very minimalistic demo
The following example does not try to explain the options, I just want to help you to get up an running as fast as possible.
Let us look at an example of org code:
#+TITLE: Using org mode with R
#+AUTHOR: Erich Neuwirth
* Minimalistic demo
Just a piece of R code producing outpout
#+BEGIN_SRC R :session *R* :exports both
123*456
#+END_SRC
It also allows including plots in output
#+BEGIN_SRC R :session *R* :results output graphics :file first.png :exports both
x <- (0:100)/100
y <- x^2
plot(x,y,type="l",xlab=expression(x),ylab=expression(f(x)==x^2),
main="Quadratfunktion")
#+END_SRC
We can use the modern plotting package ~ggplot2~
#+BEGIN_SRC R :session *R* :results output graphics :file second.png :exports both
library(ggplot2)
x <- (0:100)/100
y <- x^2
qplot(x,y,geom="line",xlab=expression(x),ylab=expression(f(x)==x^2),
main="Quadratfunktion")
#+END_SRC
And it can produce nice tables
#+BEGIN_SRC R :results output org :exports both
library(ascii)
a <- runif(100)
c <- "Quantiles of 100 random numbers"
b <- ascii(quantile(a),header=TRUE,include.colnames=TRUE)
print(b,type="org")
rm(a,b,c)
#+END_SRC
We even can embed source code to perform computations
in-line:
1+2 = src_R[:session *R*]{1+2}
And we can embed mathematical formulas
$$\Phi(x|\mu,\sigma)=\int_{-\infty}^{x}\frac{1}{\sqrt{2\pi\sigma}}e^{\frac{(t-\mu)^2}{2\sigma^2}}dt$$ |
Converting this org file into html produces
this page.
Converting this org file into TeX and pdf produces this page.
If your Emacs is configured correctly, all you have to to is to copy the above text into a file
with extension .org and open this file in Emacs. In Emacs then just press the keys
C-c C-e b.
Putting the cursor in one of the code snippets in the file and pressing the keys C-c C-c will put the results of the computation (with additional markup) directly after the code snippet.
All this will, however, not work if Emacs is not configured correctly.
Configuring Emacs
We describe how to setup Emacs on Windows and on OSX
To be able to run this in Vincent Goulet’s Emacs (available from his site) for Windows and for OSX.
Emacs has to be configured to make org mode with R work. Configuration of Emacs is usually done by statements in a file names .emacs in the directory Emacs considers your home directory.
If your installation of Emacs is new, you might not yet have this file.
You can open (or create if necessary) this file by starting Emacs and typing C-x C-f. Then the bottom line of the Emacs window will display ~/ and wait for you to enter a file name. Just type .emacs. Now we need to copy some commands into this file.
On Windows, Emacs org mode needs soe help to find the correct version of R.
Since org mode and ESS (Emacs Speaks Statistics, used by org mode) are under very vivid development, this might change in the near future.
On OSX, no special initialization is necessary for this.
Therefore we have three slightly different versions of the initialization file for the different OSes.
On Windows with 32bit R and a standard installation, then following code is needed in .emacs
;; At first, we make sure that our modifications in .emacs ;; are applied _after_ default.el is read/ (setq inhibit-default-init t) (load "default.el") ;; We ensure that Emacs can copy from and to the clipboard (setq x-select-enable-clipboard t) ;; Now we set up Emacs to find R ;; The path to R might need to be changed (setq-default inferior-R-program-name "C:/Program Files/R/R-2.15.3/bin/i386/Rterm.exe") (setenv "PATH" (concat "C:\\Program Files\\R\\R-2.15.3\\bin\\i386" ";" (getenv "PATH"))) ;; Configuring org mode to know about R and set some reasonable default behavior (require 'ess-site) (require 'org-install) (org-babel-do-load-languages 'org-babel-load-languages '((R . t) ) ) (add-hook 'org-babel-after-execute-hook 'org-display-inline-images) (add-hook 'org-mode-hook 'org-display-inline-images) (setq org-confirm-babel-evaluate nil) (setq org-export-html-validation-link nil) (setq org-export-allow-BIND t) (setq org-support-shift-select t) (setq org-src-fontify-natively t) |
For 64bit R in a standard installation you need
;; At first, we make sure that our modifications in .emacs ;; are applied _after_ default.el is read/ (setq inhibit-default-init t) (load "default.el") ;; We ensure that Emacs can copy from and to the clipboard (setq x-select-enable-clipboard t) ;; Now we set up Emacs to find R ;; The path to R might need to be changed (setq-default inferior-R-program-name "C:/Program Files/R/R-2.15.3/bin/x64/Rterm.exe") (setenv "PATH" (concat "C:\\Program Files\\R\\R-2.15.3\\bin\\x64" ";" (getenv "PATH"))) ;; Configuring org mode to know about R and set some reasonable default behavior (require 'ess-site) (require 'org-install) (org-babel-do-load-languages 'org-babel-load-languages '((R . t) ) ) (add-hook 'org-babel-after-execute-hook 'org-display-inline-images) (add-hook 'org-mode-hook 'org-display-inline-images) (setq org-confirm-babel-evaluate nil) (setq org-export-html-validation-link nil) (setq org-export-allow-BIND t) (setq org-support-shift-select t) (setq org-src-fontify-natively t) |
For OSX on a Mac you need
;; At first, we make sure that our modifications in .emacs ;; are applied _after_ default.el is read/ (setq inhibit-default-init t) (load "default.el") ;; We ensure that Emacs can copy from and to the clipboard (setq x-select-enable-clipboard t) ;; Configuring org mode to know about R and set some reasonable default behavior (require 'ess-site) (require 'org-install) (org-babel-do-load-languages 'org-babel-load-languages '((R . t) ) ) (add-hook 'org-babel-after-execute-hook 'org-display-inline-images) (add-hook 'org-mode-hook 'org-display-inline-images) (setq org-confirm-babel-evaluate nil) (setq org-export-html-validation-link nil) (setq org-export-allow-BIND t) (setq org-support-shift-select t) (setq org-src-fontify-natively t) |
Copy the code for your OS into you Emacs window displaying the (initially possibly empty) .emacs file. Then save the file with C-x C-s and close Emacs with C-x C-c.
You are now ready to run our demo.
Running the demo
Now start Emacs again, type C-x C-f and then type OrgWithR.org to open a new file. Copy the text from the first code window of this document into Emacs and type C-x C-s to save the file.
Type C-c C-e and in the options window that appears type b. After a few seconds the html file will be displayed in a browser.
Type C-c C-e and in the options window that appears type d. After a few seconds the pdf file will be displayed in a browser.
Put the cursor into a code segment (somewhere between #+begin_src and #+end_src and type C-c C-c. The results of running the code will appear just below the code segment.
Close Emacs and open the file OrgWithR.org you just created. You might be surprised that you see only the first few lines, like this.
#+TITLE: Using org mode with R #+AUTHOR: Erich Neuwirth * Minimalistic demo... |
Putting the cursor (called point in Emacs speak) into the line Minimalistic Demo... and pressing TAB will expand the file. Pressing TAB in this line again will collapse the text. This way, you can hide or show selected parts of your document while working with it.
Further tips
On Windows you are in for a surprise. Emacs by default does not use C-c/C-x/C-v for Copy/Cut/Paste. The Options menu, however, has an item to use the standard windows keys for these operations.
How do you learn Emacs and org mode?
Emacs itself has a very nice tutorial accessible from the opening screen.
Org mode tutorials can be found at http://orgmode.org/worg/org-tutorials/index.html.
A tutorial on using org mode with R can be found at http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-R.html
If you also want spell checking, just download and install Aspell. The Windows version is available at http://aspell.net/win32/. You need to install the dictionaries separately from this site.
On Macs with OSX you can use cocoAspell available from http://cocoaspell.leuski.net/. The installer from there does include the English dictionary, but it is not completely activated. To activate it, open a Terminal window and run the following commands:
cd /Library/Application\ Support/cocoAspell/aspell6-en-6.0-0 sudo ./configure sudo make install |
If you need to install other dictionaries, get the archive files from
ftp://ftp.gnu.org/gnu/aspell/dict, unpack the archive(s) and run the ./configure and sudo make install commands in the unpacked directory.