The key tool here is the wonderful org-mode extension Org-R by Dan Davison. It allows to include code fragments that create figures or tables directly into your document. That way, everything will be in one place.  Searching, au revoir.

Introduction to Org-R

Luckily, Dan wrote a comprehensive tutorial on how to use org-R. If your planning to give it a try, I suggest to look over his words first. However, he forgot to mention two things you’ll need to enable the org-R goodness. Insert

(add-to-list ‘load-path “~/site-lisp/org-mode/contrib/lisp”)
(require ‘org-R)

into your .emacs and edit the directory to point into your org-mode directory. Also, you need to have a R instance running (invoke M-x R) in the directory of your document. Try some of the examples given in his tutorial in a new .org document now.

What happens behind the scenes here is that org-R translates the inline commands into a R command sequence. For example, infile:x.csv is converted into x = read.table(...) . The +RR prefix introduces direct R commands, which are executed before the +R commands (except infile:). The result is then inserted as a table or as a link to a graphic. Note that many actions rely on conventions:  outfile:x.png will create a png image. Reading from a datafile will only work if the file suffix is .csv. And its contents will always be stored in a variable x. If you are not sure what is happening behind the scenes, the command showcode:t shows you the created R-code and is hence a great tool for debugging.

Using figures

A typical fragment for creating a figure that is also exported into LaTeX/PDF/HTML properly is

#+CAPTION: Distribution of foot sizes among coputer scientists
#+LABEL: fig:SizeDistribution
#+ATTR_LaTeX: scale=0.5
[[file:images/distanceDist.png]]
#+R: infile:”tmp.csv” #+R: action:density columns:1 args:(:lwd 4)
#+R: outfile:”images/distanceDist.png”
#+R: inline:t

The first three lines give the image a caption and a reference, and define the size of the image in the paper. Invoking C-c (or org-apply) in the second part will (re-)create the image. The command #+R: inline:t is required for the resulting link to the image having the same format as the LaTeX exporter recognizes for figures.

Keeping your document clean

The main intend of org-R obviously was to enable org-mode users to perform quick calculations and create simple graphs from data that originates from org-tables. Undeniable, org-r is very good at that. However, our objective shall rather be to centralize and de-fragment drafting of papers containing complex figures. When it comes to more elaborate graphs and datasets, the usefulness of  the predefined actions vanishes and longer, more complex R code is required. You might rather want to work in ESS/R-mode, where you have all the coloring and intendation niceness, and you do not have to precede every line with an +RR:.

The alternative is to source the functions from a separate .R file, for example you could use

#+CAPTION: Distribution of finger lengths among computer scientists
#+ATTR_LaTeX: scale=0.5
#+LABEL: fig:LengthDistribution
[[file:images/distanceDist.png]]
#+R: infile:”tmp.csv”
#+RR: source(”rcode.R”)
#+RR: myDensity(x)
#+R: outfile:”images/distanceDist.png”
#+R: inline:t

with the following code (imagine a longer fragment) in rcode.R

myDensity <- function(x) {  
plot(density(x[,1]), col=”chartreuse4″, lwd=5, xlim=c(0,2000))
}

That way, you avoid immense R code pollution in your draft, yet you have all the information (data-files, linked code and parameters) in one place. Happy drafting!

Assume you’re developing a small software under Linux, maybe using C or C++ and the GCC compiler. Testing your program, you find that it crashes with an error (segfault, assertion, …). How do find the cause for this crash rapidly? How can you back-trace the error?

First, compile your program again adding the option “-g” (or “-gstabs“). The compiler (e.g. g++) will now include information necessary for debugging into your binary. Start Emacs and invoke “M-x gdb“. As parameter, enter the full path of your executable. You end up with something like “gdb --annotate=3 ~/myProject/myProgram“. In the newly opened buffer, set the commandline parameters as for example in “start --verbose-mode inputfile.dat“. Simply append the program options you normally use after “start“.

Run the command “c” (=continue). Your program will start – and crash. Now, invoke “M-x gdb-many-windows“. You will see the steps leading to the function that caused the crash in the window “stack frames”. By clicking on each of the steps, Emacs will directly navigate to the respective source code block, enabling you to trace the cause of the error. Find a more extensive tutorial here.

Also, as he reported on a conference I attended recently, the author of Pub-Mode is developing a Bibliographic Management System that, amongst other things, automtically fetches the PDF-file of a reference. No more clicking through publishers websites. I’m really waiting for this one!

Installation

First, you have to install org-mode for Emacs as described here. Org-mode is included in Emacs since version 22.1 and the latest version can be obtained from the a git repository via

