RELAX

RELAX: R Editor for Literate Analysis and lateX

--- the all-in-one editor for data analysis
and easy creation of LaTeX based documents with R

designed by H. P. Wolf

-> relax icon:
-> Overview
-> How to work with relax? -- writing reports
-> Other uses of relax? -- modifying your computations, data sets, interactive papers for presentation, programming
-> Technical remarks
-> Installation

Overview

relax is designed for statisticians allowing them to write statistical reports without switching between text processing and R.

relax creates a window with a report field. The report field enables you to enter R expressions as well as pieces of text to document your ideas. Computations and plots can be included quickly. After finishing your work the sequence of text chunks, code chunks and integrated graphics and/or R-output will constitute the basis of your work. To achieve a higher quality relax integrates LaTeX compilation for professional formatting and pretty printing.

Reports and other papers written according to the rules of relax (even without prior use of this editor) can be opened with relax. Rwined?s striking feature is the possibility to easily modify your R-analysis in your already written report: Undo all your computations or modify only details, relax merges R-output and text or graphics for checking or presentation matters. You can also select and modify only few expressions and apply them to new data sets -- and so create one document to be used on several different occasions -- fast and efficient.

relax is based on the literate programming concept proposed by D.E. Knuth and the noweb system written by Norman Ramsey -- see: literate programming, literate programming, Donald E. Knuth, noweb.

Here you find a poster describing relax. Here is a snapshot: ...

How to work with relax?

How do we start relax?

After installing the package relax you activate the editor by loading the package relax and starting the R function relax():

> library(relax)
> relax()

relax() creates a new window consisting of two text fields and some buttons and menus.

The upper text field is the report field. Here you type in R expressions and the necassary annotations and remarks for properly documenting your argumentation. The lower field is the output field. It shows the results of R?s computations.

How do we write text and R expressions?

An analysis usually starts by describing the problem, the data and so on. First you will usually write an introduction or simply some explanations -- even if you just intend to brainstorm your ideas or put your thought into the right order: Text needs a "@"-character signalling the beginning of a new text chunk in the report field (light sky-blue). In the following we will refer to paragraphs or portions of text as text chunks whenever they start with the @ line.

To make relax understand that R commands are used and some calculations are to be integrated into the document we need an introductory expression, let?s call ot code chunk. It has a header line like "‹‹*››=" or "‹‹nice name for the following code››=". A code chunk is automatically completed by the following text chunk.

As you can see, using relax?s syntax is simple. All you need are two rules with text chunks and code chunks: "@" defines the start of a text chunk whereas "‹‹...››" shows the beginning of a code chunk.

Here is a simple example:

How do we evaluate R expressions?

To evaluate a code chunk you have to position the mouse cursor anywhere in the code chunk to be evaluated and press "EvalRCode" (or Alt+E). relax will extract the code and R will try to run it. Results are shown in the lower text field of relax (output field -- in a beach-like color).

How do we integrate results into the report?

By pushing Insert the contents of the output field are moved to the report field.

How do we integrate a plot into the report?

SavePlot generates a postscript copy and a jpeg copy of the current graphics device and inserts LaTeX / html commands in order to include the graphics file for further printing in LaTeX.

What's about "RemoveOut", "TrashROutput" and "PlanRCode"?

RemoveOut clears the output field. TrashROutput deletes the inserted R output of the report field the mouse is pointing at.

This way you can perform step by step your analysis: Writing text chunks, writing code chunks and inserting results. "PlanRCode" creates an empty text chunk and an empty code chunk to make your work easier.

How do we get a nice hardcopy of the report?

After finishing your statistical analysis you want to save the report. By activating SaveReport of the File-menu you are asked to choose a file name. Then relax will generate two files: a file with extension .rev and a "html" file. The second file can be viewed by a browser.

Friends of LaTeX prefer LaTeX for formatting. To generate a .tex-file from the source file (".rev"-file) you have to "weave" it. Weaving is initiated by selecting WebReport of the Wizardry menu. If the .tex version of the report contains a correct preamble, LaTeX will format it as usually. By the way the menu Wizardry has an item Wizardry->LaTeX.head to insert a simple preamble into the report. LaTeX can be invoked by relax (try: Wizardry->LaTeXReport), but you do not get any LaTeX error messages. Therefore it is recommended to normally compile the generated .tex file from your local LaTeX source. Proceed with the ".dvi"-file as usual.

example report file: pdf format

How to use relax most effectively -- gaining expertise fast

Repetition and modification of your data analysis

Load a ".rev"-file. Repeat the steps of the data analysis of your report. Interactively check the results through relax. Integrate new ideas -- modify the code chunks or append new expressions to enhance the analysis!

Application of code chunks to new data sets

If you have to operate with several data sets you can proceed as follows: 1. load a ".rev"-file containing your basic ideas or simply use a similar .rev file from the past that just needs to be modified, 2. assign a data set to the "formal" variable of the code chunks, 3. evaluate the code chunks (EvalRCode).

Hands on Presentations with relax

If you want to demonstrate your R analysis in a presentation, store the code chunks you are interested in as a .rev file. Load the source file, select the code chunks you need and simply evaluate them as a part of your discussion. This is an easy an impressive way to keep people interested and in touch with the subject. Comments or critics can be "felt and seen" without delay by modifying or extending the code spontaneously. Code chunks with name "start" (code chunk header: ‹‹start››=) will be evaluated at startup relax. This enables you to save the definitions of your own programmed functions in an appendix in "start" code chunks and you can use these at once in the first code chunk of the ".rev"-file.

Programming of R functions

Labelled code chunks, e.g. >>foo<< can be used in other code chunks like macros. This key structure refers to Donald Knuth?s literate programming style. Take a look at the following example.

Remark: strings in text chunks that are bracketed by [[...]] will be formatted as code.

Sweave

The syntax of Sweave is based on the noweb system. Consequently, you can construct an Sweave file by relax interactively.

Technical Remarks

relax is written in R and Tcl/Ttk. To make it work the package relax needs to be installed in R. Some local configuration settings are found in the file "your-R-library/relax/config/settings.cfg".

relax checks your report in an environment named "revive.env". If this variable is not found the environment is generated. Otherwise it is used to evalute the code chunks. After exiting relax you can have a look at "revive.env" and change the objects of "revive.env" by hand. The internal variables of relax are stored in a second environment. It can be found via "revive.sys" stored in environment "revive.env".

New Features of Version 1.02

Installation

...

enjoy relax and relax -- P. Wolf, M. Hempelmann

License

relax is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. relax is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A copy of the GNU General Public License is available via WWW at http://www.gnu.org/copyleft/gpl.html

Acknowledgements