Architect – Advanced

Documentation: Defining R Snippets

Mon, 01 Jan 0001 00:00:00 +0000

R Snippets are chunks of R code that you can assign to a keyboard shortcut. Architect ships with some default, simple snippets, but you can define customized snippets to perform far more complex tasks.

Access the snippets menu by typing ‘R Code Snippets’ into the Quick Search bar (Ctrl + 3), or navigate to it via the menus by selecting Window > Preferences > StatET > Run/Debug > R Code Snippets.

The above snippet allows you to switch the working directory of your active console at the push of a button. But to do so, we must first associate a key binding to the command. If you click the Keys button at the bottom of the R Code Snippets window, you’ll reach a menu for customizing keyboard shortcuts.

Find the desired snippet, then assign your command. Above, we assigned the command Ctrl + r, Ctrl + w to the change working directory snippet. This allows us to click on a folder in our Project Explorer, enter the chosen command, and our active console will change its working directory to that folder.

Documentation: Debugging

Mon, 01 Jan 0001 00:00:00 +0000

Architect has an advanced tool for visual debugging. In this exercise, we’ll use the following code to demonstrate the debugging functionality:

myFun <- function(x){
  y <- x + 2
  z <- y - 3
  myOtherFun(z)
}

myOtherFun <- function(x) {
  m <- matrix(diag(x), ncol = 2)
  colnames(m) <- c("A", "B")
  return(m)
}

data(cars)

 # myFun(6)

Launch via debugger icon

The visual debugger can only be used within an R session launched by the Debugger icon () in the top toolbar. Click on the icon and select the R version you’d like to use.

Set a breakpoint

Visual debugging works with the concept of breakpoints. By setting a breakpoint, you instruct Architect to pause the evaluation of code at a given line. This allows you to quickly get under the hood of complex chunks of code and inspect the values of variables.

To set a breakpoint, double click in the “gutter” on the line where you’d like evaluation to be paused.

You can set multiple breakpoints in the same script.

Now, when we run code, evaluation will be paused when either breakpoint is reached.

Source the script

The last preparatory step is to source the script you intend to debug. Source the script by typing Ctrl+r, Ctrl+s. Our breakpoints will update visually with a check mark to show we are ready to debug:

Run code

With our breakpoints set, we run the code by calling:

myFun(6)

When a breakpoint is reached, the debug perspective launches automatically.

Note that you can toggle to your previous perspective with the toggler in the top-right corner ().

Inside of the debugging view, we have access to debug-specific commands:

(F5): execute the current line and move to the next line. If the current line contains a function call, the debugger will step inside of that function.
(F6): execute the current line of code and move to the next, without stepping into any called functions
(F7): steps out of the currently executed function and returns to that function’s caller
(F8): resume code evaluation until the next breakpoint

Conditional Breakpoints

Suppose we would like a breakpoint to trigger only if a certain condition is met. In a trivial example, say we have a loop that will run 10 times, but we only want the breakpoint to trigger on the ninth iteration.

We can set such a condition in the breakpoint window.

Debugging Installed Packages

If you’ve installed a package in Architect via R CMD INSTALL, you can debug it by placing a breakpoint within a function and calling that function.

Documentation: Git Repositories

Mon, 01 Jan 0001 00:00:00 +0000

You can link a directory to a git repository through the “Git Repository” window. Access this window by quick searching ‘git repository’, or through the main menus via Window > Show View > Other > Git > Git Repositories.

This window gives controls for adding, cloning and creating git repositories.

: add an existing local Git repository
: clone a Git repository
: create a new local Git repository

Once you have a local folder associated with a git repository, create a project in that folder, as demonstrated in the Your First Project section.

Git actions can then be performed by right-clicking a project and accessing the Team menu. All Git repository interactions are powered by the Eclipse EGit plugin. Click here for a comprehensive EGit user guide.

Documentation: Installing Different Versions of R

Mon, 01 Jan 0001 00:00:00 +0000

Architect ships with an embedded, recent version of R. To configure another version for use within Architect, use the following steps:

Install the desired version of R.
Open the newly installed version of R and install packages rj and rj.gd.

install.packages(c("rj", "rj.gd"), repos="https://download.walware.de/rj-4.0")

In Architect, select from the main menu Run > Run Configurations, and navigate to the R Console section. From there, click the button New launch configuration.
Click on the Configure... button in the R Config tab.

Click Add... to add the new R installation.

Name your installation (e.g. R 3.4.0), then in the Location (R_HOME) field, navigate to the installed R folder.

Click the button titled Detect Default Properties/Settings (see above). Then click OK. Your R environments should now look something like this:

Click Apply.
On the Run Configurations screen, R Config tab, choose the new configuration (e.g. R 3.4.0) for the Selected Configuration field, and click Apply.

In order to make your configuration selectable from the Run and Debug dropdown menus, check the checkboxes of the Display in favorites menu section of the Common tab, as seen below.

You may now run the new R configuration by selecting it via the triangle next to the button in the top menu.

Documentation: Building, Testing and Installing R Packages

Mon, 01 Jan 0001 00:00:00 +0000

Architect ships with a suite of tools to support R package development. If you’re new to developing R packages, Hilary Parker posted a very useful blog on how to write an R package from scratch.

This section assumes you have the structure of an R package more or less in place already. In the top toolbar, clicking the triangle of the External Tools button () opens a list of default tools for R packages (as well as some tools for generating various document types). To customize these, see the section External Tool Configuration.

Once the package is in place, select a tool to check, build or install it.

Package Projects

