Rgedit 0.8 Help

(c) 2009 - 2012, Dan Dediu

First, please be aware of several potential security issues when installing new wizards!

Table of Contents

    Introduction
    Main features
    Wizards
    Profiles
    Notes and FAQ
    Acknowledgements

Introduction

Rgedit is a gedit  plug-in tranforming it into a light weight IDE capable to interface primarily with the statistical programming environment R , but also with other interactive software packages such as Octave  and Pyhton , and even work remotely through, for example, SSH connections.

The project was inspired by the amazing rkward , JGR , Tinn-R and RStudio  (congratulations for a very good job!), which provide full-featured IDEs for R, designed for KDE , Java , MS Windows , and cross-platformm respectively.

Rgedit, however, aims to offer a simpler set of features than them, providing the proficient/professional R (and Octave, Python, etc.) user an environment which would boost their efficieny while keeping interference and resources consumption to a minimum. Moreover, by using GTK+  and gedit, it is better suited not only to users of Gnome  and Xfce, but also to those who prefer for example Openbox  or Fluxbox  and their own collection of applications. In fact, Rgedit is designed to facilitate working with R (and Octave, Python, etc.) under Linux  more or less independently of the Window Manager/Desktop Environment (I now work primarily on OpenSuse   and CentOS , but this project was developed and used also on Debian  , Archlinux and Ubuntu ).

    Main features

Below is a screen shot of a session using Rgedit (screenshots taken on a variety of systems: Debian Lenny/Gnome, ArchLinux/Xfce & Openbox, Debian Squeeze/Xfce, Ubuntu 10.04/Gnome).

• advanced editing offered by gedit, including multiple tabs each containing a different document and syntax highlighting;
• bottom panel containing one or more different consoles which can be accessed using the tabs on the right hand side (in this case, there are two R consoles open);
  
• these tabs can have custom names, color schemes and prompts for easy identification;
• the capacity to run the current line, current selection or the whole source file by clicking the appropriate buttons in the toolbar;
• the capacity to define blocks of source code - which are smart enough to take into account editing - and run them (in this shot, there is a block defined between lines 29 and 37);
• basic code folding: line 41 is the "head" of a whole section of source code, with the tooltip showing the first and last couple of folded lines;
  
• an optional left panel tab showing the most important elements of the R file (function defintions, data.frame defintions and custom landmark comments) and allowing fast navigation with the mouse;
• profiles are a very powerful and general mechanism allowing the user to use not only R but also Octave, Python or even conduct remote sessions over SSH, but to define his/her own profile or customize them to his/her own environment (for more information please see here).
  

The options accessible through the "Configure R interface" menu are the same as those accessible through gedit's plug-in configuration and are shown below:

• "Send as text a selection of at most NNN lines": implicitly, the current line and current selection are sent to the R console as if typed by the user using the keyboard, while the whole file and the source blocks are sent using R's source() function through a temporary file. The obvious advantage of the first method is that the line(s) are available in the history using the Up and Down keys, but it is limited by the size of R console's buffer. Therefore, it is recommended that selections larger than NNN lines be sent using the source() method;
• "Echo commands sent through source() (i.e., not as text)?": uncheck if you want to avoid seeing the actual commands piped to the R console using source(). This could be useful when sending large quantities of text to R and the interest is mainly in the actual results produced;
  
• "Use HTML help?": if using HTML help the help pages will be opened using the current Web browser, otherwise the within-console system will be used;
• "Advance to next line after sending the current one to R?": if yes, the editor will make the next line current, otherwise the current line will stay the same;
• "Audible bell?" and "Visible bell?": console options concerning the bell;
• Each of the (at most three) tabs containing an R console can have its own "foreground", "background" and R "prompt" colors (but see note v);
• "Use tab name in R's prompt?": should R's prompt contain the tab's name in addition to the standard ">" and "+" symbols? You can rename a tab by right-clicking inside its R console, select "Tab name" from the menu and change the name in the dialog box (see screencaptures below);

• "Cursor blink": the cursor in the R console can use either the system blinking settings, can blink anyway or not;
• "Cursor shape": the cursor in the R console can be shaped as a block, beam or line;
• "Font": allows the user to select the font used by the R console;
• "Scroll on keystroke?" and "Scroll on output?": should the R console scroll on these two events?
• "Scrollback lines NNN": how many lies to keep in the R console's history?
• "Start R console automatically when gedit starts?": if yes, the first R console will automatically start when gedit starts, otherwise the user will have to explicitly spawn it using the "Create new R workspace tab..." command: this conserves resources when gedit is rarely used to edit R code;
• "Should new R consoles use the current document's directory?": if checked, all newly started R consoles try to set the working directory to be the current' document's directory;
• "Show rgedit's warnings and messages when R starts?": if checked, then upon starting a new R console the most current warnings and messages (concerning new features and issues) are displayed as comments in the R consoles;
  
