rearrr (version 0.3.4)

roll_values: Shift values and wrap to range

Description

lifecycle::badge("experimental")

Adds a specified value to each element in the vector and wraps the values around the min-max range with:

\((x - .min)\) % \((.max - .min + between) + .min\)

Useful when adding to the degrees of a circle, where the values should remain in the 0-360 range. A value larger than 360 will start over from 0, e.g. \(365 -> 5\), while a value smaller than 0 would become e.g. \(-5 -> 355\). Here, 0 and 360 are considered the same angle. If we were instead adding days to the weekdays 1-7, where 1 and 7 are separate days, we can set `between = 1` to have one day in-between them.

wrap_to_range() is a wrapper with `add = 0`.

The *_vec() versions take and return a vector.

Should not be confused with roll_elements(), which changes the positions of the elements.

Usage

roll_values(
  data,
  cols = NULL,
  add = 0,
  .min = NULL,
  .max = NULL,
  between = 0,
  na.rm = FALSE,
  suffix = "_rolled",
  keep_original = TRUE,
  range_col_name = ".range",
  overwrite = FALSE
)
wrap_to_range(
  data,
  cols = NULL,
  .min = NULL,
  .max = NULL,
  between = 0,
  na.rm = FALSE,
  suffix = "_wrapped",
  keep_original = TRUE,
  range_col_name = ".range",
  overwrite = FALSE
)
roll_values_vec(
  data,
  add = 0,
  .min = NULL,
  .max = NULL,
  between = 0,
  na.rm = FALSE
)
wrap_to_range_vec(data, .min = NULL, .max = NULL, between = 0, na.rm = FALSE)

Value

`data` with new columns with values in the specified min-max range(s) and columns with the applied ranges.

The *_vec() versions return a vector.

Arguments

data

vector or data.frame to roll/wrap values of. When a data.frame is grouped, the rolling/wrapping is applied group-wise.

cols

Names of columns to roll/wrap in `data`. Must be specified when `data` is a data.frame.

add

Amount to add to each element. (numeric scalar)

When 0, the wrapping is applied without any rolling.

.min

Minimum value allowed. If NULL, the minimum value in the vector/column is used.

.max

Maximum value allowed. If NULL, the maximum value in the vector/column is used.

between

The wrapping distance between `.max` and `.min`.

When 0, they are considered the same. I.e. \(`.max == .min`\).

When 1, `x` can be greater than `.max` by up to 1, why `.min` and `.max` are two separate values with 1 in-between them. I.e. \(`.max + 1 == .min`\).

na.rm

Whether to remove missing values (NAs) when finding the `.min` and `.max` values.

suffix

Suffix to add to the names of the generated columns.

Use an empty string (i.e. "") to overwrite the original columns.

keep_original

Whether to keep the original columns. (Logical)

Some columns may have been overwritten, in which case only the newest versions are returned.

range_col_name

Name of new column with the min-max range. If NULL, no column is added.

N.B. Ignored when `data` is a vector.

overwrite

Whether to allow overwriting of existing columns. (Logical)

Author

Ludvig Renbo Olsen,

See Also

Other roll functions: roll_elements()

Other mutate functions: apply_transformation_matrix(), cluster_groups(), dim_values(), expand_distances(), expand_distances_each(), flip_values(), rotate_2d(), rotate_3d(), shear_2d(), shear_3d(), swirl_2d(), swirl_3d()

Examples

# Attach packages
library(rearrr)

# Add 90 to all degrees
# Note that 0 and 360 is considered the same angle
# why there is no distance between the two
roll_values(c(0:360), add = 90)

# Get as vector
roll_values_vec(c(0:360), add = 90)

# Change limits to 0-180
# so e.g. 270 becomes 90
roll_values(c(0:360), .min = 0, .max = 180)

# Change values first, then wrap to range
x <- c(1:7)
x <- x^2
wrap_to_range(x, .min = 1, .max = 7)

# With 1 in-between .min and .max
wrap_to_range(x, .min = 1, .max = 7, between = 1)

# Get as vector
wrap_to_range_vec(x, .min = 1, .max = 7, between = 1)

#
# Roll data.frame
#

# Set seed
set.seed(1)

# Create a data frame
df <- data.frame(
  "w" = 1:7,
  "d" = c(0, 45, 90, 135, 180, 270, 360)
)

# Roll weekdays by 1 day
roll_values(
  df,
  cols = "w",
  add = 1,
  .min = 1,
  .max = 7,
  between = 1
)

# Roll degrees by -90 degrees
roll_values(
  df,
  cols = "d",
  add = -90,
  .min = 0,
  .max = 360,
  between = 0
)

# Roll both weekdays and degrees by 1
# We don't specify .min and .max, so they
# are based on the values in the columns
# Note: This is not that meaningful but shows
# the option
roll_values(
  df,
  cols = c("w", "d"),
  add = 1
)

# Wrap weekdays to 2-5 range
wrap_to_range(
  df,
  cols = "w",
  .min = 2,
  .max = 5,
  between = 1
)