Passing Data Between F# and R
Passing Parameters
Parameter Passing Conventions
R supports various kinds of parameters, which we try to map onto equivalent F# parameter types:
All R formal parameters have names, and you can always pass their values either by name or positionally. If you pass by name, you can skip arguments in your actual argument list. We simply map these onto F# arguments, which you can also pass by name or positionally.
In R, essentially all arguments are optional (even if no default value is specified in the function argument list). It's up to the receiving function to determine whether to error if the value is missing. So we make all arguments optional.
R functions support ... (varargs/paramarray). We map this onto a .NET ParamArray, which allows an arbitrary number of arguments to be passed. However, there are a couple of kinks with this:
R allows named arguments to appear after the ... argument, whereas .NET requires the ParamArray argument to be at the end. Some R functions use this convention because their primary arguments are passed in the ... argument and the named arguments will sometimes be used to modify the behavior of the function. From the RProvider you will to supply values for the positional arguments before you can pass to the ... argument. If you don't want to supply a value to one of these arguments, you can explicitly pass System.Reflection.Missing.
Parameters passed to the R ... argument can also be passed using a name. Those names are accessible to the calling function. Example are list and dataframe construction (R.list, and R.data_frame). To pass arguments this way, you can use the overload of each function that takes an IDictionary
, either directly, or using the namedParams function. For example: R.data_frame(namedParams [ "A", [|1;2;3|]; "B", [|4;5;6|] ])
Parameter Types
Since all arguments to functions are of type obj, it is not necessarily obvious what you can pass. Ultimately, you will need to know what the underlying function is expecting, but here is a table to help you. When reading this, remember that for most types, R supports only vector types. There are no scalar string, int, bool etc. types.
R Type | F#/.NET Type |
---|---|
character | string or string[] |
complex | System.Numerics.Complex or Complex[] |
integer | int or int[] |
logical | bool or bool[] |
numeric | double or double[] |
list | Call R.list, passing the values as separate arguments |
dataframe | Call R.data_frame, passing column vectors in a dictionary |
NB: For any input, you can also pass a SymbolicExpression instance you received as the result of calling another R function. Doing so it a very efficient way of passing data from one function to the next, since there is no marshalling between .NET and R types in that case.
Creating and passing an R function
R has some high-level functions (e.g. sapply) that require a function parameter. Although F# has first-class support of functional programming and provides better functionality and syntax for apply-like operations, which often makes it sub-optimal to call apply-like high-level functions in R, the need for parallel computing in R, which is not yet directly supported by F# parallelism to R functions, requires users to pass a function as parameter. Here is an example way to create and pass an R function:
1: 2: |
|
The same usage also applies to parallel apply functions in parallel package.
Accessing results
Functions exposed by the RProvider return an instance of RDotNet.SymbolicExpression
. This keeps all return data inside R data structures, so does not impose any data marshalling overhead. If you want to pass the value in as an argument to another R function, you can simply do so.
In order to access the result in .NET code, you have three routes:
Convert the data into a specified .NET type via GetValue()
RProvider adds a generic GetValue<'T>
extension method to SymbolicExpression
. This supports conversions from certain R values to specific .NET types. Here are the currently supported conversions:
R Type | Requested F#/.NET Type |
---|---|
character (when vector is length 1) | string |
character | string[] |
complex (when vector is length 1) | Complex |
complex | Complex[] |
integer (when vector is length 1) | int |
integer | int[] |
logical (when vector is length 1) | bool |
logical | bool[] |
numeric (when vector is length 1) | double |
numeric | double[] |
Custom conversions can be supported through plugins.
Convert the data into the default .NET type the .Value property
We also expose an extension property called Value that performs a default conversion of a SymbolicExpresion to a .NET type. These are the current conversions:
R Type | F#/.NET Type |
---|---|
character | string[] |
complex | Complex[] |
integer | int[] |
logical | bool[] |
numeric | double[] |
Again, custom conversions can be supported through plugins.
Explicitly access the data in the SymbolicExpression
If there are no supported conversions, you can access the data through the RDotNet object model. RDotNet exposes properties, members and extension members (available only if you open the RDotNet namespace) that allow you to access the underlying data directly. So, for example:
1: 2: 3: |
|
To make this easier, we have defined some active patterns, under the RProvider.Helpers namespace, which is auto-opened when you open the RProvider namespace. These combine the type tests and conversion. An equivalent example:
1: 2: 3: |
|
What if I commonly need an argument or result conversion that RProvider does not support?
If you believe the argument conversion is universally appropriate and should be available to everybody, please fork the repo and submit a pull request.
RProvider also supports custom conversions to/from your own data types using plugins.
Full name: Passing-data.fun1
static member ! : ?paramArray: obj [] -> SymbolicExpression + 1 overload
static member != : ?paramArray: obj [] -> SymbolicExpression + 1 overload
static member !_hexmode : ?a: obj -> SymbolicExpression + 1 overload
static member !_octmode : ?a: obj -> SymbolicExpression + 1 overload
static member $ : ?paramArray: obj [] -> SymbolicExpression + 1 overload
static member $<- : ?paramArray: obj [] -> SymbolicExpression + 1 overload
static member $<-_data_frame : ?x: obj * ?name: obj * ?value: obj -> SymbolicExpression + 1 overload
static member $_DLLInfo : ?x: obj * ?name: obj -> SymbolicExpression + 1 overload
static member $_data_frame : ?x: obj * ?name: obj -> SymbolicExpression + 1 overload
static member $_package__version : ?x: obj * ?name: obj -> SymbolicExpression + 1 overload
...
Full name: RProvider.R
Base R functions.
R.eval(?expr: obj, ?envir: obj, ?enclos: obj) : SymbolicExpression
Evaluate an (Unevaluated) Expression
R.parse(?file: obj, ?n: obj, ?text: obj, ?prompt: obj, ?keep_source: obj, ?srcfile: obj, ?encoding: obj) : SymbolicExpression
Parse Expressions
Full name: Passing-data.nums
R.sapply(?X: obj, ?FUN: obj, ?___: obj, ?simplify: obj, ?USE_NAMES: obj, ?paramArray: obj []) : SymbolicExpression
No documentation available
Combine Values into a Vector or List
Full name: Passing-data.res
R.sum(?paramArray: obj []) : SymbolicExpression
Sum of Vector Elements
| Null = 0
| Symbol = 1
| Pairlist = 2
| Closure = 3
| Environment = 4
| Promise = 5
| LanguageObject = 6
| SpecialFunction = 7
| BuiltinFunction = 8
| InternalCharacterString = 9
...
Full name: RDotNet.Internals.SymbolicExpressionType
Full name: Microsoft.FSharp.Core.ExtraTopLevelOperators.failwithf
active recognizer IntegerVector: SymbolicExpression -> IntegerVector option
Full name: RDotNet.ActivePatterns.( |IntegerVector|_| )
--------------------
type IntegerVector =
inherit Vector<int>
new : engine:REngine * length:int -> IntegerVector + 2 overloads
member CopyTo : destination:int[] * length:int * ?sourceIndex:int * ?destinationIndex:int -> unit
member Item : int -> int with get, set
Full name: RDotNet.IntegerVector
--------------------
IntegerVector(engine: REngine, length: int) : unit
IntegerVector(engine: REngine, vector: Collections.Generic.IEnumerable<int>) : unit
IntegerVector(engine: REngine, vector: int []) : unit