R and S+ Mode Help
Name: | S+/R Mode |
Version: | 2.7 |
Last update: | 2021-05-18 15:43:55 |
This document describes the S+/R statistical mode for the text editor
Alpha.
Introduction
This mode serves primarily to make it easier to write statistical syntax
files for the R or S+ languages.
It is triggered automatically for files with a .s, .R or
.r extension. Note that the .r extension is also claimed by
the language C mode: use the menu item Alpha ↣ Global Setup ↣ Preferred Mapping in case of conflict.
The S mode includes its own menu called S+/R in the menu bar, allowing
Alpha to act as a front end for the Mac OS X version of the R
application. This means that R commands can be sent directly from Alpha to
R for execution. The menu includes Options, Help, and Keywords submenus
that contain items for obtaining command information, setting mode specific
preferences, and adding or removing keywords.
Since version 2.6 of S mode, Alpha is able to communicate either
with the
R Gui
application (R.app) or with
RStudio. You can
select which interpreter you want to use in the Options submenu (the
current one is marked by a diamond symbol ◇).
Editing features
The S mode has the following capacities:
- Syntax coloring, syntax completion, commenting preferences.
- The mode contains a full set of electric completions, as well as a
Completions Tutorial via the
Alpha ↣ S+/R Mode Setup menu item.
- The mode lets you execute R code from Alpha either by sending the
selected commands or an entire file to the R or RStudio gui applications,
or by typing commands in an interactive R console within Alpha.
See the Executing R code from Alpha section.
- An example syntax file is available. If
you open the example syntax file through the provided hyperlink, it will
open in a shell window. After you close the window, clicking on the
hyperlink will return the unblemished original.
- The mode automatically indents the new line created by the
Return
key. Adjust the mode's Indent On Return preference if you want
to turn off this feature. The mode recognizes both the continuation and the
end of commands, indenting appropriately. The indentation amount can be set
in the preferences panel Alpha ↣ Preferences ↣ Global Preferences ↣ Electrics. Click here to open the Electrics panel.
One could also take advantage of Alpha's indent on return
override key binding. Pressing Control-return will place the cursor on
the next line without any indentation.
- The mode has navigation menu items, bound to the
⌃⇧N
and ⌃⇧P
key combos. These items are also
bound to Control-Shift Arrrow keys, and to 1 and 3 on the keypad when the
Num-Lock is turned off.
Control-Shift up and down will find the prev/next command. The right
and left Arrrow keys not only find prev/next commands, but will also
place the cursor at the top of the window.
- The mode has its own indentation scheme, based upon unbalanced braces.
Entire commands can also be highlighted with
⌃⇧S
, or
reformatted (aligning indentation) with ⌃⇧I
.
The Full Indent mode preference determines if continued
commands are indented to the full Indentation Amount (which can be
set using Alpha ↣ Preferences ↣ Global Preferences ↣ Electrics panel), or just half of this value. Click here to open the Electrics panel.
- The mode has Mark Window and Parse Function
capabilities. Each marking routine can recognize either source or output
files.
- Finally, on-line help is available for each mode through Shift-Command-Double-Clicking. If you double-click on a keyword while
pressing the Shift-Command keys (
⇧⌘
), the corresponding help
page is opened in the R application.
Executing R code from Alpha
The S+/R menu provides commands to execute R instructions from the
currently edited window. The following commands are available:
- Process Current File
- This command sends the current window to R or RStudio for evaluation. If
the window does not correspond to a file on disk, the entire text is
executed line by line. Otherwise, the file itself is executed in the R
application via a source command.
- Process Selection
- Similar to the previous command but Alpha sends only the current selection.
You may select any set of R commands and send them for processing. If
there is no selection, the entire text of the current window is processed
line by line.
- Process A Script
- This command lets you select an R script file and sends it to R for
processing via a source command.
- Launch Console
- This command displays an R console within Alpha. The console establishes a
connection with the R command line (not the GUI application) and you can
type any instructions. The result is displayed directly in the console so
that you do not have to quit Alpha at all. Graphic commands need the
AquaTerm
program to be available on your machine.
Note that the R console is also directly available from the Console
Launcher package. If this package is activated, you do not need to be
in S+/R mode to lanch the console. See the documentation of the Console Launcher package.
Sweave support
Alpha supports the editing of sweave files (with a .Snw or .Rnw extension). For more information, see the Sweave support section of the LaTeX Mode
User's Guide.
S mode preferences
S mode preferences include items for indentation, help keys, etc.
Click here
to open the S mode preferences.
Keywords completion
S-Plus is remarkably elegant in structure. Commands have arguments, and
rarely does the language use the same names for both. Keywords are primarily based
on release number 3.3, taken from the 'common commands' as listed in
Venable and Ripley's Modern Applied Statistics with S-PLUS, second edition.
The Venable and Ripley MASS library can also be included in keyword lists for
completions by checking the Use Mass Library preference.
Keywords can be reviewed in "sMode.tcl" .
Each of the S+/R commands has an electric completion available, and the mode
comes with a Completions Tutorial, available via the
Alpha ↣ Mode Setup ↣ Edit Tutorial menu
item. Using the completion key, which can be defined with the menu item
Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Special Keys, the user can type
glm<complete>
and Alpha will automatically insert the following text:
glm(| ~ •)•
•
The template stops will allow the user to use the tab key to jump ahead to
insert the needed variable names, and the last stop will position the cursor
for the next command.
Additional keywords can be added or removed in two ways, through
the Keywords submenu, and in an SPrefs.tcl file. Extra keywords defined
(using either method) will be included in the electric completion routines.
The Keywords ↣ Add Keywords menu item will
let you specify your own keywords. These user defined keywords are
recorded between sessions.
Completions Tutorial: "S Tutorial.s"
S mode Carriage Returns
S mode has its own indentation scheme, based upon unbalanced braces, and
uses the Indent On Return preference for automatic indentation of new
lines. Each time that you start a new line with the Return
key, the
previous non-commented line is evaluated for unmatched (
and )
-- ignoring any braces that appear within double quotes or after valid
comment characters.
Lines that begin with ) will have their indentation reduced by one level to
match the line with the matching (
, as in
for (i in 1:length(data03.1$year)){
data03.1$year <- as.vector(data03.1$year)
if(data03.1$year[i] == "1965-70") (
data03.1$year[i] <- c("1965-69")
)
}
In some cases, as when you are continuing a command, you might want to
over-ride this behavior. For example, if you type
qqno|
and press the completion key, the command completes to
qqnorm(|)••
Typing resid and pressing the completion key again turns the line into
qqnorm(resid(|)••)••
If you type some more text and then press Return, the next line will
automatically indent to
qqnorm(resid(out3.11), ylab = "deviance residuals",
|)••
which is properly indented. This would be fine if this line actually
terminated the command, but you might want to continue the command. To
over-ride this behavior, which in this case would increase the level of
indentation for the next line to 1, press Shift-Return instead:
qqnorm(resid(out3.11), ylab = "deviance residuals",
|)••
and then some more text and a regular carriage return will make the command
look like
qqnorm(resid(out3.11), ylab = "deviance residuals",
xlab = "extremities"
)
Entire commands can also be reformatted (aligning indentation) with
⌃⇧I
.
To enter a carriage return with no indentation whatsoever, press
⌃-Return
.
S File Marking
For S mode, Mark Window will return the first 35 characters of each command
that begins a new line. Therefore it should not include any indented or
continued commands. Headings will be marked, defined by three (and only
three) comment characters and a space at the start of a line. Subheadings are
indicated by four comment characters.
The File | The Mark |
### Section Heading | • Section Heading |
#### Subsection Heading | * Subsection Heading |
command varlist (options) | command varlist (options) |
Function parsing (available in the Parse popup menu of document windows)
will return only the command names, in alphabetical order.
Adding an S Prefs file
To declare additional keywords in an SPrefs.tcl file, select the menu
item Alpha ↣ Mode Setup ↣ Edit Prefs File and
add these lines:
set SUserKeywords {
blah bladdity
}
S::buildCompletionList
Include as many keywords as desired within the braces, separating each
keyword by at least one space or carriage return. Alpha will automatically
load this preferences file the first time that the S mode is invoked.
Any keywords contained in these categories will not only be colorized, but
will also be included as electric completions.
License and Disclaimer
Copyright (c) 2000-2021, Craig Barton Upright.
All rights reserved.
The S+/R Mode package is free software and distributed under
the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
- Neither the name of Craig Barton Upright nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CRAIG BARTON UPRIGHT BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.