r.md

Introduction

This document describes how to use the R programming language from within the application. The application uses an interpreter known as Renjin to integrate with R.

Hello world

Complete the following steps to see R in action:

1. Start the application.
2. Click File → New to create a new file.
3. Click File → Save As.
4. Set Name to: addition.Rmd
5. Click Save.

Setting the file name extension tells the application what processor to use when transforming the contents for display in the preview pane. Continue by typing in the following text, including the backticks:

`r#1 + 1`

The preview pane shows the result of 1 plus 1:

2.0

Bootstrap script

Being able to run R code while editing an R Markdown document is convenient. Having the ability to call functions is where the power of R can be leveraged.

Complete the following steps to call an R function from your own library:

1. Click File → New to create a new file.
2. Click File → Save As.
3. Browse to your home directory.
4. Set Name to: library.R.
5. Click Save.
6. Set the contents to:

   sum <- function( a, b ) {
     a + b
   }

7. Click the Save icon.
8. Click R → Script.
9. Set the R Startup Script contents to:

   source( 'library.R' );

10. Click OK.
11. Create a new file.
12. Set the contents to:

    `r#sum( 5, 5 )`

13. Save the file as sum.R.

The preview panel shows the result of calling the sum function:

10.0

This shows how the bootstrap script can load library.R, which defines a sum function that is called by name in the Markdown document.

Working directory

R files may be sourced from any directory, not just the user's home directory. Accomplish this as follows:

1. Click R → Directory.
2. Set Directory to a different directory.
3. Click OK.
4. Create the directory if it does not exist.
5. Move library.R into the directory.
6. Append a new function to library.R as follows:

   mul <- function( a, b ) {
     a * b
   }

7. Click R → Script.
8. Set the R Startup Script contents to:

   setwd( '$application.r.working.directory$' );
   source( 'library.R' );

9. Change sum.Rmd to:

   `r#mul( 5, 5 )`

10. Close the file sum.Rmd.
11. Confirm saving the file when prompted.
12. Re-open sum.Rmd.

The preview panel shows:

25.0

Calling setwd using '$application.r.working.directory$' changes the working directory where the R engine searches for source files.

YAML definitions

To see how variable definitions work in R, try the following:

1. Create a new file.
2. Change the contents to (use spaces not tabs):

   project:
     title: Project Title
     author: Author Name

3. Save the file as definitions.yaml.
4. Click File → Open.
5. Set Source Files to Definition Files.
6. Select definitions.yaml.
7. Click Open.
8. Open sum.Rmd if it is not already open.
9. Type: je
10. Press Ctrl+Space

The editor inserts the following text (matches je against Project):

`r#x( v$project$title )`

The preview panel shows:

r#x( 'Project Title' )

This is because the application inserts definition reference names based on the type of file being edited. By default, the R engine does not have a function named x defined.

Continue as follows:

1. Click R → Script.
2. Append the following:

   x <- function( s ) {
     tryCatch( {
       r = eval( parse( text = s ) )
   
       ifelse( is.atomic( r ), r, s );
     },
     warning = function( w ) { s },
     error = function( e ) { s } )
   }

3. Click OK.
4. Close and re-open sum.Rmd.

The preview panel shows:

25.0

Project Title

The x function attempts to evaluate the expression defined by the YAML variable. This means that the YAML definitions can also include expressions that R is capable of evaluating.

While the x function can be defined within the R Startup Script, it is better practice to put it into its own library so that it can be reused outside of the application.