In R, many characters come in pairs: parentheses, brackets, braces, and quotes ((, [, [[, ", and '). Failing to have a matching pair will often result in a parse error or an incomplete command, both annoyances. RStudio tries to circumvent this by automatically creating matching pairs when the first one is entered. That is, typing a left parenthesis adds a matching right one. Also, deleting one will can cause the other to be deleted if no text is entered in between.

While a useful convenience, this feature can be hard to get accustomed to, so it can be turned off. RStudio’s Options dialog (Preferences in Mac OS X) provides a toggle button (Figure 3-4). Even if this feature is turned off, RStudio still provides assistance with matching pairs by highlighting the opening parenthesis, bracket, or brace when the cursor is positioned at the closing one.

Figure 3-4. The Options dialog has the ability to turn off automatic matching of paired values

The console is excellent for quick interactive commands but not as convenient for longer, multiline commands. For such tasks, being able to type the commands into a file to be executed as a block proves very useful. Not only is it easier to see the underlying logic of the commands and to find any errors, this style also allows one to easily archive commands for later reference. The RStudio Source editor (described more fully in Source Code Editor) can be used for writing scripts and executing blocks of code from them.

A new R script file can be opened in the code editor using the leftmost toolbar button on the application toolbar or from the File > New > R Script menu item. Into this file a series of commands may be typed. There are different actions available that execute these commands in part or in total:

These actions are invoked via the menu bar, keyboard shortcut, or toolbar button. All appear under the Edit menu item and have their corresponding keyboard shortcut shown (Table 3-2). The toolbar buttons for the editor allow one to run the line or selection quickly, rerun the previous region, or source the buffer into R.

Working at the command line requires users to remember function names and the names of their arguments. To save keystrokes, many R users rely on tab completion to complete partially typed commands. The basic idea of tab completion is that when the user has a partially completed command and the Tab key is pressed, the command will be completed if there is only one candidate for completion. If there is more than one, a menu of candidates is given to choose from. The implementation of this feature varies across the different R interfaces, although most implement it—none, perhaps, as intuitively as RStudio. Here the menu provided for candidate selection is a context-sensitive completion dialog raised (when needed) by pressing the Tab key and dismissed by making a selection or by pressing either the Backspace or Escape key.

The completion dialog (see Figure 3-5) has a left pane with options that can be scrolled through, and usually a right pane providing details on the selection (if available). This short description is great for jogging memories as to what the value effects. The corresponding help page that contains this information can be opened by pressing the F1 key.

A candidate value for completion may be selected with a mouse, but it is typically more convenient to use the keyboard. Press the up or down arrow to scroll through the list and use the Enter key (or Tab key again) to select the currently highlighted value for insertion. Typing a new character will narrow the list of candidates.

The completion window depends on the context of the cursor when the Tab key is pressed. Here are some scenarios:

Keyboard shortcuts allow the user to quickly invoke common actions by pressing the appropriate keyboard combination. For example, many people have their fingers trained for the copy and paste keyboard shortcuts, as using them can be more convenient than using a mouse to initiate these actions. RStudio has numerous keyboard shortcuts. In keeping with standard GUI design, many of these appear alongside the menu item associated with the action. Here, we discuss those shortcuts that are implemented for the console and its integration with the source-code editor.

Keyboard shortcuts are usually operating-system dependent, and RStudio’s are no exception (though, they are not locale specific). Additionally, keybindings may also be editor-dependent. In particular, the well-established vi and Emacs keybindings are hardwired into many users’ fingers. The RStudio keybindings are a mix of OS-consistent bindings (e.g., copy and paste in Windows is Ctrl+C and Ctrl+V, and in Mac OS X, Cmd+C and Cmd+V) and Emacs-specific (e.g., Ctrl+K will kill all the text to the right of the cursor [including the end-of-line character] and Ctrl+Y will yank it back [paste it in]). Although vi users may feel left out, adding in the Emacs bindings surely makes many longtime R users happy—it is hard to retrain one’s fingers! Similar shortcuts have been present for a long time in R’s console through the readline library.

In Table 1-2, we listed shortcuts for navigation between components. Here in Table 3-1, we describe shortcuts for working at the console, and in Table 3-2 list the available shortcuts for sending commands from the source-code editor to the console. General editing shortcuts for the console and source editor are listed later in Table 5-1.

Interactive usage often involves repeating a past command or parts of a command. Perhaps one wishes to change an argument’s value, or perhaps there was a minor error. Retyping an entire command to make a minor change is tedious at best. A common instinct is to insert the cursor at the error and edit the previously issued command, but this is not typically supported by console usage. One might then be tempted to copy and paste the command to the prompt and proceed to edit. Though this works, the history mechanism speeds up this process.

RStudio keeps a stack of past commands and allows one to scroll through them easily. This can be done using the up and down arrow keys. As the arrows are pressed, the previous commands are copied to the prompt, allowing them to be edited. The list of commands can be scrolled through quickly.

To see more than one previous command at a time, the Ctrl+Up keyboard shortcut can be typed, and a history window, similar to that for tab completion, will pop up (Figure 3-9).

Figure 3-9. History pop up opened by Ctrl+Up or, as in this case, Ctrl+R. The latter narrows the history candidates by searching for previous command completions

History Browser

In addition to the command-line interaction with a user’s history, RStudio also provides a History browser (Figure 3-10), allowing the user to scroll through past commands or use a search box. The past commands are organized in time order, with timestamps added for extended sessions. By default, this component resides in a tab on the upper right, and may be raised by clicking on the tab or using the shortcut Ctrl+4.

The basic usage involves double-clicking a line, which sends it to the console to be edited or reissued (the focus shifts to the console, so just pressing the Enter key will re-execute the command). Other uses involve first marking a selection. A single click selects the line, and this selection can be extended by holding the Shift key and using the up and down arrows. Other selection modifications are also possible. The component’s toolbar has three buttons: one sends the selection to the console, one appends the selection to a file in the source-code editor (opening one if need be), and one removes the selection from the history list (the page icon with the red “x”). If a multiline selection is sent to the console, no continuation prompt is inserted, allowing one to edit any of the lines.

The toolbar also has icons to save the history to a file, read the history in from a file, and clear the history in its entirety.

Figure 3-10. The history component shows the session history, which allows commands to be recycled

The General panel of the options dialog has a couple of entries related to the history-recording mechanism: one to modify how the history is saved and one to toggle the option to remove duplicate commands.

Clicking on a value will initiate an action to edit or view the object. Currently, rectangular objects, such as data frames and matrices, are not editable. For these, RStudio provides an implementation for View (really dataentry).

For other objects, how the value gets edited depends on the type of object and its length.

For some atomic objects with length 1, the editing occurs within the Workspace browser (Figure 3-12). Clicking on the object highlights its value, which can then be edited using the browser as a property editor. The input expression is not evaluated and need not be of the same class.

More typically, clicking on an object invokes an editor in a pop-up window. In Figure 3-13, we see the editor appearing after clicking on the ch variable, a character vector of length 12.

Figure 3-12. Atomic objects of length 1 are edited inline

Figure 3-13. Simple pop-up editor is used to edit data vectors

One can edit and save, or simply cancel. Similarly, one can edit functions through the same editor.

For data frames and matrices, there is a data viewer. Clicking on such an object will open a view of the data in the code-editor pane similar to Figure 3-14. At the time of this writing, the view is limited to 100 columns and 1,000 lines. This view is a snapshot and is not updated if the underlying object changes. However, reclicking the object in the Workspace browser will refresh the view.

Figure 3-14. The data-frame viewer provided by RStudio is rendered in the Source-editor pane

The Workspace browser has a few other features available through its toolbar for manipulating the workspace:

Importing data into an R session can be done in numerous ways, as there are many different data formats. The R Data Import/Export manual provides details for common cases. For properly formatted text files, RStudio provides the Import Dataset toolbar button to open a dialog to initiate the process. You select where the file resides (locally, or as a web resource), then a dialog opens to select the file. Once a file is specified (and possibly downloaded/uploaded), a dialog appears that allows you to customize how the data will be imported. Figure 3-15 shows the defaults for reading in the mtcars data when first written out as a csv file.

Figure 3-15. Dialog for importing a data set from a formatted text file

The dialog has the more commonly used arguments for a call to read.table, but it is missing a few, such as comment.char.

RStudio provides its own device for the display of graphics, RStudioGD. By default, the device’s output is rendered in the Plots browser. Although the graphics are secretly image files, the RStudioGD device also allows for interactivity. In Figure 3-19 we see a graph from one of the examples of stat_contour from ggplot2 displayed in the browser.

Figure 3-19. Plots browser showing a graphic produced by R

The image is initially sized to fit the space allocated to the browser. If the browser is resized, the image will be regenerated to match the new size. This happens in the background, though there is a button to refresh the current plot on the component’s toolbar. If one desires an even larger view, the zoom toolbar button will open the graphic in a much larger Plot Zoom pop-up window. The zoom window is not an interactive device but a snapshot of the current graphic.

One benefit of how the device works is that a new graphic is produced each time (unlike many R devices, which essentially have an erase feature). This makes it easy for the component to keep a list of the graphics that are produced. One can scroll through old graphics using the left and right arrows located on the toolbar.

The currently viewed graphic can be exported as an image or .pdf file. RStudio provides a few dialogs to control this. In Figure 3-20, we see that the save-plot dialog allows one to easily specify the file type, directory, and file name of the image, as well as adjust the size of the image in pixels. The size can be adjusted by entering a value, or by dynamically adjusting the size with the grab handle in the lower right.

Figure 3-20. Export dialog for producing a graphic file for a plot

In addition, there are toolbar buttons to remove the current plot and to clear all the plots.

R allows for interaction with a graphic through the locator function, which returns the position of the point (in the “user coordinate system”) where the (first) mouse button is pressed; and the identify function, which returns the index of the point nearest to where the (first) mouse button is pressed. Both functions are implemented for the RStudioGD device.

When the functions are called, the Plots browser is raised (if it wasn’t already). The two functions are blocking, in that no input into the console is available until after the selection of coordinates is done. The console shows its stop icon, and the graphic device displays a message (Figure 3-21) that the locator is active, and instructs the user to press the Finish button. (For locator, one specifies ahead of time the number of points to identify, so the block will terminate if that occurs as well.)

Figure 3-21. When identify or locator is blocking input, the graphic window displays an alert

Through the tcltk package (and others), an R programmer can create graphics that can have associated GUI controls to manipulate the display. Through the manipulate package, RStudio users can too. This package is provided with RStudio and delivers a set of simple-to-define controls that provide values to an expression used for plotting. These controls include a button, a slider, a picker, and a checkbox.

The basic usage is:

To illustrate, Figure 3-22 shows the code that implements the tkdensity demo from the tcltk package (there are 103 lines in the original, but just 16 here).

When the commands are executed, RStudio produces a plot based on the initial values of the control and also pops up a window with the controls as shown in Figure 3-23). Manipulating these controls will update the graphic (but not add to the history of graphics). The control frame’s visibility is toggled through the double arrow icon in the control bar and the gear icon in the plot window.

This example shows three control types. A slider appears with both its own label, another label indicating the value, and a slider widget to adjust that value. The pickers are rendered using comboboxes, and the checkbox is displayed with its accompanying label.

Figure 3-22. Example R code for using the manipulate package for interactive graphics

Figure 3-23. The manipulate function creates a control panel for setting parameter values in a plot