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

• autocompletion of object names by pressing TAB
• simple highlighting of matching brackets
• configuration of height and width of relax window

Installation

• Installation for windows:
• relax_1.3.14.zip
• relax_1.3.13.zip
• relax_1.3.12.zip
• relax_1.3.10.zip
• relax_1.3.9.zip (>=R-2.11.0)
• relax_1.3.8.zip (>=R-2.11.0)
• relax_1.3.7.zip (>=R-2.11.0)
• relax_1.3.6.zip (>=R-2.11.0) -- (via CRAN available)
• relax_1.3.0.zip (>=R-2.7.0)
• new 1.3.8-features: playground, some weave facilities, code chunk player, history function, processing of single chunks or LaTeX environments, icons of plot in the report field, button for activation of help examples

• version >= 1.2 of relax / new features: now the including of a code chunk index and an object index is possible during weaving by weaveR(), also some "used-in" informations are added to the header lines of code chunks

  relax_1.3.2 zip (>=R-2.11.0) (via CRAN available)
  contains the installed version 1.2 of relax. The .zip file has to be extracted into your local R library -- for example: .../R-2.8.0/library/.

  Some configuration settings are stored in .../relax/config/settings.relax. Feel free to play around with the settings, but don't cry when relax doesn't work properly anymore.

• Installation for linux:
• relax_1.3.14.tar.gz
• relax_1.3.13.tar.gz
• relax_1.3.12.tar.gz
• relax_1.3.10.tar.gz
• relax_1.3.9.tar.gz (>=R-2.11.0)
• relax_1.3.8.tar.gz (>=R-2.11.0)
• relax_1.3.7.tar.gz (>=R-2.11.0)
• relax_1.3.6.tar.gz (>=R-2.11.0)
• relax_1.3.5.tar.gz (>=R-2.11.0) (via CRAN available)
• relax_1.3.0.tar.gz (>=R-2.7.0)

• relax_1.2.tar.gz (>=R-2.7.0)

• contains the newest versions of relax. This .gz file has to be installed by R CMD INSTALL

• newest features:
  * during saving as a html file code chunk names starting with "Rweb" will be transformed to Rweb text / submit fields
  * now there are two TeX-macros to modify the layout of text and code chunks, e.g. to redine the font size : \renewcommand{\textchunkcommands}{\normalsize}, \renewcommand{\codechunkcommands}{\small}

• Plots

  To be able to show copies of R-plots in the report field the "Img" package (written by Jan Nijtmans) for Tcl/Tk has to be installed. For installation Img on windows machines see help page of relax "> help(relax)". Windows-Users have to extract img1.3.zip into the lib directory of the relax package; afterwards the lib directory must contain a directory called "img1.3" -- see readme files in the img1.3 directory for questions of source code and license issues . Linux users have to install "Img" (see: img.html) and have to manually correct the path in the assignment of path.tcltk.package.img="/usr/local/lib" in ".../relax/config/settings.cfg".

• Installation of R for windows :

  R-2.13.0 (via CRAN -- TU Wien)

• old relax version: relax_1.1.zip (>=R-2.7.0) relax_1.1.tar.gz (>=R-2.7.0)  relax_1.07.zip (>=R-2.2.0) relax_1.07.tar.gz (>=R-2.2.0)    relax_1.083.zip (>=R-2.5.0) relax_1.083.tar.gz (>=R-2.5.0)

 ...

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

• Thanks to Mark Hempelmann and Torben Kuhlenkasper for testing and for checking documentations as well as for helpful ideas and discussions