Public API¶
Types¶
#
RCall.AnySxp — Type.
R "any" object
source
#
RCall.BcodeSxp — Type.
R byte code
source
#
RCall.BuiltinSxp — Type.
R built-in function
source
#
RCall.CharSxp — Type.
R character string
source
#
RCall.ClosSxp — Type.
R function closure
source
#
RCall.CplxSxp — Type.
R complex vector
R dot-dot-dot object
R environment
source
#
RCall.ExprSxp — Type.
R expression vector
source
#
RCall.ExtPtrSxp — Type.
R external pointer
R integer vector
source
#
RCall.LangSxp — Type.
R function call
R logical vector
source
#
RCall.ListSxp — Type.
R pairs (cons) list cell
R NULL value
source
#
RCall.PromSxp — Type.
R promise
source
#
RCall.RObject — Type.
An RObject is a Julia wrapper for an R object (known as an "S-expression" or "SEXP"). It is stored as a pointer which is protected from the R garbage collector, until the RObject itself is finalized by Julia. The parameter is the type of the S-expression.
When called with a Julia object as an argument, a corresponding R object is constructed.
julia> RObject(1)
RObject{IntSxp}
[1] 1
julia> RObject(1:3)
RObject{IntSxp}
[1] 1 2 3
julia> RObject(1.0:3.0)
RObject{RealSxp}
[1] 1 2 3
R byte vector
source
#
RCall.RealSxp — Type.
R real vector
R S4 object
source
#
RCall.SpecialSxp — Type.
R special function
R vector of character strings
R symbolic expression (SxpPtr): these are represented by a pointer to a symbolic expression record (Sxp).
source
#
RCall.SxpHead — Type.
R Sxp header: a pointer to this is used for unknown types.
R symbol
R list (i.e. Array{Any,1})
source
#
RCall.WeakRefSxp — Type.
R weak reference
Methods¶
#
Base.eltype — Function.
Element types of R vectors.
source
#
Base.getindex — Function.
Indexing into VectorSxp types uses Julia indexing into the vec result, except for StrSxp and the VectorListSxp types, which must apply sexp to the Ptr{Void} obtained by indexing into the vec result.
String indexing finds the first element with the matching name
extract the i-th element of LangSxp l
extract the value of symbol s in the environment e
source
#
Base.isascii — Function.
Determines the encoding of the CharSxp. This is determined by the 'gp' part of the sxpinfo (this is the middle 16 bits). * 0x00_0002_00 (bit 1): set of bytes (no known encoding) * 0x00_0004_00 (bit 2): Latin-1 * 0x00_0008_00 (bit 3): UTF-8 * 0x00_0040_00 (bit 6): ASCII
We only support ASCII and UTF-8.
source
#
Base.length — Function.
Sxp methods for length return the R length.
Rf_xlength handles Sxps that are not vector-like and R's "long vectors", which have a negative value for the length member.
source
#
Base.setindex! — Function.
assign value v to the i-th element of LangSxp l
assign value v to symbol s in the environment e
source
#
RCall.NAel — Function.
NA element for each type
source
#
RCall.anyNA — Function.
Check if there are any NA values in the vector.
source
#
RCall.bound — Function.
The R NAMED property, represented by 2 bits in the info field. This can take values 0,1 or 2, corresponding to whether it is bound to 0,1 or 2 or more symbols. See http://cran.r-project.org/doc/manuals/r-patched/R-exts.html#Named-objects-and-copying
source
#
RCall.callJuliaExtPtr — Function.
The function called by R .External for Julia callbacks.
It receives a ListSxpPtr containing - a pointer to the function itself (ExtPtrSxpPtr) - a pointer to the Julia function (ExtPtrSxpPtr) - any arguments (as SxpPtr)
source
#
RCall.dataptr — Function.
Pointer to start of the data array in a SEXPREC. Corresponds to DATAPTR C macro.
source
#
RCall.decrefExtPtr — Function.
Called by the R finalizer.
source
#
RCall.endEmbeddedR — Function.
endEmbeddedR()
Close embedded R session.
source
#
RCall.findNamespace — Function.
find namespace by name of the namespace, it is not error tolerant.
source
#
RCall.getAttrib — Function.
Return a particular attribute of an RObject
source
#
RCall.getClass — Function.
Returns the class of an R object.
source
#
RCall.getNames — Function.
Returns the names of an R vector.
source
#
RCall.getNamespace — Function.
get namespace by name of the namespace. It is safer to be used than findNamespace as it checks bound.
source
#
RCall.ijulia_displayplots — Function.
Called after cell evaluation. Closes graphics device and displays files in notebook.
source
#
RCall.ijulia_setdevice — Function.
Set options for R plotting with IJulia.
The first argument should be a MIME object: currently supported are * MIME("image/png") [default] * MIME("image/svg+xml")
The remaining arguments (keyword only) are passed to the appropriate R graphics device: see the relevant R help for details.
source
#
RCall.initEmbeddedR — Function.
initEmbeddedR()
This initializes an embedded R session. It should only be called when R is not already running (e.g. if Julia is running inside an R session)
source
#
RCall.isFactor — Function.
Check whether an R variable is a factor variable
source
#
RCall.isNA — Function.
Check if values correspond to R's sentinel NA values.
source
#
RCall.isOrdered — Function.
Check whether an R variable is an ordered factor variable
source
#
RCall.makeExternalPtr — Function.
Create an ExtPtrSxpPtr object
source
#
RCall.makeNativeSymbol — Function.
Register a function pointer as an R NativeSymbol.
This is completely undocumented, so may break: we technically are supposed to use R_registerRoutines, but this is much easier for just 1 function.
source
#
RCall.newEnvironment — Function.
create a new environment which extends env
source
#
RCall.preserve — Function.
Prevent garbage collection of an R object. Object can be released via release.
This is slower than protect, as it requires searching an internal list, but more flexible.
source
#
RCall.protect — Function.
Stack-based protection of garbage collection of R objects. Objects are released via unprotect. Returns the same pointer, allowing inline use.
This is faster than preserve, but more restrictive. Really only useful inside functions.
source
#
RCall.rcall — Function.
Evaluate a function in the global environment. The first argument corresponds to the function to be called. It can be either a FunctionSxp type, a SymSxp or a Symbol.
source
#
RCall.rcopy — Function.
rcopy(T,p) converts a pointer p to a Sxp object to a native Julia object of type T.
rcopy(p) performs a default conversion.
rcopy copies the contents of an R object into a corresponding canonical Julia type.
Evaluate and convert the result of a string as an R expression.
source
#
RCall.registerFinalizer — Function.
Register finalizer to be called by the R GC.
source
#
RCall.release — Function.
Release object that has been gc protected by preserve.
source
#
RCall.reval — Function.
Evaluate an R symbol or language object (i.e. a function call) in an R try/catch block, returning an RObject.
source
#
RCall.reval_p — Function.
Evaluate an R symbol or language object (i.e. a function call) in an R try/catch block, returning a Sxp pointer.
source
#
RCall.rlang — Function.
Create a function call from a function pointer and a list of arguments and return it as an RObject, which can then be evaulated
source
#
RCall.rlang_p — Function.
Create a function call from a list of arguments
source
#
RCall.rparse — Function.
Parse a string as an R expression, returning an RObject.
source
#
RCall.rparse_p — Function.
Parse a string as an R expression, returning a Sxp pointer.
source
#
RCall.rprint — Function.
Print the value of an Sxp using R's printing mechanism
Parse, evaluate and print the result of a string as an R expression.
source
#
RCall.rscript — Function.
Parses an inline R script, substituting invalid ":($(Expr(:incomplete, "incomplete: invalid string syntax")))
source
#
RCall.setAttrib! — Function.
Set a particular attribute of an RObject
source
#
RCall.setClass! — Function.
Set the class of an R object.
source
#
RCall.setNames! — Function.
Set the names of an R vector.
source
#
RCall.sexp — Function.
Convert a UnknownSxpPtr to an approptiate SxpPtr.
sexp(S,x) converts a Julia object x to a pointer to a Sxp object of type S.
sexp(x) performs a default conversion.
Create a SymSxp from a Symbol
Generic function for constructing Sxps from Julia objects.
Create a CharSxp from a String.
Create a StrSxp from an AbstractString
Wrap a Julia object an a R ExtPtrSxpPtr.
We store the pointer and the object in a const Dict to prevent it being removed by the Julia GC.
Wrap a callable Julia object f an a R ClosSxpPtr.
Constructs the following R code
function(...) .External(juliaCallback, fExPtr, ...)
source
#
RCall.sexp_arglist_dots — Function.
Create an argument list for an R function call, with a varargs "dots" at the end.
source
#
RCall.sexpnum — Function.
The SEXPTYPE number of a Sxp
Determined from the trailing 5 bits of the first 32-bit word. Is a 0-based index into the info field of a SxpHead.
source
#
RCall.unprotect — Function.
Release last n objects gc-protected by protect.
source
#
RCall.unsafe_array — Function.
The same as unsafe_vec, except returns an appropriately sized array.
source
#
RCall.unsafe_vec — Function.
Represent the contents of a VectorSxp type as a Vector.
This does not copy the contents. If the argument is not named (in R) or otherwise protected from R's garbage collection (e.g. by keeping the containing RObject in scope) the contents of this vector can be modified or could cause a memory error when accessed.
The contents are as stored in R. Missing values (NA's) are represented in R by sentinels. Missing data values in RealSxp and CplxSxp show up as NaN and NaN + NaNim, respectively. Missing data in IntSxp show up as -2147483648, the minimum 32-bit integer value. Internally a LglSxp is represented as Vector{Int32}. The convention is that 0 is false, -2147483648 is NA and all other values represent true.
Macros¶
#
RCall.@R_str — Macro.
Allows inline R scripts, e.g
foo = R"glm(Sepal.Length ~ Sepal.Width, data=$iris)"
Does not yet support assigning to Julia variables, so can only return results.
Copies variables from R to Julia using the same name.
source
#
RCall.@rimport — Macro.
Import a R Package as a Julia module. You can also use classic Python syntax to make an alias: @rimport *module-name* as *shorthand*
source
#
RCall.@rlibrary — Macro.
Load all exported functions/objects of a R package to the current module.
Copies variables from Julia to R using the same name.
source
#
RCall.@var_str — Macro.
Returns a variable named "str". Useful for passing keyword arguments containing dots.
Constants¶
#
RCall.globalEnv — Constant.
R global Environment.
globalEnv[:x] = 1
globalEnv[:x]
source
#
RCall.jtypExtPtrs — Constant.
Julia types (typically functions) which are wrapped in ExtPtrSxpPtr are stored here to prevent garbage collection by Julia.
source
#
RCall.typs — Constant.
vector of R Sxp types