OCamlR: use the R environment for statistical computing and graphics from OCaml.

This package offers an API to build bindings to the R environment for statistical computing and graphics. It provides functions to initialize an R interpreter, encode OCaml values to R values, retrieve R-side values, call R functions and decode R values into OCaml values. OCaml's type system is used when possible to enforce invariants on R's operations to allow a safer use. Some (very partial) bindings to R's standard librairies are available.

Here are the main entry points of the library:

The following sections illustrate a few uses of the package.

Bindings to standard R libraries

ocaml-r provides partial bindings for R libraries base (OCamlR_base), stats (OCamlR_stats), grDevices (OCamlR_grDevices), graphics (OCamlR_graphics), utils (OCamlR_utils) and methods (OCamlR_methods). The general design of these bindings is to offer one (OCaml) module for each R data type, where the type t is abstract. See for instance the signature for floating point arrays (aka numeric in R), OCamlR_base.Numeric.

Thanks to abstraction, interacting with R is as simple as calling regular functions. Here is how to use the library to perform statistical tests:

# require "ocaml-r.stats";;
# open OCamlR_base;;
# open OCamlR_stats;;
# let sample = rnorm ~mean:1. ~sd:1. 10;;
val sample : Numeric.t = <abstr>
# let test = T'test.one_sample sample;;
val test : T'test.t = <abstr>
# T'test.p'value test;;
- : float = 0.000223914842630059665
# T'test.print test;;

	One Sample t-test

data:  c(2.07617445897347, 0.940542561435446, 2.05650431270334, 1.21388435907814, 0.143109357690333, 0.600620037187408, 1.65525155532367, 0.928790144562367, 1.66977862776445, 2.47640151281091)
t = 5.9184, df = 9, p-value = 0.0002239
alternative hypothesis: true mean is not equal to 0
95 percent confidence interval:
 0.8501232 1.9020882
sample estimates:
mean of x
 1.376106

- : unit = ()

This example illustrates the simplest use of the package, that is calling R functions through already available bindings. A few more details are given in the next section.

Naming convention is to try to be as close as possible to the original names, when possible. Names that correspond to OCaml keywords are surrounded by underscores like in _method_ or _class_. Dots are replaced by ticks, like in p'value.

When a datatype is a specialization of another one, like data.frame is a special case of list, the signature of the OCaml module of the former includes the signature of the latter.

Here are links to the most frequent R datatypes bindings:

Using the Rmath library

ocaml-r also provides bindings to the Rmath library.

# #require "ocaml-r.math";;
# OCamlR_math.dchisq ~df:3. ~log:true 1.;;
- : float = -1.41893853320467267

Defining new bindings

open OCamlR
open OCamlR_base

let sample_fun = symbol "sample"

let sample ?replace ?prob ~size x =
  call sample_fun [
    arg Numeric.to_sexp x ;
    arg Enc.int size ;
    opt_arg Enc.bool "replace" replace ;
    opt_arg Numeric.to_sexp "prob" prob ;
  ]
  |> Numeric.unsafe_of_sexp