Getting started

The RCall package is loaded via

julia> using RCall

This will initialize the R process in the background.

Several Ways to use RCall

RCall provides multiple ways to allow R interacting with Julia.

R REPL mode

The R REPL mode allows real time switching between the Julia prompt and R prompt. Press $ to activate the R REPL mode and the R prompt will be shown. (Press backspace to leave R REPL mode in case you did not know.)

julia> foo = 1
1

R> x <- $foo

R> x
[1] 1

The R REPL mode supports variable substitution of Julia objects via the $ symbol. It is also possible to pass Julia expressions in the REPL mode.

R> x = $(rand(10))

R> sum(x)
[1] 5.097083

@rput and @rget macros

These macros transfer variables between R and Julia environments. The copied variable will have the same name as the original.

julia> z = 1
1

julia> @rput z
1

R> z
[1] 1

R> r = 2

julia> @rget r
2.0

julia> r
2.0

It is also possible to put and get multiple variables in one line.

julia> foo = 2
2

julia> bar = 4
4

julia> @rput foo bar
4

R> foo + bar
[1] 6

@R_str string macro

Another way to use RCall is the R"" string macro, it is especially useful in script files.

julia> R"rnorm(10)"RObject{RealSxp}
 [1] -0.47472233  0.17609750 -0.08352281 -0.71856442 -0.29819380  0.78404621
 [7]  2.07005839  0.31664610  0.53360257 -1.06783403

This evaluates the expression inside the string in R, and returns the result as an RObject, which is a Julia wrapper type around an R object.

The R"" string macro supports variable substitution of Julia objects via the $ symbol, whenever it is not valid R syntax (i.e. when not directly following a symbol or completed expression such as aa$bb):

julia> x = randn(10)10-element Vector{Float64}:
  1.2385354165016937
  0.9526739058004399
  0.16802338489770202
  1.027047244337757
 -0.8154017739534671
 -0.25941152169549553
 -1.8125812719115049
  1.5793154757807906
  0.023584553444657402
  0.22646579563688712
julia> R"t.test($x)"RObject{VecSxp} One Sample t-test data: `#JL`$x t = 0.71488, df = 9, p-value = 0.4928 alternative hypothesis: true mean is not equal to 0 95 percent confidence interval: -0.5039209 0.9695712 sample estimates: mean of x 0.2328251

It is also possible to pass Julia expressions which are evaluated before being passed to R: these should be included in parentheses

julia> R"optim(0, $(x -> x-cos(x)), method='BFGS')"RObject{VecSxp}
$par
[1] -1.56343

$value
[1] -1.570796

$counts
function gradient
      14       13

$convergence
[1] 0

$message
NULL

A large chunk of code could be quoted between triple string quotations

julia> y = 11
julia> R""" f <- function(x, y) x + y ret <- f(1, $y) """RObject{RealSxp} [1] 2

RCall API

The reval function evaluates any given input string as R code in the R environment. The returned result is an RObject object.

julia> jmtcars = reval("mtcars");
julia> names(jmtcars)11-element Vector{Symbol}: :mpg :cyl :disp :hp :drat :wt :qsec :vs :am :gear :carb
julia> jmtcars[:mpg]Ptr{RealSxp} @0x00000000074bcf90
julia> typeof(jmtcars)RObject{VecSxp}

The rcall function is used to construct function calls.

julia> rcall(:dim, jmtcars)RObject{IntSxp}
[1] 32 11

The arguments will be implicitly converted to RObject upon evaluation.

julia> rcall(:sum, Float64[1.0, 4.0, 6.0])RObject{RealSxp}
[1] 11

The rcopy function converts RObjects to Julia objects. It uses a variety of heuristics to pick the most appropriate Julia type:

julia> rcopy(R"c(1)")1.0
julia> rcopy(R"c(1, 2)")2-element Vector{Float64}: 1.0 2.0
julia> rcopy(R"list(1, 'zz')")2-element Vector{Any}: 1.0 "zz"
julia> rcopy(R"list(a = 1, b= 'zz')")OrderedCollections.OrderedDict{Symbol, Any} with 2 entries: :a => 1.0 :b => "zz"

It is possible to force a specific conversion by passing the output type as the first argument:

julia> rcopy(Array{Int}, R"c(1, 2)")2-element Vector{Int64}:
 1
 2

Converter could also be used specifically to yield the desired type.

julia> convert(Array{Float64}, R"c(1, 2)")2-element Vector{Float64}:
 1.0
 2.0

The robject function converts any julia object to an RObject.

julia> robject(1)RObject{IntSxp}
[1] 1
julia> robject(Dict(:a => 1, :b = 2))ERROR: syntax: invalid keyword argument name ":b" around REPL[2]:1

@rlibrary and @rimport macros

This macro loads all exported functions/objects of an R package to the current module.

julia> @rlibrary boot
julia> city = rcopy(R"boot::city") # get some data10×2 DataFrame Row │ u x │ Float64 Float64 ─────┼────────────────── 1 │ 138.0 143.0 2 │ 93.0 104.0 3 │ 61.0 69.0 4 │ 179.0 260.0 5 │ 48.0 75.0 6 │ 37.0 63.0 7 │ 29.0 50.0 8 │ 23.0 48.0 9 │ 30.0 111.0 10 │ 2.0 50.0
julia> ratio(d, w) = sum(d[!, :x] .* w)/sum(d[!, :u] .* w)ratio (generic function with 1 method)
julia> b = boot(city, ratio, R = 100, stype = "w");
julia> rcall(:summary, b[:t])RObject{StrSxp} V1 Min. :1.222 1st Qu.:1.415 Median :1.551 Mean :1.593 3rd Qu.:1.704 Max. :2.634

Of course, it is highly inefficient, because the data are copying multiple times between R and Julia. The R"" string macro is more recommended for efficiency.

Some R functions may have keyword arguments which contain dots. RCall provides a string macro to escape those keywords, e.g,

julia> @rimport base as rbase
julia> rbase.sum([1, 2, 3], var"rm.na" = true)RObject{IntSxp} [1] 7