--- title: "Broadcasting" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Broadcasting} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} --- ```{r} #| label: setup #| include: false knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r} library(rray) ``` ## Introduction The idea for rray sprung from frustration with the following example: ```{r} #| error: true x <- matrix(1:6, nrow = 3) x x + 1 y <- matrix(1) x + y ``` To someone who has worked with matrices in R before, this error message is probably nothing new. It's stating that because `x` has dimensions `(3, 2)` and is being added to an object with dimensions `(1, 1)`, which is a matrix that does not have *exactly the same dimensions*, the operation cannot be completed. My frustration lies with the fact that I had this "feeling" that I knew the answer to this operation. It shouldn't be an error, it should have the same answer as `x + 1`. Why does this work, when the other doesn't? In one sentence, the answer is that R *recycles*, but I want it to *broadcast*. This vignette's goal is to introduce the concept of broadcasting. Broadcasting is the idea of repeating dimensions of one object to match the dimensions of another, so that an operation can be applied between the two inputs. Later you will learn two rules which formalize this idea. ## What did I expect? For this first example, I expected this result: ```{r} x x + 1 rray_add(x, y) ``` rray implements broadcasting throughout the package, which is what allows this to work. It solves this motivating example, but is generally useful in variety of ways. ## Rules Broadcasting has two steps: 1) The *dimensionality* of the inputs are matched by *appending 1's* to the input with a lower dimensionality. 2) The *dimensions* of the inputs are matched by *recycling* the dimension of each axis as needed. By *recycling*, we mean that an axis of dimension 1 can be repeated to any other dimension. If you're familiar with the [tidyverse recycling rules](https://vctrs.r-lib.org/reference/theory-faq-recycling.html), then this should feel familiar. It's the same idea, just applied to all axes of the array. ## Example - `x + y` Let's revisit the original example, but use the broadcasting rules to understand how we got the result. ```{r} x y ``` When adding these two matrices together, it's useful to write out the dimensions explicitly, using the general notation of: ``` (rows, cols) | object ``` ``` (3, 2) | x (1, 1) | y -------|------- (3, 2) | result ``` To understand how we get from `x + y -> result`, compare axes vertically, and apply the broadcasting rules. - 1st dimension: - `x` has `3` rows - `y` has `1` row - Recycle the 1 to 3 - 2nd dimension: - `x` has `2` column - `y` has `1` column - Recycle the 1 to 2 ``` ( 3, 2) | x (1 -> 3, 1 -> 2) | y ``` You can explicitly see these rules in action with `rray_dimensions_common()` ```{r} dimensions <- rray_dimensions_common(x, y) dimensions ``` And you can explicitly broadcast with `rray_broadcast()`, which generates "conformable" arrays that base R can add together: ```{r} x_broadcast <- rray_broadcast(x, dimensions) x_broadcast y_broadcast <- rray_broadcast(y, dimensions) y_broadcast x_broadcast + y_broadcast ``` The downside of `rray_broadcast()` is that this materializes the fully broadcast version of `y` in memory. `rray_add()` instead iterates over both `x` and `y` without materializing the intermediate result, which is much more efficient! ## Example - Implicit dimensions If `y` was a 1-D array, not a 2-D matrix, what would have changed? ```{r} x y <- array(c(1L, 2L, 3L)) y rray_add(x, y) ``` This operation is still valid, and represents the first broadcasting rule in action - the *dimensionality* of the inputs are matched by *appending 1's* to the input with a lower dimensionality. Here, that's `y`: ``` (3, 2) | x (3) | y -------|------- (3, 2) | result ``` `x` has a dimensionality of 2, `y` has a dimensionality of 1, so we append 1s to the *right* hand side of `y` until dimensionalities match: ``` (3, 2) | x (3, 1) | y -------|------- (3, 2) | result ``` Now we apply recycling to `y` 2nd axis: ``` (3, 2) | x (3, 2) | y -------|------- (3, 2) | result ``` Explicitly: ```{r} y dimensions <- rray_dimensions_common(x, y) dimensions rray_broadcast(y, dimensions) ``` ## Example - Higher dimensions Broadcasting becomes more interesting when higher dimensional objects are used. Additionally, at this point only 1 object at a time has needed altering. This example will require both inputs to be changed. ```{r} a <- array(1:3, c(1, 3)) a b <- array(1:8, c(4, 1, 2)) b ``` Perhaps surprisingly, these inputs can be added together using broadcasting. ```{r} rray_add(a, b) ``` To understand this, write out dimensions and follow the rules: ``` (1, 3) | a (4, 1, 2) | b ``` Match dimensionalities by appending `1`s to `a`: ``` (1, 3, 1) | a (4, 1, 2) | b ``` and then recycle the axes with dimension 1 within each vertical pair: ``` (1 -> 4, 3, 1 -> 2) | a ( 4, 1 -> 3, 2) | b ``` Written compactly: ``` (1, 3) | a (4, 1, 2) | b --------- | ------ (4, 3, 2) | result ``` ## Addendum ### Base R Recycling The only exception to the strict behavior of base R is when an array is combined with a 1D vector. "Scalar" operations work as one might expect: ```{r} x x * 2 ``` But when a vector and an array are combined, the vector is recycled in its 1D flat form to fit the total size of the array. *This is very different from broadcasting.* ```{r} vec <- c(1, 2, 3) x x + vec # Equivalent to: rep(vec, 2) x + rep(vec, 2) ``` This example seems intuitive and harmless, but even *partial recycling* is allowed, which can be quite confusing and dangerous. ```{r} vec <- c(1, 2) x + vec ``` This is identical to the following, where `vec` is repeatedly recycled to construct something that can be added to `x`. ```{r} recycled <- matrix(NA, 3, 2) recycled[1, 1] <- vec[1] recycled[2, 1] <- vec[2] recycled[3, 1] <- vec[1] recycled[1, 2] <- vec[2] recycled[2, 2] <- vec[1] recycled[3, 2] <- vec[2] recycled x + recycled ``` rray never performs partial recycling when it is going through the steps of broadcasting, and will error if this example is attempted. ```{r} #| error: true rray_add(x, vec) ``` ### Differences from Python In the Python world, NumPy is used for broadcasting operations. One interesting thing to note is that when applying broadcasting rules for NumPy, implicit dimensions are *prepended to the left hand side* as `1`s. This is used consistently in the NumPy world, even down to how they are printed. However, R already uses the concept of *appended* implicit dimensions on the *right* hand side, and prints with this concept in mind. For a simple example of R doing this, try coercing a vector to a matrix: ```{r} # (3) -> (3, 1) as.matrix(1:3) ``` The dimensions went from `(3)` to `(3, 1)`. NumPy actually does the opposite, and would convert `(3)` to `(1, 3)`. This is fine, because they use it consistently there, but can be confusing when comparing broadcasting of rray to NumPy, and is just something to keep in mind.