---
title: "Toolkit"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Toolkit}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r}
#| include: false
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r}
#| label: setup
library(rray)
```
## Introduction
One of the big goals for rray is to be a general purpose toolkit for working
with base R arrays. In this vignette, we'll look at a few parts of this toolkit,
and compare against similar concepts from base R.
## Axes
Many of the functions in rray are applied "along an axis". With base R, you
might be used to the `MARGIN` argument when specifying the axis to apply a
function over. In rray, you'll use `axes` (or `axis`, depending on the
function). In short, these two are *complements* of one another. Notice that the
values computed in the example below are the same, even though the axes to
compute over look different (ignore the difference in dimensionality for the
moment).
```{r}
x <- array(1:8, c(2, 2, 2))
rray_sum(x, axes = 1)
apply(x, MARGIN = c(2, 3), FUN = sum)
```
With `axes`, you list the axes that change in some way. In the above example,
`axes = 1` was specified which *guarantees* that the result will have the same
dimensions as `x` everywhere except along the first axis, which will have
dimension 1, no matter what. In other words, the dimensions change as:
`(2, 2, 2) -> (1, 2, 2)`.
## Combining
Reducers like `rray_sum()` aren't the only functions with this `axes` guarantee.
With `rray_combine()`, you specify the `.axis` that you want to combine along.
This has the same guarantee that only the `.axis` specified will be changing.
The only caveat here is that the inputs are first broadcast to common dimensions
(ignoring the `.axis` dimension) before the combine is carried out. A few
examples might be helpful:
```{r}
# (5, 1)
x <- matrix(1:5)
# (3)
y <- 6:8
rray_combine(x, y, .axis = 1)
```
This works by first finding the common dimensions between `x` and `y`, ignoring
the `.axis` dimension. In this case, the common dimensions are `(., 1)` where
the `.` represents whatever dimension is actually there for that input (5 for
`x` and 3 for `y`). The final result after combining the inputs together will
also have a `(., 1)` shape, where `.` will be replaced with `5 + 3 = 8`.
Here's another example, this time combining along the 2nd axis:
```{r}
x <- array(1:6, dim = c(3, 2))
x
y <- array(1:9, dim = c(3, 3))
y
z <- 10L
combined <- rray_combine(x, y, z, .axis = 2)
combined
```
The inverse of combining is splitting via `rray_split()`. Splitting requires an
`axis` to split along and a vector of `dimensions` that represent the dimension
of each output along `axis`. So, to recover `x`, `y`, and `z`, we could do:
```{r}
rray_split(combined, axis = 2, dimensions = c(2, 3, 1))
```
Note that splitting is a precise inverse unless broadcasting was involved during
the original combination process!
## Stacking
When combining arrays, you can only specify an `axis` that *already exists*
along at least one of the inputs. This means that you can't, say, combine 2-D
matrices along the 3rd axis:
```{r}
#| error: true
x <- matrix(1:4, nrow = 2)
x
y <- matrix(5:8, nrow = 2)
y
rray_combine(x, y, .axis = 3)
```
To do this, you'll instead want `rray_stack()`:
```{r}
stacked <- rray_stack(x, y, .axis = 3)
stacked
```
Conceptually, stacking arrays involves inserting a new axis via
`rray_insert_axes()` at the chosen `.axis`, and then combining the results
together via `rray_combine()`. The `.axis` to stack along can be any axis
between `1` to `dimensionality + 1` of the inputs.
```{r}
# Expand to 3D
x_3d <- rray_insert_axes(x, axes = 3)
y_3d <- rray_insert_axes(y, axes = 3)
# Now we can combine
rray_combine(x_3d, y_3d, .axis = 3)
```
Stacking is interesting because you aren't limited to stacking along
`dimensionality + 1`. You can instead stack along a new 2nd axis, which results
in the columns of each individual array getting grouped together (i.e. the 1st
columns of `x` and `y` are now side by side in the result):
```{r}
x
y
rray_stack(x, y, .axis = 2)
```
The inverse of `rray_stack()` is `rray_unstack()`. With `rray_stack()`, you
always get an output with a dimensionality 1 greater than the inputs. With
`rray_unstack()`, you get a list of outputs with a dimensionality 1 less than
the input.
```{r}
stacked
rray_unstack(stacked, axis = 3)
```
If you find yourself reaching for `rray_split(dimensions = 1)` followed by
`rray_remove_axes()`, you probably wanted `rray_unstack()` instead!
## Removing axes
One thing you will immediately notice when working with rray is that it often
tries *not* to remove axes automatically. This is most apparent with subsetting,
and in the reducers like `rray_sum()` and is in stark contrast to base R.
```{r}
x <- matrix(1:6, ncol = 2)
x[1,]
rray_slice_rows(x, 1)
apply(x, 2, sum)
rray_sum(x, axes = 1)
```
The rationale for this has to do with how broadcasting works. When axes are
kept, operations combining multiple rray functions feel natural:
```{r}
rray_divide(x, rray_sum(x, axes = 1))
```
This doesn't work as you might expect with base R, and can result in a tragic
error since partial recycling kicks in and you don't get an error.
```{r}
x / apply(x, 2, sum)
# Equivalent to
col_sums <- apply(x, 2, sum)
partially_recycled <- matrix(rep(col_sums, times = 3), ncol = 2)
partially_recycled
x / partially_recycled
```
Instead you must remember to use `sweep()` like:
```{r}
sweep(x, 2, apply(x, 2, sum), FUN = "/")
```
This works nicely in rray because of two reasons, both are necessary:
- When reducing, axes aren't removed
- When dividing, broadcasting kicks in
If you do want to remove axes, you can explicitly call `rray_remove_axes()`
afterwards. As a rule of thumb, it is much easier to remove axes explicitly than
it is to recover them.
```{r}
x |>
rray_sum(axes = 1) |>
rray_remove_axes(axes = 1)
```
If you're a Python user coming from NumPy, you might be used to reducers
dropping the axis you reduce over. I think this is a mistake, and there have
been a number of discussions on the NumPy forums about this choice. Here is why:
```{r}
#| error: true
# This is the result you'd get in a NumPy sum. The 1st axis is dropped.
x_sum_dropped <- rray_remove_axes(rray_sum(x, axes = 1), axes = 1)
x_sum_dropped
# Now broadcasting doesn't work!
rray_divide(x, x_sum_dropped)
# So you have to add back the axis manually
# (NumPy has slightly cleaner ways to do this, but it's still an extra step)
x_sum_reshaped <- rray_insert_axes(x_sum_dropped, axes = 1)
rray_divide(x, x_sum_reshaped)
```
For the curious, Julia's implementation of reducers works similarly to rray.