• "Start R console detached from gedit's bottom panel?": if yes, the R console will automatically start detached (as a separate window; see below);
• "Autorun R script on startup?": if yes, automatically runs a user-specified R script with an R console starts (or restarts);
  
• "Edit keyboard shortcuts": allows the user to define custom keyboard shortcuts through the dialog shown below. The shortcuts are introduced as text like "<Ctlr><Alt>X" or <Shift>P> or "None" if no shortcut is desired. For sending the current line/block/file/selection to R, "special" shortcuts involving Return and modifiers (<CTRL>,<SHIFT>,<ALT>) can be defined. Moreover, <Ctrl>C in the R console can be defined to copy the current selection (as in gedit itself), in which case <ESC> and/or <Ctrl>Q can be defined to do its job (i.e., to interrupt the current R task). Please note that gedit (actually, the plug-in) must be restarted for these changes to take effect. Also, shortcuts already used by gedit are unavailable;

• "Side panel options": allows the user to define behaviour of the side panel tab showing the most important landmakrs in the R document. The landmark comments are specially structured comments of the form # @@ RGEDIT LANDMARK @@: your text goes here which allow the user to define important places in the R document (by replacing the your text goes here with the desired information). These can be directly written in the document or inserted at the desired place using the right-click menu's or the R's menu Insert Landmark Comment.
  

• "Code folding options": while waiting for proper cde folding to be implemented in gtksourceview, the code folding engine provided by rgedit is fairly basic but functional. Its options can be accessed through the right-click menu within the editor view and provides the following possible actions depending on the context:
• "Fold block containing current line": this looks through the sourcecode and finds all valid R blocks (i.e., enclosed between { and }) containing the line on which the right-click was produced. Then, depending on the user's options as specified in the Code folding options dialog, it folds the highest level (i.e., largest) containing block, the lowest level (i.e., smallest) containing block or the highest/lowest level function() block;
• "Fold current selection": if there is a text selection, then the user can fold it;
• "Unfold code on current line": if the right-click occured on a line containing folded text (marked by color, text style, left-margin icon and a specific tooltip), the user can unfold it;
• "Unfold all folded code": this will unfold all (if any) folded code in the current document;
• "Inspect folded code...": if the right-click occured on a line containing folded text (marked by color, text style, left-margin icon and a specific tooltip), the user can insect its content in a dialog box without actually unfolding it;

• "Edit profiles": adds/deletes/changes profiles.

• Copy and Paste: from and to the R console. <Ctrl+V> is the keyboard shortcut for paste and, if defined, <Ctrl+C> for copy (also see note iv);
• Change the tab's name: see details above;
• Always show tabs?: if checked show the tab even if a single R console exists;
• Show tabs on: defines the side of the bottom panel on which the R console tabs will be shown;
  
• Close the tab: you can close the current tab (but not the first one) by sending a SIGHUP signal to the shell process within which R is hosted;
• Start R and Restart R: these two commands start a fresh R session in the current console (tab), the only difference being that Start R assumes that the bash session is active and ready to process user input (e.g., after quitting R and working in bash for a while) as it simply starts a session with R --no-save --no-restore, followed by the appropriate option commands (e.g., options(htmlhelp = TRUE) and options( prompt="2> ", continue="2+ " )), while Restart R assumes a running and ready R session, as it first quits it with q() and then calls the Start R commands (see note viii as well);
• Change R's working folder: allows the user to select the desired working folder and changes it (assumes a running and ready R session as it send a setwd("<selected_directory>") command; see note viii as well);
• Use document's folder: changes R's working directory to the current document's directory;
• Load and Save R Workspace: allows the user to interactively load and save R's workspace.
  

Wizards

• "text" is the simplest and means that the variable can be any text and creates a one-line edit widget in the interface;
• "list" represents a list of pre-defined values (given by the value elements) and the user can select one (singlechoice="True") through a combobox widget; default in this case is the number of the default choice, starting at 0;
• "editablelist" is a list of pre-defined values (given by the value elements) but the user can introduce a new one as well, through an editable combobox widget; default in this case is a free string, as for "text";
• "bool" is represented by a checkbox widget and stands for a boolean value.

