Introduction
Relation to F# RProvider
Getting set up
There is a page gathering
Software Prerequisites listing the platforms on which R.NET is known to run.
As of version 1.6, R.NET binaries are platform independent. You
might need to set up a small add-on workaround on some Linux distributions (CentOS a known one), but you can just move and use the R.NET binaries across platforms.
Assuming you have the right
Software Prerequisites, you can obtain R.NET binaries from two sources
- The codeplex web site, by downloading a zip file
- The nuget.org web site
Visual Studio
NuGet is the preferred way to manage dependencies on R.NET. Consider giving it a try: this is the way of the future for .NET projects...
If you are using the binaries from the zip file distribution, unzip the file and copy the content to a location of your choice. Add project references to RDotNet.dll and RDotNet.Native.dll the "usual" way.
If you are using the NuGet packages:
You first have to install, if you have not already, the NuGet package manager via Tools - Extension and Updates:
![0001.png]( "0001.png")
You can add the R.NET package as a dependency to one or more projects in your solution. For one project:
![001.png]( "001.png")
![002.png]( "002.png")
The NuGet system then adds a couple of references.
![003.png]( "003.png")
You can manage several projects in one go at the solution level:
![004.png]( "004.png")
You can find more general information about NuGet at
NuGet documentationXamarin Studio
This section is a placeholder.
Getting started with coding
Version 1.6 of R.NET includes significant changes notably to alleviate two stumbling blocks often dealt with by users: paths to the R shared library, and preventing multiple engine initializations.
The following "Hello World" sample illustrates how the new API is simpler in 90% of use cases on Windows:
staticvoid Main(string[] args)
{
REngine.SetEnvironmentVariables(); // <-- May be omitted; the next line would call it.
REngine engine = REngine.GetInstance();
// A somewhat contrived but customary Hello World:
CharacterVector charVec = engine.CreateCharacterVector(new[] { "Hello, R world!, .NET speaking" });
engine.SetSymbol("greetings", charVec);
engine.Evaluate("str(greetings)"); // print out in the consolestring[] a = engine.Evaluate("'Hi there .NET, from the R engine'").AsCharacter().ToArray();
Console.WriteLine("R answered: '{0}'", a[0]);
Console.WriteLine("Press any key to exit the program");
Console.ReadKey();
engine.Dispose();
}You retrieve a single REngine object instance, after setting the necessary environmental variables. Even the call to
SetEnvironmentVariables can be omitted, though we'd advise you keep it explicit.
SetEnvironmentVariables looks at the Registry settings set up by the R installer on Windows. If need be, you can override the behaviours setting the environment variables and engine initialization with your own steps, detailed in the Appendix.
On Linux/MacOS, the path to libR.so (for Linux)
must be in the environment variable LD_LIBRARY_PATH
before the process start, otherwise the R.NET engine will not properly initialize. If this is not set up, R.NET will throw an exception with a detailed message. Read the Appendix at the end of this page if R.NET complains about your LD_LIBRARY_PATH.
Sample code
LOOK AT THE MATERIAL IN THE UNIT TESTS
Dealing with missing values
Illustrate the speed of data transfer
You usually interact with the REngine object with the methods Evaluate, GetSymbol, and SetSymbol. To create R vector and matrices, the REngine object has methods such as CreateNumericVector, CreateCharacterMatrix, etc. Finally, you can invoke R functions in a variety of ways, using the method Evaluate of the REngine object, and also more directly.
Sample 1
It is available from the sample code 1 at
https://github.com/jmp75/rdotnet-onboarding, as of 2014-04.
staticvoid Main(string[] args)
{
REngine.SetEnvironmentVariables();
REngine engine = REngine.GetInstance();
// REngine requires explicit initialization.// You can set some parameters.
engine.Initialize();
// .NET Framework array to R vector.
NumericVector group1 = engine.CreateNumericVector(newdouble[] { 30.02, 29.99, 30.11, 29.97, 30.01, 29.99 });
engine.SetSymbol("group1", group1);
// Direct parsing from R script.
NumericVector group2 = engine.Evaluate("group2 <- c(29.89, 29.93, 29.72, 29.98, 30.02, 29.98)").AsNumeric();
// Test difference of mean and get the P-value.
GenericVector testResult = engine.Evaluate("t.test(group1, group2)").AsList();
double p = testResult["p.value"].AsNumeric().First();
Console.WriteLine("Group1: [{0}]", string.Join(", ", group1));
Console.WriteLine("Group2: [{0}]", string.Join(", ", group2));
Console.WriteLine("P-value = {0:0.000}", p);
// you should always dispose of the REngine properly.// After disposing of the engine, you cannot reinitialize nor reuse it
engine.Dispose();
}The following sample code illustrate the most used capabilities. It is extracted from the sample code 2 at
https://github.com/jmp75/rdotnet-onboarding, as of 2014-04.
This illustrate basic operations with numeric vectors
var e = engine.Evaluate("x <- 3");
// You can now access x defined in the R environment
NumericVector x = engine.GetSymbol("x").AsNumeric();
engine.Evaluate("y <- 1:10");
NumericVector y = engine.GetSymbol("y").AsNumeric();While you may evaluate function calls by generating a string and call the Evaluate method, this can be unwieldy for cases where you pass large amounts of data. The following demonstrates how you may call a function, a bit like how you would invoke a function reflectively in .NET.
// Invoking functions; Previously you may have needed custom function definitionsvar myFunc = engine.Evaluate("function(x, y) { expand.grid(x=x, y=y) }").AsFunction();
var v1 = engine.CreateIntegerVector(new[] { 1, 2, 3 });
var v2 = engine.CreateCharacterVector(new[] { "a", "b", "c" });
var df = myFunc.Invoke(new SymbolicExpression[] { v1, v2 }).AsDataFrame();R.NET 1.6 includes many improvements to support function calls.
// As of R.NET 1.6, more function call syntaxes are supported.var expandGrid = engine.Evaluate("expand.grid").AsFunction();
var d = new Dictionary<string, SymbolicExpression>();
d["x"] = v1;
d["y"] = v2;
df = expandGrid.Invoke(d).AsDataFrame();Continuing with the results of our use of expand.grid, the following code illustrate that while R.NET tries to mimic the behavior of R with respect to data frames. Data frames are a central part of R data structures, so it is worth expanding with a few examples
engine.SetSymbol("cases", df);
// As of R.NET 1.6, factor to character expressions work consistently with Rvar letterCases = engine.Evaluate("cases[,'y']").AsCharacter().ToArray();
// "a","a","a","b","b","b", etc. Same as as.character(cases[,'y']) in R// Note that this used to return "1", "1", "1", "2", "2", etc. with R.NET 1.5.5There are other ways to extract columns from the data frame, without passing strings of R expressions:
// Equivalent:
letterCases = df[1].AsCharacter().ToArray();
letterCases = df["y"].AsCharacter().ToArray();
The behavior for what is returned by 2-dimensional indexing usually mirrors what is observed directly in R. One exception is when row names are missing; the R behavior is debatable, so R.NET prefers to be strict.
// Accessing items by two dimensional indexingstring s = (string)df[1, 1]; // "a"
s = (string)df[3, 1]; // "a"
s = (string)df[3, "y"]; // "b"// s = (string)df["4", "y"]; // fails because there are no row names
df[3, "y"] = "a";
s = (string)df[3, "y"]; // "a"
df[3, "y"] = "d";
s = (string)df[3, "y"]; // null, because we have an <NA> string in R
To reuse whole scripts, the simplest method is to use the 'source' function in R
engine.Evaluate("source('c:/src/path/to/myscript.r')");Data Types
All expressions in R are represented as SymbolicExpression objects in R.NET. For data access, the following special classes are defined. Note that there is no direct equivalent in .NET for 'NA' values in R. Special values are used for some types but pay attention to the behaviour, so as not to risk incorrect calculations.
Table. Classes in R.NET bridges between R and .NET Framework.
| R | R.NET | .NET Framework | Note |
|---|
| character vector | RDotNet.CharacterVector | System.String[] | |
| integer vector | RDotNet.IntegerVector | System.Int32[] | The minimum value in R is -2^31+1 while that of .NET Framework is -2^31. Missing values are int.MinValue |
| real vector | RDotNet.NumericVector | System.Double[] | Missing values are represented as double.NaN |
| complex vector | RDotNet.ComplexVector | System.Numerics.Complex[] | System.Numerics assembly is required for .NET Framework 4. |
| raw vector | RDotNet.RawVector | System.Byte[] | |
| logical vector | RDotNet.LogicalVector | System.Boolean[] | |
| character matrix | RDotNet.CharacterMatrix | System.String[, ] | |
| integer matrix | RDotNet.IntegerMatrix | System.Int32[, ] | The minimum value in R is -2^31+1 while that of .NET Framework is -2^31. |
| real matrix | RDotNet.NumericMatrix | System.Double[, ] | |
| complex matrix | RDotNet.ComplexMatrix | System.Numerics.Complex[, ] | Reference to System.Numerics assembly is required. |
| raw matrix | RDotNet.RawMatrix | System.Byte[, ] | |
| logical matrix | RDotNet.LogicalMatrix | System.Boolean[, ] | |
| list | RDotNet.GenericVector | | From version 1.1. |
| data frame | RDotNet.GenericVector | | From version 1.1. RDotNet.DataFrame class is also available (below). |
| data frame | RDotNet.DataFrame | | From version 1.3. And from version 1.5.3, DataFrameRowAttribute and DataFrameColumnAttribute are available for data mapping. |
| function | RDotNet.Function | | From version 1.4. Including closure, built-in function, and special function. |
| factor | RDotNet.Factor | System.Int32[] | From version 1.5.2. |
| S4 | RDotNet.S4Object | | Not Available Yet. See S4 branch in the source control. |
Acknowledgements
- Daniel Collins found the workaround for the native library "libdl" loader that was not working on at least some CentOS Linux distributions.
- evolvedmicrobe contributed to several features to run on MacOS and Linux, and initiated the changes to make R.NET platform independent.
- Kosei initiated R.NET
- gchapman
Appendices
Updating environment variables on Linux (MacOS?)
The path to libR.so (for Linux)
must be in the environment variable LD_LIBRARY_PATH
before the process start, otherwise the R.NET engine will not properly initialize. If this is not set up, R.NET will throw an exception with a detailed message.
What you will need to do there depends on the Linux (MacOS?) machine you are.
Let's say you needed to compile your own R from source, to get a shared R library:
LOCAL_DIR=/home/username/local
JAVAHOME=/apps/java/jdk1.7.0_25
cd ~src
cd R/
tar zxpvf R-3.0.2.tar.gz
cd R-3.0.2
./configure --prefix=$LOCAL_DIR --enable-R-shlib CFLAGS="-g"
make
make install
Then prior to running a project with R.NET, you may need to update your LD_LIBRARY_PATH, and quite possibly PATH (though the latter can be done at runtime too).
LOCAL_DIR=/home/username/local
if [ "${LD_LIBRARY_PATH}" != "" ]
then
export LD_LIBRARY_PATH=$LOCAL_DIR/lib:$LOCAL_DIR/lib64/R/lib:/usr/local/lib64:${LD_LIBRARY_PATH}
else
export LD_LIBRARY_PATH=$LOCAL_DIR/lib:$LOCAL_DIR/lib64/R/lib:/usr/local/lib64
fi
# You may as well update the PATH environment variable, though R.NET does update it if need be.
export PATH=$LOCAL_DIR/bin:$LOCAL_DIR/lib64/R/lib:${PATH}Advanced options for the R engine initialization
custom characterconsole
Multiple app domains