When creating a new project, you have the option to create an ‘R Package Project’ instead of ‘R Project’. This is largely the same as creating an ‘R Project’, but it allows you to use R code snippets that refer directly to your package.

There is a default snippet for adding roxygen documentation to an R package. For instructions on defining additional snippets or assigning them to hotkeys, see the Defining R Snippets section.

Generate Roxygen Documentation

Packaged functions require proper documentation. This can be done automatically in Architect. Under the Source menu, select Generate Element Comment (Roxygen), and structured documentation will be generated for a selected function. The parameters are pulled automatically from your function code.

One can further customize the default code that is generated by Quick Searching the Code Generation preferences menu. Additionally, you can assign the roxygen documentation to a hotkey.

Documentation: External Tool Configuration

Mon, 01 Jan 0001 00:00:00 +0000

To modify the existing External Tools, or add new ones, use the External Tool Configuration Window. This is particularly useful after you’ve installed a new version of R, to make sure tools such as R CMD INSTALL are run with the intended R version.

Switching a Configuration’s R Version

If you’ve installed a new version of R, you can edit your external tool configurations to work on the new R version. Navigate to the External Tools Configuration window, select the desired configuration, and change the selected configuration in the R Config tab.

Document Processing

Architect ships with built-in functionality for processing LaTeX, Sweave and knitr documents. These can be run via the External Tools dropdown menu, and further customized and modified in the External Tools Configurations window.

Documentation: Non-Embedded R Graphics View

Mon, 01 Jan 0001 00:00:00 +0000

To use a non-embedded R Graphics view, select from the main menu Run > Run Configurations.

Then select your R Console from the list on the left, navigate to the R Console tab and scroll to the bottom. Uncheck the box titled Set R Graphics view by StatET as default graphic device for new plots in R.

Documentation: Eclipse Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Eclipse Marketplace

Since Architect is embedded in the Eclipse environment, additional Eclipse plugins can be installed directly in Architect via the Eclipse Marketplace.

From the Eclipse Marketplace menu, one can search for available plugins. Here, as an example, we look for a Python editor, and find PyDev, a popular Python IDE for Eclipse.

Click Install, and you’ll be presented with a selection of features available for installation.

To select all, click Confirm. Next, you’ll be prompted to accept the licenses associated with the downloaded software. Click Finish to initiate the installation.

Note that software may take some time to install. To hide the installation progress, click the Run in Background button on the installation window. Note that Architect may be restarted after installation in order to use the new software.

Software from Other Sources

Software add-ons from other sources may also be added via Help > Install New Software.

Architect ships with a number of predefined sites with software additions available to download. Other sources may be configured via the Add button.

Documentation: Using Architect Behind a Proxy Server

Mon, 01 Jan 0001 00:00:00 +0000

You can configure Architect to run an R Console behind a proxy server. Type Ctrl + 3 to access the Quick Search, then search for Network Connections. Use this window to configure your proxy settings.

Next, we’ll configure an R Environment to use these defined proxy settings. Quick Search for the R Environments preferences menu, then click the checkbox titled Use Eclipse preferences for Network Connections for the desired R Environment.

Documentation: Searching R Help Files

Mon, 01 Jan 0001 00:00:00 +0000

Architect allows you to search the help files from all installed R packages. To open the R Help search view, type Ctrl + h, then click on the R Help tab.

This is useful for finding packages and functions related to a given topic or keyword. For example, we may be interested in finding help pages that relate to ‘geom’. A quick search shows that 11 of our installed packages contain help pages related to this query.

By clicking on a package, we can see all pages from that package related to our search query. Clicking on a page opens the corresponding R Help page.

Help pages for base R packages are indexed the first time you run Architect. For other packages, help pages are automatically index upon package installation. Indexing displays the following messages in the Console.

Additional Search Features

You can specify the scope of your search via the Search in field. Selecting Complete Document may be needed for many queries. In our previous example, searching for “geom” in only selected fields yielded only three packages (and only two ggplot2 pages!).

Although not often utilized by package developers, searches can be done for predefined keywords such as “htest” (hypothesis test). The terms are available by clicking the Select… button.

Finally, if you have installed other versions of R, you can pick the R installation to search via the Selected Configuration dropdown menu.

Documentation: Refactoring R Code

Mon, 01 Jan 0001 00:00:00 +0000

Architect contains easy-to-use tools to quickly make alterations to your code. Below, we display how to use these functionalities.

Extracting Local Variables

Suppose we have some expressions that are reused throughout our code. In the example below, we have repeated instances of the expression:

profit > 0 & revenue > 50000

To clean up our code, we may be interested in assigning this expression to a variable, and replacing all instances of said expression by our new variable. We can do this by highlighting the specified code and selecting ‘Source > Extract Local Variable…’. The extraction is shown below.

Renaming Variables in a Selected Region

In the Tips and Tricks Section, we showed how to rename all instances of a variable in an entire document. However, often one wishes to rename a variable in just a specific section of the code.

We can do this by selecting a given section of code and selecting Source > Rename in Selected Region…. This opens a window the displays all variables within the selected region. Navigate to a variable and type another name in the New Name column to rename that variable in the highlighted region.

Converting Code into a Function

In Architect, a chunk of code can be transformed into a function with the click of a button. Simply highlight the desired code and select Source > Extract R Function…. Architect will automatically detect the function’s necessary input parameters, at which point you can specify their order in the function call. The code is wrapped into a function, and a function call is given underneath the definition.

In the example below, we wrap some code for a residual plot into a ‘plotResiduals’ function that takes ‘x’ and ‘y’ as inputs.