rray (said: “r-ray”) is an array manipulation library for R. It has three main goals:
View the vignettes for each goal on the website to learn more about how to use rray.
In short, rray tries to make array manipulation in R more intuitive by combining the idea of broadcasting with knowing when to not drop dimensions. This results in operations such as:
x <- rray(1:6, dim = c(3, 2)) # Compute proportions along the 1st dimension x / rray_sum(x, axes = 1) #> <rray<dbl>[,2]> #> [,1] [,2] #> [1,] 0.1666667 0.2666667 #> [2,] 0.3333333 0.3333333 #> [3,] 0.5000000 0.4000000 # Equivalent base R syntax sweep(x, 2, apply(x, 2, sum), "/") #> <rray<dbl>[,2]> #> [,1] [,2] #> [1,] 0.1666667 0.2666667 #> [2,] 0.3333333 0.3333333 #> [3,] 0.5000000 0.4000000
These concepts are baked into every part of rray, and show up in other functions such as
rray_bind(). Using broadcasting,
rray_bind() can bind arrays together in ways that base R cannot with the native
a <- array(c(1, 2), dim = c(2, 1)) b <- array(c(3, 4), dim = c(1, 2)) a #> [,1] #> [1,] 1 #> [2,] 2 b #> [,1] [,2] #> [1,] 3 4 # Error cbind(a, b) #> Error in cbind(a, b): number of rows of matrices must match (see arg 2) # `a` is first broadcast to have dimensions: (2, 2) rray_bind(a, b, .axis = 1) #> [,1] [,2] #> [1,] 1 1 #> [2,] 2 2 #> [3,] 3 4 # Error rbind(a, b) #> Error in rbind(a, b): number of columns of matrices must match (see arg 2) # `b` is first broadcast to have dimensions: (2, 2) rray_bind(a, b, .axis = 2) #> [,1] [,2] [,3] #> [1,] 1 3 4 #> [2,] 2 3 4
You can install from CRAN with:
You can install the development version from Github with:
rray would not be possible without the underlying C++ library,
xtensor. Additionally, rray uses a large amount of the infrastructure in
vctrs to be as consistent and type stable as possible.
The Matrix package implements a small subset of column-wise broadcasting operations. rray fully supports broadcasting in all operations.
The original motivation for this package, and even for xtensor, is the excellent Python library, NumPy. As far as I know, it has the original implementation of broadcasting, and is a core library that a huge number of others are built on top of.
In the past, the workhorse for flexibly binding arrays together has been the abind package. This package has been a great source of inspiration and has served as a nice benchmark for rray.
Currently, rray does not handle missing values in arithmetic operations and the reducing functions. This is coming, as the underlying library xtensor natively supports missing values, however a few upstream bugs are currently preventing rray from using those features.
rray will perform best on R 3.6.0 and above. It is able to take advantage of a few of the ALTREP features there, which result in less copies being made per function call.