Get or set dimensions of an array

rray_subset() extracts dimensions from an array by index. It powers [ for rray objects. Notably, it never drops dimensions, and ignores trailing commas.

rray_subset(x, ...) <- value

# S3 method for vctrs_rray
[(x, ...) <- value

rray_subset_assign(x, ..., value)

rray_subset(x, ...)

# S3 method for vctrs_rray
[(x, ..., drop = FALSE)

Arguments

x	A vector, matrix, array, or rray.
...	A specification of indices to extract. Integer-ish indices extract specific elements of dimensions. Logical indices must be length 1, or the length of the dimension you are subsetting over. Character indices are only allowed if x has names for the corresponding dimension. NULL is treated as 0.
value	The value to assign to the location specified by .... Before assignment, value is cast to the type and dimension of x[...].
drop	Ignored, but preserved for better error messages with code that might have used arrays before.

Value

x subset by the specification defined in the ....

The assignment variants return x modified by having the elements of value inserted into the positions defined by ....

Details

rray_subset() and its assignment variant can also be used with base R matrices and arrays to get rray subsetting behavior with them.

Differences from base R

• rray_subset() never drops dimensions.

• rray_subset() ignores trailing commas. This has the nice property of making x[1] == x[1,].

• rray_subset()<- casts value to x, rather than casting x to value.

See also

pad()

Other rray subsetters: rray_extract<-, rray_slice<-, rray_yank<-

Examples

x <- rray(1:8, c(2, 2, 2))

# `rray_subset()` powers `[` so these are identical
rray_subset(x, 1)
#> <rray<int>[,2,2][1]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    3
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    5    7
#> 
x[1]
#> <rray<int>[,2,2][1]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    3
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    5    7
#> 

# Trailing dots are ignored, so these are identical
x[1]
#> <rray<int>[,2,2][1]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    3
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    5    7
#> 
x[1,]
#> <rray<int>[,2,2][1]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    3
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    5    7
#> 

# Missing arguments are treated as selecting the
# entire dimension, consistent with base R.
# This selects all of the rows, and the first column.
x[,1]
#> <rray<int>[,1,2][2]>
#> , , 1
#> 
#>      [,1]
#> [1,]    1
#> [2,]    2
#> 
#> , , 2
#> 
#>      [,1]
#> [1,]    5
#> [2,]    6
#> 

# Notice that you can't actually do the above with base
# R. It requires you to fully specify the dimensions of `x`.
# This would throw an error.
x_arr <- as_array(x)
try(x_arr[,1])
#> Error in x_arr[, 1] : incorrect number of dimensions

# To get the same behavior, you have to do:
x_arr[, 1, , drop = FALSE]
#> , , 1
#> 
#>      [,1]
#> [1,]    1
#> [2,]    2
#> 
#> , , 2
#> 
#>      [,1]
#> [1,]    5
#> [2,]    6
#> 

# Note that you can use base R arrays with `rray_subset()`
rray_subset(x_arr, , 1)
#> , , 1
#> 
#>      [,1]
#> [1,]    1
#> [2,]    2
#> 
#> , , 2
#> 
#>      [,1]
#> [1,]    5
#> [2,]    6
#> 

# For higher dimensional objects, `pad()` can be
# useful for automatically adding commas. The
# following are equivalent:
x[pad(), 1]
#> <rray<int>[,2,1][2]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    3
#> [2,]    2    4
#> 
x[, , 1]
#> <rray<int>[,2,1][2]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    3
#> [2,]    2    4
#> 

# You can assign to index locations with
# `x[...] <- value`
# This assigns 99 to the entire first row
x[1] <- 99
x
#> <rray<int>[,2,2][2]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]   99   99
#> [2,]    2    4
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]   99   99
#> [2,]    6    8
#> 

# First row in the first
# element of the 3rd dimension
x[1, , 1] <- 100
x
#> <rray<int>[,2,2][2]>
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]  100  100
#> [2,]    2    4
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]   99   99
#> [2,]    6    8
#> 

# Note that `value` is broadcast to the shape
# of `x[...]`. So this...
x[,1] <- matrix(5)

# ...becomes the same as
x[,1] <- array(5, c(2, 1, 2))

# You can also use `rray_subset<-()` directly to
# use these semantics with base R
rray_subset(x_arr, , 1) <- matrix(5)
x_arr
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    5    3
#> [2,]    5    4
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    5    7
#> [2,]    5    8
#>