Accept titles for axis in the remaining one axis functions

R/locate.R

@@ -34,7 +34,8 @@
 #'
 #' @param x An array.
 #'
-#' @param axis A single integer giving the axis to locate along.
+#' @param axis The axis to locate along, given
+#'   [by position or by title][faq-axes].
 #'
 #' @param na_rm If `TRUE`, missing values are skipped.
 #'
@@ -51,6 +52,10 @@
 #'
 #' # Position of the minimum going across the columns
 #' rray_locate_min(x, axis = 2L)
+#'
+#' # Position of the minimum going across the columns, by title
+#' y <- rray_set_titles(x, c("row", "col"))
+#' rray_locate_min(y, axis = "col")
 NULL
 
 #' @rdname rray-locate

R/names.R

@@ -37,7 +37,8 @@ rray_names <- function(x) {
 #'
 #' @param x An array.
 #'
-#' @param axis A single integer. The axis to get names for.
+#' @param axis The axis to get names for, given
+#'   [by position or by title][faq-axes].
 #'
 #' @returns
 #' A character vector of names, or `NULL` if that axis has no names.
@@ -49,6 +50,10 @@ rray_names <- function(x) {
 #' rray_axis_names(x, 1)
 #' rray_axis_names(x, 2)
 #'
+#' # By title
+#' y <- rray_set_titles(x, c("row", "col"))
+#' rray_axis_names(y, "col")
+#'
 #' rray_row_names(x)
 #' rray_column_names(x)
 rray_axis_names <- function(x, axis) {
@@ -105,7 +110,8 @@ rray_set_names <- function(x, names) {
 #'
 #' @param x An array.
 #'
-#' @param axis A single integer. The axis to set names for.
+#' @param axis The axis to set names for, given
+#'   [by position or by title][faq-axes].
 #'
 #' @param names A character vector of names for `axis`, the same length as
 #'   the dimension of `axis`. Can also be `NULL` to remove names from `axis`.
@@ -120,6 +126,10 @@ rray_set_names <- function(x, names) {
 #' rray_set_axis_names(x, 1, c("r1", "r2"))
 #' rray_set_axis_names(x, 2, c("c1", "c2", "c3"))
 #'
+#' # By title
+#' y <- rray_set_titles(x, c("row", "col"))
+#' rray_set_axis_names(y, "col", c("c1", "c2", "c3"))
+#'
 #' rray_set_row_names(x, c("r1", "r2"))
 #' rray_set_column_names(x, c("c1", "c2", "c3"))
 rray_set_axis_names <- function(x, axis, names) {

R/rep.R

@@ -31,7 +31,8 @@
 #'
 #' @param axes An integer vector of axes to repeat along.
 #'
-#' @param axis A single integer representing the axis to repeat along.
+#' @param axis The axis to repeat along, given
+#'   [by position or by title][faq-axes].
 #'
 #' @returns
 #' An array with the same dimensions as `x`, except along the repeated axes.
@@ -58,6 +59,10 @@
 #' # A different number of repeats per row
 #' rray_rep_each(x, times = c(1, 2, 3), axis = 1)
 #'
+#' # A different number of repeats per row, by title
+#' z <- rray_set_titles(x, c("row", "col"))
+#' rray_rep_each(z, times = c(1, 2, 3), axis = "row")
+#'
 #' # Zeroes drop slices entirely
 #' rray_rep_each(x, times = c(1, 0, 2), axis = 1)
 #'

R/roll.R

@@ -226,7 +226,8 @@
 #'
 #' @param axes An integer vector of axes to roll along.
 #'
-#' @param axis A single integer representing the axis to roll along.
+#' @param axis The axis to roll along, given
+#'   [by position or by title][faq-axes].
 #'
 #' @returns
 #' An array with the same type and dimensions as `x`.
@@ -261,6 +262,10 @@
 #' # Roll each row by its own `n`, given as a one column matrix
 #' rray_roll_each(y, n = matrix(c(1, 0, -1), ncol = 1), axis = 2)
 #'
+#' # Roll each row by its own `n`, by title
+#' z <- rray_set_titles(y, c("row", "col"))
+#' rray_roll_each(z, n = matrix(c(1, 0, -1), ncol = 1), axis = "col")
+#'
 #' # Roll each column by its own `n`, given as a one row matrix
 #' rray_roll_each(y, n = matrix(c(0, 1, 2, 3), nrow = 1), axis = 1)
 #'

R/slice.R

@@ -58,7 +58,8 @@
 #' @param i A subscript for the selected axis. It takes any of the forms
 #'   allowed in `...`.
 #'
-#' @param axis A single integer. The axis to slice along.
+#' @param axis The axis to slice along, given
+#'   [by position or by title][faq-axes].
 #'
 #' @param value An array to assign to the selected positions. It is cast to
 #'   the type of `x`, then broadcast to the dimensions of the selection.
@@ -100,6 +101,10 @@
 #' rray_slice_rows(y, c("b", "a"))
 #' rray_slice_columns(x, -2)
 #'
+#' # Slice a single axis, by title
+#' z <- rray_set_titles(y, c("row", "col"))
+#' rray_slice_axis(z, c("e", "c"), axis = "col")
+#'
 #' # Assign one value to every first row
 #' rray_slice_assign(x, 1, TRUE, TRUE, value = 0L)
 #' rray_slice_assign_rows(x, 1, 0L)

R/split.R

@@ -9,7 +9,8 @@
 #'
 #' @param x An array.
 #'
-#' @param axis A single integer representing the axis to split on.
+#' @param axis The axis to split along, given
+#'   [by position or by title][faq-axes].
 #'
 #' @param dimensions One of:
 #'
@@ -35,6 +36,10 @@
 #' # One array per column
 #' rray_split(x, axis = 2, dimensions = 1)
 #'
+#' # One array per column, by title
+#' y <- rray_set_titles(x, c("row", "col"))
+#' rray_split(y, axis = "col", dimensions = 1)
+#'
 #' # Arrays of dimension zero are allowed in the explicit form
 #' rray_split(x, axis = 2, dimensions = c(0, 2))
 #'

R/titles.R

@@ -14,7 +14,11 @@
 #'
 #' @param x An array.
 #'
-#' @param axis A single integer. The axis to get or set the title for.
+#' @param axis The axis to get or set the title for.
+#'
+#'   - For `rray_set_axis_title()`, given [by position or by title][faq-axes].
+#'
+#'   - For `rray_axis_title()`, given [by position][faq-axes].
 #'
 #' @param titles A character vector with one title per axis, or `NULL` to
 #'   remove all titles.
@@ -38,6 +42,7 @@
 #' rray_titles(x)
 #' rray_axis_title(x, 2)
 #' rray_set_axis_title(x, 1, NULL)
+#' rray_set_axis_title(x, "Row", "R")
 NULL
 
 #' @rdname rray-titles

R/unstack.R

@@ -18,7 +18,8 @@
 #'
 #' @param x An array.
 #'
-#' @param axis A single integer representing the axis to unstack along.
+#' @param axis The axis to unstack along, given
+#'   [by position or by title][faq-axes].
 #'
 #' @returns
 #' A list of arrays with the same dimensions as `x`, except that `axis` has
@@ -36,6 +37,10 @@
 #' # One array per column
 #' rray_unstack(x, axis = 2)
 #'
+#' # One array per column, by title
+#' z <- rray_set_titles(x, c("row", "col"))
+#' rray_unstack(z, axis = "col")
+#'
 #' # Names along the axis become list names
 #' y <- array(1:4, c(2, 2), dimnames = list(c("a", "b"), c("x", "y")))
 #' rray_unstack(y, axis = 2)