1. in order to unleash the full power of Python (an example of complex string processing is given by the plots_index_plot.xml wizard), the Python code defined within $[Python and $] is allowed access to the __builtins__, which means that malicious code can even delete all your files (see here a discussion: http://diveintopython3.org/advanced-iterators.html#eval)
2. even if the Python code within the template won't format your HDD and eat your cat, there is the possibility that the generated R code will do that.

Profiles

Notes and FAQ

These are several notes and questions on different aspects of Rgedit:

1. Quitting R in a console: it is possible to quit R in an R console in the usual way (i.e, q()) but note that the workspace is not automatically saved on exit nor is the system asking you for that (namely, the R sessions are spawned with  --no-save --no-restore arguments). Upon quitting, a standard shell is available from with R can be relaunched (with R --no-save --no-restore) or any other command executed as you would do from a normal shell;
   
2. Closing R console tabs: there can be at most three R console tabs simultaneously open and only consoles 2 and 3 can be closed. To do this, quit R in the standard manner (see above) and simply type exit when in the shell. Typing exit in the first R console (after quitting R there) will have no effect (technically, it will respawn a shell after quitting the current one);
3. Defining, running and deleting source code blocks: blocks are contiguous sequences of source code starting at the begining of a given line and ending at the begining of another line. They are marked with symbols in the left margin and colored background. There can be only two blocks defined at any moment in a given source file, identified as block 1 and block 2. Block 1 is marked with symbols  and and the background color is light blue (for an example, see the first screenshot), while block 2 is marked with symbols  and  and the background color is gold. Defining a block is very easy: just select the lines you want to be contained (not necessarily starting at the beging of the first and ending at end of the last line) and press the define block 1  or define block 2  toolitem or menu entries: if the block was already defined it will be simply replaced with the new one. Please, note that the last line of the block is actually the beginning of the last selected line plus one. Editing the text within a defined block will cause the block to automatically adjust;
4. Copy and paste in the R console: in an R console, <Ctrl+V> can be used to Paste but <Ctrl+C> can still used to stop the current R process, but it can also be allowed to copy the current selection; however, the right-click menu gives easy access to Copy and Paste actions;
5. Text coloring in R console: due to the fact that the interaction with R is done through the terminal (see note viii), the amount of coloring text is limited; however, the R promot can be colored using xterm escape sequences and this helps a lot in easily identifying commands entered as opposed to text produced by R. However, due to the way in which the prompt character length is computed by R's line editor, these escape sequences are considered by R as actual characters, resulting in corruptions of the current line (extra characters at the begining). If the advantage of having a colored prompt exceed the corruption of the current line during editing, then feel free to enable this option;
   
6. Icons and artwork in general: as you have probably noted, I am definitely not the most gifted artist in the Universe! Couple this with my tendency towards minimalism and you get the icons and design in Rgedit. However, .if you have better skills and ideas, please consider contributing to the project on SourceForge.
7. GTK+ and Python programming: also, please note that even if I do have a lot of (especially C/C++) programming experience, this is my first ever project using GTK+  and Pyhton  (more exactly, PyGTK), so please be forgiving about less than optimal (to be nice) programming decisions. Again, if you feel you can improve bits an pieces please consider contributing to the project on SourceForge;
8. Why communicate with R through the console as opposed to embedding the shared library? This is a legitimate question, given that the embedding of R's shared library is the recommended strategy for building R GUIs and a number of R IDEs (including rkward) do it this way? Well, this decision has both pros and cons (as usual). The cons are obvious and include limited interaction with R (e.g., Rgedit cannot browse, display and edit in a nice way the defined objects in the current workspace) but the pros include a lighter and faster IDE which does not require any compiling nor does it bring R down because of its own bugs (no criticism of other IDEs intended!). Plus, it's much easier to write and maintain. If you think otherwise, please let me know your reasons and suggestions and either contribute to this project, start a new one or use one of the other IDEs/editors listed here;
9. To whom is Rgedit best addressed? I designed Rgedit with the proficient/professional R user in mind, a user which does not need a menu-driven interface to data analysis but is comfortable with the script itself, the R extensive help and R's website search facilities. Such a user supposedly would need a way to edit their extensive and complex R scripts and a good editor like gedit would obviously help. They would also need a way to pipe sections of this script into R and see what happens. Eventually, using relimp's very good showData() function to see how a data.frame looks and very rarely fix() to edit it would be more than enough. For beginners and casual users I would certainly recommend rkward, JGR or R Commander instead!
   

Acknowledgements