Words like “dimension” and “size” get used loosely when talking about arrays. rray gives each of them one precise meaning, and uses that meaning everywhere, from function names to argument names to error messages. This vignette defines each term.
We’ll use this array for most examples:
An axis is a single integer that picks a direction along the array. Axis 1 runs down the rows, axis 2 runs across the columns, and so on.
Many rray functions work “along an axis”. Summing along axis 1 adds up the rows, so only 1 row is left:
rray_sum(x, axes = 1)
#> , , 1
#>
#> [,1] [,2] [,3]
#> [1,] 3 7 11
#>
#> , , 2
#>
#> [,1] [,2] [,3]
#> [1,] 15 19 23Summing along axis 3 conceptually adds the two matrices embedded in
x together, so only one is left:
Notice that only the axis you pick changes. Every other axis keeps its original shape.
You can also provide an axis by its title
rather than its position. See ?faq-axes for more.
A dimension is the number of elements along one axis. For
x:
Axis 1 has a dimension of 2.
Axis 2 has a dimension of 3.
Axis 3 has a dimension of 2.
To get the dimension of one axis, index into the dimensions:
The dimensions are an integer vector holding the dimension of every axis.
This is like dim(), except that it also works on plain
vectors, which act like 1-D arrays:
In the other vignettes, dimensions are often written out in
parentheses, like (2, 3, 2) for x.
You can change the dimensions of an array with
rray_set_dimensions(), as long as the total number of
elements stays the same:
The dimensionality of an array is the length of the dimensions vector. This also corresponds with the number of axes it has.
A vector has a dimensionality of 1, and a matrix has a dimensionality of 2:
The terms so far have been carefully chosen so that programming with these concepts lends itself to object names that feel natural, like this:
The size is the total number of elements in the array. It is the product of the dimensions:
For an array, this is the same as length(x):
Be careful not to mix up size and dimension.
Axis 2 of x has a dimension of 3, but x has a
size of 12.
The names are a list with one element per axis. Each element
is either a character vector naming the elements along that axis, or
NULL. This is the same as dimnames().
y <- rray_set_names(
x,
list(
c("a", "b"),
c("c", "d", "e"),
c("f", "g")
)
)
y
#> , , f
#>
#> c d e
#> a 1 3 5
#> b 2 4 6
#>
#> , , g
#>
#> c d e
#> a 7 9 11
#> b 8 10 12
rray_names(y)
#> [[1]]
#> [1] "a" "b"
#>
#> [[2]]
#> [1] "c" "d" "e"
#>
#> [[3]]
#> [1] "f" "g"To get the names along one axis, use
rray_axis_names():
The first two axes are common enough to get their own helpers:
An array without any names has NULL names:
The titles are the names on the list of names. There is one title per axis, and they show up when the array is printed.
z <- rray_set_titles(y, c("row", "col", "page"))
z
#> , , page = f
#>
#> col
#> row c d e
#> a 1 3 5
#> b 2 4 6
#>
#> , , page = g
#>
#> col
#> row c d e
#> a 7 9 11
#> b 8 10 12
rray_titles(z)
#> [1] "row" "col" "page"Titles are useful because you can refer to an axis by its title rather than its position:
Broadcasting is how rray works with inputs that have
different dimensions. Axes with a dimension of
1 are repeated to match the other inputs. Here, b has 1
column, so it is repeated to match the 2 columns of a:
a <- matrix(1:6, nrow = 3)
a
#> [,1] [,2]
#> [1,] 1 4
#> [2,] 2 5
#> [3,] 3 6
b <- matrix(c(10L, 20L, 30L))
b
#> [,1]
#> [1,] 10
#> [2,] 20
#> [3,] 30
rray_add(a, b)
#> [,1] [,2]
#> [1,] 11 14
#> [2,] 22 25
#> [3,] 33 36Broadcasting is important enough to get its own vignette. See
vignette("broadcasting") to learn more.