JuliaConnectoR-package {JuliaConnectoR}

A Functionally Oriented Interface for Integrating Julia with R

Description

This package provides a functionally oriented interface between R and Julia. The goal is to call functions from Julia packages directly as R functions.

Details

This R-package provides a functionally oriented interface between R and Julia. The goal is to call functions from Julia packages directly as R functions. Julia functions imported via the JuliaConnectoR can accept and return R variables. It is also possible to pass R functions as arguments in place of Julia functions, which allows callbacks from Julia to R.

From a technical perspective, R data structures are serialized with an optimized custom streaming format, sent to a (local) Julia TCP server, and translated to Julia data structures by Julia. The results are returned back to R. Simple objects, which correspond to vectors in R, are directly translated. Complex Julia structures are by default transferred to R by reference via proxy objects. This enables an effective and intuitive handling of the Julia objects via R. It is also possible to fully translate Julia objects to R objects. These translated objects are annotated with information about the original Julia objects, such that they can be translated back to Julia. This makes it also possible to serialize them as R objects.

Setup

The package requires that Julia (Version \geq 1.0) is installed and that the Julia executable is in the system search PATH or that the JULIA_BINDIR environment variable is set to the bin directory of the Julia installation. If the JULIA_BINDIR variable is set, it takes precedence over looking in the executable path. By setting the JULIA_BINDIR variable before starting Julia, it is therefore possible to use different installations of Julia on the same machine without having to change the executable path.

Function overview

The function juliaImport makes functions and data types from Julia packages or modules available as R functions.

If only a single Julia function needs to be imported in R, juliaFun can do this. The simplest way to call a Julia function without any importing is to use juliaCall with the function name given as character string.

For evaluating expressions in Julia, juliaEval and juliaLet can be used. With juliaLet one can use R variables in a expression.

juliaExpr makes it possible use complex Julia syntax in R via R strings that contain Julia expressions.

With juliaGet, a full translation of a Julia proxy object into an R object is performed.

as.data.frame is overloaded (as.data.frame.JuliaProxy) for translating Julia objects that implement the Tables interface to R data frames.

Translation

Since Julia is more type-sensitive than R, and many Julia functions expect to be called using specific types, it is important to know the translations of the R data structures to Julia.

Translation from R to Julia

The type correspondences of the basic R data types in Julia are the following:

R		Julia
integer	\rightarrow	Int
double	\rightarrow	Float64
logical	\rightarrow	Bool
character	\rightarrow	String
complex	\rightarrow	Complex{Float64}
raw	\rightarrow	UInt8
symbol	\rightarrow	Symbol

R vectors of length 1 of the types in the table above will be translated to the types shown.

R vectors or arrays with more than one element will be translated to Julia Arrays of the corresponding types. The dimensions of an R array, as returned by dim(), will also be respected. For example, the R integer vector c(1L, 2L) will be of type Vector{Int}, or Array{Int,1}, in Julia. A double matrix such as matrix(c(1,2,3,4), nrow = 2) will be of type Array{Float64,2}.

Missing values (NA) in R are translated to missing values in Julia. R vectors and arrays with missing values are converted to Julia arrays of type Array{Union{Missing, T}}, where T stands for the translated type in the table above.

R lists are translated as Vector{T} in Julia, with T being the most specific supertype of the list elements after translation to Julia.

An R function that is handed to Julia as argument in a function call is translated to a Julia callback function that will call the given R function.

Strings with attribute "JLEXPR" will be evaluated as Julia expressions, and the value is used in their place (see juliaExpr).

R data frames are translated to objects that implement the Julia Tables interface. Such objects can be used by functions of many different Julia packages that deal with table-like data structures.

Translation from Julia to R

The type system of Julia is richer than that of R. Therefore, to be able to turn the Julia data structures that have been translated to R back to the original Julia data structures, the original Julia types are added to the translated Julia objects in R via the attribute "JLTYPE". When passed to Julia, R variables with this attribute will be coerced to the respective type. This allows the reconstruction of the objects with their original type.

It should not be necessary to worry too much about the translations from Julia to R because the resulting R objects should be intuitive to handle.

The following table shows how basic R-compatible types of Julia are translated to R:

Julia		R
Float64	\rightarrow	double
Float16, Float32, UInt32	\rightarrow	double with type attribute
Int64 that fits in 32 bits	\rightarrow	integer
Int64 not fitting in 32 bits	\rightarrow	double with type attribute
Int8, Int16, UInt16, Int32, Char	\rightarrow	integer with type attribute
UInt8	\rightarrow	raw
UInt64, Int128, UInt128, Ptr	\rightarrow	raw with type attribute
Complex{Float64}	\rightarrow	complex
Complex{IntX} with X \leq 64	\rightarrow	complex with type attribute
Complex{FloatX} with X \leq 32	\rightarrow	complex with type attribute

Julia Arrays of these types are translated to vectors or arrays of the corresponding types in R.

Julia functions are translated to R functions that call the Julia function. These functions can also be translated back to the corresponding Julia functions when used as argument of another function (see juliaFun).

Julia object of other types, in particular structs, Tuples, NamedTuples, and AbstractArrays of other types are transferred by reference in the form of proxy objects. Elements and properties of these proxy objects can be accessed and mutated via the operators `[[`, `[`, and `$` (see AccessMutate.JuliaProxy).

A full translation of the proxy objects into R objects, which also allows saving these objects in R, is possible via juliaGet.

Limitations

Possible inexactness when dealing with large 64 bit integers

Numbers of type Int64 that are too big to be expressed as 32-bit integer values in R will be translated to double numbers. This may lead to a inaccurate results for very large numbers, when they are translated back to Julia, since, e. g., (2^53 + 1) - 2^53 == 0 holds for double-precision floating point numbers.

Non-ASCII characters in variable names

Julia uses UTF-8 as default string encoding everywhere. In particular, Julia permits characters that are not expressible in encodings such as "Latin-1" in variable and function names. In R, the encoding of names in lists of environments depends on the platform. On locales without UTF-8 as native encoding, (i.e., mostly Windows), unexpected translations may happen when using UTF-8 characters in strings.

When using juliaImport for importing packages/modules, alternative names for variables using non-ASCII characters are added, which are compatible across different encodings. (For more information, see juliaImport.)

In other places, such as when evaluating code via juliaEval and juliaLet, the problem cannot be addressed. It should therefore be avoided to use non-ASCII characters if code should be portable across different platforms.