git clone git://repo.or.cz/org-mode.git

Be sure to use the latest version for this tutorial as there really is some active development going on and some of the features I use were included just recently.

The First Document

Begin by opening a new files with a “.org” extension. Paste the following lines into that document

The Impact of Beer Consumption on Scientific Collaboration
#+AUTHOR: Mario Fasold
* Introduction
** Previous Work
Some studies relating scientific output and beer have previously been done.
#+BEGIN_QUOTE
In Europe, most alcohol is consumed as beer and, based on well known negative effects of alcohol consumption on cognitive performance, I predicted negative correlations between beer consumption and several measures of scientific performance.
#+END_QUOTE
([[www.zoologie.upol.cz/osoby/Grim/Grim_Oikos_2008_on-line.pdf]])
* Results
** What beer should you drink
+ Becks
+ Czech Budweiser
+ Duff


The first line contains the title of your document. It will be used by each of the exporters, e.g. LaTeX or HTML. Note that there was a bug in the latex exporter, leading to duplicated text after the table-of-contents if the first line of the document was a headline. Leaving the fist line empty is the suggested workaround here.

The export can be controlled by various parameters that can be set anywhere in the org-document. The syntax is “#+OPTIONS: toc:nil”, for example (available options). Some export options that might be useful to create a paper draft include

• #+AUTHOR: the author (default taken from user-full-name)
• #+DATE: A date, fixed, of a format string for format-time-string
• #+EMAIL: his/her email address (default from user-mail-address)

Using the very simple org-mode markup, the document then defines some sections, subsections, textblocks and formulas. Note that only the first three outline levels (* – ***) are used for headlines by default. Using the markup you can easily define lists, include other files, enter footnotes, define literal and source code blocks (and even use Emacs font-lock for those areas) and more. For example, a text literal is inserted via

#+BEGIN_EXAMPLE
Some example from a text file.
#+END_EXAMPLE

and the following passes code directly into latex

#+BEGIN_LaTeX
All lines between these markers are exported literally
#+END_LaTeX

Another honored mention be the org-tables mode which lets you create and edit and tables in a dead-easy manner (try to swap a table column in AucTeX…).

Figures

Papers and their drafts can’t live without images in most cases. The following syntax allows since december to insert one

#+CAPTION: Degradation Plot
#+ATTR_LaTeX: scale=0.75
#+LABEL: fig:degradation
[[./images/DegradationPlot.png]]

It’s a little buggy still, for example, no underscores seem to be allowed within filenames for now. For more complex cases, you can just write the LaTeX-code (org-mode will recognize many identifiers):

\begin{figure}[!tpb]
\centerline{
\includegraphics[scale=0.3]{images/BeerPlot}
}\caption{This is plot looks like a beer.}\label{fig:Beer}
\end{figure}

References

You may also want to include references while drafting the paper. Luckily, you can use RefTex-Mode (included in Emacs) to scan your BibTeX-file (containing the bibliographies) and easily insert a reference to an entry of that file. First, activate RefTex in org-mode by inserting the following lines into .emacs:

(defun org-mode-reftex-setup ()
(load-library "reftex")
(and (buffer-file-name)
(file-exists-p (buffer-file-name))
(reftex-parse-all))
(define-key org-mode-map (kbd "C-c )") 'reftex-citation)
)
(add-hook 'org-mode-hook 'org-mode-reftex-setup)

Second, include the BibTeX-file by inserting

\bibliographystyle{plain}
\bibliography{ProbePosition}

at the end of your org-document. When you want to insert the reference just invoke “C-c )”, enter a search term (e.g. auther name) and select the right one from the search results. Note: When first opening the org document, RefTeX will ask you to give him the name of the “master” which is the .tex-file corresponding to your org-file.

You can also use org-mode to collect notes about all the publications you are reading. Stick to this description to find out how you could manage bibliographies and PDF-documents in a nice way.

Outlook

Org-mode is a very versatile and extensible mode for Emacs. If Emacs is considered an Operating System, consider Org-mode as the Emacs for that system! I find org-mode particularly handy to draft papers. Include images, formulas, tables and references with ease, without the hassle of dealing with LaTeX markup.

Additionaly, you might use org-mode to organize related links, documents and data. With org-R you can even do any computations (e.g.statistics) and plots in-line using R – no need to fragment your information! Also, expect to see nice features appearing for org-mode frequently. I would be glad to hear how you use org-mode to collect information and do science!

Ps. Someone even wrote his complete diploma thesis with org-mode. He describes his experience here (his org-file is a good example, too).