rray_rotate() rotates an array along the plane defined by c(from, to). It can be thought of as sequentially rotating the array 90 degrees a set number of times.

rray_rotate(x, from = 1, to = 2, times = 1)

## Arguments

x A matrix, array, or rray. Single integer values. The direction of the rotation goes from from and towards to. When using a 2D matrix, this can be thought of as rotating counter clockwise starting at from and going towards to. To go clockwise, reverse from and to. A single integer. The number of times to perform the rotation. One of: 1, 2, 3. Or, equivalently: -3, -2, -1.

## Value

x rotated along the axis described by from and to.

## Details

A rotation can be a hard thing to wrap your head around. I encourage looking at the examples and starting with 2D to try and understand what is happening before moving up to higher dimensions.

Note that a rotation is not the same thing as a transpose.

Generally, you can predict the output of rotating using from and to by switching the dimensions at the from and to axes position. This gives you the shape of the output. So, a (5, 2, 4) array rotated using from = 1 and to = 3 would have a resulting shape of (4, 2, 5). Note that using from = 3 and to = 1 would give the same shape. The "direction" of how these are rotated is controlled by the ordering of from and to.

## Examples

# ---------------------------------------------------------------------------
# 2D example

x <- rray(1:6, c(3, 2))
x <- rray_set_row_names(x, c("r1", "r2", "r3"))
x <- rray_set_col_names(x, c("c1", "c2"))

# "counter clockwise" rotation turning the
# rows into columns
rray_rotate(x)#> <rray<int>[,3][2]>
#>    r1 r2 r3
#> c2  4  5  6
#> c1  1  2  3
# "clockwise" by reversing the direction
rray_rotate(x, from = 2, to = 1)#> <rray<int>[,3][2]>
#>    r3 r2 r1
#> c1  3  2  1
#> c2  6  5  4
# Rotate twice (180 degrees)
# Direction doesn't matter here, the following
# give the same result
rray_rotate(x, times = 2)#> <rray<int>[,2][3]>
#>    c2 c1
#> r3  6  3
#> r2  5  2
#> r1  4  1rray_rotate(x, from = 2, to = 1, times = 2)#> <rray<int>[,2][3]>
#>    c2 c1
#> r3  6  3
#> r2  5  2
#> r1  4  1
# ---------------------------------------------------------------------------
# 3D example

x_3d <- rray_expand(x, 3)

# - Rotations on the (1, 3) axis plane
# - Dimensions go from (3, 2, 1) -> (1, 2, 3) in both cases
# - And the direction of how that happens is controlled
#   by from and to
rray_rotate(x_3d, from = 1, to = 3)#> <rray<int>[,2,3][1]>
#> , , r1
#>
#>      c1 c2
#> [1,]  1  4
#>
#> , , r2
#>
#>      c1 c2
#> [1,]  2  5
#>
#> , , r3
#>
#>      c1 c2
#> [1,]  3  6
#>
rray_rotate(x_3d, from = 3, to = 1)#> <rray<int>[,2,3][1]>
#> , , r3
#>
#>      c1 c2
#> [1,]  3  6
#>
#> , , r2
#>
#>      c1 c2
#> [1,]  2  5
#>
#> , , r1
#>
#>      c1 c2
#> [1,]  1  4
#>